harn-stdlib 0.10.201

Embedded Harn standard library source catalog
Documentation
/** 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
}