Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 5 additions & 6 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Opus audit session that fixed all broken tests, real bugs, and documentation.

**Measured, not claimed (2026-11-17, gate G0).** `impl/rust-cli/tests/conformance_battery.rs`
starts the built shell on 128 everyday command lines and compares the result with bash:
**67 match**. The cases that fail are listed in
**69 match**. The cases that fail are listed in
`impl/rust-cli/tests/conformance/known_failing.txt`. That list is a ratchet: it may only
shrink, and a case may not be added to it to make a build pass.

Expand All @@ -40,7 +40,9 @@ Works through the built shell (passing battery cases, or checked by hand interac
- `test`, `[ ... ]`, and `[[ ... ]]` on its own; `if/elif/else`, `while`, a single `for`, `case`
- Functions, `local`, `return`; `$VAR`, `${VAR}`, `${VAR:-default}`, `${#VAR}`, `${VAR:o:n}`
- `$((expr))`, and `$(cmd)` of another program, as the whole value of an assignment
- `echo`, `printf`, `eval`, `set --`, `alias`, `trap ... EXIT`, `exit N`
- `echo`, `printf`, `eval`, `set --`, `set -e`, `alias`, `trap ... EXIT`, `exit N`
- A command that fails fails only itself, with a status: the next command of a script,
a function or a loop runs, and `||` runs its right side
- Reversible variable assignment (undo/redo)
- Transaction grouping (`begin`/`commit`/`rollback`)
- `explain`, `checkpoint`/`restore`, `diff`, `replay`, `history --proofs`
Expand All @@ -53,14 +55,11 @@ In the source and unit-tested, but NOT working through the built shell (battery
- `$((expr))` and `$(cmd)` inside an argument (`echo $((1+2))` prints the text); backquotes
- A quoted `*`, `?`, `[`, `{` or `~` reaches other programs with a backslash added
- `${VAR#pat}`, `${VAR%pat}`, `${VAR^^}` (give an empty string); `$$`
- Nested `for` loops (silently wrong), `break`, `continue`, `! cmd`, `set -e`
- Nested `for` loops (silently wrong), `break`, `continue`, `! cmd`
- Subshells, brace groups in pipelines, arrays, `(( ))`, the C-style `for`
- `export` and `VAR=value cmd` do not reach the program being run
- Here documents passed with `-c`; redirections on built-in commands outside the session root
(`ls nosuch 2>/dev/null`)
- A built-in that fails with an error (`mkdir` on a directory that exists, say) ends a `-c`
script, and the rest of an `&&` or `||` list with it. A refused built-in and `false` do
not: they fail with status 1 and the script goes on
- Ctrl-Z does not suspend a running program

Not exercised by the battery: process substitution, command correction, the pager.
Expand Down
2 changes: 1 addition & 1 deletion README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ Valence Shell is a formally verified shell with proven reversibility guarantees.

[NOTE]
====
*Measured, not claimed.* `impl/rust-cli/tests/conformance_battery.rs` starts the built shell on 128 everyday command lines and compares the result with bash. On 2026-11-17, 67 match. The cases that fail are listed in `impl/rust-cli/tests/conformance/known_failing.txt`, which may only shrink. Below, `[x]` means it works through the built shell, `[~]` means in part, and the limit is stated.
*Measured, not claimed.* `impl/rust-cli/tests/conformance_battery.rs` starts the built shell on 128 everyday command lines and compares the result with bash. On 2026-11-18, 69 match. The cases that fail are listed in `impl/rust-cli/tests/conformance/known_failing.txt`, which may only shrink. Below, `[x]` means it works through the built shell, `[~]` means in part, and the limit is stated.
====

* [~] Built-in file commands with undo: `mkdir`, `rmdir`, `touch`, `rm`, `cp`, `mv`, `ln -s`, `chmod`, `chown`, in their plain forms only (one operand each; two for `cp`, `mv` and `ln -s`; a mode or an owner and then one file for `chmod` and `chown`; no options, the `-s` of `ln -s` apart). An option or an extra operand is refused and nothing is done
Expand Down
2 changes: 1 addition & 1 deletion ROADMAP.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ integration), #56/#57/#58 (the three admits surfaced by #55).

[IMPORTANT]
====
*Parked* by owner ruling OD-42 (2026-11-17; recorded in `docs/plans/VSH-ROUTE-PLAN-2026-11-04.adoc` on valence-shell#230). The engine is the product and the shell interpreter is one front end, which comes last. What the interpreter does today is measured by `impl/rust-cli/tests/conformance_battery.rs` (67 of 128 command lines match bash), not by the list below, parts of which are out of date.
*Parked* by owner ruling OD-42 (2026-11-17; recorded in `docs/plans/VSH-ROUTE-PLAN-2026-11-04.adoc` on valence-shell#230). The engine is the product and the shell interpreter is one front end, which comes last. What the interpreter does today is measured by `impl/rust-cli/tests/conformance_battery.rs` (69 of 128 command lines match bash), not by the list below, parts of which are out of date.
====

Most critical missing POSIX features, ranked by impact (per CLAUDE.md
Expand Down
5 changes: 5 additions & 0 deletions impl/rust-cli/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,11 @@ which = "7.0"
proptest = "1.10"
tempfile = "3.26"

# Pseudo-terminal for the tests that run the built shell at its prompt
# (tests/function_frame_tests.rs). Same crate and version as above; the `term`
# feature is turned on for test builds only.
nix = { version = "0.31", default-features = false, features = ["fs", "term"] }

# Benchmarking
criterion = "0.5"

Expand Down
182 changes: 142 additions & 40 deletions impl/rust-cli/src/executable.rs
Original file line number Diff line number Diff line change
Expand Up @@ -70,8 +70,10 @@
Return { exit_code: i32 },
}

impl ExecutableCommand for Command {
fn execute(&self, state: &mut ShellState) -> Result<ExecutionResult> {
impl Command {
/// Run the command itself. A failure can come back as an error here;
/// [`ExecutableCommand::execute`] turns it into a failed status.
fn run(&self, state: &mut ShellState) -> Result<ExecutionResult> {

Check failure on line 76 in impl/rust-cli/src/executable.rs

View check run for this annotation

SonarQubeCloud / SonarCloud Code Analysis

Refactor this function to reduce its Cognitive Complexity from 339 to the 30 allowed.

See more on https://sonarcloud.io/project/issues?id=hyperpolymath_valence-shell2&issues=AaHsSC-XcxGY-RHtvgBM&open=AaHsSC-XcxGY-RHtvgBM&pullRequest=243
match self {
// Filesystem operations (reversible)
Command::Mkdir { path, redirects } => {
Expand Down Expand Up @@ -949,16 +951,13 @@
let params: Vec<String> = args[1..].to_vec();
state.set_positional_params(params);
} else if args[0].starts_with('-') || args[0].starts_with('+') {
// Shell options (stub: just acknowledge)
// -e: exit on error, -x: trace, -u: error on unset, etc.
// Shell options. `-e` is honoured; `-x` and `-u` are only
// recorded.
for arg in args {
let enable = arg.starts_with('-');
for ch in arg[1..].chars() {
match ch {
'e' => state.set_variable(
"SHOPT_E".to_string(),
if enable { "1" } else { "0" }.to_string(),
),
'e' => state.errexit = enable,
'x' => state.set_variable(
"SHOPT_X".to_string(),
if enable { "1" } else { "0" }.to_string(),
Expand Down Expand Up @@ -1000,8 +999,15 @@
.map(|a| crate::parser::expand_variables(a, state))
.collect();
let combined = expanded_args.join(" ");
let cmd = crate::parser::parse_command(&combined)?;
cmd.execute(state)
match crate::parser::parse_command(&combined) {
Ok(cmd) => cmd.execute(state),
// A line that cannot be read is status 2, as in bash
// and dash.
Err(e) => {
eprintln!("vsh: eval: {e}");
Ok(ExecutionResult::ExternalCommand { exit_code: 2 })
}
}
}

// Control structures
Expand All @@ -1011,8 +1017,9 @@
elif_parts,
else_body,
} => {
// Execute condition and get exit code
let cond_result = condition.execute(state)?;
// Execute condition and get exit code. `set -e` does not
// apply to it.
let cond_result = as_condition(state, |s| condition.execute(s))?;
let cond_exit = match cond_result {
ExecutionResult::Success => 0,
ExecutionResult::Exit => return Ok(ExecutionResult::Exit),
Expand All @@ -1029,7 +1036,7 @@

// Try elif parts
for (elif_cond, elif_body) in elif_parts {
let elif_result = elif_cond.execute(state)?;
let elif_result = as_condition(state, |s| elif_cond.execute(s))?;
let elif_exit = match elif_result {
ExecutionResult::Success => 0,
ExecutionResult::Exit => return Ok(ExecutionResult::Exit),
Expand All @@ -1048,8 +1055,9 @@
return execute_block(else_cmds, state);
}

// No branch matched — return last condition's exit code
Ok(ExecutionResult::ExternalCommand { exit_code: 1 })
// No branch ran: the status is 0 (POSIX 2.9.4.4). It was 1,
// which `set -e` would take for a failure.
Ok(ExecutionResult::ExternalCommand { exit_code: 0 })
}

Command::WhileLoop { condition, body } => {
Expand Down Expand Up @@ -1125,8 +1133,9 @@
} => {
use crate::parser::LogicalOperator;

// Execute left command
let left_result = left.execute(state)?;
// Execute left command. `set -e` does not apply to it, only
// to the command that ends the list.
let left_result = as_condition(state, |s| left.execute(s))?;

// Get exit code from left command
let left_exit_code = match left_result {
Expand Down Expand Up @@ -1214,7 +1223,9 @@
// Return from function
Command::Return { code } => {
if state.functions.call_depth() == 0 {
anyhow::bail!("return: can only return from a function");
// Status 2, as bash gives.
eprintln!("vsh: return: can only return from a function");
return Ok(ExecutionResult::ExternalCommand { exit_code: 2 });
}
let exit_code = code.unwrap_or(state.last_exit_code);
state.last_exit_code = exit_code;
Expand Down Expand Up @@ -1296,6 +1307,58 @@
}
}

/// The commands that hold other commands. Their status is that of a
/// command inside them, which `set -e` has already seen, or of a
/// condition, which `set -e` does not apply to.
fn is_compound(&self) -> bool {
matches!(
self,
Command::If { .. }
| Command::WhileLoop { .. }
| Command::UntilLoop { .. }
| Command::ForLoop { .. }
| Command::CaseStatement { .. }
| Command::LogicalOp { .. }
| Command::Source { .. }
| Command::Eval { .. }
)
}
}

impl ExecutableCommand for Command {
/// Every command is a boundary. A command that fails prints what went
/// wrong and fails with status 1; whatever ran it goes on, as in a POSIX
/// shell: the next line of a script or a function, the next turn of a
/// loop, the other side of `||`. It used to be an error that unwound
/// through every enclosing command, so `mkdir x || echo no` never ran
/// `echo no`, and a script ended at the first built-in that failed.
///
/// With `set -e`, a simple command that fails ends the shell, outside
/// the contexts listed at [`ShellState::errexit_suppressed`].
///
/// This never returns `Err`. The type stays a `Result` for the callers.
fn execute(&self, state: &mut ShellState) -> Result<ExecutionResult> {
let result = match self.run(state) {
Ok(result) => result,
Err(e) => {
eprintln!("vsh: {e}");
state.last_exit_code = 1;
ExecutionResult::ExternalCommand { exit_code: 1 }
}
};
if let ExecutionResult::ExternalCommand { exit_code } = result {
if exit_code != 0
&& state.errexit
&& state.errexit_suppressed == 0
&& !self.is_compound()
{
state.last_exit_code = exit_code;
return Ok(ExecutionResult::Exit);
}
}
Ok(result)
}

fn is_reversible(&self) -> bool {
matches!(
self,
Expand Down Expand Up @@ -1608,11 +1671,12 @@
/// 1. Save current positional parameters
/// 2. Set new positional parameters from function arguments
/// 3. Push a function frame for local variable scoping
/// 4. Parse the raw function body, splitting on semicolons/newlines with
/// control-structure awareness (so `if/fi`, `for/done`, `while/done`,
/// and `case/esac` work inside a function body)
/// 5. Execute each segment; stop early on `return` / `exit`
/// 6. Restore positional parameters and local variables
/// 4. Run the body ([`run_function_body`])
/// 5. Pop the frame: restore positional parameters and local variables
///
/// Step 5 runs however the body ended: at its last command, at `return` or
/// `exit`, or at a command that returned an error. The error still goes to
/// the caller; the frame does not go with it.
fn execute_function_call(
func_def: &crate::functions::FunctionDef,
args: &[String],
Expand All @@ -1627,6 +1691,47 @@
// Push a function frame
state.functions.push_frame(saved_params.clone());

// Run the body. There is no `?` on this call, and there must not be one:
// the frame is popped before the result goes back, whichever it is. An
// error that left with the frame still pushed would leave the caller
// with the function's local variables and positional parameters, and
// with a call depth that lets `local` and `return` run outside any
// function.
let result = run_function_body(func_def, state);

// Pop function frame and restore local variables
if let Some(frame) = state.functions.pop_frame() {
// Restore positional parameters
state.set_positional_params(frame.saved_params);

// Restore local variables to their previous values
for (var_name, prev_value) in &frame.saved_vars {
match prev_value {
Some(val) => state.set_variable(var_name.clone(), val.clone()),
None => {
state.unset_variable(var_name);
}
}
}
}

result
}

/// Run the body of a shell function, inside the frame that
/// [`execute_function_call`] pushed and will pop.
///
/// 1. Parse the raw function body, splitting on semicolons/newlines with
/// control-structure awareness (so `if/fi`, `for/done`, `while/done`,
/// and `case/esac` work inside a function body)
/// 2. Execute each segment; stop early on `return` / `exit`
///
/// This is a function of its own so that every way out of the body, the `?`
/// below included, comes back to one place in the caller.
fn run_function_body(
func_def: &crate::functions::FunctionDef,
state: &mut ShellState,
) -> Result<ExecutionResult> {
// Execute function body. We prefer the raw body string (which preserves
// control-structure integrity) and fall back to the pre-split segments
// for older in-memory definitions.
Expand Down Expand Up @@ -1688,25 +1793,22 @@
}
}

// Pop function frame and restore local variables
if let Some(frame) = state.functions.pop_frame() {
// Restore positional parameters
state.set_positional_params(frame.saved_params);

// Restore local variables to their previous values
for (var_name, prev_value) in &frame.saved_vars {
match prev_value {
Some(val) => state.set_variable(var_name.clone(), val.clone()),
None => {
state.unset_variable(var_name);
}
}
}
}

Ok(last_result)
}

/// Run `f` where `set -e` does not apply: a condition, or a command of an
/// `&&` or `||` list that is not the last. The context closes on every way
/// out of `f`.
fn as_condition(
state: &mut ShellState,
f: impl FnOnce(&mut ShellState) -> Result<ExecutionResult>,
) -> Result<ExecutionResult> {
state.errexit_suppressed += 1;
let result = f(state);
state.errexit_suppressed -= 1;
result
}

/// Execute a block of commands in sequence, returning the result of the last command.
///
/// Short-circuits on `Exit` (shell-wide) and `Return` (function-scope) so the
Expand Down Expand Up @@ -1764,7 +1866,7 @@
}
iterations += 1;

let cond_result = condition.execute(state)?;
let cond_result = as_condition(state, |s| condition.execute(s))?;
let cond_exit = match cond_result {
ExecutionResult::Success => 0,
ExecutionResult::Exit => return Ok(ExecutionResult::Exit),
Expand Down
11 changes: 11 additions & 0 deletions impl/rust-cli/src/state.rs
Original file line number Diff line number Diff line change
Expand Up @@ -288,6 +288,15 @@ pub struct ShellState {
/// loops. A script, or `-c`, leaves it unset.
pub interactive: bool,

/// `set -e`: a simple command that fails ends the shell, with its status.
pub errexit: bool,

/// How many contexts are open in which `set -e` does not apply: the
/// condition of `if`, `elif`, `while` and `until`, and every command of
/// an `&&` or `||` list but the last. A function called there is inside
/// the context too.
pub errexit_suppressed: usize,

/// Previous directory for cd - support
pub previous_dir: Option<PathBuf>,

Expand Down Expand Up @@ -351,6 +360,8 @@ impl ShellState {
state_file,
last_exit_code: 0,
interactive: false,
errexit: false,
errexit_suppressed: 0,
previous_dir: None,
variables: HashMap::new(),
exported_vars: HashSet::new(),
Expand Down
4 changes: 3 additions & 1 deletion impl/rust-cli/tests/builtin_strictness_tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -499,6 +499,8 @@ fn an_exit_trap_reports_a_statement_that_fails() {
"stdout: {}",
run.stdout
);
assert!(run.stderr.contains("vsh: trap: "), "stderr: {}", run.stderr);
// A statement that cannot be read says `vsh: trap:`. One that runs and
// fails is reported like any failed command, `vsh: ` and the reason.
assert!(run.stderr.contains("vsh: "), "stderr: {}", run.stderr);
assert!(run.stderr.contains("exists"), "stderr: {}", run.stderr);
}
Loading
Loading