@taliesinb/mash 0.0.0-stage → 0.1.0

package/src/analysis/analyze.ts

@@ -0,0 +1,1395 @@
+/**
+ * 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 type * as A from '../parser/ast.ts'
+import { parse, lineColumn, literalOf } from '../parser/parser.ts'
+import type { BehaviorRegistry } from '../behaviors/registry.ts'
+import { basename, resolvePath } from '../behaviors/registry.ts'
+import type { Invocation, OutputInfo, StdinKind } from '../behaviors/types.ts'
+import type { Effect } from '../policy/effects.ts'
+import { describeEffect, withVia, type Via } from '../policy/effects.ts'
+import { checkCommandName, checkEffects, checkExecEffects, shapesOf, worstVerdict, type Policy, type PolicyFinding, type Verdict } from '../policy/policy.ts'
+import { braceExpand } from '../vm/expand.ts'
+import { hasGlobChars, quotePattern, removePrefix, removeSuffix, replacePattern } from '../vm/pattern.ts'
+import { BUILTINS } from '../vm/builtins.ts'
+import { evaluateArith, type ArithEnv } from '../vm/arith.ts'
+import { refineOutput } from './outputs.ts'
+import { AFs, type FsState } from './fs.ts'
+import {
+  concat, concrete, describe, hole, guardEmpty, isFullyKnown, isNameLike, isSlashFree, join, known, typeOf, unknownString, type AValue, type HoleType, type Seg,
+} from './value.ts'
+
+export interface AnalyzeOptions {
+  cwd: AValue
+  /** Concrete initial environment. */
+  env: Record<string, string>
+  /** Abstract environment lookup (nested analysis of `bash -c`). Overrides `env`. */
+  envValues?: (name: string) => AValue | undefined
+  policy: Policy
+  behaviors: BehaviorRegistry
+  positional?: AValue[]
+  /** Nested analysis (bash -c, eval): suppress uncalled-function reporting. */
+  nested?: boolean
+  /** Reject definite violations reached on these paths (default: must and happy). */
+  rejectOn?: Reach[]
+}
+
+/**
+ * `must`: runs on every execution that does not terminate earlier.
+ * `happy`: runs if every preceding command succeeds (`a && b`, `cd x && cmd`).
+ * `may`: runs only under some condition (if/case arms, `||`, loop bodies that may not run).
+ */
+export type Reach = 'must' | 'happy' | 'may'
+
+export interface CommandSite {
+  nodeId: number
+  span: A.Span
+  line: number
+  text: string
+  /** Abstractly expanded argv. */
+  argv: AValue[]
+  /** Human-readable argv (unknowns shown as ⟨origin⟩). */
+  display: string
+  kind: 'builtin' | 'function' | 'external' | 'not-found' | 'unknown' | 'assignment'
+  reach: Reach
+  context: { loop: boolean; subshell: boolean; cmdsubst: boolean; pipeline: boolean; background: boolean; function?: string }
+  cwd: AValue
+  effects: Effect[]
+  /** The behavior definition fully determined the effects. */
+  complete: boolean
+  findings: PolicyFinding[]
+  verdict: Verdict
+}
+
+export interface VariableInfo {
+  name: string
+  value: string
+  type: HoleType | 'literal' | 'mixed' | 'array'
+}
+
+export interface Violation {
+  nodeId: number
+  line: number
+  text: string
+  reach: Reach
+  verdict: 'deny' | 'unknown'
+  reason: string
+  /** The effect, with its provenance (`… (via \`rm x\` (s.sh:3))`) for nested commands. */
+  effect: string
+  /** For effects of nested code (`bash -c`, scripts, `eval`, `source`): the inner commands, outermost first. */
+  via?: Via[]
+}
+
+export interface AnalysisReport {
+  commands: CommandSite[]
+  variables: VariableInfo[]
+  functions: string[]
+  violations: Violation[]
+  /** `reject`: a definite violation on a must-reach path. */
+  verdict: 'allow' | 'check-at-runtime' | 'reject'
+  reasons: string[]
+}
+
+interface AVar {
+  value: AValue
+  array?: AValue[]
+  exported: boolean
+  unsetMaybe?: boolean
+}
+
+interface AField {
+  value: AValue
+  /** May expand to zero or several fields. */
+  spread: boolean
+  /** Expands to at least one field (an unmatched glob stays literal). */
+  atLeastOne?: boolean
+}
+
+class AEnv {
+  vars = new Map<string, AVar>()
+  cwd: AValue
+  positional: AField[]
+  terminated = false
+  functions = new Map<string, AFunction>()
+  /** 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: boolean } = { mayHaveCreated: false }
+
+  constructor(cwd: AValue, positional: AField[]) {
+    this.cwd = cwd
+    this.positional = positional
+  }
+
+  clone(): AEnv {
+    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: string): FsState {
+    return this.fs.lookup(p, this.flags.mayHaveCreated)
+  }
+
+  /** Join two environments (control-flow merge). */
+  static join(a: AEnv, b: AEnv): AEnv {
+    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
+  }
+}
+
+interface Ctx {
+  reach: Reach
+  loop: boolean
+  subshell: boolean
+  cmdsubst: boolean
+  pipeline: boolean
+  background: boolean
+  function?: string
+  stdin: StdinKind
+  /** Call depth for inlined functions. */
+  depth: number
+}
+
+const MAX_CALL_DEPTH = 6
+
+export function analyzeScript(script: A.Script, source: string, opts: AnalyzeOptions): AnalysisReport {
+  return new Analyzer(source, opts).run(script)
+}
+
+/** Parse and analyze in one step. */
+export function analyzeSource(source: string, opts: AnalyzeOptions): AnalysisReport {
+  return analyzeScript(parse(source), source, opts)
+}
+
+/** State shared by an analyzer and the analyzers of code it inlines (`eval`, `source`, `trap`). */
+interface Shared {
+  calledFunctions: Set<string>
+  /** An earlier command had unknown effects (it might have created directories). */
+  mayHaveCreated: boolean
+  /** Concrete paths the snippet writes (a sourced file it wrote is not read from disk). */
+  written: Set<string>
+  /** An earlier command wrote somewhere not known statically. */
+  mayHaveWritten: boolean
+  /** Node ids for inlined code. */
+  nextId: number
+}
+
+/** A function definition and the analyzer whose source it is written in. */
+interface AFunction {
+  def: A.FunctionDef
+  owner: Analyzer
+}
+
+const MAX_INLINE_BYTES = 256 * 1024
+
+class Analyzer {
+  private readonly sites = new Map<number, CommandSite>()
+  private readonly source: string
+  private readonly opts: AnalyzeOptions
+  private readonly shared: Shared
+  /** Where recorded sites go: the report, or the inlining analyzer (adding provenance). */
+  private readonly emit: (site: CommandSite) => void
+  private lastOutput: AValue | null = null
+  /** Typed stdout of each external simple command (by node id), for `$(a | b)`. */
+  private readonly outputs = new Map<number, AValue | null>()
+
+  constructor(source: string, opts: AnalyzeOptions, parent?: { shared: Shared; emit: (site: CommandSite) => void }) {
+    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.
+   */
+  private missingOk(f: PolicyFinding, env: AEnv): PolicyFinding {
+    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). */
+  private applyFs(env: AEnv, effects: Effect[], argv0: string | undefined): void {
+    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 `!`.
+   */
+  private refine(cmd: A.Command | undefined, env: AEnv, success: boolean): void {
+    if (!cmd) return
+    const apply = (op: string, w: A.Word, ok: boolean): void => {
+      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 is A.Word => 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? */
+  private mayHaveChanged(p: string): boolean {
+    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.
+   */
+  private inline(cmd: A.SimpleCommand, code: string, env: AEnv, ctx: Ctx, file?: string): AEnv | undefined {
+    let script: A.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: A.Script): AnalysisReport {
+    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: 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: Violation[] = []
+    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: VariableInfo[] = []
+    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}`),
+    }
+  }
+
+  private line(span: A.Span): number {
+    return lineColumn(this.source, span.start).line
+  }
+
+  private text(span: A.Span): string {
+    return this.source.slice(span.start, span.end)
+  }
+
+  // -------------------------------------------------------------------------
+  // Statements
+  // -------------------------------------------------------------------------
+
+  private list(stmts: A.Stmt[], env: AEnv, ctx: Ctx): AEnv {
+    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
+  }
+
+  private stmt(s: A.Stmt, env: AEnv, ctx: Ctx): AEnv {
+    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)
+  }
+
+  private command(cmd: A.Command, env: AEnv, ctx: Ctx): AEnv {
+    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: A.Command, out: AEnv, ok: boolean): AEnv => {
+          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: 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: AEnv[] = []
+          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 = { ...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: AValue = items.length === 0 ? known('') : join(...items.map((f) => f.value))
+          if (items.length === 0) value = unknownString(`$${cmd.variable}`)
+          let e = env
+          const inner: Ctx = { ...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: AEnv[] = []
+          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
+        })
+    }
+  }
+
+  private withRedirs(redirs: A.Redirect[], env: AEnv, ctx: Ctx, fn: () => AEnv): AEnv {
+    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()
+  }
+
+  private condWords(e: A.CondExpr, env: AEnv, ctx: Ctx): void {
+    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. */
+  private arithAssignments(e: A.ArithExpr, env: AEnv): void {
+    const visit = (x: A.ArithExpr): void => {
+      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
+  // -------------------------------------------------------------------------
+
+  private simple(cmd: A.SimpleCommand, env: AEnv, ctx: Ctx): AEnv {
+    const argvFields: AField[] = []
+    const declAssigns: A.Assign[] = []
+    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
+  }
+
+  private outputValue(info: OutputInfo | undefined, name: string): AValue | null {
+    if (!info) return null
+    if (info.value) return info.value
+    return hole(info.type, `$(${name})`, info.under ? { under: info.under } : {})
+  }
+
+  private invocation(argv: AValue[], env: AEnv, ctx: Ctx): Invocation {
+    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),
+    }
+  }
+
+  private builtin(name: string, cmd: A.SimpleCommand, fields: AField[], declAssigns: A.Assign[], env: AEnv, prefixEnv: AEnv, ctx: Ctx, redirEffects: Effect[]): AEnv {
+    const argv = fields.map((f) => f.value)
+    const args = argv.slice(1)
+    const rec = (effects: Effect[] = [], complete = true): void => {
+      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: string[] = []
+        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: Effect = { 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
+    }
+  }
+
+  private assign(a: A.Assign, env: AEnv, ctx: Ctx, exported: boolean): void {
+    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) })
+  }
+
+  private redirectEffects(redirs: A.Redirect[], env: AEnv, ctx: Ctx): Effect[] {
+    const effects: Effect[] = []
+    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
+  }
+
+  private record(r: {
+    nodeId: number; span: A.Span; argv: AValue[]; kind: CommandSite['kind']; env: AEnv; ctx: Ctx; effects: Effect[]; complete: boolean; display?: string; extraFindings?: PolicyFinding[]
+  }): void {
+    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
+  // -------------------------------------------------------------------------
+
+  private patternText(w: A.Word, env: AEnv, ctx: Ctx): string {
+    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: A.Word, env: AEnv, ctx: Ctx, assignment = false): AValue {
+    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: A.Word[], env: AEnv, ctx: Ctx): AField[] {
+    const out: AField[] = []
+    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: AValue[] = []
+        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⟩`. */
+  private globValue(w: A.Word, value: AValue): AValue | null {
+    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: AValue[] = []
+    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)
+  }
+
+  private allParamFields(p: A.ParamExp, env: AEnv): AField[] {
+    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 }]
+  }
+
+  private partValue(p: A.WordPart, env: AEnv, ctx: Ctx, _split: boolean, first = false): AValue {
+    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')
+    }
+  }
+
+  private cmdSubst(p: A.CmdSubst, env: AEnv, ctx: Ctx): AValue {
+    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)
+  }
+
+  private arith(expr: A.ArithExpr, env: AEnv): AValue {
+    let ok = true
+    const aenv: ArithEnv = {
+      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', '$((…))')
+  }
+
+  private param(p: A.ParamExp, env: AEnv, ctx: Ctx): AValue {
+    const special = (): AValue | undefined => {
+      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: AValue | undefined = 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: AValue
+        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.ts'
+
+function readSmallFile(p: string): string | undefined {
+  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: A.Word): boolean {
+  const visit = (parts: A.WordPart[]): boolean => 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: 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: A.Command): boolean {
+  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: A.Command): A.SimpleCommand | undefined {
+  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: A.ParamExp): boolean {
+  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: AValue): AValue {
+  const c = concrete(v)
+  if (c === undefined || !c.startsWith('/')) return v
+  const out: string[] = []
+  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: A.ArithExpr, env: ArithEnv, ok: () => boolean): AValue | null {
+  const words: A.ArithWord[] = []
+  const visit = (e: A.ArithExpr): void => {
+    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.ts'
+import * as parserModule from '../parser/parser.ts'