@backbencher/brain 0.0.0-stage → 0.1.0

package/dist/real-bash-analyzer-SXSV67E2.js

@@ -0,0 +1,2201 @@
+import {
+  ASTEngine
+} from "./chunk-V44PGPA6.js";
+import "./chunk-BQ3OVQ3P.js";
+import "./chunk-SK6YVHFZ.js";
+import "./chunk-2BSKD7O3.js";
+import "./chunk-KAET47ZL.js";
+import "./chunk-KCDECRJY.js";
+import "./chunk-MLKGABMK.js";
+
+// src/ast/real-bash-analyzer.ts
+import { existsSync } from "fs";
+import * as path from "path";
+var BASH_REPO_ROOT = /* @__PURE__ */ new Map();
+function bashRepoRootOf(filePath) {
+  const abs = path.resolve(filePath);
+  const dir = path.dirname(abs);
+  const cached = BASH_REPO_ROOT.get(dir);
+  if (cached !== void 0) return cached;
+  let probe = dir;
+  for (let i = 0; i < 64; i++) {
+    if (existsSync(path.join(probe, ".git"))) {
+      BASH_REPO_ROOT.set(dir, probe);
+      return probe;
+    }
+    const parent = path.dirname(probe);
+    if (parent === probe) break;
+    probe = parent;
+  }
+  BASH_REPO_ROOT.set(dir, "");
+  return "";
+}
+function bashFileScopeOf(filePath) {
+  const root = bashRepoRootOf(filePath);
+  if (root === "") return "";
+  const rel = path.relative(root, path.resolve(filePath));
+  if (rel.startsWith("..") || rel === "") return "";
+  return rel.split(path.sep).join("/").split(".").join("_").split(":").join("_");
+}
+var SHELL_BUILTINS = /* @__PURE__ */ new Set([
+  "echo",
+  "printf",
+  "cd",
+  "pwd",
+  "exit",
+  "return",
+  "break",
+  "continue",
+  "shift",
+  "source",
+  ".",
+  "export",
+  "local",
+  "declare",
+  "typeset",
+  "readonly",
+  "set",
+  "unset",
+  "alias",
+  "unalias",
+  "trap",
+  "eval",
+  "exec",
+  "true",
+  "false",
+  "test",
+  "[",
+  "command",
+  "builtin",
+  "type",
+  "let",
+  "pushd",
+  "popd",
+  "dirs",
+  "wait",
+  "jobs",
+  "fg",
+  "bg",
+  "kill",
+  "read",
+  "readarray",
+  "mapfile",
+  "getopts",
+  "ulimit",
+  "umask",
+  "times",
+  "enable",
+  "help",
+  "hash",
+  "bind",
+  "compgen",
+  "complete",
+  "compopt",
+  "logout",
+  "suspend",
+  "caller",
+  "disown",
+  "shopt",
+  "history",
+  "fc",
+  "getopts",
+  "coproc",
+  // `:` is the POSIX no-op utility — a builtin, and also the shape an
+  // ERROR-recovered `command` can carry when the grammar lost the real command
+  // word (see isRecoveredCommandWord), so naming it here keeps a recovery
+  // artifact off the call graph as well.
+  ":"
+  // `sudo` is DELIBERATELY absent. It is an external binary that happens to be
+  // installed everywhere, not a shell builtin, and the pre-wave list filed it
+  // under builtins — which withheld the edge for `sudo docker build …` and left
+  // the privilege-escalation pattern as the only trace of the call. The pattern
+  // is still raised (see the classification block); the edge is emitted too.
+]);
+var DECLARATION_KEYWORDS = /* @__PURE__ */ new Set(["export", "local", "declare", "typeset", "readonly"]);
+var SHELL_RESERVED_WORDS = /* @__PURE__ */ new Set([
+  "if",
+  "then",
+  "else",
+  "elif",
+  "fi",
+  "case",
+  "esac",
+  "for",
+  "select",
+  "while",
+  "until",
+  "do",
+  "done",
+  "in",
+  "function",
+  "time",
+  "{",
+  "}",
+  "!",
+  "[[",
+  "]]",
+  "((",
+  "))",
+  "coproc"
+]);
+var SPECIAL_VAR_PUNCTUATION = /* @__PURE__ */ new Set(["@", "*", "?", "$", "#", "!", "_"]);
+var COMPUTED_EXPORT_NAME_PATTERN = "Computed Export Name";
+var SHELL_DEFINED_VARS = /* @__PURE__ */ new Set([
+  "BASH",
+  "BASHOPTS",
+  "BASHPID",
+  "BASH_ALIASES",
+  "BASH_ARGC",
+  "BASH_ARGV",
+  "BASH_ARGV0",
+  "BASH_CMDS",
+  "BASH_COMMAND",
+  "BASH_EXECUTION_STRING",
+  "BASH_LINENO",
+  "BASH_LOADABLES_PATH",
+  "BASH_REMATCH",
+  "BASH_SOURCE",
+  "BASH_SUBSHELL",
+  "BASH_VERSINFO",
+  "BASH_VERSION",
+  "COMP_CWORD",
+  "COMP_LINE",
+  "COMP_POINT",
+  "COMP_TYPE",
+  "COMP_WORDBREAKS",
+  "COMP_WORDS",
+  "COMP_KEY",
+  "COMP_WORDBREAKS",
+  "DIRSTACK",
+  "EPOCHREALTIME",
+  "EPOCHSECONDS",
+  "EUID",
+  "FUNCNAME",
+  "GROUPS",
+  "HISTCMD",
+  "HOSTNAME",
+  "HOSTTYPE",
+  "LINENO",
+  "LINES",
+  "MACHTYPE",
+  "MAIL",
+  "MAILCHECK",
+  "OLDPWD",
+  "OPTARG",
+  "OPTERR",
+  "OPTIND",
+  "OSTYPE",
+  "PIPESTATUS",
+  "PPID",
+  "PROMPT_COMMAND",
+  "PS0",
+  "PS1",
+  "PS2",
+  "PS3",
+  "PS4",
+  "PWD",
+  "RANDOM",
+  "SECONDS",
+  "SHELL",
+  "SHELLOPTS",
+  "SRANDOM",
+  "UID",
+  "OTEST"
+]);
+var READ_TARGET_COMMANDS = /* @__PURE__ */ new Set(["read", "mapfile", "readarray"]);
+var READ_VALUE_OPT_LETTERS = /* @__PURE__ */ new Set(["d", "e", "i", "n", "N", "p", "s", "t", "u", "O"]);
+var READ_OPTION_LETTERS = /* @__PURE__ */ new Set(["r", "a", "d", "e", "i", "n", "N", "p", "s", "t", "u", "O", "C", "c"]);
+var isShellIdentifierName = (text) => {
+  if (text.length === 0) return false;
+  const first = text.charCodeAt(0);
+  const firstOk = first >= 97 && first <= 122 || first >= 65 && first <= 90 || first === 95;
+  if (!firstOk) return false;
+  for (let i = 1; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    if (c >= 97 && c <= 122 || c >= 65 && c <= 90 || c >= 48 && c <= 57 || c === 95) continue;
+    return false;
+  }
+  return true;
+};
+var opensWithDoubleParen = (text) => text.length >= 2 && text.charCodeAt(0) === 40 && text.charCodeAt(1) === 40;
+var opensWithArithmeticExpansion = (text) => text.length >= 3 && text.charCodeAt(0) === 36 && opensWithDoubleParen(text.slice(1));
+var endsWithDoubleParen = (text) => {
+  const t = text.trim();
+  return t.length >= 2 && t.charCodeAt(t.length - 2) === 41 && t.charCodeAt(t.length - 1) === 41;
+};
+var isArithmeticCompoundText = (text) => opensWithDoubleParen(text) && endsWithDoubleParen(text);
+var isCommandNameText = (text) => {
+  if (text.length === 0) return false;
+  if (SHELL_RESERVED_WORDS.has(text)) return false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    if (c >= 48 && c <= 57) {
+      let allDigits = true;
+      for (let j = 0; j < text.length; j++) {
+        const d = text.charCodeAt(j);
+        if (d < 48 || d > 57) {
+          allDigits = false;
+          break;
+        }
+      }
+      if (allDigits) return false;
+      break;
+    }
+  }
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    if (c === 36 || c === 96 || c === 34 || c === 39) return false;
+    if (c === 32 || c === 9 || c === 10 || c === 13) return false;
+    if (c === 59 || c === 124 || c === 38) return false;
+    if (c === 40 || c === 41 || c === 60 || c === 62) return false;
+  }
+  return true;
+};
+var RealBashAnalyzer = class {
+  analyze(rootNode, content, filePath) {
+    const symbols = [];
+    const relationships = [];
+    const imports = [];
+    const patterns = /* @__PURE__ */ new Set();
+    const scriptName = this.scriptNameOf(filePath);
+    const scriptRange = this.nodeToRange(rootNode);
+    symbols.push({
+      name: scriptName,
+      kind: ASTEngine.SymbolKind.Module,
+      range: scriptRange,
+      visibility: "public",
+      metadata: { bashSpecific: true, isScript: true, scriptPath: filePath }
+    });
+    const declaredSymbols = /* @__PURE__ */ new Set();
+    const declSites = /* @__PURE__ */ new Map();
+    const localFunctions = this.collectFunctionNames(rootNode);
+    const scopeOwners = localFunctions;
+    const functionStack = [];
+    const functionPriorDeclaration = /* @__PURE__ */ new Map();
+    const functionParams = /* @__PURE__ */ new Map();
+    const relKeys = /* @__PURE__ */ new Set();
+    let cyclomaticComplexity = 1;
+    const scopeComplexity = /* @__PURE__ */ new Map();
+    let hasStrictError = false;
+    let usesEval = false;
+    let usesSudo = false;
+    let hasCurlPipeBash = false;
+    let hasChmod777 = false;
+    let hasRmRoot = false;
+    const enclosingFunction = () => functionStack[functionStack.length - 1] ?? "";
+    const relSource = () => enclosingFunction() || scriptName;
+    const evidenceClassFor = (type) => {
+      if (type === ASTEngine.RelationshipType.Imports || type === ASTEngine.RelationshipType.References) return "import_based";
+      if (type === ASTEngine.RelationshipType.Uses) return "usage_contextual";
+      return "structural";
+    };
+    const addRel = (source, target, type, confidence, line, metadata = {}) => {
+      if (!Number.isInteger(line) || line < 1) return;
+      const key = `${source}\0${type}\0${target}\0${line}`;
+      if (relKeys.has(key)) return;
+      relKeys.add(key);
+      relationships.push({
+        source,
+        target,
+        type,
+        confidence,
+        metadata: { evidenceClass: evidenceClassFor(type), ...metadata },
+        line_number: line
+      });
+    };
+    const stack = [{ node: rootNode, exit: false }];
+    while (stack.length > 0) {
+      const { node, exit } = stack.pop();
+      if (!node) continue;
+      if (exit) {
+        if (node.type === "function_definition") functionStack.pop();
+        continue;
+      }
+      stack.push({ node, exit: true });
+      if (node.type === "if_statement" || node.type === "for_statement" || node.type === "while_statement" || node.type === "case_item" || node.type === "elif_clause" || node.type === "test_command" || node.type === "binary_expression" || node.type === "c_style_for_statement") {
+        cyclomaticComplexity++;
+        const scope = enclosingFunction() || scriptName;
+        scopeComplexity.set(scope, (scopeComplexity.get(scope) ?? 0) + 1);
+      }
+      if (node.type === "function_definition") {
+        const parentFn = enclosingFunction();
+        this.extractFunction(node, symbols, parentFn || scriptName);
+        const name = this.functionName(node);
+        if (name) {
+          functionStack.push(name);
+          if (!functionParams.has(name)) functionParams.set(name, /* @__PURE__ */ new Set());
+          const prior = functionPriorDeclaration.get(name);
+          if (prior !== void 0) {
+            addRel(
+              parentFn || scriptName,
+              name,
+              ASTEngine.RelationshipType.Overrides,
+              1,
+              node.startPosition.row + 1,
+              {
+                bashSpecific: true,
+                overridesLine: prior,
+                redefinition: true,
+                evidenceClass: "structural"
+              }
+            );
+          }
+          functionPriorDeclaration.set(name, node.startPosition.row + 1);
+        }
+        patterns.add("Function Definition");
+      } else if (node.type === "command_substitution") {
+        patterns.add("Command Substitution");
+      } else if (node.type === "subshell") {
+        patterns.add("Subshell");
+      } else if (node.type === "pipeline") {
+        const names = [];
+        const collect = (n) => {
+          for (let i = 0; i < n.namedChildCount; i++) {
+            const child = n.namedChild(i);
+            if (!child) continue;
+            if (child.type === "command") {
+              const name = this.commandNameOf(child);
+              if (name) names.push(name);
+            } else if (child.type !== "pipeline") {
+              collect(child);
+            }
+          }
+        };
+        collect(node);
+        const hasDownloader = names.some((n) => n === "curl" || n === "wget");
+        const hasShell = names.some((n) => n === "bash" || n === "sh" || n === "zsh" || n === "dash");
+        if (hasDownloader && hasShell) {
+          hasCurlPipeBash = true;
+          patterns.add("Insecure Pipe Execution");
+        }
+      } else if (node.type === "simple_expansion" || node.type === "expansion" || // BD-gap closure: a variable read inside an arithmetic context is a
+      // read. `$((i + 1))`, `((count++))` and `for ((i=0; i<n; i++))` all
+      // name real project variables and the analyzer reached none of them:
+      // `expansionVariableName` was only consulted for the two string
+      // expansion forms, so every arithmetic operand was invisible. The
+      // census then named `arithmetic_expression` as a fourth form to add —
+      // a literal the pinned grammar does not have, which the rewritten
+      // F8 gate reported as a dead branch on the same day it was written.
+      // That is the gate working: a plausible guess, refused by evidence.
+      node.type === "arithmetic_expansion" || node.type === "postfix_expression" || node.type === "c_style_for_statement" || // `((i < 5))` — an arithmetic COMMAND, whose operands are real reads. The
+      // five node types above cover `$((…))`, `for ((…))` and `((i++))`, and none
+      // of them covers the plain form, because the pinned grammar holds a bare
+      // `(( … ))` in a `compound_statement` wrapping a `binary_expression` /
+      // `unary_expression` / plain `variable_name` — none of which is dispatched.
+      // The asymmetry was a grammar-shape accident rather than a fact about bash:
+      // `((i++))` produced a `uses` edge only because its operand happened to
+      // arrive as a `postfix_expression`, and `((i < 5))` on the same line
+      // produced none. Recorded as limitation 7 and measured before it was
+      // changed: `probe-bash-arithmetic-operands.mts` derives the delta from the
+      // tree BEFORE the edit and predicts +70 `uses` edges on the 400-file
+      // hash-order sample — 89 arithmetic compound_statements in 32 files, 126
+      // operand name nodes, 115 distinct (target, line) pairs, 45 of them
+      // already published through the five dispatched types and 70 not, 54 of
+      // those 70 naming a variable the same file declares. The census then
+      // measured uses 7,786 -> 7,856 and total relationships 16,984 -> 17,054,
+      // which is the 70. NO other type moves: this adds reads, no symbols and no
+      // edges of any other type.
+      //
+      // The first run of that probe predicted 72 and the census said 70, and the
+      // probe was wrong: it deduplicated operands per STATEMENT while `addRel`'s
+      // key carries no statement identity, so `(( i++ )); (( i-- ))` on one line
+      // counted twice. The instrument now dedupes per file.
+      //
+      // The predicate is the node's own text, because `compound_statement` is also
+      // a block: `then <block> fi` and `do <body> done` reach the same node type,
+      // and their reads are already dispatched — `simple_expansion`, `expansion`,
+      // `arithmetic_expansion`, `postfix_expression` and `c_style_for_statement`
+      // all sit under them — so a block contributes no edge a block-read would
+      // duplicate. The guard keeps the claim true rather than preventing a
+      // duplicate, and its own population is measured: 792 compound_statements
+      // are excluded by it on the 400-file sample, of which 0 open `((`.
+      //
+      // That 0 is also why no mutant covers the CLOSING half of the test. A
+      // malformed `(( a < 2` does not arrive as a compound_statement at all — the
+      // grammar produces an ERROR node for it (verified on the tree) — so
+      // `opensWithDoubleParen` alone has an empty reachable population on this
+      // corpus and a mutant dropping `endsWithDoubleParen` would survive. The
+      // condition is kept because `( (date) )` is a subshell and `((x))` is
+      // arithmetic, and it is declared rather than covered by a mutant that
+      // cannot fail.
+      node.type === "compound_statement" && isArithmeticCompoundText(node.text)) {
+        this.emitVariableUses(node, symbols, relSource, addRel, declaredSymbols, functionStack, functionParams, declSites, scriptName);
+      } else if (node.type === "for_statement") {
+        this.extractImplicitBinding(node, symbols, enclosingFunction() || scriptName, declaredSymbols, scopeOwners, declSites);
+      } else if (node.type === "variable_assignment") {
+        if (node.parent?.type !== "declaration_command") {
+          this.extractAssignment(node, symbols, enclosingFunction() || scriptName, declaredSymbols, scopeOwners, declSites);
+        }
+      } else if (node.type === "declaration_command") {
+        this.extractDeclaration(node, symbols, enclosingFunction() || scriptName, functionParams, declaredSymbols, scopeOwners, addRel, declSites, patterns);
+      } else if (node.type === "command") {
+        this.extractImplicitBinding(node, symbols, enclosingFunction() || scriptName, declaredSymbols, scopeOwners, declSites);
+        this.extractCommand(node, symbols, imports, patterns, {
+          addRel,
+          relSource,
+          scriptName,
+          localFunctions,
+          scopeOwners,
+          flags: {
+            usesEval: () => usesEval,
+            usesSudo: () => usesSudo,
+            hasChmod777: () => hasChmod777,
+            hasRmRoot: () => hasRmRoot,
+            hasStrictError: () => hasStrictError
+          },
+          setFlag: {
+            eval: (v) => usesEval = v,
+            sudo: (v) => usesSudo = v,
+            chmod777: (v) => hasChmod777 = v,
+            rmRoot: (v) => hasRmRoot = v,
+            strictError: (v) => hasStrictError = v
+          }
+        });
+      }
+      for (let i = node.childCount - 1; i >= 0; i--) {
+        const child = node.child(i);
+        if (child) stack.push({ node: child, exit: false });
+      }
+    }
+    for (const sym of symbols) {
+      if (sym.kind !== ASTEngine.SymbolKind.Module && sym.kind !== ASTEngine.SymbolKind.Function) continue;
+      const points = scopeComplexity.get(sym.name);
+      if (points === void 0) continue;
+      sym.complexity = 1 + points;
+    }
+    for (let i = 0; i < symbols.length; i++) {
+      const sym = symbols[i];
+      if (sym.kind === ASTEngine.SymbolKind.Function) {
+        const params = functionParams.get(sym.name);
+        if (params && params.size > 0) {
+          const paramObjects = [];
+          for (const p of params) paramObjects.push({ name: p, type: "any" });
+          sym.parameters = paramObjects;
+        }
+      }
+      if (sym.ownerName) {
+        addRel(sym.ownerName, sym.name, ASTEngine.RelationshipType.Contains, 1, this.nameLineOf(sym), {
+          bashSpecific: true
+        });
+      }
+    }
+    const functionDeclLines = /* @__PURE__ */ new Map();
+    const namesWithNonFunctionDecl = /* @__PURE__ */ new Set();
+    for (const sym of symbols) {
+      const name = sym.name;
+      if (sym.kind === ASTEngine.SymbolKind.Function) {
+        const line = this.nameLineOf(sym);
+        const list = functionDeclLines.get(name);
+        if (list) {
+          if (!list.some((e) => e.line === line)) list.push({ line, kind: String(sym.kind) });
+        } else functionDeclLines.set(name, [{ line, kind: String(sym.kind) }]);
+      } else if (name.length > 0 && !namesWithNonFunctionDecl.has(name)) {
+        namesWithNonFunctionDecl.add(name);
+      }
+    }
+    const assignedNamesInFile = /* @__PURE__ */ new Set();
+    for (const k of declaredSymbols) {
+      const i = k.indexOf("\0");
+      if (i >= 0) assignedNamesInFile.add(k.slice(i + 1));
+    }
+    for (const rel of relationships) {
+      if (rel.type !== ASTEngine.RelationshipType.Uses) continue;
+      const meta = rel.metadata;
+      if (meta.isAssignedInFile !== void 0) continue;
+      if (assignedNamesInFile.has(String(rel.target ?? ""))) meta.isAssignedInFile = true;
+    }
+    for (const rel of relationships) {
+      if (rel.type !== ASTEngine.RelationshipType.Uses) continue;
+      const meta = rel.metadata;
+      if (meta.targetResolution !== void 0) continue;
+      const resolved = this.resolveDeclaration(
+        declSites,
+        String(rel.target ?? ""),
+        String(rel.source ?? ""),
+        rel.line_number,
+        scriptName
+      );
+      if (resolved) Object.assign(meta, resolved);
+    }
+    for (const rel of relationships) {
+      if (rel.type !== ASTEngine.RelationshipType.Uses) continue;
+      const meta = rel.metadata;
+      if (meta.targetResolution !== void 0) continue;
+      const name = String(rel.target ?? "");
+      if (!functionDeclLines.has(name)) continue;
+      const resolved = this.resolveReadAgainstFunctionSymbol(
+        declSites,
+        name,
+        String(rel.source ?? ""),
+        rel.line_number,
+        scriptName
+      );
+      if (resolved) Object.assign(meta, resolved);
+    }
+    for (const rel of relationships) {
+      if (rel.type !== ASTEngine.RelationshipType.Calls) continue;
+      const meta = rel.metadata;
+      if (meta.targetResolution !== void 0) continue;
+      if (meta.isFunctionCall !== true) {
+        if (meta.commandInErrorRecovery === true) {
+          if ((declSites.get(String(rel.target ?? ""))?.length ?? 0) >= 2) meta.targetResolution = "ambiguousInFile";
+          continue;
+        }
+        const name = String(rel.target ?? "");
+        if (!namesWithNonFunctionDecl.has(name)) continue;
+        meta.targetResolution = "commandNameIsExternal";
+        meta.collidesWithLocalDeclaration = true;
+        continue;
+      }
+      const resolved = this.resolveFunctionTarget(
+        functionDeclLines,
+        String(rel.target ?? ""),
+        rel.line_number,
+        namesWithNonFunctionDecl
+      );
+      if (resolved) Object.assign(meta, resolved);
+    }
+    for (const rel of relationships) {
+      if (rel.type !== ASTEngine.RelationshipType.Exports) continue;
+      const meta = rel.metadata;
+      if (meta.targetResolution !== void 0) continue;
+      const name = String(rel.target ?? "");
+      if (functionDeclLines.has(name)) continue;
+      const resolved = this.resolveDeclaration(
+        declSites,
+        name,
+        String(rel.source ?? ""),
+        rel.line_number,
+        scriptName
+      );
+      if (resolved) Object.assign(meta, resolved);
+    }
+    const fileScope = bashFileScopeOf(filePath);
+    if (fileScope !== "") {
+      const occurrences = /* @__PURE__ */ new Map();
+      for (const sym of symbols) {
+        const n = String(sym.name ?? "");
+        if (n.length > 0) occurrences.set(n, (occurrences.get(n) ?? 0) + 1);
+      }
+      const resplellable = {
+        // command position: a function declared in this file answers it (bash resolves functions
+        // before PATH); a variable does NOT, which is what `commandNameIsExternal` records.
+        calls: (k) => k === "function",
+        uses: (k) => k === "variable" || k === "constant",
+        exports: (k) => k === "variable" || k === "constant" || k === "function",
+        overrides: (k) => k === "function"
+      };
+      const published = /* @__PURE__ */ new Set();
+      for (const sym of symbols) {
+        const n = String(sym.name ?? "");
+        if (n.length === 0) continue;
+        published.add(`${n}|${Number(sym.range?.startLine ?? 0)}|${String(sym.kind ?? "")}`);
+      }
+      for (const rel of relationships) {
+        const kindRule = resplellable[String(rel.type ?? "")];
+        if (kindRule === void 0) continue;
+        const target = String(rel.target ?? "");
+        if (target.length === 0) continue;
+        const r = this.bindingInEffect(declSites, target, String(rel.source ?? ""), rel.line_number, scriptName);
+        if (r === null || r === "ambiguous") continue;
+        if (!kindRule(r.kind)) continue;
+        const symbolKind = r.kind === "function" ? ASTEngine.SymbolKind.Function : r.kind === "constant" ? ASTEngine.SymbolKind.Constant : ASTEngine.SymbolKind.Variable;
+        if (!published.has(`${target}|${r.line}|${symbolKind}`)) continue;
+        const owner = r.owner.length > 0 ? r.owner : scriptName;
+        rel.target = `${owner}.${target}`;
+      }
+    }
+    let security = 50;
+    let maintainability = 50;
+    if (hasStrictError) {
+      security += 20;
+      maintainability += 10;
+    }
+    if (usesEval) security -= 30;
+    if (usesSudo) security -= 10;
+    if (hasCurlPipeBash) security -= 25;
+    if (hasChmod777) security -= 20;
+    if (hasRmRoot) security -= 40;
+    let hasFunction = false;
+    for (let i = 0; i < symbols.length; i++) {
+      if (symbols[i].kind === ASTEngine.SymbolKind.Function) {
+        hasFunction = true;
+        break;
+      }
+    }
+    if (hasFunction) maintainability += 20;
+    if (cyclomaticComplexity > 10) maintainability -= 15;
+    const score = Math.round((security + maintainability) / 2);
+    const patternsArray = [...patterns];
+    const frameworks = this.detectFrameworks(patternsArray);
+    return {
+      language: "bash",
+      symbols,
+      relationships,
+      imports,
+      exports: symbols.filter((s) => s.metadata?.isExported).map((s) => ({
+        name: s.name,
+        type: s.kind,
+        range: s.range,
+        isType: false
+      })),
+      // Syntax errors are engine-owned (engine.ts merges treeErrors) — this
+      // analyzer never duplicates them.
+      metadata: {
+        complexity: symbols.length + relationships.length,
+        linesOfCode: content.split("\n").length,
+        cyclomaticComplexity,
+        framework: frameworks.length > 1 ? frameworks[1] : "Bash Script",
+        patterns: patternsArray,
+        detectedFrameworks: frameworks,
+        frameworkPatterns: [{ framework: "Bash", patterns: patternsArray }],
+        architecturalInsights: this.generateInsights(patternsArray, hasStrictError),
+        architecturalScore: score,
+        codeQuality: score >= 80 ? "Excellent" : score >= 60 ? "Good" : "Fair",
+        hasTypeInference: false,
+        // A framework claim must be earned. This used to be an unconditional
+        // `true` on every bash file, which asserted framework intelligence for a
+        // file that had none; it is now true only when a framework beyond the
+        // language itself was actually detected from the file's own commands.
+        hasFrameworkIntelligence: frameworks.length > 1,
+        securityScore: Math.min(100, Math.max(0, security)),
+        maintainabilityScore: Math.min(100, Math.max(0, maintainability)),
+        analysisVersion: "5.0-bash-module-owner-per-site-lines"
+      }
+    };
+  }
+  // -------------------------------------------------------------- functions
+  /** BD2: the file's own basename, extension included. */
+  scriptNameOf(filePath) {
+    const normalized = filePath.split("\\").join("/");
+    const base = normalized.slice(normalized.lastIndexOf("/") + 1);
+    return base.length > 0 ? base : "script.sh";
+  }
+  /** The 1-based line a symbol's NAME is written on (M60 #921). */
+  nameLineOf(sym) {
+    const line = sym.range?.startLine;
+    return typeof line === "number" && line >= 1 ? line : 1;
+  }
+  /** Record WHERE a name was declared. One entry per (owner, name), added at the
+   * same place `declaredSymbols` is, so the two indexes cannot disagree. */
+  noteDeclaration(declSites, name, owner, line, kind) {
+    if (!Number.isInteger(line) || line < 1) return;
+    const list = declSites.get(name);
+    if (list) list.push({ owner, line, kind });
+    else declSites.set(name, [{ owner, line, kind }]);
+  }
+  /**
+   * Which declaration does an edge naming `name` at `useLine` in `useOwner` mean?
+   *
+   * The rule is a lexical-scope chain walked OUTWARD, and the order of the two
+   * halves is load-bearing:
+   *
+   *   1. Walk the scope chain from the use's own function out to the file. In the
+   *      first scope that has a declaration of `name` AT OR BEFORE the use site,
+   *      the nearest such line is the answer — and the walk STOPS there. A use is
+   *      not answered by a declaration in a scope it does not belong to.
+   *   2. If no scope in the chain has one, the analyzer publishes nothing and
+   *      says `targetResolution: "ambiguousInFile"`.
+   *
+   * Both halves were arrived at by being wrong first, and the fixture
+   * `ambiguous-target-resolution.sh` is what caught each:
+   *
+   *   The first version had no scope chain at all — it took every declaration of
+   *   the name in the file and picked the nearest preceding one. So `echo "$X"` at
+   *   line 45 inside `read_early`, whose own assignment to X is at line 46,
+   *   resolved to line 37 — a declaration inside a DIFFERENT function. That is
+   *   wrong twice over: bash does not let one function's assignment to a local
+   *   shadow another function's, and the fixture's own comment says the analyzer
+   *   must not point at a declaration that does not exist yet at the use site.
+   *
+   *   The second version had the chain but walked it in the wrong direction for
+   *   the "no declaration yet" case, and would fall through to a nearer
+   *   declaration in an unrelated scope instead of the file-scope one that really
+   *   is the value in effect.
+   *
+   * `declSites` keys only the first declaration of each (owner, name), because
+   * that is exactly what the collectors publish — a second `X=1` in the same
+   * function is a reassignment, not a declaration. So "nearest preceding" within
+   * a scope always has one candidate, and the ties the corpus measurement found
+   * (49 of 1,879 edges) can only arise between scopes.
+   *
+   * The three outcomes are DISTINCT on purpose, because "the analyzer could not
+   * say" and "the analyzer saw several and declined to pick" are different facts:
+   *
+   *   resolved   one candidate — `targetLine` + `targetKind` + the rule named, so
+   *              the fact can be checked rather than trusted.
+   *   ambiguous  two or more candidates and the rule cannot separate them — no
+   *              line is published, because publishing one of several would be
+   *              exactly the invented attribution this exists to prevent.
+   *   undefined  fewer than two declarations in the file, so the name is not
+   *              ambiguous and the edge needs nothing added to it.
+   *
+   * The `undefined` case is why this adds metadata to 15.2% of `uses` edges
+   * rather than all of them: an edge whose target is unique in its file carries
+   * no new information, and 80,851 `uses` edges on the whole corpus would each
+   * grow three keys to say so.
+   */
+  resolveDeclaration(declSites, name, useOwner, useLine, fileOwner) {
+    const cands = declSites.get(name);
+    if (!cands || cands.length < 2) return void 0;
+    const r = this.bindingInEffect(declSites, name, useOwner, useLine, fileOwner);
+    if (r === null || r === "ambiguous") return { targetResolution: "ambiguousInFile" };
+    return {
+      targetLine: r.line,
+      targetKind: r.kind,
+      targetResolution: r.innermost ? "innermostScope" : "outerScope"
+    };
+  }
+  /**
+   * WHICH DECLARATION IS IN EFFECT WHERE THE EDGE POINTS — the lane's scope-chain rule, in ONE
+   * place, because two consumers now need it and two copies of a resolution rule are two rules.
+   *
+   *   `null`        the file declares this name NOWHERE — there is nothing to name
+   *   `"ambiguous"` the name is declared, but not exactly one of them is in effect here
+   *   the binding   the nearest declaration at-or-before the use, in the innermost scope that
+   *                 has one, with `innermost` saying which scope answered
+   *
+   * Bash's own rule drives the walk: a function or variable defined LATER in the file does not
+   * answer a use that precedes it, and a use inside a function is answered by that function's own
+   * scope before the script's. That is why the respell pass below can reach a declaration WITHOUT
+   * guessing — and why it must not respell an edge whose binding is `"ambiguous"` or `null`.
+   */
+  bindingInEffect(declSites, name, useOwner, useLine, fileOwner) {
+    const cands = declSites.get(name);
+    if (!cands || cands.length === 0) return null;
+    const scopes = useOwner === fileOwner ? [fileOwner] : [useOwner, fileOwner];
+    for (const scope of scopes) {
+      const atOrBefore = cands.filter((c) => c.owner === scope && c.line <= useLine);
+      if (atOrBefore.length === 0) continue;
+      const nearest = Math.max(...atOrBefore.map((c) => c.line));
+      const winners = atOrBefore.filter((c) => c.line === nearest);
+      if (winners.length !== 1) return "ambiguous";
+      return { line: winners[0].line, kind: winners[0].kind, owner: scope, innermost: scope === useOwner };
+    }
+    return "ambiguous";
+  }
+  /**
+   * Publish, on a `uses` edge, that this file binds `name` as a VARIABLE nowhere.
+   *
+   * ## Why this is not the same as "external"
+   *
+   * The obvious field name here is `isExternal`, and it would be a false claim on a
+   * measured population. Measured on the pinned corpus — 600 `*.sh` files in path order,
+   * production `parseFile`, analyzer digest `6d5542aa6d6640e2` — 490 `uses` edges go to a
+   * name no file in the window declares, and a whole-corpus pass over all 3,748 tracked
+   * bash files found a real declaration for 101 of them:
+   *
+   *     consul/test/integration/connect/envoy/defaults.sh   DEFAULT_REQUIRED_SERVICES  32 edges
+   *     fsharp/eng/common/tools.sh                            HOME                       48 edges
+   *     consul/test/integration/connect/envoy/run-tests.sh   CASE_DIR, CLUSTER, XDS_TARGET
+   *
+   * Those 101 reads are not external. They read a variable that a `source`d file assigns,
+   * and a single-file analyzer cannot see it. Calling them external would tell a consumer
+   * to stop looking for a declaration that exists.
+   *
+   * So the published fact is the one that is true and checkable: **no variable, alias or
+   * local in THIS FILE binds this name.**
+   *
+   * ## Why the field says "variable"
+   *
+   * `declSites` holds variables, aliases and locals and never functions — the same
+   * limitation `resolveReadAgainstFunctionSymbol` is built around (a `$name` read cannot
+   * denote a function). So for a name declared only as a function, "no declaration in this
+   * file" is FALSE while "no VARIABLE binding in this file" is TRUE. The field is named for
+   * the index it is derived from so the row cannot be over-read, and the distinction is the
+   * one a consumer needs: a read that no variable binds is unresolved for a different
+   * reason than one that binds ambiguously, and `targetResolution` already reports the
+   * latter.
+   *
+   * Published on both states, as `resolvedWithinFile` is, so a consumer reads one field
+   * rather than inferring the negative from an absent one.
+   */
+  declareAbsenceOfVariableBinding(declSites, name) {
+    const cands = declSites.get(name);
+    return { variableDeclaredInFile: cands !== void 0 && cands.length > 0 };
+  }
+  /**
+   * THE SHELL'S OWN VARIABLE NAMES, ON THE KEY THE INCOMING GATE READS — the one part of this
+   * lane's residual an analyzer can answer.
+   *
+   * ## The defect this closes is the fleet's finding (a), and this lane had it
+   *
+   * The fact was already computed: `isShellDefined` (`SHELL_DEFINED_VARS`, the interpreter's own
+   * name space) is set on every read of a name the shell binds. But `script/m14/incoming-rule.ts`
+   * reads external claims from a CLOSED list of keys (`EXTERNAL_KEYS`, `:56-66`) and
+   * `isShellDefined` is not one of them — so on the gate's own 400-file stride **125 unresolved
+   * `uses` edges carried the reason and `extOK` read 0**, the spelling problem the fleet brief
+   * records for html's `isExternalResource`. The reason is republished here as a CLAIM
+   * (`isExternal`, the key BD12 already uses for path-invoked commands) with the evidence naming
+   * which list spoke.
+   *
+   * ## Why this is sound where the CALL marker was withdrawn (and stays withdrawn)
+   *
+   * `SHELL_DEFINED_VARS` is the shell's name space, not a guess about the corpus: `BASH_SOURCE`,
+   * `PIPESTATUS`, `UID`, `SECONDS` … are bound by the interpreter running the script, so no file
+   * of any project declares them and the claim cannot be refuted by a sourced library the way a
+   * bare command name can (a file may define `grep` as a function — measured 82 of 435 refuted,
+   * which is why `externalCommandEvidence` below stayed path-invoked only and
+   * `bash/incoming-external-marker-bd12` forbids the wider marker).
+   * MEASURED on this population with `probe-bash-residual-causes.mts --repo-wide` (all 3,178
+   * admitted files of the 118 sampled repositories parsed into a declaration index): **123 of the
+   * 125 marked edges name nothing the project declares; 2 do** (`HOSTNAME` read in
+   * `kubernetes/cluster/addons/addon-manager/kube-addons.sh` while another file of that project
+   * binds it) — the false-in-fact class, reported rather than hidden, and the same shape the `c`
+   * lane published (55 of 2,686, its `zig`/musl counter-example).
+   *
+   * ## The guard, and why it is not optional
+   *
+   * NOT EMITTED WHEN THIS FILE ITSELF BINDS THE NAME. `HOSTNAME=$(hostname)` makes a later
+   * `$HOSTNAME` a read of a PROJECT variable, and the claim would then be false about the file in
+   * hand. The guard asks the question `variableDeclaredInFile` already answers, from the same
+   * `declSites` index — one rule, not two.
+   *
+   * ## What the claim can and cannot do to the table
+   *
+   * `classifyEdge` reaches the verifier only where the key space declares NOTHING by that name
+   * (`incoming-rule.ts:1147`), and a bare identifier is looked up directly (`:815`) — so the
+   * outcome is `externalVerified` (the project confirms it) or, if a declaration exists,
+   * `externalRefuted`, which counts AGAINST the lane. It can never raise `resolved`, never turn an
+   * ambiguous edge into anything, and never touch `collRes` or the binding-intent split.
+   */
+  externalShellVariableEvidence(name, declSites) {
+    if (!SHELL_DEFINED_VARS.has(name)) return {};
+    const cands = declSites.get(name);
+    if (cands !== void 0 && cands.length > 0) return {};
+    return { isExternal: true, externalEvidence: "shellDefinedVariable" };
+  }
+  /**
+   * A `$name` read in a file that also declares `name` as a FUNCTION.
+   *
+   * `resolveDeclaration` declines here, and correctly so: it is asked "is this name
+   * ambiguous in this file?" and `declSites` — variables, aliases and locals, never
+   * functions — says no. The ambiguity a consumer actually faces is against the
+   * PUBLISHED symbol table, which holds both.
+   *
+   * The rule is the language's, not a preference: `$name` is a parameter expansion,
+   * it reads a variable, and a function is not reachable through `$`. So the
+   * function symbol is excluded as a candidate and the SAME outward scope walk
+   * `resolveDeclaration` performs runs over what remains. One walk, called twice
+   * over two different candidate sets — not a second implementation of the walk,
+   * which is how two rules drift apart.
+   *
+   * Declines, publishing no line, when the walk finds nothing at or before the use
+   * site or finds a tie: the same two refusals `resolveDeclaration` makes, for the
+   * same reason. In that case the edge carries `ambiguousInFile`, which is the
+   * honest row — the name is genuinely claimed by two published declarations and
+   * this edge declines to say which.
+   */
+  resolveReadAgainstFunctionSymbol(declSites, name, useOwner, useLine, fileOwner) {
+    const cands = declSites.get(name);
+    if (!cands || cands.length === 0) return void 0;
+    const scopes = useOwner === fileOwner ? [fileOwner] : [useOwner, fileOwner];
+    for (const scope of scopes) {
+      const atOrBefore = cands.filter((c) => c.owner === scope && c.line <= useLine);
+      if (atOrBefore.length === 0) continue;
+      const nearest = Math.max(...atOrBefore.map((c) => c.line));
+      const winners = atOrBefore.filter((c) => c.line === nearest);
+      if (winners.length !== 1) return { targetResolution: "ambiguousInFile" };
+      return {
+        targetLine: winners[0].line,
+        targetKind: winners[0].kind,
+        targetResolution: "readCannotBeAFunction"
+      };
+    }
+    return { targetResolution: "ambiguousInFile" };
+  }
+  /**
+   * Which FUNCTION does a `calls` edge at `useLine` naming `name` reach?
+   *
+   * The sibling of `resolveDeclaration`, over functions rather than variables, and
+   * deliberately not a shared code path: `declSites` keys variables, aliases and
+   * locals and never functions, so the two indexes have different contents and a
+   * shared body would be a claim about one of them dressed as a claim about both.
+   *
+   * bash has no nested function scope, so the scope chain `resolveDeclaration`
+   * walks does not exist here and is not faked. The language rule is one step:
+   * a name resolves to the most recent definition executed before the call, which
+   * for a script read top to bottom is the latest definition AT OR BEFORE the call
+   * site. `overrides` already publishes that a redefinition happened and both
+   * lines; this publishes which one a given call reaches.
+   *
+   * The three outcomes are the same three `resolveDeclaration` publishes, and they
+   * are distinct on purpose — "resolved", "there is more than one at the same
+   * line" and "every definition is after the call" are different facts, and a
+   * consumer cannot tell them apart if they collapse into one row:
+   *
+   *   latestDefinitionBeforeUse  one candidate — `targetLine` + `targetKind`, so
+   *                              the fact can be checked against the symbol table
+   *                              instead of trusted.
+   *   commandNameIsAFunction     exactly ONE function declaration, and the name is
+   *                              also declared as something that is not a function.
+   *                              Position is irrelevant here and deliberately so: a
+   *                              COMMAND position cannot denote a variable at all,
+   *                              so unlike a `uses` edge there is no "declared
+   *                              after the use site" case to decline. Measured at
+   *                              105 whole-corpus edges (swift-nio/scripts/
+   *                              nio-diagnose:398 `nio_pids` against variable@136
+   *                              and function@151; mvdan-sh/syntax/typedjson/
+   *                              testdata/roundtrip/file.sh `foo` against
+   *                              function@19 and variable@20).
+   *   commandNameIsExternal      NOT this function. Published by the CALLER, not
+   *                              here: `isFunctionCall` is false and the name is
+   *                              declared in this file as something that is not a
+   *                              function, so a name-matching consumer has
+   *                              candidates that are not this edge's target. The
+   *                              sibling of `commandNameIsAFunction` and the same
+   *                              fact seen from the other side — there the
+   *                              function is the answer, here nothing local is.
+   *                              2 whole-corpus edges (`xargs` in
+   *                              ohmyzsh/plugins/pip/pip.plugin.zsh at 107/115).
+   *   ambiguousInFile            two declarations on the same line, which the
+   *                              published line cannot separate. No line: picking
+   *                              one would be the invented attribution.
+   *   declaredAfterUse           every definition of the name is below the call
+   *                              site, so none of them is in effect there. bash
+   *                              permits the forward reference — the callee may be
+   *                              defined before the caller's body runs — so this
+   *                              says what was observed and publishes no line
+   *                              rather than pretending the text order settles it.
+   *
+   * The name is only ambiguous at all if there are two or more FUNCTION
+   * declarations of it, or one function plus a declaration of another kind. Fewer
+   * than that and nothing is added: 55,241 `calls` edges on the whole corpus and
+   * only the 236 whose target the published symbol table answers to twice grow a
+   * key.
+   *
+   * `targetKind` is read off the PUBLISHED symbol rather than written as a literal.
+   * The first version wrote the literal `"Function"` and the published kind is
+   * `"function"` (`SymbolKind.Function`, src/ast/types.ts:11), so every edge it
+   * touched carried a `targetKind` that matched nothing: the attribution pointed at
+   * a real line and a kind no symbol carries, and a consumer filtering on kind
+   * discarded the answer. `probe-bash-published-resolvability.mts` caught it as 6
+   * edges where applying the published fields leaves ZERO candidates — which is the
+   * worse outcome, because it reads as a dangling claim rather than a wrong kind.
+   */
+  resolveFunctionTarget(functionDeclLines, name, useLine, namesWithNonFunctionDecl) {
+    const cands = functionDeclLines.get(name);
+    const collidesWithOtherKind = namesWithNonFunctionDecl.has(name);
+    if (!cands) return void 0;
+    if (cands.length < 2) {
+      if (!collidesWithOtherKind) return void 0;
+      const only = cands[0];
+      return { targetLine: only.line, targetKind: only.kind, targetResolution: "commandNameIsAFunction" };
+    }
+    const atOrBefore = cands.filter((c) => c.line <= useLine);
+    if (atOrBefore.length === 0) return { targetResolution: "declaredAfterUse" };
+    const nearest = Math.max(...atOrBefore.map((c) => c.line));
+    const winners = atOrBefore.filter((c) => c.line === nearest);
+    if (winners.length !== 1) return { targetResolution: "ambiguousInFile" };
+    return {
+      targetLine: nearest,
+      targetKind: winners[0].kind,
+      targetResolution: "latestDefinitionBeforeUse"
+    };
+  }
+  /** Remove quote characters from a path expression. Index arithmetic over the
+   *  two quote code points; a path cannot contain either. */
+  dequotePath(text) {
+    let out = "";
+    for (let i = 0; i < text.length; i++) {
+      const c = text.charCodeAt(i);
+      if (c === 34 || c === 39) continue;
+      out += text[i];
+    }
+    return out;
+  }
+  stripQuotes(text) {
+    if (text.length >= 2) {
+      const first = text.charCodeAt(0);
+      const last = text.charCodeAt(text.length - 1);
+      if ((first === 34 || first === 39) && last === first) return text.slice(1, -1);
+    }
+    return text;
+  }
+  commandNameNode(node) {
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child && child.type === "command_name") return child;
+    }
+    return null;
+  }
+  commandNameOf(node) {
+    const cn = this.commandNameNode(node);
+    if (!cn) return "";
+    for (let j = 0; j < cn.namedChildCount; j++) {
+      const word = cn.namedChild(j);
+      if (word && word.type === "word") return word.text;
+    }
+    return cn.text;
+  }
+  /**
+   * BD4 (structural): does this node's subtree contain an unexpanded value?
+   * `command_name` holding `$cmd`, `${cmd}` or `$(cmd)` names a command only at
+   * run time, so there is no callee to point at. The test is on the TREE, not
+   * on the text: a character-class test cannot tell `apt-get` from `$pkg_mgr`
+   * without a rule per metacharacter, and the first cut of this guard was
+   * exactly that and swallowed every hyphenated command in the corpus.
+   */
+  containsExpansion(node) {
+    const stack = [node];
+    while (stack.length > 0) {
+      const n = stack.pop();
+      if (n.type === "simple_expansion" || n.type === "expansion" || n.type === "command_substitution" || n.type === "arithmetic_expansion" || n.type === "process_substitution") {
+        return true;
+      }
+      for (let i = 0; i < n.childCount; i++) {
+        const c = n.child(i);
+        if (c) stack.push(c);
+      }
+    }
+    return false;
+  }
+  /**
+   * Is this `command` node an ARITHMETIC OPERAND that the grammar handed back in
+   * command position?
+   *
+   * bash writes an arithmetic expression `$(( ... ))`. The pinned grammar models
+   * it correctly in the ordinary position — `z=$((a + 1))` yields
+   * `arithmetic_expansion` → `binary_expression` → `variable_name`, and there
+   * is no `command` node to misread. It misparses in exactly two shapes, and in
+   * both the operand arrives as a `command` whose `command_name` is a VARIABLE,
+   * so the analyzer was emitting a call to something bash never runs:
+   *
+   *   1. as the default operand of a parameter expansion inside a string —
+   *      `last_run="${last_run:-$((attempt + 1))}"` parses as
+   *      `expansion` → `command_substitution` → `subshell` → `command` →
+   *      `command_name: attempt`, i.e. `$(` plus a subshell where `$((` was meant.
+   *   2. under `!` — `! ((force_known_update))` parses as `negated_command` →
+   *      `subshell` → `subshell` → `command` → `command_name`.
+   *
+   * The test is the enclosing node's own text, never the source text: a
+   * `command_substitution` whose text opens `$((` is an arithmetic expansion,
+   * and a `subshell` whose text opens `((` is one too. A real command
+   * substitution is untouched by this — `$(wc -l < f)` inside `$(( ))` opens
+   * `$(w`, so `calls: -> wc` still fires, which is correct, because `wc` really
+   * is run there.
+   *
+   * Measured on the 400-file census sample: 2 occurrences of shape 1 and 1 of
+   * shape 2. Both edges carried `confidence: 1` and
+   * `evidenceClass: structural`, i.e. they were presented as parse facts rather
+   * than guesses, which is what made them worth removing rather than labelling.
+   */
+  isArithmeticOperandCommand(node) {
+    let cur = node.parent;
+    while (cur) {
+      if (cur.type === "command_substitution") return opensWithArithmeticExpansion(cur.text);
+      if (cur.type === "subshell" && isArithmeticCompoundText(cur.text)) return true;
+      cur = cur.parent;
+    }
+    return false;
+  }
+  /**
+   * Is this node inside a CHILD-PROCESS boundary — a subshell, a command
+   * substitution, or a process substitution?
+   *
+   * BD16: `part_of` asserts that the included text shares THIS file's single
+   * shell scope. `( source lib.sh )` runs the inclusion in a forked shell, so
+   * the definitions live and die in that child and the outer file's scope never
+   * sees them; the claim would be false. The boundary is read from the tree
+   * (ancestor node types), never from the text, so `source lib.sh` inside a
+   * function — which DOES run in this shell, because a function is not a
+   * process — is unaffected.
+   *
+   * `bash x.sh` / `sh x.sh` never reach this helper: they are not the
+   * `source`/`.` command at all, they EXECUTE a file and the analyzer already
+   * publishes a `calls` edge to the interpreter.
+   */
+  isInsideChildProcess(node) {
+    let cur = node.parent;
+    while (cur) {
+      if (cur.type === "subshell" || cur.type === "command_substitution" || cur.type === "process_substitution") {
+        return true;
+      }
+      if (cur.type === "program") return false;
+      cur = cur.parent;
+    }
+    return false;
+  }
+  /**
+   * THE PART'S MODULE SYMBOL — the only `part_of` target the arbiter can bind.
+   *
+   * The argument of a `source` is a PATH, and a path is not in the arbiter's
+   * target space: it resolves target STRINGS against SYMBOL NAMES, so a path
+   * target can only ever be unresolved (`partPath` keeps the path as evidence).
+   * The symbol this lane publishes for a file is BD2's module symbol — its
+   * basename WITH its extension — so `source ./lib/helpers.sh` names the part
+   * `helpers.sh`. The stem (`helpers`) is deliberately NOT used: it is the
+   * spelling another lane's module symbol may have, and here it names no symbol
+   * this analyzer publishes.
+   *
+   * Returns "" when the last path segment is an EXPRESSION rather than a name
+   * (`source "$lib"`, `source "$(pick)"`, `source lib/*.sh`). A name that a
+   * symbol can carry is: non-empty, and free of the characters that mark an
+   * unexpanded value or shell syntax. Index arithmetic over code points, which
+   * is the same non-syntactic shape the lane's other text tests use.
+   */
+  partSymbolOfPath(pathText) {
+    const slash = pathText.lastIndexOf("/");
+    const base = slash >= 0 ? pathText.slice(slash + 1) : pathText;
+    if (base.length === 0) return "";
+    for (let i = 0; i < base.length; i++) {
+      const c = base.charCodeAt(i);
+      if (c <= 32 || c === 34 || c === 39 || c === 96 || c === 36 || c === 40 || c === 41 || c === 123 || c === 125 || c === 91 || c === 93 || c === 42 || c === 63 || c === 59 || c === 124 || c === 38 || c === 60 || c === 62 || c === 92) {
+        return "";
+      }
+    }
+    return base;
+  }
+  /**
+   * Is this `command` a `case` arm's PATTERN that the grammar could not close?
+   *
+   * `if ! case "$t" in binary) … ;; source) … ;; esac; then` is a construct the
+   * pinned wasm cannot close, so an arm arrives as
+   *
+   *   command @936 "binary) _try_existing binary"
+   *     command_name → word "binary"     ← the arm's PATTERN, not a command
+   *     ERROR → ")"                      ← the arm terminator the grammar kept
+   *     word "_try_existing"
+   *
+   * The structural fact is a POSIX one, not a heuristic: **a `)` can never
+   * immediately follow a command NAME in valid bash.** `(cmd)` puts the `)` on
+   * the subshell, a sibling of the whole command; `echo )` puts it after an
+   * argument or on its own as a `word`. The only way `)` lands directly between
+   * the name and the first argument is a terminator the grammar could not place.
+   *
+   * This is the narrow half that the rejected damage guard (see
+   * `guard-ab-bash-calls.ts`, guard E) lacked. Guard E refuses a command with ANY
+   * direct `ERROR`/missing child and costs 15 real `kube::log::status` calls in
+   * kubernetes/test/e2e_node/gubernator.sh, because `V=2 kube::log::status "…"`
+   * puts a `variable_assignment` in the command's own slot and the grammar puts an
+   * `ERROR` beside it. Keying on the POSITION — immediately after `command_name` —
+   * and on the CHARACTER `)` costs 0 real calls on 400 hash-ordered corpus files
+   * while removing 5 fabrications.
+   *
+   * The wider predicate was measured too and REJECTED, rather than assumed:
+   * "the command has a direct `ERROR`/missing child whose text is `)`" fires on
+   * `echo one two ) three`, where `)` is an ordinary word argument, so it would
+   * delete a real `calls: -> echo`. `guard-f-soundness.mts` asks both predicates
+   * about 39 node shapes; the positional one fires on 0 valid-parse commands, the
+   * wider one on 1.
+   *
+   * **Why this is worth an edge the `calls` guards were declined.** The `binary`,
+   * `git` and `auto` arms produce `calls` edges naming nothing runnable — the
+   * residuals pass 2 named and declined. The `source` arm's pattern is the word
+   * `source`, so that arm's `command` reaches the `source`/`.` branch, which emits
+   * `imports` AND `references` to its first argument:
+   *
+   *   gimme -[imports]->    _try_existing
+   *   gimme -[references]-> _try_existing
+   *
+   * `_try_existing` is a shell FUNCTION defined at gimme:414, not a file. That is
+   * a fabricated module dependency — the kind `imports` feeds `bb_migrate` and
+   * `bb_impact` — and no prior guard was aimed at it. The shared differential
+   * cannot see it either: `deriveBashEdges` pushes `imports`+`references` for the
+   * same construct, so two walkers over the same tree agree that a function name
+   * is a dependency.
+   */
+  isCaseArmPatternCommand(node) {
+    const name = this.commandNameNode(node);
+    if (!name) return false;
+    const after = name.nextSibling;
+    if (!after) return false;
+    if (after.type !== "ERROR" && !after.isMissing) return false;
+    return after.text.charCodeAt(0) === 41;
+  }
+  /**
+   * A command's name is a WORD, and a plain `word` name is trusted outright.
+   * The two real-world shapes that put something else in `command_name` are
+   * both fabrications: a zsh `case` arm's alternation, and a quoted string or
+   * number the grammar could not classify. Measured on ohmyzsh's
+   * `tools/changelog.sh` the analyzer emitted `calls: -> ]+` and
+   * `calls: -> \e[2m\1\e[0m`; measured on the 385 extensionless files the
+   * shebang rule had just opened (nvm, rbenv, ohmyzsh, otp) it emitted
+   * `calls: -> 129`, `-> 130`, `-> 141`, `-> 143` and `-> 6` — numeric literals
+   * promoted to callees, 18 rows the independent oracle refused.
+   */
+  isRecoveredCommandWord(nameNode) {
+    if (!nameNode) return true;
+    if (nameNode.isMissing) return true;
+    const name = nameNode;
+    const nameIsPlainWord = name.namedChildCount === 0 || name.namedChildCount === 1 && name.namedChild(0)?.type === "word";
+    if (!nameIsPlainWord) {
+      return true;
+    }
+    if (name.text.charCodeAt(0) === 92) return true;
+    return false;
+  }
+  functionName(node) {
+    const named = node.childForFieldName?.("name");
+    if (named && named.text) return named.text;
+    let prev = null;
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (!child) continue;
+      if (child.type === "compound_statement" && prev && prev.type === "word") {
+        return prev.text;
+      }
+      prev = child;
+    }
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child && child.type === "word" && child.text !== "function") return child.text;
+    }
+    return "";
+  }
+  /**
+   * Every function name the file declares, in one linear pass over the
+   * function_definition nodes. Order-independent by construction: a call to a
+   * function defined later in the file resolves the same as one defined above
+   * it, which is the property the pre-order walk cannot provide on its own.
+   */
+  collectFunctionNames(root) {
+    const names = /* @__PURE__ */ new Set();
+    const stack = [root];
+    while (stack.length > 0) {
+      const node = stack.pop();
+      if (node.type === "function_definition") {
+        const name = this.functionName(node);
+        if (name) names.add(name);
+      }
+      for (let i = node.childCount - 1; i >= 0; i--) {
+        const child = node.child(i);
+        if (child) stack.push(child);
+      }
+    }
+    return names;
+  }
+  extractFunction(node, symbols, owner) {
+    const name = this.functionName(node);
+    if (!name) return;
+    symbols.push({
+      name,
+      kind: ASTEngine.SymbolKind.Function,
+      range: this.nodeToRange(node),
+      scope: owner,
+      visibility: "public",
+      ownerName: owner,
+      parameters: [],
+      metadata: { bashSpecific: true, isScriptFunction: true }
+    });
+  }
+  /**
+   * Every variable READ the analyzer can see, at any expansion or arithmetic
+   * site. Positional parameters and shell bookkeeping never become Uses edges.
+   */
+  emitVariableUses(node, symbols, relSource, addRel, declaredSymbols, functionStack, functionParams, declSites, fileOwner) {
+    const names = [];
+    this.collectReadNames(node, names);
+    for (const { rawName, line } of names) {
+      const name = rawName.trim();
+      if (name.length === 0) continue;
+      if (isAllDigits(name)) {
+        if (name === "0") continue;
+        const fn = functionStack[functionStack.length - 1];
+        if (fn) functionParams.get(fn)?.add(name);
+        continue;
+      }
+      if (SPECIAL_VAR_PUNCTUATION.has(name)) continue;
+      addRel(
+        relSource(),
+        name,
+        ASTEngine.RelationshipType.Uses,
+        0.8,
+        line,
+        {
+          isVariableReference: true,
+          bashSpecific: true,
+          // A read of a name the shell itself defines is recorded as such, so
+          // a consumer can tell `${BASH_SOURCE[0]}` from a project variable
+          // instead of seeing 23 undiagnosable edges to one shell name.
+          ...SHELL_DEFINED_VARS.has(name) ? { isShellDefined: true } : {},
+          // THE SAME FACT ON THE KEY THE INCOMING GATE READS -- see
+          // `externalShellVariableEvidence`. A read of a name the interpreter itself binds is
+          // not a read of a project declaration, and until this the lane published that only
+          // as `isShellDefined`, which `incoming-rule.ts` does not read as a claim.
+          ...this.externalShellVariableEvidence(name, declSites),
+          // Why a `uses` edge does not name a line, when the reason is that this file
+          // binds the name as a variable nowhere. `resolveDeclaration` publishes nothing
+          // in that case and the edge looks identical to one that resolved, so the
+          // population is unreadable from the row alone.
+          ...this.declareAbsenceOfVariableBinding(declSites, name),
+          // WHICH declaration, when this file has more than one. A `uses` edge
+          // puts the READ's line on the row, which is a different line from the
+          // declaration, so without this the declaration is unrecoverable from
+          // the edge and any consumer matching on target alone is choosing
+          // between N declarations by a rule it did not write. Emitted ONLY when
+          // the name is ambiguous in this file — see `resolveDeclaration` for the
+          // three outcomes and why "declined to pick" is published separately
+          // from "picked one".
+          ...this.resolveDeclaration(
+            declSites,
+            name,
+            functionStack[functionStack.length - 1] ?? "",
+            line,
+            fileOwner
+          ) ?? {}
+        }
+      );
+    }
+    void symbols;
+  }
+  /** Variable names read anywhere under `node`, each with the line it is on. */
+  collectReadNames(node, out) {
+    const visit = (n) => {
+      if (n.type === "variable_name" || n.type === "special_variable_name") {
+        const text = n.text;
+        if (text.length > 0) out.push({ rawName: text, line: n.startPosition.row + 1 });
+        return;
+      }
+      if (n.type === "subscript") {
+        for (let j = 0; j < n.namedChildCount; j++) {
+          const c = n.namedChild(j);
+          if (c) visit(c);
+        }
+        return;
+      }
+      for (let i = 0; i < n.namedChildCount; i++) {
+        const c = n.namedChild(i);
+        if (c) visit(c);
+      }
+    };
+    visit(node);
+  }
+  extractAssignment(node, symbols, owner, declaredSymbols, scopeOwners, declSites) {
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      let nameNode = null;
+      let elementAssignment = false;
+      if (child && child.type === "variable_name") {
+        nameNode = child;
+      } else if (child && child.type === "subscript") {
+        const base = child.namedChild(0);
+        if (base && base.type === "variable_name") {
+          nameNode = base;
+          elementAssignment = true;
+        }
+      }
+      if (nameNode && nameNode.text.trim() !== "") {
+        const key = `${owner}\0${nameNode.text}`;
+        if (declaredSymbols.has(key)) return;
+        declaredSymbols.add(key);
+        this.noteDeclaration(declSites, nameNode.text, owner, node.startPosition.row + 1, "variable");
+        const isArray = elementAssignment || this.valueIsArray(node);
+        symbols.push({
+          name: nameNode.text,
+          kind: ASTEngine.SymbolKind.Variable,
+          range: this.nodeToRange(node),
+          scope: owner,
+          visibility: this.visibilityForOwner(owner, scopeOwners),
+          ownerName: owner || void 0,
+          metadata: { bashSpecific: true, isArray, isTopLevel: owner === "" }
+        });
+        return;
+      }
+    }
+  }
+  /**
+   * A binding the language creates without an assignment node.
+   *
+   * `extractAssignment` and `extractDeclaration` cover the two node types that
+   * carry an explicit `NAME=`. These four constructs bind a name and carry
+   * neither, so before this existed they produced a `uses` edge to a target the
+   * analyzer had not published — the edge asserted a read of a declaration that
+   * did not exist in the graph. Measured on a 400-file hash-ordered sample:
+   * 234 binding sites across 96 distinct files, and 357 `uses` edges naming a
+   * target one of them declared. Adding this closed all 357 — the unresolvable
+   * `uses` count fell 1,920 -> 1,563 and the `uses` total stayed at 7,802.
+   *
+   * The rule throughout is DECLINE, NEVER GUESS. A target counts only when it is
+   * a `word` sibling that is a shell identifier, because the pinned grammar
+   * represents a computed name as a different node and a literal name as a
+   * `word` — so the type test is the whole filter. Every one of these was
+   * verified on the tree rather than assumed, in
+   * `validation/m14/fixtures/bash/probe-bash-binding-shapes.mts`:
+   *
+   *   read "$target"          -> `string`      declined
+   *   read pre${n}fix         -> `concatenation` declined
+   *   printf -v "$2"          -> `string`      declined
+   *   mapfile -t "$name"      -> `string`      declined
+   *   read *.txt              -> `word`        declined, not an identifier
+   *   read                    -> (no target)   declined; bash assigns REPLY,
+   *                                            which is in SHELL_DEFINED_VARS
+   *   # read x                -> `comment`     declined
+   *   echo "read x"           -> `string_content` declined
+   *   cat <<'EOF' … read x …  -> `heredoc_body`  declined
+   *
+   * The last three are why this reads the tree: a text matcher would have
+   * declared a variable from a comment, a string and a heredoc.
+   */
+  extractImplicitBinding(node, symbols, owner, declaredSymbols, scopeOwners, declSites) {
+    const publish = (name, at, site, isArray) => {
+      if (!isShellIdentifierName(name)) return;
+      const key = `${owner}\0${name}`;
+      if (declaredSymbols.has(key)) return;
+      declaredSymbols.add(key);
+      this.noteDeclaration(declSites, name, owner, at.startPosition.row + 1, "variable");
+      symbols.push({
+        name,
+        kind: ASTEngine.SymbolKind.Variable,
+        range: this.nodeToRange(at),
+        scope: owner,
+        visibility: this.visibilityForOwner(owner, scopeOwners),
+        ownerName: owner || void 0,
+        metadata: { bashSpecific: true, isImplicitBinding: true, bindingSite: site, isArray }
+      });
+    };
+    if (node.type === "for_statement") {
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child && child.type === "variable_name") publish(child.text, child, "for", false);
+      }
+      return;
+    }
+    const cmd = this.commandNameOf(node);
+    if (cmd.length === 0) return;
+    if (READ_TARGET_COMMANDS.has(cmd)) {
+      let skipNext = false;
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (!child || child.type === "command_name") continue;
+        if (child.type === "variable_assignment") continue;
+        const isOption = child.type === "word" && child.text.length > 1 && child.text.charCodeAt(0) === 45 && child.text.charCodeAt(1) !== 45;
+        if (isOption) {
+          const lastIndex = child.text.length - 1;
+          let consumesNext = false;
+          for (let j = 1; j < child.text.length; j++) {
+            const letter = child.text[j];
+            if (!READ_OPTION_LETTERS.has(letter)) continue;
+            if (READ_VALUE_OPT_LETTERS.has(letter)) {
+              consumesNext = j === lastIndex;
+              break;
+            }
+          }
+          skipNext = consumesNext;
+          continue;
+        }
+        if (skipNext) {
+          skipNext = false;
+          continue;
+        }
+        publish(child.text, child, cmd, cmd !== "read");
+      }
+      return;
+    }
+    if (cmd === "printf") {
+      for (let i = 0; i < node.namedChildCount - 1; i++) {
+        const child = node.namedChild(i);
+        if (!child || child.type !== "word" || child.text !== "-v") continue;
+        const target = node.namedChild(i + 1);
+        if (target && target.type === "word") publish(target.text, target, "printf -v", false);
+        return;
+      }
+    }
+  }
+  valueIsArray(node) {
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (!child) continue;
+      if (child.type === "array") return true;
+      if (child.type === "variable_name") continue;
+      if (child.type === "word" || child.type === "string" || child.type === "concatenation") continue;
+      return false;
+    }
+    return false;
+  }
+  /**
+   * A declaration inside a function is private to it; one at the script's top
+   * level is part of the script's surface.
+   *
+   * The lookup is a Set membership test, not a scan of the symbol list. The
+   * scan was the last O(n^2) on the hot path: this is called for EVERY
+   * assignment and EVERY `local`/`declare`, so a file with D declarations and S
+   * symbols spent O(D x S) deciding a field that answers to one question — "is
+   * this owner a function?". The answer is already known: the caller collected
+   * the file's function names in one linear pre-pass (BD10) precisely so that
+   * this kind of question is O(1). `alias` names join the same set, because an
+   * alias is callable and a `local` inside one is equally private.
+   */
+  visibilityForOwner(owner, scopeOwners) {
+    return scopeOwners.has(owner) ? "private" : "public";
+  }
+  extractDeclaration(node, symbols, owner, functionParams, declaredSymbols, scopeOwners, addRel, declSites, patterns) {
+    const keyword = node.child(0)?.text ?? "";
+    if (!DECLARATION_KEYWORDS.has(keyword)) return;
+    const hasFunctionFlag = (() => {
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child && child.type === "word" && child.text === "-f") return true;
+      }
+      return false;
+    })();
+    const isArrayDecl = keyword === "declare" || keyword === "typeset";
+    let sawArrayFlag = false;
+    let sawExportFlag = false;
+    if (isArrayDecl) {
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (!child || child.type !== "word") continue;
+        if (child.text === "-a") sawArrayFlag = true;
+        if (child.text === "-x") sawExportFlag = true;
+      }
+    }
+    const isExport = keyword === "export" || sawExportFlag;
+    const emit = (name, range, line) => {
+      if (!name || name.trim() === "") return;
+      if (!isShellIdentifierName(name)) return;
+      if (isExport) {
+        addRel(owner, name, ASTEngine.RelationshipType.Exports, 1, line, {
+          bashSpecific: true,
+          exportForm: "variable"
+        });
+      }
+      const key = `${owner}\0${name}`;
+      if (declaredSymbols.has(key)) return;
+      declaredSymbols.add(key);
+      this.noteDeclaration(declSites, name, owner, line, isExport || keyword === "readonly" ? "constant" : "variable");
+      if (isExport || keyword === "readonly") {
+        symbols.push({
+          name,
+          kind: ASTEngine.SymbolKind.Constant,
+          range,
+          scope: owner,
+          visibility: "public",
+          ownerName: owner || void 0,
+          metadata: {
+            bashSpecific: true,
+            isExported: isExport,
+            isReadonly: keyword === "readonly"
+          }
+        });
+      } else {
+        symbols.push({
+          name,
+          kind: ASTEngine.SymbolKind.Variable,
+          range,
+          scope: owner,
+          visibility: this.visibilityForOwner(owner, scopeOwners),
+          ownerName: owner || void 0,
+          metadata: {
+            bashSpecific: true,
+            isLocal: keyword === "local",
+            isDeclared: keyword === "declare" || keyword === "typeset",
+            isArray: sawArrayFlag
+          }
+        });
+      }
+    };
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (!child) continue;
+      const childLine = child.startPosition.row + 1;
+      if (child.type === "variable_name") {
+        if (hasFunctionFlag) {
+          this.markFunctionExported(symbols, child.text);
+          addRel(owner, child.text, ASTEngine.RelationshipType.Exports, 1, childLine, {
+            bashSpecific: true,
+            exportForm: "function"
+          });
+        } else {
+          emit(child.text, this.nodeToRange(child), childLine);
+        }
+      } else if (child.type === "variable_assignment") {
+        if (hasFunctionFlag) {
+          for (let j = 0; j < child.namedChildCount; j++) {
+            const vn = child.namedChild(j);
+            if (vn && vn.type === "variable_name") {
+              this.markFunctionExported(symbols, vn.text);
+              addRel(owner, vn.text, ASTEngine.RelationshipType.Exports, 1, childLine, {
+                bashSpecific: true,
+                exportForm: "function"
+              });
+            }
+          }
+          continue;
+        }
+        for (let j = 0; j < child.namedChildCount; j++) {
+          const vn = child.namedChild(j);
+          if (vn && vn.type === "variable_name") {
+            emit(vn.text, this.nodeToRange(child), childLine);
+            if (keyword === "local" && owner) {
+              const valueNode = child.namedChild(1);
+              this.collectPositionalFromValue(valueNode, functionParams, owner);
+            }
+          }
+        }
+      } else if (child.type === "word" && !child.text.startsWith("-") && child.text !== keyword) {
+        if (hasFunctionFlag) {
+          this.markFunctionExported(symbols, child.text);
+          addRel(owner, child.text, ASTEngine.RelationshipType.Exports, 1, childLine, {
+            bashSpecific: true,
+            exportForm: "function"
+          });
+        } else {
+          emit(child.text, this.nodeToRange(child), childLine);
+        }
+      } else if (child.type === "string" || child.type === "concatenation") {
+        const name = this.staticNameOfDeclarationString(child);
+        if (name) {
+          if (hasFunctionFlag) {
+            this.markFunctionExported(symbols, name);
+            addRel(owner, name, ASTEngine.RelationshipType.Exports, 1, childLine, {
+              bashSpecific: true,
+              exportForm: "function"
+            });
+          } else {
+            emit(name, this.nodeToRange(child), childLine);
+          }
+        } else if (isExport) {
+          patterns.add(COMPUTED_EXPORT_NAME_PATTERN);
+        }
+      }
+    }
+  }
+  /**
+   * BD11 -- the statically-known name inside a declaration whose whole argument is ONE string
+   * node (`export "NAME=value"`, `export "NAME"`, `export 'NAME=value'`).
+   *
+   * The name is read from the node's LITERAL run: the characters up to the first `=` that are
+   * produced by `string_content`/`word`/`raw_string`, with the quotes removed. The moment an
+   * expansion appears before the `=`, the name is decided at RUN TIME and `null` is returned --
+   * there is no name to publish, and publishing the template would be a target no symbol can
+   * ever have.
+   *
+   * FAIL-CLOSED: an unrecognised child shape ends the literal run rather than contributing to
+   * it, so a grammar change makes this quieter instead of wrong. `isShellIdentifierName` is the
+   * same identifier test the rest of the declaration path uses, so a value that is not a shell
+   * name (`export "1=2"`, `export "a b=c"`) is refused here too rather than published.
+   */
+  staticNameOfDeclarationString(node) {
+    if (node.namedChildCount === 0) return this.nameFromLiteralRun(this.stripQuotes(node.text));
+    let literal = "";
+    let computed = false;
+    const scan = (n) => {
+      for (let i = 0; i < n.namedChildCount && !computed; i++) {
+        const c = n.namedChild(i);
+        if (!c) continue;
+        switch (c.type) {
+          case "simple_expansion":
+          case "expansion":
+          case "command_substitution":
+          case "arithmetic_expansion":
+            computed = true;
+            break;
+          case "concatenation":
+          case "string":
+            scan(c);
+            break;
+          default:
+            literal += this.stripQuotes(c.text);
+            break;
+        }
+        if (literal.includes("=")) return;
+      }
+    };
+    scan(node);
+    if (computed) return null;
+    return this.nameFromLiteralRun(literal);
+  }
+  /** The identifier before the first `=` in a literal run, or the whole run when it holds no
+   *  `=` (a quoted BARE name: `export "NAME"`). Anything that is not a shell identifier is
+   *  refused -- including the empty string. */
+  nameFromLiteralRun(literal) {
+    const eq = literal.indexOf("=");
+    const name = eq >= 0 ? literal.slice(0, eq) : literal;
+    return isShellIdentifierName(name) ? name : null;
+  }
+  collectPositionalFromValue(node, functionParams, fnName) {
+    if (!node) return;
+    const scan = (n) => {
+      if (n.type === "simple_expansion") {
+        for (let i = 0; i < n.namedChildCount; i++) {
+          const c = n.namedChild(i);
+          if (c && c.type === "variable_name" && c.text.length > 0 && c.text.charCodeAt(0) >= 48 && c.text.charCodeAt(0) <= 57) {
+            functionParams.get(fnName)?.add(c.text);
+          }
+        }
+      }
+      for (let i = 0; i < n.namedChildCount; i++) {
+        const child = n.namedChild(i);
+        if (child) scan(child);
+      }
+    };
+    scan(node);
+  }
+  markFunctionExported(symbols, name) {
+    for (let i = 0; i < symbols.length; i++) {
+      const s = symbols[i];
+      if (s.kind === ASTEngine.SymbolKind.Function && s.name === name) {
+        s.metadata = { ...s.metadata, isExported: true };
+        s.visibility = "public";
+        return;
+      }
+    }
+  }
+  extractCommand(node, symbols, imports, patterns, ctx) {
+    const nameNode = this.commandNameNode(node);
+    if (!nameNode) return;
+    const cmdName = this.commandNameOf(node);
+    if (!cmdName) return;
+    const nameLine = nameNode.startPosition.row + 1;
+    if (this.isRecoveredCommandWord(nameNode)) {
+      patterns.add("Recovered Parse Region");
+      return;
+    }
+    if (this.containsExpansion(nameNode) || !isCommandNameText(cmdName)) {
+      patterns.add(SHELL_RESERVED_WORDS.has(cmdName) ? "Recovered Parse Region" : "Dynamic Command Name");
+      return;
+    }
+    if (this.isArithmeticOperandCommand(node)) {
+      return;
+    }
+    if (this.isCaseArmPatternCommand(node)) {
+      patterns.add("Recovered Parse Region");
+      return;
+    }
+    if (cmdName === "docker" || cmdName === "docker-compose" || cmdName === "kubectl" || cmdName === "helm") {
+      patterns.add("Container/Orchestration Script");
+      patterns.add("Deployment Script");
+    } else if (cmdName === "aws" || cmdName === "gcloud" || cmdName === "az" || cmdName === "terraform") {
+      patterns.add("Cloud Infrastructure Script");
+    } else if (cmdName === "npm" || cmdName === "yarn" || cmdName === "pnpm" || cmdName === "cargo" || cmdName === "go") {
+      patterns.add("Build/Compilation Script");
+    } else if (cmdName === "curl" || cmdName === "wget") {
+      patterns.add("Network Request Script");
+    } else if (cmdName === "eval") {
+      ctx.setFlag.eval(true);
+      patterns.add("Dynamic Code Execution");
+    } else if (cmdName === "sudo") {
+      ctx.setFlag.sudo(true);
+      patterns.add("Privilege Escalation");
+    }
+    if (cmdName === "source" || cmdName === ".") {
+      const arg = this.firstArgumentWord(node);
+      if (arg) {
+        const line = this.firstArgumentLine(node) ?? nameLine;
+        const argNode = this.firstArgumentNode(node);
+        const dynamic = argNode ? this.containsExpansion(argNode) : false;
+        const normalized = this.dequotePath(arg);
+        imports.push({
+          module: normalized,
+          items: ["*"],
+          isDefaultImport: true,
+          isNamespaceImport: false,
+          range: this.nodeToRange(node),
+          metadata: {
+            isSourceImport: true,
+            resolution: dynamic ? "dynamic" : "literal"
+          }
+        });
+        const inChildProcess = this.isInsideChildProcess(node);
+        const partSymbol = inChildProcess ? "" : this.partSymbolOfPath(normalized);
+        if (partSymbol.length > 0) {
+          ctx.addRel(ctx.scriptName, partSymbol, ASTEngine.RelationshipType.PartOf, 1, line, {
+            // MANDATORY on every `part_of` row: the direction is the
+            // directive's own, and this file carries it and names the part.
+            partRole: "library",
+            partPath: normalized,
+            partSymbol,
+            resolution: dynamic ? "dynamic" : "literal",
+            isSourcePart: true,
+            isSourceInclusion: true,
+            bashSpecific: true,
+            evidenceClass: "import_based"
+          });
+        } else {
+          patterns.add(inChildProcess ? "Child-Process Inclusion" : "Dynamic Source Path");
+        }
+        ctx.addRel(ctx.relSource(), normalized, ASTEngine.RelationshipType.References, 1, line, {
+          isSourceDependency: true,
+          resolution: dynamic ? "dynamic" : "literal",
+          bashSpecific: true
+        });
+      }
+      return;
+    }
+    if (cmdName === "export") {
+      this.handleExportCommand(node, symbols, ctx);
+      return;
+    }
+    if (cmdName === "alias") {
+      const aliasName = this.aliasNameOf(node);
+      if (aliasName) {
+        symbols.push({
+          name: aliasName,
+          kind: ASTEngine.SymbolKind.Function,
+          range: this.nodeToRange(node),
+          scope: ctx.scriptName,
+          visibility: "public",
+          ownerName: ctx.scriptName,
+          metadata: { isAlias: true, bashSpecific: true }
+        });
+        ctx.localFunctions.add(aliasName);
+        ctx.scopeOwners.add(aliasName);
+      }
+      return;
+    }
+    if (cmdName === "trap") {
+      this.handleTrap(node, ctx, patterns, nameLine);
+      return;
+    }
+    if (cmdName === "set") {
+      if (this.hasErrexitFlags(node)) {
+        ctx.setFlag.strictError(true);
+        patterns.add("Strict Error Handling");
+      }
+      return;
+    }
+    if (cmdName === "chmod" && this.hasArgument(node, "777")) {
+      ctx.setFlag.chmod777(true);
+      patterns.add("Insecure Permissions");
+    }
+    if (cmdName === "rm" && this.isRmRoot(node)) {
+      ctx.setFlag.rmRoot(true);
+      patterns.add("Destructive File Operation");
+    }
+    if (SHELL_BUILTINS.has(cmdName)) return;
+    const isLocal = ctx.localFunctions.has(cmdName);
+    ctx.addRel(ctx.relSource(), cmdName, ASTEngine.RelationshipType.Calls, 1, nameLine, {
+      // The previous emitter set BOTH flags to `true` on every call, so a call
+      // to a function defined three lines above claimed to be an external
+      // command. The two are now mutually exclusive facts.
+      isFunctionCall: isLocal,
+      isExternalCommand: !isLocal,
+      resolvedWithinFile: isLocal,
+      // Where this command node sits, so the attribution pass can tell a name
+      // collision from wreckage. Published on true only, and it is a statement
+      // about the node's POSITION rather than a verdict on the edge — round 13
+      // measured 427 function names whose `name:` field sits inside an ERROR span
+      // and every one is a real declaration, the span reaching back over intact
+      // code. So this flag never removes an edge. It exists because the
+      // attribution pass runs AFTER the walk and would otherwise have to re-derive
+      // the shape from a node it no longer holds.
+      commandInErrorRecovery: this.isInsideErrorNode(node) || void 0,
+      ...this.externalCommandEvidence(cmdName, isLocal),
+      bashSpecific: true
+    });
+  }
+  /**
+   * Is this node a DESCENDANT of a tree-sitter `ERROR` node?
+   *
+   * The narrow half of what round 3's guard B would have tested, and the half that
+   * survives its own measurement. Guard B was "any damaged region — subtree or
+   * ancestor chain" and it removed 96 of 2,945 `calls` edges on a 200-file sample,
+   * 15 of them real `kube::log::status` calls, because a MISSING token anywhere in
+   * a file condemns every command under it.
+   *
+   * Re-measured at whole corpus with the analyzer's OWN selector for the command
+   * name (`commandNameNode`, which scans all named children — the first version of
+   * the probe read `namedChild(0)` and so missed the very shape round 3 named):
+   *
+   *   2,891 `calls` edges come from a command inside an ERROR subtree, and the
+   *   removal set is `setopt`, `print`, `echoti`, `autoload`, `emulate`, `title`,
+   *   `terminal-notifier`, `notify-send` — real work, overwhelmingly zsh.
+   *
+   * So the flag is published and NO guard is built on it. The three whole-corpus
+   * edges it would have caught are named in the lane doc as residuals, because the
+   * alternative is deleting 2,891 correct edges to remove 3.
+   */
+  isInsideErrorNode(node) {
+    for (let cur = node.parent; cur; cur = cur.parent) {
+      if (cur.type === "ERROR") return true;
+    }
+    return false;
+  }
+  handleExportCommand(node, symbols, ctx) {
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (!child || child.type !== "word" || child.text !== "-f") continue;
+      for (let j = 0; j < node.namedChildCount; j++) {
+        const word = node.namedChild(j);
+        if (word && word.type === "word" && !word.text.startsWith("-") && word.text !== "export") {
+          this.markFunctionExported(symbols, word.text);
+          ctx.addRel(ctx.relSource(), word.text, ASTEngine.RelationshipType.Exports, 1, child.startPosition.row + 1, {
+            bashSpecific: true,
+            exportForm: "function"
+          });
+        }
+      }
+      return;
+    }
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child && child.type === "variable_assignment") {
+        for (let j = 0; j < child.namedChildCount; j++) {
+          const vn = child.namedChild(j);
+          if (vn && vn.type === "variable_name") {
+            symbols.push({
+              name: vn.text,
+              kind: ASTEngine.SymbolKind.Constant,
+              range: this.nodeToRange(child),
+              scope: ctx.relSource(),
+              visibility: "public",
+              ownerName: ctx.relSource(),
+              metadata: { isExported: true, bashSpecific: true }
+            });
+            ctx.addRel(ctx.relSource(), vn.text, ASTEngine.RelationshipType.Exports, 1, child.startPosition.row + 1, {
+              bashSpecific: true,
+              exportForm: "variable"
+            });
+          }
+        }
+      }
+    }
+  }
+  aliasNameOf(node) {
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (!child) continue;
+      const text = child.type === "concatenation" ? child.text : child.type === "word" ? child.text : "";
+      if (text) {
+        const eq = text.indexOf("=");
+        if (eq > 0) {
+          const name = text.slice(0, eq);
+          if (name.trim() !== "" && !name.startsWith("-")) return name;
+        }
+      }
+    }
+    return "";
+  }
+  /**
+   * BD3: `trap 'handler' SIGNAL`. A signal is not code and was used as the
+   * edge SOURCE, which produced `calls: EXIT -> cleanup` — a caller that does
+   * not exist. The handler is a command string; the edge belongs to the scope
+   * that installs the trap, the target is the handler's command NAME, and the
+   * signal rides along in metadata.
+   */
+  /**
+   * THE INCOMING MARKER -- `isExternal`, and the evidence that is allowed to carry it.
+   *
+   * `script/m14/incoming-rule.ts` treats an external target as a DECLARED EXCEPTION rather than
+   * a defect, but only when the lane MARKS it, and the marker is a claim the corpus checks: an
+   * unmarked external target and a broken edge are otherwise indistinguishable. MEASURED before
+   * this method existed (`incoming-gate.ts bash sh 60`): 855 unresolved of 2,590 edges, of which
+   * 631 are `calls`, and ZERO edges carried any external marker -- the lane was asserting
+   * nothing about the half of its graph that leaves the repository.
+   *
+   * A FIRST, WIDER VERSION OF THIS RULE WAS MEASURED AND WITHDRAWN, and the measurement is the
+   * reason this one is narrow. It marked every call in a file that contains no `source`/`.` and
+   * no `eval`, on the argument that bash can then only resolve the name through PATH. On the
+   * gate's own population that marked 435 edges and an audit of the marked set
+   * (`probe-bash-incoming-split.mts`, whole-project declaration index) found **82 of them name
+   * a `function_definition` the same repository declares** -- 62 of them
+   * `kube::test::get_object_assert` in kubernetes. The argument is false for a LIBRARY file: a
+   * file that sources nothing may itself be sourced by another file that has already defined the
+   * name, so "this file cannot define it" does not mean "the project cannot supply it". A marker
+   * that is wrong 18.9% of the time is worse than no marker, because the number it removes stops
+   * meaning anything.
+   *
+   * So one shape remains, and it is a fact about the NAME rather than about the file:
+   *
+   *   PATH-INVOKED (`/bin/expr`, `./otp_build`)   the command word contains `/`, and a shell
+   *       function name cannot contain `/`. The shell is being handed a FILE to execute; the
+   *       target can never be a project declaration, whatever else the file does.
+   *
+   * WHAT IS NOT MARKED, and it is the honest half: an unqualified call to a name this file does
+   * not define. Whether the project declares it elsewhere is a fact about the CORPUS, which a
+   * single-file analyzer does not have, and the wider rule's 82 refuted claims are the price of
+   * pretending otherwise. Those edges stay in `unresolved` and are reported there -- the bash
+   * lane's residual is a measured number, not a laundered one.
+   */
+  externalCommandEvidence(cmdName, isLocal) {
+    if (isLocal) return {};
+    if (!cmdName.includes("/")) return {};
+    if (cmdName.startsWith("/")) return { isExternal: true, externalEvidence: "pathInvokedCommand" };
+    if (cmdName.length >= 3 && (cmdName.charCodeAt(0) >= 65 && cmdName.charCodeAt(0) <= 90 || cmdName.charCodeAt(0) >= 97 && cmdName.charCodeAt(0) <= 122) && cmdName.charCodeAt(1) === 58 && (cmdName.charCodeAt(2) === 92 || cmdName.charCodeAt(2) === 47)) return { isExternal: true, externalEvidence: "pathInvokedCommand" };
+    return {};
+    return { isExternal: true, externalEvidence: "pathInvokedCommand" };
+  }
+  handleTrap(node, ctx, patterns, nameLine) {
+    let handlerText = "";
+    const signals = [];
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (!child) continue;
+      const type = child.type;
+      if (type === "raw_string" || type === "string") {
+        const inner = this.stripQuotes(child.text);
+        if (!handlerText) handlerText = inner;
+      } else if (type === "word") {
+        if (child.text === "trap") continue;
+        if (child.text.startsWith("-")) continue;
+        if (!handlerText) handlerText = child.text;
+        else signals.push(child.text);
+      }
+    }
+    if (!handlerText) return;
+    const parts = handlerText.split(";");
+    let emittedAny = false;
+    for (const rawPart of parts) {
+      const part = rawPart.trim();
+      if (part.length === 0) continue;
+      const firstToken = this.firstTokenOf(part);
+      if (!firstToken || !isCommandNameText(firstToken)) continue;
+      if (SHELL_BUILTINS.has(firstToken)) continue;
+      const isLocal = ctx.localFunctions.has(firstToken);
+      ctx.addRel(ctx.relSource(), firstToken, ASTEngine.RelationshipType.Calls, 0.7, nameLine, {
+        isTrapHandler: true,
+        viaTrap: true,
+        isFunctionCall: isLocal,
+        isExternalCommand: !isLocal,
+        resolvedWithinFile: isLocal,
+        signals: signals.length > 0 ? signals : ["EXIT"],
+        ...this.externalCommandEvidence(firstToken, isLocal),
+        bashSpecific: true
+      });
+      emittedAny = true;
+    }
+    if (!emittedAny) {
+      patterns.add("Signal Handler");
+    }
+  }
+  /** The first shell token of a handler string: leading `name`, `name=value` and
+   *  `name(args)` shapes all yield the command name. */
+  firstTokenOf(part) {
+    let i = 0;
+    while (i < part.length) {
+      const start = i;
+      while (i < part.length && part.charCodeAt(i) !== 32 && part.charCodeAt(i) !== 61) i++;
+      const token = part.slice(start, i);
+      if (i < part.length && part.charCodeAt(i) === 61) {
+        i++;
+        while (i < part.length && part.charCodeAt(i) === 32) i++;
+        continue;
+      }
+      if (i < part.length && part.charCodeAt(i) === 40) break;
+      return token;
+    }
+    return "";
+  }
+  hasErrexitFlags(node) {
+    let sawO = false;
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (!child || child.type !== "word") continue;
+      const text = child.text;
+      if (text === "-o") {
+        sawO = true;
+        continue;
+      }
+      if (sawO && text === "errexit") return true;
+      sawO = false;
+      if (text.startsWith("-") && text.length > 1) {
+        for (let j = 1; j < text.length; j++) {
+          if (text.charCodeAt(j) === 101) return true;
+        }
+      }
+    }
+    return false;
+  }
+  hasArgument(node, value) {
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child && child.type === "word" && child.text === value) return true;
+    }
+    return false;
+  }
+  isRmRoot(node) {
+    let hasRecursive = false;
+    let hasForce = false;
+    let hasRoot = false;
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (!child || child.type !== "word") continue;
+      const text = child.text;
+      if (text === "/") hasRoot = true;
+      else if (text.startsWith("-")) {
+        for (let j = 1; j < text.length; j++) {
+          const code = text.charCodeAt(j);
+          if (code === 114) hasRecursive = true;
+          if (code === 102) hasForce = true;
+        }
+      }
+    }
+    return hasRecursive && hasForce && hasRoot;
+  }
+  firstArgumentWord(node) {
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (!child || child.type === "command_name") continue;
+      if (child.type === "word" || child.type === "raw_string" || child.type === "string" || child.type === "concatenation") {
+        return this.stripQuotes(child.text);
+      }
+    }
+    return "";
+  }
+  firstArgumentNode(node) {
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (!child || child.type === "command_name") continue;
+      if (child.type === "word" || child.type === "raw_string" || child.type === "string" || child.type === "concatenation") {
+        return child;
+      }
+    }
+    return null;
+  }
+  firstArgumentLine(node) {
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (!child || child.type === "command_name") continue;
+      if (child.type === "word" || child.type === "raw_string" || child.type === "string" || child.type === "concatenation") {
+        return child.startPosition.row + 1;
+      }
+    }
+    return null;
+  }
+  // `normalizeRelative` was DELETED in M60, not merely unused. It resolved a
+  // relative `source` against the sourcing file's own directory, which BD9
+  // reversed as wrong: bash resolves a relative `source` against `$PWD` at run
+  // time, so the rewrite turned `source ./eng/common/tools.sh` inside
+  // `eng/common/` into the nonexistent `eng/common/eng/common/tools.sh`. The
+  // function had no callers, and its doc comment still asserted the reversed
+  // behaviour, so the file described two different contracts for one construct.
+  detectFrameworks(patterns) {
+    const frameworks = [];
+    for (let i = 0; i < patterns.length; i++) {
+      if (patterns[i] === "Container/Orchestration Script" && !frameworks.includes("Docker/Kubernetes")) frameworks.push("Docker/Kubernetes");
+      if (patterns[i] === "Cloud Infrastructure Script" && !frameworks.includes("Cloud Native")) frameworks.push("Cloud Native");
+    }
+    return frameworks;
+  }
+  generateInsights(patterns, hasStrictError) {
+    const insights = [];
+    for (let i = 0; i < patterns.length; i++) {
+      if (patterns[i] === "Deployment Script") {
+        insights.push("This script contains deployment logic.");
+        break;
+      }
+    }
+    let hasContainerPattern = false;
+    let hasEnvPattern = false;
+    for (let i = 0; i < patterns.length; i++) {
+      if (patterns[i] === "Container/Orchestration Script") hasContainerPattern = true;
+      if (patterns[i] === "Environment Variable Tracking") hasEnvPattern = true;
+    }
+    if (hasContainerPattern) insights.push("Acts as a container orchestration script");
+    if (hasEnvPattern) insights.push("Manages environment states for downstream processes");
+    if (!hasStrictError) insights.push("Lacks 'set -e' for strict error catching");
+    return insights;
+  }
+  nodeToRange(node) {
+    return {
+      startLine: node.startPosition.row + 1,
+      startColumn: node.startPosition.column + 1,
+      endLine: node.endPosition.row + 1,
+      endColumn: node.endPosition.column + 1,
+      startIndex: node.startIndex,
+      endIndex: node.endIndex
+    };
+  }
+};
+function isAllDigits(text) {
+  if (text.length === 0) return false;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code < 48 || code > 57) return false;
+  }
+  return true;
+}
+export {
+  RealBashAnalyzer
+};