@taliesinb/mash 0.0.0-stage → 0.1.0

package/src/parser/parser.ts

@@ -0,0 +1,1826 @@
+/**
+ * A scannerless recursive-descent parser for bash. Bash's lexical structure
+ * depends on context (command position, `[[ ]]`, `$(( ))`, `${ }`, here-docs,
+ * case patterns), so instead of a separate tokenizer the parser scans the
+ * source directly with a cursor and context-specific word scanners.
+ *
+ * Every node gets a span of offsets into the source. Command substitutions
+ * and process substitutions are parsed in place, so their spans are exact;
+ * backquoted substitutions are parsed from their unescaped text and their
+ * inner spans are approximate (offset from the opening backquote).
+ */
+
+import type * as A from './ast.ts'
+import { DECL_BUILTINS } from './ast.ts'
+
+export class ParseError extends Error {
+  readonly offset: number
+  readonly line: number
+  readonly column: number
+  /** True when the error is "unexpected end of input" (an incomplete snippet). */
+  readonly incomplete: boolean
+
+  constructor(message: string, source: string, offset: number, incomplete = false) {
+    const { line, column } = lineColumn(source, offset)
+    super(`${message} (line ${line}, column ${column})`)
+    this.name = 'ParseError'
+    this.offset = offset
+    this.line = line
+    this.column = column
+    this.incomplete = incomplete
+  }
+}
+
+/** 1-based line and column of an offset. */
+export function lineColumn(source: string, offset: number): { line: number; column: number } {
+  let line = 1
+  let lineStart = 0
+  for (let i = 0; i < offset && i < source.length; i++) {
+    if (source.charCodeAt(i) === 10) {
+      line++
+      lineStart = i + 1
+    }
+  }
+  return { line, column: offset - lineStart + 1 }
+}
+
+export interface ParseOptions {
+  /** Starting node id (default 1). Lets callers keep ids unique across several parses (e.g. `eval`). */
+  firstId?: number
+  /** Return the statements before a syntax error (in `script.error`) instead of throwing. */
+  partial?: boolean
+}
+
+/** Parse a bash script into an AST. Throws {@link ParseError}. */
+/** Mutable state shared by a parser and its sub-parsers (backquotes, here-docs). */
+interface Shared {
+  next: number
+  /** Comments seen, keyed by start offset (backtracking may visit one twice). */
+  comments?: Map<number, A.Comment>
+}
+
+function sortedComments(shared: Shared): A.Comment[] {
+  return [...(shared.comments?.values() ?? [])].sort((a, b) => a.span.start - b.span.start)
+}
+
+export function parse(source: string, options: ParseOptions = {}): A.Script {
+  const ids: Shared = { next: options.firstId ?? 1, comments: new Map() }
+  const p = new Parser(source, 0, ids, source)
+  if (!options.partial) {
+    const script = p.parseScript()
+    script.comments = sortedComments(ids)
+    return script
+  }
+  const sink: A.Stmt[] = []
+  try {
+    const script = p.parseScript(sink)
+    script.comments = sortedComments(ids)
+    return script
+  } catch (e) {
+    if (!(e instanceof ParseError)) throw e
+    // keep complete statements on lines before the error line
+    const lineStart = source.lastIndexOf('\n', Math.max(0, e.offset - 1)) + 1
+    const errLineStart = e.offset >= source.length ? source.lastIndexOf('\n', source.length - 1) + 1 : lineStart
+    const body = sink.filter((s) => s.span.end < errLineStart && source.indexOf('\n', s.span.end) < errLineStart && source.indexOf('\n', s.span.end) !== -1)
+    const last = body[body.length - 1]?.span.end ?? 0
+    return { id: ids.next++, span: { start: 0, end: source.length }, type: 'Script', body, error: e, comments: sortedComments(ids).filter((c) => c.span.end <= last) }
+  }
+}
+
+const RESERVED = new Set([
+  'if', 'then', 'else', 'elif', 'fi', 'do', 'done', 'case', 'esac', 'while', 'until',
+  'for', 'in', 'select', 'function', 'time', '{', '}', '!', '[[', ']]', 'coproc',
+])
+
+const COND_UNARY = new Set([
+  '-a', '-b', '-c', '-d', '-e', '-f', '-g', '-h', '-k', '-p', '-r', '-s', '-t', '-u', '-w', '-x',
+  '-G', '-L', '-N', '-O', '-S', '-z', '-n', '-o', '-v', '-R',
+])
+
+const COND_BINARY = new Set([
+  '==', '=', '!=', '=~', '<', '>', '-eq', '-ne', '-lt', '-le', '-gt', '-ge', '-nt', '-ot', '-ef',
+])
+
+const SPECIAL_PARAMS = new Set(['@', '*', '#', '?', '-', '$', '!', '0'])
+
+type StopFn = (c: string, p: Parser) => boolean
+
+const ARITH_EXPR_TYPES = new Set([
+  'ArithNum', 'ArithVar', 'ArithWord', 'ArithUnary', 'ArithBinary', 'ArithAssign', 'ArithTernary', 'ArithIncDec', 'ArithGroup',
+])
+
+const arithSources = new WeakMap<object, { src: string; offset: number }>()
+
+/**
+ * The exact source text of an arithmetic expression node. Bash expands `$x`
+ * inside arithmetic textually before evaluating, so the VM needs the raw text
+ * around `ArithWord`s.
+ */
+export function arithText(node: A.ArithExpr, span: A.Span = node.span): string | undefined {
+  const s = arithSources.get(node)
+  if (!s) return undefined
+  return s.src.slice(span.start - s.offset, span.end - s.offset)
+}
+
+interface PendingHeredoc {
+  redirect: A.Redirect
+  delimiter: string
+  quoted: boolean
+  strip: boolean
+}
+
+function isBlank(c: string): boolean {
+  return c === ' ' || c === '\t'
+}
+
+function isMeta(c: string): boolean {
+  return c === ' ' || c === '\t' || c === '\n' || c === '|' || c === '&' || c === ';' || c === '(' || c === ')' || c === '<' || c === '>'
+}
+
+function isNameStart(c: string | undefined): boolean {
+  return c !== undefined && /[A-Za-z_]/.test(c)
+}
+
+function isNameChar(c: string | undefined): boolean {
+  return c !== undefined && /[A-Za-z0-9_]/.test(c)
+}
+
+const normalStop: StopFn = (c) => isMeta(c)
+
+class Parser {
+  pos = 0
+  private pending: PendingHeredoc[] = []
+  /** >0 while scanning inside double quotes (affects `${v:-'x'}`). */
+  private dquoteDepth = 0
+
+  readonly src: string
+  /** Added to every span (non-zero for backquote sub-parsers). */
+  private readonly offset: number
+  private readonly ids: Shared
+  /** The whole original source, for error positions. */
+  private readonly root: string
+
+  constructor(src: string, offset: number, ids: Shared, root: string) {
+    this.src = src
+    this.offset = offset
+    this.ids = ids
+    this.root = root
+  }
+
+  // -------------------------------------------------------------------------
+  // Utilities
+  // -------------------------------------------------------------------------
+
+  private node<T extends A.Node>(start: number, end: number, fields: Omit<T, 'id' | 'span'>): T {
+    const n = { id: this.ids.next++, span: { start: start + this.offset, end: end + this.offset }, ...fields } as T
+    if (ARITH_EXPR_TYPES.has(n.type)) arithSources.set(n, { src: this.src, offset: this.offset })
+    return n
+  }
+
+  private error(message: string, at = this.pos): never {
+    throw new ParseError(message, this.root, at + this.offset, at >= this.src.length)
+  }
+
+  private peek(n = 0): string {
+    return this.src[this.pos + n] ?? ''
+  }
+
+  private startsWith(s: string): boolean {
+    return this.src.startsWith(s, this.pos)
+  }
+
+  private eof(): boolean {
+    return this.pos >= this.src.length
+  }
+
+  /** Skip spaces, tabs, line continuations and comments (not newlines). */
+  private skipBlanks(): void {
+    for (;;) {
+      const c = this.peek()
+      if (isBlank(c)) this.pos++
+      else if (c === '\\' && this.peek(1) === '\n') this.pos += 2
+      else if (c === '#') {
+        const start = this.pos
+        while (!this.eof() && this.peek() !== '\n') this.pos++
+        const span = { start: start + this.offset, end: this.pos + this.offset }
+        this.ids.comments?.set(span.start, { span, text: this.src.slice(start, this.pos) })
+      } else return
+    }
+  }
+
+  /** Consume one newline and then any here-document bodies queued on the line it ends. */
+  private consumeNewline(): void {
+    this.pos++
+    if (this.pending.length > 0) this.readHeredocBodies()
+  }
+
+  /** Skip blanks, comments and newlines. */
+  private skipNewlines(): void {
+    for (;;) {
+      this.skipBlanks()
+      if (this.peek() === '\n') this.consumeNewline()
+      else return
+    }
+  }
+
+  /**
+   * If an unquoted reserved word (or `{`/`}`/`!`/`[[`) sits at the cursor and is
+   * followed by a delimiter, return it (without consuming).
+   */
+  private peekReserved(): string | null {
+    const m = /^(?:[A-Za-z]+|\{|\}|!|\[\[|\]\])/.exec(this.src.slice(this.pos, this.pos + 10))
+    if (!m) return null
+    const w = m[0]
+    if (!RESERVED.has(w)) return null
+    const after = this.src[this.pos + w.length]
+    if (after === undefined || isMeta(after)) return w
+    return null
+  }
+
+  private expectReserved(word: string): void {
+    this.skipNewlines()
+    if (this.peekReserved() !== word) this.error(`expected '${word}'`)
+    this.pos += word.length
+  }
+
+  // -------------------------------------------------------------------------
+  // Script, lists, statements
+  // -------------------------------------------------------------------------
+
+  parseScript(sink?: A.Stmt[]): A.Script {
+    const body = this.parseList(new Set(), false, sink)
+    this.skipNewlines()
+    if (!this.eof()) this.error(`unexpected '${this.peek()}'`)
+    if (this.pending.length > 0) {
+      // Here-docs at the very end without a trailing newline: read what there is.
+      this.readHeredocBodies()
+    }
+    return this.node<A.Script>(0, this.src.length, { type: 'Script', body })
+  }
+
+  /** True when the cursor (after blanks/newlines) is at a terminator of the current list. */
+  private atListEnd(stopWords: Set<string>, stopParen: boolean): boolean {
+    if (this.eof()) return true
+    const c = this.peek()
+    if (c === ')' && stopParen) return true
+    if (stopWords.has(';;') && (this.startsWith(';;') || this.startsWith(';&'))) return true
+    if (c === ')' && stopWords.has(')')) return true
+    const r = this.peekReserved()
+    return r !== null && stopWords.has(r)
+  }
+
+  /**
+   * Parse statements until one of `stopWords` (reserved words, or ';;' for case
+   * items) or, with `stopParen`, a `)`.
+   */
+  private parseList(stopWords: Set<string>, stopParen: boolean, sink?: A.Stmt[]): A.Stmt[] {
+    const stmts: A.Stmt[] = sink ?? []
+    for (;;) {
+      this.skipNewlines()
+      if (this.atListEnd(stopWords, stopParen)) break
+      const c = this.peek()
+      if (c === ')' && !stopParen) this.error(`unexpected ')'`)
+      if (c === ';') this.error(`unexpected ';'`)
+      const start = this.pos
+      const command = this.parseAndOr()
+      const end = command.span.end - this.offset
+      this.skipBlanks()
+      let background = false
+      const sep = this.peek()
+      if (sep === '&' && !this.startsWith('&&') && !this.startsWith('&>')) {
+        background = true
+        this.pos++
+      } else if (sep === ';' && !this.startsWith(';;') && !this.startsWith(';&')) {
+        this.pos++
+      } else if (sep === '\n') {
+        this.consumeNewline()
+      } else if (!this.eof() && !this.atListEnd(stopWords, stopParen) && sep !== ')' && !this.startsWith(';;') && !this.startsWith(';&')) {
+        this.error(`unexpected '${sep}'`)
+      }
+      stmts.push(this.node<A.Stmt>(start, end, { type: 'Stmt', command, background }))
+    }
+    return stmts
+  }
+
+  private parseAndOr(): A.Command {
+    const start = this.pos
+    const items: A.Command[] = [this.parsePipeline()]
+    const ops: ('&&' | '||')[] = []
+    let end = items[0].span.end - this.offset
+    for (;;) {
+      this.skipBlanks()
+      if (this.startsWith('&&') || this.startsWith('||')) {
+        ops.push(this.src.slice(this.pos, this.pos + 2) as '&&' | '||')
+        this.pos += 2
+        this.skipNewlines()
+        items.push(this.parsePipeline())
+        end = items[items.length - 1].span.end - this.offset
+      } else break
+    }
+    if (items.length === 1) return items[0]
+    return this.node<A.AndOr>(start, end, { type: 'AndOr', items, ops })
+  }
+
+  private parsePipeline(): A.Command {
+    this.skipBlanks()
+    const start = this.pos
+    let timed = false
+    let negated = false
+    for (;;) {
+      const r = this.peekReserved()
+      if (r === 'time' && !timed) {
+        timed = true
+        this.pos += 4
+        this.skipBlanks()
+        if (this.startsWith('-p') && (isMeta(this.peek(2)) || this.peek(2) === '')) {
+          this.pos += 2
+          this.skipBlanks()
+        }
+      } else if (r === '!') {
+        negated = !negated
+        this.pos += 1
+        this.skipBlanks()
+      } else break
+    }
+    const stages: A.Command[] = [this.parseCommand()]
+    const pipeStderr: boolean[] = []
+    let end = stages[0].span.end - this.offset
+    for (;;) {
+      this.skipBlanks()
+      if (this.peek() === '|' && this.peek(1) !== '|') {
+        const amp = this.peek(1) === '&'
+        this.pos += amp ? 2 : 1
+        pipeStderr.push(amp)
+        this.skipNewlines()
+        stages.push(this.parseCommand())
+        end = stages[stages.length - 1].span.end - this.offset
+      } else break
+    }
+    if (stages.length === 1 && !negated && !timed) return stages[0]
+    return this.node<A.Pipeline>(start, end, { type: 'Pipeline', stages, pipeStderr, negated, timed })
+  }
+
+  // -------------------------------------------------------------------------
+  // Commands
+  // -------------------------------------------------------------------------
+
+  private parseCommand(): A.Command {
+    this.skipBlanks()
+    const start = this.pos
+    if (this.eof()) this.error('unexpected end of input, expected a command')
+    const r = this.peekReserved()
+    switch (r) {
+      case 'if': return this.withRedirs(this.parseIf())
+      case 'while':
+      case 'until': return this.withRedirs(this.parseLoop(r))
+      case 'for': return this.withRedirs(this.parseFor())
+      case 'select': return this.withRedirs(this.parseSelect())
+      case 'case': return this.withRedirs(this.parseCase())
+      case '{': return this.withRedirs(this.parseGroup())
+      case '[[': return this.withRedirs(this.parseCondCommand())
+      case 'function': return this.parseFunctionKeyword()
+      case 'then': case 'else': case 'elif': case 'fi': case 'do': case 'done': case 'esac': case '}':
+        this.error(`unexpected reserved word '${r}'`)
+    }
+    if (this.startsWith('((')) {
+      const arith = this.tryParseArithCommand()
+      if (arith) return this.withRedirs(arith)
+    }
+    if (this.peek() === '(') return this.withRedirs(this.parseSubshell())
+    // `name () compound`
+    const fm = /^([^\s|&;()<>'"`$\\=]+)[ \t]*\([ \t]*\)/.exec(this.src.slice(this.pos))
+    if (fm && !RESERVED.has(fm[1])) {
+      this.pos += fm[0].length
+      return this.parseFunctionBody(start, fm[1])
+    }
+    return this.parseSimpleCommand()
+  }
+
+  private withRedirs<T extends A.CompoundCommand>(cmd: T): T {
+    for (;;) {
+      this.skipBlanks()
+      const r = this.tryParseRedirect()
+      if (!r) break
+      cmd.redirs.push(r)
+      cmd.span.end = this.pos + this.offset
+    }
+    return cmd
+  }
+
+  private parseFunctionKeyword(): A.FunctionDef {
+    const start = this.pos
+    this.pos += 'function'.length
+    this.skipBlanks()
+    const m = /^[^\s|&;()<>'"`$\\]+/.exec(this.src.slice(this.pos))
+    if (!m) this.error('expected function name')
+    this.pos += m[0].length
+    this.skipBlanks()
+    if (this.startsWith('(')) {
+      this.pos++
+      this.skipBlanks()
+      if (this.peek() !== ')') this.error(`expected ')'`)
+      this.pos++
+    }
+    return this.parseFunctionBody(start, m[0])
+  }
+
+  private parseFunctionBody(start: number, name: string): A.FunctionDef {
+    this.skipNewlines()
+    const body = this.parseCommand()
+    if (body.type === 'SimpleCommand' || body.type === 'Pipeline' || body.type === 'AndOr' || body.type === 'FunctionDef') {
+      this.error('function body must be a compound command', body.span.start - this.offset)
+    }
+    return this.node<A.FunctionDef>(start, this.pos, { type: 'FunctionDef', name, body })
+  }
+
+  private parseGroup(): A.Group {
+    const start = this.pos
+    this.pos++ // {
+    const body = this.parseList(new Set(['}']), false)
+    this.expectReserved('}')
+    return this.node<A.Group>(start, this.pos, { type: 'Group', body, redirs: [] })
+  }
+
+  private parseSubshell(): A.Subshell {
+    const start = this.pos
+    this.pos++ // (
+    const body = this.parseList(new Set(), true)
+    this.skipNewlines()
+    if (this.peek() !== ')') this.error(`expected ')'`)
+    this.pos++
+    return this.node<A.Subshell>(start, this.pos, { type: 'Subshell', body, redirs: [] })
+  }
+
+  private parseIf(): A.If {
+    const start = this.pos
+    this.pos += 2
+    const clauses: A.IfClause[] = []
+    let elseBody: A.Stmt[] | null = null
+    const condStop = new Set(['then'])
+    const bodyStop = new Set(['elif', 'else', 'fi'])
+    for (;;) {
+      const cond = this.parseList(condStop, false)
+      this.expectReserved('then')
+      const body = this.parseList(bodyStop, false)
+      clauses.push({ cond, body })
+      this.skipNewlines()
+      const r = this.peekReserved()
+      if (r === 'elif') {
+        this.pos += 4
+        continue
+      }
+      if (r === 'else') {
+        this.pos += 4
+        elseBody = this.parseList(new Set(['fi']), false)
+      }
+      this.expectReserved('fi')
+      break
+    }
+    return this.node<A.If>(start, this.pos, { type: 'If', clauses, elseBody, redirs: [] })
+  }
+
+  private parseDoGroup(): A.Stmt[] {
+    this.skipNewlines()
+    const r = this.peekReserved()
+    if (r === '{') {
+      // `for x in a; { ...; }` (undocumented bash form)
+      this.pos++
+      const body = this.parseList(new Set(['}']), false)
+      this.expectReserved('}')
+      return body
+    }
+    this.expectReserved('do')
+    const body = this.parseList(new Set(['done']), false)
+    this.expectReserved('done')
+    return body
+  }
+
+  private parseLoop(kind: 'while' | 'until'): A.Loop {
+    const start = this.pos
+    this.pos += kind.length
+    const cond = this.parseList(new Set(['do']), false)
+    const body = this.parseDoGroup()
+    return this.node<A.Loop>(start, this.pos, { type: 'Loop', kind, cond, body, redirs: [] })
+  }
+
+  private parseForHead(keyword: string): { variable: string; items: A.Word[] | null } {
+    this.pos += keyword.length
+    this.skipBlanks()
+    const m = /^[A-Za-z_][A-Za-z0-9_]*/.exec(this.src.slice(this.pos))
+    if (!m) this.error(`expected a variable name after '${keyword}'`)
+    this.pos += m[0].length
+    this.skipBlanks()
+    let items: A.Word[] | null = null
+    // Optional newlines before `in`
+    const save = this.pos
+    this.skipNewlines()
+    if (this.peekReserved() === 'in') {
+      this.pos += 2
+      items = []
+      for (;;) {
+        this.skipBlanks()
+        const c = this.peek()
+        if (c === ';' || c === '\n' || this.eof()) break
+        const w = this.parseWord(normalStop)
+        if (!w) this.error(`unexpected '${c}' in for list`)
+        items.push(w)
+      }
+      if (this.peek() === ';') this.pos++
+    } else {
+      this.pos = save
+      this.skipBlanks()
+      if (this.peek() === ';') this.pos++
+    }
+    return { variable: m[0], items }
+  }
+
+  private parseFor(): A.For | A.ArithFor {
+    const start = this.pos
+    // for (( ... ))
+    const after = /^for[ \t]*\(\(/.exec(this.src.slice(this.pos))
+    if (after) {
+      this.pos += after[0].length
+      const parts: (A.ArithExpr | null)[] = []
+      for (let i = 0; i < 3; i++) {
+        this.skipArithSpace()
+        const term = i < 2 ? ';' : ')'
+        if (this.peek() === term) {
+          parts.push(null)
+        } else {
+          parts.push(this.parseArithComma())
+          this.skipArithSpace()
+        }
+        if (this.peek() !== term) this.error(`expected '${term}' in arithmetic for`)
+        this.pos++
+      }
+      if (this.peek() !== ')') this.error(`expected '))'`)
+      this.pos++
+      this.skipBlanks()
+      if (this.peek() === ';') this.pos++
+      const body = this.parseDoGroup()
+      return this.node<A.ArithFor>(start, this.pos, { type: 'ArithFor', init: parts[0], cond: parts[1], step: parts[2], body, redirs: [] })
+    }
+    const { variable, items } = this.parseForHead('for')
+    const body = this.parseDoGroup()
+    return this.node<A.For>(start, this.pos, { type: 'For', variable, items, body, redirs: [] })
+  }
+
+  private parseSelect(): A.Select {
+    const start = this.pos
+    const { variable, items } = this.parseForHead('select')
+    const body = this.parseDoGroup()
+    return this.node<A.Select>(start, this.pos, { type: 'Select', variable, items, body, redirs: [] })
+  }
+
+  private parseCase(): A.Case {
+    const start = this.pos
+    this.pos += 4
+    this.skipBlanks()
+    const word = this.parseWord(normalStop)
+    if (!word) this.error('expected a word after case')
+    this.skipNewlines()
+    if (this.peekReserved() !== 'in') this.error(`expected 'in'`)
+    this.pos += 2
+    const items: A.CaseItem[] = []
+    const patStop: StopFn = (c) => isBlank(c) || c === '\n' || c === '|' || c === ')' || c === ';' || c === '&' || c === '<' || c === '>'
+    for (;;) {
+      this.skipNewlines()
+      if (this.peekReserved() === 'esac') {
+        this.pos += 4
+        break
+      }
+      if (this.eof()) this.error(`expected 'esac'`)
+      const itemStart = this.pos
+      if (this.peek() === '(') this.pos++
+      const patterns: A.Word[] = []
+      for (;;) {
+        this.skipBlanks()
+        const w = this.parseWord(patStop)
+        if (!w) this.error('expected a case pattern')
+        patterns.push(w)
+        this.skipBlanks()
+        if (this.peek() === '|') {
+          this.pos++
+          continue
+        }
+        if (this.peek() === ')') {
+          this.pos++
+          break
+        }
+        this.error(`expected ')' or '|' in case pattern`)
+      }
+      const body = this.parseList(new Set([';;', 'esac']), false)
+      this.skipNewlines()
+      let terminator: ';;' | ';&' | ';;&' = ';;'
+      if (this.startsWith(';;&')) {
+        terminator = ';;&'
+        this.pos += 3
+      } else if (this.startsWith(';;')) {
+        this.pos += 2
+      } else if (this.startsWith(';&')) {
+        terminator = ';&'
+        this.pos += 2
+      } else if (this.peekReserved() !== 'esac') {
+        this.error(`expected ';;' or 'esac'`)
+      }
+      items.push(this.node<A.CaseItem>(itemStart, this.pos, { type: 'CaseItem', patterns, body, terminator }))
+    }
+    return this.node<A.Case>(start, this.pos, { type: 'Case', word, items, redirs: [] })
+  }
+
+  private tryParseArithCommand(): A.ArithCommand | null {
+    const start = this.pos
+    const savePending = this.pending.length
+    try {
+      this.pos += 2
+      const expr = this.parseArithComma()
+      this.skipArithSpace()
+      if (!this.startsWith('))')) throw new Error('no ))')
+      this.pos += 2
+      return this.node<A.ArithCommand>(start, this.pos, { type: 'ArithCommand', expr, redirs: [] })
+    } catch {
+      this.pos = start
+      this.pending.length = savePending
+      const close = this.matchingArithClose(start + 2)
+      if (close !== -1) {
+        const text = this.src.slice(start + 2, close)
+        // a subshell inside a subshell, `((cmd) ...)`, is not arithmetic
+        if (/^\s*\(/.test(text) && !this.looksArithmetic(text)) return null
+        const expr = this.rawArithWord(start + 2, close)
+        this.pos = close + 2
+        return this.node<A.ArithCommand>(start, this.pos, { type: 'ArithCommand', expr, redirs: [] })
+      }
+      return null
+    }
+  }
+
+  private looksArithmetic(text: string): boolean {
+    return /^[\s\d\w+\-*/%<>=!&|^~?:,()$#\[\]{}"'.]*$/.test(text) && !/[a-zA-Z_][\w]*\s+[a-zA-Z_-]/.test(text)
+  }
+
+  // -------------------------------------------------------------------------
+  // Simple commands, assignments, redirections
+  // -------------------------------------------------------------------------
+
+  private parseSimpleCommand(): A.SimpleCommand {
+    const start = this.pos
+    const assigns: A.Assign[] = []
+    const words: (A.Word | A.Assign)[] = []
+    const redirs: A.Redirect[] = []
+    let declMode = false
+    let end = this.pos
+    for (;;) {
+      this.skipBlanks()
+      if (this.eof()) break
+      const c = this.peek()
+      const redir = this.tryParseRedirect()
+      if (redir) {
+        redirs.push(redir)
+        end = this.pos
+        continue
+      }
+      if (c === '\n' || c === ';' || c === '&' || c === '|' || c === ')') break
+      if (c === '(') {
+        this.error(`unexpected '('`)
+      }
+      if (c === '<' || c === '>') {
+        // process substitution as a word
+        if (this.peek(1) !== '(') this.error(`unexpected '${c}'`)
+      }
+      if (words.length === 0 || declMode) {
+        const a = this.tryParseAssign(declMode)
+        if (a) {
+          if (words.length === 0) assigns.push(a)
+          else words.push(a)
+          end = this.pos
+          continue
+        }
+      }
+      const w = this.parseWord(normalStop)
+      if (!w) this.error(`unexpected '${c}'`)
+      if (words.length === 0 && w.parts.length === 1 && w.parts[0].type === 'Lit' && DECL_BUILTINS.has(w.parts[0].value)) {
+        declMode = true
+      }
+      words.push(w)
+      end = this.pos
+    }
+    if (assigns.length === 0 && words.length === 0 && redirs.length === 0) this.error('expected a command')
+    return this.node<A.SimpleCommand>(start, end, { type: 'SimpleCommand', assigns, words, redirs })
+  }
+
+  /** `name=value`, `name+=value`, `name[sub]=value`, `name=(...)`. In decl mode a bare `name` is not an assignment. */
+  private tryParseAssign(declMode: boolean): A.Assign | null {
+    const start = this.pos
+    const m = /^[A-Za-z_][A-Za-z0-9_]*/.exec(this.src.slice(this.pos, this.pos + 256))
+    if (!m) return null
+    let p = this.pos + m[0].length
+    let index: A.Word | null = null
+    if (this.src[p] === '[') {
+      // find matching ]
+      let depth = 0
+      let q = p
+      for (; q < this.src.length; q++) {
+        const ch = this.src[q]
+        if (ch === '[') depth++
+        else if (ch === ']') {
+          depth--
+          if (depth === 0) break
+        } else if (ch === '\n') return null
+      }
+      if (q >= this.src.length) return null
+      const after = this.src[q + 1]
+      if (!(after === '=' || (after === '+' && this.src[q + 2] === '='))) return null
+      this.pos = p + 1
+      index = this.parseWord((c) => c === ']', { allowBlanks: true }) ?? this.node<A.Word>(this.pos, this.pos, { type: 'Word', parts: [] })
+      if (this.peek() !== ']') {
+        this.pos = start
+        return null
+      }
+      this.pos++
+      p = this.pos
+    }
+    let append = false
+    if (this.src[p] === '+' && this.src[p + 1] === '=') {
+      append = true
+      p += 2
+    } else if (this.src[p] === '=') {
+      p += 1
+    } else {
+      this.pos = start
+      return null
+    }
+    this.pos = p
+    let value: A.Word | A.ArrayLiteral | null = null
+    if (this.peek() === '(') {
+      value = this.parseArrayLiteral()
+    } else {
+      value = this.parseWord(normalStop)
+    }
+    return this.node<A.Assign>(start, this.pos, { type: 'Assign', name: m[0], index, append, value })
+  }
+
+  private parseArrayLiteral(): A.ArrayLiteral {
+    const start = this.pos
+    this.pos++ // (
+    const elems: A.ArrayElem[] = []
+    for (;;) {
+      this.skipNewlines()
+      if (this.peek() === ')') {
+        this.pos++
+        break
+      }
+      if (this.eof()) this.error(`expected ')' to close array`)
+      let index: A.Word | null = null
+      if (this.peek() === '[') {
+        const save = this.pos
+        this.pos++
+        const idx = this.parseWord((c) => c === ']', { allowBlanks: true })
+        if (this.peek() === ']' && this.peek(1) === '=') {
+          index = idx ?? this.node<A.Word>(this.pos, this.pos, { type: 'Word', parts: [] })
+          this.pos += 2
+        } else {
+          this.pos = save
+        }
+      }
+      const value = this.parseWord(normalStop) ?? this.node<A.Word>(this.pos, this.pos, { type: 'Word', parts: [] })
+      if (!index && value.parts.length === 0) this.error(`unexpected '${this.peek()}' in array`)
+      elems.push({ index, value })
+    }
+    return this.node<A.ArrayLiteral>(start, this.pos, { type: 'ArrayLiteral', elems })
+  }
+
+  private tryParseRedirect(): A.Redirect | null {
+    const start = this.pos
+    let fd: number | null = null
+    let fdVar: string | null = null
+    const rest = this.src.slice(this.pos, this.pos + 64)
+    let m = /^(\d+)(?=[<>])/.exec(rest)
+    if (m) {
+      fd = Number(m[1])
+      this.pos += m[0].length
+    } else if ((m = /^\{([A-Za-z_][A-Za-z0-9_]*)\}(?=[<>])/.exec(rest))) {
+      fdVar = m[1]
+      this.pos += m[0].length
+    }
+    const ops: A.RedirectOp[] = ['&>>', '&>', '<<<', '<<-', '<<', '<&', '<>', '>>', '>&', '>|', '<', '>']
+    let op: A.RedirectOp | null = null
+    for (const o of ops) {
+      if (this.startsWith(o)) {
+        op = o
+        break
+      }
+    }
+    if (op === null || ((op === '<' || op === '>') && this.peek(1) === '(') || ((op === '&>' || op === '&>>') && (fd !== null || fdVar !== null))) {
+      this.pos = start
+      return null
+    }
+    this.pos += op.length
+    this.skipBlanks()
+    const target = this.parseWord(normalStop)
+    if (!target) this.error(`expected a word after '${op}'`)
+    const redirect = this.node<A.Redirect>(start, this.pos, { type: 'Redirect', op, fd, fdVar, target, heredoc: null })
+    if (op === '<<' || op === '<<-') {
+      let delimiter = ''
+      let quoted = false
+      for (const part of target.parts) {
+        if (part.type === 'Lit') delimiter += part.value
+        else if (part.type === 'SglQuoted' || part.type === 'Escaped') {
+          delimiter += part.value
+          quoted = true
+        } else if (part.type === 'DblQuoted') {
+          quoted = true
+          for (const inner of part.parts) {
+            if (inner.type === 'Lit') delimiter += inner.value
+            else delimiter += this.src.slice(inner.span.start - this.offset, inner.span.end - this.offset)
+          }
+        } else {
+          delimiter += this.src.slice(part.span.start - this.offset, part.span.end - this.offset)
+        }
+      }
+      this.pending.push({ redirect, delimiter, quoted, strip: op === '<<-' })
+    }
+    return redirect
+  }
+
+  private readHeredocBodies(): void {
+    const queue = this.pending
+    this.pending = []
+    for (const h of queue) {
+      const bodyStart = this.pos
+      let bodyEnd = this.pos
+      let found = false
+      while (!this.eof()) {
+        const nl = this.src.indexOf('\n', this.pos)
+        const lineEnd = nl === -1 ? this.src.length : nl
+        let line = this.src.slice(this.pos, lineEnd)
+        if (h.strip) line = line.replace(/^\t+/, '')
+        if (line === h.delimiter) {
+          bodyEnd = this.pos
+          this.pos = nl === -1 ? this.src.length : nl + 1
+          found = true
+          break
+        }
+        this.pos = nl === -1 ? this.src.length : nl + 1
+        bodyEnd = this.pos
+      }
+      if (!found) bodyEnd = this.src.length
+      const missingNewline = !found && bodyEnd > bodyStart && this.src[bodyEnd - 1] !== '\n'
+      let body: A.Word
+      if (h.quoted) {
+        let text = this.src.slice(bodyStart, bodyEnd)
+        if (h.strip) text = text.replace(/^\t+/gm, '')
+        if (missingNewline) text += '\n'
+        body = this.node<A.Word>(bodyStart, bodyEnd, {
+          type: 'Word',
+          parts: [this.node<A.SglQuoted>(bodyStart, bodyEnd, { type: 'SglQuoted', value: text, ansi: false })],
+        })
+      } else {
+        const resume = this.pos
+        const sub = new Parser(this.src.slice(0, bodyEnd), this.offset, this.ids, this.root)
+        sub.pos = bodyStart
+        const parts = sub.parseDquotedParts('heredoc')
+        if (h.strip) {
+          for (const part of parts) {
+            if (part.type !== 'Lit') continue
+            const atLineStart = part.span.start - this.offset === bodyStart || this.src[part.span.start - this.offset - 1] === '\n'
+            part.value = part.value.replace(/\n\t+/g, '\n')
+            if (atLineStart) part.value = part.value.replace(/^\t+/, '')
+          }
+        }
+        if (missingNewline) parts.push(this.node<A.Lit>(bodyEnd, bodyEnd, { type: 'Lit', value: '\n' }))
+        body = this.node<A.Word>(bodyStart, bodyEnd, { type: 'Word', parts })
+        this.pos = resume
+      }
+      h.redirect.heredoc = { delimiter: h.delimiter, quoted: h.quoted, body }
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Words
+  // -------------------------------------------------------------------------
+
+  /**
+   * Parse one word. `stop` decides which unquoted characters end it. Returns
+   * null if the word would be empty (cursor at a stop character).
+   */
+  parseWord(stop: StopFn, opts: { allowBlanks?: boolean; inDquote?: boolean; sglLiteral?: boolean } = {}): A.Word | null {
+    const start = this.pos
+    const parts = this.parseWordParts(stop, opts)
+    if (parts.length === 0 && this.pos === start) return null
+    return this.node<A.Word>(start, this.pos, { type: 'Word', parts })
+  }
+
+  private parseWordParts(stop: StopFn, opts: { allowBlanks?: boolean; inDquote?: boolean; sglLiteral?: boolean }): A.WordPart[] {
+    const parts: A.WordPart[] = []
+    let litStart = -1
+    let lit = ''
+    const flush = (): void => {
+      if (litStart >= 0) {
+        parts.push(this.node<A.Lit>(litStart, this.pos, { type: 'Lit', value: lit }))
+        litStart = -1
+        lit = ''
+      }
+    }
+    while (!this.eof()) {
+      const c = this.peek()
+      if (c === '\\' && this.peek(1) === '\n') {
+        flush()
+        this.pos += 2
+        continue
+      }
+      if ((c === '<' || c === '>') && this.peek(1) === '(' && !opts.inDquote && !opts.allowBlanks) {
+        flush()
+        parts.push(this.parseProcSubst())
+        continue
+      }
+      if ('@*+?!'.includes(c) && this.peek(1) === '(' && !opts.inDquote) {
+        const end = this.extglobEnd(this.pos + 1)
+        if (end !== -1) {
+          if (litStart < 0) litStart = this.pos
+          lit += this.src.slice(this.pos, end)
+          this.pos = end
+          continue
+        }
+      }
+      if (stop(c, this) && !(opts.allowBlanks && isBlank(c))) break
+      if (c === '\\') {
+        flush()
+        const s = this.pos
+        if (this.pos + 1 >= this.src.length) {
+          // a backslash at the very end of the input: bash 5 keeps it literally (3.2 dropped it)
+          this.pos++
+          parts.push(this.node<A.Lit>(s, this.pos, { type: 'Lit', value: '\\' }))
+          continue
+        }
+        this.pos += 2
+        if (opts.inDquote) {
+          const e = this.src[s + 1]
+          const value = '$`"\\}'.includes(e) ? e : '\\' + e
+          parts.push(this.node<A.Lit>(s, this.pos, { type: 'Lit', value }))
+        } else {
+          parts.push(this.node<A.Escaped>(s, this.pos, { type: 'Escaped', value: this.src[s + 1] }))
+        }
+        continue
+      }
+      if (c === "'" && !opts.inDquote && !opts.sglLiteral) {
+        flush()
+        const s = this.pos
+        const close = this.src.indexOf("'", this.pos + 1)
+        if (close === -1) this.error('unterminated single quote', s)
+        this.pos = close + 1
+        parts.push(this.node<A.SglQuoted>(s, this.pos, { type: 'SglQuoted', value: this.src.slice(s + 1, close), ansi: false }))
+        continue
+      }
+      if (c === '"') {
+        flush()
+        if (opts.inDquote) break
+        parts.push(this.parseDquoted(false))
+        continue
+      }
+      if (c === '$') {
+        const d = this.parseDollar(opts.inDquote ?? false)
+        if (d) {
+          flush()
+          parts.push(d)
+          continue
+        }
+      }
+      if (c === '`') {
+        flush()
+        parts.push(this.parseBackquote())
+        continue
+      }
+      if (litStart < 0) litStart = this.pos
+      lit += c
+      this.pos++
+    }
+    flush()
+    return parts
+  }
+
+  /** End offset (exclusive) of an extglob group starting at the `(` at `open`, or -1. */
+  private extglobEnd(open: number): number {
+    let depth = 0
+    for (let i = open; i < this.src.length; i++) {
+      const c = this.src[i]
+      if (c === '\\') {
+        i++
+        continue
+      }
+      if (c === '(') depth++
+      else if (c === ')') {
+        depth--
+        if (depth === 0) return i + 1
+      } else if (c === '\n' || ((c === ' ' || c === '\t') && depth <= 1 && false)) return -1
+    }
+    return -1
+  }
+
+  private parseDquoted(locale: boolean): A.DblQuoted {
+    const s = locale ? this.pos - 1 : this.pos
+    this.pos++ // "
+    const parts = this.parseDquotedParts('dquote')
+    if (this.peek() !== '"') this.error('unterminated double quote', s)
+    this.pos++
+    return this.node<A.DblQuoted>(s, this.pos, { type: 'DblQuoted', parts, locale })
+  }
+
+  /**
+   * Parts inside double quotes (until an unescaped `"`) or in an unquoted
+   * here-document body (until the end of the sub-source).
+   */
+  parseDquotedParts(mode: 'dquote' | 'heredoc'): A.WordPart[] {
+    this.dquoteDepth++
+    try {
+      return this.parseDquotedPartsInner(mode)
+    } finally {
+      this.dquoteDepth--
+    }
+  }
+
+  private parseDquotedPartsInner(mode: 'dquote' | 'heredoc'): A.WordPart[] {
+    const parts: A.WordPart[] = []
+    let litStart = -1
+    let lit = ''
+    const flush = (): void => {
+      if (litStart >= 0) {
+        parts.push(this.node<A.Lit>(litStart, this.pos, { type: 'Lit', value: lit }))
+        litStart = -1
+        lit = ''
+      }
+    }
+    while (!this.eof()) {
+      const c = this.peek()
+      if (c === '"' && mode === 'dquote') break
+      if (c === '\\') {
+        const e = this.peek(1)
+        if (e === '\n') {
+          flush()
+          this.pos += 2
+          continue
+        }
+        const escapable = mode === 'dquote' ? '$`"\\' : '$`\\'
+        if (e !== '' && escapable.includes(e)) {
+          if (litStart < 0) litStart = this.pos
+          lit += e
+          this.pos += 2
+          continue
+        }
+        if (litStart < 0) litStart = this.pos
+        lit += c
+        this.pos++
+        continue
+      }
+      if (c === '$') {
+        const d = this.parseDollar(true)
+        if (d) {
+          flush()
+          parts.push(d)
+          continue
+        }
+      }
+      if (c === '`') {
+        flush()
+        parts.push(this.parseBackquote())
+        continue
+      }
+      if (litStart < 0) litStart = this.pos
+      lit += c
+      this.pos++
+    }
+    flush()
+    return parts
+  }
+
+  private parseBackquote(): A.CmdSubst {
+    const s = this.pos
+    this.pos++
+    let text = ''
+    for (;;) {
+      if (this.eof()) this.error('unterminated backquote', s)
+      const c = this.peek()
+      if (c === '`') {
+        this.pos++
+        break
+      }
+      if (c === '\\' && (('`\\$'.includes(this.peek(1)) && this.peek(1) !== '') || (this.peek(1) === '"' && this.dquoteDepth > 0))) {
+        text += this.peek(1)
+        this.pos += 2
+        continue
+      }
+      text += c
+      this.pos++
+    }
+    const sub = new Parser(text, this.offset + s + 1, this.ids, this.root)
+    const body = sub.parseList(new Set(), false)
+    sub.skipNewlines()
+    if (!sub.eof()) sub.error(`unexpected '${sub.peek()}'`)
+    return this.node<A.CmdSubst>(s, this.pos, { type: 'CmdSubst', body, backquote: true })
+  }
+
+  private parseProcSubst(): A.ProcSubst {
+    const s = this.pos
+    const direction = this.peek() as '<' | '>'
+    this.pos += 2
+    const body = this.parseList(new Set(), true)
+    this.skipNewlines()
+    if (this.peek() !== ')') this.error(`expected ')' to close process substitution`, s)
+    this.pos++
+    return this.node<A.ProcSubst>(s, this.pos, { type: 'ProcSubst', direction, body })
+  }
+
+  /** Parse a `$`-construct at the cursor, or return null if `$` is literal here. */
+  private parseDollar(inDquote: boolean): A.WordPart | null {
+    const s = this.pos
+    const n = this.peek(1)
+    if (n === '(') {
+      if (this.peek(2) === '(') {
+        // $(( arith )) — or a command substitution starting with a subshell
+        const savePending = this.pending.length
+        const close = this.matchingArithClose(this.pos + 3)
+        try {
+          this.pos += 3
+          this.skipArithSpace()
+          if (this.startsWith('))')) {
+            this.pos += 2
+            return this.node<A.ArithExp>(s, this.pos, { type: 'ArithExp', expr: this.node<A.ArithNum>(s, this.pos, { type: 'ArithNum', text: '0' }) })
+          }
+          const expr = this.parseArithComma()
+          this.skipArithSpace()
+          if (!this.startsWith('))')) throw new Error('not arithmetic')
+          this.pos += 2
+          return this.node<A.ArithExp>(s, this.pos, { type: 'ArithExp', expr })
+        } catch {
+          this.pos = s
+          this.pending.length = savePending
+          if (close !== -1) {
+            // balanced `$(( ... ))` that does not parse: an arithmetic syntax error at runtime, like bash
+            return this.rawArith(s, this.pos + 3, close)
+          }
+        }
+      }
+      this.pos += 2
+      const savedDq = this.dquoteDepth
+      this.dquoteDepth = 0
+      const body = this.parseList(new Set(), true)
+      this.dquoteDepth = savedDq
+      this.skipNewlines()
+      if (this.peek() !== ')') this.error(`expected ')' to close command substitution`, s)
+      this.pos++
+      return this.node<A.CmdSubst>(s, this.pos, { type: 'CmdSubst', body, backquote: false })
+    }
+    if (n === '[') {
+      // deprecated $[ expr ]
+      const close = this.src.indexOf(']', this.pos + 2)
+      if (close !== -1) {
+        const save = this.pos
+        try {
+          this.pos += 2
+          const expr = this.parseArithComma()
+          this.skipArithSpace()
+          if (this.peek() !== ']') throw new Error('not arithmetic')
+          this.pos++
+          return this.node<A.ArithExp>(s, this.pos, { type: 'ArithExp', expr })
+        } catch {
+          this.pos = save
+        }
+      }
+    }
+    if (n === '{') return this.parseBracedParam()
+    if (n === "'" && !inDquote) return this.parseAnsiQuoted()
+    if (n === '"' && !inDquote) {
+      this.pos++
+      return this.parseDquoted(true)
+    }
+    if (isNameStart(n)) {
+      let e = this.pos + 2
+      while (isNameChar(this.src[e])) e++
+      const name = this.src.slice(this.pos + 1, e)
+      this.pos = e
+      return this.param(s, name, true)
+    }
+    if (/[0-9]/.test(n) || SPECIAL_PARAMS.has(n)) {
+      this.pos += 2
+      return this.param(s, n, true)
+    }
+    return null
+  }
+
+  /**
+   * If `from` starts arithmetic text whose parentheses balance up to a `))`,
+   * the offset of that `))`; else -1. (bash decides `$((` vs `$( (` this way.)
+   */
+  private matchingArithClose(from: number): number {
+    let depth = 0
+    for (let i = from; i < this.src.length; i++) {
+      const c = this.src[i]
+      if (c === '(') depth++
+      else if (c === ')') {
+        if (depth === 0) return this.src[i + 1] === ')' ? i : -1
+        depth--
+      } else if (c === '\n' && depth === 0) {
+        // keep scanning: arithmetic may span lines
+      } else if (c === "'" || c === '"' || c === '`') return -1
+    }
+    return -1
+  }
+
+  /** An arithmetic expansion kept as raw text (evaluated, and diagnosed, at runtime). */
+  private rawArith(s: number, textStart: number, close: number): A.ArithExp {
+    const expr = this.rawArithWord(textStart, close)
+    this.pos = close + 2
+    return this.node<A.ArithExp>(s, this.pos, { type: 'ArithExp', expr })
+  }
+
+  /** Raw arithmetic text as one word with `$`-expansions active (substituted textually, then parsed). */
+  private rawArithWord(textStart: number, close: number): A.ArithWord {
+    const sub = new Parser(this.src.slice(0, close), this.offset, this.ids, this.root)
+    sub.pos = textStart
+    const parts = sub.parseDquotedParts('heredoc')
+    const word = this.node<A.Word>(textStart, close, { type: 'Word', parts })
+    return this.node<A.ArithWord>(textStart, close, { type: 'ArithWord', word })
+  }
+
+  private param(s: number, name: string, short: boolean, extra: Partial<A.ParamExp> = {}): A.ParamExp {
+    return this.node<A.ParamExp>(s, this.pos, {
+      type: 'ParamExp', short, name, index: null, length: false, indirect: false, prefixNames: null, op: null, ...extra,
+    })
+  }
+
+  private parseAnsiQuoted(): A.SglQuoted {
+    const s = this.pos
+    this.pos += 2
+    let value = ''
+    for (;;) {
+      if (this.eof()) this.error('unterminated $\'', s)
+      const c = this.peek()
+      if (c === "'") {
+        this.pos++
+        break
+      }
+      if (c !== '\\') {
+        value += c
+        this.pos++
+        continue
+      }
+      const e = this.peek(1)
+      this.pos += 2
+      switch (e) {
+        case 'n': value += '\n'; break
+        case 't': value += '\t'; break
+        case 'r': value += '\r'; break
+        case 'a': value += '\x07'; break
+        case 'b': value += '\b'; break
+        case 'e': case 'E': value += '\x1b'; break
+        case 'f': value += '\f'; break
+        case 'v': value += '\v'; break
+        case '\\': value += '\\'; break
+        case "'": value += "'"; break
+        case '"': value += '"'; break
+        case '?': value += '?'; break
+        case 'c': {
+          const ch = this.peek()
+          this.pos++
+          value += String.fromCharCode(ch.toUpperCase().charCodeAt(0) ^ 0x40)
+          break
+        }
+        case 'x': case 'u': case 'U': {
+          const max = e === 'x' ? 2 : e === 'u' ? 4 : 8
+          const m = new RegExp(`^[0-9a-fA-F]{1,${max}}`).exec(this.src.slice(this.pos))
+          if (!m) {
+            value += '\\' + e
+            break
+          }
+          this.pos += m[0].length
+          value += String.fromCodePoint(parseInt(m[0], 16))
+          break
+        }
+        default: {
+          if (/[0-7]/.test(e)) {
+            const m = /^[0-7]{0,2}/.exec(this.src.slice(this.pos))!
+            this.pos += m[0].length
+            value += String.fromCharCode(parseInt(e + m[0], 8) & 0xff)
+          } else {
+            value += '\\' + e
+          }
+        }
+      }
+    }
+    return this.node<A.SglQuoted>(s, this.pos, { type: 'SglQuoted', value, ansi: true })
+  }
+
+  private parseBracedParam(): A.ParamExp {
+    const s = this.pos
+    this.pos += 2 // ${
+    let length = false
+    let indirect = false
+    const c0 = this.peek()
+    if (c0 === '#' && this.peek(1) !== '}' && (isNameStart(this.peek(1)) || /[0-9@*#?$!-]/.test(this.peek(1)))) {
+      // ${#x} — but ${#} is $#, and ${#-} etc are rare
+      length = true
+      this.pos++
+    } else if (c0 === '!' && this.peek(1) !== '}' && (isNameStart(this.peek(1)) || /[0-9@*#?$-]/.test(this.peek(1)))) {
+      indirect = true
+      this.pos++
+    }
+    let name: string
+    const c = this.peek()
+    if (isNameStart(c)) {
+      let e = this.pos + 1
+      while (isNameChar(this.src[e])) e++
+      name = this.src.slice(this.pos, e)
+      this.pos = e
+    } else if (/[0-9]/.test(c)) {
+      let e = this.pos + 1
+      while (/[0-9]/.test(this.src[e] ?? '')) e++
+      name = this.src.slice(this.pos, e)
+      this.pos = e
+    } else if (SPECIAL_PARAMS.has(c)) {
+      name = c
+      this.pos++
+    } else {
+      this.error('bad substitution', s)
+    }
+    if (indirect && (this.peek() === '*' || this.peek() === '@') && this.peek(1) === '}') {
+      const which = this.peek() as '*' | '@'
+      this.pos += 2
+      return this.param(s, name, false, { prefixNames: which })
+    }
+    let index: A.Word | null = null
+    if (this.peek() === '[') {
+      this.pos++
+      index = this.parseWord((ch) => ch === ']', { allowBlanks: true }) ?? this.node<A.Word>(this.pos, this.pos, { type: 'Word', parts: [] })
+      if (this.peek() !== ']') this.error(`expected ']'`)
+      this.pos++
+    }
+    let op: A.ParamOp | null = null
+    const braceStop: StopFn = (ch) => ch === '}'
+    const wordUntilBrace = (): A.Word | null => this.parseWord(braceStop, { allowBlanks: true })
+    // inside "...", single quotes in ${v:-'x'} are literal characters
+    const defaultWord = (): A.Word | null => this.parseWord(braceStop, { allowBlanks: true, sglLiteral: this.dquoteDepth > 0 })
+    const emptyWord = (): A.Word => this.node<A.Word>(this.pos, this.pos, { type: 'Word', parts: [] })
+    const o = this.peek()
+    if (o === '}') {
+      // plain
+    } else if (o === ':' && '-=?+'.includes(this.peek(1)) && this.peek(1) !== '') {
+      const kind = ({ '-': 'default', '=': 'assign', '?': 'error', '+': 'alternative' } as const)[this.peek(1) as '-' | '=' | '?' | '+']
+      this.pos += 2
+      op = { kind, colon: true, word: defaultWord() }
+    } else if ('-=?+'.includes(o)) {
+      const kind = ({ '-': 'default', '=': 'assign', '?': 'error', '+': 'alternative' } as const)[o as '-' | '=' | '?' | '+']
+      this.pos += 1
+      op = { kind, colon: false, word: defaultWord() }
+    } else if (o === ':') {
+      this.pos++
+      const offset = this.parseArithSegment([':', '}'])
+      let len: A.ArithExpr | null = null
+      if (this.peek() === ':') {
+        this.pos++
+        len = this.parseArithSegment(['}'])
+      }
+      op = { kind: 'substring', offset, length: len }
+    } else if (o === '#' || o === '%') {
+      const longest = this.peek(1) === o
+      this.pos += longest ? 2 : 1
+      op = { kind: o === '#' ? 'removePrefix' : 'removeSuffix', longest, pattern: wordUntilBrace() ?? emptyWord() }
+    } else if (o === '/') {
+      let mode: 'first' | 'all' | 'prefix' | 'suffix' = 'first'
+      this.pos++
+      if (this.peek() === '/') { mode = 'all'; this.pos++ } else if (this.peek() === '#') { mode = 'prefix'; this.pos++ } else if (this.peek() === '%') { mode = 'suffix'; this.pos++ }
+      const pattern = this.parseWord((ch) => ch === '/' || ch === '}', { allowBlanks: true }) ?? emptyWord()
+      let replacement: A.Word | null = null
+      if (this.peek() === '/') {
+        this.pos++
+        replacement = wordUntilBrace() ?? emptyWord()
+      }
+      op = { kind: 'replace', mode, pattern, replacement }
+    } else if (o === '^' || o === ',') {
+      const all = this.peek(1) === o
+      this.pos += all ? 2 : 1
+      op = { kind: 'case', upper: o === '^', all, pattern: wordUntilBrace() }
+    } else if (o === '@') {
+      this.pos++
+      const operator = this.peek()
+      this.pos++
+      op = { kind: 'transform', operator }
+    } else {
+      this.error('bad substitution', s)
+    }
+    if (this.peek() !== '}') this.error(`expected '}' to close parameter expansion`, s)
+    this.pos++
+    return this.param(s, name, false, { index, length, indirect, op })
+  }
+
+  // -------------------------------------------------------------------------
+  // [[ conditional ]]
+  // -------------------------------------------------------------------------
+
+  private parseCondCommand(): A.CondCommand {
+    const start = this.pos
+    this.pos += 2
+    const expr = this.parseCondOr()
+    this.skipCondSpace()
+    if (!this.startsWith(']]')) this.error(`expected ']]'`)
+    this.pos += 2
+    return this.node<A.CondCommand>(start, this.pos, { type: 'CondCommand', expr, redirs: [] })
+  }
+
+  private skipCondSpace(): void {
+    for (;;) {
+      this.skipBlanks()
+      if (this.peek() === '\n') this.consumeNewline()
+      else return
+    }
+  }
+
+  private atCondEnd(): boolean {
+    return this.startsWith(']]') && (isMeta(this.peek(2)) || this.peek(2) === '')
+  }
+
+  private parseCondOr(): A.CondExpr {
+    this.skipCondSpace()
+    const start = this.pos
+    let left = this.parseCondAnd()
+    for (;;) {
+      this.skipCondSpace()
+      if (!this.startsWith('||')) return left
+      this.pos += 2
+      const right = this.parseCondAnd()
+      left = this.node<A.CondAndOr>(start, this.pos, { type: 'CondAndOr', op: '||', left, right })
+    }
+  }
+
+  private parseCondAnd(): A.CondExpr {
+    this.skipCondSpace()
+    const start = this.pos
+    let left = this.parseCondNot()
+    for (;;) {
+      this.skipCondSpace()
+      if (!this.startsWith('&&')) return left
+      this.pos += 2
+      const right = this.parseCondNot()
+      left = this.node<A.CondAndOr>(start, this.pos, { type: 'CondAndOr', op: '&&', left, right })
+    }
+  }
+
+  private parseCondNot(): A.CondExpr {
+    this.skipCondSpace()
+    const start = this.pos
+    if (this.peek() === '!' && (isMeta(this.peek(1)) || this.peek(1) === '')) {
+      this.pos++
+      const operand = this.parseCondNot()
+      return this.node<A.CondNot>(start, this.pos, { type: 'CondNot', operand })
+    }
+    return this.parseCondPrimary()
+  }
+
+  private condWord(): A.Word {
+    const stop: StopFn = (c, p) => isBlank(c) || c === '\n' || c === '(' || c === ')' || c === '<' || c === '>' || c === ';'
+      || (c === '&' && p.peek(1) === '&') || (c === '|' && p.peek(1) === '|')
+    const w = this.parseWord(stop)
+    if (!w) this.error(this.eof() ? 'unexpected end of input in [[ ]]' : `unexpected '${this.peek()}' in [[ ]]`)
+    return w
+  }
+
+  private regexWord(): A.Word {
+    // RHS of =~: parens and | are part of the regex; blanks end it at depth 0.
+    let depth = 0
+    const stop: StopFn = (c, p) => {
+      if (c === '(') { depth++; return false }
+      if (c === ')') {
+        if (depth === 0) return true
+        depth--
+        return false
+      }
+      if (depth > 0) return c === '\n'
+      return isBlank(c) || c === '\n' || (c === '&' && p.peek(1) === '&') || (c === '|' && p.peek(1) === '|')
+    }
+    const w = this.parseWord(stop)
+    if (!w) this.error('expected a regular expression after =~')
+    return w
+  }
+
+  private parseCondPrimary(): A.CondExpr {
+    this.skipCondSpace()
+    const start = this.pos
+    if (this.peek() === '(') {
+      this.pos++
+      const expr = this.parseCondOr()
+      this.skipCondSpace()
+      if (this.peek() !== ')') this.error(`expected ')' in [[ ]]`)
+      this.pos++
+      return this.node<A.CondGroup>(start, this.pos, { type: 'CondGroup', expr })
+    }
+    if (this.atCondEnd()) this.error('expected an expression in [[ ]]')
+    const first = this.condWord()
+    const firstLit = literalOf(first)
+    this.skipBlanks()
+    if (firstLit !== null && COND_UNARY.has(firstLit) && !this.atCondEnd() && !this.startsWith('&&') && !this.startsWith('||') && this.peek() !== ')') {
+      // unary unless followed by a binary operator
+      const save = this.pos
+      const opm = this.peekCondBinaryOp()
+      if (opm === null) {
+        const operand = this.condWord()
+        return this.node<A.CondUnary>(start, this.pos, { type: 'CondUnary', op: firstLit, operand })
+      }
+      this.pos = save
+    }
+    const op = this.peekCondBinaryOp()
+    if (op !== null) {
+      this.pos += op.length
+      this.skipBlanks()
+      const right = op === '=~' ? this.regexWord() : this.condWord()
+      return this.node<A.CondBinary>(start, this.pos, { type: 'CondBinary', op, left: first, right })
+    }
+    return this.node<A.CondWord>(start, this.pos, { type: 'CondWord', word: first })
+  }
+
+  private peekCondBinaryOp(): string | null {
+    const m = /^(==|=~|!=|=|<|>|-(?:eq|ne|lt|le|gt|ge|nt|ot|ef))/.exec(this.src.slice(this.pos, this.pos + 4))
+    if (!m) return null
+    const after = this.src[this.pos + m[0].length]
+    if (m[0] === '<' || m[0] === '>') return m[0]
+    if (after !== undefined && !isBlank(after) && after !== '\n') return null
+    return COND_BINARY.has(m[0]) ? m[0] : null
+  }
+
+  // -------------------------------------------------------------------------
+  // Arithmetic
+  // -------------------------------------------------------------------------
+
+  private skipArithSpace(): void {
+    for (;;) {
+      const c = this.peek()
+      if (c === ' ' || c === '\t' || c === '\r') this.pos++
+      else if (c === '\n') this.consumeNewline()
+      else if (c === '\\' && this.peek(1) === '\n') this.pos += 2
+      else return
+    }
+  }
+
+  /** Arithmetic inside `${x:off:len}`: parse up to one of `terminators`. */
+  private parseArithSegment(terminators: string[]): A.ArithExpr {
+    const start = this.pos
+    this.skipArithSpace()
+    if (terminators.includes(this.peek())) {
+      // empty offset/length means 0
+      return this.node<A.ArithNum>(start, this.pos, { type: 'ArithNum', text: '0' })
+    }
+    const e = this.parseArithTernary()
+    this.skipArithSpace()
+    if (!terminators.includes(this.peek())) this.error(`unexpected '${this.peek()}' in substring expansion`)
+    return e
+  }
+
+  parseArithComma(): A.ArithExpr {
+    this.skipArithSpace()
+    const start = this.pos
+    let left = this.parseArithAssign()
+    for (;;) {
+      this.skipArithSpace()
+      if (this.peek() !== ',') return left
+      this.pos++
+      const right = this.parseArithAssign()
+      left = this.node<A.ArithBinary>(start, this.pos, { type: 'ArithBinary', op: ',', left, right })
+    }
+  }
+
+  private parseArithAssign(): A.ArithExpr {
+    this.skipArithSpace()
+    const start = this.pos
+    const left = this.parseArithTernary()
+    this.skipArithSpace()
+    const m = /^(<<=|>>=|\*=|\/=|%=|\+=|-=|&=|\^=|\|=|=(?!=))/.exec(this.src.slice(this.pos, this.pos + 3))
+    if (m) {
+      if (left.type !== 'ArithVar') this.error('attempted assignment to non-variable')
+      this.pos += m[0].length
+      const value = this.parseArithAssign()
+      return this.node<A.ArithAssign>(start, this.pos, { type: 'ArithAssign', op: m[0] as A.ArithAssign['op'], target: left, value })
+    }
+    return left
+  }
+
+  private parseArithTernary(): A.ArithExpr {
+    this.skipArithSpace()
+    const start = this.pos
+    const cond = this.parseArithBinary(0)
+    this.skipArithSpace()
+    if (this.peek() !== '?') return cond
+    this.pos++
+    const then = this.parseArithAssign()
+    this.skipArithSpace()
+    if (this.peek() !== ':') this.error(`expected ':' in ternary`)
+    this.pos++
+    const els = this.parseArithAssign()
+    return this.node<A.ArithTernary>(start, this.pos, { type: 'ArithTernary', cond, then, else: els })
+  }
+
+  private static readonly BIN_LEVELS: string[][] = [
+    ['||'], ['&&'], ['|'], ['^'], ['&'], ['==', '!='], ['<=', '>=', '<', '>'], ['<<', '>>'], ['+', '-'], ['*', '/', '%'],
+  ]
+
+  private matchArithOp(level: number): string | null {
+    for (const op of Parser.BIN_LEVELS[level]) {
+      if (!this.startsWith(op)) continue
+      const next = this.src[this.pos + op.length]
+      // don't confuse with longer operators / assignments
+      if (op === '|' && (next === '|' || next === '=')) continue
+      if (op === '&' && (next === '&' || next === '=')) continue
+      if ((op === '<' || op === '>') && (next === op || next === '=')) continue
+      if ((op === '<<' || op === '>>') && next === '=') continue
+      if ((op === '+' || op === '-') && (next === op || next === '=')) continue
+      if (op === '*' && (next === '*' || next === '=')) continue
+      if ((op === '/' || op === '%' || op === '^') && next === '=') continue
+      return op
+    }
+    return null
+  }
+
+  private parseArithBinary(level: number): A.ArithExpr {
+    if (level >= Parser.BIN_LEVELS.length) return this.parseArithPower()
+    this.skipArithSpace()
+    const start = this.pos
+    let left = this.parseArithBinary(level + 1)
+    for (;;) {
+      this.skipArithSpace()
+      const op = this.matchArithOp(level)
+      if (op === null) return left
+      this.pos += op.length
+      const right = this.parseArithBinary(level + 1)
+      left = this.node<A.ArithBinary>(start, this.pos, { type: 'ArithBinary', op: op as A.ArithBinaryOp, left, right })
+    }
+  }
+
+  private parseArithPower(): A.ArithExpr {
+    this.skipArithSpace()
+    const start = this.pos
+    const base = this.parseArithUnary()
+    this.skipArithSpace()
+    if (this.startsWith('**') && this.peek(2) !== '=') {
+      this.pos += 2
+      const exp = this.parseArithPower()
+      return this.node<A.ArithBinary>(start, this.pos, { type: 'ArithBinary', op: '**', left: base, right: exp })
+    }
+    return base
+  }
+
+  private parseArithUnary(): A.ArithExpr {
+    this.skipArithSpace()
+    const start = this.pos
+    if (this.startsWith('++') || this.startsWith('--')) {
+      const op = this.src.slice(this.pos, this.pos + 2) as '++' | '--'
+      this.pos += 2
+      this.skipArithSpace()
+      const target = this.parseArithPostfix()
+      if (target.type !== 'ArithVar') this.error(`${op} requires a variable`)
+      return this.node<A.ArithIncDec>(start, this.pos, { type: 'ArithIncDec', op, prefix: true, target })
+    }
+    const c = this.peek()
+    if (c === '-' || c === '+' || c === '!' || c === '~') {
+      this.pos++
+      const operand = this.parseArithUnary()
+      return this.node<A.ArithUnary>(start, this.pos, { type: 'ArithUnary', op: c, operand })
+    }
+    return this.parseArithPostfix()
+  }
+
+  private parseArithPostfix(): A.ArithExpr {
+    const start = this.pos
+    const primary = this.parseArithPrimary()
+    if (primary.type === 'ArithVar') {
+      const save = this.pos
+      this.skipArithSpace()
+      if (this.startsWith('++') || this.startsWith('--')) {
+        const op = this.src.slice(this.pos, this.pos + 2) as '++' | '--'
+        this.pos += 2
+        return this.node<A.ArithIncDec>(start, this.pos, { type: 'ArithIncDec', op, prefix: false, target: primary })
+      }
+      this.pos = save
+    }
+    return primary
+  }
+
+  private parseArithPrimary(): A.ArithExpr {
+    this.skipArithSpace()
+    const start = this.pos
+    const c = this.peek()
+    if (c === '(') {
+      this.pos++
+      const expr = this.parseArithComma()
+      this.skipArithSpace()
+      if (this.peek() !== ')') this.error(`expected ')' in arithmetic`)
+      this.pos++
+      return this.node<A.ArithGroup>(start, this.pos, { type: 'ArithGroup', expr })
+    }
+    if (/[0-9]/.test(c)) {
+      const based = /^([0-9]+#)(?=[$`])/.exec(this.src.slice(this.pos, this.pos + 8))
+      if (based) {
+        // `10#$n`: base prefix glued to an expansion — kept as one word, evaluated textually
+        const litEnd = this.pos + based[1].length
+        const lit = this.node<A.Lit>(this.pos, litEnd, { type: 'Lit', value: based[1] })
+        this.pos = litEnd
+        const d = this.peek() === '$' ? this.parseDollar(false) : this.parseBackquote()
+        if (!d) this.error('bad base expression')
+        const word = this.node<A.Word>(start, this.pos, { type: 'Word', parts: [lit, d] })
+        return this.node<A.ArithWord>(start, this.pos, { type: 'ArithWord', word })
+      }
+      const m = /^(0[xX][0-9a-fA-F]+|[0-9]+#[0-9a-zA-Z@_]+|[0-9]+)/.exec(this.src.slice(this.pos))!
+      this.pos += m[0].length
+      return this.node<A.ArithNum>(start, this.pos, { type: 'ArithNum', text: m[0] })
+    }
+    if (isNameStart(c)) {
+      let e = this.pos + 1
+      while (isNameChar(this.src[e])) e++
+      const name = this.src.slice(this.pos, e)
+      this.pos = e
+      let index: A.ArithExpr | null = null
+      if (this.peek() === '[') {
+        this.pos++
+        index = this.parseArithComma()
+        this.skipArithSpace()
+        if (this.peek() !== ']') this.error(`expected ']' in arithmetic`)
+        this.pos++
+      }
+      return this.node<A.ArithVar>(start, this.pos, { type: 'ArithVar', name, index })
+    }
+    if (c === '$' || c === '`' || c === '"' || c === "'") {
+      // A word: $x, ${x}, $(cmd), `cmd`, "..."
+      const parts: A.WordPart[] = []
+      for (;;) {
+        const ch = this.peek()
+        if (ch === '$') {
+          const d = this.parseDollar(false)
+          if (!d) break
+          parts.push(d)
+        } else if (ch === '`') {
+          parts.push(this.parseBackquote())
+        } else if (ch === '"') {
+          parts.push(this.parseDquoted(false))
+        } else if (ch === "'") {
+          const close = this.src.indexOf("'", this.pos + 1)
+          if (close === -1) this.error('unterminated quote')
+          const s = this.pos
+          this.pos = close + 1
+          parts.push(this.node<A.SglQuoted>(s, this.pos, { type: 'SglQuoted', value: this.src.slice(s + 1, close), ansi: false }))
+        } else if (isNameChar(ch) && parts.length > 0) {
+          // $x1 style continuation (e.g. ${a}b)
+          const s = this.pos
+          let e = this.pos
+          while (isNameChar(this.src[e])) e++
+          this.pos = e
+          parts.push(this.node<A.Lit>(s, e, { type: 'Lit', value: this.src.slice(s, e) }))
+        } else break
+      }
+      if (parts.length === 0) this.error(`unexpected '${c}' in arithmetic`)
+      const word = this.node<A.Word>(start, this.pos, { type: 'Word', parts })
+      return this.node<A.ArithWord>(start, this.pos, { type: 'ArithWord', word })
+    }
+    this.error(this.eof() ? 'unexpected end of arithmetic expression' : `unexpected '${c}' in arithmetic expression`)
+  }
+}
+
+/** The literal value of a word if it contains only unquoted literal text. */
+export function literalOf(w: A.Word): string | null {
+  let s = ''
+  for (const p of w.parts) {
+    if (p.type === 'Lit') s += p.value
+    else return null
+  }
+  return s
+}
+
+/**
+ * The static value of a word if it involves no expansions (quotes allowed),
+ * e.g. `'a b'"c"` → `a bc`. Glob characters in unquoted parts are kept as-is.
+ */
+export function staticWordValue(w: A.Word): string | null {
+  let s = ''
+  for (const p of w.parts) {
+    switch (p.type) {
+      case 'Lit':
+      case 'SglQuoted':
+      case 'Escaped':
+        s += p.value
+        break
+      case 'DblQuoted':
+        for (const q of p.parts) {
+          if (q.type === 'Lit') s += q.value
+          else return null
+        }
+        break
+      default:
+        return null
+    }
+  }
+  return s
+}
+
+/** The `parseArithmetic` entry point used by the VM to re-parse textually expanded arithmetic. */
+export function parseArithmetic(text: string, firstId = 1_000_000_000): A.ArithExpr {
+  const p = new Parser(text, 0, { next: firstId }, text)
+  const expr = p.parseArithComma()
+  // ensure everything consumed
+  const rest = text.slice(p.pos).trim()
+  if (rest !== '') throw new ParseError(`syntax error in expression (error token is "${rest}")`, text, p.pos)
+  return expr
+}