@backbencher/brain 0.0.0-stage → 0.1.1

package/dist/real-perl-analyzer-WWTRHYDT.js

@@ -0,0 +1,1865 @@
+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-perl-analyzer.ts
+var PERL_MAGIC_TOKENS = /* @__PURE__ */ new Set(["__PACKAGE__", "__FILE__", "__LINE__", "__SUB__", "__DATA__", "__END__"]);
+var isPerlIdentStart = (c) => c >= "a" && c <= "z" || c >= "A" && c <= "Z" || c === "_";
+var isPerlIdentChar = (c) => isPerlIdentStart(c) || c >= "0" && c <= "9";
+var PERL_BUILTINS = /* @__PURE__ */ new Set([
+  "abs",
+  "accept",
+  "alarm",
+  "atan2",
+  "bind",
+  "binmode",
+  "bless",
+  "break",
+  "caller",
+  "catch",
+  "chdir",
+  "chmod",
+  "chomp",
+  "chop",
+  "chown",
+  "chr",
+  "chroot",
+  "close",
+  "closedir",
+  "cmp",
+  "connect",
+  "continue",
+  "cos",
+  "crypt",
+  "dbmclose",
+  "dbmopen",
+  "defined",
+  "delete",
+  "die",
+  "do",
+  "dump",
+  "each",
+  "eof",
+  "eval",
+  "exec",
+  "exists",
+  "exit",
+  "exp",
+  "fc",
+  "fcntl",
+  "fileno",
+  "flock",
+  "fork",
+  "format",
+  "formline",
+  "getc",
+  "getgrent",
+  "getgrgid",
+  "getgrnam",
+  "gethostbyaddr",
+  "gethostbyname",
+  "getlogin",
+  "getnetbyaddr",
+  "getnetbyname",
+  "getpeername",
+  "getpgrp",
+  "getppid",
+  "getpriority",
+  "getprotobyname",
+  "getprotobynumber",
+  "getpwnam",
+  "getpwuid",
+  "getservbyname",
+  "getservbyport",
+  "getsockname",
+  "getsockopt",
+  "glob",
+  "gmtime",
+  "goto",
+  "grep",
+  "hex",
+  "if",
+  "index",
+  "int",
+  "ioctl",
+  "join",
+  "keys",
+  "kill",
+  "last",
+  "lc",
+  "lcfirst",
+  "length",
+  "link",
+  "listen",
+  "local",
+  "localtime",
+  "lock",
+  "log",
+  "lstat",
+  "map",
+  "mkdir",
+  "msgctl",
+  "msgget",
+  "msgrcv",
+  "msgsnd",
+  "my",
+  "next",
+  "oct",
+  "open",
+  "opendir",
+  "ord",
+  "pack",
+  "pipe",
+  "pop",
+  "pos",
+  "print",
+  "printf",
+  "prototype",
+  "push",
+  "quotemeta",
+  "rand",
+  "read",
+  "readdir",
+  "readline",
+  "readlink",
+  "readpipe",
+  "recv",
+  "redo",
+  "ref",
+  "rename",
+  "require",
+  "reset",
+  "return",
+  "reverse",
+  "rewinddir",
+  "rindex",
+  "rmdir",
+  "say",
+  "scalar",
+  "seek",
+  "seekdir",
+  "select",
+  "semctl",
+  "semget",
+  "semop",
+  "send",
+  "setpgrp",
+  "setpriority",
+  "setsockopt",
+  "shift",
+  "shmctl",
+  "shmget",
+  "shmread",
+  "shmwrite",
+  "shutdown",
+  "sin",
+  "sleep",
+  "socket",
+  "socketpair",
+  "sort",
+  "splice",
+  "split",
+  "sprintf",
+  "sqrt",
+  "srand",
+  "stat",
+  "state",
+  "study",
+  "substr",
+  "symlink",
+  "syscall",
+  "sysopen",
+  "sysread",
+  "sysseek",
+  "system",
+  "syswrite",
+  "tell",
+  "telldir",
+  "tie",
+  "tied",
+  "time",
+  "times",
+  "truncate",
+  "uc",
+  "ucfirst",
+  "umask",
+  "undef",
+  "unlink",
+  "unpack",
+  "unshift",
+  "untie",
+  "until",
+  "use",
+  "utime",
+  "values",
+  "vec",
+  "wait",
+  "waitpid",
+  "wantarray",
+  "warn",
+  "while",
+  "write",
+  "xor",
+  "our"
+]);
+var PERL_REASON_CODES = {
+  nameOnlyCallee: "name-only-callee",
+  dynamicReceiver: "dynamic-receiver",
+  concreteInvocant: "concrete-invocant",
+  useParentDeclaration: "use-parent-declaration",
+  isaArray: "isa-array",
+  mojoBaseDeclaration: "mojo-base-declaration",
+  mooRoleComposition: "moo-role-composition",
+  mooExtendsKeyword: "moo-extends-keyword",
+  indirectObjectInvocation: "indirect-object-invocation",
+  useRoleComposition: "use-role-composition",
+  // THE IMPORT AND EXPORT EDGES ✓✓ — 2026-10-21 ✓✓.
+  //
+  // The corpus EXPRESSES both ✓✓ (3,539 use/require sites ✓✓, 33 @EXPORT
+  // conventions in 11 files ✓✓) and the ARM's TABLE 1 carried `imports 0` and
+  // `exports 0` ✓✓, because the facts went into the analyzer's OUTPUT SHAPE ✓✓
+  // and never became RELATIONSHIPS ✓✓. These two codes are the receipt ✓✓.
+  moduleImport: "module-import",
+  exportedSymbol: "exported-symbol",
+  exportedArrayPush: "exporter-array-push",
+  exportedArrayDeclaration: "exporter-array-declaration",
+  exporterSurface: "exporter-surface",
+  useModuleLoad: "use-module-load",
+  runtimeRequire: "runtime-require",
+  isaArrayPush: "isa-array-push",
+  baseDeclaresMethod: "base-declares-method",
+  firstParentGuess: "first-parent-guess",
+  magicTokenInvocant: "magic-token-invocant",
+  codeReference: "code-reference",
+  qualifiedVariableRead: "qualified-variable-read",
+  qualifiedNameAccess: "qualified-name-access",
+  blessClassLiteral: "bless-class-literal",
+  refClassComparison: "ref-class-comparison",
+  universalIsaLiteral: "universal-isa-literal",
+  isaClassLiteral: "isa-class-literal",
+  doesRoleLiteral: "does-role-literal",
+  typeQueryLiteral: "type-query-literal"
+};
+var REASON = PERL_REASON_CODES;
+function perlFindChildByType(node, type) {
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (child?.type === type) return child;
+  }
+  return void 0;
+}
+function perlWordValues(node) {
+  if (node.type === "string_content" || node.type === "autoquoted_bareword" || node.type === "bareword" || node.type === "package") return node.text ? splitWords(node.text) : [];
+  if (node.type === "quoted_word_list") {
+    const content = node.childForFieldName("content") || perlFindChildByType(node, "string_content");
+    return content ? splitWords(content.text) : [];
+  }
+  if (node.type === "string_literal") {
+    const content = node.childForFieldName("content") || perlFindChildByType(node, "string_content");
+    return [content ? content.text : unquote(node.text)];
+  }
+  if (node.type === "interpolated_string_literal") {
+    const values2 = [];
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (!child) continue;
+      if (child.type === "string_content") {
+        for (const w of splitWords(child.text)) values2.push(w);
+      }
+    }
+    return values2;
+  }
+  if (node.type === "subroutine_declaration_statement" || node.type === "anonymous_subroutine_expression" || node.type === "block" || node.type === "block_statement") return [];
+  if (node.type === "conditional_expression") return [];
+  if (node.type === "function_call_expression" || node.type === "method_call_expression" || node.type === "func0op_call_expression" || node.type === "func1op_call_expression" || node.type === "coderef_call_expression" || node.type === "ambiguous_function_call_expression") return [];
+  if (node.type === "binary_expression" || node.type === "lowprec_logical_expression" || node.type === "logical_not_expression") {
+    const op = node.childForFieldName("operator") ?? node.children.find((c) => !c.isNamed);
+    const t = op ? op.type : "";
+    if (t === "and" || t === "or" || t === "||" || t === "&&" || t === "//") return [];
+  }
+  const values = [];
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (child) values.push(...perlWordValues(child));
+  }
+  return values;
+}
+function unquote(text) {
+  if (text.length >= 2) {
+    const first = text[0];
+    const last = text[text.length - 1];
+    if (first === "'" && last === "'" || first === '"' && last === '"') return text.slice(1, -1);
+  }
+  return text;
+}
+function isPerlPragma(module) {
+  return PERL_PRAGMAS.has(module);
+}
+var PERL_PRAGMAS = /* @__PURE__ */ new Set([
+  "strict",
+  "warnings",
+  "integer",
+  "feature",
+  "lib",
+  "utf8",
+  "bytes",
+  "constant",
+  "vars",
+  "parent",
+  "base",
+  "overload",
+  "bigint",
+  "bignum",
+  "bigrat",
+  "open",
+  "charnames",
+  "autodie",
+  "re",
+  "attributes",
+  "sigtrap",
+  "sort",
+  "subs",
+  "threads",
+  "fields",
+  "if",
+  "less",
+  "locale",
+  "mro",
+  "ops",
+  "version",
+  "vmsish",
+  "arybase",
+  "deprecated",
+  "experimental",
+  "diagnostics",
+  "sigtrap",
+  "class",
+  "builtin"
+]);
+var PERL_BUILTIN_REF_TYPES = /* @__PURE__ */ new Set(["ARRAY", "HASH", "SCALAR", "CODE", "REF", "GLOB", "LVALUE", "REGEXP", "IO", "VSTRING", "UNKNOWN"]);
+function splitWords(text) {
+  const result = [];
+  let current = "";
+  for (const char of text) {
+    if (char === " " || char === "	" || char === "\n" || char === ",") {
+      if (current) result.push(current);
+      current = "";
+    } else current += char;
+  }
+  if (current) result.push(current);
+  return result;
+}
+function isArgumentSpecification(statement) {
+  const WRAPPERS = /* @__PURE__ */ new Set(["list_expression", "array_expression", "hash_expression", "anonymous_array_expression", "anonymous_hash_expression"]);
+  const hasFatArrow = (n) => {
+    for (let i = 0; i < n.childCount; i++) {
+      const child = n.child(i);
+      if (!child) continue;
+      if (!child.isNamed && child.type === "=>") return true;
+    }
+    return false;
+  };
+  const nodes = [statement, ...Array.from({ length: statement.childCount }, (_, i) => statement.child(i)).filter(Boolean)];
+  for (const n of nodes) {
+    if (!n) continue;
+    if (hasFatArrow(n)) return true;
+    for (let i = 0; i < n.childCount; i++) {
+      const child = n.child(i);
+      if (child && WRAPPERS.has(child.type) && hasFatArrow(child)) return true;
+    }
+  }
+  return false;
+}
+function perlArgumentNodes(node) {
+  const module = node.childForFieldName("module");
+  const fromField = [];
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child && node.fieldNameForChild(i) === "arguments" && perlWordValues(child).length > 0) fromField.push(child);
+  }
+  if (fromField.length) return fromField;
+  const list = perlFindChildByType(node, "list_expression");
+  if (list) return list.namedChildren.filter((c) => !!c && perlWordValues(c).length > 0);
+  const result = [];
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (!child || child === module) continue;
+    if (child.type === "string_literal" || child.type === "interpolated_string_literal" || child.type === "quoted_word_list" || child.type === "autoquoted_bareword") {
+      if (perlWordValues(child).length > 0) result.push(child);
+    }
+  }
+  return result;
+}
+function hasArgumentSyntax(node) {
+  if (node.childrenForFieldName("arguments").length > 0) return true;
+  for (let i = 0; i < node.childCount; i++) {
+    const t = node.child(i)?.type;
+    if (t === "(" || t === ")") return true;
+  }
+  return false;
+}
+var RealPerlAnalyzer = class {
+  analyze(rootNode, content, _filePath, context) {
+    const symbols = [];
+    const relationships = [];
+    const imports = [];
+    const exports = [];
+    const errors = [];
+    const frameworks = /* @__PURE__ */ new Set(["Perl"]);
+    const patterns = /* @__PURE__ */ new Set();
+    const symbolKeys = /* @__PURE__ */ new Set();
+    const symbolsByKey = /* @__PURE__ */ new Map();
+    const relationshipKeys = /* @__PURE__ */ new Set();
+    const packageBases = /* @__PURE__ */ new Map();
+    const packageBaseOrigin = /* @__PURE__ */ new Map();
+    const packageBaseLine = /* @__PURE__ */ new Map();
+    const packageMethods = /* @__PURE__ */ new Map();
+    const deferredIsa = [];
+    const indirectObjectClassNodes = /* @__PURE__ */ new Set();
+    const nodeKey = (n) => `${n.startIndex}:${n.endIndex}:${n.type}`;
+    const versionRequirements = [];
+    if (!rootNode) return this.result(symbols, relationships, imports, exports, errors, content, frameworks, patterns);
+    this.collectErrors(rootNode, errors);
+    const addSymbol = (name, kind, node, state, extra = {}, ownerOverride, nameNode) => {
+      if (!name) return void 0;
+      const owner = ownerOverride ?? state.ownerName;
+      const key = `${kind}${owner || ""}${name}`;
+      if (symbolKeys.has(key)) return symbolsByKey.get(key);
+      const nameLineSource = nameNode ?? node.childForFieldName("name") ?? this.findChildByType(node, "bareword");
+      const nameLine = name === node.text?.trim() ? node.startPosition.row + 1 : nameLineSource ? nameLineSource.startPosition.row + 1 : node.startPosition.row + 1;
+      const symbol = {
+        name,
+        kind,
+        range: this.nodeToRange(node),
+        scope: owner || state.packageName || void 0,
+        ownerName: owner,
+        ownerKind: owner ? state.ownerKind : void 0,
+        visibility: state.visibility,
+        metadata: { perlSpecific: true, nameLine, ...extra }
+      };
+      symbolKeys.add(key);
+      symbolsByKey.set(key, symbol);
+      symbols.push(symbol);
+      return symbol;
+    };
+    const nameLineOf = (symbol) => {
+      const recorded = symbol.metadata?.nameLine;
+      if (typeof recorded === "number" && recorded > 0) return recorded;
+      const start = symbol.range?.startLine;
+      return typeof start === "number" && start > 0 ? start : void 0;
+    };
+    const addRelationship = (source, target, type, metadata2 = {}, confidence = 0.9, lineNode, explicitLine) => {
+      if (!source || !target) return;
+      const key = `${type}${source}${target}`;
+      if (relationshipKeys.has(key)) return;
+      relationshipKeys.add(key);
+      const line = explicitLine ?? (lineNode ? lineNode.startPosition.row + 1 : void 0);
+      relationships.push({
+        source,
+        target,
+        type,
+        confidence,
+        ...typeof line === "number" && line > 0 ? { line_number: line } : {},
+        metadata: { perlSpecific: true, ...metadata2 }
+      });
+    };
+    const addReferenceName = (rawName, nameNode, state, reasonCode) => {
+      const leaf = this.leafName(rawName);
+      const source = state.functionName || state.ownerName || state.packageName || "global";
+      if (!leaf || leaf === source) return;
+      const qualifier = rawName.includes("::") ? rawName.slice(0, rawName.lastIndexOf("::")) : void 0;
+      addRelationship(source, leaf, ASTEngine.RelationshipType.References, { reasonCode, ...qualifier ? { qualifiedAs: rawName, qualifier } : {} }, 0.9, nameNode);
+    };
+    const addBase = (owner, parents, reasonCode, nameNode, parentLines) => {
+      const existing = packageBases.get(owner) || [];
+      for (const parent of parents) {
+        if (!parent) continue;
+        if (!existing.includes(parent)) {
+          existing.push(parent);
+          if (!packageBaseOrigin.has(owner)) packageBaseOrigin.set(owner, reasonCode);
+        }
+        const key = `${owner}${parent}`;
+        if (packageBaseLine.has(key)) continue;
+        const perParent = parentLines?.get(parent);
+        if (typeof perParent === "number") packageBaseLine.set(key, perParent);
+        else if (nameNode) packageBaseLine.set(key, nameNode.startPosition.row + 1);
+      }
+      packageBases.set(owner, existing);
+    };
+    const qualifiedClassNames = /* @__PURE__ */ new Set();
+    const addCall = (target, state, calleeNode, dynamicReceiver, callNode, builtinProbe) => {
+      const named = target.startsWith("&") ? target.slice(1) : target;
+      const probe = builtinProbe ?? named;
+      if (!target || PERL_BUILTINS.has(probe) || probe === "use" || probe === "no") return;
+      if (target.startsWith("&") && !hasArgumentSyntax(callNode ?? calleeNode)) {
+        const source = state.functionName || state.ownerName || state.packageName || "global";
+        const leaf = this.leafName(named);
+        if (leaf && leaf !== source) {
+          const qualifier = named.includes("::") ? named.slice(0, named.lastIndexOf("::")) : void 0;
+          addRelationship(source, leaf, ASTEngine.RelationshipType.Uses, { reasonCode: REASON.codeReference, ...qualifier ? { qualifiedAs: named, qualifier } : {} }, 0.9, calleeNode);
+        }
+        return;
+      }
+      addRelationship(
+        state.functionName || state.ownerName || state.packageName || "global",
+        this.leafName(named),
+        ASTEngine.RelationshipType.Calls,
+        { reasonCode: dynamicReceiver ? REASON.dynamicReceiver : REASON.nameOnlyCallee },
+        0.9,
+        calleeNode
+      );
+    };
+    const walk = (node, state) => {
+      switch (node.type) {
+        case "package_statement": {
+          const nameNode = node.childForFieldName("name") ?? void 0;
+          const name = nameNode?.text || "";
+          if (!name) break;
+          const kind = ASTEngine.SymbolKind.Class;
+          addSymbol(name, kind, nameNode ?? node, { ...state, packageName: name }, { isPackage: true });
+          patterns.add("Packages");
+          const block = node.childForFieldName("body") || this.findChildByType(node, "block");
+          if (block) {
+            walkChildren(block, {
+              ...state,
+              packageName: name,
+              ownerName: name,
+              ownerKind: kind,
+              insideFunction: false,
+              bodyKind: "package"
+            });
+          } else {
+            state.packageName = name;
+          }
+          return;
+        }
+        case "class_statement":
+        case "role_statement": {
+          const nameNode = node.childForFieldName("name") ?? void 0;
+          const name = nameNode?.text || "";
+          if (!name) break;
+          const isRole = node.type === "role_statement";
+          const kind = isRole ? ASTEngine.SymbolKind.Trait : ASTEngine.SymbolKind.Class;
+          addSymbol(name, kind, nameNode ?? node, { ...state, packageName: name }, isRole ? { isPerlRole: true } : { isPerlClass: true });
+          patterns.add(isRole ? "Roles" : "Classes");
+          frameworks.add("Perl 5.38 core OO");
+          const block = node.childForFieldName("body") || this.findChildByType(node, "block");
+          if (block) {
+            walkChildren(block, {
+              ...state,
+              packageName: name,
+              ownerName: name,
+              ownerKind: kind,
+              insideFunction: false,
+              bodyKind: isRole ? "role" : "class"
+            });
+          }
+          return;
+        }
+        case "subroutine_declaration_statement":
+        case "method_declaration_statement": {
+          if (state.insideFunction) {
+            const nestedBody = node.childForFieldName("body") || this.findChildByType(node, "block");
+            if (nestedBody) walkChildren(nestedBody, { ...state, insideFunction: true });
+            return;
+          }
+          const nameNode = node.childForFieldName("name") || this.findChildByType(node, "bareword");
+          const rawName = nameNode?.text || "";
+          if (!rawName) break;
+          const isConstructor = rawName === "new";
+          const name = isConstructor ? "constructor" : rawName;
+          const owner = state.packageName || state.ownerName;
+          const kind = isConstructor ? ASTEngine.SymbolKind.Constructor : owner ? ASTEngine.SymbolKind.Method : ASTEngine.SymbolKind.Function;
+          const symbol = addSymbol(name, kind, node, {
+            ...state,
+            ownerName: owner,
+            ownerKind: owner ? ASTEngine.SymbolKind.Class : void 0
+          }, {
+            originalName: rawName,
+            isMethod: !!owner,
+            isConstructor
+          }, owner);
+          if (symbol) {
+            symbol.parameters = this.extractParameters(node);
+            symbol.ownerKind = owner ? ASTEngine.SymbolKind.Class : void 0;
+            const decorators = this.extractAttributes(node);
+            if (decorators.length) symbol.decorators = decorators;
+          }
+          if (owner && symbol) {
+            let methodSet = packageMethods.get(owner);
+            if (!methodSet) {
+              methodSet = /* @__PURE__ */ new Set();
+              packageMethods.set(owner, methodSet);
+            }
+            methodSet.add(rawName);
+          }
+          const body = node.childForFieldName("body") || this.findChildByType(node, "block");
+          if (body) walkChildren(body, { ...state, ownerName: owner, ownerKind: owner ? ASTEngine.SymbolKind.Class : void 0, functionName: name, insideFunction: true });
+          return;
+        }
+        case "variable_declaration": {
+          const declaration = this.declarationKind(node);
+          patterns.add("Variable Declarations");
+          const inClassBody = state.bodyKind === "class" || state.bodyKind === "role";
+          const isPackageGlobal = declaration === "our" && !state.insideFunction;
+          const isClassField = declaration === "field" && inClassBody && !state.insideFunction;
+          if (!isPackageGlobal && !isClassField) break;
+          for (const variable of this.variableChildren(node)) {
+            const varNameNode = this.findChildByType(variable, "varname");
+            const rawName = varNameNode?.text || "";
+            const name = this.stripSigil(rawName);
+            if (!name || name === "_") continue;
+            if (isClassField) {
+              addSymbol(name, ASTEngine.SymbolKind.Property, variable, state, { isPerlField: true, perlDeclType: declaration, sigil: variable.type }, state.packageName || state.ownerName);
+              continue;
+            }
+            const kind = name === "ISA" ? ASTEngine.SymbolKind.Variable : this.isAllCapsName(name) ? ASTEngine.SymbolKind.Constant : ASTEngine.SymbolKind.Variable;
+            addSymbol(name, kind, variable, state, { perlDeclType: declaration, sigil: variable.type, ...name === "ISA" ? { isInheritanceVariable: true } : {} }, state.packageName || void 0);
+          }
+          break;
+        }
+        case "refgen_expression": {
+          const fnNode = this.findChildByType(node, "function");
+          if (!fnNode) break;
+          const varname = this.findChildByType(fnNode, "varname");
+          if (!varname) break;
+          if (fnNode.namedChildCount !== 1) break;
+          const name = varname.text;
+          if (!name || !this.isWrittenCalleeName(name)) break;
+          const leaf = this.leafName(name);
+          const source = state.functionName || state.ownerName || state.packageName || "global";
+          if (leaf === source) break;
+          const qualifier = name.includes("::") ? name.slice(0, name.lastIndexOf("::")) : void 0;
+          addRelationship(source, leaf, ASTEngine.RelationshipType.Uses, { reasonCode: REASON.codeReference, ...qualifier ? { qualifiedAs: name, qualifier } : {} }, 0.9, varname);
+          break;
+        }
+        case "scalar":
+        case "array":
+        case "hash": {
+          const varname = this.findChildByType(node, "varname");
+          const qualified = varname?.text || "";
+          if (!qualified || !qualified.includes("::")) break;
+          if (!this.isWrittenCalleeName(qualified)) break;
+          const readSource = state.functionName || state.ownerName || state.packageName || "global";
+          addRelationship(readSource, qualified, ASTEngine.RelationshipType.Uses, { reasonCode: REASON.qualifiedVariableRead }, 0.9, varname);
+          break;
+        }
+        case "equality_expression": {
+          const kids = [];
+          for (let i = 0; i < node.namedChildCount; i++) {
+            const c = node.namedChild(i);
+            if (c) kids.push(c);
+          }
+          const isRefCall = (n) => n.type === "func1op_call_expression" && String(n.child(0)?.text ?? "") === "ref";
+          const refKid = kids.find(isRefCall);
+          const litKid = kids.find((k) => k.type === "string_literal" || k.type === "interpolated_string_literal");
+          if (refKid && litKid) {
+            const word = this.wordValues(litKid)[0];
+            if (word && this.isWrittenCalleeName(word) && !PERL_BUILTIN_REF_TYPES.has(word)) addReferenceName(word, litKid, state, REASON.refClassComparison);
+          }
+          break;
+        }
+        case "bareword": {
+          const text = String(node.text ?? "");
+          if (!text.includes("::") || text.endsWith("::")) break;
+          const parent = node.parent;
+          const parentType = parent ? String(parent.type) : "";
+          if (parentType === "hash_element_expression" || parentType === "slice_container_variable") break;
+          if (parent) {
+            let nextIsFatComma = false;
+            for (let i = 0; i < parent.childCount; i++) {
+              const child = parent.child(i);
+              if (!child || child.id !== node.id) continue;
+              const next = parent.child(i + 1);
+              if (next && !next.isNamed && next.type === "=>") nextIsFatComma = true;
+              break;
+            }
+            if (nextIsFatComma) break;
+          }
+          const VALUE_PARENT = /* @__PURE__ */ new Set(["assignment_expression", "return_expression", "list_expression", "expression_statement", "keyval_expression"]);
+          if (!VALUE_PARENT.has(parentType)) break;
+          let ancestor = parent;
+          let insideDirective = false;
+          for (let depth = 0; ancestor && depth < 4; depth++) {
+            if (ancestor.type === "use_statement" || ancestor.type === "require_expression" || ancestor.type === "require_version_expression") {
+              insideDirective = true;
+              break;
+            }
+            ancestor = ancestor.parent;
+          }
+          if (insideDirective) break;
+          const source = state.functionName || state.ownerName || state.packageName || "global";
+          addRelationship(source, text, ASTEngine.RelationshipType.Uses, { reasonCode: REASON.qualifiedNameAccess }, 0.9, node);
+          break;
+        }
+        case "use_statement": {
+          if (node.child(0)?.type === "no") break;
+          const moduleNode = node.childForFieldName("module") ?? void 0;
+          const module = moduleNode?.text || "";
+          if (!module) break;
+          if (module === "constant") {
+            for (const constant of this.constantDeclarationNames(node)) {
+              addSymbol(constant.name, ASTEngine.SymbolKind.Constant, constant.node, state, { isPerlConstant: true }, state.packageName || void 0);
+            }
+            patterns.add("Constants");
+            frameworks.add("Compile-time Constants");
+            break;
+          }
+          const args = this.argumentValues(node);
+          imports.push({
+            module,
+            items: args.length > 0 && !isArgumentSpecification(node) ? args : ["*"],
+            isDefault: true,
+            range: this.nodeToRange(node),
+            metadata: { perlSpecific: true, type: "use" }
+          });
+          patterns.add("Module Includes");
+          addRelationship(state.packageName || "global", module, ASTEngine.RelationshipType.Imports, {
+            reasonCode: REASON.useModuleLoad,
+            perlSpecific: true,
+            relationshipType: "use_module",
+            isImport: true,
+            fileLevel: true,
+            isPragma: isPerlPragma(module),
+            items: imports[imports.length - 1]?.items ?? []
+          }, 1, node);
+          if (module === "Moose" || module === "Moo" || module === "Mojo::Base") frameworks.add(module === "Mojo::Base" ? "Mojolicious" : "Moose/Moo OOP");
+          if (module === "parent" || module === "base") {
+            const parents = args.filter((arg) => !this.isOption(arg));
+            const parentLines = /* @__PURE__ */ new Map();
+            for (const argNode of this.argumentNodes(node)) {
+              for (const value of this.wordValues(argNode)) {
+                if (this.isOption(value)) continue;
+                const line = this.lineOfNameWithin(argNode, value);
+                if (line !== void 0) parentLines.set(value, line);
+              }
+            }
+            if (state.packageName) addBase(state.packageName, parents, REASON.useParentDeclaration, moduleNode, parentLines);
+          } else if (module === "role") {
+            for (const argNode of this.argumentNodes(node)) {
+              for (const value of this.wordValues(argNode)) {
+                if (this.isOption(value)) continue;
+                const roleName = this.leafName(value);
+                const roleLine = this.lineOfNameWithin(argNode, value);
+                addRelationship(
+                  state.packageName || "global",
+                  roleName,
+                  ASTEngine.RelationshipType.Implements,
+                  { reasonCode: REASON.useRoleComposition },
+                  0.9,
+                  void 0,
+                  roleLine
+                );
+                addRelationship(
+                  state.packageName || "global",
+                  roleName,
+                  ASTEngine.RelationshipType.MixesIn,
+                  { reasonCode: REASON.useRoleComposition, compositionSite: "role-composition" },
+                  0.9,
+                  void 0,
+                  roleLine
+                );
+              }
+            }
+            if (state.packageName) frameworks.add("Moose/Moo OOP");
+          }
+          if (module === "Mojo::Base" && state.packageName) {
+            const named = args.find((arg) => arg && !this.isOption(arg));
+            addBase(state.packageName, [named ?? module], REASON.mojoBaseDeclaration, moduleNode);
+          }
+          const useArgList = this.findChildByType(node, "list_expression");
+          if (useArgList) walk(useArgList, state);
+          return;
+        }
+        case "use_version_statement": {
+          const versionNode = node.childForFieldName("version");
+          const version = versionNode?.text || "";
+          if (version) {
+            versionRequirements.push(version);
+            patterns.add("Version Requirements");
+          }
+          return;
+        }
+        case "require_expression": {
+          const moduleNode = this.findChildByType(node, "bareword") || this.findChildByType(node, "package");
+          const pathNode = this.findChildByType(node, "string_literal");
+          const module = pathNode ? this.wordValues(pathNode)[0] ?? "" : moduleNode?.text ?? "";
+          if (!module) break;
+          imports.push({
+            module,
+            items: [],
+            isDefault: false,
+            range: this.nodeToRange(node),
+            metadata: { perlSpecific: true, type: "require" }
+          });
+          addRelationship(state.packageName || "global", module, ASTEngine.RelationshipType.Imports, {
+            reasonCode: REASON.runtimeRequire,
+            perlSpecific: true,
+            relationshipType: pathNode ? "require_file" : "require_module",
+            ...pathNode ? { specifier: "path" } : {},
+            isImport: true,
+            fileLevel: true,
+            isPragma: false,
+            items: []
+          }, 0.9, node);
+          patterns.add("Module Includes");
+          return;
+        }
+        case "require_version_expression": {
+          const versionNode = node.childForFieldName("version") || this.findChildByType(node, "number");
+          const version = versionNode?.text || "";
+          if (version) {
+            versionRequirements.push(version);
+            patterns.add("Version Requirements");
+          }
+          return;
+        }
+        case "assignment_expression": {
+          const lefts = this.fieldNodes(node, "left");
+          const rights = this.fieldNodes(node, "right");
+          const leftVar = lefts.flatMap((l) => this.variableChildren(l).map((variable) => this.findChildByType(variable, "varname")).find(Boolean)).find(Boolean);
+          const leftName = leftVar?.text || "";
+          const right = rights.find((r) => r.isNamed && r.namedChildCount > 0) ?? rights[0];
+          if (leftName === "ISA" && right && state.packageName) deferredIsa.push({ owner: state.packageName, right });
+          if (right && (leftName === "EXPORT" || leftName === "EXPORT_OK")) {
+            for (const exported of this.wordValues(right)) {
+              exports.push({ name: exported, kind: ASTEngine.SymbolKind.Function, range: this.nodeToRange(node), metadata: { perlSpecific: true, exportArray: leftName } });
+              addRelationship(state.packageName || "global", exported, ASTEngine.RelationshipType.Exports, { reasonCode: REASON.exportedArrayDeclaration, perlSpecific: true, exportArray: leftName }, 1, node, this.lineOfNameWithin(right, exported));
+            }
+            patterns.add("Exports");
+          }
+          if (leftName === "EXPORT_TAGS" && right) {
+            for (const tag of this.fatCommaKeys(right)) {
+              exports.push({ name: tag.text, kind: ASTEngine.SymbolKind.Function, range: this.nodeToRange(node), metadata: { perlSpecific: true, exportTag: "EXPORT_TAGS" } });
+              addRelationship(state.packageName || "global", tag.text, ASTEngine.RelationshipType.Exports, { reasonCode: REASON.exporterSurface, perlSpecific: true, exportTag: "EXPORT_TAGS" }, 1, node, tag.startPosition.row + 1);
+            }
+            patterns.add("Exports");
+          }
+          break;
+        }
+        case "ambiguous_function_call_expression":
+        case "function_call_expression": {
+          const functionNode = node.childForFieldName("function") || this.findChildByType(node, "function");
+          const target = functionNode?.text || "";
+          if (!this.isWrittenCalleeName(target)) break;
+          if (target === "bless") {
+            const els = this.compositionElements(node);
+            let cls;
+            let clsNode;
+            for (const el of els) {
+              if (el.type !== "string_literal" && el.type !== "interpolated_string_literal") continue;
+              const word = this.wordValues(el)[0];
+              if (word && this.isWrittenCalleeName(word)) {
+                cls = word;
+                clsNode = el;
+              }
+            }
+            if (cls && clsNode) addReferenceName(cls, clsNode, state, REASON.blessClassLiteral);
+            break;
+          }
+          if (target === "UNIVERSAL::isa") {
+            const els = this.compositionElements(node);
+            let cls;
+            let clsNode;
+            for (const el of els) {
+              if (el.type !== "string_literal" && el.type !== "interpolated_string_literal") continue;
+              const word = this.wordValues(el)[0];
+              if (word && this.isWrittenCalleeName(word)) {
+                cls = word;
+                clsNode = el;
+              }
+            }
+            if (cls && clsNode) addReferenceName(cls, clsNode, state, REASON.universalIsaLiteral);
+          }
+          if (target === "push") {
+            const elements = this.compositionElements(node);
+            const targetEl = elements[0];
+            const arrayVar = targetEl && targetEl.type === "array" ? this.findChildByType(targetEl, "varname")?.text ?? "" : "";
+            const arrayName = this.leafName(arrayVar);
+            const owner = arrayVar.includes("::") ? arrayVar.slice(0, arrayVar.lastIndexOf("::")) : state.packageName || "global";
+            const NAMED_ELEMENT = /* @__PURE__ */ new Set(["quoted_word_list", "string_literal", "interpolated_string_literal", "autoquoted_bareword", "bareword"]);
+            if (arrayName === "EXPORT" || arrayName === "EXPORT_OK") {
+              for (const el of elements.slice(1)) {
+                if (!NAMED_ELEMENT.has(el.type)) continue;
+                for (const value of this.wordValues(el)) {
+                  if (!value || this.isOption(value)) continue;
+                  exports.push({ name: value, kind: ASTEngine.SymbolKind.Function, range: this.nodeToRange(node), metadata: { perlSpecific: true, exportArray: arrayName } });
+                  addRelationship(owner, value, ASTEngine.RelationshipType.Exports, { reasonCode: REASON.exportedArrayPush, perlSpecific: true, exportArray: arrayName }, 1, node, this.lineOfNameWithin(el, value));
+                }
+              }
+              patterns.add("Exports");
+            } else if (arrayName === "ISA") {
+              const bases = [];
+              const lines = /* @__PURE__ */ new Map();
+              for (const el of elements.slice(1)) {
+                if (!NAMED_ELEMENT.has(el.type)) continue;
+                for (const value of this.wordValues(el)) {
+                  if (!value || this.isOption(value)) continue;
+                  bases.push(value);
+                  const line = this.lineOfNameWithin(el, value);
+                  if (line !== void 0) lines.set(value, line);
+                }
+              }
+              if (bases.length) addBase(owner, bases, REASON.isaArrayPush, targetEl, lines);
+            }
+            break;
+          }
+          if (target === "has") {
+            const attrs = this.attributeNames(node);
+            for (const attr of attrs) {
+              if (!attr.name || !state.packageName) continue;
+              if (symbolKeys.has(`${ASTEngine.SymbolKind.Property}${state.packageName}${attr.name}`)) continue;
+              addSymbol(attr.name, ASTEngine.SymbolKind.Property, attr.node, { ...state, ownerName: state.packageName, ownerKind: ASTEngine.SymbolKind.Class }, { isMooseProperty: true }, state.packageName);
+            }
+            frameworks.add("Moose/Moo OOP");
+            patterns.add("Declarative Properties");
+          } else if (target === "with" || target === "extends") {
+            const isWith = target === "with";
+            for (const arg of this.compositionElements(node)) {
+              if (arg.type === "anonymous_hash_expression" || arg.type === "anonymous_array_expression") continue;
+              for (const value of this.wordValues(arg)) {
+                if (!value || this.isOption(value)) continue;
+                if (isWith) {
+                  const roleName = this.leafName(value);
+                  const roleLine = this.lineOfNameWithin(arg, value);
+                  addRelationship(
+                    state.packageName || "global",
+                    roleName,
+                    ASTEngine.RelationshipType.Implements,
+                    { reasonCode: REASON.mooRoleComposition, mooseKeyword: target },
+                    0.9,
+                    arg,
+                    // `arg` is the right NODE but the wrong LINE for a `qw` list that
+                    // wraps: the list starts on the `with` line and the role names
+                    // are on the lines after it. Prefer the name's own line and keep
+                    // the node as the fallback, so a shape the offset search cannot
+                    // resolve keeps its previous (correct) line.
+                    roleLine
+                  );
+                  addRelationship(
+                    state.packageName || "global",
+                    roleName,
+                    ASTEngine.RelationshipType.MixesIn,
+                    { reasonCode: REASON.mooRoleComposition, mooseKeyword: target, compositionSite: "role-composition" },
+                    0.9,
+                    arg,
+                    roleLine
+                  );
+                  continue;
+                }
+                addBase(state.packageName || "global", [value], REASON.mooExtendsKeyword, arg, /* @__PURE__ */ new Map([[value, this.lineOfNameWithin(arg, value) ?? arg.startPosition.row + 1]]));
+              }
+            }
+            frameworks.add("Moose/Moo OOP");
+          } else if (target === "new") {
+            const indirect = this.indirectObjectClass(node);
+            const inner = indirect?.carrier;
+            if (inner && indirect?.name) {
+              indirectObjectClassNodes.add(nodeKey(inner));
+              if (indirect.name.includes("::")) qualifiedClassNames.add(indirect.name);
+              addRelationship(state.functionName || state.packageName || "global", `${this.leafName(indirect.name)}.constructor`, ASTEngine.RelationshipType.Instantiates, { isConstructor: true, reasonCode: REASON.indirectObjectInvocation }, 0.9, node);
+              break;
+            }
+            const requestedType = this.firstValue(node);
+            const instanceTarget = requestedType && !requestedType.includes("$") ? `${this.leafName(requestedType)}.constructor` : "constructor";
+            if (requestedType && requestedType.includes("::")) qualifiedClassNames.add(requestedType);
+            addRelationship(state.functionName || state.packageName || "global", instanceTarget, ASTEngine.RelationshipType.Instantiates, { isConstructor: true, reasonCode: REASON.concreteInvocant }, 0.9, node);
+          } else {
+            if (indirectObjectClassNodes.has(nodeKey(node))) break;
+            addCall(target, state, functionNode ?? node, false, node);
+          }
+          break;
+        }
+        case "method_call_expression": {
+          const methodNode = this.findChildByType(node, "method");
+          const method = methodNode?.text || "";
+          if (!this.isWrittenCalleeName(method)) {
+            break;
+          }
+          const invocant = this.fieldNodes(node, "invocant").find((c) => c.isNamed) ?? this.firstNamedChild(node);
+          if (method === "new") {
+            const target = invocant ? this.invocantName(invocant) : "";
+            if (target && PERL_MAGIC_TOKENS.has(target)) {
+              const owner = state.packageName;
+              if (owner && owner !== "main") {
+                if (owner.includes("::")) qualifiedClassNames.add(owner);
+                addRelationship(state.functionName || owner, `${this.leafName(owner)}.constructor`, ASTEngine.RelationshipType.Instantiates, { isConstructor: true, reasonCode: REASON.magicTokenInvocant }, 0.9, invocant ?? node);
+              }
+            } else if (invocant && this.namesAClass(invocant) && target && !target.includes("$") && !target.includes("->")) {
+              if (target.includes("::")) qualifiedClassNames.add(target);
+              addRelationship(state.functionName || state.packageName || "global", `${this.leafName(target)}.constructor`, ASTEngine.RelationshipType.Instantiates, { isConstructor: true, reasonCode: REASON.concreteInvocant }, 0.9, invocant ?? node);
+            }
+          } else {
+            const recvTarget = invocant ? this.invocantName(invocant) : "";
+            const provableClass = invocant != null && this.namesAClass(invocant) && (invocant.type === "package" || recvTarget.includes("::")) && !recvTarget.includes("$") && !recvTarget.includes("->");
+            if (provableClass) {
+              if (recvTarget.includes("::")) qualifiedClassNames.add(recvTarget);
+              addCall(`${this.leafName(recvTarget)}.${method}`, state, methodNode ?? node, false, node, method);
+            } else {
+              addCall(method, state, methodNode ?? node, true, node, method);
+            }
+          }
+          if (method === "isa" || method === "DOES" || method === "can") {
+            const args = this.argumentNodes(node);
+            const named = this.fieldNodes(node, "arguments").filter((a) => a.isNamed);
+            const first = named[0] ?? args[0];
+            const queried = this.literalNameIn(first);
+            if (queried && this.isWrittenCalleeName(queried) && !PERL_MAGIC_TOKENS.has(queried)) {
+              const leaf = this.leafName(queried);
+              const source = state.functionName || state.ownerName || state.packageName || "global";
+              const selfByMethod = leaf === source;
+              const selfByPackage = state.packageName !== "" && queried === state.packageName;
+              if (!selfByMethod && !selfByPackage) {
+                const nameNode = this.queriedNameNode(first) ?? first;
+                addRelationship(
+                  source,
+                  leaf,
+                  ASTEngine.RelationshipType.References,
+                  // The written package rides in `qualifiedAs` for the same
+                  // reason the other reference sites record it: the target is the
+                  // LEAF (one class, one node) and the qualification the source
+                  // wrote is not lost, it is metadata a reader can ask for.
+                  { reasonCode: REASON.typeQueryLiteral, query: method, ...queried.includes("::") ? { qualifiedAs: queried } : {} },
+                  0.9,
+                  nameNode
+                );
+              }
+            }
+          }
+          break;
+        }
+      }
+      if (node.type !== "source_file") {
+        const childState = node.type === "block" || node.type === "block_statement" ? { ...state } : state;
+        for (let i = 0; i < node.namedChildCount; i++) {
+          const child = node.namedChild(i);
+          if (child) walk(child, childState);
+        }
+      }
+    };
+    const walkChildren = (container, state) => {
+      for (let i = 0; i < container.namedChildCount; i++) {
+        const child = container.namedChild(i);
+        if (child) walk(child, state);
+      }
+    };
+    const rootState = { packageName: "", insideFunction: false, visibility: "public", bodyKind: "file" };
+    if (rootNode.type === "source_file") walkChildren(rootNode, rootState);
+    else walk(rootNode, rootState);
+    for (const item of deferredIsa) {
+      const parents = this.wordValues(item.right);
+      if (parents.length) addBase(item.owner, parents, REASON.isaArray, item.right);
+    }
+    for (const [owner, bases] of packageBases) {
+      const origin = packageBaseOrigin.get(owner) ?? REASON.useParentDeclaration;
+      for (const base of bases) {
+        if (base === owner) continue;
+        addRelationship(
+          owner,
+          this.leafName(base),
+          ASTEngine.RelationshipType.Extends,
+          { via: "Perl inheritance", reasonCode: origin },
+          0.9,
+          void 0,
+          packageBaseLine.get(`${owner}${base}`)
+        );
+      }
+    }
+    for (const symbol of symbols) {
+      if (symbol.kind !== ASTEngine.SymbolKind.Method && symbol.kind !== ASTEngine.SymbolKind.Constructor || !symbol.ownerName) continue;
+      const base = packageBases.get(symbol.ownerName)?.[0];
+      if (!base) continue;
+      const baseLeaf = this.leafName(base);
+      if (base === symbol.ownerName) continue;
+      const method = String(symbol.metadata?.originalName || symbol.name);
+      const candidateNames = [method, symbol.name];
+      const localMethods = packageMethods.get(base) || packageMethods.get(baseLeaf);
+      const companionMethods = context?.overrideCompanion?.get(base) || context?.overrideCompanion?.get(baseLeaf);
+      const localDeclares = candidateNames.some((candidate) => localMethods?.has(candidate));
+      const companionDeclares = candidateNames.some((candidate) => companionMethods?.has(candidate));
+      if (localDeclares || companionDeclares) {
+        addRelationship(`${symbol.ownerName}.${method}`, method, ASTEngine.RelationshipType.Overrides, { isOverride: true, reasonCode: REASON.baseDeclaresMethod, overriddenOwner: baseLeaf }, 0.95, void 0, nameLineOf(symbol));
+      } else if (!context?.overrideCompanion?.has(base) && !context?.overrideCompanion?.has(baseLeaf)) {
+        if (base.includes("::")) qualifiedClassNames.add(base);
+        addRelationship(`${symbol.ownerName}.${method}`, `${baseLeaf}.${method}`, ASTEngine.RelationshipType.Overrides, { isOverride: true, reasonCode: REASON.firstParentGuess }, 0.5, void 0, nameLineOf(symbol));
+      }
+    }
+    for (const symbol of symbols) {
+      if (symbol.ownerName && symbol.ownerName !== symbol.name) addRelationship(symbol.ownerName, symbol.name, ASTEngine.RelationshipType.Contains, {}, 1, void 0, nameLineOf(symbol));
+    }
+    const metadata = {
+      complexity: symbols.length + relationships.length,
+      linesOfCode: this.lineCount(content),
+      cyclomaticComplexity: this.countBranches(rootNode) + 1,
+      framework: [...frameworks][0],
+      detectedFrameworks: [...frameworks],
+      patterns: [...patterns],
+      frameworkPatterns: [...patterns].map((pattern) => ({ framework: "Perl", patterns: [{ type: "usage", detected: true, description: pattern }] })),
+      architecturalInsights: [],
+      architecturalScore: Math.max(0, 100 - errors.length * 5),
+      codeQuality: errors.length === 0 ? "Excellent" : "Fair",
+      hasTypeInference: false,
+      hasFrameworkIntelligence: true,
+      analysisVersion: "3.1.0-perl-ast",
+      ...versionRequirements.length ? { perlVersion: versionRequirements[0], perlVersions: versionRequirements } : {}
+    };
+    this.classifyEvidenceTier(relationships);
+    this.publishStatedCauses(symbols, relationships, qualifiedClassNames);
+    this.publishExternalDependencies(symbols, relationships);
+    return { symbols, relationships, imports, exports, errors, metadata };
+  }
+  /**
+   * Perl's own confidences decide the floors, not a copied constant: the
+   * source-declared edges (`extends`/`implements`/`instantiates` from `use
+   * parent`, `with`, `use role`, a class invocant) are all 0.9, `contains` is
+   * 1.0, `calls` is 0.9, and `overrides` is 0.5 because it is guessed from a
+   * first-parent chain. So the guessed kind lands on `inferred` on its own,
+   * with no special case: a 0.5 edge can never clear a 0.7 structural floor.
+   */
+  classifyEvidenceTier(relationships) {
+    for (const r of relationships) {
+      const type = r.type ?? r.relationshipType ?? "";
+      const md = r.metadata ?? {};
+      r.metadata = md;
+      if (type === "contains") {
+        md.evidenceClass = "structural";
+        continue;
+      }
+      if (type === "imports" || type === "exports") {
+        md.evidenceClass = "import_based";
+        continue;
+      }
+      if (type === "instantiates" || type === "extends" || type === "implements") {
+        md.evidenceClass = (r.confidence ?? 0) >= 0.9 ? "structural" : "inferred";
+        continue;
+      }
+      if (type === "calls") {
+        md.evidenceClass = (r.confidence ?? 0) >= 0.85 ? "usage_contextual" : "inferred";
+        continue;
+      }
+      if (type === "uses" || type === "references") {
+        md.evidenceClass = (r.confidence ?? 0) >= 0.7 ? "usage_contextual" : "inferred";
+        continue;
+      }
+      if (type === "overrides") {
+        md.evidenceClass = "inferred";
+        continue;
+      }
+      md.evidenceClass = "inferred";
+    }
+  }
+  result(symbols, relationships, imports, exports, errors, content, frameworks, patterns) {
+    return {
+      symbols,
+      relationships,
+      imports,
+      exports,
+      errors,
+      metadata: {
+        complexity: symbols.length + relationships.length,
+        linesOfCode: this.lineCount(content),
+        cyclomaticComplexity: 1,
+        framework: [...frameworks][0],
+        detectedFrameworks: [...frameworks],
+        patterns: [...patterns],
+        frameworkPatterns: [],
+        architecturalInsights: [],
+        architecturalScore: Math.max(0, 100 - errors.length * 5),
+        codeQuality: errors.length === 0 ? "Excellent" : "Fair",
+        hasTypeInference: false,
+        hasFrameworkIntelligence: true,
+        analysisVersion: "3.1.0-perl-ast"
+      }
+    };
+  }
+  collectErrors(root, errors) {
+    const stack = [root];
+    while (stack.length > 0) {
+      const node = stack.pop();
+      if (node.type === "ERROR" || node.isMissing) {
+        errors.push({ message: `Syntax ${node.type} detected.`, range: this.nodeToRange(node), severity: "warning" });
+      }
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child) stack.push(child);
+      }
+    }
+  }
+  /**
+   * ALL children carrying `name` as their field.
+   *
+   * The pinned grammar gives one field name to SEVERAL children whenever a
+   * construct is parenthesised: `our @EXPORT_OK = (a => 1, b => 2)` puts `(`,
+   * the `list_expression` and `)` ALL under the `right` field, so
+   * `childForFieldName("right")` returns the EMPTY `(` marker. Measured over
+   * mojo+Moose+DBI+plack: `assignment_expression.right` 1,593 sites,
+   * `ambiguous_function_call_expression.arguments` 1,058,
+   * `method_call_expression.invocant` 168, `function_call_expression.arguments`
+   * 3, `method_call_expression.arguments` 36 — every one of them lost by the
+   * single-child read. `variable_declaration` additionally spells the paren form
+   * `variables` (plural) against the bare form `variable`, 14,272 sites.
+   */
+  fieldNodes(node, name) {
+    const out = [];
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (child && node.fieldNameForChild(i) === name) out.push(child);
+    }
+    return out;
+  }
+  /**
+   * The declared variables of a `variable_declaration`. The bare form
+   * (`our $VERSION`) spells the field `variable`; the parenthesised form
+   * (`our ($x, $y) = ...`) spells it `variables`, so BOTH are read.
+   */
+  variableChildren(node) {
+    const result = [];
+    for (const child of [...this.fieldNodes(node, "variable"), ...this.fieldNodes(node, "variables")]) {
+      if (child.type === "scalar" || child.type === "array" || child.type === "hash") result.push(child);
+    }
+    return result;
+  }
+  /**
+   * The declaration scope, read from the grammar's own scope node.
+   *
+   * `variable_declaration` declares NO `scope` field: `our`/`my`/`state`/`field`
+   * are CHILD NODES of the declaration. The pre-review implementation matched
+   * `node.text.startsWith("our ")` — source text doing a syntax job, which
+   * mis-reads any declaration whose keyword is followed by a newline or whose
+   * text begins with something else.
+   *
+   * Those scope tokens are UNNAMED (`node.isNamed === false`, no field), so the
+   * scan walks the RAW child list. A named-child scan silently finds nothing
+   * and every `our` global in the corpus would vanish — the 2,379 constants
+   * measured on the pre-review corpus all came from the text prefix.
+   */
+  declarationKind(node) {
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (!child) continue;
+      if (child.type === "our" || child.type === "my" || child.type === "state" || child.type === "field") return child.type;
+    }
+    return "unknown";
+  }
+  /**
+   * The argument nodes of a call or `use`.
+   *
+   * Two grammar generations have to be read here, and both are live:
+   *  - 1.2.1 (the WIRED build): the `arguments` field is MULTI-CHILD — a
+   *    parenthesised argument list spreads one field across `(`, the payload
+   *    and `)`, so `childForFieldName` returns the empty bracket marker.
+   *    Measured on 5,875 corpus files: 39,897 such sites over 41 field pairs.
+   *  - 2.0.0: the paren is a `parenthesized_expression` NODE, and on a
+   *    `use_statement` it carries NO field at all — so a field-driven read sees
+   *    nothing and the whole import list disappears.
+   *
+   * Reading every child that yields words, and descending through the paren
+   * wrapper, is correct under BOTH: measured over the same 5,875 files, the
+   * analyzer's emissions are then identical under a 1.2.1 build and a 2.0.0
+   * build on 5,875 of 5,875 files, so a grammar bump needs no analyzer work.
+   */
+  argumentNodes(node) {
+    return perlArgumentNodes(node);
+  }
+  /**
+   * The line a NAME is written on INSIDE a node, when the node's own start line
+   * is not it. `with qw/\n  MooseRoleOne\n  MooseRoleTwo\n/` is ONE
+   * `quoted_word_list` node starting on the `with` line, so stamping the edge from
+   * that node puts `implements` two lines above the role it names.
+   *
+   * Scoped to the ARGUMENT node, never the whole statement: for
+   * `use Moose::Role 'My::Role'`, searching the statement for `Role` finds the
+   * one inside `Moose::Role` and returns the module's line — exactly the bug
+   * this avoids. Returns undefined when the name is not in the node's text, so
+   * callers fall back to the node's own line rather than inventing one.
+   */
+  lineOfNameWithin(node, name) {
+    if (!name) return void 0;
+    const text = String(node.text ?? "");
+    let from = 0;
+    for (; ; ) {
+      const idx = text.indexOf(name, from);
+      if (idx < 0) return void 0;
+      const before = idx > 0 ? text[idx - 1] : "";
+      const after = text[idx + name.length] ?? "";
+      if (!isPerlIdentChar(before) && !isPerlIdentChar(after)) {
+        let line = node.startPosition.row;
+        for (let i = 0; i < idx; i++) if (text.charCodeAt(i) === 10) line++;
+        return line + 1;
+      }
+      from = idx + 1;
+    }
+  }
+  /**
+   * Is this callee text a NAME the source actually writes?
+   *
+   * A target that is not written cannot be verified — the M59 line oracle reads
+   * every claimed target back against the file's own text, and one that is not
+   * there is a FABRICATED claim rather than a weak one. Same reasoning that
+   * removed the phantom `DSN` and `use_module` classes, applied to the method
+   * side, and found by that oracle:
+   *
+   *   Moo/Object.pm:56   calls -> DemolishAll->new
+   *   Moo/Role.pm:224    calls -> ${\( $tc->can('coercion')||sub { ... } )}
+   *
+   * Both are symbolic deref — `$self->${\( EXPR \)}`, perl's "call the method
+   * whose name this expression computes". The grammar puts the whole expression
+   * in the `method` field, so the lane published arbitrary source text as a
+   * callee name. A POSITIVE allowlist again, not a "does this look wrong" test:
+   * a negative test only enumerates the dynamic cases somebody already hit, and
+   * this pair has been wrong that way three times.
+   *
+   * Rejected: a sigil (`->$name`), braces, `$`, `->`, whitespace. For a rejected
+   * one NO edge is emitted — and the children are still walked, so the real calls
+   * INSIDE the expression survive: `Method::Generate::DemolishAll->new` inside a
+   * deref becomes its own `instantiates` edge. 19 such edges left a 14-file
+   * draw.
+   */
+  isWrittenCalleeName(text) {
+    const t = String(text ?? "").trim();
+    if (!t) return false;
+    for (let i2 = 0; i2 < t.length; i2++) {
+      const c = t.charAt(i2);
+      if (c === " " || c === "	" || c === "\n" || c === "\r") return false;
+      if (c === "$" || c === "{" || c === "}") return false;
+    }
+    if (t.includes("->")) return false;
+    let i = 0;
+    if (t.charAt(i) === "&") i++;
+    if (t.charAt(i) === ":" && t.charAt(i + 1) === ":") i += 2;
+    let segments = 0;
+    for (; ; ) {
+      if (segments > 0) {
+        if (t.charAt(i) !== ":" || t.charAt(i + 1) !== ":") break;
+        i += 2;
+      }
+      if (!isPerlIdentStart(t.charAt(i))) return false;
+      i++;
+      while (isPerlIdentChar(t.charAt(i))) i++;
+      segments++;
+      if (i >= t.length) return true;
+    }
+    return false;
+  }
+  /**
+   * The ELEMENTS of a role-composition argument list — the shapes `with` and
+   * `extends` are written in, as separate elements rather than as one blob.
+   *
+   * The call's `arguments` field holds ONE `list_expression` for every
+   * multi-argument form, so a reader that treated that field as a single argument
+   * read the first word of the WHOLE list and dropped the rest. Expanding the list
+   * into its named children restores the element boundary: in
+   * `with A, { -excludes => [...] }, B` the elements are A, the modifier hash
+   * and B, which is exactly the information the role reader needs.
+   */
+  compositionElements(node) {
+    const out = [];
+    for (const arg of this.argumentNodes(node)) {
+      if (arg.type === "list_expression") {
+        for (let i = 0; i < arg.namedChildCount; i++) {
+          const child = arg.namedChild(i);
+          if (child) out.push(child);
+        }
+      } else out.push(arg);
+    }
+    return out;
+  }
+  /**
+   * The names a `has` declaration declares — ONE per element of its name list.
+   *
+   * TWO facts live here and each was a measured defect. (1) A QUOTED name is ONE
+   * name whatever it contains: `has 'has spaces' => (is => 'ro')` is a legal
+   * attribute whose name has a space in it, and the old reader ran the name
+   * through `wordValues`, whose whitespace splitter exists for `qw(a b)` (a real
+   * LIST) and truncated this to `has` — publishing a member named `has`, which is
+   * a real perl function, while the declared member got no symbol at all. (2) A
+   * `qw`/array list declares SEVERAL attributes: `has [qw(handlers helpers)]` is
+   * two members, and reading only the first dropped the rest.
+   *
+   * The splitter is therefore applied to the shapes that ARE lists
+   * (`quoted_word_list`, each element of an array), and never to a string
+   * literal's own content.
+   */
+  attributeNames(node) {
+    const args = this.argumentNodes(node);
+    const first = args[0];
+    if (!first) return [];
+    const head = first.type === "list_expression" && first.namedChildCount > 0 ? first.namedChild(0) : first;
+    if (!head) return [];
+    return this.namesOfDeclarator(head);
+  }
+  namesOfDeclarator(head) {
+    if (head.type === "string_literal") {
+      const content = head.childForFieldName("content") || this.findChildByType(head, "string_content");
+      const name = content ? content.text : unquote(head.text);
+      return name ? [{ name, node: content ?? head }] : [];
+    }
+    if (head.type === "quoted_word_list") {
+      const content = head.childForFieldName("content") || this.findChildByType(head, "string_content");
+      if (!content) return [];
+      return splitWords(content.text).filter(Boolean).map((name) => ({ name, node: content }));
+    }
+    if (head.type === "anonymous_array_expression") {
+      const out = [];
+      for (let i = 0; i < head.namedChildCount; i++) {
+        const child = head.namedChild(i);
+        if (child) out.push(...this.namesOfDeclarator(child));
+      }
+      return out;
+    }
+    if (head.type === "interpolated_string_literal") {
+      const pieces = [];
+      let interpolates = false;
+      for (let i = 0; i < head.namedChildCount; i++) {
+        const child = head.namedChild(i);
+        if (!child) continue;
+        if (child.type === "string_content") pieces.push(...splitWords(child.text));
+        else if (child.type === "scalar" || child.type === "array" || child.type === "hash") interpolates = true;
+      }
+      if (interpolates) return pieces.filter(Boolean).map((name) => ({ name, node: head }));
+      const content = head.childForFieldName("content") || this.findChildByType(head, "string_content");
+      const verbatim = content ? content.text : "";
+      return verbatim ? [{ name: verbatim, node: content ?? head }] : [];
+    }
+    return this.wordValues(head).filter(Boolean).map((name) => ({ name, node: head }));
+  }
+  argumentValues(node) {
+    const module = node.childForFieldName("module");
+    if (module && module.type !== "package") return this.wordValues(module);
+    const values = [];
+    for (const arg of this.argumentNodes(node)) values.push(...this.wordValues(arg));
+    return values;
+  }
+  /**
+   * The fat-comma KEYS of a list: the named child immediately followed by a
+   * `=>` token. Read from the child list, so `A => 1, B => 2` yields A and B
+   * and never the values.
+   */
+  fatCommaKeys(node) {
+    let list;
+    if (node.type === "list_expression") list = node;
+    else {
+      list = this.findChildByType(node, "list_expression");
+      if (!list) {
+        const hash = this.findChildByType(node, "anonymous_hash_expression");
+        if (hash) list = this.findChildByType(hash, "list_expression");
+      }
+    }
+    if (!list) return [];
+    const keys = [];
+    let pending = null;
+    for (let i = 0; i < list.childCount; i++) {
+      const child = list.child(i);
+      if (!child) continue;
+      if (child.type === "=>") {
+        if (pending) keys.push(pending);
+        pending = null;
+        continue;
+      }
+      pending = child.isNamed ? child : pending;
+    }
+    return keys;
+  }
+  /** Names declared by `use constant ...` — the fat-comma keys. */
+  constantDeclarationNames(node) {
+    const result = [];
+    for (const key of this.fatCommaKeys(node)) {
+      const name = this.wordValues(key)[0];
+      if (name) result.push({ name, node: key });
+    }
+    return result;
+  }
+  wordValues(node) {
+    return perlWordValues(node);
+  }
+  firstValue(node) {
+    const values = this.argumentValues(node);
+    return values[0];
+  }
+  /**
+   * M14 #863 REPAYMENT — the dead `childForFieldName("parameters")`.
+   *
+   * The pinned tree-sitter-perl grammar declares NO `parameters` field, so that
+   * lookup returned undefined for every sub in every file and the lane shipped
+   * 0 parameters across 29,640 symbols on 5,866 corpus files. A signature is the
+   * `signature` NODE TYPE, whose children are `mandatory_parameter`,
+   * `optional_parameter` and `slurpy_parameter`; each wraps the
+   * scalar/array/hash node that carries the `varname`.
+   *
+   * The first version of this fix said FIELD here and reached for
+   * `childForFieldName("signature")`, which is dead for the same reason the
+   * original was — `signature` is not among the grammar's 44 fields either. The
+   * working `findChildByType` beside it is what has been producing every
+   * parameter all along, and the dead-literal audit is what finally said so. The
+   * wording is corrected here because the wrong word is what produced the bug.
+   */
+  extractParameters(node) {
+    const signature = this.findChildByType(node, "signature");
+    if (!signature) return [];
+    const result = [];
+    for (let i = 0; i < signature.namedChildCount; i++) {
+      const param = signature.namedChild(i);
+      if (!param) continue;
+      const kind = param.type;
+      if (kind !== "mandatory_parameter" && kind !== "optional_parameter" && kind !== "slurpy_parameter") continue;
+      const carrier = this.findChildByType(param, "scalar") || this.findChildByType(param, "array") || this.findChildByType(param, "hash");
+      if (!carrier) continue;
+      const varname = this.findChildByType(carrier, "varname");
+      if (!varname) continue;
+      result.push({ name: this.stripSigil(varname.text), isOptional: kind === "optional_parameter" });
+    }
+    return result;
+  }
+  /** `sub f :lvalue :method` — the grammar's `attributes` field. */
+  extractAttributes(node) {
+    const attrlist = node.childForFieldName("attributes") || this.findChildByType(node, "attrlist");
+    if (!attrlist) return [];
+    const result = [];
+    for (let i = 0; i < attrlist.namedChildCount; i++) {
+      const attribute = attrlist.namedChild(i);
+      if (!attribute || attribute.type !== "attribute") continue;
+      const nameNode = attribute.childForFieldName("name") || this.findChildByType(attribute, "attribute_name");
+      const name = nameNode?.text || "";
+      if (name) result.push(name);
+    }
+    return result;
+  }
+  /**
+   * Does this receiver node NAME a class, as opposed to being a runtime value?
+   *
+   * The allowlist is the set of node types whose entire content is a name. A
+   * `function_call_expression` is deliberately absent: its `function` field is
+   * the name of a FUNCTION, and calling it yields a value, so
+   * `use_module('X')->new` constructs nothing knowable. `ambiguous_function_
+   * call_expression` IS present because that is the indirect-object spelling,
+   * where the node's `function` field is the class.
+   */
+  /**
+   * The CLASS half of an indirect-object call: `new Class @args` is exactly
+   * `Class->new(@args)`, and the grammar spells the class as the `function`
+   * FIELD of a nested `ambiguous_function_call_expression`.
+   *
+   * Read STRUCTURALLY, from the node's named children, rather than through
+   * `argumentNodes` — that helper keeps an argument only when it contributes at
+   * least one WORD, and this nested call contributes none whenever its own
+   * arguments are a plain scalar or a list of literals. Measured: it returned
+   * `[]` for `new Win32::ODBC $dbname` and `new Foo 1, 2` but DID return the
+   * call for `new Win32::ODBC $x->{DSN}` — kept only because of a hash KEY, which
+   * is the same accident that published the phantom class `DSN`. A structural
+   * read is right for all three, and for the third shape (`new Foo;`, where the
+   * class is a direct `bareword` child and there is no nested call at all) the
+   * caller's existing path already reads the bareword correctly.
+   */
+  indirectObjectClass(node) {
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (!child || child.type !== "ambiguous_function_call_expression") continue;
+      const fn = child.childForFieldName("function") || this.findChildByType(child, "function");
+      if (fn?.text) return { name: fn.text, carrier: child };
+    }
+    return void 0;
+  }
+  namesAClass(node) {
+    switch (node.type) {
+      case "bareword":
+      case "autoquoted_bareword":
+      case "package":
+      case "ambiguous_function_call_expression":
+        return true;
+      case "string_literal":
+      case "interpolated_string_literal":
+        return !node.text.includes("$");
+      default:
+        return false;
+    }
+  }
+  invocantName(node) {
+    if (node.type === "scalar" || node.type === "array" || node.type === "hash") {
+      return node.text;
+    }
+    if (node.type === "function_call_expression" || node.type === "ambiguous_function_call_expression") {
+      const fn = node.childForFieldName("function") || this.findChildByType(node, "function");
+      return fn?.text || "";
+    }
+    return node.text;
+  }
+  isOption(value) {
+    return value.length > 0 && value[0] === "-";
+  }
+  /**
+   * The NAME an argument node writes, and only when it writes one literally.
+   *
+   * `'Class::Name'` and `Class::Name` are names. `$class`, `@classes` and
+   * `"Pkg::$sub"` are not: the file states no name, so an edge built on one
+   * would name a symbol the source never mentions. The interpolation test is
+   * character comparison on the literal's own text, never a pattern -- the
+   * grammar exposes the unquoted body under `content`, so there is nothing to
+   * unquote here and nothing to strip.
+   *
+   * Returns undefined for every other node type, which is the refusal the
+   * measured counts depend on: 170 `isa($var)` and 5 `DOES($var)` sites in
+   * 5,127 files resolve to nothing rather than to a guess.
+   */
+  literalNameIn(node) {
+    if (!node) return void 0;
+    if (node.type !== "string_literal" && node.type !== "bareword" && node.type !== "package" && node.type !== "autoquoted_bareword") return void 0;
+    if (node.text.includes("$")) return void 0;
+    const content = node.childForFieldName("content") ?? this.findChildByType(node, "string_content");
+    const text = String(content?.text ?? node.text ?? "").trim();
+    return text.length ? text : void 0;
+  }
+  /**
+   * The node a queried name is WRITTEN on, so the edge's `line_number` is the
+   * line that names it and not the line the call starts on (M59.A7: the line
+   * comes from the node that NAMES the edge). `literalNameIn` already decided
+   * the name exists; this only locates it.
+   */
+  queriedNameNode(node) {
+    if (!node) return void 0;
+    return node.childForFieldName("content") ?? this.findChildByType(node, "string_content") ?? this.findChildByType(node, "varname") ?? node;
+  }
+  stripSigil(name) {
+    if (!name) return name;
+    const first = name[0];
+    return first === "$" || first === "@" || first === "%" || first === "#" ? name.slice(1) : name;
+  }
+  leafName(name) {
+    let trimmed = name;
+    while (trimmed.length >= 2 && trimmed.charAt(trimmed.length - 1) === ":" && trimmed.charAt(trimmed.length - 2) === ":") trimmed = trimmed.slice(0, -2);
+    const colon = trimmed.lastIndexOf("::");
+    return colon >= 0 ? trimmed.slice(colon + 2) : trimmed;
+  }
+  /**
+   * THE BASE A `leaf.member` TARGET NAMES — the single-dot, identifier-shaped owner the declared
+   * cause channel is defined over, or null when the target cannot carry that claim at all.
+   *
+   * This is not a style choice, it is the channel's own precondition. The arbiter takes the owner
+   * as everything before the LAST dot (`incoming-rule.ts` `targetOwner`) and accepts a stated base
+   * only when it is IDENTIFIER-SHAPED and IS that owner
+   * (`classifyEdge`: `const shaped = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(claim.base)` then
+   * `const consistent = shaped && owner === claim.base`). A target carrying two dots, an empty
+   * member, or an owner with `::` in it therefore cannot be given this claim: writing one there
+   * reads `causeRefuted`, which is `causeFAIL` — a clause-4 defect, not a stated cause.
+   *
+   * The character test is the lane's own `isPerlIdentStart`/`isPerlIdentChar` rather than a regex
+   * literal, because this file's contract forbids regex literals (proved by
+   * `script/m14/tmp/perl-zero-regex.mts`), and reusing them keeps the predicate from drifting away
+   * from the rest of the lane.
+   */
+  statedOwnerOf(target) {
+    const dot = target.lastIndexOf(".");
+    if (dot <= 0 || dot === target.length - 1) return null;
+    if (target.indexOf(".") !== dot) return null;
+    const owner = target.slice(0, dot);
+    if (!isPerlIdentStart(owner[0])) return null;
+    for (let i = 1; i < owner.length; i++) if (!isPerlIdentChar(owner[i])) return null;
+    return owner;
+  }
+  /**
+   * PUBLISH THE REASON THE LANE ALREADY COMPUTES, ON THE KEY THE GATE READS — the fleet's finding
+   * (a), measured on this lane rather than assumed: every perl edge below confidence 1.0 carries a
+   * machine-readable `metadata.reasonCode` (M14 HONESTY-CONTRACT §4.1 — the 1,664 `contains` edges
+   * are @1.0 and carry none), and the arbiter's bucket-3 column reads
+   * `metadata.baseBeyondRunScope` ONLY (`incoming-rule.ts` `CAUSE_CLAIM_KEY`). So the gate printed
+   * `causeOK 0`, `clause 2 ok — no edge carries a declared cause (residual 6998)`, and clause 2
+   * passed VACUOUSLY over a 4,110-edge unresolved residual. See
+   * `validation/m14/verification/PERL-FIX.md` for the bucketed residual and the measurements.
+   *
+   * WHAT THE CLAIM MEANS, and it is a claim about the RUN, not about the project: "the base this
+   * edge names is beyond THIS RUN's reach" (`incoming-rule.ts`, `CAUSE_CLAIM_KEY`). Production
+   * parses a perl file with NO project index and NO override companion
+   * (`parallel-indexer.ts` `PROJECT_INDEX_EXTENSIONS` names only `.sol`), so a class another file
+   * declares is genuinely out of this run's sight — which is exactly what the lane's own reason
+   * codes already say (`first-parent-guess`: "the base does not declare it anywhere visible";
+   * `name-only-callee`: "whether it binds to a sub in this file, an imported sub, or a
+   * module-level sub is not decided at this edge"). Dart is the reference implementation of this
+   * mechanism for the index-less case (`real-dart-analyzer.ts:2089-2091`).
+   *
+   * THE GUARD, and it is the difference between a stated cause and a laundering vector: the claim
+   * is attached ONLY where the class the target names is NOT published by the file being analyzed.
+   * When this file declares the class, the run DID reach it, and "beyond this run's reach" would be
+   * FALSE — so `IOLoop.start` inside `package IOLoop` keeps its reason code and states nothing.
+   * The arbiter cannot check this half (property 4 of the channel — a second implementation — is
+   * explicitly not claimed to exist), so the analyzer must not state it.
+   *
+   * It can never move a resolution number. `classifyEdge` reads a cause ONLY inside its
+   * `decls === 0` branch, so a claimed edge is already unresolved; and it is REFUTED outright if
+   * the edge also carries an external claim — the lane publishes none, which is why the conflict
+   * branch cannot fire here.
+   */
+  publishStatedCauses(symbols, relationships, qualifiedClassNames) {
+    const declaredHere = /* @__PURE__ */ new Set();
+    for (const symbol of symbols) {
+      const kind = symbol.kind;
+      if (kind !== ASTEngine.SymbolKind.Class && kind !== ASTEngine.SymbolKind.Trait) continue;
+      const name = String(symbol.name ?? "");
+      if (name) declaredHere.add(this.leafName(name));
+    }
+    const heldQualified = /* @__PURE__ */ new Set();
+    for (const qualified of qualifiedClassNames) heldQualified.add(this.leafName(qualified));
+    for (const relationship of relationships) {
+      const type = relationship.type;
+      if (type !== ASTEngine.RelationshipType.Calls && type !== ASTEngine.RelationshipType.Overrides && type !== ASTEngine.RelationshipType.Instantiates) continue;
+      const metadata = relationship.metadata;
+      if (!metadata || metadata.baseBeyondRunScope !== void 0) continue;
+      const owner = this.statedOwnerOf(String(relationship.target ?? ""));
+      if (owner === null || declaredHere.has(owner)) continue;
+      if (heldQualified.has(owner)) continue;
+      metadata.baseBeyondRunScope = owner;
+    }
+  }
+  /**
+   * PERL-1 — A DEPENDENCY THE FILE DOES NOT DECLARE IS A CLAIM, NOT SILENCE.
+   *
+   * The lane published no externality reading at all: its whole-population arm read **10,096 edges ·
+   * 4,605 resolved · 9,435 ambiguous/unresolved · 0 verified · 0 refuted**, i.e. 93 % of the graph was
+   * wall. The two largest unresolved labels are the two dependencies Perl names without any syntax of
+   * its own:
+   *
+   *   `use strict` / `use warnings` / `use Test::More`   an IMPORT of a module or pragma
+   *   `is(…)` / `plan(…)` / `ok(…)` / `run_tests(…)`     a BARE function call
+   *
+   * MEASURED: `imports` 1,654 unresolved (strict 328 · Test::More 267 · warnings 228 ·
+   * Test::Nginx::Socket::Lua 120) and `calls` 2,966 unresolved (is 206 · plan 175 · run_tests 124 ·
+   * repeat_each 122 · blocks 120 · ok 118). None of those names is declared by a corpus file that does
+   * not already declare it, so every row was a dependency published with no reading at all.
+   *
+   * THE CLAIM IS SAFE BY CONSTRUCTION, exactly as on the powershell and haskell lanes: the arbiter
+   * consults a claim only where the name model has NOTHING (`decls === 0`), so a name the project
+   * declares keeps its resolved/ambiguous answer and this claim cannot refute it. The guard is the
+   * file's own declaration table, so a local sub or a package this file declares keeps no claim.
+   */
+  publishExternalDependencies(symbols, relationships) {
+    const declared = /* @__PURE__ */ new Set();
+    for (const s of symbols) if (s.name) declared.add(s.name);
+    for (const rel of relationships) {
+      const type = rel.type;
+      if (type !== ASTEngine.RelationshipType.Imports && type !== ASTEngine.RelationshipType.Calls && type !== ASTEngine.RelationshipType.Instantiates && type !== ASTEngine.RelationshipType.Extends && type !== ASTEngine.RelationshipType.Uses) continue;
+      const md = rel.metadata;
+      if (!md || md.externalTarget === true) continue;
+      if (type === ASTEngine.RelationshipType.Calls && md.baseBeyondRunScope !== void 0) continue;
+      const target = String(rel.target ?? "");
+      if (target.length === 0) continue;
+      if (!this.isPerlName(target)) continue;
+      if (declared.has(target) || declared.has(this.leafName(target))) continue;
+      if (target.indexOf("::") >= 0) {
+        md.externalTarget = true;
+        md.externalReason = "module-namespace";
+        md.externalSpecifier = target;
+        continue;
+      }
+      md.externalTarget = true;
+      md.externalVia = type === ASTEngine.RelationshipType.Imports ? "use" : "call";
+    }
+  }
+  /** A Perl module/function spelling: `strict`, `Test::More`, `is`, `run_tests`. */
+  isPerlName(name) {
+    const code = name.charCodeAt(0);
+    const firstOk = code >= 65 && code <= 90 || code >= 97 && code <= 122 || code === 95;
+    if (!firstOk) return false;
+    for (let i = 1; i < name.length; i++) {
+      const c = name.charCodeAt(i);
+      const ok = c >= 65 && c <= 90 || c >= 97 && c <= 122 || c >= 48 && c <= 57 || c === 95 || c === 58;
+      if (!ok) return false;
+    }
+    return !name.endsWith(":");
+  }
+  isAllCapsName(name) {
+    let hasLetter = false;
+    for (const char of name) {
+      if (char >= "a" && char <= "z") return false;
+      if (char >= "A" && char <= "Z" || char >= "0" && char <= "9" || char === "_") hasLetter = true;
+    }
+    return hasLetter;
+  }
+  findChildByType(node, type) {
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child?.type === type) return child;
+    }
+    return void 0;
+  }
+  firstNamedChild(node) {
+    return node.namedChildCount > 0 ? node.namedChild(0) || void 0 : void 0;
+  }
+  /**
+   * Cyclomatic decision points, counted from the pinned grammar's OWN node
+   * types (probed: script/m14/tmp/perl-branch-shapes.ts).
+   *
+   * The pre-review set named `if_statement`, `unless_statement`,
+   * `while_statement`, `until_statement`, `foreach_statement` and
+   * `ternary_expression` — SIX literals the grammar does not declare, so only
+   * `for_statement` and `conditional_expression` ever fired and
+   * cyclomaticComplexity was 1 for almost every real file. This grammar spells
+   * them `conditional_statement` (if/unless), `loop_statement` (while/until/
+   * bare foreach), `for_statement`, `cstyle_for_statement`,
+   * `conditional_expression` (ternary), `postfix_conditional_expression`
+   * (statement modifier) and `try_statement`; `elsif` and `catch` are further
+   * decisions in their own chains.
+   */
+  countBranches(root) {
+    const branchTypes = /* @__PURE__ */ new Set([
+      "conditional_statement",
+      "elsif",
+      "loop_statement",
+      "for_statement",
+      "cstyle_for_statement",
+      "conditional_expression",
+      "postfix_conditional_expression",
+      "try_statement",
+      "catch",
+      "when",
+      "given"
+    ]);
+    const logicalTypes = /* @__PURE__ */ new Set(["lowprec_logical_expression", "logical_not_expression"]);
+    let count = 0;
+    const stack = [root];
+    while (stack.length > 0) {
+      const node = stack.pop();
+      if (branchTypes.has(node.type)) count++;
+      else if (logicalTypes.has(node.type)) {
+        for (let i = 0; i < node.childCount; i++) {
+          const child = node.child(i);
+          if (child && (child.type === "&&" || child.type === "||" || child.type === "and" || child.type === "or")) {
+            count++;
+            break;
+          }
+        }
+      }
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child) stack.push(child);
+      }
+    }
+    return count;
+  }
+  lineCount(content) {
+    let lines = 1;
+    for (const char of content) if (char === "\n") lines++;
+    return lines;
+  }
+  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 {
+  PERL_BUILTINS,
+  PERL_REASON_CODES,
+  RealPerlAnalyzer,
+  hasArgumentSyntax,
+  perlArgumentNodes,
+  perlWordValues
+};