@backbencher/brain 0.0.0-stage → 0.1.1

package/dist/real-erlang-analyzer-7BVPQEHO.js

@@ -0,0 +1,1731 @@
+import {
+  ASTEngine
+} from "./chunk-3ZTOHHSW.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-erlang-analyzer.ts
+var OTP_BEHAVIOURS = /* @__PURE__ */ new Set(["gen_server", "gen_statem", "gen_event", "supervisor", "application"]);
+var SPAWN_BIFS = /* @__PURE__ */ new Set(["spawn", "spawn_link", "spawn_monitor"]);
+var TYPE_SCOPE_NODES = /* @__PURE__ */ new Set([
+  "spec",
+  "callback",
+  "type_alias",
+  "opaque",
+  "nominal",
+  "type_sig",
+  "fun_type_sig",
+  "ann_type",
+  "ann_var",
+  "field_type",
+  "fun_type",
+  "range_type",
+  "var_args",
+  "type_name",
+  "type_guards",
+  "pipe"
+]);
+var ARM_NODES = /* @__PURE__ */ new Set(["cr_clause", "if_clause", "catch_clause", "receive_after"]);
+var COMPREHENSION_NODES = /* @__PURE__ */ new Set(["list_comprehension", "binary_comprehension", "map_comprehension"]);
+var PRE_PASS_DESCEND = /* @__PURE__ */ new Set([
+  "pp_if",
+  "pp_ifdef",
+  "pp_ifndef",
+  "pp_else",
+  "pp_elif",
+  "pp_endif",
+  "ERROR"
+]);
+var MATCH_OPERATORS = /* @__PURE__ */ new Set(["=", "?=", "<-", "<:=", "<="]);
+var DECL_NODES = /* @__PURE__ */ new Set([
+  "module_attribute",
+  "fun_decl",
+  "spec",
+  "record_decl",
+  "pp_define",
+  "type_alias",
+  "opaque",
+  "nominal",
+  "callback"
+]);
+var DEFAULT_EVIDENCE_CLASS = {
+  contains: "structural",
+  exports: "structural",
+  implements: "structural",
+  instantiates: "structural",
+  overrides: "structural",
+  extends: "structural",
+  imports: "import_based",
+  references: "reference_qualified",
+  calls: "usage_contextual",
+  uses: "usage_contextual"
+};
+function evidenceClassFor(type, confidence, target) {
+  const t = String(type ?? "");
+  if (t === "calls") return target.indexOf(":") !== -1 ? "reference_qualified" : "usage_contextual";
+  return DEFAULT_EVIDENCE_CLASS[t] ?? (confidence >= 0.85 ? "structural" : "inferred");
+}
+var RealErlangAnalyzer = class {
+  analyze(rootNode, content, filePath) {
+    const ctx = {
+      filePath,
+      symbols: [],
+      relationships: [],
+      imports: [],
+      exports: [],
+      errors: [],
+      patterns: {},
+      seenRels: /* @__PURE__ */ new Set(),
+      funDecls: /* @__PURE__ */ new Map(),
+      declaredFnKeys: /* @__PURE__ */ new Set(),
+      clauseCountByKey: /* @__PURE__ */ new Map(),
+      fnBranches: /* @__PURE__ */ new Map(),
+      specs: /* @__PURE__ */ new Map(),
+      macroAtoms: /* @__PURE__ */ new Map(),
+      nifEntries: /* @__PURE__ */ new Map(),
+      onLoadEntries: /* @__PURE__ */ new Map(),
+      functionSymbolByKey: /* @__PURE__ */ new Map(),
+      moduleName: void 0,
+      typeDepth: 0,
+      macroDepth: 0,
+      declStack: [],
+      currentFun: void 0,
+      totalBranches: 0,
+      optionalCallbacks: [],
+      moduleSymbol: void 0,
+      stats: { dynamicRemote: 0, unresolvedNifs: 0, macroHeadDecls: 0 },
+      grammarDamaged: false
+    };
+    this.collectPrePass(rootNode, ctx);
+    const DECLARATION_FORMS = /* @__PURE__ */ new Set([
+      "fun_decl",
+      "module_attribute",
+      "pp_define",
+      "record_decl",
+      "type_alias",
+      "opaque",
+      "nominal",
+      "import_attribute",
+      "export_attribute",
+      "export_type_attribute",
+      // `-include` / `-include_lib` are declarations too. An include-ONLY header has
+      // no symbol to publish but a real dependency to record, so calling it
+      // "grammar damaged" would be as false as calling a comment-only header
+      // damaged was.
+      "pp_include",
+      "pp_include_lib"
+    ]);
+    const hasErrorNodes = rootNode.hasError === true;
+    if (hasErrorNodes && !this.prePassForms(rootNode).some((f) => DECLARATION_FORMS.has(f.type))) {
+      ctx.grammarDamaged = true;
+    }
+    const stack = [{ node: rootNode }];
+    while (stack.length > 0) {
+      const { node, isExit } = stack.pop();
+      const type = node.type;
+      const named = node.isNamed;
+      if (isExit) {
+        if (named && TYPE_SCOPE_NODES.has(type)) ctx.typeDepth--;
+        if (named && type === "pp_define") ctx.macroDepth--;
+        if (named && DECL_NODES.has(type)) ctx.declStack.pop();
+        if (named && type === "fun_decl") {
+          const done = ctx.currentFun;
+          if (done) ctx.fnBranches.set(done.key, (ctx.fnBranches.get(done.key) ?? 0) + done.branches);
+          ctx.currentFun = void 0;
+        }
+        continue;
+      }
+      let pushScope = false;
+      if (named && TYPE_SCOPE_NODES.has(type)) ctx.typeDepth++;
+      if (named && type === "pp_define") ctx.macroDepth++;
+      if (named && (TYPE_SCOPE_NODES.has(type) || DECL_NODES.has(type) || type === "pp_define")) pushScope = true;
+      if (type === "ERROR" || node.isMissing) {
+        ctx.errors.push({
+          message: `Erlang syntax ${node.isMissing ? "MISSING" : "ERROR"} node.`,
+          range: this.nodeToRange(node),
+          severity: "warning"
+        });
+      }
+      if (named) {
+        switch (type) {
+          // ---- module-level declarations ----
+          case "module_attribute":
+            this.processModuleAttribute(node, ctx, filePath);
+            break;
+          case "behaviour_attribute":
+            this.processBehaviourAttribute(node, ctx, filePath);
+            break;
+          case "export_attribute":
+            this.processFaListAttribute(node, ctx, filePath, ASTEngine.SymbolKind.Function);
+            break;
+          case "export_type_attribute":
+            this.processFaListAttribute(node, ctx, filePath, ASTEngine.SymbolKind.Type);
+            break;
+          case "import_attribute":
+            this.processImportAttribute(node, ctx, filePath);
+            break;
+          case "optional_callbacks_attribute":
+            this.processOptionalCallbacksAttribute(node, ctx);
+            break;
+          // ---- preprocessor ----
+          case "pp_include":
+          case "pp_include_lib":
+            this.processInclude(node, ctx, type === "pp_include", filePath);
+            break;
+          case "pp_define":
+            this.processDefine(node, ctx);
+            break;
+          // ---- type declarations: the type graph ----
+          case "type_alias":
+          case "opaque":
+          case "nominal":
+            this.processTypeDeclaration(node, ctx, type, filePath);
+            break;
+          case "callback":
+            this.processCallback(node, ctx, filePath);
+            break;
+          case "spec":
+            this.processSpecTypes(node, ctx);
+            break;
+          case "record_decl":
+            this.processRecordDecl(node, ctx, filePath);
+            break;
+          case "field_type":
+            this.processTypeReferences(node, void 0, this.currentSource(ctx) ?? "", ctx);
+            break;
+          // ---- functions ----
+          case "fun_decl":
+            this.enterFunDecl(node, ctx, filePath);
+            break;
+          // ---- evaluation-time edges ----
+          case "call":
+            this.processCall(node, ctx);
+            break;
+          case "record_expr":
+            this.processRecordExpr(node, ctx);
+            break;
+          case "record_field_expr":
+          case "record_index_expr":
+            this.processRecordRead(node, ctx);
+            break;
+          case "record_update_expr":
+            this.processRecordUpdate(node, ctx);
+            break;
+          case "macro_call_expr":
+            this.processMacroUse(node, ctx);
+            break;
+          case "internal_fun":
+            this.processFunReference(node, ctx, false);
+            break;
+          case "external_fun":
+            this.processFunReference(node, ctx, true);
+            break;
+          // ---- control constructs: patterns + decision points ----
+          case "binary_op_expr":
+            this.processBinaryOp(node, ctx);
+            break;
+          case "receive_expr":
+            ctx.patterns["Message Reception (receive)"] = true;
+            ctx.patterns["Actor Model (OTP)"] = true;
+            break;
+          case "case_expr":
+          case "if_expr":
+          case "try_expr":
+          case "maybe_expr":
+            ctx.patterns["Pattern Matching"] = true;
+            break;
+          case "anonymous_fun":
+            ctx.patterns["Higher-Order Functions"] = true;
+            break;
+          default:
+            if (ARM_NODES.has(type)) this.countBranch(ctx);
+            else if (COMPREHENSION_NODES.has(type)) {
+              ctx.patterns["Comprehensions"] = true;
+              this.countBranch(ctx);
+            }
+            break;
+        }
+      }
+      if (pushScope) stack.push({ node, isExit: true });
+      for (let i = node.childCount - 1; i >= 0; i--) {
+        const child = node.child(i);
+        if (child) stack.push({ node: child });
+      }
+    }
+    for (const [key, branches] of ctx.fnBranches) {
+      const sym = ctx.functionSymbolByKey.get(key);
+      if (sym) sym.complexity = 1 + branches;
+    }
+    this.annotateNativeFunctions(ctx);
+    if (ctx.grammarDamaged) {
+      return {
+        language: "erlang",
+        symbols: [],
+        relationships: [],
+        imports: [],
+        exports: [],
+        errors: ctx.errors,
+        metadata: {
+          complexity: 0,
+          linesOfCode: content.split("\n").length,
+          patterns: [],
+          framework: "Erlang",
+          hasFrameworkIntelligence: false,
+          hasTypeInference: false,
+          grammarDamaged: true
+        }
+      };
+    }
+    this.emitOwnership(ctx);
+    if (ctx.moduleName) {
+      ctx.patterns["OTP Module"] = true;
+      const ms = ctx.moduleSymbol;
+      if (ms && ctx.optionalCallbacks.length > 0) {
+        ms.metadata = { ...ms.metadata ?? {}, optionalCallbacks: ctx.optionalCallbacks };
+      }
+    }
+    const pa = [];
+    for (const k in ctx.patterns) pa.push(k);
+    for (const rel of ctx.relationships) {
+      const md = rel.metadata ?? {};
+      if (typeof md.evidenceClass !== "string" || md.evidenceClass.length === 0) {
+        md.evidenceClass = evidenceClassFor(rel.type, Number(rel.confidence), String(rel.target ?? ""));
+        rel.metadata = md;
+      }
+    }
+    return {
+      language: "erlang",
+      symbols: ctx.symbols,
+      relationships: ctx.relationships,
+      imports: ctx.imports,
+      exports: ctx.exports,
+      errors: ctx.errors,
+      metadata: {
+        complexity: 1 + ctx.totalBranches,
+        linesOfCode: content.split("\n").length,
+        patterns: pa,
+        framework: "Erlang",
+        hasFrameworkIntelligence: true,
+        hasTypeInference: false
+      }
+    };
+  }
+  // ==========================================================================
+  // Pre-pass
+  // ==========================================================================
+  /**
+   * ER-D29: every DECLARATION is a direct child of `source_file`. Measured over
+   * the full 4,326-file census: module_attribute, behaviour_attribute,
+   * export_attribute, export_type_attribute, import_attribute,
+   * optional_callbacks_attribute, pp_include, pp_include_lib, pp_define,
+   * type_alias, opaque, nominal, spec, callback, record_decl — every one of them
+   * has `source_file` as its ONLY parent (the census's other "parent" entries are
+   * the anonymous keyword token that shares the type's name, e.g. the `spec`
+   * inside a `spec`).
+   *
+   * So the pre-pass reads the top level instead of walking all ~4,000 nodes per
+   * file again. The one place a declaration can hide is inside conditional
+   * compilation (`-ifdef … -endif`), whose bodies are top-level forms too, so
+   * those containers are descended into explicitly.
+   */
+  collectPrePass(rootNode, ctx) {
+    for (const form of this.prePassForms(rootNode)) {
+      if (form.type !== "pp_define") continue;
+      const lhs = this.getChildByType(form, "macro_lhs");
+      const nameNode = lhs ? this.getChildByType(lhs, "var") ?? this.getChildByType(lhs, "atom") : void 0;
+      if (!nameNode?.text) continue;
+      for (let i = 0; i < form.namedChildCount; i++) {
+        const body = form.namedChild(i);
+        if (!body || body.type !== "atom" || !body.text) continue;
+        ctx.macroAtoms.set(nameNode.text, body.text);
+        break;
+      }
+    }
+    for (const top of this.prePassForms(rootNode)) {
+      if (top.type !== "module_attribute") continue;
+      const atom = this.getChildByType(top, "atom");
+      if (atom?.text) {
+        ctx.moduleName = atom.text;
+        break;
+      }
+      const expanded = this.expandModuleNameMacro(top, ctx);
+      if (expanded) {
+        ctx.moduleName = expanded;
+        break;
+      }
+    }
+    const forms = this.prePassForms(rootNode);
+    const stack = [];
+    for (let i = forms.length - 1; i >= 0; i--) {
+      const top = forms[i];
+      if (top) stack.push(top);
+    }
+    while (stack.length > 0) {
+      const node = stack.pop();
+      if (!node.isNamed) continue;
+      const type = node.type;
+      if (type === "fun_decl") {
+        const clauses = this.collectChildrenByType(node, "function_clause");
+        const head = this.readClauseHead(clauses[0], ctx.moduleName);
+        if (head) {
+          ctx.funDecls.set(node.startIndex, {
+            name: head.name,
+            arity: head.arity,
+            clauseCount: clauses.length,
+            macroHead: head.macroHead,
+            startIndex: node.startIndex
+          });
+          const key = this.fnKey(head.name, head.arity);
+          ctx.declaredFnKeys.add(key);
+          ctx.clauseCountByKey.set(key, (ctx.clauseCountByKey.get(key) ?? 0) + clauses.length);
+          if (head.macroHead) ctx.stats.macroHeadDecls++;
+        }
+      } else if (type === "spec") {
+        const nameNode = this.getChildByType(node, "atom");
+        const sig = this.getChildByType(node, "type_sig");
+        if (nameNode?.text && sig) {
+          const params = this.namedChildrenTexts(this.getChildByType(sig, "expr_args"));
+          ctx.specs.set(this.fnKey(nameNode.text, params.length), {
+            params,
+            ret: this.typeSigReturnText(sig),
+            line: nameNode.startPosition.row + 1
+          });
+        }
+      } else if (type === "wild_attribute") {
+        const attrName = this.attrNameText(node);
+        if (attrName === "nifs") this.collectAttributeFaEntries(node, ctx.nifEntries, ctx);
+        else if (attrName === "on_load") this.collectAttributeFaEntries(node, ctx.onLoadEntries, ctx);
+      } else if (PRE_PASS_DESCEND.has(type)) {
+        for (let i = node.namedChildCount - 1; i >= 0; i--) {
+          const c = node.namedChild(i);
+          if (c) stack.push(c);
+        }
+      }
+    }
+  }
+  /**
+   * The forms the pre-pass reads: `source_file`'s named children, with any
+   * conditional-compilation or grammar-ERROR container's children spliced in
+   * (ER-D29). Every DECLARATION lives here — measured over the 4,326-file
+   * census — so the pre-pass costs O(declarations) instead of a second walk of
+   * all ~4,000 nodes per file.
+   */
+  prePassForms(rootNode) {
+    const out = [];
+    const stack = [];
+    for (let i = rootNode.namedChildCount - 1; i >= 0; i--) {
+      const c = rootNode.namedChild(i);
+      if (c) stack.push(c);
+    }
+    while (stack.length > 0) {
+      const n = stack.pop();
+      if (!n.isNamed) continue;
+      if (PRE_PASS_DESCEND.has(n.type)) {
+        for (let i = n.namedChildCount - 1; i >= 0; i--) {
+          const c = n.namedChild(i);
+          if (c) stack.push(c);
+        }
+        continue;
+      }
+      out.push(n);
+    }
+    return out;
+  }
+  fnKey(name, arity) {
+    return `${name}/${arity}`;
+  }
+  /**
+   * The inverse of `fnKey`, for the two places that must go back from a collected
+   * "name/arity" entry to a symbol. Erlang function names cannot contain `/`, so
+   * the LAST slash is the separator and a name like `mod/1` never appears here.
+   */
+  splitFnKey(key) {
+    const i = key.lastIndexOf("/");
+    return i === -1 ? [key, ""] : [key.slice(0, i), key.slice(i + 1)];
+  }
+  /**
+   * A clause head's declared name and arity.
+   *
+   * ER-D25: the name is normally the head's `atom`, but a MACRO-headed
+   * definition carries a `macro_call_expr` instead, and the real function name
+   * only exists AFTER the preprocessor expands it. Measured over the whole
+   * corpus, every one of the 79 such clauses is `?MODULE() -> …` — the OTP test
+   * suite idiom — and `?MODULE` is a PREDEFINED macro whose value is this file's
+   * module atom, so the expansion is exact: the function is `<module>/<arity>`.
+   * That is the OTP `yes_2.erl` / `stacktrace.erl` shape, and resolving it
+   * recovers 79 function definitions that previously produced NO symbol at all
+   * (the "unreadable clause name" the pre-ER3 oracle had to mirror).
+   *
+   * Any OTHER macro head is refused on purpose. `-define(DOUBLE(X), helper(X))`
+   * plus `?DOUBLE(X) -> X` declares `helper/1`, not `DOUBLE/1`: naming the macro
+   * would FABRICATE a function that does not exist, and the analyzer does not
+   * expand macros. The clause's body is then attributed to the module, and the
+   * parse is reported by the error channel.
+   */
+  readClauseHead(clause, moduleName) {
+    if (!clause) return void 0;
+    const arity = this.countArgs(this.getChildByType(clause, "expr_args"));
+    const direct = this.getChildByType(clause, "atom") ?? this.getChildByType(clause, "var");
+    if (direct?.text) return { name: direct.text, arity, macroHead: false };
+    const macro = this.getChildByType(clause, "macro_call_expr");
+    const macroName = macro ? (this.getChildByType(macro, "var") ?? this.getChildByType(macro, "atom"))?.text : void 0;
+    if (macroName === "MODULE" && moduleName) return { name: moduleName, arity, macroHead: true };
+    return void 0;
+  }
+  /**
+   * A parameter list's arity: the named children of `expr_args`, comments
+   * excluded. ONE counter serves a clause head, a call site and a `fa`, so
+   * `f/1` and `f/2` can never be confused anywhere in this analyzer (ER-D2).
+   */
+  countArgs(args) {
+    if (!args) return 0;
+    let n = 0;
+    for (let i = 0; i < args.namedChildCount; i++) {
+      const c = args.namedChild(i);
+      if (c && c.type !== "comment") n++;
+    }
+    return n;
+  }
+  namedChildrenTexts(args) {
+    if (!args) return [];
+    const out = [];
+    for (let i = 0; i < args.namedChildCount; i++) {
+      const c = args.namedChild(i);
+      if (c && c.type !== "comment") out.push(c.text);
+    }
+    return out;
+  }
+  /** The text after a type signature's `->`, or undefined when it has none. */
+  typeSigReturnText(sig) {
+    for (let i = 0; i < sig.childCount; i++) {
+      const c = sig.child(i);
+      if (c?.type !== "->") continue;
+      const t = sig.text.slice(c.endIndex - sig.startIndex).trim();
+      return t.length > 0 ? t : void 0;
+    }
+    return void 0;
+  }
+  // ==========================================================================
+  // Module-level declarations
+  // ==========================================================================
+  /**
+   * The module name a `-module(?MACRO)` attribute expands to, or undefined when
+   * it cannot be known without running the preprocessor.
+   *
+   * ER-D34. Common Test suites name themselves through a macro by convention, so
+   * this is not exotic: otp/lib/kernel/test/file_SUITE.erl writes
+   * `-module(?FILE_SUITE).` and is the only such file in the 4,326-file corpus
+   * — rare, but the failure was silent and total. The attribute parsed as a
+   * module_attribute with a macro_call_expr child, and a reader that required an
+   * `atom` emitted no module symbol at all, so the file fell back to being owned
+   * by its path: wrong owner on every edge, no module in the store, exports
+   * unmatched.
+   */
+  expandModuleNameMacro(attr, ctx) {
+    const macro = this.getChildByType(attr, "macro_call_expr") ?? this.getChildByType(attr, "macro_expr");
+    if (!macro) return void 0;
+    const nameNode = this.getChildByType(macro, "var") ?? this.getChildByType(macro, "atom");
+    if (!nameNode?.text) return void 0;
+    return ctx.macroAtoms.get(nameNode.text);
+  }
+  processModuleAttribute(node, ctx, filePath) {
+    if (ctx.moduleSymbol) return;
+    let nameNode = this.getChildByType(node, "atom");
+    let moduleNameOverride;
+    if (!nameNode?.text) {
+      const macro = this.getChildByType(node, "macro_call_expr") ?? this.getChildByType(node, "macro_expr");
+      const macroName = macro ? this.getChildByType(macro, "var") ?? this.getChildByType(macro, "atom") : void 0;
+      const expanded = this.expandModuleNameMacro(node, ctx);
+      if (!macroName?.text) return;
+      const source = expanded ?? this.ownerNameOf(ctx) ?? node.text;
+      this.pushRel(
+        ctx,
+        source,
+        macroName.text,
+        ASTEngine.RelationshipType.References,
+        0.9,
+        {
+          erlangSpecific: true,
+          context: "macro use",
+          isModuleNameMacro: true,
+          moduleNameResolved: !!expanded
+        },
+        macroName.startPosition.row + 1
+      );
+      if (!expanded) return;
+      moduleNameOverride = expanded;
+      nameNode = macroName;
+    }
+    const moduleName = moduleNameOverride ?? nameNode.text;
+    const symbol = {
+      name: moduleName,
+      kind: ASTEngine.SymbolKind.Module,
+      range: this.nodeToRange(node),
+      metadata: {
+        nodeType: "module_attribute",
+        line: nameNode.startPosition.row + 1,
+        ...moduleNameOverride ? { nameFromMacro: nameNode.text, expandsTo: moduleNameOverride } : {}
+      }
+    };
+    ctx.moduleSymbol = symbol;
+    ctx.symbols.push(symbol);
+    ctx.moduleName = moduleName;
+    ctx.declStack.push({ source: moduleName, kind: "module" });
+    void filePath;
+  }
+  processBehaviourAttribute(node, ctx, filePath) {
+    const beNode = this.getChildByType(node, "atom");
+    if (!beNode?.text) return;
+    this.pushRel(
+      ctx,
+      ctx.moduleName ?? filePath,
+      beNode.text,
+      ASTEngine.RelationshipType.Implements,
+      1,
+      { erlangSpecific: true, behaviour: beNode.text, context: "OTP behaviour callback implementation" },
+      beNode.startPosition.row + 1
+    );
+    if (OTP_BEHAVIOURS.has(beNode.text)) {
+      ctx.patterns["Actor Model (OTP)"] = true;
+      ctx.patterns["OTP Behaviours"] = true;
+    }
+  }
+  /** `-export` / `-export_type`: a list of `fa` nodes. */
+  processFaListAttribute(node, ctx, filePath, kind) {
+    const owner = ctx.moduleName ?? filePath;
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child?.type !== "fa") continue;
+      const fa = this.readFa(child, ctx.moduleName);
+      if (!fa) continue;
+      ctx.exports.push({
+        name: fa.name,
+        arity: fa.arity,
+        file: filePath,
+        line: fa.line,
+        kind,
+        ...kind === ASTEngine.SymbolKind.Type ? { metadata: { isTypeExport: true } } : {}
+      });
+      this.pushRel(
+        ctx,
+        owner,
+        fa.name,
+        ASTEngine.RelationshipType.Exports,
+        1,
+        {
+          erlangSpecific: true,
+          arity: fa.arity,
+          exportForm: kind === ASTEngine.SymbolKind.Type ? "export_type" : "export",
+          isTypeExport: kind === ASTEngine.SymbolKind.Type
+        },
+        fa.line
+      );
+    }
+  }
+  processImportAttribute(node, ctx, filePath) {
+    const modNode = this.getChildByType(node, "atom");
+    if (!modNode?.text) return;
+    const funcs = [];
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child?.type !== "fa") continue;
+      const fa = this.readFa(child, ctx.moduleName);
+      if (fa) funcs.push(fa.name);
+    }
+    ctx.imports.push({
+      module: modNode.text,
+      path: modNode.text,
+      importType: "named",
+      // ER-D20: `-import(lists, …)` names an OTP module, which by construction
+      // cannot be declared in this file — M60/#910's `is_external` contract,
+      // which the file-dependency engine reads to keep system dependencies out
+      // of internal resolution. The old code wrote no classification at all.
+      isExternal: true,
+      importedNames: funcs,
+      items: funcs,
+      file: filePath,
+      line: modNode.startPosition.row + 1,
+      isNif: false
+    });
+    this.pushRel(
+      ctx,
+      ctx.moduleName ?? filePath,
+      modNode.text,
+      ASTEngine.RelationshipType.Imports,
+      1,
+      { erlangSpecific: true, isModuleImport: true, importedFunctions: funcs, isExternal: true },
+      modNode.startPosition.row + 1
+    );
+    this.pushRel(
+      ctx,
+      ctx.moduleName ?? filePath,
+      modNode.text,
+      ASTEngine.RelationshipType.References,
+      1,
+      { erlangSpecific: true, isModuleImport: true, importedFunctions: funcs },
+      modNode.startPosition.row + 1
+    );
+  }
+  /**
+   * `-optional_callbacks([f/2, …])` names callbacks a behaviour MAY omit. It
+   * declares nothing, so no symbol and no edge; the names are recorded on the
+   * module symbol, which is the only place they are true.
+   */
+  processOptionalCallbacksAttribute(node, ctx) {
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child?.type !== "fa") continue;
+      const fa = this.readFa(child, ctx.moduleName);
+      if (fa) ctx.optionalCallbacks.push(this.fnKey(fa.name, fa.arity));
+    }
+  }
+  // ==========================================================================
+  // Preprocessor
+  // ==========================================================================
+  /**
+   * `-include("x.hrl")` / `-include_lib("kernel/include/x.hrl")`.
+   *
+   * ER-D46 (2026-10-23): THE LABEL IS `part_of`, NOT `references`. An include is
+   * FILE INCLUSION: the header is textually spliced into THIS module's single
+   * compilation scope, it cannot be compiled as a unit of its own, and it
+   * imports nothing — which is the vocabulary's `part_of` contract
+   * (`src/ast/types.ts:PartOf`: "a library unit INCLUDES a part file … one
+   * compilation unit"), the same construct php's include/require and fsharp's
+   * `#load` were relabelled to. `references` said the path was MENTIONED; it
+   * cannot say the file became part of this unit.
+   *
+   * DIRECTION AND ROLE follow the directive's own: source = the file carrying
+   * the directive (its module symbol, else its path — ER-D32); target = the
+   * path as written. `metadata.partRole:"library"` because THIS file is the
+   * including library and names the part. `isExternal` keeps ER-D20's
+   * classification: `-include_lib` resolves through the code path (a system
+   * header), `-include` is this project's.
+   *
+   * NOT `imports`: `-import(Mod, [f/a])` stays imports + references (ER-D41) —
+   * a name import creates binding scope, an include splices text. The two
+   * constructs were distinguished by the fixture `imports-and-try` before this
+   * change and are pinned apart by the `extended-part-of` fixture after it.
+   *
+   * THE TIER FOLLOWS THE CONSTRUCT, as php's `part_of` relabel did: a file
+   * inclusion directive is `import_based`, confidence 1.0 (the directive IS the
+   * syntax) — not the old row's 0.9/`reference_qualified`, which was the
+   * mention reading the relabel exists to replace.
+   *
+   * M59 (#825): the line belongs to the NAME-BEARING node — the path STRING,
+   * never the `-include` keyword. The fixture erlang/callsite-lines-825 splits
+   * the attribute across three lines precisely to pin that difference.
+   */
+  processInclude(node, ctx, isPlain, filePath) {
+    const fNode = this.getChildByType(node, "string");
+    if (!fNode) return;
+    const includePath = this.stripQuotes(fNode.text);
+    const line = fNode.startPosition.row + 1;
+    ctx.imports.push({
+      module: includePath,
+      path: includePath,
+      importType: isPlain ? "include" : "include_lib",
+      // ER-D20: `-include_lib("kernel/include/…")` resolves through the code
+      // path — a system dependency. `-include("local.hrl")` is this project's.
+      isExternal: !isPlain,
+      file: includePath,
+      line,
+      isNif: false
+    });
+    this.pushRel(
+      ctx,
+      ctx.moduleName ?? filePath,
+      includePath,
+      ASTEngine.RelationshipType.PartOf,
+      1,
+      {
+        erlangSpecific: true,
+        // THE MANDATORY ROLE FIELD (part_of's contract): this file carries the
+        // directive and names the part, so it is the library side of the pair.
+        partRole: "library",
+        isInclude: isPlain,
+        isLibInclude: !isPlain,
+        // A PATH TARGET, not a symbol: the include names a file. Consumers that
+        // resolve names must not read it as one, and the declaration's
+        // resolution caveat relies on this marker.
+        isFileInclusion: true,
+        // The tier follows the construct (ER-D46) — see the doc block above.
+        evidenceClass: "import_based"
+      },
+      line
+    );
+  }
+  processDefine(node, ctx) {
+    const lhs = this.getChildByType(node, "macro_lhs");
+    if (!lhs) return;
+    const nameNode = this.getChildByType(lhs, "var") ?? this.getChildByType(lhs, "atom");
+    if (!nameNode?.text) return;
+    const params = this.getChildByType(lhs, "var_args");
+    const isFunctionLike = params !== void 0;
+    ctx.symbols.push({
+      name: nameNode.text,
+      kind: isFunctionLike ? ASTEngine.SymbolKind.Macro : ASTEngine.SymbolKind.Constant,
+      range: this.nodeToRange(node),
+      ownerName: this.ownerNameOf(ctx),
+      ownerKind: ASTEngine.SymbolKind.Module,
+      metadata: {
+        nodeType: "macro_definition",
+        isMacro: true,
+        isFunctionLike,
+        isFunctionLikeMacro: isFunctionLike,
+        parameterCount: this.countArgs(params),
+        line: nameNode.startPosition.row + 1
+      }
+    });
+    ctx.declStack.push({ source: nameNode.text, kind: "macro" });
+  }
+  // ==========================================================================
+  // Types
+  // ==========================================================================
+  processTypeDeclaration(node, ctx, type, filePath) {
+    const typeNameNode = this.getChildByType(node, "type_name");
+    const nameNode = typeNameNode ? this.getChildByType(typeNameNode, "atom") : this.getChildByType(node, "atom");
+    const typeName = nameNode?.text ?? (typeNameNode ? this.stripFirstParen(typeNameNode.text) : void 0);
+    if (!typeName) return;
+    const params = typeNameNode ? this.getChildByType(typeNameNode, "var_args") : void 0;
+    ctx.symbols.push({
+      name: typeName,
+      kind: ASTEngine.SymbolKind.Type,
+      range: this.nodeToRange(node),
+      ownerName: this.ownerNameOf(ctx),
+      ownerKind: ASTEngine.SymbolKind.Module,
+      metadata: {
+        nodeType: type,
+        isOpaque: type === "opaque",
+        isNominal: type === "nominal",
+        arity: this.countArgs(params),
+        line: (nameNode ?? typeNameNode ?? node).startPosition.row + 1
+      }
+    });
+    ctx.declStack.push({ source: typeName, kind: "type" });
+    this.processTypeReferences(node, typeNameNode, typeName, ctx);
+  }
+  /**
+   * ER-G3: a behaviour's callback contract is a Method owned by the module.
+   * The arity is the type signature's parameter count. A behaviour that also
+   * DEFINES its callback (`-callback init/1` plus `init/1 -> …`) yields ONE
+   * symbol: both declare the same (name, arity) identity.
+   */
+  processCallback(node, ctx, filePath) {
+    const nameNode = this.getChildByType(node, "atom");
+    if (!nameNode?.text) return;
+    const sig = this.getChildByType(node, "type_sig");
+    const key = this.fnKey(nameNode.text, this.countArgs(sig ? this.getChildByType(sig, "expr_args") : void 0));
+    const existing = ctx.functionSymbolByKey.get(key);
+    if (existing) {
+      existing.metadata = {
+        ...existing.metadata ?? {},
+        isCallback: true,
+        callbackLine: nameNode.startPosition.row + 1
+      };
+    } else {
+      const symbol = {
+        name: nameNode.text,
+        kind: ASTEngine.SymbolKind.Method,
+        range: this.nodeToRange(node),
+        ownerName: this.ownerNameOf(ctx),
+        ownerKind: ASTEngine.SymbolKind.Module,
+        metadata: {
+          nodeType: "callback",
+          isCallback: true,
+          arity: this.countArgs(sig ? this.getChildByType(sig, "expr_args") : void 0),
+          line: nameNode.startPosition.row + 1
+        }
+      };
+      ctx.functionSymbolByKey.set(key, symbol);
+      ctx.symbols.push(symbol);
+    }
+    this.processTypeReferences(node, nameNode, nameNode.text, ctx);
+    ctx.declStack.push({ source: nameNode.text, kind: "callback" });
+  }
+  processSpecTypes(node, ctx) {
+    const nameNode = this.getChildByType(node, "atom");
+    if (!nameNode?.text) return;
+    this.processTypeReferences(node, nameNode, nameNode.text, ctx);
+    ctx.declStack.push({ source: nameNode.text, kind: "spec" });
+  }
+  /**
+   * A record is the struct analog: one Struct symbol owned by the module, one
+   * Property per field owned by the record. Field DEFAULTS are EVALUATIONS and
+   * field TYPES are TYPE references, both attributed to the RECORD (ER-D12) —
+   * `-record(state, {t = erlang:make_ref()})` calls a function from the record's
+   * own declaration, and `-record(r, {f :: pid()})` names a type from it.
+   */
+  processRecordDecl(node, ctx, filePath) {
+    const nameNode = this.getChildByType(node, "atom");
+    if (!nameNode?.text) return;
+    const recordName = nameNode.text;
+    ctx.declStack.push({ source: recordName, kind: "record" });
+    const fields = [];
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child?.type !== "record_field") continue;
+      const fieldName = this.getChildByType(child, "atom");
+      if (!fieldName?.text) continue;
+      fields.push(fieldName.text);
+      const fieldType = this.getChildByType(child, "field_type");
+      const defaultExpr = this.getChildByType(child, "field_expr");
+      ctx.symbols.push({
+        name: fieldName.text,
+        kind: ASTEngine.SymbolKind.Property,
+        range: this.nodeToRange(child),
+        ownerName: recordName,
+        ownerKind: ASTEngine.SymbolKind.Struct,
+        metadata: {
+          nodeType: "record_field",
+          isRecordField: true,
+          line: fieldName.startPosition.row + 1,
+          ...defaultExpr ? { defaultValue: defaultExpr.text } : {},
+          ...fieldType ? { fieldType: fieldType.text } : {}
+        }
+      });
+      if (fieldType) this.processTypeReferences(fieldType, void 0, recordName, ctx);
+    }
+    ctx.symbols.push({
+      name: recordName,
+      kind: ASTEngine.SymbolKind.Struct,
+      range: this.nodeToRange(node),
+      ownerName: this.ownerNameOf(ctx),
+      ownerKind: ASTEngine.SymbolKind.Module,
+      metadata: { nodeType: "record_decl", fields, line: nameNode.startPosition.row + 1 }
+    });
+  }
+  // ==========================================================================
+  // Functions
+  // ==========================================================================
+  enterFunDecl(node, ctx, filePath) {
+    const info = ctx.funDecls.get(node.startIndex);
+    if (!info) {
+      ctx.declStack.push({ source: ctx.moduleName ?? filePath, kind: "module" });
+      return;
+    }
+    const name = info.name;
+    const arity = info.arity;
+    const key = this.fnKey(name, arity);
+    const clause = this.collectChildrenByType(node, "function_clause")[0];
+    let symbol = ctx.functionSymbolByKey.get(key);
+    if (symbol) {
+      this.extendRange(symbol, node);
+      if (symbol.kind === ASTEngine.SymbolKind.Method && symbol.metadata?.isCallback) {
+        symbol.kind = ASTEngine.SymbolKind.Function;
+        symbol.metadata = {
+          ...symbol.metadata ?? {},
+          definedHere: true,
+          ...clause ? { definitionLine: clause.startPosition.row + 1, line: clause.startPosition.row + 1 } : {}
+        };
+        if (clause) {
+          const r = this.nodeToRange(clause);
+          symbol.range.startLine = r.startLine;
+          symbol.range.startColumn = r.startColumn;
+          if (symbol.range.startIndex !== void 0 && r.startIndex !== void 0) {
+            symbol.range.startIndex = r.startIndex;
+          }
+        }
+      }
+    } else {
+      symbol = this.makeFunctionSymbol(ctx, name, arity, clause, node, info, filePath);
+      ctx.functionSymbolByKey.set(key, symbol);
+      ctx.symbols.push(symbol);
+    }
+    ctx.currentFun = { name, key, symbol, branches: 0 };
+    const extra = (ctx.clauseCountByKey.get(key) ?? 1) - 1;
+    for (let i = 0; i < extra; i++) this.countBranch(ctx);
+    ctx.declStack.push({ source: name, kind: "function" });
+  }
+  extendRange(symbol, node) {
+    const r = this.nodeToRange(node);
+    symbol.range.endLine = Math.max(symbol.range.endLine, r.endLine);
+    symbol.range.endColumn = Math.max(symbol.range.endColumn, r.endColumn);
+    if (symbol.range.endIndex !== void 0 && r.endIndex !== void 0) {
+      symbol.range.endIndex = Math.max(symbol.range.endIndex, r.endIndex);
+    }
+  }
+  /**
+   * The name of the macro sitting in a remote-module position, or undefined when
+   * the module is a plain atom.
+   *
+   * ER-D25 vs ER-D35. `?MODULE:f(X)` is the idiomatic self-dispatch and resolves
+   * to this file's module. `?ANYTHING_ELSE:f(X)` does not: the macro is an
+   * ordinary build-time constant whose value this analyzer does not expand, and
+   * treating it as `?MODULE` fabricates a self-call. The distinction is the
+   * macro's NAME, and the full-corpus draw is what forced it — otp's
+   * `file_SUITE.erl` writes `?FILE_MODULE:read_file_info(Priv)`, and before this
+   * check every one of those calls was reported as a call into its own module.
+   */
+  remoteMacroModuleName(remoteModule) {
+    if (!remoteModule) return void 0;
+    const macro = this.getChildByType(remoteModule, "macro_call_expr") ?? this.getChildByType(remoteModule, "macro_expr");
+    if (!macro) return void 0;
+    const nameNode = this.getChildByType(macro, "var") ?? this.getChildByType(macro, "atom");
+    return nameNode?.text;
+  }
+  makeFunctionSymbol(ctx, name, arity, clause, declNode, info, filePath) {
+    const key = this.fnKey(name, arity);
+    const spec = ctx.specs.get(key);
+    const params = this.namedChildrenOf(
+      clause ? this.getChildByType(clause, "expr_args") : void 0
+    ).map((c, i) => ({
+      // ER-D21: a clause head is a PATTERN, not a declaration. The binding's
+      // name is carried when the pattern is a plain variable; the pattern itself
+      // is always carried, because that is what the head really says.
+      name: c.type === "var" ? c.text : "",
+      pattern: c.text,
+      ...spec?.params[i] ? { type: spec.params[i] } : {}
+    }));
+    return {
+      name,
+      kind: ASTEngine.SymbolKind.Function,
+      range: this.nodeToRange(declNode),
+      ownerName: this.ownerNameOf(ctx),
+      ownerKind: ASTEngine.SymbolKind.Module,
+      parameters: params,
+      ...spec?.ret ? { returnType: spec.ret } : {},
+      complexity: 1,
+      metadata: {
+        nodeType: "function_clause",
+        arity,
+        clauseCount: ctx.clauseCountByKey.get(key) ?? 1,
+        ...clause ? { line: clause.startPosition.row + 1 } : {},
+        ...info?.macroHead ? { isMacroHead: true } : {},
+        ...spec ? { hasSpec: true, specLine: spec.line } : {}
+      }
+    };
+  }
+  /**
+   * ER-D22: `-nifs([f/1])` and `-on_load([g/0])` are ATTRIBUTES about functions,
+   * not declarations. The old code minted a second Function symbol per entry —
+   * and could not have: `attr_name.text` is `-nifs` (the dash is INSIDE the
+   * node), so its `=== "nifs"` test never matched, and the entries are
+   * `binary_op_expr` (`f/1`), not the `fa` the branch then looked for. Two
+   * independent defects hid the same behaviour. The entries now annotate the
+   * declared function, which is the honest surface: a NIF always has an
+   * Erlang-visible stub.
+   */
+  annotateNativeFunctions(ctx) {
+    const owner = this.ownerNameOf(ctx);
+    for (const [key, line] of ctx.nifEntries) {
+      const sym = ctx.functionSymbolByKey.get(key);
+      if (sym) {
+        sym.metadata = { ...sym.metadata ?? {}, isNif: true };
+        continue;
+      }
+      const [name, arityText] = this.splitFnKey(key);
+      const arity = Number(arityText);
+      if (!name || !Number.isFinite(arity)) {
+        ctx.stats.unresolvedNifs++;
+        continue;
+      }
+      const published = {
+        name,
+        kind: ASTEngine.SymbolKind.Function,
+        range: { startLine: line, startColumn: 1, endLine: line, endColumn: 1 },
+        ownerName: owner,
+        ownerKind: ASTEngine.SymbolKind.Module,
+        metadata: {
+          nodeType: "nif_declaration",
+          arity,
+          clauseCount: 0,
+          isNif: true,
+          declaredByNifsAttribute: true,
+          line
+        }
+      };
+      ctx.symbols.push(published);
+      ctx.functionSymbolByKey.set(key, published);
+    }
+    for (const [key] of ctx.onLoadEntries) {
+      const sym = ctx.functionSymbolByKey.get(key);
+      if (sym) sym.metadata = { ...sym.metadata ?? {}, isOnLoad: true };
+    }
+  }
+  // ==========================================================================
+  // Calls
+  // ==========================================================================
+  processCall(node, ctx) {
+    const callee = node.namedChild(0);
+    if (!callee) return;
+    if (callee.type === "atom" && SPAWN_BIFS.has(callee.text)) {
+      ctx.patterns["Actor Model (OTP)"] = true;
+      ctx.patterns["Process Spawning"] = true;
+      return;
+    }
+    if (ctx.typeDepth > 0) return;
+    if (ctx.macroDepth > 0) return;
+    const source = this.currentSource(ctx);
+    if (!source) return;
+    const arity = this.countArgs(this.getChildByType(node, "expr_args"));
+    const remote = this.getChildByType(node, "remote");
+    if (remote) {
+      const remoteModule = this.getChildByType(remote, "remote_module");
+      const modAtom = remoteModule ? this.getChildByType(remoteModule, "atom") : void 0;
+      const macroMod = this.remoteMacroModuleName(remoteModule);
+      const fnAtom = this.getChildByType(remote, "atom");
+      if (!fnAtom?.text) {
+        ctx.stats.dynamicRemote++;
+        return;
+      }
+      if (modAtom?.text) {
+        this.pushRel(
+          ctx,
+          source,
+          `${modAtom.text}:${fnAtom.text}`,
+          ASTEngine.RelationshipType.Calls,
+          0.9,
+          { erlangSpecific: true, context: "remote function call", callArity: arity },
+          fnAtom.startPosition.row + 1
+        );
+        return;
+      }
+      if (macroMod) {
+        const mod = macroMod === "MODULE" ? ctx.moduleName : void 0;
+        if (!mod) {
+          ctx.stats.dynamicRemote++;
+          return;
+        }
+        this.pushRel(
+          ctx,
+          source,
+          `${mod}:${fnAtom.text}`,
+          ASTEngine.RelationshipType.Calls,
+          0.9,
+          { erlangSpecific: true, context: "remote function call", callArity: arity, macroModule: true },
+          fnAtom.startPosition.row + 1
+        );
+        return;
+      }
+      ctx.stats.dynamicRemote++;
+      return;
+    }
+    if (callee.type !== "atom" || !callee.text) return;
+    if (!ctx.declaredFnKeys.has(this.fnKey(callee.text, arity))) return;
+    this.pushRel(
+      ctx,
+      source,
+      callee.text,
+      ASTEngine.RelationshipType.Calls,
+      0.9,
+      { erlangSpecific: true, context: "local function call", callArity: arity },
+      callee.startPosition.row + 1
+    );
+  }
+  // ==========================================================================
+  // Records
+  // ==========================================================================
+  processRecordExpr(node, ctx) {
+    const nameNode = this.getChildByType(node, "record_name");
+    const atom = nameNode ? this.getChildByType(nameNode, "atom") : void 0;
+    if (!atom?.text) return;
+    const source = this.currentSource(ctx);
+    if (!source) return;
+    const line = atom.startPosition.row + 1;
+    if (ctx.typeDepth > 0) {
+      this.pushRel(
+        ctx,
+        source,
+        atom.text,
+        ASTEngine.RelationshipType.References,
+        1,
+        // The context is the generic type-dependency label so the whole family
+        // reads uniformly, and the record-ness is an explicit flag rather than a
+        // second context string: a consumer asking "is this a dependency on a
+        // record?" then has a boolean to read instead of a string to match.
+        { erlangSpecific: true, context: "type reference", isRecordType: true },
+        line
+      );
+      return;
+    }
+    if (this.isPatternPosition(node)) return;
+    this.pushRel(
+      ctx,
+      source,
+      atom.text,
+      ASTEngine.RelationshipType.Instantiates,
+      1,
+      { erlangSpecific: true, isRecordExpr: true },
+      line
+    );
+  }
+  /**
+   * ER-D24 (user finding #1, ER-G4): a member READ is the dominant OTP idiom —
+   * every gen_server state transition reads the state record. Reads and index
+   * reads emit `uses` to the RECORD and to the touched FIELD (java/kotlin
+   * member-read parity, #739/#740). A read in PATTERN position is a match and
+   * emits nothing.
+   */
+  processRecordRead(node, ctx) {
+    if (ctx.typeDepth > 0 || this.isPatternPosition(node)) return;
+    const source = this.currentSource(ctx);
+    if (!source) return;
+    const recordAtom = this.atomIn(this.getChildByType(node, "record_name"));
+    if (recordAtom) {
+      this.pushRel(
+        ctx,
+        source,
+        recordAtom.text,
+        ASTEngine.RelationshipType.Uses,
+        1,
+        { erlangSpecific: true, context: "record member read" },
+        recordAtom.startPosition.row + 1
+      );
+    }
+    const fieldAtom = this.atomIn(this.getChildByType(node, "record_field_name"));
+    if (fieldAtom) {
+      this.pushRel(
+        ctx,
+        source,
+        fieldAtom.text,
+        ASTEngine.RelationshipType.Uses,
+        1,
+        { erlangSpecific: true, context: "record member read" },
+        fieldAtom.startPosition.row + 1
+      );
+    }
+  }
+  /**
+   * ER-D4: an UPDATE is member mutation of an existing value, never a
+   * construction — so `uses`, never `instantiates` — and it touches the RECORD
+   * plus every ASSIGNED field.
+   */
+  processRecordUpdate(node, ctx) {
+    if (ctx.typeDepth > 0 || this.isPatternPosition(node)) return;
+    const source = this.currentSource(ctx);
+    if (!source) return;
+    const recordAtom = this.atomIn(this.getChildByType(node, "record_name"));
+    if (recordAtom) {
+      this.pushRel(
+        ctx,
+        source,
+        recordAtom.text,
+        ASTEngine.RelationshipType.Uses,
+        1,
+        { erlangSpecific: true, context: "record field update" },
+        recordAtom.startPosition.row + 1
+      );
+    }
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child?.type !== "record_field") continue;
+      const fieldAtom = this.getChildByType(child, "atom");
+      if (!fieldAtom?.text) continue;
+      this.pushRel(
+        ctx,
+        source,
+        fieldAtom.text,
+        ASTEngine.RelationshipType.Uses,
+        1,
+        { erlangSpecific: true, context: "record field update" },
+        fieldAtom.startPosition.row + 1
+      );
+    }
+  }
+  // ==========================================================================
+  // Macros and fun values
+  // ==========================================================================
+  /**
+   * ER-D9 (user finding #2, ER-G1): every `?MACRO` use is a reference to the
+   * macro's Constant symbol, per site, whether or not the macro is defined in
+   * this file. A use of a header-defined macro lands as an EXTERNAL target,
+   * which is the honest answer — the declaration lives in another file, and the
+   * fixture erlang/refs-er2 pins exactly that.
+   *
+   * The name is the `var` child when the macro takes no arguments and the `atom`
+   * child when it does (`?FOO(A)` → atom + macro_call_args). Reading only the
+   * `var` would drop every function-like macro use (measured: 2,691 of the 6,612
+   * macro_call_expr sites in 300 corpus files carry a macro_call_args).
+   */
+  processMacroUse(node, ctx) {
+    if (node.parent?.type === "module_attribute") return;
+    const nameNode = this.getChildByType(node, "var") ?? this.getChildByType(node, "atom");
+    if (!nameNode?.text) return;
+    const source = this.currentSource(ctx);
+    if (!source) return;
+    this.pushRel(
+      ctx,
+      source,
+      nameNode.text,
+      ASTEngine.RelationshipType.References,
+      1,
+      { erlangSpecific: true, context: "macro use" },
+      nameNode.startPosition.row + 1
+    );
+  }
+  /**
+   * ER-D10 (user finding #4, ER-G2): `fun f/1` and `fun lists:map/2` name a
+   * function VALUE. Taking a reference is not calling it, so these are
+   * `references`, never `calls` (the fixture forbids a calls edge at the same
+   * site). A qualified reference keeps its module (ER-D1); `fun ?MODULE:g/0`
+   * expands to this module exactly like the remote-call rule.
+   */
+  processFunReference(node, ctx, external) {
+    if (ctx.typeDepth > 0 || ctx.macroDepth > 0) return;
+    const source = this.currentSource(ctx);
+    if (!source) return;
+    const arityNode = this.getChildByType(node, "arity");
+    const arity = arityNode ? this.digitsOf(this.getChildByType(arityNode, "integer")?.text) : 0;
+    if (!external) {
+      const nameAtom = this.getChildByType(node, "atom");
+      if (!nameAtom?.text) return;
+      this.pushRel(
+        ctx,
+        source,
+        nameAtom.text,
+        ASTEngine.RelationshipType.References,
+        0.9,
+        { erlangSpecific: true, context: "fun value reference", callArity: arity },
+        nameAtom.startPosition.row + 1
+      );
+      return;
+    }
+    const fnAtom = this.getChildByType(node, "atom");
+    if (!fnAtom?.text) return;
+    const modNode = this.getChildByType(node, "module");
+    const modAtom = modNode ? this.getChildByType(modNode, "atom") : void 0;
+    const macroMod = this.remoteMacroModuleName(modNode);
+    if (modAtom?.text) {
+      this.pushRel(
+        ctx,
+        source,
+        `${modAtom.text}:${fnAtom.text}`,
+        ASTEngine.RelationshipType.References,
+        0.9,
+        { erlangSpecific: true, context: "fun value reference", callArity: arity },
+        fnAtom.startPosition.row + 1
+      );
+      return;
+    }
+    if (macroMod === "MODULE" && ctx.moduleName) {
+      this.pushRel(
+        ctx,
+        source,
+        `${ctx.moduleName}:${fnAtom.text}`,
+        ASTEngine.RelationshipType.References,
+        0.9,
+        { erlangSpecific: true, context: "fun value reference", callArity: arity, macroModule: true },
+        fnAtom.startPosition.row + 1
+      );
+    }
+  }
+  // ==========================================================================
+  // Operators
+  // ==========================================================================
+  processBinaryOp(node, ctx) {
+    const op = node.child(1)?.text;
+    if (op === "!") {
+      ctx.patterns["Message Passing"] = true;
+      ctx.patterns["Actor Model (OTP)"] = true;
+      return;
+    }
+    if ((op === "andalso" || op === "orelse") && ctx.macroDepth === 0) {
+      ctx.patterns["Pattern Matching"] = true;
+      this.countBranch(ctx);
+    }
+  }
+  countBranch(ctx) {
+    if (ctx.macroDepth > 0) return;
+    ctx.totalBranches++;
+    if (ctx.currentFun) ctx.currentFun.branches++;
+  }
+  // ==========================================================================
+  // Type references (the type graph)
+  // ==========================================================================
+  /**
+   * ER-D10 (user finding #6, ER-G5's type half): a declared type's BODY names
+   * other types, and that dependency graph is the whole value of reading a
+   * `-type`. Inside a type context every `atom` and every applied `call` head is
+   * a type name; `var` is a type parameter and `string` is a literal, so both are
+   * silent.
+   *
+   * The declared type's OWN `type_name` is skipped by SPAN CONTAINMENT
+   * (startIndex/endIndex), never by object identity: web-tree-sitter hands out a
+   * FRESH wrapper per access, so `child !== skip` never matches and the type
+   * would reference itself. That was a real defect the M14 hygiene gate caught
+   * (KAD2/TSD2 class); the mirrored copy in the oracle was invisible because
+   * both sides agreed.
+   *
+   * A self-reference that survives this filter is LEGAL Erlang (a recursive
+   * type, `-type t() :: {t, integer()}`) and is emitted — the span filter removes
+   * the declaration's name, not a genuine recursive dependency.
+   */
+  processTypeReferences(declNode, skipSpan, declName, ctx) {
+    const stack = [declNode];
+    while (stack.length > 0) {
+      const node = stack.pop();
+      if (node.isNamed && node.type === "record_name") continue;
+      if (node.isNamed && (node.type === "remote" || node.type === "remote_module")) continue;
+      if (node.isNamed && node.type === "call") {
+        let name;
+        let nameNode;
+        if (node.type === "call") {
+          const remote = this.getChildByType(node, "remote");
+          if (remote) {
+            const remoteModule = this.getChildByType(remote, "remote_module");
+            const modAtom = remoteModule ? this.getChildByType(remoteModule, "atom") : void 0;
+            const fnAtom = this.getChildByType(remote, "atom");
+            if (modAtom?.text && fnAtom?.text) {
+              name = `${modAtom.text}:${fnAtom.text}`;
+              nameNode = fnAtom;
+            }
+          } else {
+            nameNode = node.namedChild(0) ?? void 0;
+            name = nameNode?.text;
+          }
+        }
+        const inDeclarationName = skipSpan !== void 0 && nameNode !== void 0 && this.spanContains(skipSpan, nameNode);
+        if (name && !inDeclarationName) {
+          this.pushRel(
+            ctx,
+            declName,
+            name,
+            ASTEngine.RelationshipType.References,
+            0.9,
+            { erlangSpecific: true, context: "type reference" },
+            (nameNode ?? node).startPosition.row + 1
+          );
+        }
+      }
+      for (let i = node.childCount - 1; i >= 0; i--) {
+        const child = node.child(i);
+        if (child) stack.push(child);
+      }
+    }
+  }
+  // ==========================================================================
+  // Ownership
+  // ==========================================================================
+  /**
+   * `contains` for every owned symbol: module -> its functions, methods, types,
+   * records and macros; record -> its fields. The line is the member's own
+   * declaration line, which is where bb_graph's call hierarchy and the M59
+   * symbol-line contract read it from.
+   */
+  /**
+   * The owner of a module-scope declaration.
+   *
+   * Erlang has an honest gap here: a source file may declare NO `-module` at
+   * all. OTP's own `lib/syntax_tools/examples/merl/basic_test.erl` is one — its
+   * `-module` line is commented out because the file is textually included into
+   * another module. Nothing in the file names the module it will end up in, and
+   * the analyzer cannot know it. So the owner falls back to the FILE PATH: the
+   * outermost container that definitely holds the declaration, and the only
+   * identity the file has. (The alternative — inventing a module name from the
+   * filename — would fabricate a module that does not exist.)
+   *
+   * Every module-scope declaration must route through here. The 400-file corpus
+   * draw caught the one site that did not: macros took bare `ctx.moduleName`
+   * while functions, records, types and callbacks took the fallback, so a
+   * macro in a module-less file was emitted with NO owner while the function
+   * beside it had one. A fallback that is duplicated per declaration is a
+   * fallback that will drift.
+   */
+  ownerNameOf(ctx) {
+    return ctx.moduleName ?? ctx.filePath;
+  }
+  emitOwnership(ctx) {
+    for (const s of ctx.symbols) {
+      const owner = s.ownerName;
+      if (!owner) continue;
+      const nameLine = s.metadata?.line;
+      const line = typeof nameLine === "number" && nameLine > 0 ? nameLine : s.range.startLine;
+      this.pushRel(
+        ctx,
+        owner,
+        s.name,
+        ASTEngine.RelationshipType.Contains,
+        1,
+        { erlangSpecific: true, isModuleMember: s.ownerKind === ASTEngine.SymbolKind.Module },
+        line
+      );
+    }
+  }
+  // ==========================================================================
+  // Relationship emission
+  // ==========================================================================
+  /**
+   * One edge per (source, type, target, line, callArity).
+   *
+   * ER-D2: call-site arity is part of call identity — `pick(1)` and `pick(1,2)`
+   * are different callees and must not collapse into one row.
+   * M59 (#825): the line is part of identity for per-SITE edges — `run/0` calling
+   * `target/0` on four lines is four call sites, and the fixture pins all four.
+   * The line also makes the ancestor-wins rule deterministic: in
+   * `S#state{count = S#state.count + 1}` the update and the inner read share
+   * (source, target, line), and because the outer node is visited first its
+   * "record field update" edge is the one that survives.
+   *
+   * ER-D43 (measured 2026-10-03): the PUBLISHED IDENTITY is part of identity too. An
+   * `exports` edge publishes a module's interface, and the interface is keyed by
+   * `name/arity` (ER-D2), so `-export([start/0, start/1, complete/1, complete/0])` on
+   * ONE line is four publications. The key carried `callArity` — which an `exports` edge
+   * does not set — and `line`, which is the same line for all four, so the second
+   * publication of each name was dropped and the module's interface was published at half
+   * its real size with no error and no counter. 340 sites in a 204-file corpus draw;
+   * `otp/lib/asn1/examples/test_driver.erl:10` and
+   * `otp/lib/common_test/src/ct_doctest.erl:318` are two of them. `metadata.arity` is set
+   * on the `exports` edge and on nothing else, so reading it here widens the key for that
+   * one label and changes no other.
+   */
+  pushRel(ctx, source, target, type, confidence, metadata = {}, line) {
+    const publishedIdentity = metadata.callArity ?? metadata.arity ?? "";
+    const key = `${source}|${type}|${target}|${line ?? ""}|${publishedIdentity}`;
+    if (ctx.seenRels.has(key)) return;
+    ctx.seenRels.add(key);
+    ctx.relationships.push({
+      source,
+      target,
+      type,
+      confidence,
+      metadata,
+      ...typeof line === "number" && line > 0 ? { line_number: line } : {}
+    });
+  }
+  // ==========================================================================
+  // Context helpers
+  // ==========================================================================
+  /** The symbol every edge inside the current declaration belongs to. */
+  currentSource(ctx) {
+    const top = ctx.declStack[ctx.declStack.length - 1];
+    return top?.source ?? this.ownerNameOf(ctx);
+  }
+  /**
+   * Is this node in PATTERN position — a clause head, a `case`/`receive`/`try`
+   * arm pattern, the left side of a `=` / `?=` match, or a comprehension
+   * generator's left side?
+   *
+   * A pattern is a MATCH, not an evaluation: `S#state.count` in a head is
+   * destructuring, while `State#state{…}` in a body is a real update. The rule
+   * climbs to the nearest boundary. A CLAUSE HEAD makes everything below it a
+   * pattern (`case X of Y = #state{} -> …` binds, it does not construct). An
+   * EVALUATION context (clause body, guard) makes only the pattern side of a
+   * match or generator a pattern.
+   */
+  /**
+   * Is this node in PATTERN position?
+   *
+   * A pattern is a MATCH, not an evaluation. The rule is "the NEAREST enclosing
+   * boundary decides", which is the only formulation that survives Erlang's
+   * nesting — three corpus shapes decided it, and each one is a case a
+   * cumulative flag gets wrong:
+   *
+   *   `D#r.f == []` in a GUARD                -> evaluation (a guard computes).
+   *     Climbing to the clause head would call it a pattern; the boundary is the
+   *     guard, and a guard evaluates.
+   *   `[C || #cert{der = C} <- Certs]`        -> pattern. The generator's left
+   *     side binds, whatever expression holds the comprehension. The nearest
+   *     boundary is the generator and the node is on its `<-` side, so the
+   *     enclosing `= unzip4(…)` match is never consulted.
+   *   `Y = #r{} -> …` in a case arm           -> pattern. The node is on the
+   *     match's VALUE side, but the match itself sits in an arm head, so the
+   *     rule re-asks the boundary's own context.
+   *   `X = #r{}` in a clause body            -> evaluation.
+   */
+  isPatternPosition(node) {
+    let probe = node;
+    for (; ; ) {
+      const boundary = this.nearestPatternBoundary(probe.parent);
+      if (!boundary) return false;
+      if (boundary.kind === "head") return true;
+      if (boundary.kind === "body" || boundary.kind === "guard") return false;
+      if (this.isOnPatternSide(node, boundary.node)) return true;
+      probe = boundary.node;
+    }
+  }
+  nearestPatternBoundary(from) {
+    let cur = from;
+    while (cur) {
+      const t = cur.type;
+      if (t === "function_clause" || t === "fun_clause" || t === "cr_clause") return { node: cur, kind: "head" };
+      if (t === "clause_body") return { node: cur, kind: "body" };
+      if (t === "guard" || t === "guard_clause") return { node: cur, kind: "guard" };
+      if (t === "match_expr" || t === "cond_match_expr" || t === "lc_or_zc_expr") return { node: cur, kind: "match" };
+      cur = cur.parent;
+    }
+    return void 0;
+  }
+  /**
+   * Does `node` sit left of the boundary operator of `owner`?
+   *
+   * The `<-` of a comprehension generator is NOT a direct child of the
+   * `lc_or_zc_expr` — the grammar wraps it in a `generator` node (measured shape:
+   * `lc_or_zc_expr → generator → {LHS, <-, RHS}`). Both this analyzer AND the
+   * independent oracle first missed that and agreed with each other on the wrong
+   * answer, which is precisely the case a mirror cannot see: only the authored
+   * fixture `erlang/patterns-er3` catches it. The `generator` / `map_generator` /
+   * `b_generator` wrapper is resolved here.
+   *
+   * A `lc_or_zc_expr` with NO generator is a comprehension FILTER, which
+   * computes — no operator, so the answer is false.
+   */
+  isOnPatternSide(node, owner) {
+    let target = owner;
+    if (owner.type === "lc_or_zc_expr") {
+      const gen = this.getChildByType(owner, "generator") ?? this.getChildByType(owner, "map_generator") ?? this.getChildByType(owner, "b_generator");
+      if (gen) target = gen;
+    }
+    for (let i = 0; i < target.childCount; i++) {
+      const c = target.child(i);
+      if (c && MATCH_OPERATORS.has(c.type)) return node.startIndex < c.startIndex;
+    }
+    return false;
+  }
+  /** Span containment — the only correct way to compare two tree-sitter nodes. */
+  spanContains(outer, inner) {
+    return outer.startIndex <= inner.startIndex && inner.endIndex <= outer.endIndex;
+  }
+  // ==========================================================================
+  // Node readers
+  // ==========================================================================
+  /**
+   * `name/arity` from an `fa`, with the NAME's line (M59).
+   *
+   * An `fa`'s name has THREE spellings in this grammar and a reader that takes only the
+   * first loses rows SILENTLY — no error, no counter, and the label simply has fewer
+   * members than the file publishes:
+   *
+   *   atom               `-export([run/0])`
+   *   macro_call_expr    `-export([?MODULE/0])` — ER-D28: how OTP test suites export the
+   *                      function their `?MODULE() -> …` clause declares. `?MODULE`
+   *                      expands to the module atom, so the entry resolves exactly like
+   *                      the clause head does. Any other macro in an `fa` needs expansion
+   *                      and is refused.
+   *   var                `-export([HEAD/1])` — ER-D42, measured 2026-10-03. An
+   *                      identifier beginning with an UPPERCASE letter is a VARIABLE in
+   *                      Erlang, so the grammar types it `var`, not `atom`, and this
+   *                      reader required `atom`. Every all-caps export name was therefore
+   *                      dropped: `-export([HEAD/1])` in the lane's own
+   *                      `macros-er3.erl` fixture produced no `exports` row at all, and the
+   *                      fixture did not catch it because nothing pinned the row. A macro
+   *                      is a real Erlang function name here — `-define(HEAD(X), X).` plus
+   *                      `-export([HEAD/1])` is ordinary code — so the name is read and the
+   *                      arity with it.
+   */
+  readFa(fa, moduleName) {
+    const nameNode = this.getChildByType(fa, "atom");
+    const arityNode = this.getChildByType(fa, "arity");
+    const arity = arityNode ? this.digitsOf(this.getChildByType(arityNode, "integer")?.text) : 0;
+    if (nameNode?.text) return { name: nameNode.text, arity, line: nameNode.startPosition.row + 1 };
+    const macro = this.getChildByType(fa, "macro_call_expr");
+    const macroName = macro ? (this.getChildByType(macro, "var") ?? this.getChildByType(macro, "atom"))?.text : void 0;
+    if (macroName === "MODULE" && moduleName) {
+      const at = this.getChildByType(macro, "var") ?? this.getChildByType(macro, "atom");
+      return { name: moduleName, arity, line: (at ?? macro).startPosition.row + 1 };
+    }
+    const varNode = this.getChildByType(fa, "var");
+    if (varNode?.text) return { name: varNode.text, arity, line: varNode.startPosition.row + 1 };
+    return void 0;
+  }
+  /**
+   * `-nifs([f/1])` / `-on_load([g/0])` entries. The list holds
+   * `binary_op_expr` (`f` `/` `1`), NOT an `fa` — the second half of the
+   * dead-branch defect ER-D22 records. Both spellings are read, because the
+   * grammar's own `-record`-in-`wild_attribute` error path produces `fa` nodes
+   * for some vendor attributes.
+   */
+  collectAttributeFaEntries(node, out, ctx) {
+    const line = node.startPosition.row + 1;
+    const stack = [node];
+    while (stack.length > 0) {
+      const n = stack.pop();
+      if (n.isNamed && n.type === "binary_op_expr" && n.child(1)?.type === "/") {
+        const nameNode = this.getChildByType(n, "atom");
+        if (nameNode?.text) {
+          out.set(this.fnKey(nameNode.text, this.digitsOf(this.getChildByType(n, "integer")?.text)), line);
+        }
+        continue;
+      }
+      if (n.isNamed && n.type === "fa") {
+        const fa = this.readFa(n, ctx.moduleName);
+        if (fa) out.set(this.fnKey(fa.name, fa.arity), line);
+        continue;
+      }
+      for (let i = n.childCount - 1; i >= 0; i--) {
+        const c = n.child(i);
+        if (c) stack.push(c);
+      }
+    }
+  }
+  /** `-nifs`, not `nifs`: the dash is INSIDE the `attr_name` node. */
+  attrNameText(node) {
+    const attrName = this.getChildByType(node, "attr_name");
+    if (!attrName) return void 0;
+    return this.getChildByType(attrName, "atom")?.text ?? attrName.text;
+  }
+  atomIn(node) {
+    return node ? this.getChildByType(node, "atom") : void 0;
+  }
+  namedChildrenOf(args) {
+    if (!args) return [];
+    const out = [];
+    for (let i = 0; i < args.namedChildCount; i++) {
+      const c = args.namedChild(i);
+      if (c && c.type !== "comment") out.push(c);
+    }
+    return out;
+  }
+  getChildByType(node, targetType) {
+    if (!node) return void 0;
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (child?.type === targetType) return child;
+    }
+    return void 0;
+  }
+  collectChildrenByType(node, targetType) {
+    const results = [];
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child && child.type === targetType) results.push(child);
+    }
+    return results;
+  }
+  digitsOf(text) {
+    if (!text) return 0;
+    const digits = this.keepDigits(text);
+    return digits.length > 0 ? parseInt(digits, 10) || 0 : 0;
+  }
+  // ==========================================================================
+  // Pure-string helpers (no regex — M12 census, M49 #849)
+  // ==========================================================================
+  stripQuotes(text) {
+    let out = "";
+    for (let i = 0; i < text.length; i++) {
+      const ch = text[i];
+      if (ch === '"' || ch === "'") continue;
+      out += ch;
+    }
+    return out;
+  }
+  keepDigits(text) {
+    let out = "";
+    for (let i = 0; i < text.length; i++) {
+      const ch = text[i];
+      if (ch >= "0" && ch <= "9") out += ch;
+    }
+    return out;
+  }
+  /** `name()` -> `name`; `maybe(T)` -> `maybe`. */
+  stripFirstParen(text) {
+    const paren = text.indexOf("(");
+    return (paren >= 0 ? text.slice(0, paren) : text).trim();
+  }
+  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
+    };
+  }
+};
+export {
+  RealErlangAnalyzer
+};