openlatch-client 0.6.6

//! The shell classifier — the walk, the shell table, and the 12 `unknown → ASK`
//! shapes. Plan 02 §2f, PRD §Client evaluator.
//!
//! # Normalisation happens BEFORE the parse
//!
//! NFKC, then strip zero-width characters, then walk. Shape 7 (a non-ASCII
//! program name after NFKC, mixed-script confusables) is only detectable if
//! normalisation happens first — get the order wrong and one of the twelve
//! shapes is permanently undetectable while nothing else fails.
//!
//! # Walk EVERY simple command
//!
//! Pipelines, substitutions, `&&`/`||` chains; recurse through the wrapper list
//! (`timeout time nice nohup stdbuf command builtin noglob env exec xargs`) and
//! the env runners (`npx`, `devbox run`, `mise exec`, `direnv exec`,
//! `docker exec`). **Never prefix-approve a runner** — `docker exec` is not a
//! safe prefix, it is a door.
//!
//! # Where tree-sitter is, and where it deliberately is not
//!
//! `tree-sitter-bash` answers exactly one question here: **does this command
//! parse at all** (shape 1's `ERROR`/`MISSING` nodes). Splitting the chain is
//! done by the tokeniser below rather than by walking the AST, and that is a
//! decision, not an omission: the conformance corpus pins the *token* a
//! classifier saw — `$(which rm) -rf x` is expected to yield
//! `execute × shell` with `program: "$(which"` and the shape-2 gap beside it, not
//! a tidy `command_substitution` node. Both readings answer "we cannot know what
//! ran"; only one of them is the corpus's. The AST's contribution is the shape
//! the tokeniser cannot see — text that is not a shell command at all.
//!
//! # D-15
//!
//! Unknown-ness is per simple command and is carried ALONGSIDE confident tuples.
//! `rm -rf /data/x && $UNKNOWN_CMD` yields the confident `delete × data_store`
//! AND an unknown entry. Never one in place of the other.

use unicode_normalization::UnicodeNormalization;

use super::super::facts::FactSet;
use super::super::types::{Classification, SimpleCommand};
use super::catalogue::{self, Fallback, MergedSelector, VERB_MUTATION, VERB_STATEMENT};
use super::path::{self, PathEnv};
use super::{add_effect, add_unknown, attrs_of};

/// Characters an attacker can hide a program name behind. Stripped before the
/// program name is read.
pub const ZERO_WIDTH: &[char] = &['\u{200b}', '\u{200c}', '\u{200d}', '\u{2060}', '\u{feff}'];

/// The length past which a command is shape 1 without being parsed at all.
pub const MAX_COMMAND_CHARS: usize = 10_000;

/// Wrappers that are stripped and recursed through, never approved.
///
/// The PRD's wrapper row and its shape-8 row overlap: `xargs`, `watch`,
/// `setsid`, `flock` and `ionice` are both "strip and recurse" and "a runner
/// whose inner command hitting 1–7 becomes shape 8". They are one list here and
/// [`SHAPE8_RUNNERS`] marks the overlap.
pub const WRAPPERS: &[&str] = &[
    "timeout", "time", "nice", "nohup", "stdbuf", "command", "builtin", "noglob", "env", "exec",
    "xargs", "watch", "setsid", "flock", "ionice",
];

/// Env runners the classifier recurses into. **Never prefix-approve a runner** —
/// `npx <anything>` is not `npx`. `docker exec` is handled in
/// [`strip_wrapper`], because it eats a container name where these eat a flag.
pub const ENV_RUNNERS: &[&str] = &["npx", "devbox", "mise", "direnv"];

/// Stripping one of these is what turns an inner shape 1–7 into shape 8.
pub const SHAPE8_RUNNERS: &[&str] = &["xargs", "watch", "setsid", "flock", "ionice"];

/// Assignment prefixes that change what a later program even is — shape 6.
pub const DANGEROUS_ASSIGNMENTS: &[&str] =
    &["PATH", "LD_PRELOAD", "LD_LIBRARY_PATH", "BASH_ENV", "ENV"];

const INTERPRETERS: &[&str] = &[
    "sh", "bash", "zsh", "dash", "ksh", "python", "python3", "node", "perl", "ruby",
];
const DECODERS: &[&str] = &["base64", "xxd", "printf"];
/// Shells whose `-c '<literal>'` is a command line like the `Bash` tool's own.
const SHELL_INTERPRETERS: &[&str] = &["sh", "bash", "zsh", "dash", "ksh"];
/// Interpreters whose inline code (`-c`, `-e`, …) is unreadable, whatever it says.
const CODE_INTERPRETERS: &[&str] = &["python", "python3", "node", "perl", "ruby"];
/// The flags that hand an interpreter its program as an argument.
const INLINE_CODE_FLAGS: &[&str] = &["-c", "-e", "-E", "--eval", "-p"];

// ── What the shell classifier keeps in code ─────────────────────────
//
// The lookup rows of the PRD's shell table — which programs delete, which talk to
// a database, which reach the network, which escalate, which drive infrastructure,
// which install — are **program entries of the catalogue** now (AZ-4 D-I16-28).
// What stays here is logic that is not a lookup (D-I16-30): the wrappers and
// runners, `sudo` recursion, redirections, SQL parsing, the `git` / `gh` / `find` /
// `docker` rows, shape detection, and the infrastructure verbs that decide
// `write` from `delete`.

const RECURSING_ESCALATORS: &[&str] = &["sudo", "su", "doas"];

/// Branch prefixes a forced push must not land on.
///
/// **The PRD names this row's own gap:** nothing in the client knows which
/// branches a customer protects, so this list is a seed and a forced push onto
/// anything else emits only `write × vcs_remote`.
pub const PROTECTED_BRANCHES: &[&str] = &["main", "master", "trunk", "production", "release"];

/// The flags that name a remote context — `production_namespace`'s resolver.
const CONTEXT_FLAGS: &[&str] = &[
    "--context",
    "-n",
    "--namespace",
    "--profile",
    "--project",
    "--configuration",
    "--subscription",
    "-H",
    "--host",
    "--workspace",
];
const INFRA_MUTATING: &[&str] = &[
    "apply",
    "delete",
    "scale",
    "rollout",
    "create",
    "patch",
    "replace",
    "edit",
    "upgrade",
    "uninstall",
    "install",
    "destroy",
    "rm",
    "put",
    "update",
    "set",
];
const INFRA_DELETING: &[&str] = &["delete", "destroy", "uninstall", "rm"];

/// The null device, in both spellings the PRD names. A write here is not a
/// write and a read here reads nothing, so the redirection row and the
/// path-operand row both skip it.
///
/// These are **classification data, not paths this process resolves**: they are
/// compared as text against a string the caller declared, and never opened.
/// `ci/check-engine-purity.py` rule `filesystem` proves the stronger claim the
/// portability waiver below is standing on — the engine touches no filesystem at
/// all, so a path that does not exist behaves exactly like one that does.
const NULL_DEVICE: &[&str] = &["/dev/null", "NUL"]; // portability-ok: text compare, never opened

/// Short options that eat the token after them.
///
/// Without this a wrapper's option ARGUMENT becomes the inner program: the
/// oracle reads `nice -n 19 rm -rf /data/x` as the program `19`, loses the
/// `rm`, and reports a coverage gap where there is a confident delete. Keyed by
/// wrapper because the flag letters mean different things to different
/// programs — `-n` is a count to `nice` and non-interactive to `sudo`.
const VALUE_FLAGS: &[(&str, &[&str])] = &[
    ("nice", &["-n"]),
    ("ionice", &["-c", "-n", "-p"]),
    ("flock", &["-w", "-E"]),
    ("watch", &["-n", "--interval"]),
    (
        "xargs",
        &["-n", "-P", "-I", "-i", "-d", "-E", "-L", "-s", "-a"],
    ),
    ("stdbuf", &["-i", "-o", "-e"]),
    ("env", &["-u", "-C"]),
    ("sudo", &["-u", "-g", "-p", "-C", "-h", "-r", "-t", "-U"]),
    ("doas", &["-u", "-C"]),
    ("su", &["-c", "-s", "-g"]),
    (
        "docker",
        &["-u", "-w", "-e", "--user", "--workdir", "--env"],
    ),
];

/// Wrappers nest — `env FOO=1 timeout 30 rm x` is three deep — so stripping
/// loops. The bound is what keeps a pathological `env env env …` from spinning.
const MAX_STRIP_ROUNDS: usize = 8;

fn is(program: &str, table: &[&str]) -> bool {
    table.contains(&program)
}

// ── Normalisation ────────────────────────────────────────────────────

/// NFKC-normalise and strip zero-width characters, **before** any parse.
pub fn normalise(command: &str) -> String {
    command
        .nfkc()
        .filter(|ch| !ZERO_WIDTH.contains(ch))
        .collect()
}

// ── The tokeniser ────────────────────────────────────────────────────

/// Unbalanced quoting — the classifier refuses to guess what was meant, which
/// is shape 1.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TokeniseError;

/// Longest match first: `2>>` before `2>`, `<<<` before `<<` before `<`.
const OPERATORS: &[&str] = &[
    "&&", "||", "2>>", "2>", ">>", "<<<", "<<", ">", "<", "|", ";", "&", "\n",
];
const SEPARATORS: &[&str] = &["&&", "||", "|", ";", "&", "\n"];
const REDIRECT_OPS: &[&str] = &[">", ">>", "2>", "2>>", "<", "<<", "<<<"];

/// Split a command string into words and operators, honouring quotes.
///
/// A token keeps its quotes, so a caller can still ask *"was this argument a
/// literal?"* — shapes 3 and 10 turn on exactly that question, and
/// [`unquote`] has thrown the answer away by the time they run.
pub fn tokenise(command: &str) -> Result<Vec<String>, TokeniseError> {
    let chars: Vec<char> = command.chars().collect();
    let mut tokens: Vec<String> = Vec::new();
    let mut current = String::new();
    let mut quote: Option<char> = None;
    let mut i = 0;
    while i < chars.len() {
        let ch = chars[i];
        if let Some(open) = quote {
            current.push(ch);
            if ch == '\\' && open == '"' && i + 1 < chars.len() {
                current.push(chars[i + 1]);
                i += 2;
                continue;
            }
            if ch == open {
                quote = None;
            }
            i += 1;
            continue;
        }
        if ch == '\'' || ch == '"' {
            quote = Some(ch);
            current.push(ch);
            i += 1;
            continue;
        }
        if ch == '\\' && i + 1 < chars.len() {
            current.push(ch);
            current.push(chars[i + 1]);
            i += 2;
            continue;
        }
        if ch == ' ' || ch == '\t' {
            if !current.is_empty() {
                tokens.push(std::mem::take(&mut current));
            }
            i += 1;
            continue;
        }
        if let Some(op) = OPERATORS
            .iter()
            .find(|op| chars[i..].starts_with(&op.chars().collect::<Vec<_>>()[..]))
        {
            if !current.is_empty() {
                tokens.push(std::mem::take(&mut current));
            }
            tokens.push((*op).to_string());
            i += op.chars().count();
            continue;
        }
        current.push(ch);
        i += 1;
    }
    if quote.is_some() {
        return Err(TokeniseError);
    }
    if !current.is_empty() {
        tokens.push(current);
    }
    Ok(tokens)
}

/// Strip one layer of surrounding quotes, and backslash escapes.
pub fn unquote(token: &str) -> String {
    let chars: Vec<char> = token.chars().collect();
    let mut out = String::new();
    let mut quote: Option<char> = None;
    let mut i = 0;
    while i < chars.len() {
        let ch = chars[i];
        if quote.is_none() && (ch == '\'' || ch == '"') {
            quote = Some(ch);
        } else if quote == Some(ch) {
            quote = None;
        } else if ch == '\\' && i + 1 < chars.len() {
            out.push(chars[i + 1]);
            i += 2;
            continue;
        } else {
            out.push(ch);
        }
        i += 1;
    }
    out
}

/// True when the token contains no expansion the classifier would have to run.
pub fn is_literal(token: &str) -> bool {
    !token.contains('$')
        && !token.contains('`')
        && !token.contains('*')
        && !token.contains('?')
        && !token.contains('~')
}

/// Whether a quoted `-c` operand carries code the classifier can read: no `$` and
/// no backtick outside single quotes. A `*`, a `?` or a `~` inside a command
/// string is text for the inner command to read, not an expansion the outer shell
/// runs before it — so `bash -c "cat ~/.ssh/id_rsa"` is readable (AZ-4 D-14).
pub fn is_literal_code(raw: &str) -> bool {
    let (mut single, mut double) = (false, false);
    let mut chars = raw.chars();
    while let Some(ch) = chars.next() {
        match ch {
            '\'' if !double => single = !single,
            '"' if !single => double = !double,
            '\\' if !single => {
                chars.next();
            }
            '$' | '`' if !single => return false,
            _ => {}
        }
    }
    true
}

/// A redirection source the walk can resolve: no variable, substitution or glob.
/// `~` is fine — the resolver reads it against the declared home.
fn is_resolvable(target: &str) -> bool {
    !target.contains(['$', '`', '*', '?'])
}

/// Every quoted string literal of an inline program, in order. A lexical scan and
/// nothing more: it makes no claim to understand the language around the strings.
fn string_literals(code: &str) -> Vec<String> {
    let chars: Vec<char> = code.chars().collect();
    let mut out = Vec::new();
    let mut i = 0;
    while i < chars.len() {
        let quote = chars[i];
        if quote != '\'' && quote != '"' {
            i += 1;
            continue;
        }
        let mut literal = String::new();
        i += 1;
        while i < chars.len() && chars[i] != quote {
            if chars[i] == '\\' && i + 1 < chars.len() {
                i += 1;
            }
            literal.push(chars[i]);
            i += 1;
        }
        i += 1;
        out.push(literal);
    }
    out
}

/// The program an interpreter is handed inline: the argument after `-c`, `-e`,
/// `-E` or `-p`, or after `--eval` (or `--eval=…`).
fn inline_code(sc: &SimpleCommand) -> Option<String> {
    for (i, arg) in sc.argv.iter().enumerate() {
        if INLINE_CODE_FLAGS.contains(&arg.as_str()) {
            return Some(sc.argv.get(i + 1).cloned().unwrap_or_default());
        }
        if let Some(code) = arg.strip_prefix("--eval=") {
            return Some(code.to_string());
        }
    }
    None
}

// ── Splitting a command line into simple commands ────────────────────

struct Part {
    /// The separator BEFORE this part. `| sh` is shape 4 and `&& sh` is not.
    sep: String,
    tokens: Vec<String>,
}

/// One simple command of the chain, plus everything the walk learned about it
/// while stripping it down. The chain is built in full before any of it is
/// classified, because shape 4 asks what the NEXT program is.
struct Built {
    command: SimpleCommand,
    /// The wrapper layers stripped to reach `command`, outermost first.
    wrappers: Vec<SimpleCommand>,
    /// Shapes noticed during the strip — assignment prefixes, so far.
    shapes: Vec<(i64, String)>,
    /// Whether a [`SHAPE8_RUNNERS`] member was stripped to get here.
    via_runner: bool,
    sep: String,
    tokens: Vec<String>,
}

fn split_chain(tokens: Vec<String>) -> Vec<Part> {
    let mut parts: Vec<Part> = Vec::new();
    let mut current: Vec<String> = Vec::new();
    let mut sep = String::new();
    for token in tokens {
        if SEPARATORS.contains(&token.as_str()) {
            parts.push(Part {
                sep: std::mem::take(&mut sep),
                tokens: std::mem::take(&mut current),
            });
            sep = token;
            continue;
        }
        current.push(token);
    }
    parts.push(Part {
        sep,
        tokens: current,
    });
    parts.retain(|part| !part.tokens.is_empty());
    parts
}

/// Pull the redirections out of a word list.
///
/// They come out first because `cp a b > c` has three path operands, two of
/// which are arguments and one of which is a write target.
fn split_redirects(words: Vec<String>) -> (Vec<String>, Vec<(String, String)>) {
    let mut kept = Vec::new();
    let mut redirects = Vec::new();
    let mut i = 0;
    while i < words.len() {
        if REDIRECT_OPS.contains(&words[i].as_str()) && i + 1 < words.len() {
            // `> >(cmd)`, `>(cmd)`, `<(cmd)`: a process substitution is a command,
            // not a file. The tokeniser splits it into operator tokens and a
            // `(`-led word, none of which names a path (a space between a
            // redirect operator and `(` is a bash syntax error, so the shapes
            // cannot be a real target). Skip the whole opener.
            let mut j = i + 1;
            while j < words.len() && REDIRECT_OPS.contains(&words[j].as_str()) {
                j += 1;
            }
            if j < words.len() && words[j].starts_with('(') {
                i = j + 1;
                continue;
            }
            redirects.push((words[i].clone(), unquote(&words[i + 1])));
            i += 2;
            continue;
        }
        kept.push(words[i].clone());
        i += 1;
    }
    (kept, redirects)
}

/// Drop a `FOO=1 BAR=2 cmd` prefix, reporting the ones that matter.
fn strip_assignments(mut words: Vec<String>) -> (Vec<String>, Vec<(i64, String)>) {
    let mut shapes = Vec::new();
    while let Some(first) = words.first() {
        if !first.contains('=') || first.starts_with('=') {
            break;
        }
        let name = first.split('=').next().unwrap_or_default().to_string();
        if !name.chars().all(|c| c.is_alphanumeric() || c == '_') || name.is_empty() {
            break;
        }
        if DANGEROUS_ASSIGNMENTS.contains(&name.as_str()) {
            shapes.push((
                6,
                format!("assignment prefix {name}= changes program resolution"),
            ));
        }
        words.remove(0);
    }
    (words, shapes)
}

/// Drop a wrapper's own leading options — never the inner command's, because
/// the inner command starts at the first non-option.
fn drop_options(program: &str, words: &[String]) -> Vec<String> {
    let value_flags = VALUE_FLAGS
        .iter()
        .find(|(name, _)| *name == program)
        .map(|(_, flags)| *flags)
        .unwrap_or(&[]);
    let mut i = 0;
    while i < words.len() && words[i].starts_with('-') {
        let eats_value = value_flags.contains(&words[i].as_str()) && i + 1 < words.len();
        i += if eats_value { 2 } else { 1 };
    }
    words[i..].to_vec()
}

/// One wrapper stripped, or `None` when `program` is not a wrapper at all.
///
/// One branch per wrapper family, each saying exactly what it eats. The families
/// differ, which is the whole reason this is not one generic rule: `timeout`
/// eats a bare duration, `devbox` eats a `run` subcommand, `direnv exec` eats a
/// directory, and `docker exec` eats a container name.
fn strip_wrapper(program: &str, words: &[String]) -> Option<Vec<String>> {
    if program == "timeout" {
        // `timeout 30 cmd`, `timeout -k 5 30 cmd`: options and bare durations in
        // any order, until the inner program.
        let mut rest = &words[1..];
        while rest.first().is_some_and(|w| {
            w.starts_with('-') || w.chars().next().is_some_and(|c| c.is_ascii_digit())
        }) {
            rest = &rest[1..];
        }
        return Some(rest.to_vec());
    }
    if is(program, WRAPPERS) {
        return Some(drop_options(program, &words[1..]));
    }
    if is(program, ENV_RUNNERS) {
        let mut rest = words[1..].to_vec();
        if matches!(program, "devbox" | "mise" | "direnv")
            && rest.first().is_some_and(|w| w == "run" || w == "exec")
        {
            rest.remove(0);
        }
        let mut rest = drop_options(program, &rest);
        // `direnv exec DIR COMMAND` — the directory is an operand, not the
        // inner program. Eating it is what stops `direnv exec . rm -rf /data/x`
        // classifying the program as `.`.
        if program == "direnv" && rest.len() > 1 {
            rest.remove(0);
        }
        return Some(rest);
    }
    if program == "docker" && words.len() > 1 && unquote(&words[1]) == "exec" {
        // `docker exec -it NAME cmd`.
        let rest = drop_options(program, &words[2..]);
        return Some(rest.into_iter().skip(1).collect());
    }
    None
}

/// What stripping one chain part down to a simple command produced.
struct Stripped {
    /// The simple command with every wrapper and env runner gone.
    command: SimpleCommand,
    /// Each layer stripped to reach it, **outermost first**.
    ///
    /// They are kept, not discarded, because `command.program` must see the
    /// runner AND what ran inside it. Keeping only the inner one silently breaks
    /// a rule written against `docker`; keeping only the outer one is
    /// prefix-approval, which the PRD forbids outright. Both, always.
    wrappers: Vec<SimpleCommand>,
    shapes: Vec<(i64, String)>,
    /// Whether a [`SHAPE8_RUNNERS`] member was among the layers.
    via_runner: bool,
}

/// Strip redirections, assignments, wrappers and runners, in that order.
///
/// Assignments are re-stripped every round, because a wrapper HIDES them behind
/// it: in `env FOO=1 rm x` the assignment is only visible once `env` is gone.
fn build_simple(tokens: &[String]) -> Stripped {
    let raw = tokens.join(" ");
    let (mut words, redirects) = split_redirects(tokens.to_vec());
    let mut shapes = Vec::new();
    let mut wrappers = Vec::new();
    let mut via_runner = false;

    for _ in 0..MAX_STRIP_ROUNDS {
        let (stripped_words, assignment_shapes) = strip_assignments(words);
        words = stripped_words;
        shapes.extend(assignment_shapes);
        if words.is_empty() {
            break;
        }
        let program = normalise(&unquote(&words[0]));
        let Some(stripped) = strip_wrapper(&program, &words) else {
            break;
        };
        wrappers.push(simple_of(&words, &[]));
        via_runner = via_runner || is(&program, SHAPE8_RUNNERS);
        words = stripped;
    }

    let mut command = simple_of(&words, &redirects);
    command.raw = raw;
    Stripped {
        command,
        wrappers,
        shapes,
        via_runner,
    }
}

/// One `SimpleCommand` from a word list. `raw` is the words rejoined; the caller
/// overwrites it where it has the original text.
fn simple_of(words: &[String], redirects: &[(String, String)]) -> SimpleCommand {
    let Some(head) = words.first() else {
        return SimpleCommand {
            raw: words.join(" "),
            redirects: redirects.to_vec(),
            ..SimpleCommand::default()
        };
    };
    SimpleCommand {
        program: normalise(&unquote(head)),
        argv: words[1..].iter().map(|w| unquote(w)).collect(),
        raw: words.join(" "),
        redirects: redirects.to_vec(),
        raw_argv: words[1..].to_vec(),
    }
}

// ── The 12 `unknown → ASK` shapes ────────────────────────────────────

/// Shapes 2–4, 6, 7, 10 and 12 for one simple command. Coarse on purpose.
///
/// Shapes 1, 5, 8, 9 and 11 are not here: 1 is the parse, 5 is chain-wide, 8 is
/// 1–7 seen through a runner, and 9 and 11 are the shell table's own answers.
fn detect_shapes(
    sc: &SimpleCommand,
    raw_tokens: &[String],
    sep: &str,
    next_program: &str,
) -> Vec<(i64, String)> {
    let mut shapes = Vec::new();
    let head = raw_tokens.first().map(String::as_str).unwrap_or("");

    // 2 — dynamic program name.
    if head.starts_with('$') || head.contains("$(") || head.contains('`') {
        shapes.push((2, "dynamic program name".to_string()));
    }

    // 3 — eval, an interpreter `-c` with a non-literal string, a non-literal source.
    if sc.program == "eval" {
        shapes.push((3, "eval".to_string()));
    }
    if is(&sc.program, INTERPRETERS) {
        if let Some(index) = sc.argv.iter().position(|a| a == "-c") {
            let operand = sc.raw_argv.get(index + 1).map(String::as_str).unwrap_or("");
            if !is_literal_code(operand) {
                shapes.push((3, format!("{} -c with a non-literal string", sc.program)));
            }
        }
    }
    if sc.program == "source" || sc.program == "." {
        let operand = sc.raw_argv.first().map(String::as_str).unwrap_or("");
        if !is_literal(operand) {
            shapes.push((3, "source of a non-literal path".to_string()));
        }
    }

    // 4 — a decoder feeding an interpreter, and a pipe or heredoc INTO one.
    if sep == "|" && is(&sc.program, INTERPRETERS) {
        shapes.push((4, "pipe into an interpreter".to_string()));
    }
    if is(&sc.program, DECODERS) && is(next_program, INTERPRETERS) {
        shapes.push((4, format!("{} feeding {next_program}", sc.program)));
    }
    if sc.redirects.iter().any(|(op, _)| op == "<<" || op == "<<<") && is(&sc.program, INTERPRETERS)
    {
        shapes.push((4, "heredoc into an interpreter".to_string()));
    }

    // 6 — alias and function definitions in the same command.
    if matches!(sc.program.as_str(), "alias" | "function" | "unalias")
        || raw_tokens.get(1).is_some_and(|t| t == "()")
    {
        shapes.push((6, "alias or function definition".to_string()));
    }

    // 7 — non-ASCII in the program name after NFKC, or mixed scripts.
    if !sc.program.is_empty() && !sc.program.is_ascii() {
        shapes.push((7, "non-ASCII program name after NFKC".to_string()));
    }

    // 10 — a redirection target that does not resolve.
    for (op, target) in &sc.redirects {
        if matches!(op.as_str(), ">" | ">>" | "2>" | "2>>") && !is_literal(target) {
            shapes.push((10, format!("unresolvable redirection target {target:?}")));
        }
        if op == "<" && !is_resolvable(target) {
            shapes.push((10, format!("unresolvable redirection source {target:?}")));
        }
    }

    // 12 — quote-escape shapes inside an otherwise mapped command. The
    // CVE-2025-54795 regression fixture, and a SECURITY test rather than a
    // parser nicety: the escape is how a second command hides inside the first.
    // Coarse on purpose — an escaped double quote next to a separator is enough
    // to refuse to read the command.
    if sc.raw.contains("\\\"")
        && (sc.raw.contains(';') || sc.raw.contains("&&") || sc.raw.contains('|'))
    {
        shapes.push((
            12,
            "escaped quote adjacent to a command separator".to_string(),
        ));
    }

    shapes
}

// ── The shell table ──────────────────────────────────────────────────

/// argv entries that are not flags — the path-shaped operands of a command.
fn operands(sc: &SimpleCommand) -> Vec<String> {
    sc.argv
        .iter()
        .filter(|a| !a.starts_with('-'))
        .cloned()
        .collect()
}

fn add_path_effect(
    cls: &mut Classification,
    verb: &str,
    raw_path: &str,
    facts: &FactSet,
    env: &PathEnv,
) {
    if is(raw_path, NULL_DEVICE) {
        return; // the PRD skips it explicitly
    }
    let classes = path::resolve_all(raw_path, env, facts);
    if classes.is_empty() {
        add_unknown(
            cls,
            10,
            format!("path operand does not resolve to a class: {raw_path:?}"),
            raw_path,
        );
        return;
    }
    // Every class the path carries (D-I16-29), each tuple tagged with the target
    // entries that put the class there.
    for found in classes {
        let needs = catalogue::one_of(&found.origins);
        catalogue::within(cls, &needs, &[], |cls| {
            record_path(cls, raw_path, &found.class);
            add_effect(cls, verb, &found.class.0, attrs_of(&[]));
        });
    }
}

pub(super) fn record_path(
    cls: &mut Classification,
    value: &str,
    class: &crate::generated::types::TargetClass,
) {
    let entry = super::super::types::ClassifiedPath {
        class: class.clone(),
        value: value.to_string(),
    };
    // Deduplicated: `record_operands` and `add_path_effect` both see the same
    // operand, and `path.value` is a set of what the action named, not a tally.
    let tag = cls.provenance.tag_now();
    catalogue::record_path_tagged(cls, entry, tag);
}

/// What an UNCLASSIFIED command still tells us: the paths and URLs it names.
///
/// A command the shell table could not place is still a command that named
/// things, and D-15's discipline covers `paths` and `urls` exactly as it covers
/// `effects` — unknown-ness never erases what was observed. `cat
/// /data/warehouse/orders.db` is shape 9, and `path.class == data_store` must
/// still see it.
///
/// It records **no effect and no coverage gap**: the verb is what is unknown,
/// not the operand, and a shape 10 per argument of every `ls` would bury the
/// gap that matters under the gaps that do not.
///
/// # Why an operand is not simply "any argv entry"
///
/// Because most of them are not paths. `head -n 5 app.log` has the operand `5`,
/// and every bare relative token resolves through row 6's
/// relative-is-under-the-workspace fallthrough — so a blanket pass files `5`,
/// `--porcelain`'s argument and every subcommand name as a `workspace_file`, and
/// a rule reading `path.class == workspace_file` fires on all of them.
///
/// So an operand is recorded when it resolves **and** it either carries a path
/// separator or lands in a class other than `workspace_file`. What that drops
/// is exactly the bare relative token whose only possible class is the
/// fallthrough — the least policy-bearing class there is, and the one where a
/// false positive is most likely.
fn record_operands(sc: &SimpleCommand, cls: &mut Classification, facts: &FactSet, env: &PathEnv) {
    for operand in operands(sc) {
        if let Some(url) = super::parse_url(&operand) {
            if !cls.urls.contains(&url) {
                cls.urls.push(url);
            }
            continue;
        }
        for found in path::resolve_all(&operand, env, facts) {
            let looks_like_a_path = operand.contains('/')
                || operand.contains('\\')
                || found.class.0 != "workspace_file";
            if looks_like_a_path {
                let needs = catalogue::one_of(&found.origins);
                catalogue::within(cls, &needs, &[], |cls| {
                    record_path(cls, &operand, &found.class);
                });
            }
        }
    }
}

/// The value of the first of `flags` present in `argv`, as `--flag value` or
/// `--flag=value`.
fn flag_value(sc: &SimpleCommand, flags: &[&str]) -> Option<String> {
    for (i, arg) in sc.argv.iter().enumerate() {
        for flag in flags {
            if arg == flag {
                if let Some(value) = sc.argv.get(i + 1) {
                    return Some(value.clone());
                }
            }
            if let Some(value) = arg.strip_prefix(&format!("{flag}=")) {
                return Some(value.to_string());
            }
        }
    }
    None
}

/// `is_production` from the `env_selectors` fact, or `None` when unresolvable.
///
/// `None` is shape 11: a remote-target command whose context cannot be resolved.
fn resolve_production(
    sc: &SimpleCommand,
    cls: &mut Classification,
    facts: &FactSet,
) -> Option<bool> {
    let Some(selector) = flag_value(sc, CONTEXT_FLAGS) else {
        add_unknown(
            cls,
            11,
            format!("{}: no resolvable context flag", sc.program),
            &sc.raw,
        );
        return None;
    };
    if !is_literal(&selector) {
        add_unknown(
            cls,
            11,
            format!("{}: context {selector:?} does not resolve", sc.program),
            &sc.raw,
        );
        return None;
    }
    let members = path::fact_members(facts, "env_selectors");
    if members.is_empty() {
        add_unknown(
            cls,
            11,
            format!("{}: env_selectors fact unavailable", sc.program),
            &sc.raw,
        );
        return None;
    }
    Some(members.contains(&selector))
}

/// SQL/statement classification. `None` = unparsed, which the PRD calls unknown.
pub(super) fn classify_sql(statement: &str) -> Option<&'static str> {
    let head = statement
        .trim()
        .trim_matches(';')
        .trim_start_matches('(')
        .trim();
    let word = head.split_whitespace().next()?.to_uppercase();
    match word.as_str() {
        "SELECT" | "SHOW" | "EXPLAIN" | "DESCRIBE" | "DESC" | "WITH" | "GET" | "SCAN" => {
            Some("read")
        }
        "DROP" | "TRUNCATE" | "FLUSHALL" | "FLUSHDB" | "DEL" => Some("delete"),
        "DELETE" => {
            if format!(" {} ", head.to_uppercase()).contains(" WHERE ") {
                Some("write")
            } else {
                Some("delete")
            }
        }
        "INSERT" | "UPDATE" | "CREATE" | "ALTER" | "GRANT" | "REVOKE" | "COPY" | "SET" => {
            Some("write")
        }
        _ => None,
    }
}

/// The paths and URLs among an inline program's string literals, recorded as an
/// unclassified command's operands are: a path counts when it carries a separator or
/// lands in a class other than `workspace_file`.
fn record_literals(code: &str, cls: &mut Classification, facts: &FactSet, env: &PathEnv) {
    for literal in string_literals(code) {
        if let Some(url) = super::parse_url(&literal) {
            if !cls.urls.contains(&url) {
                cls.urls.push(url);
            }
            continue;
        }
        for found in path::resolve_all(&literal, env, facts) {
            let looks_like_a_path = literal.contains('/')
                || literal.contains('\\')
                || found.class.0 != "workspace_file";
            if looks_like_a_path {
                let needs = catalogue::one_of(&found.origins);
                catalogue::within(cls, &needs, &[], |cls| {
                    record_path(cls, &literal, &found.class);
                });
            }
        }
    }
}

/// What a command no code row and no program entry places leaves behind: the
/// coverage gap, `execute × shell` at the chain level, and the operands it named.
///
/// It is also what a view falls back to when the entries that *did* place a
/// program are outside the artifact's scope (spec §6.13), so it is written once
/// and run against a detached classification in that case.
fn record_unmapped(
    sc: &SimpleCommand,
    cls: &mut Classification,
    facts: &FactSet,
    env: &PathEnv,
    chain_level: bool,
) {
    add_unknown(
        cls,
        9,
        format!("{:?} is not in the shell table", sc.program),
        &sc.raw,
    );
    if chain_level {
        add_effect(
            cls,
            "execute",
            "shell",
            attrs_of(&[("program", serde_json::Value::from(sc.program.as_str()))]),
        );
    }
    record_operands(sc, cls, facts, env);
}

/// Map one simple command to effect tuples. `false` when it is unmapped.
///
/// The code rows run first and the catalogue's program entries after them, and
/// both contribute (spec §6.11): `gh auth token` is an escalation to the code row
/// and a secret read to the catalogue. `chain_level` is `false` for the inner
/// command of `sudo` or `find -exec`, which never carried `execute × shell`.
fn classify_simple(
    sc: &SimpleCommand,
    cls: &mut Classification,
    facts: &FactSet,
    env: &PathEnv,
    chain_level: bool,
) -> bool {
    let coded = classify_code_rows(sc, cls, facts, env);
    let entries = apply_program_entries(sc, cls, facts, env, chain_level);
    coded || entries
}

/// The rows that are logic and not lookups (D-I16-30).
fn classify_code_rows(
    sc: &SimpleCommand,
    cls: &mut Classification,
    facts: &FactSet,
    env: &PathEnv,
) -> bool {
    let program = sc.program.as_str();
    let sub = sc
        .argv
        .first()
        .filter(|a| !a.starts_with('-'))
        .cloned()
        .unwrap_or_default();

    if program == "truncate"
        && sc
            .argv
            .iter()
            .position(|a| a == "-s")
            .and_then(|i| sc.argv.get(i + 1))
            .is_some_and(|v| v == "0")
    {
        for operand in operands(sc).into_iter().skip(1) {
            add_path_effect(cls, "delete", &operand, facts, env);
        }
        return true;
    }

    if program == "find" {
        return classify_find(sc, cls, facts, env);
    }

    if program == "git" {
        return classify_git(sc, &sub, cls, facts, env);
    }

    if program == "gh" {
        if sub == "pr" && sc.argv.iter().any(|a| a == "merge") {
            add_effect(cls, "write", "vcs_remote", attrs_of(&[]));
            return true;
        }
        if sub == "auth" {
            add_effect(cls, "escalate", "identity_permission", attrs_of(&[]));
            return true;
        }
        return false;
    }

    if program == "aws" && sub == "iam" {
        add_effect(cls, "escalate", "identity_permission", attrs_of(&[]));
        return true;
    }

    if is(program, RECURSING_ESCALATORS) {
        // The PRD's row is `escalate × identity_permission` PLUS a recursion, so
        // the escalate tuple is carried alongside whatever the inner command
        // yields, never in place of it.
        add_effect(cls, "escalate", "identity_permission", attrs_of(&[]));
        // `drop_options` and NOT a filter over the whole argv: the escalator's
        // own flags come first and stop at the inner program, whereas dropping
        // every `-x` throws away the inner command's flags too — and the flags
        // are what classify it. `sudo git push --force origin main` read that way
        // loses the `--force`, and the tuple flips from `delete` to `write` with
        // `force: false`: confidently wrong, with no coverage gap to say so.
        let stripped = build_simple(&drop_options(program, &sc.raw_argv));
        let inner = stripped.command;
        for (shape, reason) in stripped.shapes {
            add_unknown(cls, shape, reason, &sc.raw);
        }
        // The escalator's inner command is a simple command the walk VISITED, so
        // it is recorded like any other. `sudo rm -rf /x` has to be visible to a
        // rule written against `rm`, not only to one written against `sudo`.
        cls.simple.extend(stripped.wrappers);
        if !inner.program.is_empty() {
            cls.simple.push(inner.clone());
        }
        if !inner.program.is_empty() && !classify_simple(&inner, cls, facts, env, false) {
            record_unmapped(&inner, cls, facts, env, false);
        }
        return true;
    }

    if program == "docker" && (sub == "run" || sub == "exec") {
        if flag_value(sc, &["-H", "--host", "--context"]).is_some() {
            resolve_production(sc, cls, facts);
        }
        add_effect(
            cls,
            "execute",
            "shell",
            attrs_of(&[("program", serde_json::Value::from(program))]),
        );
        return true;
    }

    // `sh -c '<literal>'` is a command line like the `Bash` tool's own: classified
    // recursively, and it does not also carry `execute × shell` (D-14).
    if is(program, SHELL_INTERPRETERS) {
        if let Some(index) = sc.argv.iter().position(|a| a == "-c") {
            if let (Some(code), Some(raw)) = (sc.argv.get(index + 1), sc.raw_argv.get(index + 1)) {
                if is_literal_code(raw) {
                    classify_into(code, cls, facts, env);
                    return true;
                }
            }
        }
    }

    // Inline code of another interpreter is unreadable (shape 9, `execute × shell`),
    // but its quoted string literals are resolved like operands: the claim is
    // "literals examined", never code analysis (D-14).
    if is(program, CODE_INTERPRETERS) {
        if let Some(code) = inline_code(sc) {
            add_effect(
                cls,
                "execute",
                "shell",
                attrs_of(&[("program", serde_json::Value::from(program))]),
            );
            add_unknown(
                cls,
                9,
                format!("{program}: inline code is not read"),
                &sc.raw,
            );
            record_literals(&code, cls, facts, env);
            return true;
        }
    }

    if is(program, INTERPRETERS) || program.starts_with("./") {
        add_effect(
            cls,
            "execute",
            "shell",
            attrs_of(&[("program", serde_json::Value::from(program))]),
        );
        return true;
    }

    if matches!(program, "cp" | "mv" | "tee") {
        let operands = operands(sc);
        if program == "tee" {
            for operand in operands {
                add_path_effect(cls, "write", &operand, facts, env);
            }
            return true;
        }
        if operands.len() >= 2 {
            let (sources, target) = operands.split_at(operands.len() - 1);
            for source in sources {
                add_path_effect(cls, "read", source, facts, env);
                if program == "mv" {
                    add_path_effect(cls, "delete", source, facts, env);
                }
            }
            add_path_effect(cls, "write", &target[0], facts, env);
        }
        return true;
    }

    false
}

// ── Program entries ──────────────────────────────────────────────────

/// The infrastructure verbs: `write` unless one of them deletes, and the
/// production flag read from the context the command names. `false` when the
/// command carries no mutating word at all — it is then not mapped.
fn apply_mutation(
    sc: &SimpleCommand,
    target_class: &str,
    cls: &mut Classification,
    facts: &FactSet,
) -> bool {
    let mutating: Vec<&String> = sc
        .argv
        .iter()
        .filter(|a| INFRA_MUTATING.contains(&a.as_str()))
        .collect();
    if mutating.is_empty() {
        return false;
    }
    let verb = if mutating
        .iter()
        .any(|v| INFRA_DELETING.contains(&v.as_str()))
    {
        "delete"
    } else {
        "write"
    };
    if let Some(is_production) = resolve_production(sc, cls, facts) {
        add_effect(
            cls,
            verb,
            target_class,
            attrs_of(&[("is_production", serde_json::Value::Bool(is_production))]),
        );
    }
    true
}

/// The statement an entry's `statement` role names: the first selector that
/// yields a value, so a flag beats the last positional.
fn statement_of(sc: &SimpleCommand, selectors: &[MergedSelector]) -> String {
    for merged in selectors {
        if let Some(value) = catalogue::select(&sc.argv, &merged.selector)
            .into_iter()
            .next()
        {
            return value;
        }
    }
    String::new()
}

/// The values the selectors of one role pick, each with the entry it came from.
fn role_values(
    sc: &SimpleCommand,
    selectors: &[MergedSelector],
) -> Vec<(String, catalogue::Origin)> {
    let mut out = Vec::new();
    for merged in selectors {
        for value in catalogue::select(&sc.argv, &merged.selector) {
            out.push((value, merged.origin.clone()));
        }
    }
    out
}

/// Apply the program entries that match this command. `true` when an entry
/// placed it.
///
/// One merged hit — the longest matching key, its entries unioned and `narrow`
/// ones subtracted — then each effect in turn. The entries' tuples carry their
/// origins, and the fallback the command would have without them is recorded
/// beside them for the views of artifacts that do not hold those entries.
fn apply_program_entries(
    sc: &SimpleCommand,
    cls: &mut Classification,
    facts: &FactSet,
    env: &PathEnv,
    chain_level: bool,
) -> bool {
    let Some(entries) = env.catalogue else {
        return false;
    };
    let lookup = entries.lookup_program(&sc.program, &sc.argv);
    let Some(hit) = lookup.hit else {
        return false;
    };
    // An entry that only carries `global_flags` (or operand roles) classifies
    // nothing: the command is not placed, and says so through the caller.
    if hit.effects.is_empty() && !hit.benign {
        return false;
    }

    // URLs the entries name are recorded whatever the effects are, as the
    // network rows always did: `curl` names a host even when it also reads a file.
    for (role, selectors) in &hit.operands {
        if role != "url" {
            continue;
        }
        for (value, _) in role_values(sc, selectors) {
            if let Some(url) = super::parse_url(&value) {
                cls.urls.push(url);
            }
        }
    }

    let mut mapped = false;
    for merged in &hit.effects {
        let needs = catalogue::one_of(&merged.origins);
        let spec = &merged.spec;
        let placed = catalogue::within(cls, &needs, &hit.narrowed_by, |cls| {
            apply_effect(sc, spec, &hit.operands, cls, facts, env)
        });
        mapped |= placed;
    }
    // An entry that says only "benign" classifies the program: it is placed, and it
    // carries no tuple (an empty classified entry suppresses `unknown`).
    if hit.effects.is_empty() {
        mapped = true;
    }

    // An option the entries do not list, before a subcommand, stops the match at
    // the bare program (D-5): when that program placed the command, it is still
    // unreadable and says so — which also gives it its located unknown tuples.
    // (When nothing placed it, the caller's own gap says it already.)
    if mapped && !lookup.unlisted_option.is_empty() {
        let needs = catalogue::one_of(&lookup.unlisted_option);
        catalogue::within(cls, &needs, &[], |cls| {
            add_unknown(
                cls,
                9,
                format!(
                    "{}: an option before the subcommand is not a listed global flag",
                    sc.program
                ),
                &sc.raw,
            );
        });
    }

    let mut fallback = Classification::default();
    record_unmapped(sc, &mut fallback, facts, env, chain_level);
    cls.provenance.fallbacks.push(Fallback {
        stands_for: hit.stands_for.clone(),
        items: fallback,
    });
    mapped
}

/// One effect of a merged program hit. `false` when it declined — an
/// infrastructure command with no mutating word is not placed by it.
fn apply_effect(
    sc: &SimpleCommand,
    spec: &catalogue::EffectSpec,
    operands: &[(String, Vec<MergedSelector>)],
    cls: &mut Classification,
    facts: &FactSet,
    env: &PathEnv,
) -> bool {
    let program = sc.program.as_str();
    if spec.verb == VERB_MUTATION {
        return apply_mutation(sc, &spec.target_class, cls, facts);
    }
    if spec.verb == VERB_STATEMENT {
        let selectors = operands
            .iter()
            .find(|(role, _)| role == "statement")
            .map(|(_, selectors)| selectors.as_slice())
            .unwrap_or(&[]);
        let statement = statement_of(sc, selectors);
        match classify_sql(&statement) {
            Some(verb) => add_effect(cls, verb, &spec.target_class, attrs_of(&[])),
            None => add_unknown(cls, 9, format!("{program}: unparsed statement"), &sc.raw),
        }
        return true;
    }
    // A network tuple names the program that reached out, so a rule can tell `curl`
    // from `wget` (AC-1).
    let attrs = if spec.verb == "network_egress" {
        attrs_of(&[("program", serde_json::Value::from(program))])
    } else {
        attrs_of(&[])
    };
    let Some(role) = spec.target_class.strip_prefix('@') else {
        // A fixed class is used as is.
        add_effect(cls, &spec.verb, &spec.target_class, attrs);
        return true;
    };
    // `@<role>`: the class is resolved per call from the values under that role.
    let role = if role == "target" { "file" } else { role };
    let selectors = operands
        .iter()
        .find(|(name, _)| name == role)
        .map(|(_, selectors)| selectors.as_slice())
        .unwrap_or(&[]);
    for (value, origin) in role_values(sc, selectors) {
        let needs = catalogue::compose(
            &catalogue::always(),
            &catalogue::one_of(std::slice::from_ref(&origin)),
        );
        catalogue::within(cls, &needs, &[], |cls| match role {
            "file" => add_file_effect(cls, &spec.verb, &value, facts, env),
            "url" | "host" => {
                let url = if role == "url" {
                    super::parse_url(&value)
                } else {
                    super::host_url(&value)
                };
                if let Some(url) = url {
                    let host = url.host.clone();
                    cls.urls.push(url);
                    add_effect(cls, &spec.verb, "network_host", attrs.clone());
                    super::add_host_classes(cls, &spec.verb, &host, env, &attrs);
                }
            }
            _ => {}
        });
    }
    true
}

/// A `@file` operand: a URL is a URL, a `read` keeps only a value that looks like
/// a path (a separator, or a class other than `workspace_file` — so a `grep`
/// pattern is not read as a file), and anything else resolves like `rm`'s operand.
fn add_file_effect(
    cls: &mut Classification,
    verb: &str,
    value: &str,
    facts: &FactSet,
    env: &PathEnv,
) {
    if let Some(url) = super::parse_url(value) {
        if !cls.urls.contains(&url) {
            cls.urls.push(url);
        }
        return;
    }
    if verb == "read" {
        let classes = path::resolve_all(value, env, facts);
        let looks_like_a_path = value.contains('/')
            || value.contains('\\')
            || classes.iter().any(|c| c.class.0 != "workspace_file");
        if !classes.is_empty() && !looks_like_a_path {
            return;
        }
    }
    add_path_effect(cls, verb, value, facts, env);
}

fn classify_find(
    sc: &SimpleCommand,
    cls: &mut Classification,
    facts: &FactSet,
    env: &PathEnv,
) -> bool {
    let root = operands(sc).first().cloned().unwrap_or_else(|| {
        if env.cwd.is_empty() {
            ".".to_string()
        } else {
            env.cwd.clone()
        }
    });
    if sc.argv.iter().any(|a| a == "-delete") {
        add_path_effect(cls, "delete", &root, facts, env);
        return true;
    }
    let Some(index) = sc.argv.iter().position(|a| a == "-exec" || a == "-execdir") else {
        return false;
    };
    // `find … -exec CMD {} \;` — the inner command IS classifiable, and `{}`
    // stands for whatever the search found, so it resolves to the search root.
    // The oracle stops here and reports shape 8 unconditionally; the PRD's
    // shape-8 row is narrower than that ("whose inner command itself hits 1–7"),
    // so an inner command that reads cleanly gets its tuples.
    let inner_tokens: Vec<String> = sc.argv[index + 1..]
        .iter()
        .take_while(|a| a.as_str() != ";" && a.as_str() != "+")
        .map(|a| if a == "{}" { root.clone() } else { a.clone() })
        .collect();
    if inner_tokens.is_empty() {
        add_unknown(
            cls,
            8,
            "find -exec with no inner command".to_string(),
            &sc.raw,
        );
        return true;
    }
    let stripped = build_simple(&inner_tokens);
    let inner = stripped.command;
    for (_, reason) in stripped.shapes {
        add_unknown(cls, 8, format!("via find -exec: {reason}"), &sc.raw);
    }
    let inner_shapes = detect_shapes(&inner, &inner_tokens, "", "");
    for (_, reason) in &inner_shapes {
        add_unknown(cls, 8, format!("via find -exec: {reason}"), &sc.raw);
    }
    cls.simple.extend(stripped.wrappers);
    cls.simple.push(inner.clone());
    if !classify_simple(&inner, cls, facts, env, false) {
        record_unmapped(&inner, cls, facts, env, false);
    }
    true
}

fn classify_git(
    sc: &SimpleCommand,
    sub: &str,
    cls: &mut Classification,
    facts: &FactSet,
    env: &PathEnv,
) -> bool {
    let cwd = if env.cwd.is_empty() {
        ".".to_string()
    } else {
        env.cwd.clone()
    };
    if sub == "clean"
        && sc.argv.iter().any(|a| {
            a.starts_with('-')
                && ['f', 'd', 'x']
                    .iter()
                    .all(|c| a.trim_start_matches('-').contains(*c))
        })
    {
        add_path_effect(cls, "delete", &cwd, facts, env);
        return true;
    }
    if sub == "reset" && sc.argv.iter().any(|a| a == "--hard") {
        add_path_effect(cls, "delete", &cwd, facts, env);
        return true;
    }
    if sub == "push" {
        let forced = sc
            .argv
            .iter()
            .any(|a| matches!(a.as_str(), "-f" | "--force" | "--force-with-lease"));
        let branch = operands(sc).into_iter().nth(2).unwrap_or_default();
        let protected = branch
            .split('/')
            .next()
            .is_some_and(|head| !branch.is_empty() && PROTECTED_BRANCHES.contains(&head));
        let attrs = attrs_of(&[
            ("force", serde_json::Value::Bool(forced)),
            ("branch", serde_json::Value::from(branch.as_str())),
        ]);
        // The PRD writes this row as `write × vcs_remote`, with a `→ delete` for
        // a forced push onto a protected branch. The arrow reads as substitution;
        // D-15 says otherwise, and the PRD's own 2026-09-03 amendment settles it:
        // BOTH tuples. Substituting is what makes "no push without a passing test
        // run" — the natural `write × vcs_remote` trigger — fail to match the
        // single most destructive push there is.
        add_effect(cls, "write", "vcs_remote", attrs.clone());
        if forced && protected {
            add_effect(cls, "delete", "vcs_remote", attrs);
        }
        return true;
    }
    if sub == "tag" {
        add_effect(cls, "write", "vcs_remote", attrs_of(&[]));
        return true;
    }
    false
}

// ── Chain-level classification ───────────────────────────────────────

/// `>`, `>>`, `2>` per the PRD's redirection row.
fn apply_redirects(sc: &SimpleCommand, cls: &mut Classification, facts: &FactSet, env: &PathEnv) {
    for (op, target) in &sc.redirects {
        // `<` reads its source; a heredoc (`<<`, `<<<`) is not a file (D-I16-30).
        if op == "<" {
            if !is(target, NULL_DEVICE) && is_resolvable(target) {
                add_path_effect(cls, "read", target, facts, env);
            }
            continue;
        }
        if !matches!(op.as_str(), ">" | ">>" | "2>" | "2>>") {
            continue;
        }
        if is(target, NULL_DEVICE) {
            continue;
        }
        if !is_literal(target) {
            continue; // already reported as shape 10 by `detect_shapes`
        }
        let classes = path::resolve_all(target, env, facts);
        if classes.is_empty() {
            add_unknown(
                cls,
                10,
                format!("redirection target does not resolve: {target:?}"),
                target,
            );
            continue;
        }
        for found in classes {
            let needs = catalogue::one_of(&found.origins);
            catalogue::within(cls, &needs, &[], |cls| {
                record_path(cls, target, &found.class);
                add_effect(cls, "write", &found.class.0, attrs_of(&[]));
                // A truncating `>` onto a data store is also a delete — `> /data/x`
                // has to fire SA1, and only this branch makes it.
                if op == ">" && found.class.0 == "data_store" {
                    add_effect(cls, "delete", "data_store", attrs_of(&[]));
                }
            });
        }
    }
}

/// Shape 1's parse half: does this text parse as bash at all?
///
/// The parser is built here, per call, and dropped: it is derived from nothing
/// and retained across nothing, which is the shape `ci/check-engine-purity.py`
/// rule `global-state` asks for. A grammar this build cannot load answers
/// `false` — a missing parser must not turn every command into a coverage gap.
fn has_parse_error(command: &str) -> bool {
    let mut parser = tree_sitter::Parser::new();
    if parser
        .set_language(&tree_sitter_bash::LANGUAGE.into())
        .is_err()
    {
        return false;
    }
    parser
        .parse(command, None)
        .is_some_and(|tree| tree.root_node().has_error())
}

/// Classify one shell command line into effect tuples plus coverage gaps.
pub fn classify_command(command: &str, facts: &FactSet, env: &PathEnv) -> Classification {
    let mut cls = Classification::default();
    classify_into(command, &mut cls, facts, env);
    cls
}

/// [`classify_command`], writing into a classification the caller already owns —
/// the entry point has already put the tool's own paths and URLs in it.
pub fn classify_into(command: &str, cls: &mut Classification, facts: &FactSet, env: &PathEnv) {
    let text = normalise(command);
    if text.chars().count() > MAX_COMMAND_CHARS {
        add_unknown(
            cls,
            1,
            format!("command longer than {MAX_COMMAND_CHARS} characters"),
            "",
        );
        return;
    }
    let Ok(tokens) = tokenise(&text) else {
        add_unknown(
            cls,
            1,
            "unreadable command: unbalanced quote".to_string(),
            "",
        );
        return;
    };
    if has_parse_error(&text) {
        add_unknown(
            cls,
            1,
            "tree-sitter-bash reports an ERROR or MISSING node".to_string(),
            "",
        );
        return;
    }

    let parts = split_chain(tokens);
    let built: Vec<Built> = parts
        .into_iter()
        .map(|part| {
            let stripped = build_simple(&part.tokens);
            Built {
                command: stripped.command,
                wrappers: stripped.wrappers,
                shapes: stripped.shapes,
                via_runner: stripped.via_runner,
                sep: part.sep,
                tokens: part.tokens,
            }
        })
        .collect();

    for index in 0..built.len() {
        let Built {
            command: sc,
            wrappers,
            shapes: entry_shapes,
            via_runner,
            sep,
            tokens,
        } = &built[index];
        // Outermost first, then what it ran. EVERY simple command the walk
        // visits is recorded, whether or not the table could place it.
        cls.simple.extend(wrappers.iter().cloned());
        cls.simple.push(sc.clone());
        let next_program = built
            .get(index + 1)
            .map(|next| next.command.program.as_str())
            .unwrap_or("");
        let mut shapes = entry_shapes.clone();
        shapes.extend(detect_shapes(sc, tokens, sep, next_program));
        for (shape, reason) in shapes {
            // Shape 8 is shapes 1–7 seen THROUGH a runner, so it replaces them.
            if *via_runner && (1..=7).contains(&shape) {
                add_unknown(cls, 8, format!("via a runner: {reason}"), &sc.raw);
            } else {
                add_unknown(cls, shape, reason, &sc.raw);
            }
        }

        // `curl … | sh` — the pipe target is opaque code, whatever fed it.
        if sep == "|" && is(&sc.program, INTERPRETERS) {
            add_effect(cls, "execute", "opaque_code", attrs_of(&[]));
        }

        apply_redirects(sc, cls, facts, env);

        if sc.program.is_empty() {
            continue;
        }
        if !classify_simple(sc, cls, facts, env, true) {
            // Shape 9: a program neither a code row nor a catalogue entry places.
            // `execute × shell` is the tuple, and it counts as unknown for
            // effect-class atoms.
            record_unmapped(sc, cls, facts, env, true);
        }
    }

    detect_script_then_run(
        &built.iter().map(|b| b.command.clone()).collect::<Vec<_>>(),
        cls,
    );
}

/// Shape 5 — write a file, make it executable, run it, all in one command.
///
/// The honest rule, and deliberately blunt: any chain containing `chmod +x` is
/// unknown. Working out WHICH file was written, and whether it is the one that
/// then runs, takes a data-flow pass over redirects, `cp`/`mv`/`tee` operands
/// and `chmod` modes — a guess that overlaps shape 9 and that a reviewer cannot
/// check against the PRD. The `chmod +x` is the observable part of the shape, so
/// it is the whole of the rule.
fn detect_script_then_run(built: &[SimpleCommand], cls: &mut Classification) {
    for sc in built {
        if sc.program != "chmod" {
            continue;
        }
        let mode = operands(sc).first().cloned().unwrap_or_default();
        if mode.contains('x') {
            add_unknown(
                cls,
                5,
                format!("chmod {mode}: a file may be made executable and then run"),
                &sc.raw,
            );
        }
    }
}

#[cfg(test)]
mod tests {
    use super::super::catalogue::fixtures::seed_r1;
    use super::*;

    /// The seed-r1 catalogue on an empty host context: the tables, as data.
    fn seeded() -> PathEnv<'static> {
        PathEnv::default().with_catalogue(Some(seed_r1()))
    }

    fn classify(command: &str) -> Classification {
        classify_command(command, &FactSet::default(), &seeded())
    }

    fn tuples(cls: &Classification) -> Vec<String> {
        cls.effects
            .iter()
            .map(|e| format!("{}x{}", e.verb.0, e.target_class.0))
            .collect()
    }

    fn shapes(cls: &Classification) -> Vec<i64> {
        let mut shapes: Vec<i64> = cls.unknown.iter().map(|u| u.shape).collect();
        shapes.sort_unstable();
        shapes
    }

    /// D-15, vault issue #34, spike amendment 7. **The mandatory test.**
    #[test]
    fn one_unmapped_sibling_does_not_erase_a_confident_tuple() {
        let cls = classify("rm -rf /data/warehouse/x && $UNKNOWN_CMD");
        assert!(
            tuples(&cls).contains(&"deletexdata_store".to_string()),
            "the rm's confident tuple SURVIVES the unmapped sibling: {:?}",
            tuples(&cls)
        );
        assert_eq!(
            shapes(&cls),
            vec![2, 9],
            "and the gap is reported beside it"
        );
    }

    fn programs(cls: &Classification) -> Vec<String> {
        cls.simple.iter().map(|s| s.program.clone()).collect()
    }

    /// D-15 again, over `simple` / `paths` / `urls` rather than over `effects`:
    /// unknown-ness never erases what the walk observed.
    #[test]
    fn an_unclassifiable_command_still_contributes_what_it_named() {
        let cls = classify("rm -rf /data/warehouse/x && cat /data/warehouse/notes.sql");
        assert_eq!(
            programs(&cls),
            vec!["rm", "cat"],
            "BOTH commands are recorded"
        );
        assert!(
            tuples(&cls).contains(&"deletexdata_store".to_string()),
            "the mapped command keeps its tuple"
        );
        assert_eq!(shapes(&cls), vec![9], "and the unmapped one keeps its gap");
        let named: Vec<&str> = cls.paths.iter().map(|p| p.value.as_str()).collect();
        assert!(
            named.contains(&"/data/warehouse/notes.sql"),
            "the unclassified `cat` still named a data store: {named:?}"
        );
    }

    /// `command.program` must see the runner AND what ran inside it. Keeping
    /// only the inner silently breaks a rule written against `docker`; keeping
    /// only the outer is the prefix-approval the PRD forbids.
    #[test]
    fn every_layer_of_a_wrapped_command_is_recorded_outermost_first() {
        let cls = classify("docker exec -it api rm -rf /data/warehouse/orders.db");
        assert_eq!(programs(&cls), vec!["docker", "rm"]);
        let cls = classify("env FOO=1 timeout 30 command rm -rf /data/warehouse/x");
        assert_eq!(programs(&cls), vec!["env", "timeout", "command", "rm"]);
        // An escalator recurses rather than stripping, and its inner command is
        // just as much a command the walk visited.
        let cls = classify("sudo rm -rf /data/warehouse/orders.db");
        assert_eq!(programs(&cls), vec!["sudo", "rm"]);
    }

    /// A bare relative token is not a path. Without this, `5` and every
    /// subcommand name file as `workspace_file` and a rule reading
    /// `path.class == workspace_file` fires on all of them.
    #[test]
    fn a_flag_argument_of_an_unclassified_command_is_not_filed_as_a_path() {
        let cls = classify("head -n 5 app.log");
        assert!(
            cls.paths.is_empty(),
            "neither `5` nor `app.log` is a path claim: {:?}",
            cls.paths
        );
        let cls = classify("grep -r secret /data/warehouse");
        let named: Vec<&str> = cls.paths.iter().map(|p| p.value.as_str()).collect();
        assert_eq!(named, vec!["/data/warehouse"], "but the real path is");
    }

    #[test]
    fn a_path_is_recorded_as_declared_and_never_as_resolved() {
        let env = PathEnv {
            home: "/home/dev".to_string(),
            cwd: "/home/dev/proj".to_string(),
            ..seeded()
        };
        let cls = classify_command("rm -rf ~/proj/stale", &FactSet::default(), &env);
        assert_eq!(cls.paths.len(), 1);
        assert_eq!(
            cls.paths[0].value, "~/proj/stale",
            "the VALUE is what the action declared"
        );
        assert_eq!(
            cls.paths[0].class.0, "workspace_file",
            "the CLASS is resolved"
        );
    }

    #[test]
    fn a_url_an_unmapped_command_names_is_still_recorded() {
        let cls = classify("weirdtool --push https://api.example.com/v1");
        assert_eq!(
            cls.urls.iter().map(|u| u.host.as_str()).collect::<Vec<_>>(),
            vec!["api.example.com"]
        );
    }

    #[test]
    fn a_mapped_command_survives_an_unmapped_one_in_a_pipeline() {
        let cls = classify("rm -rf /data/warehouse/x | weirdtool");
        assert!(tuples(&cls).contains(&"deletexdata_store".to_string()));
        assert!(!cls.unknown.is_empty());
    }

    #[test]
    fn normalisation_happens_before_the_program_name_is_read() {
        // A zero-width joiner inside the program name is stripped, so `rm` is
        // still `rm`; a Cyrillic homoglyph is not, so it is shape 7.
        assert_eq!(
            shapes(&classify("r\u{200b}m -rf /data/warehouse/x")),
            Vec::<i64>::new()
        );
        assert!(shapes(&classify("rм -rf /data/warehouse/x")).contains(&7));
    }

    #[test]
    fn a_runner_is_never_prefix_approved() {
        let cls = classify("docker exec -it api rm -rf /data/warehouse/orders.db");
        assert!(tuples(&cls).contains(&"deletexdata_store".to_string()));
    }

    #[test]
    fn a_wrapper_option_argument_is_not_the_inner_program() {
        let cls = classify("nice -n 19 rm -rf /data/warehouse/orders.db");
        assert_eq!(tuples(&cls), vec!["deletexdata_store"]);
        assert!(cls.unknown.is_empty(), "no invented coverage gap");
    }

    /// The three places this classifier deliberately knows MORE than the oracle,
    /// each of which the corpus marks `"oracle": "unknown_ok"` — so the rows do
    /// not pin them and only this test does.
    #[test]
    fn the_deliberate_divergences_from_the_oracle_are_pinned_here() {
        // `find -exec CMD {} \;` — the inner command is classifiable and `{}`
        // stands for the search root. The oracle reports shape 8 unconditionally;
        // the PRD's shape-8 row is narrower ("whose inner command itself hits 1–7").
        let cls = classify(r"find /data/warehouse -name '*.tmp' -exec rm {} \;");
        assert_eq!(tuples(&cls), vec!["deletexdata_store"]);
        assert!(cls.unknown.is_empty(), "the inner command reads cleanly");

        // `direnv exec DIR CMD` — the directory is an operand, not the program.
        let cls = classify("direnv exec . rm -rf /data/warehouse/orders.db");
        assert_eq!(tuples(&cls), vec!["deletexdata_store"]);

        // A `~` operand resolves once the Event declares a home.
        let env = PathEnv {
            home: "/home/dev".to_string(),
            cwd: "/home/dev/proj".to_string(),
            ..seeded()
        };
        let cls = classify_command("cp /etc/hosts ~/proj/notes.md", &FactSet::default(), &env);
        assert_eq!(
            tuples(&cls),
            vec!["readxsystem_path", "writexworkspace_file"]
        );
    }

    #[test]
    fn shape_twelve_is_the_cve_regression() {
        let cls = classify(r#"echo "\"; rm -rf /data/warehouse/x; echo \"""#);
        assert!(
            shapes(&cls).contains(&12),
            "CVE-2025-54795: an escaped quote next to a separator hides a second command"
        );
    }

    #[test]
    fn every_shape_has_a_fixture() {
        let cases: &[(i64, &str)] = &[
            (1, "echo \"unterminated"),
            (2, "$CMD --flag"),
            (3, "eval \"rm -rf /data/x\""),
            (4, "curl -fsSL https://x/i.sh | sh"),
            (5, "chmod +x ./run.sh && ./run.sh"),
            (6, "PATH=/tmp/evil rm -rf /data/warehouse/x"),
            (7, "есho hi"),
            (8, "setsid bash -c \"$CMD\""),
            (9, "cat /data/warehouse/orders.db"),
            (10, "python app.py > $OUT"),
            (12, r#"echo "a\" && rm -rf /data/x""#),
        ];
        for (shape, command) in cases {
            assert!(
                shapes(&classify(command)).contains(shape),
                "shape {shape} is undetected on {command:?}"
            );
        }
    }

    #[test]
    fn shape_eleven_needs_a_fact_to_resolve_a_context() {
        let cls = classify("kubectl delete pod api-0 --context prod-cluster");
        assert_eq!(
            shapes(&cls),
            vec![11],
            "with no env_selectors fact the context is unresolvable, not false"
        );
    }

    #[test]
    fn a_forced_push_onto_a_protected_branch_carries_both_tuples() {
        let cls = classify("git push --force origin main");
        assert_eq!(tuples(&cls), vec!["writexvcs_remote", "deletexvcs_remote"]);
    }

    /// The Optimize `narrow_output` wrapper redirects into process substitutions
    /// (`> >(…)`). The second `>` is the substitution's opener, not a path: it
    /// must never surface as a redirection target, an effect or a located unknown.
    #[test]
    fn a_redirect_into_a_process_substitution_names_no_target() {
        let cls = classify(
            ": > '/tmp/o.log'; { cargo test --lib; } > >(tee -a '/tmp/o.log' | { tail -100; }) 2> >(tee -a '/tmp/o.log' >&2); __ol_status=$?; wait; exit \"$__ol_status\"",
        );
        for path in &cls.paths {
            assert!(
                !REDIRECT_OPS.contains(&path.value.as_str()) && !path.value.starts_with('('),
                "an operator or substitution opener was emitted as a path target: {path:?}"
            );
        }
    }

    #[test]
    fn a_truncating_redirect_onto_a_data_store_is_also_a_delete() {
        let cls = classify("python app.py > /data/warehouse/orders.db");
        assert!(tuples(&cls).contains(&"deletexdata_store".to_string()));
    }
}