@taliesinb/mash 0.0.0-stage → 0.1.0

package/dist/src/analysis/analyze.js

@@ -0,0 +1,1406 @@
+/**
+ * Static analysis by abstract interpretation.
+ *
+ * Walks the AST with an abstract environment (variables → {@link AValue}s,
+ * abstract cwd, positional parameters), expands every simple command's words
+ * abstractly, applies the same behavior definitions the VM uses at runtime,
+ * and checks the predicted effects against the policy.
+ *
+ * Each command site gets a reachability: `must` when it runs on every
+ * execution that does not terminate earlier (not under a condition, loop body
+ * that may not run, `&&`/`||`, case arm, or uncalled function), else `may`.
+ * The report's verdict is `reject` when some `must` site has a definite
+ * policy violation — the snippet would certainly violate the policy if it
+ * gets that far — and `check-at-runtime` when violations are only possible.
+ */
+import * as os from 'node:os';
+import * as fs from 'node:fs';
+import { parse, lineColumn, literalOf } from "../parser/parser.js";
+import { basename, resolvePath } from "../behaviors/registry.js";
+import { describeEffect, withVia } from "../policy/effects.js";
+import { checkCommandName, checkEffects, checkExecEffects, shapesOf, worstVerdict } from "../policy/policy.js";
+import { braceExpand } from "../vm/expand.js";
+import { hasGlobChars, quotePattern, removePrefix, removeSuffix, replacePattern } from "../vm/pattern.js";
+import { BUILTINS } from "../vm/builtins.js";
+import { evaluateArith } from "../vm/arith.js";
+import { refineOutput } from "./outputs.js";
+import { AFs } from "./fs.js";
+import { concat, concrete, describe, hole, guardEmpty, isFullyKnown, isNameLike, isSlashFree, join, known, typeOf, unknownString, } from "./value.js";
+class AEnv {
+    vars = new Map();
+    cwd;
+    positional;
+    terminated = false;
+    functions = new Map();
+    /** What the snippet has done to the file system on this path. */
+    fs = new AFs();
+    /** Shared analysis flags (`mayHaveCreated` affects file-system lookups). */
+    flags = { mayHaveCreated: false };
+    constructor(cwd, positional) {
+        this.cwd = cwd;
+        this.positional = positional;
+    }
+    clone() {
+        const e = new AEnv(this.cwd, [...this.positional]);
+        for (const [k, v] of this.vars)
+            e.vars.set(k, { ...v, array: v.array ? [...v.array] : undefined });
+        e.terminated = this.terminated;
+        e.functions = new Map(this.functions);
+        e.fs = this.fs.clone();
+        e.flags = this.flags;
+        return e;
+    }
+    /** The file-system state of a concrete path on this path. */
+    fsState(p) {
+        return this.fs.lookup(p, this.flags.mayHaveCreated);
+    }
+    /** Join two environments (control-flow merge). */
+    static join(a, b) {
+        if (a.terminated)
+            return b.clone();
+        if (b.terminated)
+            return a.clone();
+        const e = new AEnv(join(a.cwd, b.cwd), a.positional.length === b.positional.length ? a.positional.map((f, i) => ({ value: join(f.value, b.positional[i].value), spread: f.spread || b.positional[i].spread })) : [{ value: unknownString('$@'), spread: true }]);
+        const names = new Set([...a.vars.keys(), ...b.vars.keys()]);
+        for (const n of names) {
+            const x = a.vars.get(n);
+            const y = b.vars.get(n);
+            if (x && y)
+                e.vars.set(n, { value: join(x.value, y.value), exported: x.exported || y.exported, array: x.array && y.array && x.array.length === y.array.length ? x.array.map((v, i) => join(v, y.array[i])) : x.array || y.array ? [unknownString(`${n}[@]`)] : undefined, unsetMaybe: x.unsetMaybe || y.unsetMaybe });
+            else {
+                const v = (x ?? y);
+                e.vars.set(n, { ...v, value: join(v.value, known('')), unsetMaybe: true });
+            }
+        }
+        for (const [k, f] of b.functions)
+            e.functions.set(k, f);
+        e.flags = a.flags;
+        e.fs = AFs.join(a.fs, b.fs, a.flags.mayHaveCreated);
+        return e;
+    }
+}
+const MAX_CALL_DEPTH = 6;
+export function analyzeScript(script, source, opts) {
+    return new Analyzer(source, opts).run(script);
+}
+/** Parse and analyze in one step. */
+export function analyzeSource(source, opts) {
+    return analyzeScript(parse(source), source, opts);
+}
+const MAX_INLINE_BYTES = 256 * 1024;
+class Analyzer {
+    sites = new Map();
+    source;
+    opts;
+    shared;
+    /** Where recorded sites go: the report, or the inlining analyzer (adding provenance). */
+    emit;
+    lastOutput = null;
+    /** Typed stdout of each external simple command (by node id), for `$(a | b)`. */
+    outputs = new Map();
+    constructor(source, opts, parent) {
+        this.source = source;
+        this.opts = opts;
+        this.shared = parent?.shared ?? { calledFunctions: new Set(), mayHaveCreated: false, written: new Set(), mayHaveWritten: false, nextId: 1_500_000_000 };
+        this.emit = parent?.emit ?? ((site) => {
+            const existing = this.sites.get(site.nodeId);
+            const rank = { must: 2, happy: 1, may: 0 };
+            if (existing && rank[existing.reach] > rank[site.reach])
+                site.reach = existing.reach;
+            this.sites.set(site.nodeId, site);
+        });
+    }
+    /**
+     * `rm -f` of a path that is missing (on disk, after what the snippet did)
+     * does nothing: not a violation. If it may exist, it is only possibly one.
+     */
+    missingOk(f, env) {
+        const e = f.effect;
+        if (f.verdict !== 'deny' || e.kind !== 'delete' || !e.ifExists || this.opts.policy.missingDeletes !== 'allow')
+            return f;
+        const paths = e.path.alts.map((a) => concrete(normalizeKnownPath({ alts: [a] })));
+        const states = paths.map((p) => (p === undefined ? 'unknown' : env.fsState(p)));
+        if (states.every((s) => s === 'absent'))
+            return { ...f, verdict: 'allow', reason: 'delete: nothing to delete (missing path, -f)' };
+        if (states.every((s) => s === 'dir' || s === 'file'))
+            return f;
+        return { ...f, verdict: 'unknown', reason: `${f.reason} (if it exists)` };
+    }
+    /** Update the simulated file system with a command's effects (on the path where it succeeds). */
+    applyFs(env, effects, argv0) {
+        const name = argv0 === undefined ? '' : basename(argv0);
+        for (const e of effects) {
+            if (e.kind !== 'write' && e.kind !== 'delete')
+                continue;
+            const c = e.maybe ? undefined : concrete(normalizeKnownPath(e.path));
+            if (c === undefined) {
+                env.fs.fuzz(shapesOf(e.path));
+                continue;
+            }
+            if (e.kind === 'delete') {
+                env.fs.remove(c, 'unknown');
+                continue;
+            }
+            const up = c.slice(0, c.lastIndexOf('/')) || '/';
+            env.fs.mkdirs(up);
+            if (name === 'mkdir' || (e.recursive && DIR_CREATORS.has(name)))
+                env.fs.mkdirs(c);
+            else if (e.recursive) {
+                // chmod -R and the like: the path keeps its kind
+            }
+            else if (env.fsState(c) !== 'dir')
+                env.fs.set(c, name === 'mv' || name === 'ln' ? 'unknown' : 'file');
+        }
+    }
+    /**
+     * What a successful or failed test tells about the file system:
+     * `[ -d x ]`, `test -f x`, `[[ -e x ]]`, negated with `!`.
+     */
+    refine(cmd, env, success) {
+        if (!cmd)
+            return;
+        const apply = (op, w, ok) => {
+            if (op !== '-d' && op !== '-f' && op !== '-e')
+                return;
+            if (hasSubstitution(w))
+                return; // re-expanding would analyze it again
+            const c = concrete(normalizeKnownPath(resolvePath(this.stringValue(w, env, NO_CTX), env.cwd)));
+            if (c === undefined || !c.startsWith('/'))
+                return;
+            const cur = env.fsState(c);
+            if (ok) {
+                if (op === '-d')
+                    env.fs.mkdirs(c);
+                else if (op === '-f') {
+                    env.fs.mkdirs(c.slice(0, c.lastIndexOf('/')) || '/');
+                    env.fs.set(c, 'file');
+                }
+                else if (cur === 'absent')
+                    env.fs.set(c, 'unknown');
+            }
+            else if (op === '-e')
+                env.fs.remove(c, 'absent');
+            else if (cur === (op === '-d' ? 'dir' : 'file'))
+                env.fs.set(c, 'unknown');
+        };
+        switch (cmd.type) {
+            case 'Pipeline':
+                if (cmd.stages.length === 1)
+                    this.refine(cmd.stages[0], env, cmd.negated ? !success : success);
+                return;
+            case 'CondCommand': {
+                let e = cmd.expr;
+                let ok = success;
+                while (e.type === 'CondNot' || e.type === 'CondGroup') {
+                    if (e.type === 'CondNot')
+                        ok = !ok;
+                    e = e.type === 'CondNot' ? e.operand : e.expr;
+                }
+                if (e.type === 'CondUnary')
+                    apply(e.op, e.operand, ok);
+                return;
+            }
+            case 'SimpleCommand': {
+                const words = cmd.words.filter((w) => w.type === 'Word');
+                if (words.length !== cmd.words.length || cmd.redirs.length > 0)
+                    return;
+                const lits = words.map((w) => literalOf(w));
+                let args = words.slice(1);
+                if (lits[0] === '[') {
+                    if (lits[lits.length - 1] !== ']')
+                        return;
+                    args = args.slice(0, -1);
+                }
+                else if (lits[0] !== 'test')
+                    return;
+                let ok = success;
+                if (args.length === 3 && literalOf(args[0]) === '!') {
+                    ok = !ok;
+                    args = args.slice(1);
+                }
+                if (args.length === 2) {
+                    const op = literalOf(args[0]);
+                    if (op)
+                        apply(op, args[1], ok);
+                }
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    /** Did the snippet (possibly) write `p` or a directory containing it? */
+    mayHaveChanged(p) {
+        if (this.shared.mayHaveWritten)
+            return true;
+        for (const w of this.shared.written)
+            if (p === w || p.startsWith(w === '/' ? '/' : w + '/'))
+                return true;
+        return false;
+    }
+    /**
+     * Analyze inlined code (`eval` text, a sourced file, a trap action) in the
+     * current environment. Its sites are reported at the inlining command, with
+     * each effect saying which inner command (and file line) it comes from.
+     */
+    inline(cmd, code, env, ctx, file) {
+        let script;
+        try {
+            script = parse(code, { firstId: this.shared.nextId });
+        }
+        catch {
+            return undefined;
+        }
+        this.shared.nextId = script.id + 1;
+        const outer = { span: cmd.span, line: this.line(cmd.span), text: this.text(cmd.span) };
+        const sub = new Analyzer(code, { ...this.opts, nested: true }, {
+            shared: this.shared,
+            emit: (site) => {
+                const hop = { text: site.text, line: site.line, ...(file ? { file } : {}) };
+                this.emit({
+                    ...site,
+                    ...outer,
+                    effects: site.effects.map((e) => withVia(e, hop)),
+                    findings: site.findings.map((f) => ({ ...f, effect: withVia(f.effect, hop) })),
+                });
+            },
+        });
+        return sub.list(script.body, env, { ...ctx, depth: ctx.depth + 1 });
+    }
+    run(script) {
+        const positional = (this.opts.positional ?? []).map((v) => ({ value: v, spread: false }));
+        const env = new AEnv(this.opts.cwd, positional);
+        env.flags = this.shared;
+        for (const [k, v] of Object.entries(this.opts.env))
+            env.vars.set(k, { value: known(v), exported: true });
+        const ctx = { reach: 'must', loop: false, subshell: false, cmdsubst: false, pipeline: false, background: false, stdin: 'unknown', depth: 0 };
+        const final = this.list(script.body, env, ctx);
+        // functions that were defined but never called: analyze as `may` with unknown arguments
+        if (!this.opts.nested) {
+            for (const [name, fn] of final.functions) {
+                // functions of sourced files are library code: only their calls are analyzed
+                if (this.shared.calledFunctions.has(name) || fn.owner !== this)
+                    continue;
+                const fenv = final.clone();
+                fenv.positional = [{ value: unknownString(`${name} args`), spread: true }];
+                fenv.terminated = false;
+                fn.owner.command(fn.def.body, fenv, { ...ctx, reach: 'may', function: name, depth: 1 });
+            }
+        }
+        const commands = [...this.sites.values()].sort((a, b) => a.span.start - b.span.start);
+        const violations = [];
+        for (const c of commands) {
+            for (const f of c.findings) {
+                if (f.verdict === 'allow')
+                    continue;
+                violations.push({ nodeId: c.nodeId, line: c.line, text: c.text, reach: c.reach, verdict: f.verdict, reason: f.reason, effect: describeEffect(f.effect), ...(f.effect.via ? { via: f.effect.via } : {}) });
+            }
+        }
+        const rejectOn = this.opts.rejectOn ?? ['must', 'happy'];
+        const definite = violations.filter((v) => v.verdict === 'deny' && rejectOn.includes(v.reach));
+        const verdict = definite.length > 0 ? 'reject' : violations.some((v) => v.verdict === 'deny' || v.verdict === 'unknown') ? 'check-at-runtime' : 'allow';
+        const variables = [];
+        for (const [name, v] of final.vars) {
+            if (name in this.opts.env && concrete(v.value) === this.opts.env[name])
+                continue;
+            variables.push({ name, value: v.array ? `(${v.array.map(describe).join(' ')})` : describe(v.value), type: v.array ? 'array' : typeOf(v.value) });
+        }
+        return {
+            commands,
+            variables,
+            functions: [...final.functions.keys()],
+            violations,
+            verdict,
+            reasons: definite.map((v) => `line ${v.line}: \`${v.text}\` would ${v.effect}: ${v.reason}`),
+        };
+    }
+    line(span) {
+        return lineColumn(this.source, span.start).line;
+    }
+    text(span) {
+        return this.source.slice(span.start, span.end);
+    }
+    // -------------------------------------------------------------------------
+    // Statements
+    // -------------------------------------------------------------------------
+    list(stmts, env, ctx) {
+        let e = env;
+        for (const s of stmts) {
+            if (e.terminated) {
+                // unreachable code: analyze as `may` for completeness, but it cannot be `must`
+                const dead = e.clone();
+                dead.terminated = false;
+                this.stmt(s, dead, { ...ctx, reach: 'may' });
+                continue;
+            }
+            e = this.stmt(s, e, ctx);
+        }
+        return e;
+    }
+    stmt(s, env, ctx) {
+        if (s.background) {
+            // file-system changes of a background job may or may not have happened yet: keep them (an approximation)
+            env.fs = this.command(s.command, env.clone(), { ...ctx, background: true, subshell: true }).fs;
+            return env;
+        }
+        return this.command(s.command, env, ctx);
+    }
+    command(cmd, env, ctx) {
+        switch (cmd.type) {
+            case 'SimpleCommand':
+                return this.simple(cmd, env, ctx);
+            case 'Pipeline': {
+                if (cmd.stages.length === 1) {
+                    env.fs = this.command(cmd.stages[0], env.clone(), ctx).fs;
+                    return env;
+                }
+                // stages run in subshells, concurrently; their file-system changes are kept (in stage order)
+                cmd.stages.forEach((st, i) => {
+                    env.fs = this.command(st, env.clone(), { ...ctx, pipeline: true, subshell: true, stdin: i > 0 ? 'pipe' : ctx.stdin }).fs;
+                });
+                return env;
+            }
+            case 'AndOr': {
+                // `a && b`: b runs on the happy path, in the state a left; after any
+                // `||`, or after a predicate (`test -f x && ...`), only conditionally.
+                // The state after the list joins every point where it can stop.
+                // `a && b || c` is `(a && b) || c`: track the states in which the
+                // list so far succeeded and failed; `&&` continues from the first,
+                // `||` from the second (tests refine them: `[ -d x ] || mkdir x`).
+                const outcome = (item, out, ok) => {
+                    const e = out.clone();
+                    this.refine(item, e, ok);
+                    return e;
+                };
+                const first = this.command(cmd.items[0], env, ctx);
+                let succ = outcome(cmd.items[0], first, true);
+                let fail = outcome(cmd.items[0], first, false);
+                let reach = ctx.reach === 'may' ? 'may' : 'happy';
+                for (let i = 1; i < cmd.items.length; i++) {
+                    const and = cmd.ops[i - 1] === '&&';
+                    if (!and || isPredicate(cmd.items[i - 1]))
+                        reach = 'may';
+                    const item = cmd.items[i];
+                    const out = this.command(item, and ? succ : fail, { ...ctx, reach });
+                    if (and) {
+                        fail = AEnv.join(fail, outcome(item, out, false));
+                        succ = outcome(item, out, true);
+                    }
+                    else {
+                        succ = AEnv.join(succ, outcome(item, out, true));
+                        fail = outcome(item, out, false);
+                    }
+                }
+                return AEnv.join(succ, fail);
+            }
+            case 'FunctionDef':
+                env.functions.set(cmd.name, { def: cmd, owner: this });
+                return env;
+            case 'Group':
+                return this.withRedirs(cmd.redirs, env, ctx, () => this.list(cmd.body, env, ctx));
+            case 'Subshell': {
+                this.withRedirs(cmd.redirs, env, ctx, () => {
+                    env.fs = this.list(cmd.body, env.clone(), { ...ctx, subshell: true }).fs;
+                    return env;
+                });
+                return env;
+            }
+            case 'If':
+                return this.withRedirs(cmd.redirs, env, ctx, () => {
+                    let e = env;
+                    const outs = [];
+                    for (let i = 0; i < cmd.clauses.length; i++) {
+                        const c = cmd.clauses[i];
+                        e = this.list(c.cond, e, i === 0 ? ctx : { ...ctx, reach: 'may' });
+                        const last = c.cond[c.cond.length - 1]?.command;
+                        const yes = e.clone();
+                        this.refine(last, yes, true);
+                        outs.push(this.list(c.body, yes, { ...ctx, reach: 'may' }));
+                        e = e.clone();
+                        this.refine(last, e, false);
+                    }
+                    outs.push(cmd.elseBody ? this.list(cmd.elseBody, e.clone(), { ...ctx, reach: 'may' }) : e);
+                    return outs.reduce((a, b) => AEnv.join(a, b));
+                });
+            case 'Loop':
+                return this.withRedirs(cmd.redirs, env, ctx, () => {
+                    // condition runs at least once; body may not
+                    let e = this.list(cmd.cond, env, ctx);
+                    const inner = { ...ctx, reach: 'may', loop: true };
+                    for (let pass = 0; pass < 2; pass++) {
+                        const after = this.list(cmd.body, e.clone(), inner);
+                        const again = this.list(cmd.cond, after, { ...ctx, reach: 'may', loop: true });
+                        e = AEnv.join(e, again);
+                    }
+                    e.terminated = false;
+                    return e;
+                });
+            case 'For':
+                return this.withRedirs(cmd.redirs, env, ctx, () => {
+                    const items = cmd.items === null ? env.positional : this.fields(cmd.items, env, ctx);
+                    const definitelyRuns = items.length > 0 && items.some((f) => !f.spread || f.atLeastOne);
+                    let value = items.length === 0 ? known('') : join(...items.map((f) => f.value));
+                    if (items.length === 0)
+                        value = unknownString(`$${cmd.variable}`);
+                    let e = env;
+                    const inner = { ...ctx, reach: definitelyRuns ? ctx.reach : 'may', loop: true };
+                    for (let pass = 0; pass < 2; pass++) {
+                        const body = e.clone();
+                        body.vars.set(cmd.variable, { value, exported: body.vars.get(cmd.variable)?.exported ?? false });
+                        const after = this.list(cmd.body, body, inner);
+                        e = pass === 0 && definitelyRuns ? after : AEnv.join(e, after);
+                    }
+                    e.terminated = false;
+                    return e;
+                });
+            case 'ArithFor':
+                return this.withRedirs(cmd.redirs, env, ctx, () => {
+                    let e = env;
+                    for (const ex of [cmd.init, cmd.cond, cmd.step])
+                        if (ex)
+                            this.arithAssignments(ex, e);
+                    for (let pass = 0; pass < 2; pass++) {
+                        const after = this.list(cmd.body, e.clone(), { ...ctx, reach: 'may', loop: true });
+                        e = AEnv.join(e, after);
+                    }
+                    e.terminated = false;
+                    return e;
+                });
+            case 'Select':
+                return this.withRedirs(cmd.redirs, env, ctx, () => {
+                    const items = cmd.items === null ? env.positional : this.fields(cmd.items, env, ctx);
+                    const e = env.clone();
+                    e.vars.set(cmd.variable, { value: items.length ? join(...items.map((f) => f.value)) : unknownString(cmd.variable), exported: false });
+                    return AEnv.join(env, this.list(cmd.body, e, { ...ctx, reach: 'may', loop: true }));
+                });
+            case 'Case':
+                return this.withRedirs(cmd.redirs, env, ctx, () => {
+                    const word = this.stringValue(cmd.word, env, ctx);
+                    const outs = [];
+                    let anyCatchAll = false;
+                    for (const item of cmd.items) {
+                        const pats = item.patterns.map((p) => this.stringValue(p, env, ctx));
+                        // a literal word and literal patterns: decide statically
+                        const w = concrete(word);
+                        if (w !== undefined && pats.every((p) => concrete(p) !== undefined)) {
+                            const { matchPattern } = patternModule;
+                            if (!item.patterns.some((p) => matchPattern(w, this.patternText(p, env, ctx))))
+                                continue;
+                            outs.push(this.list(item.body, env.clone(), ctx));
+                            anyCatchAll = true;
+                            if (item.terminator === ';;')
+                                break;
+                            continue;
+                        }
+                        if (pats.some((p) => concrete(p) === '*'))
+                            anyCatchAll = true;
+                        outs.push(this.list(item.body, env.clone(), { ...ctx, reach: 'may' }));
+                    }
+                    if (!anyCatchAll)
+                        outs.push(env);
+                    return outs.length === 0 ? env : outs.reduce((a, b) => AEnv.join(a, b));
+                });
+            case 'ArithCommand':
+                return this.withRedirs(cmd.redirs, env, ctx, () => {
+                    this.arithAssignments(cmd.expr, env);
+                    return env;
+                });
+            case 'CondCommand':
+                return this.withRedirs(cmd.redirs, env, ctx, () => {
+                    this.condWords(cmd.expr, env, ctx);
+                    return env;
+                });
+        }
+    }
+    withRedirs(redirs, env, ctx, fn) {
+        if (redirs.length > 0) {
+            const effects = this.redirectEffects(redirs, env, ctx);
+            if (effects.length > 0) {
+                const r = redirs[0];
+                this.record({
+                    nodeId: r.id, span: r.span, argv: [], kind: 'builtin', env, ctx, effects, complete: true, display: redirs.map((x) => this.text(x.span)).join(' '),
+                });
+            }
+        }
+        return fn();
+    }
+    condWords(e, env, ctx) {
+        switch (e.type) {
+            case 'CondWord':
+                this.stringValue(e.word, env, ctx);
+                break;
+            case 'CondUnary':
+                this.stringValue(e.operand, env, ctx);
+                break;
+            case 'CondBinary':
+                this.stringValue(e.left, env, ctx);
+                this.stringValue(e.right, env, ctx);
+                break;
+            case 'CondNot':
+                this.condWords(e.operand, env, ctx);
+                break;
+            case 'CondAndOr':
+                this.condWords(e.left, env, ctx);
+                this.condWords(e.right, env, ctx);
+                break;
+            case 'CondGroup':
+                this.condWords(e.expr, env, ctx);
+                break;
+        }
+    }
+    /** Variables assigned inside arithmetic become int-typed. */
+    arithAssignments(e, env) {
+        const visit = (x) => {
+            switch (x.type) {
+                case 'ArithAssign':
+                    env.vars.set(x.target.name, { value: hole('int', `$${x.target.name}`), exported: env.vars.get(x.target.name)?.exported ?? false });
+                    visit(x.value);
+                    break;
+                case 'ArithIncDec':
+                    env.vars.set(x.target.name, { value: hole('int', `$${x.target.name}`), exported: env.vars.get(x.target.name)?.exported ?? false });
+                    break;
+                case 'ArithBinary':
+                    visit(x.left);
+                    visit(x.right);
+                    break;
+                case 'ArithUnary':
+                    visit(x.operand);
+                    break;
+                case 'ArithTernary':
+                    visit(x.cond);
+                    visit(x.then);
+                    visit(x.else);
+                    break;
+                case 'ArithGroup':
+                    visit(x.expr);
+                    break;
+                default: break;
+            }
+        };
+        visit(e);
+    }
+    // -------------------------------------------------------------------------
+    // Simple commands
+    // -------------------------------------------------------------------------
+    simple(cmd, env, ctx) {
+        const argvFields = [];
+        const declAssigns = [];
+        for (const w of cmd.words) {
+            if (w.type === 'Assign') {
+                declAssigns.push(w);
+                argvFields.push({ value: known(this.text(w.span)), spread: false });
+            }
+            else
+                argvFields.push(...this.fields([w], env, ctx));
+        }
+        const redirEffects = this.redirectEffects(cmd.redirs, env, ctx);
+        if (argvFields.length === 0) {
+            for (const a of cmd.assigns)
+                this.assign(a, env, ctx, false);
+            if (redirEffects.length > 0 || cmd.assigns.some((a) => a.value?.type === 'Word' && a.value.parts.some((p) => p.type === 'CmdSubst'))) {
+                this.record({ nodeId: cmd.id, span: cmd.span, argv: [], kind: 'assignment', env, ctx, effects: redirEffects, complete: true });
+            }
+            return env;
+        }
+        const argv = argvFields.map((f) => f.value);
+        const spread = argvFields.some((f) => f.spread);
+        const name = concrete(argv[0]);
+        const prefixEnv = env.clone();
+        for (const a of cmd.assigns)
+            this.assign(a, prefixEnv, ctx, true);
+        if (name === undefined) {
+            this.record({
+                nodeId: cmd.id, span: cmd.span, argv, kind: 'unknown', env, ctx,
+                effects: [...redirEffects, { kind: 'unknown', detail: `command name ${describe(argv[0])} is not known statically` }], complete: false,
+            });
+            return env;
+        }
+        // functions (inline at the call site)
+        const fn = env.functions.get(name);
+        if (fn) {
+            this.shared.calledFunctions.add(name);
+            this.record({ nodeId: cmd.id, span: cmd.span, argv, kind: 'function', env, ctx, effects: redirEffects, complete: true });
+            if (ctx.depth >= MAX_CALL_DEPTH)
+                return env;
+            const fenv = prefixEnv.clone();
+            fenv.positional = argvFields.slice(1);
+            const out = fn.owner.command(fn.def.body, fenv, { ...ctx, function: name, depth: ctx.depth + 1 });
+            // positional parameters are restored after the call; `exit` inside the function terminates the caller too
+            out.positional = env.positional;
+            return out;
+        }
+        if (BUILTINS.has(name))
+            return this.builtin(name, cmd, argvFields, declAssigns, env, prefixEnv, ctx, redirEffects);
+        // external
+        const inv = this.invocation(argv, prefixEnv, ctx);
+        const r = this.opts.behaviors.analyze(inv);
+        const effects = [...redirEffects, ...r.effects];
+        if (r.complete === false)
+            this.shared.mayHaveCreated = true;
+        const nameFinding = checkCommandName(name, this.opts.policy);
+        this.record({ nodeId: cmd.id, span: cmd.span, argv, kind: 'external', env, ctx, effects, complete: r.complete !== false && !spread, extraFindings: nameFinding ? [nameFinding] : [] });
+        this.lastOutput = this.outputValue(refineOutput(inv, r.stdout), name);
+        this.outputs.set(cmd.id, this.lastOutput);
+        return env;
+    }
+    outputValue(info, name) {
+        if (!info)
+            return null;
+        if (info.value)
+            return info.value;
+        return hole(info.type, `$(${name})`, info.under ? { under: info.under } : {});
+    }
+    invocation(argv, env, ctx) {
+        return {
+            name: basename(concrete(argv[0]) ?? '?'),
+            argv,
+            cwd: env.cwd,
+            env: (n) => {
+                const v = env.vars.get(n);
+                if (v)
+                    return v.value;
+                return this.opts.envValues?.(n);
+            },
+            stdin: ctx.stdin,
+            mayHaveChanged: (p) => this.mayHaveChanged(p),
+        };
+    }
+    builtin(name, cmd, fields, declAssigns, env, prefixEnv, ctx, redirEffects) {
+        const argv = fields.map((f) => f.value);
+        const args = argv.slice(1);
+        const rec = (effects = [], complete = true) => {
+            this.record({ nodeId: cmd.id, span: cmd.span, argv, kind: 'builtin', env, ctx, effects: [...redirEffects, ...effects], complete });
+        };
+        switch (name) {
+            case 'cd':
+            case 'pushd': {
+                const target = args[0] ?? env.vars.get('HOME')?.value ?? unknownString('$HOME');
+                const t = concrete(target);
+                const dest = normalizeKnownPath(t === '-' ? (env.vars.get('OLDPWD')?.value ?? hole('path', '$OLDPWD')) : resolvePath(target, env.cwd));
+                rec([{ kind: 'chdir', path: dest }]);
+                // `cd` only changes directory if it succeeds: a concrete target that is
+                // not a directory now leaves the cwd as is; an unknown one may or may not
+                const d = concrete(dest);
+                const st = d === undefined ? 'unknown' : env.fsState(d);
+                // a concrete path that is not a directory (now, after what the snippet did): cd fails
+                if (st === 'absent' || st === 'file')
+                    return env;
+                env.vars.set('OLDPWD', { value: env.cwd, exported: true });
+                env.cwd = st === 'dir' ? dest : join(env.cwd, dest);
+                env.vars.set('PWD', { value: env.cwd, exported: true });
+                return env;
+            }
+            case 'popd':
+                rec();
+                env.cwd = hole('path', 'popd');
+                return env;
+            case 'export':
+            case 'declare':
+            case 'typeset':
+            case 'local':
+            case 'readonly': {
+                rec();
+                for (const a of declAssigns)
+                    this.assign(a, env, ctx, name === 'export');
+                for (const f of args) {
+                    const s = concrete(f);
+                    if (s === undefined || s.startsWith('-'))
+                        continue;
+                    const eq = s.indexOf('=');
+                    if (eq > 0 && !s.startsWith('\u0000')) {
+                        if (declAssigns.some((a) => this.text(a.span) === s))
+                            continue;
+                        env.vars.set(s.slice(0, eq), { value: known(s.slice(eq + 1)), exported: name === 'export' });
+                    }
+                    else if (name === 'export') {
+                        const v = env.vars.get(s);
+                        if (v)
+                            v.exported = true;
+                    }
+                }
+                return env;
+            }
+            case 'unset':
+                rec();
+                for (const a of args) {
+                    const s = concrete(a);
+                    if (s && !s.startsWith('-'))
+                        env.vars.delete(s);
+                }
+                return env;
+            case 'read':
+            case 'mapfile':
+            case 'readarray': {
+                rec();
+                const names = [];
+                for (let i = 0; i < args.length; i++) {
+                    const s = concrete(args[i]);
+                    if (s === undefined)
+                        continue;
+                    if (s === '-a' || (name !== 'read' && !s.startsWith('-'))) {
+                        const n = s === '-a' ? concrete(args[++i] ?? known('')) : s;
+                        if (n)
+                            env.vars.set(n, { value: unknownString(`$${n}`), array: [unknownString(`${n}[@]`)], exported: false });
+                        continue;
+                    }
+                    if (['-d', '-n', '-N', '-p', '-t', '-u', '-i', '-C', '-c', '-O', '-s'].includes(s)) {
+                        i++;
+                        continue;
+                    }
+                    if (s.startsWith('-'))
+                        continue;
+                    names.push(s);
+                }
+                if (name === 'read') {
+                    for (const n of names.length ? names : ['REPLY'])
+                        env.vars.set(n, { value: unknownString(`$${n}`), exported: env.vars.get(n)?.exported ?? false });
+                }
+                else if (names.length === 0)
+                    env.vars.set('MAPFILE', { value: unknownString('MAPFILE'), array: [unknownString('MAPFILE[@]')], exported: false });
+                return env;
+            }
+            case 'printf': {
+                rec();
+                const i = args.findIndex((a) => concrete(a) === '-v');
+                if (i >= 0) {
+                    const n = concrete(args[i + 1] ?? known(''));
+                    if (n)
+                        env.vars.set(n, { value: unknownString(`$${n}`), exported: false });
+                }
+                return env;
+            }
+            case 'set': {
+                rec();
+                const i = args.findIndex((a) => concrete(a) === '--');
+                if (i >= 0)
+                    env.positional = fields.slice(i + 2);
+                else if (args.length > 0 && !/^[-+]/.test(concrete(args[0]) ?? '-'))
+                    env.positional = fields.slice(1);
+                return env;
+            }
+            case 'shift': {
+                rec();
+                const n = Number(concrete(args[0] ?? known('1')) ?? NaN);
+                if (Number.isInteger(n) && !env.positional.some((f) => f.spread))
+                    env.positional = env.positional.slice(n);
+                else
+                    env.positional = [{ value: unknownString('$@'), spread: true }];
+                return env;
+            }
+            case 'exit':
+                rec();
+                if (ctx.subshell)
+                    return env;
+                env.terminated = true;
+                return env;
+            case 'return':
+                rec();
+                if (ctx.function)
+                    env.terminated = true;
+                return env;
+            case 'exec': {
+                const rest = args.filter((a, i) => !(i === 0 && (concrete(a) ?? '').startsWith('-')));
+                if (rest.length === 0) {
+                    rec();
+                    return env;
+                }
+                const r = this.opts.behaviors.analyze(this.invocation(rest, prefixEnv, ctx));
+                rec(r.effects, r.complete !== false);
+                if (!ctx.subshell)
+                    env.terminated = true;
+                return env;
+            }
+            case 'command':
+            case 'builtin':
+            case 'time': {
+                const rest = args.filter((a) => !(concrete(a) ?? '').startsWith('-'));
+                if (rest.length === 0 || args.some((a) => ['-v', '-V'].includes(concrete(a) ?? ''))) {
+                    rec();
+                    return env;
+                }
+                const sub = concrete(rest[0]);
+                if (sub && BUILTINS.has(sub)) {
+                    return this.builtin(sub, cmd, [{ value: rest[0], spread: false }, ...rest.slice(1).map((v) => ({ value: v, spread: false }))], [], env, prefixEnv, ctx, redirEffects);
+                }
+                const r = this.opts.behaviors.analyze(this.invocation(rest, prefixEnv, ctx));
+                rec(r.effects, r.complete !== false);
+                return env;
+            }
+            case 'eval': {
+                const text = concat(...args.flatMap((a, i) => (i === 0 ? [a] : [known(' '), a])));
+                const t = concrete(text);
+                if (t === undefined) {
+                    rec([{ kind: 'unknown', detail: `eval of ${describe(text)}` }], false);
+                    return env;
+                }
+                rec();
+                return this.inline(cmd, t, env, ctx) ?? env;
+            }
+            case 'source':
+            case '.': {
+                const file = args[0];
+                if (!file) {
+                    rec();
+                    return env;
+                }
+                const p = normalizeKnownPath(resolvePath(file, env.cwd));
+                const read = { kind: 'read', path: p };
+                const c = concrete(p);
+                // follow a file that exists now and that the snippet has not (possibly) written
+                const text = c !== undefined && !this.mayHaveChanged(c) && ctx.depth < MAX_CALL_DEPTH ? readSmallFile(c) : undefined;
+                if (text === undefined) {
+                    rec([read, { kind: 'unknown', detail: `source of ${describe(p)}: contents not known statically` }], false);
+                    return env;
+                }
+                rec([read]);
+                const saved = env.positional;
+                if (args.length > 1)
+                    env.positional = fields.slice(2);
+                const out = this.inline(cmd, text, env, ctx, c) ?? env;
+                if (args.length > 1)
+                    out.positional = saved;
+                return out;
+            }
+            case 'trap': {
+                rec();
+                const action = concrete(args[0] ?? known(''));
+                if (action && args.length > 1 && action !== '-')
+                    this.inline(cmd, action, env.clone(), { ...ctx, reach: 'may' });
+                return env;
+            }
+            case 'kill':
+                rec([{ kind: 'process', detail: `kill ${args.map(describe).join(' ')}` }]);
+                return env;
+            default:
+                rec();
+                return env;
+        }
+    }
+    assign(a, env, ctx, exported) {
+        const prev = env.vars.get(a.name);
+        if (a.value?.type === 'ArrayLiteral') {
+            const elems = a.value.elems.flatMap((el) => this.fields([el.value], env, ctx).map((f) => f.value));
+            env.vars.set(a.name, { value: elems[0] ?? known(''), array: elems, exported: exported || (prev?.exported ?? false) });
+            return;
+        }
+        this.lastOutput = null;
+        let value = a.value ? this.stringValue(a.value, env, ctx, true) : known('');
+        // `x=$(cmd)`: use the command's inferred output type
+        if (a.value && a.value.parts.length === 1 && a.value.parts[0].type === 'CmdSubst' && this.lastOutput && !isFullyKnown(value))
+            value = this.lastOutput;
+        if (a.index) {
+            env.vars.set(a.name, { value: join(prev?.value ?? known(''), value), array: [unknownString(`${a.name}[@]`)], exported: prev?.exported ?? false });
+            return;
+        }
+        if (a.append)
+            value = concat(prev?.value ?? known(''), value);
+        env.vars.set(a.name, { value, exported: exported || (prev?.exported ?? false) });
+    }
+    redirectEffects(redirs, env, ctx) {
+        const effects = [];
+        for (const r of redirs) {
+            if (r.op === '<<' || r.op === '<<-' || r.op === '<<<') {
+                if (r.heredoc && !r.heredoc.quoted)
+                    this.stringValue(r.heredoc.body, env, ctx);
+                continue;
+            }
+            if (r.op === '<&' || r.op === '>&') {
+                const t = literalOf(r.target);
+                if (t !== null && /^(\d+-?|-)$/.test(t))
+                    continue;
+            }
+            const target = guardEmpty(this.stringValue(r.target, env, ctx));
+            const t = concrete(target);
+            if (t === '/dev/null' || t === '/dev/stdout' || t === '/dev/stderr' || t === '/dev/stdin' || (t && /^\/dev\/fd\/\d+$/.test(t)))
+                continue;
+            const p = resolvePath(target, env.cwd);
+            if (r.op === '<')
+                effects.push({ kind: 'read', path: p, source: 'redirect' });
+            else if (r.op === '<>')
+                effects.push({ kind: 'read', path: p, source: 'redirect' }, { kind: 'write', path: p, source: 'redirect' });
+            else
+                effects.push({ kind: 'write', path: p, append: r.op === '>>' || r.op === '&>>', source: 'redirect' });
+        }
+        return effects;
+    }
+    record(r) {
+        const findings = [...checkExecEffects(r.effects, this.opts.policy), ...(r.extraFindings ?? []), ...checkEffects(r.effects, this.opts.policy).map((f) => this.missingOk(f, r.env))];
+        for (const e of r.effects) {
+            if (e.kind !== 'write' && e.kind !== 'delete')
+                continue;
+            const c = concrete(normalizeKnownPath(e.path));
+            if (c !== undefined)
+                this.shared.written.add(c);
+            else
+                this.shared.mayHaveWritten = true;
+        }
+        if (!r.complete)
+            this.shared.mayHaveWritten = true;
+        this.applyFs(r.env, r.effects, r.argv[0] ? concrete(r.argv[0]) : undefined);
+        this.emit({
+            nodeId: r.nodeId,
+            span: r.span,
+            line: this.line(r.span),
+            text: this.text(r.span),
+            argv: r.argv,
+            display: r.display ?? r.argv.map(describe).join(' '),
+            kind: r.kind,
+            reach: r.ctx.reach,
+            context: { loop: r.ctx.loop, subshell: r.ctx.subshell, cmdsubst: r.ctx.cmdsubst, pipeline: r.ctx.pipeline, background: r.ctx.background, function: r.ctx.function },
+            cwd: r.env.cwd,
+            effects: r.effects,
+            complete: r.complete,
+            findings,
+            verdict: worstVerdict(findings),
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Abstract expansion
+    // -------------------------------------------------------------------------
+    patternText(w, env, ctx) {
+        let s = '';
+        for (const p of w.parts) {
+            const v = concrete(this.partValue(p, env, ctx, false)) ?? '*';
+            s += p.type === 'Lit' ? v : quotePattern(v);
+        }
+        return s;
+    }
+    /** Expand a word without splitting (assignment values, redirect targets). */
+    stringValue(w, env, ctx, assignment = false) {
+        const parts = w.parts.map((p, i) => this.partValue(p, env, ctx, false, i === 0 || assignment));
+        return concat(...parts);
+    }
+    /** Expand words to abstract fields (splitting and globbing approximated). */
+    fields(words, env, ctx) {
+        const out = [];
+        for (const word of words) {
+            for (const w of braceExpand(word)) {
+                // "$@" and unquoted unknown expansions spread
+                if (w.parts.length === 1 && w.parts[0].type === 'DblQuoted' && w.parts[0].parts.length === 1 && w.parts[0].parts[0].type === 'ParamExp' && isAllParam(w.parts[0].parts[0])) {
+                    out.push(...this.allParamFields(w.parts[0].parts[0], env));
+                    continue;
+                }
+                if (w.parts.length === 1 && w.parts[0].type === 'ParamExp' && isAllParam(w.parts[0])) {
+                    out.push(...this.allParamFields(w.parts[0], env).map((f) => ({ ...f, spread: f.spread || !isFullyKnown(f.value) })));
+                    continue;
+                }
+                let spread = false;
+                const vals = [];
+                w.parts.forEach((p, i) => {
+                    const v = this.partValue(p, env, ctx, true, i === 0);
+                    if ((p.type === 'ParamExp' || p.type === 'CmdSubst') && !isFullyKnown(v))
+                        spread = true;
+                    vals.push(v);
+                });
+                let value = concat(...vals);
+                // unquoted known expansions: split on whitespace
+                const c = concrete(value);
+                const hasUnquotedExpansion = w.parts.some((p) => p.type === 'ParamExp' || p.type === 'CmdSubst' || p.type === 'ArithExp');
+                if (c !== undefined && hasUnquotedExpansion) {
+                    const pieces = c.split(/[ \t\n]+/).filter((x) => x !== '');
+                    for (const piece of pieces)
+                        out.push({ value: known(piece), spread: false });
+                    continue;
+                }
+                // globs in unquoted literal parts
+                const globbed = this.globValue(w, value);
+                if (globbed) {
+                    value = globbed;
+                    out.push({ value, spread: true, atLeastOne: !spread });
+                    continue;
+                }
+                out.push({ value: guardEmpty(value), spread });
+            }
+        }
+        return out;
+    }
+    /** `*.txt` → `⟨*.txt:filename⟩`, `/etc/*.conf` → `/etc/⟨*.conf:filename⟩`. */
+    globValue(w, value) {
+        if (!w.parts.some((p) => p.type === 'Lit' && hasGlobChars(p.value)))
+            return null;
+        const c = concrete(value);
+        if (c === undefined)
+            return null;
+        const comps = c.split('/');
+        const segs = [];
+        comps.forEach((comp, i) => {
+            if (i > 0)
+                segs.push(known('/'));
+            if (hasGlobChars(comp))
+                segs.push(hole('filename', comp, { pattern: comp }));
+            else
+                segs.push(known(comp));
+        });
+        return concat(...segs);
+    }
+    allParamFields(p, env) {
+        if (p.name === '@' || p.name === '*')
+            return env.positional;
+        const v = env.vars.get(p.name);
+        if (v?.array)
+            return v.array.map((value) => ({ value, spread: !isFullyKnown(value) }));
+        return [{ value: unknownString(`\${${p.name}[@]}`), spread: true }];
+    }
+    partValue(p, env, ctx, _split, first = false) {
+        switch (p.type) {
+            case 'Lit': {
+                if (first && p.value.startsWith('~')) {
+                    // with HOME unset, bash uses the user's home directory from the password database
+                    const home = env.vars.get('HOME')?.value ?? this.opts.envValues?.('HOME') ?? known(this.opts.policy.home ?? os.homedir());
+                    const slash = p.value.indexOf('/');
+                    const user = slash === -1 ? p.value.slice(1) : p.value.slice(1, slash);
+                    if (user === '')
+                        return concat(home, known(slash === -1 ? '' : p.value.slice(slash)));
+                }
+                return known(p.value);
+            }
+            case 'SglQuoted':
+            case 'Escaped':
+                return known(p.value);
+            case 'DblQuoted':
+                return concat(...p.parts.map((q) => this.partValue(q, env, ctx, false)));
+            case 'ParamExp':
+                return this.param(p, env, ctx);
+            case 'CmdSubst':
+                return this.cmdSubst(p, env, ctx);
+            case 'ArithExp':
+                return this.arith(p.expr, env);
+            case 'ProcSubst':
+                env.fs = this.list(p.body, env.clone(), { ...ctx, subshell: true, cmdsubst: true }).fs;
+                return known('/dev/fd/63');
+        }
+    }
+    cmdSubst(p, env, ctx) {
+        const saved = this.lastOutput;
+        this.lastOutput = null;
+        env.fs = this.list(p.body, env.clone(), { ...ctx, subshell: true, cmdsubst: true }).fs;
+        this.lastOutput = saved;
+        // the output is that of the body's last command: `$(cmd)`, `$(a | b)`
+        const last = p.body.length === 1 ? finalSimple(p.body[0].command) : undefined;
+        const out = last ? this.outputs.get(last.id) : undefined;
+        if (out) {
+            this.lastOutput = out;
+            return out;
+        }
+        // $(pwd) / $(cd x && pwd)
+        const text = this.text(p.span);
+        if (/^\$\(\s*pwd\s*\)$/.test(text))
+            return env.cwd;
+        return hole('string', text.length > 40 ? text.slice(0, 37) + '...' : text);
+    }
+    arith(expr, env) {
+        let ok = true;
+        const aenv = {
+            get: (name) => {
+                const v = env.vars.get(name);
+                if (!v) {
+                    // unknown to the analysis (RANDOM, SECONDS, unset or environment-dependent): the result is unknown
+                    ok = false;
+                    return undefined;
+                }
+                const c = concrete(v.value);
+                if (c === undefined)
+                    ok = false;
+                return c ?? '0';
+            },
+            isAssoc: () => false,
+            set: () => { },
+            expandWord: async (w) => {
+                const v = concrete(this.stringValue(w, env, { reach: 'may', loop: false, subshell: false, cmdsubst: false, pipeline: false, background: false, stdin: 'unknown', depth: 0 }));
+                if (v === undefined)
+                    ok = false;
+                return v ?? '0';
+            },
+            nounset: false,
+        };
+        return syncArith(expr, aenv, () => ok) ?? hole('int', '$((…))');
+    }
+    param(p, env, ctx) {
+        const special = () => {
+            switch (p.name) {
+                case '?':
+                case '#':
+                case '$':
+                case '!': return hole('int', `$${p.name}`);
+                case '0': return known('mash');
+                case '-': return hole('string', '$-');
+                case '@':
+                case '*': {
+                    const fs = env.positional;
+                    if (fs.length === 0)
+                        return known('');
+                    return concat(...fs.flatMap((f, i) => (i === 0 ? [f.value] : [known(' '), f.value])));
+                }
+            }
+            if (/^\d+$/.test(p.name)) {
+                const f = env.positional[Number(p.name) - 1];
+                if (env.positional.some((x) => x.spread))
+                    return unknownString(`$${p.name}`);
+                return f?.value ?? known('');
+            }
+            return undefined;
+        };
+        if (p.length)
+            return hole('int', `\${#${p.name}}`);
+        if (p.indirect || p.prefixNames)
+            return unknownString(this.text(p.span));
+        let base = special();
+        let unset = false;
+        if (base === undefined) {
+            const v = env.vars.get(p.name);
+            if (p.index && v?.array) {
+                const idx = literalOf(p.index);
+                if (idx === '@' || idx === '*')
+                    base = v.array.length ? concat(...v.array.flatMap((x, i) => (i === 0 ? [x] : [known(' '), x]))) : known('');
+                else if (idx !== null && /^\d+$/.test(idx))
+                    base = v.array[Number(idx)] ?? known('');
+                else
+                    base = join(...v.array);
+            }
+            else if (v) {
+                base = v.value;
+                if (v.unsetMaybe)
+                    unset = true;
+            }
+            else {
+                const ev = this.opts.envValues?.(p.name);
+                if (ev)
+                    base = ev;
+                else if (INT_SHELL_VARS.has(p.name))
+                    base = hole('int', `$${p.name}`);
+                else {
+                    base = unknownString(`$${p.name}`);
+                    unset = true;
+                }
+            }
+        }
+        const op = p.op;
+        if (!op)
+            return base;
+        switch (op.kind) {
+            case 'default':
+            case 'assign': {
+                const d = op.word ? this.stringValue(op.word, env, ctx) : known('');
+                const c = concrete(base);
+                let out;
+                if (c !== undefined && !unset && (c !== '' || !op.colon))
+                    out = base;
+                else if (c === '' && op.colon && !unset)
+                    out = d;
+                else if (env.vars.has(p.name) && !unset && !op.colon)
+                    out = base;
+                else
+                    out = env.vars.has(p.name) || this.opts.envValues?.(p.name) ? join(base, d) : d;
+                if (op.kind === 'assign')
+                    env.vars.set(p.name, { value: out, exported: env.vars.get(p.name)?.exported ?? false });
+                return out;
+            }
+            case 'alternative': {
+                const c = concrete(base);
+                const alt = op.word ? this.stringValue(op.word, env, ctx) : known('');
+                if (c !== undefined && !unset)
+                    return c === '' && op.colon ? known('') : alt;
+                return join(alt, known(''));
+            }
+            case 'error':
+                return base;
+            case 'removePrefix':
+            case 'removeSuffix':
+            case 'replace': {
+                const c = concrete(base);
+                const pat = op.kind === 'replace' ? op.pattern : op.pattern;
+                const patText = this.patternText(pat, env, ctx);
+                const patKnown = concrete(this.stringValue(pat, env, ctx)) !== undefined;
+                if (c !== undefined && patKnown) {
+                    if (op.kind === 'removePrefix')
+                        return known(removePrefix(c, patText, op.longest));
+                    if (op.kind === 'removeSuffix')
+                        return known(removeSuffix(c, patText, op.longest));
+                    if (op.kind === 'replace') {
+                        const rep = op.replacement ? concrete(this.stringValue(op.replacement, env, ctx)) : '';
+                        if (rep !== undefined)
+                            return known(replacePattern(c, patText, rep, op.mode));
+                    }
+                }
+                const origin = this.text(p.span);
+                // `${p##*/}` and `${p%%/*}` never contain `/`; nor does `${p//\//_}`
+                if (patKnown && op.kind !== 'replace' && op.longest && patText === (op.kind === 'removePrefix' ? '*/' : '/*'))
+                    return hole('segment', origin);
+                if (op.kind === 'replace' && op.mode === 'all' && patKnown && (patText === '/' || patText === '\\/')) {
+                    const rep = op.replacement ? concrete(this.stringValue(op.replacement, env, ctx)) : '';
+                    if (rep !== undefined && !rep.includes('/'))
+                        return hole('segment', origin);
+                }
+                // removing part of a slash-free value keeps it slash-free (but it may become empty, `.` or `..`)
+                const t = typeOf(base);
+                if (t !== 'mixed' && t !== 'literal' && isSlashFree(t))
+                    return hole(op.kind === 'replace' ? 'string' : 'segment', origin);
+                // `${p%/*}` of a path is a path
+                if (t === 'path')
+                    return hole('path', origin);
+                return unknownString(origin);
+            }
+            case 'case': {
+                const c = concrete(base);
+                if (c !== undefined && !op.pattern)
+                    return known(op.upper ? (op.all ? c.toUpperCase() : c.slice(0, 1).toUpperCase() + c.slice(1)) : op.all ? c.toLowerCase() : c.slice(0, 1).toLowerCase() + c.slice(1));
+                // case changes keep a slash-free value slash-free, and a name a name
+                const t = typeOf(base);
+                if (t !== 'mixed' && t !== 'literal' && isSlashFree(t))
+                    return hole(isNameLike(t) ? 'identifier' : 'segment', this.text(p.span));
+                return unknownString(this.text(p.span));
+            }
+            case 'substring': {
+                const c = concrete(base);
+                const off = concrete(this.arith(op.offset, env));
+                const len = op.length ? concrete(this.arith(op.length, env)) : undefined;
+                if (c !== undefined && off !== undefined && (op.length === null || len !== undefined)) {
+                    let start = Number(off);
+                    if (start < 0)
+                        start = Math.max(0, c.length + start);
+                    const end = len === undefined ? c.length : Number(len) < 0 ? c.length + Number(len) : start + Number(len);
+                    return known(c.slice(start, end));
+                }
+                const t = typeOf(base);
+                if (t !== 'mixed' && t !== 'literal' && isSlashFree(t))
+                    return hole('segment', this.text(p.span));
+                return unknownString(this.text(p.span));
+            }
+            case 'transform':
+                return unknownString(this.text(p.span));
+        }
+    }
+}
+import * as patternModule from "../vm/pattern.js";
+function readSmallFile(p) {
+    try {
+        const st = fs.statSync(p);
+        if (!st.isFile() || st.size > MAX_INLINE_BYTES)
+            return undefined;
+        return fs.readFileSync(p, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function hasSubstitution(w) {
+    const visit = (parts) => parts.some((p) => p.type === 'CmdSubst' || p.type === 'ProcSubst' || (p.type === 'DblQuoted' && visit(p.parts)));
+    return visit(w.parts);
+}
+/** Commands whose recursive writes create the directory written (`git clone x`, `tar -C x -x`, `cp -r a x`). */
+const DIR_CREATORS = new Set(['git', 'tar', 'unzip', 'cp', 'rsync', 'install', 'mktemp', 'ditto', 'curl', 'wget']);
+const NO_CTX = { reach: 'may', loop: false, subshell: false, cmdsubst: false, pipeline: false, background: false, stdin: 'unknown', depth: 0 };
+/** Variables bash itself sets to integers (when the snippet and environment do not define them). */
+const INT_SHELL_VARS = new Set(['RANDOM', 'SRANDOM', 'SECONDS', 'LINENO', 'BASHPID', 'PPID', 'UID', 'EUID', 'EPOCHSECONDS']);
+const PREDICATES = new Set(['test', '[', 'true', 'false', 'which', 'type', 'hash', 'pgrep', 'id', 'cmp', 'diff', 'tty', 'getent', 'grep', 'egrep', 'fgrep', 'rg', 'command']);
+/** Commands whose exit status is a yes/no answer: `x && y` after them is a guard, not a happy path. */
+function isPredicate(cmd) {
+    switch (cmd.type) {
+        case 'CondCommand':
+        case 'ArithCommand':
+            return true;
+        case 'Pipeline':
+            return cmd.negated || isPredicate(cmd.stages[cmd.stages.length - 1]);
+        case 'AndOr':
+            return isPredicate(cmd.items[cmd.items.length - 1]);
+        case 'SimpleCommand': {
+            const w = cmd.words[0];
+            const name = w && w.type === 'Word' ? literalOf(w) : null;
+            if (name === null || !PREDICATES.has(name))
+                return false;
+            const args = cmd.words.slice(1).map((x) => (x.type === 'Word' ? literalOf(x) ?? '' : ''));
+            if (name === 'grep' || name === 'egrep' || name === 'fgrep' || name === 'rg')
+                return args.some((a) => /^-[a-zA-Z]*q/.test(a) || a === '--quiet' || a === '--silent');
+            if (name === 'command')
+                return args.some((a) => a === '-v' || a === '-V');
+            return true;
+        }
+        default:
+            return false;
+    }
+}
+/** The simple command whose stdout is a command's stdout: itself, or the last stage of a pipeline. */
+function finalSimple(cmd) {
+    if (cmd.type === 'SimpleCommand')
+        return cmd;
+    if (cmd.type === 'Pipeline' && !cmd.negated) {
+        const st = cmd.stages[cmd.stages.length - 1];
+        return st.type === 'SimpleCommand' ? st : undefined;
+    }
+    return undefined;
+}
+function isAllParam(p) {
+    if (p.length || p.op)
+        return false;
+    if (p.name === '@' && !p.index)
+        return true;
+    return p.index !== null && literalOf(p.index) === '@';
+}
+/** `/a/b/../c` → `/a/c` for fully known paths (cwd tracking). */
+function normalizeKnownPath(v) {
+    const c = concrete(v);
+    if (c === undefined || !c.startsWith('/'))
+        return v;
+    const out = [];
+    for (const part of c.split('/')) {
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..')
+            out.pop();
+        else
+            out.push(part);
+    }
+    return known('/' + out.join('/'));
+}
+/** Synchronous arithmetic for fully known operands (static analysis). */
+function syncArith(expr, env, ok) {
+    const words = [];
+    const visit = (e) => {
+        switch (e.type) {
+            case 'ArithWord':
+                words.push(e);
+                break;
+            case 'ArithVar':
+                if (e.index)
+                    visit(e.index);
+                break;
+            case 'ArithUnary':
+                visit(e.operand);
+                break;
+            case 'ArithBinary':
+                visit(e.left);
+                visit(e.right);
+                break;
+            case 'ArithAssign':
+                visit(e.value);
+                break;
+            case 'ArithTernary':
+                visit(e.cond);
+                visit(e.then);
+                visit(e.else);
+                break;
+            case 'ArithGroup':
+                visit(e.expr);
+                break;
+            default: break;
+        }
+    };
+    visit(expr);
+    if (words.length > 0)
+        return null;
+    try {
+        const { evaluateArithText } = arithModule;
+        const { arithText } = parserModule;
+        const text = arithText(expr);
+        if (text === undefined)
+            return null;
+        const v = evaluateArithText(text, env);
+        return ok() ? known(String(v)) : null;
+    }
+    catch {
+        return null;
+    }
+}
+import * as arithModule from "../vm/arith.js";
+import * as parserModule from "../parser/parser.js";
+//# sourceMappingURL=analyze.js.map