@backbencher/brain 0.0.0-stage → 0.1.1

package/dist/real-json-analyzer-MPA6PRXL.js

@@ -0,0 +1,1640 @@
+import {
+  applyDocumentScope,
+  documentDirScope,
+  projectRelativePath
+} from "./chunk-2WXYNLBA.js";
+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-json-analyzer.ts
+import { statSync } from "fs";
+import { join } from "path";
+var VALIDATION_KEYS = /* @__PURE__ */ new Set([
+  "minLength",
+  "maxLength",
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "pattern",
+  "format",
+  "enum",
+  "const",
+  "multipleOf",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "minProperties",
+  "maxProperties",
+  "additionalProperties"
+]);
+var API_METHOD_KEYS = /* @__PURE__ */ new Set(["get", "post", "put", "patch", "delete", "head", "options", "trace"]);
+var LSP_INHERITANCE_KEYS = ["extends", "base", "superclass", "superClass", "implements", "mixins"];
+function isDependencyContainerPath(path) {
+  const dot = path.lastIndexOf(".");
+  const segment = dot >= 0 ? path.slice(dot + 1) : path;
+  return segment === "dependencies" || segment === "devDependencies" || segment === "peerDependencies" || segment === "optionalDependencies";
+}
+function isPathReference(value) {
+  return value.startsWith("#/") || value.startsWith("#/definitions/") || value.startsWith("#/components/");
+}
+var RealJsonAnalyzer = class {
+  analyze(rootNode, content, filePath, context) {
+    const rootName = this.documentName(filePath, context?.projectRoot);
+    const ctx = {
+      filePath,
+      projectRoot: typeof context?.projectRoot === "string" ? context.projectRoot : void 0,
+      content,
+      rootName,
+      symbols: [],
+      symbolMap: /* @__PURE__ */ new Map(),
+      relationships: [],
+      imports: [],
+      exports: [],
+      errors: [],
+      requiredByObject: /* @__PURE__ */ new Map(),
+      schemaObjects: /* @__PURE__ */ new Set(),
+      referenceSymbols: [],
+      validationSymbols: [],
+      apiEndpointSymbols: [],
+      dependencySymbols: [],
+      dependencyVersions: /* @__PURE__ */ new Map(),
+      overrideCandidates: [],
+      emittedPaths: /* @__PURE__ */ new Set(),
+      usesReferenceLiterals: false,
+      usesClassDeclarations: false,
+      typeDeclarations: /* @__PURE__ */ new Map(),
+      documentIds: /* @__PURE__ */ new Map(),
+      documentAnchors: /* @__PURE__ */ new Map(),
+      inheritanceCandidates: [],
+      objectCount: 0,
+      propertyCount: 0,
+      rootNode,
+      arrayCount: 0,
+      maxDepth: 0,
+      hasNullValues: false,
+      hasBooleanValues: false,
+      hasArrays: false
+    };
+    this.collectErrors(rootNode, ctx);
+    this.collectSchemaFacts(rootNode, ctx);
+    this.extractSymbols(rootNode, ctx);
+    this.extractRelationships(ctx);
+    this.extractManifestExports(ctx);
+    this.extractSchemaComposition(ctx);
+    this.extractDeclaredInheritance(ctx);
+    this.extractPackageDependencies(ctx);
+    this.extractNpmScriptCalls(ctx);
+    this.extractDuplicateKeyOverrides(ctx);
+    const rootSymbol = {
+      name: rootName,
+      kind: ASTEngine.SymbolKind.Module,
+      qualifiedName: rootName,
+      range: this.nodeToRange(rootNode),
+      scope: "",
+      visibility: "public",
+      metadata: {
+        jsonSpecific: true,
+        documentType: this.documentType(ctx),
+        hasSchema: ctx.schemaObjects.size > 0 || ctx.symbolMap.has("$schema"),
+        isApiSpec: this.isApiSpec(ctx),
+        objectCount: ctx.objectCount,
+        propertyCount: ctx.propertyCount,
+        arrayCount: ctx.arrayCount,
+        maxDepth: ctx.maxDepth,
+        hasNullValues: ctx.hasNullValues,
+        hasBooleanValues: ctx.hasBooleanValues
+      }
+    };
+    ctx.symbols.push(rootSymbol);
+    ctx.exports.push({
+      name: rootName,
+      kind: ASTEngine.SymbolKind.Module,
+      range: rootSymbol.range,
+      visibility: "public"
+    });
+    const frameworks = this.detectFrameworks(ctx);
+    const patterns = this.detectPatterns(ctx);
+    const structural = this.structuralScores(ctx);
+    return {
+      symbols: ctx.symbols,
+      relationships: ctx.relationships,
+      imports: ctx.imports,
+      exports: ctx.exports,
+      errors: ctx.errors,
+      metadata: {
+        complexity: ctx.symbols.length + ctx.relationships.length,
+        linesOfCode: content.split("\n").length,
+        cyclomaticComplexity: 1,
+        framework: frameworks[0],
+        patterns,
+        detectedFrameworks: frameworks,
+        frameworkPatterns: [],
+        architecturalInsights: this.insights(ctx),
+        architecturalScore: structural.dataModelingScore,
+        codeQuality: structural.dataModelingScore >= 90 ? "Excellent" : structural.dataModelingScore >= 70 ? "Good" : "Fair",
+        hasTypeInference: false,
+        hasFrameworkIntelligence: true,
+        dataModelingScore: structural.dataModelingScore,
+        schemaValidationScore: structural.schemaValidationScore,
+        apiDesignScore: this.isApiSpec(ctx) ? 100 : 80,
+        analysisVersion: "4.0.0-pure-json-ast"
+      }
+    };
+  }
+  collectErrors(rootNode, ctx) {
+    const stack = [rootNode];
+    while (stack.length > 0) {
+      const node = stack.pop();
+      if (node.type === "ERROR" || node.isMissing) {
+        ctx.errors.push({
+          message: `Syntax ${node.type} detected in JSON AST.`,
+          range: this.nodeToRange(node),
+          severity: "warning"
+        });
+      }
+      const children = node.namedChildren ?? [];
+      for (let i = children.length - 1; i >= 0; i--) {
+        const child = children[i];
+        if (child) stack.push(child);
+      }
+    }
+  }
+  /**
+   * Two DOCUMENT-level preconditions, read in the pass that already visits every pair.
+   *
+   * Both exist because the pass-2 corpus probe found inheritance declared as ordinary
+   * object keys, and both are deliberately narrow. `implements` had been RULED on the
+   * ground that the grammar cannot express a supertype clause, and the corpus says
+   * otherwise: `dart-sdk`'s `lsp_meta_model.json` states 87 interface mix-ins and 66 class
+   * supertypes, and duckdb's serialization schemas state 200-odd superclasses. A grammar
+   * has no node type for a KEYWORD, which is the same unsound question this lane has now
+   * had to retract six times.
+   *
+   * What keeps this from firing everywhere is that both shapes are announced by the
+   * document before any key is interpreted:
+   *
+   *   - LSP's meta-model uses `{"kind":"reference","name":X}`, a discriminated union for
+   *     "this is a named type". Two documents in the admitted population contain one, and
+   *     only one of them states inheritance. So the `name` key of an arbitrary JSON object
+   *     is never read as a type declaration.
+   *   - duckdb's schemas declare a C++ class with a `class` string. Twenty-one documents,
+   *     all duckdb.
+   *
+   * The measurement that would overturn this: a corpus document that states a supertype or
+   * an interface mix-in in a shape carrying neither marker. 0 occurrences over 11,713
+   * files, which is what `validation/m14/fixtures/json/inheritance-probe.ts` reports.
+   *
+   * It is folded into `collectSchemaFacts` rather than given its own walk, and the reason is
+   * measured. `otp`'s adversarial `json_SUITE_data/n_structure_open_array_object.json` is 50,000
+   * unclosed `[` — the grammar recovers it as an ERROR root with 200,000 children — and every
+   * extra full-tree walk over that shape costs ~100 s on top of a 249 s baseline, because
+   * `namedChild(i)` is not O(1) in this binding. Two walks became one.
+   */
+  noteDocumentConventions(key, value, ctx) {
+    if (value?.type !== "string") return;
+    if (key === "kind") {
+      if (this.stripQuotes(value.text) === "reference") ctx.usesReferenceLiterals = true;
+      return;
+    }
+    if (key !== "class" || ctx.usesClassDeclarations) return;
+    const declared = this.stripQuotes(value.text);
+    if (this.isIdentifierText(declared)) ctx.usesClassDeclarations = true;
+  }
+  isIdentifierText(text) {
+    const first = text[0];
+    if (!(first >= "a" && first <= "z" || first >= "A" && first <= "Z" || first === "_")) return false;
+    for (let i = 1; i < text.length; i++) {
+      const c = text[i];
+      const ok = c >= "a" && c <= "z" || c >= "A" && c <= "Z" || c >= "0" && c <= "9" || c === "_";
+      if (!ok) return false;
+    }
+    return true;
+  }
+  /**
+   * Collect schema metadata before symbol extraction so `required` is based on
+   * the actual sibling array, not on a key-name convention. Each object is
+   * visited once, so this pass is O(number of AST nodes).
+   */
+  collectSchemaFacts(rootNode, ctx) {
+    const stack = [{ node: rootNode, parentPath: ctx.rootName, parentName: ctx.rootName }];
+    while (stack.length > 0) {
+      const { node, parentPath } = stack.pop();
+      if (node.type === "document") {
+        this.pushTopLevelValues(stack, node, parentPath, ctx.rootName);
+        continue;
+      }
+      if (node.type === "object") {
+        const schemaKeys = /* @__PURE__ */ new Set();
+        let requiredNames;
+        for (const pair of node.namedChildren ?? []) {
+          if (pair?.type !== "pair") continue;
+          const key = this.keyText(pair);
+          const value = pair.childForFieldName("value");
+          if (!key) continue;
+          this.noteDocumentConventions(key, value, ctx);
+          if (value?.type === "string" && (key === "$id" || key === "$anchor")) {
+            const declared = this.stripQuotes(String(value.text ?? ""));
+            if (declared.length > 0) {
+              if (key === "$id") {
+                const base = this.withoutEmptyFragment(declared);
+                if (!ctx.documentIds.has(base)) ctx.documentIds.set(base, parentPath);
+              } else {
+                const paths = ctx.documentAnchors.get(declared);
+                if (paths) paths.push(parentPath);
+                else ctx.documentAnchors.set(declared, [parentPath]);
+              }
+            }
+          }
+          schemaKeys.add(key);
+          if (key === "required" && value?.type === "array") {
+            const required = /* @__PURE__ */ new Set();
+            for (const item of value.namedChildren ?? []) {
+              if (item?.type === "string") required.add(this.stripQuotes(item.text));
+            }
+            if (required.size > 0) requiredNames = required;
+          }
+          if (value?.type === "object") stack.push({ node: value, parentPath: this.childPath(parentPath, key), parentName: key });
+          else if (value?.type === "array") stack.push({ node: value, parentPath: this.childPath(parentPath, key), parentName: key });
+        }
+        let schemaMatches = 0;
+        for (const key of schemaKeys) {
+          if (key === "$schema" || key === "type" || key === "properties" || key === "required" || key === "items" || key === "definitions" || key === "$defs" || key === "additionalProperties") schemaMatches++;
+        }
+        if (requiredNames) {
+          const requiredOwner = schemaKeys.has("properties") ? this.childPath(parentPath, "properties") : parentPath;
+          ctx.requiredByObject.set(requiredOwner, requiredNames);
+        }
+        if (schemaMatches >= 2) ctx.schemaObjects.add(parentPath);
+        continue;
+      }
+      if (node.type === "array") this.pushArrayChildren(stack, node, parentPath, ctx.rootName, ctx.rootName);
+    }
+  }
+  extractSymbols(rootNode, ctx) {
+    const stack = [{ node: rootNode, parentPath: ctx.rootName, parentName: ctx.rootName }];
+    while (stack.length > 0) {
+      const frame = stack.pop();
+      const { node, parentPath, parentName } = frame;
+      if (node.type === "document") {
+        this.pushTopLevelValues(stack, node, parentPath, parentName);
+        continue;
+      }
+      if (node.type === "object") {
+        this.updateDepth(ctx, parentPath);
+        if (frame.emitObject) this.addArrayObjectSymbol(ctx, node, parentPath, parentName);
+        this.recordTypeDeclaration(node, parentPath, ctx);
+        this.pushNamedChildren(stack, node, parentPath, parentName, frame.duplicateKeys ?? /* @__PURE__ */ new Map());
+        continue;
+      }
+      if (node.type === "array") {
+        ctx.arrayCount++;
+        ctx.hasArrays = true;
+        if (frame.emitObject) this.addArrayElementSymbol(ctx, node, parentPath, parentName);
+        this.pushArrayChildren(stack, node, parentPath, parentName, ctx.rootName);
+        continue;
+      }
+      if (node.type !== "pair") continue;
+      const key = this.keyText(node);
+      const value = node.childForFieldName("value");
+      if (!key || !value) continue;
+      if (frame.duplicateKeys && key.length > 0) {
+        const line = node.startPosition.row + 1;
+        const prior = frame.duplicateKeys.get(key);
+        if (prior === void 0) frame.duplicateKeys.set(key, line);
+        else
+          ctx.overrideCandidates.push({
+            ownerName: parentName,
+            ownerPath: parentPath,
+            key,
+            targetPath: this.childPath(parentPath, key),
+            line,
+            overridesLine: prior
+          });
+      }
+      const path = this.childPath(parentPath, key);
+      const valueType = this.valueType(value);
+      const kind = valueType === "object" ? ASTEngine.SymbolKind.Class : ASTEngine.SymbolKind.Property;
+      const symbol = {
+        name: key,
+        kind,
+        qualifiedName: path,
+        range: this.nodeToRange(node),
+        ownerName: parentName,
+        ownerKind: parentPath === ctx.rootName ? ASTEngine.SymbolKind.Module : ASTEngine.SymbolKind.Class,
+        scope: parentPath,
+        visibility: "public",
+        returnType: valueType,
+        metadata: {
+          jsonSpecific: true,
+          nodeType: node.type,
+          valueType,
+          fullPath: path,
+          isArray: valueType === "array",
+          isObject: valueType === "object",
+          isRequired: this.isRequired(ctx, parentPath, key),
+          hasValidation: this.hasValidation(ctx, key, value),
+          isReference: this.isReference(key, value),
+          refPath: this.referencePath(key, value),
+          isApiEndpoint: this.isApiEndpoint(key, value),
+          depth: this.pathDepth(path, ctx.rootName)
+        }
+      };
+      if (ctx.emittedPaths.has(path)) continue;
+      ctx.emittedPaths.add(path);
+      this.addSymbol(ctx, symbol);
+      if (valueType === "null") ctx.hasNullValues = true;
+      if (valueType === "boolean") ctx.hasBooleanValues = true;
+      if (symbol.metadata.isReference) ctx.referenceSymbols.push(symbol);
+      if (symbol.metadata.hasValidation) ctx.validationSymbols.push(symbol);
+      if (symbol.metadata.isApiEndpoint) ctx.apiEndpointSymbols.push(symbol);
+      if (isDependencyContainerPath(parentPath)) {
+        ctx.dependencySymbols.push(symbol);
+        if (value.type === "string") {
+          const range = this.stripQuotes(String(value.text ?? ""));
+          if (range.length > 0) ctx.dependencyVersions.set(path, range);
+        }
+      }
+      if (value.type === "object" || value.type === "array") stack.push({ node: value, parentPath: path, parentName: key });
+    }
+  }
+  /**
+   * INHERITANCE DECLARED AS ORDINARY OBJECT KEYS — the corpus measurement that retracted
+   * this lane's `implements` ruling and found `extends` incomplete.
+   *
+   * `implements` was ruled on a grammar inventory ("the grammar produced 20 distinct node
+   * types across the corpus and NONE expresses it") and the corpus says otherwise. Two
+   * documents in 11,713 declare types and state their supertypes:
+   *
+   *   dart-sdk/…/lsp_meta_model.json — the Language Server Protocol's own serialisation of
+   *     its type declarations. 66 structures carry
+   *       "extends": [{"kind":"reference","name":"TextDocumentPositionParams"}]
+   *     and 87 carry
+   *       "mixins":  [{"kind":"reference","name":"WorkDoneProgressParams"}, …]
+   *     `mixins` names the TypeScript INTERFACES a class mixes in, which is `implements`
+   *     and nothing else: in TypeScript an interface carries no implementation, so there is
+   *     nothing else for the word to mean.
+   *
+   *   duckdb/src/include/duckdb/storage/serialization/*.json — serialisation schemas for
+   *     C++ classes. `{ "class": "NotNullConstraint", "base": "Constraint", … }`: `class`
+   *     declares the type, `base` names its superclass, and every superclass named is
+   *     declared in the same file.
+   *
+   * Two shapes are declined, and the corpus says why:
+   *
+   *   - A member descriptor. duckdb writes `{ "id": 200, "name": "info", "type":
+   *     "AlterInfo*", "base": "ParseInfo" }` — a FIELD whose C++ class derives from
+   *     `ParseInfo`. It is not a type declaration, and 16 such statements name a target the
+   *     document does not declare. The rule requires a `class` marker, which a member
+   *     descriptor does not carry, so all 16 are declined by the marker rather than by a
+   *     name list.
+   *   - `"parent"` and a non-string `base`. vega's data files carry `"parent": <number>` on
+   *     251 pairs; a number is not a type. The value must be a STRING.
+   *
+   * Confidence is 1.0 for `extends` and 0.9 for `implements`, and the difference is the
+   * honest one: a declared supertype is read structurally in both cases, but the mapping of
+   * LSP's word `mixins` onto the ontology's `implements` is a NAMING decision, not a parse
+   * fact. It therefore carries `reasonCode`, which is what the honesty contract §4 asks of
+   * anything below the deterministic threshold.
+   */
+  recordTypeDeclaration(node, path, ctx) {
+    const index = this.objectKeyIndex(node);
+    if (this.referenceLiteralName(index) !== void 0) return;
+    const className = ctx.usesClassDeclarations ? this.stringPairValue(index, "class") : void 0;
+    const named = className ?? (ctx.usesReferenceLiterals ? this.lspDeclaredName(index) : void 0);
+    if (named !== void 0 && named.length > 0 && !ctx.typeDeclarations.has(named)) ctx.typeDeclarations.set(named, path);
+    if (named === void 0 || named.length === 0) return;
+    if (className !== void 0) {
+      const base = this.stringPairValue(index, "base");
+      if (base !== void 0 && base.length > 0) {
+        ctx.inheritanceCandidates.push({
+          source: path,
+          target: base,
+          key: "base",
+          form: "duckdb_base_class_name",
+          label: "extends",
+          line: this.pairLine(index, "base")
+        });
+      }
+      return;
+    }
+    for (const key of LSP_INHERITANCE_KEYS) {
+      const value = this.pairValue(index, key);
+      if (value?.type !== "array") continue;
+      const label = key === "mixins" || key === "implements" ? "implements" : "extends";
+      const items = (value.namedChildren ?? []).filter((c) => c.type !== "[");
+      for (const item of items) {
+        const reference = this.referenceLiteralName(this.objectKeyIndex(item));
+        if (reference === void 0) continue;
+        ctx.inheritanceCandidates.push({
+          source: path,
+          target: reference,
+          key,
+          form: "lsp_reference_literal",
+          label,
+          line: item.startPosition.row + 1
+        });
+      }
+    }
+  }
+  /**
+   * Resolve the candidates against the declarations collected in the same walk and emit.
+   *
+   * A candidate whose target this document never declares produces NO edge. Measured: 16 of
+   * the supertype statements name a type declared in a sibling file, and an edge to a symbol
+   * this file does not contain is exactly the fabrication the ontology workstream calls the
+   * most expensive mistake available.
+   *
+   * The endpoints are QUALIFIED PATHS, which is the lane's established convention for a
+   * relation between two declarations rather than between two keys — the same choice
+   * `references` makes, and for the same reason: the thing that inherits is an object in the
+   * document, not a key. It has a measured cost, declared in the doc: these endpoints bind by
+   * qualified name and not by bare name, so the store cannot resolve them by name.
+   */
+  extractDeclaredInheritance(ctx) {
+    for (const c of ctx.inheritanceCandidates) {
+      const targetPath = ctx.typeDeclarations.get(c.target);
+      if (targetPath === void 0) continue;
+      if (targetPath === c.source) continue;
+      ctx.relationships.push({
+        source: c.source,
+        target: targetPath,
+        type: c.label === "implements" ? ASTEngine.RelationshipType.Implements : ASTEngine.RelationshipType.Extends,
+        confidence: c.label === "implements" ? 0.9 : 1,
+        line_number: c.line,
+        metadata: {
+          jsonSpecific: true,
+          inheritanceForm: c.form,
+          declarationKey: c.key,
+          declaredType: c.target,
+          reasonCode: c.label === "implements" ? "declared_interface_mixin" : "declared_supertype",
+          evidenceClass: "structural",
+          endpoints: "qualified_path"
+        }
+      });
+    }
+  }
+  /** An LSP reference literal: an object with `kind` == "reference" and a `name` string. */
+  referenceLiteralName(index) {
+    if (this.stringPairValue(index, "kind") !== "reference") return void 0;
+    const name = this.stringPairValue(index, "name");
+    return name !== void 0 && name.length > 0 ? name : void 0;
+  }
+  /**
+   * The name an LSP-style object declares ITSELF under, or undefined when the object is not a
+   * type declaration.
+   *
+   * Two keys name the type (`name` for a structure or an enumeration, `typeName` for a
+   * request or a notification) and one of five makes the object a TYPE rather than one of its
+   * members: `properties`, `values`, `extends`, `mixins`, `implements`. A property descriptor
+   * (`{"name":"textDocument","type":{"kind":"reference",…}}`) has a `name` and none of those,
+   * so it is declined — and it sits inside a declaration in the same file, which is what makes
+   * the test necessary rather than tidy.
+   */
+  lspDeclaredName(index) {
+    if (!index.has("properties") && !index.has("values") && !index.has("extends") && !index.has("mixins") && !index.has("implements")) {
+      return void 0;
+    }
+    return this.stringPairValue(index, "name") ?? this.stringPairValue(index, "typeName");
+  }
+  /** A key -> pair index for one object, built once. */
+  objectKeyIndex(node) {
+    const index = /* @__PURE__ */ new Map();
+    const children = node?.namedChildren ?? [];
+    for (let i = 0; i < children.length; i++) {
+      const child = children[i];
+      if (child?.type !== "pair") continue;
+      const key = this.keyText(child);
+      if (key.length === 0) continue;
+      if (!index.has(key)) index.set(key, child);
+    }
+    return index;
+  }
+  pairValue(index, key) {
+    const pair = index.get(key);
+    return pair ? pair.childForFieldName("value") : void 0;
+  }
+  stringPairValue(index, key) {
+    const value = this.pairValue(index, key);
+    if (value?.type !== "string") return void 0;
+    const text = this.stripQuotes(String(value.text ?? ""));
+    return text.length > 0 ? text : void 0;
+  }
+  pairLine(index, key) {
+    const pair = index.get(key);
+    return pair ? pair.startPosition.row + 1 : 0;
+  }
+  addSymbol(ctx, symbol) {
+    ctx.symbols.push(symbol);
+    ctx.symbolMap.set(symbol.name, symbol);
+    const fullPath = symbol.metadata?.fullPath;
+    if (fullPath) ctx.symbolMap.set(fullPath, symbol);
+    if (symbol.kind === ASTEngine.SymbolKind.Class) ctx.objectCount++;
+    if (symbol.kind === ASTEngine.SymbolKind.Property) ctx.propertyCount++;
+  }
+  extractRelationships(ctx) {
+    for (const symbol of ctx.symbols) {
+      if (symbol.ownerName) {
+        ctx.relationships.push({
+          source: this.ownerPathOf(symbol),
+          target: String(symbol.qualifiedName || symbol.name),
+          type: ASTEngine.RelationshipType.Contains,
+          confidence: 1,
+          line_number: this.declLine(symbol),
+          metadata: {
+            fullPath: symbol.metadata?.fullPath || "",
+            ownerName: symbol.ownerName,
+            endpoints: "qualified_path"
+          }
+        });
+      }
+    }
+    for (const ref of ctx.referenceSymbols) {
+      const refPath = ref.metadata?.refPath;
+      if (!refPath) continue;
+      const declaredIdentity = this.documentDeclaredIdentity(ctx, refPath);
+      const target = declaredIdentity ?? this.referenceTarget(ctx, refPath);
+      const source = String(ref.metadata?.fullPath || ref.name);
+      const fileCandidate = this.fileRefCandidate(ctx, refPath);
+      const claimedFile = fileCandidate !== null && this.projectCarriesFile(ctx, fileCandidate) ? fileCandidate : null;
+      if (this.isFileNamingRef(refPath)) {
+        ctx.relationships.push({
+          source,
+          target: refPath,
+          type: ASTEngine.RelationshipType.Imports,
+          confidence: 1,
+          line_number: this.declLine(ref),
+          metadata: {
+            jsonSpecific: true,
+            importForm: "json_schema_ref",
+            resolvedPath: false,
+            // the dependency this edge asserts, in the spelling the project's own file list uses
+            // — or, where the project does not carry it, the external claim that says so. The
+            // fallback is not optional: an `imports` edge with no claim at all is UNRESOLVED and
+            // counts against the lane, and "the project does not carry this file" is a statement,
+            // not a gap. A path-shaped target carrying `isExternal` is UNVERIFIABLE by the
+            // arbiter's owner lookup by design (`verifyExternalClaim` refuses to read a stem as an
+            // owner — a rule fixed in `5a611de4b`), which is exactly right for it.
+            ...claimedFile ? { importProjectFile: claimedFile } : { isExternal: true },
+            evidenceClass: "structural"
+          }
+        });
+      }
+      ctx.relationships.push({
+        source,
+        target,
+        type: ASTEngine.RelationshipType.References,
+        confidence: target === refPath ? 0.8 : 1,
+        line_number: this.declLine(ref),
+        metadata: {
+          relationshipType: "json_reference",
+          refPath,
+          // THE EXTERNAL CLAIM, and it is a claim about the CORPUS, so it may only be made where
+          // the shape says the target is outside this document. A LOCAL POINTER never is: `#`
+          // (the root) and `#/a/b` (a location in this file) are answered by this file. Before
+          // this test, `#` was marked external by `!refPath.startsWith("#/")` — nine edges in one
+          // vendored meta-schema — and a URI/path-shaped target can never be verified by the
+          // gate's owner lookup, so those nine made the lane's verdict unreadable: the arbiter
+          // returns a branch that prints no amb/unres/edges totals (measured, 2026-10-09).
+          // A pointer that names a location this document does not publish is a BROKEN pointer,
+          // not an external one; `reasonCode` says exactly that and the confidence carries it.
+          // A `$ref` that names a FILE carries the file claim instead, on both labels, so the two
+          // rows for one dependency are adjudicated the same way — and where the project does not
+          // carry the file, BOTH labels carry the external claim, so one dependency is never
+          // adjudicated two ways.
+          // AN IDENTITY THE DOCUMENT DECLARES IS NOT EXTERNAL EITHER: the third same-document
+          // form. `$id`/`$anchor` declarations are what make the target a declaration HERE, so the
+          // corpus claim that made the edge `ext?` would be a claim this file refutes.
+          ...claimedFile ? { importProjectFile: claimedFile } : { isExternal: !this.isLocalPointer(refPath) && declaredIdentity === null },
+          // Honesty contract §4 point 1: anything below 1.0 carries a machine-readable code.
+          // The 0.8 case is exactly one thing — the pointer names a location this document
+          // does not declare — so the code says so, and the 1.0 case says the opposite.
+          reasonCode: target === refPath ? "ref_target_not_declared_in_document" : "json_schema_ref",
+          evidenceClass: "structural"
+        }
+      });
+    }
+    for (const endpoint of ctx.apiEndpointSymbols) {
+      ctx.relationships.push({
+        // QUALIFIED PATHS on both ends. An endpoint is a KEY of the `paths` object, so it has
+        // a position in the document and a path exists for it — `endpoint.qualifiedName` IS
+        // that path, and `endpoint.scope` is the `paths` object's own path. This is what
+        // separates this site from a manifest dependency's `uses`, whose target is an npm
+        // package name and genuinely has no position: see `classifyUnresolved` in
+        // validation/m14/fixtures/json/namespace-orphan-probe.ts, which reads the two apart
+        // from the discriminator each site publishes.
+        source: endpoint.scope || endpoint.ownerName || ctx.rootName,
+        target: endpoint.qualifiedName || endpoint.name,
+        type: ASTEngine.RelationshipType.Uses,
+        confidence: 0.8,
+        line_number: this.declLine(endpoint),
+        metadata: {
+          relationshipType: "json_api_endpoint",
+          // Honesty contract §4 point 1. The endpoints are a fact about the tree; the claim
+          // that declaring an HTTP method in a `paths` entry is a USE rather than mere
+          // containment is a reading of the OpenAPI document shape, so it is 0.8 with a code.
+          reasonCode: "openapi_path_entry_declares_http_method",
+          evidenceClass: "usage_contextual",
+          endpoints: "qualified_path"
+        }
+      });
+    }
+  }
+  /**
+  * The OWNER's qualified path, recovered from a child's own path — or the bare `ownerName`
+  * when the path does not reduce to one.
+  *
+  * Two shapes occur and both are handled by string surgery on the child's path, because the
+  * path IS the child's `qualifiedName` in this analyzer:
+  *
+  *   an object property — path `ar.dashboard.analytics.unknown`, name `unknown`; the owner is
+  *   everything before the final `.unknown`, i.e. `ar.dashboard.analytics`.
+  *
+  *   an array item — path `ar.items[0]`, name `ar.items[0]` (see `arrayItemName`: an item is
+  *   named after the array that holds it plus its index). There is no `.` immediately before
+  *   the name, so the `.`-suffix test misses it and the `[i]` suffix test catches it, leaving
+  *   `ar.items`.
+  *
+  * The fallback returns `ownerName` unchanged, which is what the previous version always
+  * emitted. That direction was chosen on purpose: a path can only ever resolve MORE than a
+  * bare name (strategy 1 exact-matches it), so an unreducible path degrades to today's
+  * behaviour and never to a worse one.
+  */
+  ownerPathOf(symbol) {
+    const owner = String(symbol.ownerName ?? "");
+    if (owner === "") return owner;
+    const p = String(symbol.qualifiedName ?? "");
+    const n = String(symbol.name ?? "");
+    if (n === "" || p === "") return owner;
+    if (symbol.metadata?.isArrayItem === true) {
+      const bracket = p.lastIndexOf("[");
+      if (bracket > 0) return p.slice(0, bracket);
+      return owner;
+    }
+    if (p.length > n.length && p.endsWith(`.${n}`)) return p.slice(0, p.length - n.length - 1);
+    if (p.length > n.length && p.endsWith(n)) return p.slice(0, p.length - n.length);
+    return owner;
+  }
+  /**
+   * What a manifest PUBLISHES, as `exports` edges.
+   *
+   * The lane's first ruling excluded `exports` on a grammar inventory — "no
+   * `export_statement` node" — and that is the SAME unsound reasoning that produced
+   * the wrong `imports` ruling: a grammar cannot see a CONVENTION, and a Node
+   * manifest's `exports` field is a convention expressed as ordinary object keys. The
+   * audit found 1 of 36 manifests carrying `exports` and 1 carrying `main`, so the
+   * mass is small and the principle is not, and the type is emitted.
+   *
+   * A published entry point IS an export, and each of its names is exported: a
+   * subpath key for `exports`, the field name for `main`, the command name for `bin`.
+   *
+   * Two silent failures lived in this function before it worked, and both are worth
+   * recording because neither would ever have been noticed by reading it. It first
+   * reached for a `__node` property nothing set, and then iterated the `document`
+   * WRAPPER's children when the top-level `pair`s are one level down inside the root
+   * `object`. Both type-check, both compile, both do nothing. The only reason this
+   * version works is that it was measured — 24 edges on svelte's manifest, and 0 when
+   * either guard was wrong.
+   */
+  extractManifestExports(ctx) {
+    if (!this.fileEndsWith(ctx.filePath, "package.json")) return;
+    const document = ctx.rootNode;
+    if (document.type !== "document") return;
+    const rootObject = document.namedChildren?.find((c) => c.type === "object");
+    if (!rootObject) return;
+    const emit = (name, line, parent) => {
+      if (name.length === 0) return;
+      const target = [ctx.rootName, ...parent ? [parent] : [], name].join(".");
+      ctx.relationships.push({
+        source: ctx.rootName,
+        target,
+        type: ASTEngine.RelationshipType.Exports,
+        confidence: 1,
+        line_number: line,
+        metadata: { jsonSpecific: true, exportForm: "manifest_entry_point", evidenceClass: "structural" }
+      });
+    };
+    for (const pair of rootObject.namedChildren ?? []) {
+      if (pair?.type !== "pair") continue;
+      const key = this.keyText(pair);
+      const value = pair.childForFieldName("value");
+      if (!key || !value) continue;
+      const line = pair.startPosition.row + 1;
+      if (key === "main") {
+        if (value.type === "string") emit("main", line);
+      } else if (key === "bin") {
+        if (value.type === "string") emit("bin", line);
+        else {
+          for (const binPair of value.namedChildren ?? []) {
+            if (binPair?.type !== "pair") continue;
+            const binName = this.keyText(binPair);
+            if (binName) emit(binName, binPair.startPosition.row + 1, "bin");
+          }
+        }
+      } else if (key === "exports") {
+        if (value.type === "string") emit("exports", line);
+        else {
+          for (const sub of value.namedChildren ?? []) {
+            if (sub?.type !== "pair") continue;
+            const subPath = this.keyText(sub);
+            if (subPath) emit(subPath, sub.startPosition.row + 1, "exports");
+          }
+        }
+      }
+    }
+  }
+  /**
+   * JSON Schema COMPOSITION, as `extends`.
+   *
+   * `allOf` means "must satisfy ALL of these" — a superset-of relationship, and the
+   * only schema keyword that means one. `anyOf` and `oneOf` are ALTERNATIVES and have
+   * no ontology type, so they are correctly emitted as nothing beyond the `references`
+   * their `$ref`s already produce.
+   *
+   * This was ruled out twice on the same wrong reasoning, and the pattern is now
+   * recognisable: a grammar inventory says the PARSER cannot express a construct, which
+   * is not the same as the LANGUAGE lacking one. `allOf` is a keyword, and a grammar
+   * has no node type for a keyword any more than it has one for a manifest's `exports`
+   * field. Measured over the corpus: **1,226 `allOf` `$ref`s** against 88 `anyOf` and
+   * 89 `oneOf`, which is the shape the reading predicts — composition is the common
+   * case and alternatives are rare.
+   */
+  extractSchemaComposition(ctx) {
+    for (const ref of ctx.referenceSymbols) {
+      const fullPath = ref.metadata?.fullPath;
+      if (!fullPath) continue;
+      let parent = fullPath.slice(0, fullPath.lastIndexOf("."));
+      const bracket = parent.lastIndexOf("[");
+      if (bracket > 0 && parent.endsWith("]")) parent = parent.slice(0, bracket);
+      if (!parent.endsWith(".allOf")) continue;
+      const composer = parent.length > ".allOf".length ? parent.slice(0, parent.length - ".allOf".length) : ctx.rootName;
+      const refPath = ref.metadata?.refPath;
+      if (!refPath) continue;
+      const isLocal = refPath.startsWith("#/");
+      const isSiblingFile = !isLocal && this.isFileNamingRef(refPath);
+      if (!isLocal && !isSiblingFile) continue;
+      const target = isLocal ? this.referenceTarget(ctx, refPath) : refPath;
+      const siblingFile = isSiblingFile ? this.fileRefCandidate(ctx, refPath) : null;
+      const claimedSibling = siblingFile !== null && this.projectCarriesFile(ctx, siblingFile) ? siblingFile : null;
+      ctx.relationships.push({
+        source: composer,
+        target,
+        type: ASTEngine.RelationshipType.Extends,
+        confidence: 1,
+        line_number: this.declLine(ref),
+        metadata: {
+          jsonSpecific: true,
+          composition: "allOf",
+          compositionSite: parent,
+          refForm: isLocal ? "intra_document" : "sibling_file",
+          resolvedPath: isLocal,
+          ...claimedSibling ? { importProjectFile: claimedSibling } : isSiblingFile ? { isExternal: true } : {},
+          note: "allOf is a superset-of relationship; anyOf/oneOf are alternatives and emit only `references`",
+          reasonCode: "json_schema_all_of",
+          evidenceClass: "structural",
+          endpoints: "qualified_path"
+        }
+      });
+    }
+  }
+  extractPackageDependencies(ctx) {
+    if (!this.fileEndsWith(ctx.filePath, "package.json") && !this.fileEndsWith(ctx.filePath, "composer.json")) return;
+    for (const dependency of ctx.dependencySymbols) {
+      ctx.imports.push({
+        module: dependency.name,
+        symbols: [],
+        range: dependency.range,
+        type: "dependency",
+        resolvedPath: "package-manager"
+      });
+      ctx.relationships.push({
+        source: ctx.rootName,
+        target: String(dependency.qualifiedName ?? dependency.name),
+        type: ASTEngine.RelationshipType.Uses,
+        confidence: 1,
+        line_number: dependency.range?.startLine ?? 0,
+        metadata: {
+          relationshipType: "package_dependency",
+          package: dependency.name,
+          version: this.dependencyVersion(ctx, dependency)
+        }
+      });
+    }
+  }
+  /**
+   * An npm script that runs a SIBLING script, as `calls`.
+   *
+   * `calls` was ruled out for this lane twice, on a grammar inventory: the JSON
+   * grammar has no node type for a function, so it has none for an invocation either.
+   * That is the same unsound question that produced the wrong `imports`, `exports` and
+   * `extends` rulings, and the corpus settles it. A `package.json` `scripts` object
+   * declares its entries as ordinary keys, so both endpoints of the relation are
+   * symbols IN THE SAME FILE, and a command string naming one of them is an
+   * invocation of it:
+   *
+   *   "scripts": { "pretest": "npm run compile", "compile": "tsc -p ." }
+   *
+   * `pretest` calls `compile`, and both names resolve. This is not a name-match guess
+   * across files — the callee must be a key of the SAME `scripts` object, which is the
+   * only condition under which the edge can be checked at all.
+   *
+   * Three things are declined rather than left silent, each because emitting them would
+   * be a fabricated edge:
+   *
+   *   - `npm run <name>` where `<name>` is NOT a key of this `scripts` object. The
+   *     callee is then a binary, a workspace script in another package, or nothing;
+   *     `package.json` does not say, so the edge would name a symbol that is not there.
+   *     Measured separately by `validation/m14/fixtures/json/probes.ts` so the
+   *     undercount is visible instead of assumed.
+   *   - a script invoking ITSELF. npm rejects it, and a self-edge carries no order.
+   *   - npm's IMPLICIT lifecycle hooks (`pre<script>` / `post<script>` around any
+   *     script). npm runs them without the command naming them, which is real
+   *     behaviour and is NOT an explicit invocation, so emitting it would attribute an
+   *     edge to a name the file never wrote in that position.
+   *
+   * Confidence is 0.8, not 1, and the reason is carried in `reasonCode`: the two
+   * endpoints are structural facts but the LINK is read out of a string value by a
+   * known-CLI convention, which is exactly the class the honesty contract §4 requires
+   * to be below the deterministic threshold and countable.
+   */
+  /**
+   * A key declared twice in one object, as `overrides`.
+   *
+   * `overrides` was ruled out for this lane on a grammar inventory — the JSON grammar
+   * has no node type for a redefinition — which is the unsound question this lane has
+   * now had to retract three times (`imports`, `exports`, `extends`, and `calls` on the
+   * same corpus evidence). The construct is measurable and it occurs: 21 NAMED
+   * duplicate keys across 11 of 11,713 admitted files, e.g.
+   * dart-sdk/pkg/front_end/test/language_versioning/data/
+   * package_default_version_is_wrong_2/.dart_tool/package_config.json:8 declaring
+   * `languageVersion` twice, and duckdb/data/json/11152.json.
+   *
+   * The edge shape is the BASH lane's, deliberately, because it is the only shape that
+   * works when both declarations share one name: source is the OWNER symbol, target is
+   * the repeated key, and `overridesLine` carries the PRIOR declaration's line so the
+   * replacement is readable without re-deriving it.
+   *
+   * Both endpoints are QUALIFIED PATHS, like every other type on this lane. It used to be
+   * the last type emitting bare names, and the bare form was ambiguous on EVERY corpus
+   * edge: measured over the whole admitted population, 22 of 22 targets matched more than
+   * one published symbol by name, against 14 of 22 by path. The 8 that become unique are
+   * real gains — a bare `rec2` names both elements of an array and a bare `1` names four
+   * keys, so the bare endpoint could bind to a declaration in a DIFFERENT object. The 14
+   * that stay ambiguous are the two declarations of ONE key sharing a name AND a path,
+   * which is declined below and carried in `overridesLine`. The names are retained in
+   * metadata as `ownerName`/`key`, where they read as names.
+   *
+   * `contains` already emits a row for each declaration, so the pair exists independently
+   * of this edge.
+   *
+   * Three things are declined, each because the edge would assert something the file
+   * does not say:
+   *
+   *   - The same key in two DIFFERENT objects of one file. A key is unique only within
+   *     its object, so this is not a redefinition, and it is the corpus's dominant shape
+   *     (120,174 occurrences across 7,679 files against 21 real duplicates). Emitting
+   *     it would have been ~5,700 false positives.
+   *   - An EMPTY key. 10 occurrences across 5 files, every one a document the grammar
+   *     already recovered with ERROR nodes; an empty key is not a named member.
+   *   - Any attempt to name the two declarations apart. They share a name AND a
+   *     qualified path, so distinguishing them would mean minting a symbol the document
+   *     does not declare. The line metadata carries the distinction instead.
+   *
+   * Confidence is 1: two `pair` nodes with one key inside one `object` is a fact about
+   * the parse tree, read at the same place the symbol is created.
+   */
+  extractDuplicateKeyOverrides(ctx) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const c of ctx.overrideCandidates) {
+      const identity = `${c.ownerPath}\0${c.key}`;
+      if (seen.has(identity)) continue;
+      seen.add(identity);
+      ctx.relationships.push({
+        source: c.ownerPath,
+        target: c.targetPath,
+        type: ASTEngine.RelationshipType.Overrides,
+        confidence: 1,
+        line_number: c.line,
+        metadata: {
+          jsonSpecific: true,
+          redefinition: true,
+          overridesLine: c.overridesLine,
+          ownerName: c.ownerName,
+          key: c.key,
+          endpoints: "qualified_path",
+          evidenceClass: "structural"
+        }
+      });
+    }
+  }
+  extractNpmScriptCalls(ctx) {
+    if (!this.fileEndsWith(ctx.filePath, "package.json")) return;
+    const document = ctx.rootNode;
+    if (document.type !== "document") return;
+    const rootObject = document.namedChildren?.find((c) => c.type === "object");
+    if (!rootObject) return;
+    const scriptsObject = this.topLevelObjectValue(rootObject, "scripts");
+    if (!scriptsObject) return;
+    const declared = /* @__PURE__ */ new Map();
+    for (const pair of scriptsObject.namedChildren ?? []) {
+      if (pair?.type !== "pair") continue;
+      const key = this.keyText(pair);
+      if (key) declared.set(key, pair);
+    }
+    if (declared.size === 0) return;
+    const scriptsPath = this.childPath(ctx.rootName, "scripts");
+    for (const [name, pair] of declared) {
+      const value = pair.childForFieldName("value");
+      if (value?.type !== "string") continue;
+      for (const callee of this.npmRunTargets(this.stripQuotes(value.text))) {
+        if (callee === name) continue;
+        if (!declared.has(callee)) continue;
+        ctx.relationships.push({
+          source: this.childPath(scriptsPath, name),
+          target: this.childPath(scriptsPath, callee),
+          type: ASTEngine.RelationshipType.Calls,
+          confidence: 0.8,
+          line_number: pair.startPosition.row + 1,
+          metadata: {
+            jsonSpecific: true,
+            callForm: "npm_run_sibling_script",
+            evidenceClass: "usage_contextual",
+            reasonCode: "npm_run_sibling_script",
+            endpoints: "qualified_path",
+            scriptName: name,
+            calleeName: callee
+          }
+        });
+      }
+    }
+  }
+  /**
+   * The script names a command string invokes through a package runner.
+   *
+   * Tokenised with a character scan and no regex, because the lane's contract is zero
+   * regex literals in this file (`script/m12/json-contract-probe.ts` enforces it) and
+   * because a runner name is only meaningful as a whole token: `npm` inside `npx` or
+   * a path like `./scripts/npm` is not a runner. A QUOTED target is declined, because
+   * the quoting means the shell rewrote the argument and the file no longer states
+   * the name plainly.
+   */
+  npmRunTargets(command) {
+    const RUNNERS = ["npm", "pnpm", "yarn", "bun"];
+    const VERBS = ["run", "run-script", "run-s"];
+    const SEPARATORS = [" ", "	", "\n", "\r", ";", "&", "|", "(", ")", "<", ">"];
+    const tokens = [];
+    let current = "";
+    let quoted = false;
+    let inQuotes = false;
+    for (const ch of command) {
+      if (ch === '"') {
+        inQuotes = !inQuotes;
+        quoted = true;
+        continue;
+      }
+      if (!inQuotes && SEPARATORS.includes(ch)) {
+        if (current.length > 0) tokens.push({ text: current, quoted });
+        current = "";
+        quoted = false;
+        continue;
+      }
+      current += ch;
+    }
+    if (current.length > 0) tokens.push({ text: current, quoted });
+    const out = [];
+    for (let i = 0; i < tokens.length; i++) {
+      if (!RUNNERS.includes(tokens[i].text)) continue;
+      const verb = tokens[i + 1];
+      if (!verb || verb.quoted || !VERBS.includes(verb.text)) continue;
+      const target = tokens[i + 2];
+      if (!target || target.quoted) continue;
+      out.push(target.text);
+      i += 2;
+    }
+    return out;
+  }
+  /** The object value of a named top-level key, or undefined. */
+  topLevelObjectValue(rootObject, name) {
+    for (const pair of rootObject.namedChildren ?? []) {
+      if (pair?.type !== "pair") continue;
+      if (this.keyText(pair) !== name) continue;
+      const value = pair.childForFieldName("value");
+      if (value?.type === "object") return value;
+    }
+    return void 0;
+  }
+  dependencyVersion(ctx, dependency) {
+    const fullPath = String(dependency.metadata?.fullPath || "");
+    const recorded = ctx.dependencyVersions.get(fullPath);
+    if (recorded !== void 0) return recorded;
+    return "unspecified";
+  }
+  /**
+   * Does this `$ref` value name ANOTHER FILE rather than something inside this one?
+   *
+   * Three shapes, and they are genuinely different things: a local pointer (`#/a/b`)
+   * names a location in THIS document; a URL names a vocabulary (a JSON-Schema draft
+   * identifier); a relative path with a document extension names a FILE, and that is a
+   * dependency. Decided structurally — an extension and a path separator or a leading
+   * `./` — with no regex, so the lane's zero-regex contract holds.
+   */
+  /**
+   * DOES THE PROJECT CARRY THE FILE THIS EDGE DEPENDS ON? The precondition of the file claim.
+   *
+   * `candidate` is already project-relative and cannot escape the root (`fileRefCandidate` pops
+   * `..` and returns null when one would leave the project), so the join cannot address anything
+   * outside the project.
+   *
+   * ENOENT / ENOTDIR mean the project does not have it, and the claim is then NOT MADE — the
+   * arbiter would refute it, correctly, because the claim says the project has the file. ANY
+   * OTHER error means this check did not run rather than that the file is absent, and a claim is
+   * not dropped on a check that did not happen: those cases keep the claim, which is exactly the
+   * behaviour every measurement before this one recorded.
+   *
+   * This is a STAT, not a read. The lane's contract is that every decision comes from the TREE
+   * and that the file body is never scanned as text (`BD-regex`, enforced by
+   * `script/m12/json-contract-probe.ts`); asking the filesystem whether a path exists asserts
+   * nothing about that file's contents and adds no regular expression.
+   */
+  projectCarriesFile(ctx, candidate) {
+    const root = ctx.projectRoot;
+    if (typeof root !== "string" || root.length === 0) return false;
+    try {
+      return statSync(join(root, candidate)).isFile();
+    } catch (e) {
+      return !(e?.code === "ENOENT" || e?.code === "ENOTDIR");
+    }
+  }
+  isFileNamingRef(refPath) {
+    if (refPath.length === 0) return false;
+    if (refPath.startsWith("#/")) return false;
+    if (refPath.startsWith("http://") || refPath.startsWith("https://")) return false;
+    const DOCUMENT_EXTENSIONS = ["json", "jsonc", "json5", "yaml", "yml", "avsc", "avdl", "proto"];
+    const withoutFragment = refPath.split("#")[0];
+    const dot = withoutFragment.lastIndexOf(".");
+    if (dot < 0) return false;
+    const ext = withoutFragment.slice(dot + 1);
+    if (!DOCUMENT_EXTENSIONS.includes(ext)) return false;
+    return true;
+  }
+  /**
+   * A `$ref`'s TARGET, and a local pointer is a pointer INTO THIS DOCUMENT.
+   *
+   * The gate found the defect this fixes (`incoming-gate.ts json json 60`): nine `references`
+   * edges whose target was the literal string `#` and whose metadata said `isExternal: true`,
+   * all nine from one file — kubernetes' vendored draft-04 meta-schema
+   * (`.../gnostic-models/jsonschema/schema.json`), whose `definitions.schemaArray.items` is
+   * `{ "$ref": "#" }`. `#` is the JSON-Schema ROOT POINTER ("the schema itself"), so it is the
+   * most local reference a document can write, and BOTH rules below got it wrong for the same
+   * reason: they test `startsWith("#/")`, and a bare `#` is not that prefix.
+   *
+   *   the TARGET   fell through to the raw `#` — a string no symbol can be named, so the edge
+   *                named nothing. It now resolves to `ctx.rootName`, which IS the published
+   *                identity of the document root (the module symbol `analyze` pushes first), so
+   *                the pointer binds to the thing it points at.
+   *   the MARKER   (see the emission site) called it EXTERNAL, which is a claim about the corpus
+   *                that a pointer into the file's own document cannot support — the same
+   *                file-local-class-as-corpus-claim error the fsharp lane retired this week.
+   *
+   * Measured after: the gate reads 29 of 29 `references` resolved, `ext?` 0, `extFAIL` 0 — and
+   * the verdict, which had been returning a branch that prints NO totals, prints them again.
+   */
+  referenceTarget(ctx, refPath) {
+    if (refPath === "#") return ctx.rootName;
+    if (!refPath.startsWith("#/")) return refPath;
+    const local = [ctx.rootName, ...refPath.slice(2).split("/").map((seg) => this.decodePointerSegment(seg))].join(".");
+    return ctx.symbolMap.has(local) ? local : refPath;
+  }
+  /**
+   * A `$ref` THAT NAMES AN IDENTITY THIS DOCUMENT DECLARES — or `null`.
+   *
+   * This is the third form a `$ref` can take, and the one whose target was being published
+   * verbatim with a corpus claim it cannot support:
+   *
+   *   1  `#/a/b`    a JSON POINTER — a location in this document; `referenceTarget` answers it.
+   *   2  `x.json`   a SIBLING FILE — `imports`, with the project's file claim on both labels.
+   *   3  `<uri>`    an IDENTITY — `$id` declares a base URI for a schema resource and `$anchor`
+   *                 declares a fragment name inside one. JSON Schema resolves the reference
+   *                 against the declared base, and the declaration IS the object carrying the
+   *                 `$id`; this analyzer already publishes that object's qualified path.
+   *
+   * MEASURED (`validation/m14/fixtures/json/document-identity-census.ts`): 6 corpus `$ref`s in
+   * 2 repositories name an identity their own document declares; 4 of them were this lane's
+   * whole `ext?` class on `--repo=gql-graphql-mesh`.
+   *
+   * The returned path is the DECLARING OBJECT'S `qualifiedName`, i.e. production resolver
+   * strategy 1's exact key — never a basename stem — so this cannot mass-move edges into
+   * `collRes` the way a stem rebase would, and it mints no symbol.
+   *
+   * A fragment is accepted only where the base's resource really is where it lives: for an
+   * `$anchor`, the declaring object must BE the base object or sit UNDER it. A bare anchor name
+   * scopes nothing on its own, so a name declared in another resource of the same document is
+   * refused rather than guessed.
+   */
+  documentDeclaredIdentity(ctx, refPath) {
+    const hash = refPath.indexOf("#");
+    const base = this.withoutEmptyFragment(hash < 0 ? refPath : refPath.slice(0, hash));
+    if (base.length === 0) return null;
+    const declared = ctx.documentIds.get(base);
+    if (declared === void 0) return null;
+    const fragment = hash < 0 ? "" : refPath.slice(hash + 1);
+    if (fragment.length === 0) return declared;
+    if (fragment.startsWith("/")) return null;
+    const anchorPaths = ctx.documentAnchors.get(fragment);
+    if (!anchorPaths) return null;
+    const underBase = anchorPaths.find((p) => p === declared || p.startsWith(`${declared}.`));
+    return underBase ?? null;
+  }
+  /** One trailing empty fragment is not part of an identity: `…/schema` and `…/schema#` name the
+   *  same base URI (RFC 3986 §6.2.2), and `$id`/`$ref` use both spellings. */
+  withoutEmptyFragment(uri) {
+    return uri.endsWith("#") ? uri.slice(0, -1) : uri;
+  }
+  /** RFC 6901: within a pointer segment, `~1` is `/` and `~0` is `~`, decoded in that order. */
+  decodePointerSegment(segment) {
+    if (!segment.includes("~")) return segment;
+    let out = "";
+    for (let i = 0; i < segment.length; i++) {
+      if (segment[i] === "~" && i + 1 < segment.length) {
+        const next = segment[i + 1];
+        if (next === "0") {
+          out += "~";
+          i++;
+          continue;
+        }
+        if (next === "1") {
+          out += "/";
+          i++;
+          continue;
+        }
+      }
+      out += segment[i];
+    }
+    return out;
+  }
+  /**
+   * IS THIS `$ref` A LOCAL POINTER? A pointer into the file's own document — `#` (the root) or
+   * `#/a/b` (a location inside it) — is answered by the document and by nothing else, so it is
+   * neither an import nor an external target. Everything else (`./other.json`,
+   * `schemas/x.json#/defs/Y`, `https://…`) names something the document does not contain.
+   */
+  isLocalPointer(refPath) {
+    return refPath === "#" || refPath.startsWith("#/");
+  }
+  /**
+   * THE FILE A `$ref` NAMES, in the spelling the PROJECT's own file list uses — or `null`.
+   *
+   * `null` is the honest answer whenever the path cannot be derived soundly: no project root was
+   * supplied, the referring file does not sit under the root, the refPath is not a relative
+   * document path (a URL, an absolute path, a bare fragment), or folding `..` escapes the project
+   * (a sibling checkout is not an admitted file, and claiming one would be REFUTED by the gate).
+   * A wrong candidate is worse than none: the arbiter refutes a file claim it cannot find, and a
+   * refutation is counted against the lane exactly as an unresolved edge is.
+   */
+  fileRefCandidate(ctx, refPath) {
+    if (!this.isFileNamingRef(refPath)) return null;
+    const self = projectRelativePath(ctx.filePath, ctx.projectRoot);
+    if (self === null) return null;
+    const cut = self.lastIndexOf("/");
+    const dir = cut < 0 ? "" : self.slice(0, cut + 1);
+    const noFragment = refPath.split("#")[0];
+    if (noFragment.length === 0) return null;
+    const out = [];
+    for (const seg of (dir + noFragment).split("/")) {
+      if (seg.length === 0 || seg === ".") continue;
+      if (seg === "..") {
+        if (out.length === 0) return null;
+        out.pop();
+        continue;
+      }
+      out.push(seg);
+    }
+    return out.length > 0 ? out.join("/") : null;
+  }
+  isReference(key, value) {
+    if (key === "$ref") return true;
+    return value.type === "string" && isPathReference(this.stripQuotes(value.text));
+  }
+  referencePath(key, value) {
+    if (!this.isReference(key, value) || value.type !== "string") return void 0;
+    return this.stripQuotes(value.text);
+  }
+  isRequired(ctx, parentPath, key) {
+    return ctx.requiredByObject.get(parentPath)?.has(key) ?? false;
+  }
+  hasValidation(ctx, key, value) {
+    if (VALIDATION_KEYS.has(key)) return true;
+    if (value.type !== "object") return false;
+    for (const pair of value.namedChildren ?? []) {
+      if (pair?.type === "pair" && VALIDATION_KEYS.has(this.keyText(pair))) return true;
+    }
+    return false;
+  }
+  isApiEndpoint(key, value) {
+    if (key.length === 0 || key[0] !== "/") return false;
+    if (value.type !== "object") return false;
+    for (const pair of value.namedChildren ?? []) {
+      if (pair?.type === "pair" && API_METHOD_KEYS.has(this.keyText(pair))) return true;
+    }
+    return false;
+  }
+  detectFrameworks(ctx) {
+    const frameworks = [];
+    const file = ctx.filePath.toLowerCase();
+    const has = (name) => ctx.symbolMap.has(name);
+    const dependency = (name) => {
+      for (const symbol of ctx.dependencySymbols) if (symbol.name === name) return true;
+      return false;
+    };
+    if (this.fileEndsWith(file, "package.json")) frameworks.push("npm/Node.js");
+    if (this.fileEndsWith(file, "composer.json")) frameworks.push("Composer/PHP");
+    if (this.fileEndsWith(file, "tsconfig.json") || has("compilerOptions")) frameworks.push("TypeScript");
+    if (has("openapi") || has("swagger")) frameworks.push("OpenAPI/Swagger");
+    if (has("$schema") || ctx.schemaObjects.size > 0) frameworks.push("JSON Schema");
+    if (has("Version") && has("Resources")) frameworks.push("AWS CloudFormation");
+    if (dependency("react") || dependency("@types/react")) frameworks.push("React");
+    if (dependency("vue") || dependency("@vue/core")) frameworks.push("Vue.js");
+    if (dependency("next")) frameworks.push("Next.js");
+    return frameworks;
+  }
+  detectPatterns(ctx) {
+    const patterns = [];
+    if (ctx.schemaObjects.size > 0 || ctx.symbolMap.has("$schema")) patterns.push("JSON Schema Validation");
+    if (ctx.referenceSymbols.length > 0) patterns.push("Reference-based Relationships");
+    if (ctx.apiEndpointSymbols.length > 0) patterns.push("RESTful API Design");
+    if (ctx.hasArrays) patterns.push("Collection Data Types");
+    if (ctx.maxDepth > 3) patterns.push("Deep Nested Structures");
+    if (ctx.symbolMap.has("dependencies") || ctx.symbolMap.has("devDependencies")) patterns.push("Dependency Management");
+    return patterns;
+  }
+  structuralScores(ctx) {
+    let dataModelingScore = 70;
+    if (ctx.objectCount > 0 && ctx.propertyCount / ctx.objectCount >= 2) dataModelingScore += 10;
+    if (ctx.maxDepth <= 4) dataModelingScore += 10;
+    let schemaValidationScore = 50;
+    if (ctx.schemaObjects.size > 0) schemaValidationScore += 25;
+    if (ctx.validationSymbols.length > 0) schemaValidationScore += 15;
+    if (ctx.referenceSymbols.length > 0) schemaValidationScore += 10;
+    return { dataModelingScore: Math.min(100, dataModelingScore), schemaValidationScore: Math.min(100, schemaValidationScore) };
+  }
+  insights(ctx) {
+    const out = [];
+    if (ctx.referenceSymbols.length > 0) out.push(`JSON references detected (${ctx.referenceSymbols.length})`);
+    if (ctx.validationSymbols.length > 0) out.push(`Schema validation keywords detected (${ctx.validationSymbols.length})`);
+    if (ctx.hasArrays) out.push(`Arrays detected (${ctx.arrayCount})`);
+    return out;
+  }
+  valueType(node) {
+    switch (node.type) {
+      case "object":
+        return "object";
+      case "array":
+        return "array";
+      case "string":
+        return "string";
+      case "number":
+        return "number";
+      case "true":
+      case "false":
+        return "boolean";
+      case "null":
+        return "null";
+      default:
+        return "unknown";
+    }
+  }
+  keyText(pair) {
+    const key = pair.type === "pair" ? pair.childForFieldName("key") : pair;
+    return key ? this.stripQuotes(key.text) : "";
+  }
+  stripQuotes(text) {
+    const value = text.trim();
+    if (value.length >= 2 && value[0] === '"' && value[value.length - 1] === '"') return value.slice(1, -1);
+    return value;
+  }
+  /**
+   * An array item's SYMBOL name and the SYMBOL name of the array that holds it.
+   *
+   * Derived from the array's own QUALIFIED path (minus the module prefix) plus the index,
+   * never from the item's path and never from the array's bare NAME — and the second half of
+   * that is the fix. The array's own NAME is not enough once an array can be an ELEMENT of
+   * another array, because then two different arrays share it:
+   *
+   *   { "rows": [ [ {"cell": 1}, {"cell": 2} ] ] }
+   *
+   * The inner array's name arrives as `rows`, the same name the OUTER array has, so its two
+   * elements came out as `rows[0]` and `rows[1]` — names that collide with the outer array's
+   * own element namespace — while their qualified paths said `rows[0][0]` and `rows[0][1]`.
+   * The consequence was not cosmetic: `contains` is emitted from the OWNER symbol, and the
+   * owner was derived from the truncated name, so the document stated
+   *
+   *   rows[0] contains rows[0][1]
+   *
+   * between two objects that are not nested at all. Measured over the corpus: 30 of the 37
+   * `contains` edges an independent oracle could not corroborate, and 183 at the whole-population
+   * count before the endpoint change. The two walkers agreed on the defect, which is the case
+   * the honesty contract calls out: agreement is evidence that two implementations agree, not
+   * that either is right.
+   *
+   * Deriving from the array's own NAME is still right for the ordinary case, because a key's
+   * qualified path minus the module prefix IS its name — `a.rows` → `rows` — and it is what
+   * makes a dotted module name survive: `index.svelte.warnings.json` gives the module
+   * `index.svelte.warnings` and the item owner `items`, not `warnings`.
+   */
+  arrayItemName(arrayPath, rootName, index) {
+    if (arrayPath === rootName) return { item: `${rootName}[${index}]`, holder: rootName };
+    const lastSegment = arrayPath.slice(arrayPath.lastIndexOf(".") + 1);
+    const self = lastSegment.endsWith("]") ? this.afterModuleImpl(arrayPath, rootName) : lastSegment;
+    return { item: `${self}[${index}]`, holder: self };
+  }
+  /**
+   * The name a qualified path carries once the module prefix is removed — the ONE place that
+   * strips it, because getting it wrong is invisible in isolation and expensive in aggregate.
+   *
+   * The character at `rootName.length` says what kind of path this is, and the two cases need
+   * OPPOSITE handling:
+   *
+   *   `.`  the path continues under a KEY, and the key is the name — drop the separator, so
+   *       `mod.rows[0]` gives `rows[0]`.
+   *   `[`  the path hangs off the module by an INDEX and there is no key at all, so the
+   *       bracket IS the name's first character — keep it, so `mod[4]` gives `[4]`.
+   *
+   * A fixed `slice(rootName.length + 1)` assumes the first case and therefore eats the `[` in
+   * the second, publishing `4]`, `4][2]`, `4][2][6]`. Measured on a sample of the corpus's
+   * top-level-array documents: 19,708 names over 214 files, 14.9% of that population — a
+   * family (`4][2][6][1]`) no keyed or element name can produce, which is what distinguishes
+   * it from the correct `Statement[0]` spelling that also ends in `]`.
+   *
+   * A path that is neither (no separator at all) returns the path unchanged rather than
+   * chopping a leading character off a name that has no prefix to remove.
+   */
+  afterModuleImpl(path, rootName) {
+    if (path === rootName) return path;
+    const boundary = path.charAt(rootName.length);
+    if (boundary === "[") return path.slice(rootName.length);
+    if (boundary === ".") return path.slice(rootName.length + 1);
+    return path;
+  }
+  addArrayObjectSymbol(ctx, node, path, itemName) {
+    const bracket = itemName.lastIndexOf("[");
+    const name = itemName;
+    const ownerName = bracket > 0 ? itemName.slice(0, bracket) : ctx.rootName;
+    this.addSymbol(ctx, {
+      name,
+      kind: ASTEngine.SymbolKind.Class,
+      qualifiedName: path,
+      range: this.nodeToRange(node),
+      ownerName,
+      ownerKind: ASTEngine.SymbolKind.Class,
+      scope: ownerName,
+      visibility: "public",
+      returnType: "object",
+      metadata: {
+        jsonSpecific: true,
+        nodeType: "object",
+        valueType: "object",
+        fullPath: path,
+        isObject: true,
+        isArrayItem: true,
+        depth: this.pathDepth(path, ctx.rootName)
+      }
+    });
+  }
+  /**
+   * The symbol for an array element that is itself an ARRAY.
+   *
+   * Same shape as `addArrayObjectSymbol` and for the same reason: `contains` is emitted from
+   * the OWNER symbol, so an element that owns elements needs a symbol of its own. Its name is
+   * the qualified path minus the module prefix (`rows[0]`), which is the same string the
+   * object-element rule produces, so the two kinds cannot collide on one position.
+   */
+  addArrayElementSymbol(ctx, node, path, itemName) {
+    const lastSegment = path.slice(path.lastIndexOf(".") + 1);
+    const name = lastSegment.endsWith("]") ? this.afterModuleImpl(path, ctx.rootName) : lastSegment;
+    const bracket = name.lastIndexOf("[");
+    const ownerName = bracket > 0 ? name.slice(0, bracket) : ctx.rootName;
+    this.addSymbol(ctx, {
+      name,
+      kind: ASTEngine.SymbolKind.Class,
+      qualifiedName: path,
+      range: this.nodeToRange(node),
+      ownerName,
+      ownerKind: ASTEngine.SymbolKind.Class,
+      scope: ownerName,
+      visibility: "public",
+      returnType: "array",
+      metadata: {
+        jsonSpecific: true,
+        nodeType: "array",
+        valueType: "array",
+        fullPath: path,
+        isArray: true,
+        isArrayItem: true,
+        depth: this.pathDepth(path, ctx.rootName)
+      }
+    });
+  }
+  childPath(parentPath, key) {
+    return parentPath ? `${parentPath}.${key}` : key;
+  }
+  pushArrayChildren(stack, node, parentPath, parentName, rootName) {
+    const children = node.namedChildren ?? [];
+    for (let i = children.length - 1; i >= 0; i--) {
+      const child = children[i];
+      if (!child) continue;
+      const itemPath = `${parentPath}[${i}]`;
+      const { item } = this.arrayItemName(parentPath, rootName, i);
+      const isElement = child.type === "object" || child.type === "array";
+      stack.push({
+        node: child,
+        parentPath: itemPath,
+        parentName: isElement ? item : parentName,
+        emitObject: isElement
+      });
+    }
+  }
+  /**
+   * Depth of a qualified path below the module, counted in dot-separated segments.
+   *
+   * This reads the same prefix `afterModuleImpl` removes, so it calls that rather than
+   * repeating the arithmetic. The two derivations had drifted independently and the second
+   * one was wrong for the same reason: for a top-level array the character at
+   * `rootName.length` is `[`, so the fixed `+ 1` ate it. It happened to cost nothing here —
+   * both `4][2][6]` and `[4][2][6]` split to one segment — which is exactly why it survived
+   * a fix to the naming rule beside it. Two copies of one derivation is a second chance to be
+   * wrong for free.
+   */
+  pathDepth(path, rootName) {
+    if (path === rootName) return 0;
+    return this.afterModuleImpl(path, rootName).split(".").length;
+  }
+  updateDepth(ctx, path) {
+    const depth = this.pathDepth(path, ctx.rootName);
+    if (depth > ctx.maxDepth) ctx.maxDepth = depth;
+  }
+  pushNamedChildren(stack, node, parentPath, parentName = parentPath, duplicateKeys) {
+    const children = node.namedChildren ?? [];
+    for (let i = children.length - 1; i >= 0; i--) {
+      const child = children[i];
+      if (child) stack.push({ node: child, parentPath, parentName, duplicateKeys });
+    }
+  }
+  /**
+   * The node types that are JSON VALUES. A `comment` is a named child of `document` in
+   * this grammar and is not a value: it introduces no key and cannot publish a name. An
+   * `ERROR` node is the grammar's recovery shape and says nothing about how many documents
+   * the file really holds.
+   */
+  isValueNode(node) {
+    const t = node.type;
+    return t === "object" || t === "array" || t === "string" || t === "number" || t === "true" || t === "false" || t === "null";
+  }
+  /**
+   * Push a document's top-level values, giving each one its OWN position when the file
+   * holds more than one.
+   *
+   * ## The defect
+   *
+   * Concatenated JSON is real input — cargo/rustfix's recorded compiler diagnostics are
+   * sequences of 2 to 5 top-level objects in one file — and this grammar parses that as ONE
+   * `document` node with N named children. `pushNamedChildren` gave every one of them the
+   * SAME `parentPath`, so all N published `<module>.<key>` and the qualified name stopped
+   * identifying anything:
+   *
+   *     name=code kind=class    qn=str-lit-type-mismatch.code  line 3
+   *     name=code kind=class    qn=str-lit-type-mismatch.code  line 73
+   *     name=code kind=class    qn=str-lit-type-mismatch.code  line 143
+   *     name=code kind=property qn=str-lit-type-mismatch.code  line 213
+   *
+   * Four symbols under one name, the fourth of a different kind — so the shared arbiter
+   * counts it AMBIGUOUS and the reverse walk picks a winner that is simply the wrong line.
+   * This is the whole of bucket A in the 601-file ambiguity split.
+   *
+   * ## Why the position is conditional
+   *
+   * A document with ONE value keeps `<module>` as its parent path, unchanged. That is 13,835
+   * of 13,951 admitted files and it is the contract every fixture encodes. 358 more hold
+   * one value beside comments or ERROR nodes, and `comment+object` is the commonest
+   * multi-child shape in the corpus at 24 files — gating on `namedChildCount > 1` would
+   * rename all of them for no reason. `top-level-value-positions.ts` measures the split:
+   * 45 files have >=2 values, 358 have 1 value plus extras, 13,477 have exactly one child.
+   *
+   * ## Why the spelling is `<module>[i]` and not a new separator
+   *
+   * It is the spelling `arrayItemName` already gives a top-level array's elements, and a
+   * concatenated document is the same shape written without brackets: N values in sequence
+   * rather than N elements in an array. Reusing it means one convention, not two, and
+   * `afterModuleImpl` already handles the `[` boundary.
+   */
+  pushTopLevelValues(stack, node, parentPath, parentName) {
+    let valueCount = 0;
+    const children = node.namedChildren ?? [];
+    for (const child of children) {
+      if (child && this.isValueNode(child)) valueCount++;
+    }
+    if (valueCount <= 1) {
+      this.pushNamedChildren(stack, node, parentPath, parentName);
+      return;
+    }
+    let position = 0;
+    for (let i = children.length - 1; i >= 0; i--) {
+      const child = children[i];
+      if (!child) continue;
+      if (!this.isValueNode(child)) continue;
+      const name = `${parentPath}[${position}]`;
+      stack.push({ node: child, parentPath: name, parentName: name, emitObject: child.type === "object" });
+      position++;
+    }
+  }
+  /**
+   * A document's IDENTITY, and it is scoped to the file.
+   *
+   * ## The defect this fixes
+   *
+   * The identity was the filesystem BASENAME, and every `package.json` in a project publishes a
+   * module symbol named `package`. Measured over a 601-file stride of the json corpus
+   * (`validation/m14/measurements/json-ambiguity-split-601-after.json`): 90 colliding target names
+   * across 1,218 collision symbols, and the `package.*` family — `package.dependencies` alone
+   * carries 3 declarations — is the bucket that file scoping resolves on its own. So the `contains`
+   * edge asserting that `package` owns `dependencies` could not be walked in either direction:
+   * the shared resolver binds a bare name only under `HAVING COUNT(*) = 1`, and an exact-key match
+   * has to be unique too.
+   *
+   * ## The rule
+   *
+   * Scoping by the project-relative directory chain, dot-joined, basename last. Dot-joined because
+   * every downstream consumer already reads a dotted string as a path; basename last because the
+   * leaf of every member path is computed by slicing a fixed number of characters off the module
+   * prefix, so moving the basename would break that arithmetic. The full rule and its three
+   * properties are in `src/ast/project-scoped-identity.ts`, which is shared on purpose.
+   *
+   * ## What it does NOT do
+   *
+   * It does not make the BASENAME key unique — `package` is still published by every package.json,
+   * because the basename is the readable name a human uses. It makes the QUALIFIED PATH unique,
+   * and that path is what `contains` emits and what exact-match resolution binds.
+   */
+  documentName(filePath, projectRoot) {
+    const slash = filePath.lastIndexOf("/");
+    const base = slash >= 0 ? filePath.slice(slash + 1) : filePath;
+    const lower = base.toLowerCase();
+    for (const suffix of [".json", ".jsonc", ".json5"]) {
+      if (lower.endsWith(suffix)) return this.scoped(base.slice(0, base.length - suffix.length) || "document", filePath, projectRoot);
+    }
+    return this.scoped(base || "document", filePath, projectRoot);
+  }
+  /**
+   * Fold the project-relative directory chain onto the document's stem.
+   *
+   * One place, so the scope cannot be applied on one return path and missed on another — the
+   * early-return shape this replaced is exactly how a document keeps its basename on the branch
+   * that strips an extension and gets scoped on the branch that does not.
+   */
+  scoped(stem, filePath, projectRoot) {
+    return applyDocumentScope(stem, documentDirScope(filePath, projectRoot));
+  }
+  fileEndsWith(filePath, suffix) {
+    return filePath.toLowerCase().endsWith(suffix.toLowerCase());
+  }
+  documentType(ctx) {
+    if (this.fileEndsWith(ctx.filePath, "package.json")) return "npm_package";
+    if (this.fileEndsWith(ctx.filePath, "composer.json")) return "composer_package";
+    if (this.isApiSpec(ctx)) return "openapi_spec";
+    if (ctx.schemaObjects.size > 0 || ctx.symbolMap.has("$schema")) return "json_schema";
+    return "generic_json";
+  }
+  isApiSpec(ctx) {
+    return (ctx.symbolMap.has("openapi") || ctx.symbolMap.has("swagger")) && ctx.symbolMap.has("paths");
+  }
+  /**
+   * The 1-based line a symbol was DECLARED on, for the `line_number` every
+   * relationship must carry. M60 requires a site line on every edge, and this
+   * analyzer emitted NONE: the string `line_number` did not occur in the file, so
+   * every JSON edge in the index was stored with a NULL line and no consumer —
+   * the graph panel included — could point at where an edge came from. Symbols
+   * carried `range` all along, so the position was known and simply not published.
+   */
+  declLine(symbol) {
+    return symbol?.range?.startLine ?? 0;
+  }
+  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 {
+  RealJsonAnalyzer
+};