/** A literal command and its effective repository-relative working directory. */
pub type CommandSequenceStep = {argv: list<string>, cwd: string}
/** An unavailable shell observation never counts as an empty successful plan. */
pub type CommandSequencePlan = {status: "measured" | "unmeasured", steps: list<CommandSequenceStep>}
/**
* Observe literal POSIX commands joined with `&&`, including relative `cd`
* and subshell directory scopes. Quoted operators remain argument text.
* Dynamic shell syntax, redirects, other control flow, stateful builtins,
* path escapes and empty sequences are unmeasured. This never runs commands
* and does not grant execution authority or prove an exit status.
*
* @effects: []
* @errors: []
*/
pub fn command_sequence_plan(source: string, cwd: string = "") -> CommandSequencePlan {
return __command_sequence_plan(source, cwd)
}
/**
* One pipeline stage of a shell line. A `command` stage is a simple command,
* possibly with redirects, and `words` is its unquoted argv text. A `compound`
* stage (subshell, block, control flow) carries only its `text`.
*/
pub type ShellCommandStage = {kind: "command" | "compound", text: string, words: list<string>}
/**
* One chain member: a pipeline of stages and the operator joining it to the
* member before it: `""` for the first, otherwise `&&`, `||`, `;`, `&` or a
* newline.
*/
pub type ShellCommandSegment = {operator: string, stages: list<ShellCommandStage>}
/** What a zero exit proves about visible shell commands, never their individual exits. */
pub type ShellExitEvidence = {
scope: "all_commands" | "masked" | "unmeasured",
reason: "all_commands" \
| "syntax" \
| "dialect" \
| "chain_status" \
| "pipeline_status" \
| "compound_command" \
| "nested_execution" \
| "shell_state",
}
/** An unmeasured line never reads as a single simple command. */
pub type ShellCommandShape = {
status: "measured" | "unmeasured",
dialect: string,
segments: list<ShellCommandSegment>,
exit_evidence: ShellExitEvidence,
}
/**
* Read the operator structure of a shell line for the named shell (`sh`,
* `bash`, `zsh`, `pwsh`, `powershell`), with the same grammars the command
* policy uses. Quoted operators remain argument text. Unparseable lines, empty
* lines, unknown shells and `cmd` expose no operator segments. Exit evidence
* can separately recognize a literal CMD success chain. This never runs
* commands and grants no execution authority.
*
* @effects: []
* @errors: []
*/
pub fn shell_command_shape(source: string, shell: string = "sh") -> ShellCommandShape {
return __shell_command_shape(source, shell)
}
/**
* Analyze whether a zero shell exit proves every visible command succeeded.
* Plain POSIX commands and AND chains are covered. A pipeline requires an
* earlier `set -o pipefail` joined by AND, or a leading option setter in Bash
* or Zsh. PowerShell literal commands and AND chains use its own grammar and
* last-command status. CMD supports literal unquoted commands and AND chains;
* quoting, expansion and control flow remain unmeasured. Other separators,
* fallback chains and background commands can mask failures. Compound or
* nested execution remains unmeasured. This is syntax evidence, not execution
* or proof of a program's internal checks, imported functions, or collection.
*
* @effects: []
* @errors: []
*/
pub fn shell_exit_evidence(source: string, shell: string = "sh") -> ShellExitEvidence {
return shell_command_shape(source, shell).exit_evidence
}