@backbencher/brain 0.0.0-stage → 0.1.0

package/dist/real-graphql-analyzer-MAQRZ6QW.js

@@ -0,0 +1,1442 @@
+import {
+  FILE_CLAIM_MAX_BYTES,
+  fileClaimForTarget
+} from "./chunk-EWMWK7WN.js";
+import {
+  ASTEngine
+} from "./chunk-V44PGPA6.js";
+import "./chunk-BQ3OVQ3P.js";
+import "./chunk-SK6YVHFZ.js";
+import "./chunk-2BSKD7O3.js";
+import "./chunk-KAET47ZL.js";
+import "./chunk-KCDECRJY.js";
+import "./chunk-MLKGABMK.js";
+
+// src/ast/real-graphql-analyzer.ts
+var EXTENSION_TO_DEFINITION = {
+  ObjectTypeExtension: "ObjectTypeDefinition",
+  InterfaceTypeExtension: "InterfaceTypeDefinition",
+  UnionTypeExtension: "UnionTypeDefinition",
+  EnumTypeExtension: "EnumTypeDefinition",
+  ScalarTypeExtension: "ScalarTypeDefinition",
+  InputObjectTypeExtension: "InputObjectTypeDefinition"
+};
+var SPEC_BUILTIN_SCALARS = ["String", "Int", "Float", "Boolean", "ID"];
+var SPEC_BUILTIN_SCALAR_SET = new Set(SPEC_BUILTIN_SCALARS);
+function lastPathSegment(p) {
+  let cut = -1;
+  for (let i = 0; i < p.length; i++) {
+    const c = p.charAt(i);
+    if (c === "/" || c === "\\") cut = i;
+  }
+  return cut >= 0 ? p.slice(cut + 1) : p;
+}
+function unnamedOperationIdentity(filePath, ordinal) {
+  const base = lastPathSegment(filePath ?? "");
+  const dot = base.lastIndexOf(".");
+  const stem = dot > 0 ? base.slice(0, dot) : base;
+  return `${stem || "document"}::operation_${ordinal}`;
+}
+var HASH_IMPORT_KEYWORD = "import";
+var isQuote = (code) => code === 34 || code === 39 || code === 96;
+var isInlineSpace = (code) => code === 32 || code === 9;
+var isWordByte = (code) => code >= 65 && code <= 90 || code >= 97 && code <= 122 || code >= 48 && code <= 57 || code === 95;
+function parseHashImport(text) {
+  let i = 0;
+  while (i < text.length && isInlineSpace(text.charCodeAt(i))) i++;
+  if (text.charCodeAt(i) !== 35) return null;
+  i++;
+  while (i < text.length && isInlineSpace(text.charCodeAt(i))) i++;
+  for (let k = 0; k < HASH_IMPORT_KEYWORD.length; k++) {
+    if (text.charCodeAt(i + k) !== HASH_IMPORT_KEYWORD.charCodeAt(k)) return null;
+  }
+  i += HASH_IMPORT_KEYWORD.length;
+  if (i < text.length && isWordByte(text.charCodeAt(i))) return null;
+  const skipSpace = () => {
+    while (i < text.length && isInlineSpace(text.charCodeAt(i))) i++;
+  };
+  const quoted = () => {
+    skipSpace();
+    const q = text.charCodeAt(i);
+    if (!isQuote(q)) return null;
+    i++;
+    const start = i;
+    while (i < text.length && text.charCodeAt(i) !== q) i++;
+    if (i >= text.length) return null;
+    const value = text.slice(start, i);
+    i++;
+    return value.length > 0 ? value : null;
+  };
+  const word = () => {
+    skipSpace();
+    const s = i;
+    while (i < text.length && !isInlineSpace(text.charCodeAt(i)) && !isQuote(text.charCodeAt(i)) && text.charCodeAt(i) !== 44) i++;
+    return text.slice(s, i);
+  };
+  const first = quoted();
+  if (first !== null) {
+    const after = word();
+    if (after.length === 0) return { target: first, form: "bare", bindings: [] };
+    return after === "as" ? { target: first, form: "bare", bindings: [word()] } : null;
+  }
+  const bindings = [];
+  for (; ; ) {
+    const w = word();
+    if (w.length === 0) return null;
+    bindings.push(w);
+    if (text.charCodeAt(i) === 44) {
+      i++;
+      continue;
+    }
+    break;
+  }
+  if (word() !== "from") return null;
+  const target = quoted();
+  if (target === null) return null;
+  return { target, form: "from_binding", bindings };
+}
+var DIRECTIVE_NODE = /* @__PURE__ */ new WeakMap();
+var RealGraphqlAnalyzer = class _RealGraphqlAnalyzer {
+  /**
+   * `node.type` memoised per node id, for the duration of one `analyze` call.
+   *
+   * `type` is a marshalling getter — every read crosses into WASM and copies a
+   * string out — and the analyzer reads it far more often than there are nodes:
+   * measured on the 20,368-line GitHub public schema, **103,531 reads of 31,491
+   * distinct nodes, so 69.6% were redundant.** `node.id`, by contrast, is a plain
+   * own property set in the binding's constructor, so keying a `Map` on it costs
+   * nothing and turns every read after the first into a hash lookup.
+   *
+   * It is an instance field only because the readers are instance methods, and it
+   * is REASSIGNED at the top of every `analyze` call, which is what makes it safe:
+   * a `Node` id is only unique within one tree, and the binding documents that a
+   * node reused from an older tree keeps its id, so a cache that outlived a call
+   * could answer with the previous tree's type. Reassigning makes that impossible
+   * rather than merely unlikely.
+   */
+  typeCache = /* @__PURE__ */ new Map();
+  /** Counts the operations this document leaves unnamed, so each can be published under
+   *  the file's identity (see `unnamedOperationIdentity`). Reset per `analyze` call: a
+   *  pooled worker reuses one analyzer instance across files, and a counter that
+   *  survived the call would number the second file's operations from where the first
+   *  file stopped. */
+  unnamedOperationOrdinal = 0;
+  /** `node.type`, read through the per-call memo. */
+  typeOf(node) {
+    const id = node.id;
+    if (typeof id !== "number") return node.type;
+    const hit = this.typeCache.get(id);
+    if (hit !== void 0) return hit;
+    const t = node.type;
+    this.typeCache.set(id, t);
+    return t;
+  }
+  analyze(rootNode, content, filePath, context) {
+    this.typeCache = /* @__PURE__ */ new Map();
+    this.unnamedOperationOrdinal = 0;
+    const symbols = [];
+    const relationships = [];
+    const imports = [];
+    const exports = [];
+    const errors = [];
+    const relKeys = /* @__PURE__ */ new Set();
+    const addRelationship = (source, target, type, line, role, metadata = {}) => {
+      if (source === target && role === "field_selection") return;
+      if (!source || !target) return;
+      const key = `${source}\0${type}\0${target}\0${role}\0${line}`;
+      if (relKeys.has(key)) return;
+      relKeys.add(key);
+      relationships.push({
+        source,
+        target,
+        type,
+        confidence: 1,
+        line_number: line,
+        // Every edge this analyzer emits is read off a NAMED AST NODE — an
+        // `ImplementsInterfaces` clause, a `NamedType`, a field's own `Name`, a
+        // `Directives` child — so `structural` is the class for most of them and is
+        // stated rather than left absent. 38 sibling lanes publish this key and this
+        // one published none, which made "how much of this graph is guesswork" a
+        // question with no machine-readable answer on this lane: the honesty contract
+        // §4.3 requires the heuristic ratio to be a QUERYABLE number, and an absent
+        // key is not queryable. `confidence` was already 1 everywhere, so nothing
+        // here is newly a heuristic — the key says so explicitly.
+        //
+        // THE ONE TIER THAT IS NOT STRUCTURAL: `imports`. A `#import "file.graphql"`
+        // hash-import's TARGET is a FILE PATH read out of a comment string, not a name
+        // read off a named AST node — it is the lane's file-dependency claim (the same
+        // ladder toml's imports row carries), so it is `import_based`. Section D of the
+        // completeness inventory requires two DISTINCT tiers pinned by fixtures, and
+        // this is the lane's honest second one rather than a manufactured value.
+        metadata: {
+          ...metadata,
+          relationshipRole: role,
+          evidenceClass: type === ASTEngine.RelationshipType.Imports ? "import_based" : "structural"
+        }
+      });
+    };
+    const addDeclaredType = (source, target, line, role, metadata = {}) => {
+      addRelationship(source, target, ASTEngine.RelationshipType.References, line, role, {
+        ...metadata,
+        relationshipType: "declared_type",
+        // THE CLAIM — attached HERE and nowhere else, because this closure is the ONE place every
+        // declared-type position passes through (directive argument, field return, field argument,
+        // input field, variable) and the only place where `target` is guaranteed to be a TYPE NAME
+        // rather than a member spelling. A union member list, an export row and a field selection are
+        // NOT type clauses, so the 48 edges of those shapes whose target happens to spell one of the
+        // five are left alone and stay `unresolved` — a measured boundary, not an oversight.
+        //
+        // The reason travels WITH the claim (`languageNamespaceBasis`) so the disposition can be read
+        // off the edge; it is not a key any claim channel reads, so it cannot misfire.
+        ...SPEC_BUILTIN_SCALAR_SET.has(target) ? {
+          languageNamespace: [...SPEC_BUILTIN_SCALARS],
+          languageNamespaceBasis: "graphql-spec-builtin-scalar"
+        } : {}
+      });
+    };
+    const directiveCache = /* @__PURE__ */ new WeakMap();
+    const directivesOf = (node) => {
+      const cached = directiveCache.get(node);
+      if (cached !== void 0) return cached;
+      const list = this.scanDirectiveApplications(node);
+      directiveCache.set(node, list);
+      return list;
+    };
+    const declaredHere = /* @__PURE__ */ new Set();
+    const kindOfNameHere = /* @__PURE__ */ new Map();
+    for (const decl of this.topLevelDeclarations(rootNode)) {
+      if (!decl.name) continue;
+      declaredHere.add(`${decl.symbolKind}\0${decl.name}`);
+      const kinds = kindOfNameHere.get(decl.name) ?? /* @__PURE__ */ new Set();
+      kinds.add(decl.symbolKind);
+      kindOfNameHere.set(decl.name, kinds);
+    }
+    const supertypeKindOf = (supertype) => {
+      const kinds = kindOfNameHere.get(supertype);
+      if (!kinds || kinds.size !== 1) return void 0;
+      const only = [...kinds][0];
+      return only === ASTEngine.SymbolKind.Interface || only === ASTEngine.SymbolKind.Class || only === ASTEngine.SymbolKind.Type ? only : void 0;
+    };
+    const emitHeritage = (owner, supertype, line, inExtension) => {
+      const supertypeKind = supertypeKindOf(supertype);
+      const relType = supertypeKind === ASTEngine.SymbolKind.Class || supertypeKind === ASTEngine.SymbolKind.Type ? ASTEngine.RelationshipType.Extends : ASTEngine.RelationshipType.Implements;
+      heritageEdges.push({ owner, iface: supertype, ifaceKind: supertypeKind });
+      addRelationship(owner, supertype, relType, line, relType === ASTEngine.RelationshipType.Extends ? "extends" : "implements", {
+        ...relType === ASTEngine.RelationshipType.Extends ? { implementsClause: true } : {},
+        ...inExtension ? { extension: true } : {}
+      });
+    };
+    const heritageEdges = [];
+    const memberNameNodes = /* @__PURE__ */ new Map();
+    const extendedHere = /* @__PURE__ */ new Set();
+    for (const ext of this.topLevelExtensions(rootNode)) {
+      extendedHere.add(`${ext.symbolKind}\0${ext.name}`);
+    }
+    const TYPE_KIND = {
+      ObjectTypeDefinition: ASTEngine.SymbolKind.Class,
+      InterfaceTypeDefinition: ASTEngine.SymbolKind.Interface,
+      UnionTypeDefinition: ASTEngine.SymbolKind.Type,
+      EnumTypeDefinition: ASTEngine.SymbolKind.Enum,
+      ScalarTypeDefinition: ASTEngine.SymbolKind.Type,
+      InputObjectTypeDefinition: ASTEngine.SymbolKind.Class
+    };
+    const extensionSymbols = [];
+    const rootOperationNames = /* @__PURE__ */ new Set();
+    const hashImports = [];
+    const stack = [
+      { node: rootNode, owner: {}, sel: { path: [] }, inExtension: false }
+    ];
+    const pushChildren = (node, owner, sel, inExtension, skip = () => false) => {
+      const kids = node.namedChildren;
+      for (let i = kids.length - 1; i >= 0; i--) {
+        const child = kids[i];
+        if (child && !skip(child)) stack.push({ node: child, owner, sel, inExtension });
+      }
+    };
+    if (this.isAnyOf(rootNode, "Document", "source_file", "SourceFile")) {
+    }
+    while (stack.length > 0) {
+      const { node, owner, sel, inExtension } = stack.pop();
+      const t = node.type;
+      if (t === "SchemaDefinition" || t === "SchemaExtension") {
+        if (!symbols.some((s) => s.name === "schema" && s.kind === ASTEngine.SymbolKind.Namespace)) {
+          symbols.push({
+            name: "schema",
+            kind: ASTEngine.SymbolKind.Namespace,
+            range: this.nodeToRange(node),
+            scope: "",
+            visibility: "public",
+            docstring: this.descriptionOf(node),
+            metadata: {
+              graphqlType: t === "SchemaDefinition" ? "schema" : "schema_extension",
+              topLevel: true,
+              ...t === "SchemaExtension" ? { inExtension: true } : {}
+            }
+          });
+        }
+        for (const opDef of node.namedChildren) {
+          if (opDef?.type !== "OperationTypeDefinition") continue;
+          const opTypeNode = this.firstChildOfType(opDef, "OperationType");
+          const opType = opTypeNode?.text ?? "operation";
+          const named = this.firstChildOfType(opDef, "NamedType");
+          const rootType = named ? this.nameOf(named) : void 0;
+          const line = this.lineOf(named ?? opDef);
+          if (rootOperationNames.has(opType)) continue;
+          rootOperationNames.add(opType);
+          symbols.push({
+            name: opType,
+            kind: ASTEngine.SymbolKind.Property,
+            range: this.nodeToRange(opDef),
+            scope: "schema",
+            visibility: "public",
+            returnType: rootType,
+            ownerName: "schema",
+            ownerKind: ASTEngine.SymbolKind.Namespace,
+            metadata: {
+              graphqlRole: "root_operation_type",
+              ...t === "SchemaExtension" ? { inExtension: true } : {}
+            }
+          });
+          addRelationship("schema", `schema.${opType}`, ASTEngine.RelationshipType.Contains, line, "contains", {
+            ...t === "SchemaExtension" ? { extension: true } : {}
+          });
+          if (rootType) {
+            addRelationship(`schema.${opType}`, rootType, ASTEngine.RelationshipType.Uses, line, "root_operation_type", {
+              ...t === "SchemaExtension" ? { extension: true } : {}
+            });
+          }
+        }
+        this.emitDirectiveApplications(node, directivesOf(node), "schema", sel, addRelationship, t === "SchemaExtension");
+        pushChildren(node, { name: "schema", kind: ASTEngine.SymbolKind.Namespace }, sel, inExtension, (c) => this.typeOf(c) === "OperationTypeDefinition");
+        continue;
+      }
+      if (TYPE_KIND[t]) {
+        const name = this.nameOf(node);
+        if (name) {
+          const kind = TYPE_KIND[t];
+          this.emitTypeSymbol(node, name, kind, t, symbols, relationships, sel, inExtension, directivesOf(node));
+          if (t === "ScalarTypeDefinition" && extendedHere.has(`${kind}\0${name}`)) {
+            const last = symbols[symbols.length - 1];
+            last.metadata = { ...last.metadata, extended: true };
+          }
+          const implNode = this.firstChildOfType(node, "ImplementsInterfaces");
+          if (implNode) {
+            for (const { name: iface, node: ifaceNode } of this.collectNamedTypes(implNode)) {
+              emitHeritage(name, iface, this.lineOf(ifaceNode), inExtension);
+            }
+          }
+          if (t === "UnionTypeDefinition") {
+            const membersNode = this.firstChildOfType(node, "UnionMemberTypes");
+            if (membersNode) {
+              for (const { name: member, node: memberNode } of this.collectNamedTypes(membersNode)) {
+                addRelationship(name, member, ASTEngine.RelationshipType.Uses, this.lineOf(memberNode), "union_member", {
+                  ...inExtension ? { extension: true } : {}
+                });
+              }
+            }
+          }
+          this.emitDirectiveApplications(node, directivesOf(node), name, sel, addRelationship, inExtension);
+          pushChildren(node, { name, kind }, sel, inExtension);
+        }
+        continue;
+      }
+      if (EXTENSION_TO_DEFINITION[t]) {
+        if (t === "ScalarTypeExtension") {
+          this.emitDirectiveApplications(node, directivesOf(node), this.nameOf(node) ?? "", sel, addRelationship, true);
+          continue;
+        }
+        const definitionType = EXTENSION_TO_DEFINITION[t];
+        const name = this.nameOf(node);
+        if (name) {
+          const kind = TYPE_KIND[definitionType];
+          const kindKey = `${kind}\0${name}`;
+          if (!declaredHere.has(kindKey)) {
+            const index = symbols.length;
+            symbols.push({
+              name,
+              kind,
+              range: this.nodeToRange(node),
+              scope: "",
+              visibility: "public",
+              docstring: this.descriptionOf(node),
+              metadata: { graphqlType: t, partial: true, inExtension: true, topLevel: true }
+            });
+            extensionSymbols.push({ index, name, kindKey, typeNode: t });
+          }
+          const implNode = this.firstChildOfType(node, "ImplementsInterfaces");
+          if (implNode) {
+            for (const { name: iface, node: ifaceNode } of this.collectNamedTypes(implNode)) {
+              emitHeritage(name, iface, this.lineOf(ifaceNode), true);
+            }
+          }
+          if (definitionType === "UnionTypeDefinition") {
+            const membersNode = this.firstChildOfType(node, "UnionMemberTypes");
+            if (membersNode) {
+              for (const { name: member, node: memberNode } of this.collectNamedTypes(membersNode)) {
+                addRelationship(name, member, ASTEngine.RelationshipType.Uses, this.lineOf(memberNode), "union_member", { extension: true });
+              }
+            }
+          }
+          this.emitDirectiveApplications(node, directivesOf(node), name, sel, addRelationship, true);
+          pushChildren(node, { name, kind }, sel, true);
+        }
+        continue;
+      }
+      if (t === "EnumValueDefinition") {
+        const enumValue = this.firstChildOfType(node, "EnumValue");
+        const valueName = enumValue ? this.nameOf(enumValue) : void 0;
+        if (valueName && owner.name) {
+          symbols.push({
+            name: valueName,
+            kind: ASTEngine.SymbolKind.EnumMember,
+            range: this.nodeToRange(node),
+            scope: owner.name,
+            ownerName: owner.name,
+            ownerKind: owner.kind,
+            visibility: "public",
+            docstring: this.descriptionOf(node),
+            metadata: { graphqlRole: "enum_value", ...inExtension ? { inExtension: true } : {} }
+          });
+          addRelationship(owner.name, `${owner.name}.${valueName}`, ASTEngine.RelationshipType.Contains, this.lineOf(enumValue ?? node), "contains", {
+            ...inExtension ? { extension: true } : {}
+          });
+          this.emitDirectiveApplications(node, directivesOf(node), `${owner.name}.${valueName}`, { root: void 0 }, addRelationship, inExtension);
+        }
+        continue;
+      }
+      if (t === "DirectiveDefinition") {
+        const name = this.nameOf(node);
+        if (name) {
+          const argsNode = this.firstChildOfType(node, "ArgumentsDefinition");
+          const repeatable = this.hasChild(node, (n) => this.typeOf(n) === "repeatable");
+          const locations = this.firstChildOfType(node, "DirectiveLocations");
+          const locationNames = locations ? this.collectDirectiveLocations(locations).map((l) => l.name) : void 0;
+          symbols.push({
+            name: `@${name}`,
+            kind: ASTEngine.SymbolKind.Function,
+            range: this.nodeToRange(node),
+            scope: "",
+            visibility: "public",
+            parameters: argsNode ? this.extractArguments(argsNode) : [],
+            docstring: this.descriptionOf(node),
+            metadata: {
+              graphqlRole: "directive_definition",
+              topLevel: true,
+              directiveName: name,
+              ...repeatable ? { repeatable: true } : {},
+              ...locationNames ? { locations: locationNames } : {},
+              ...this.directiveMetadata(directivesOf(node))
+            }
+          });
+          if (argsNode) {
+            for (const arg of this.argumentPairs(argsNode)) {
+              if (!arg.type || !arg.typeNode) continue;
+              addDeclaredType(`@${name}`, arg.type, this.lineOf(arg.typeNode), "directive_argument_type", { argument: arg.name });
+              if (arg.name) this.emitEnumValueReferences(`@${name}`, arg.defaultNode, arg.type, addRelationship, { declaration: "directive_argument_default", argument: arg.name });
+            }
+          }
+        }
+        continue;
+      }
+      if (t === "FieldDefinition") {
+        const fieldName = this.nameOf(node);
+        if (fieldName && owner.name) {
+          const typeNode = this.firstChildOfType(node, "Type");
+          const returnType = typeNode ? this.namedTypeName(typeNode) : void 0;
+          const argsNode = this.firstChildOfType(node, "ArgumentsDefinition");
+          const ownerSymbol = `${owner.name}.${fieldName}`;
+          symbols.push({
+            name: fieldName,
+            kind: ASTEngine.SymbolKind.Property,
+            range: this.nodeToRange(node),
+            scope: owner.name,
+            visibility: "public",
+            returnType,
+            ownerName: owner.name,
+            ownerKind: owner.kind,
+            parameters: argsNode ? this.extractArguments(argsNode) : [],
+            docstring: this.descriptionOf(node),
+            metadata: {
+              graphqlRole: "field",
+              // `rawType` is the type EXPRESSION's source text and is emitted only
+              // when there is one: a recovered `Type` node with a MISSING `Name` has
+              // the empty text, and publishing `rawType: ""` is a fact about nothing.
+              ...typeNode && typeNode.text ? { rawType: typeNode.text } : {},
+              ...returnType ? { nullable: !this.isNonNullType(typeNode) } : {},
+              ...inExtension ? { inExtension: true } : {},
+              ...this.directiveMetadata(directivesOf(node))
+            }
+          });
+          const fieldNameNode = this.firstChildOfType(node, "Name");
+          addRelationship(owner.name, ownerSymbol, ASTEngine.RelationshipType.Contains, this.lineOf(fieldNameNode ?? node), "contains", {
+            ...inExtension ? { extension: true } : {}
+          });
+          if (fieldNameNode) {
+            const bag = memberNameNodes.get(owner.name) ?? /* @__PURE__ */ new Map();
+            if (!bag.has(fieldName)) bag.set(fieldName, fieldNameNode);
+            memberNameNodes.set(owner.name, bag);
+          }
+          if (returnType) {
+            addDeclaredType(ownerSymbol, returnType, this.lineOf(this.namedTypeNode(typeNode) ?? typeNode), "field_return_type", {
+              ...inExtension ? { extension: true } : {}
+            });
+          }
+          if (argsNode) {
+            for (const arg of this.argumentPairs(argsNode)) {
+              if (!arg.type || !arg.typeNode) continue;
+              addDeclaredType(ownerSymbol, arg.type, this.lineOf(arg.typeNode), "field_argument_type", {
+                argument: arg.name,
+                ...inExtension ? { extension: true } : {}
+              });
+              if (arg.name) this.emitEnumValueReferences(ownerSymbol, arg.defaultNode, arg.type, addRelationship, { declaration: "argument_default", argument: arg.name });
+            }
+          }
+          this.emitDirectiveApplications(node, directivesOf(node), ownerSymbol, sel, addRelationship, inExtension);
+        }
+        continue;
+      }
+      if (t === "InputValueDefinition" && node.parent?.type === "InputFieldsDefinition") {
+        const fieldName = this.nameOf(node);
+        if (fieldName && owner.name) {
+          const typeNode = this.firstChildOfType(node, "Type");
+          const fieldType = typeNode ? this.namedTypeName(typeNode) : void 0;
+          const ownerSymbol = `${owner.name}.${fieldName}`;
+          symbols.push({
+            name: fieldName,
+            kind: ASTEngine.SymbolKind.Property,
+            range: this.nodeToRange(node),
+            scope: owner.name,
+            visibility: "public",
+            returnType: fieldType,
+            ownerName: owner.name,
+            ownerKind: owner.kind,
+            docstring: this.descriptionOf(node),
+            metadata: {
+              graphqlRole: "input_field",
+              ...typeNode && typeNode.text ? { rawType: typeNode.text } : {},
+              ...fieldType ? { nullable: !this.isNonNullType(typeNode) } : {},
+              // Called ONCE. The conditional form below ran it twice per input
+              // field — a `firstChildOfType` walk each time — to test a value it
+              // then computed again, and this is the per-node hot path.
+              ...(() => {
+                const dv = this.defaultValueOf(node);
+                return dv !== void 0 ? { defaultValue: dv } : {};
+              })(),
+              ...inExtension ? { inExtension: true } : {},
+              ...this.directiveMetadata(directivesOf(node))
+            }
+          });
+          addRelationship(owner.name, ownerSymbol, ASTEngine.RelationshipType.Contains, this.lineOf(this.firstChildOfType(node, "Name") ?? node), "contains", {
+            ...inExtension ? { extension: true } : {}
+          });
+          this.emitEnumValueReferences(ownerSymbol, this.firstChildOfType(node, "DefaultValue"), fieldType, addRelationship, { declaration: "input_field_default" });
+          if (fieldType) {
+            addDeclaredType(ownerSymbol, fieldType, this.lineOf(this.namedTypeNode(typeNode) ?? typeNode), "input_field_type", {
+              ...inExtension ? { extension: true } : {}
+            });
+          }
+          this.emitDirectiveApplications(node, directivesOf(node), ownerSymbol, sel, addRelationship, inExtension);
+        }
+        continue;
+      }
+      if (t === "OperationDefinition") {
+        const opTypeNode = this.firstChildOfType(node, "OperationType");
+        const opType = opTypeNode?.text ?? "query";
+        const nameNode = this.firstChildOfType(node, "Name");
+        const opName = nameNode?.text ?? unnamedOperationIdentity(filePath, this.unnamedOperationOrdinal++);
+        symbols.push({
+          name: opName,
+          kind: ASTEngine.SymbolKind.Method,
+          range: this.nodeToRange(node),
+          scope: "",
+          visibility: "public",
+          metadata: {
+            graphqlRole: "operation",
+            graphqlOperationType: opType,
+            ...nameNode ? {} : { anonymous: true, shorthand: true }
+          }
+        });
+        const varsNode = this.firstChildOfType(node, "VariableDefinitions");
+        if (varsNode) {
+          for (const varDef of varsNode.namedChildren) {
+            if (varDef?.type !== "VariableDefinition") continue;
+            const varNode = this.firstChildOfType(varDef, "Variable");
+            const varName = varNode ? this.nameOf(varNode) : void 0;
+            const typeNode = this.firstChildOfType(varDef, "Type");
+            const varType = typeNode ? this.namedTypeName(typeNode) : void 0;
+            if (!varName) continue;
+            if (varType) {
+              addDeclaredType(`$${varName}`, varType, this.lineOf(this.namedTypeNode(typeNode) ?? typeNode), "variable_type", {
+                operation: opName
+              });
+            }
+            this.emitEnumValueReferences(`$${varName}`, this.firstChildOfType(varDef, "DefaultValue"), varType, addRelationship, { declaration: "variable_default" });
+            symbols.push({
+              name: `$${varName}`,
+              kind: ASTEngine.SymbolKind.Variable,
+              range: this.nodeToRange(varDef),
+              scope: opName,
+              returnType: varType,
+              ownerName: opName,
+              ownerKind: ASTEngine.SymbolKind.Method,
+              metadata: {
+                graphqlRole: "variable",
+                ...typeNode && typeNode.text ? { rawType: typeNode.text } : {},
+                ...varType ? { nullable: !this.isNonNullType(typeNode) } : {},
+                ...this.defaultValueOf(varDef) !== void 0 ? { defaultValue: this.defaultValueOf(varDef) } : {},
+                ...this.directiveMetadata(directivesOf(varDef))
+              }
+            });
+          }
+        }
+        this.emitDirectiveApplications(node, directivesOf(node), opName, sel, addRelationship, false);
+        if (varsNode) {
+          this.emitDirectiveApplications(varsNode, directivesOf(varsNode), opName, sel, addRelationship, false);
+        }
+        pushChildren(node, { name: opName, kind: ASTEngine.SymbolKind.Method }, { root: opName, path: [] }, inExtension, (c) => this.typeOf(c) === "VariableDefinition");
+        continue;
+      }
+      if (t === "FragmentDefinition") {
+        const fragNode = this.firstChildOfType(node, "FragmentName");
+        const fragName = fragNode ? this.nameOf(fragNode) : void 0;
+        if (fragName) {
+          symbols.push({
+            name: fragName,
+            kind: ASTEngine.SymbolKind.Method,
+            range: this.nodeToRange(node),
+            scope: "",
+            visibility: "public",
+            metadata: { graphqlRole: "fragment", ...this.directiveMetadata(directivesOf(node)) }
+          });
+          const typeCondition = this.firstChildOfType(node, "TypeCondition");
+          const onType = typeCondition ? this.namedTypeName(typeCondition) : void 0;
+          if (onType && typeCondition) {
+            addRelationship(fragName, onType, ASTEngine.RelationshipType.Uses, this.lineOf(this.namedTypeNode(typeCondition) ?? typeCondition), "fragment_type_condition");
+          }
+          this.emitDirectiveApplications(node, directivesOf(node), fragName, sel, addRelationship, false);
+          pushChildren(node, { name: fragName, kind: ASTEngine.SymbolKind.Method }, { root: fragName, enclosingType: onType, path: [] }, inExtension);
+        }
+        continue;
+      }
+      if (t === "VariableDefinition") continue;
+      if (t === "Field") {
+        const nameNode = this.firstChildOfType(node, "Name");
+        const fieldName = nameNode?.text;
+        const aliasNode = this.firstChildOfType(node, "Alias");
+        const alias = aliasNode ? this.nameOf(aliasNode) : void 0;
+        if (fieldName && sel.root) {
+          const qualified = sel.enclosingType ? `${sel.enclosingType}.${fieldName}` : fieldName;
+          const path = [...sel.path, fieldName].join(".");
+          const argsNode = this.firstChildOfType(node, "Arguments");
+          if (argsNode && sel.root) {
+            for (const arg of this.childrenOfType(argsNode, "Argument")) {
+              this.emitEnumValueReferences(sel.root, this.firstChildOfType(arg, "Value"), void 0, addRelationship, { declaration: "field_argument" });
+            }
+          }
+          addRelationship(sel.root, qualified, ASTEngine.RelationshipType.Uses, this.lineOf(nameNode), "field_selection", {
+            ...alias ? { alias } : {},
+            ...argsNode ? { arguments: this.argumentNames(argsNode) } : {},
+            ...sel.enclosingType ? { enclosingType: sel.enclosingType } : {},
+            ...path ? { selectionPath: path } : {}
+          });
+        }
+        this.emitDirectiveApplications(node, directivesOf(node), sel.root ?? "", sel, addRelationship, false);
+        const childPath = [...sel.path, fieldName ?? "?"];
+        pushChildren(node, { name: fieldName, kind: ASTEngine.SymbolKind.Property }, { root: sel.root, enclosingType: void 0, path: childPath }, inExtension, (c) => this.typeOf(c) === "Name" || this.typeOf(c) === "Alias");
+        continue;
+      }
+      if (t === "FragmentSpread") {
+        const spreadNode = this.firstChildOfType(node, "FragmentName");
+        const spreadName = spreadNode ? this.nameOf(spreadNode) : void 0;
+        if (spreadName && sel.root) {
+          addRelationship(sel.root, spreadName, ASTEngine.RelationshipType.Uses, this.lineOf(spreadNode), "fragment_spread", {
+            ...[...sel.path].length ? { selectionPath: sel.path.join(".") } : {}
+          });
+        }
+        this.emitDirectiveApplications(node, directivesOf(node), sel.root ?? "", sel, addRelationship, false);
+        continue;
+      }
+      if (t === "InlineFragment") {
+        const typeCondition = this.firstChildOfType(node, "TypeCondition");
+        const onType = typeCondition ? this.namedTypeName(typeCondition) : void 0;
+        if (onType && sel.root && typeCondition) {
+          addRelationship(sel.root, onType, ASTEngine.RelationshipType.Uses, this.lineOf(this.namedTypeNode(typeCondition) ?? typeCondition), "inline_fragment_type_condition", {
+            ...[...sel.path].length ? { selectionPath: sel.path.join(".") } : {}
+          });
+        }
+        this.emitDirectiveApplications(node, directivesOf(node), sel.root ?? "", sel, addRelationship, false);
+        pushChildren(node, { name: onType, kind: ASTEngine.SymbolKind.Type }, { root: sel.root, enclosingType: onType ?? sel.enclosingType, path: [...sel.path] }, inExtension, (c) => this.typeOf(c) === "TypeCondition");
+        continue;
+      }
+      if (t === "Variable") {
+        const valueParent = node.parent;
+        if (valueParent?.type === "Value" && sel.root) {
+          const varName = this.nameOf(node);
+          if (varName) {
+            addRelationship(sel.root, `$${varName}`, ASTEngine.RelationshipType.Uses, this.lineOf(node), "variable_reference", {
+              ...[...sel.path].length ? { selectionPath: sel.path.join(".") } : {}
+            });
+          }
+        }
+        continue;
+      }
+      if (t === "comment") {
+        const parsed = parseHashImport(node.text);
+        if (parsed) hashImports.push({ ...parsed, line: node.startPosition.row + 1 });
+        continue;
+      }
+      pushChildren(node, owner, sel, inExtension);
+    }
+    for (const ext of extensionSymbols) {
+      if (!declaredHere.has(ext.kindKey)) continue;
+      const sym = symbols[ext.index];
+      symbols.splice(ext.index, 1);
+      for (let i = extensionSymbols.length - 1; i >= 0; i--) {
+        if (extensionSymbols[i].index > ext.index) extensionSymbols[i].index--;
+      }
+      if (sym) sym.metadata = { ...sym.metadata, droppedExtensionSymbol: true };
+    }
+    for (const h of heritageEdges) {
+      if (h.owner === h.iface) continue;
+      const mine = memberNameNodes.get(h.owner);
+      const theirs = memberNameNodes.get(h.iface);
+      if (!mine || !theirs) continue;
+      for (const [member, nameNode] of mine) {
+        if (!theirs.has(member)) continue;
+        addRelationship(`${h.owner}.${member}`, `${h.iface}.${member}`, ASTEngine.RelationshipType.Override, this.lineOf(nameNode), "interface_member_supplied", {
+          implementedType: h.owner,
+          supertype: h.iface,
+          supertypeKind: h.ifaceKind ?? "undeclared_in_this_document",
+          member
+        });
+      }
+    }
+    if (hashImports.length > 0) {
+      const importer = lastPathSegment(filePath) || filePath;
+      for (const hi of hashImports) {
+        addRelationship(importer, hi.target, ASTEngine.RelationshipType.Imports, hi.line, "imports", {
+          isGraphqlImport: true,
+          importSource: importer,
+          importForm: hi.form,
+          // `fileLevel` IS THE FLAG THAT MAKES THE SOURCE ABOVE JOINABLE, and this edge was missing
+          // it while this analyzer's own `exports` edges already carried it. The M60/#910 contract
+          // (`parallel-indexer.ts:4391`) reads it as:
+          //
+          //     if (!sourceSymbol && rel.metadata?.fileLevel === true) { … sourceExternal = relativePath }
+          //
+          // — a module-level edge whose source did not resolve to a symbol is rewritten to the
+          // IMPORTING FILE's project-relative path. Without the flag `source_external` keeps this
+          // analyzer's own spelling, a bare basename (`schema.graphql`), which no declaration can
+          // ever answer: the row existed, the dependency existed, and the only thing missing was who
+          // declared it — verbatim the defect that clause exists to fix, and the reason no surface
+          // could answer "what does this file include".
+          //
+          // NOTHING ABOVE IS DISCARDED: the store keeps this spelling in `metadata.scopeName`, and
+          // the fixture's assertion that the source IS the importing file's own name
+          // (`ontology-file-imports.expectation.json`) is about the analyzer's OUTPUT, which is
+          // unchanged. Metadata-only, so no target-side count can move — the residual probe's
+          // reproduction of the gate's TABLE 1, in the same run, is the independent check of that.
+          fileLevel: true,
+          // The bound names are real GraphQL identifiers in this document's scope; `[]`
+          // on a bare directive means "the document as a whole", which is not the same
+          // as "no names" and is distinguished by `importForm` rather than by omission.
+          ...hi.bindings.length > 0 ? { importBindings: hi.bindings } : {}
+        });
+      }
+    }
+    for (const s of symbols) {
+      if (s.metadata?.droppedExtensionSymbol) continue;
+      if (s.metadata?.topLevel !== true) continue;
+      exports.push({ name: s.name, kind: s.kind, range: s.range, visibility: "public" });
+      addRelationship("(file)", s.name, ASTEngine.RelationshipType.Exports, s.range.startLine, "exports", {
+        fileLevel: true,
+        ...s.metadata?.graphqlType ? { graphqlType: s.metadata.graphqlType } : {},
+        ...s.metadata?.graphqlCategory ? { graphqlCategory: s.metadata.graphqlCategory } : {}
+      });
+    }
+    const claimRoot = typeof context?.projectRoot === "string" && context.projectRoot.length > 0 ? context.projectRoot : null;
+    if (claimRoot !== null) {
+      for (const r of relationships) {
+        if (r.type !== ASTEngine.RelationshipType.Imports) continue;
+        const md = r.metadata;
+        if (!md || typeof md.importProjectFile === "string") continue;
+        const claim = fileClaimForTarget({
+          projectRoot: claimRoot,
+          filePath,
+          written: String(r.target ?? ""),
+          admittedExtensions: ["graphql", "gql"],
+          // THE POPULATION'S SIZE CAP, passed because this lane HAS over-cap files (4 for graphql,
+          // 2 for scss on the gate's own population line). A claim about one of them would be
+          // REFUTED, and nothing in the row would say why.
+          maxFileSizeBytes: FILE_CLAIM_MAX_BYTES
+        });
+        if (claim === null) continue;
+        md.importProjectFile = claim;
+      }
+    }
+    return {
+      language: "graphql",
+      symbols,
+      relationships,
+      imports,
+      exports,
+      errors,
+      metadata: {
+        complexity: symbols.length + relationships.length,
+        linesOfCode: content.split("\n").length,
+        patterns: [],
+        framework: "GraphQL",
+        hasFrameworkIntelligence: true,
+        hasTypeInference: true,
+        documentKind: this.documentKind(rootNode)
+      }
+    };
+  }
+  // ---------------------------------------------------------------- helpers
+  documentKind(rootNode) {
+    let hasTypeSystem = false;
+    let hasExecutable = false;
+    for (const def of this.topLevelDefinitions(rootNode)) {
+      const inner = this.innermostNamed(def);
+      if (!inner) continue;
+      if (this.typeOf(inner) === "OperationDefinition" || this.typeOf(inner) === "FragmentDefinition") hasExecutable = true;
+      else hasTypeSystem = true;
+    }
+    if (hasTypeSystem && hasExecutable) return "mixed";
+    if (hasTypeSystem) return "type_system";
+    if (hasExecutable) return "executable";
+    return "empty";
+  }
+  /**
+   * The document's top-level declarations: for each `Definition`, the innermost
+   * named child, which is the actual construct. Cheap (one level of the tree)
+   * and it is the only place a type can be DECLARED, so it is exactly the set
+   * an extension has to be compared against.
+   */
+  topLevelDeclarations(rootNode) {
+    const out = [];
+    for (const def of this.topLevelDefinitions(rootNode)) {
+      const inner = this.innermostNamed(def);
+      if (!inner) continue;
+      const typeNode = inner.type;
+      if (typeNode === "SchemaDefinition") {
+        out.push({ name: "schema", symbolKind: ASTEngine.SymbolKind.Namespace, typeNode });
+        continue;
+      }
+      if (typeNode === "DirectiveDefinition") {
+        const n2 = this.nameOf(inner);
+        if (n2) out.push({ name: `@${n2}`, symbolKind: ASTEngine.SymbolKind.Function, typeNode });
+        continue;
+      }
+      if (typeNode.endsWith("Extension")) continue;
+      const kind = this.definitionKindOf(typeNode);
+      if (!kind) continue;
+      const n = this.nameOf(inner);
+      if (n) out.push({ name: n, symbolKind: kind, typeNode });
+    }
+    return out;
+  }
+  /**
+   * The top-level type EXTENSIONS of a document, with the kind of the definition
+   * each one extends. Computed in the pre-pass, beside `topLevelDeclarations`,
+   * because both answers come from the same one-level walk and computing either
+   * on demand meant re-walking every definition per question.
+   */
+  topLevelExtensions(rootNode) {
+    const out = [];
+    for (const def of this.topLevelDefinitions(rootNode)) {
+      const inner = this.innermostNamed(def);
+      if (!inner || !inner.type.endsWith("Extension")) continue;
+      if (this.typeOf(inner) === "SchemaExtension") {
+        out.push({ name: "schema", symbolKind: ASTEngine.SymbolKind.Namespace });
+        continue;
+      }
+      const definitionType = EXTENSION_TO_DEFINITION[inner.type];
+      const kind = definitionType ? this.definitionKindOf(definitionType) : void 0;
+      const n = this.nameOf(inner);
+      if (kind && n) out.push({ name: n, symbolKind: kind });
+    }
+    return out;
+  }
+  definitionKindOf(typeNode) {
+    switch (typeNode) {
+      case "ObjectTypeDefinition":
+      case "InputObjectTypeDefinition":
+        return ASTEngine.SymbolKind.Class;
+      case "InterfaceTypeDefinition":
+        return ASTEngine.SymbolKind.Interface;
+      case "UnionTypeDefinition":
+      case "ScalarTypeDefinition":
+        return ASTEngine.SymbolKind.Type;
+      case "EnumTypeDefinition":
+        return ASTEngine.SymbolKind.Enum;
+      default:
+        return void 0;
+    }
+  }
+  /**
+   * The rule that classifies a top-level definition, reached by unwrapping the
+   * grammar's pass-through rules.
+   *
+   * The WRAPPER SET IS EXPLICIT. "Descend while there is exactly one named
+   * child" is not the same rule and is wrong: a shorthand operation is
+   * `Definition > ExecutableDefinition > OperationDefinition > SelectionSet >
+   * Selection > Field > Name`, and an unconditional descent returns `Name` — so
+   * `{ ping }` was classified as a type-system definition and every file's
+   * `documentKind` was wrong. A `schema` block hit the same descent
+   * (`… > SchemaDefinition > OperationTypeDefinition > NamedType > Name`).
+   */
+  static DEFINITION_WRAPPERS = /* @__PURE__ */ new Set([
+    "Document",
+    "Definition",
+    "ExecutableDefinition",
+    "TypeSystemDefinition",
+    "TypeSystemExtension",
+    "TypeDefinition",
+    "TypeExtension"
+  ]);
+  innermostNamed(node) {
+    let cur = node;
+    for (; ; ) {
+      if (!_RealGraphqlAnalyzer.DEFINITION_WRAPPERS.has(this.typeOf(cur))) return cur;
+      const next = this.onlyNamedChild(cur);
+      if (!next) return cur;
+      cur = next;
+    }
+  }
+  onlyNamedChild(node) {
+    if (!node) return null;
+    const kids = node.namedChildren;
+    if (kids.length !== 1) return null;
+    return kids[0];
+  }
+  /**
+   * The document's `Definition` children. The tree is
+   * `source_file > Document > Definition`, so the root is NOT the document —
+   * reading `Definition` straight off `source_file` finds nothing, which is how
+   * the extension de-duplication silently became a no-op and every
+   * `extend type X` in a file that also declared `X` published a SECOND `class
+   * X` (a duplicate identity in the index).
+   */
+  topLevelDefinitions(rootNode) {
+    if (this.typeOf(rootNode) === "Definition") return [rootNode];
+    if (this.typeOf(rootNode) === "Document") return this.childrenOfType(rootNode, "Definition");
+    const document = this.firstChildOfType(rootNode, "Document");
+    if (document) return this.childrenOfType(document, "Definition");
+    return this.childrenOfType(rootNode, "Definition");
+  }
+  childrenOfType(node, type) {
+    const out = [];
+    for (const c of node.namedChildren) {
+      if (c && this.typeOf(c) === type) out.push(c);
+    }
+    return out;
+  }
+  emitTypeSymbol(node, name, kind, typeNode, symbols, _relationships, _sel, _inExtension, directives) {
+    symbols.push({
+      name,
+      kind,
+      range: this.nodeToRange(node),
+      scope: "",
+      visibility: "public",
+      docstring: this.descriptionOf(node),
+      metadata: {
+        // `graphqlType` is the GRAMMAR's node type, on every branch of this
+        // analyzer, so a consumer can match on it; `graphqlCategory` is the
+        // specification's word for the same thing. They used to be one field
+        // with two possible vocabularies, which silently emptied `exports`.
+        graphqlType: typeNode,
+        topLevel: true,
+        graphqlCategory: typeNode === "UnionTypeDefinition" ? "union" : typeNode === "ScalarTypeDefinition" ? "scalar" : typeNode === "EnumTypeDefinition" ? "enum" : typeNode === "InputObjectTypeDefinition" ? "input" : typeNode === "InterfaceTypeDefinition" ? "interface" : "object",
+        ...this.directiveMetadata(directives)
+      }
+    });
+  }
+  /**
+   * A directive applied to a declaration is metadata ON that declaration, and —
+   * when the directive is defined in this file — a real reference to the
+   * `@directive` function symbol. Federation schemas (`@key(fields: "id")`,
+   * `@external`, `@requires`) carry their meaning almost entirely in these
+   * applications, so dropping them drops the schema's structure.
+   */
+  emitDirectiveApplications(_node, applications, owner, sel, addRelationship, inExtension) {
+    if (!owner || !applications) return;
+    for (const app of applications) {
+      addRelationship(owner, `@${app.name}`, ASTEngine.RelationshipType.Uses, app.line, "directive_application", {
+        ...app.arguments ? { arguments: app.arguments } : {},
+        ...sel.root && sel.root !== owner ? { within: sel.root } : {},
+        ...inExtension ? { extension: true } : {}
+      });
+      const dnode = DIRECTIVE_NODE.get(app);
+      const dargs = dnode ? this.firstChildOfType(dnode, "Arguments") : null;
+      if (dargs) {
+        for (const arg of this.childrenOfType(dargs, "Argument")) {
+          this.emitEnumValueReferences(owner, this.firstChildOfType(arg, "Value"), void 0, addRelationship, {
+            declaration: "directive_argument",
+            directive: `@${app.name}`
+          });
+        }
+      }
+    }
+  }
+  /**
+   * The `Directives` scan itself: the `Directives` child of a definition, as
+   * structured metadata. A directive argument is a CONSTANT in GraphQL (the
+   * specification forbids variables there), so the `Value` node's own text is the
+   * literal's exact source spelling — no unquoting, no guessing, no regular
+   * expression. Called ONCE per node; the walk memoises it in a WeakMap, because
+   * this scan is the analyzer's single most expensive operation.
+   */
+  scanDirectiveApplications(node) {
+    const directives = this.firstChildOfType(node, "Directives");
+    if (!directives) return null;
+    const list = [];
+    for (const d of this.childrenOfType(directives, "Directive")) {
+      const nameNode = this.firstChildOfType(d, "Name");
+      if (!nameNode) continue;
+      const argsNode = this.firstChildOfType(d, "Arguments");
+      const args = {};
+      if (argsNode) {
+        for (const a of this.childrenOfType(argsNode, "Argument")) {
+          const argName = this.nameOf(a);
+          const value = this.firstChildOfType(a, "Value");
+          if (argName && value) args[argName] = value.text;
+        }
+      }
+      list.push({ name: nameNode.text, ...Object.keys(args).length ? { arguments: args } : {}, line: this.lineOf(nameNode) });
+      DIRECTIVE_NODE.set(list[list.length - 1], d);
+    }
+    return list.length ? list : null;
+  }
+  /** The memoised scan's result, as symbol metadata; `{}` when there is none. */
+  directiveMetadata(applications) {
+    return applications ? { graphqlDirectives: applications } : _RealGraphqlAnalyzer.NO_DIRECTIVE_METADATA;
+  }
+  /** Frozen so a future in-place write fails loudly instead of corrupting every symbol. */
+  static NO_DIRECTIVE_METADATA = Object.freeze({});
+  /**
+   * `on A | B | C` — the same left-recursion shape as `implements`, so the
+   * locations are collected from the whole subtree, not from direct children.
+   */
+  collectDirectiveLocations(node) {
+    const out = [];
+    const stack = [node];
+    while (stack.length) {
+      const n = stack.pop();
+      if (this.typeOf(n) === "DirectiveLocation") {
+        const inner = this.findChild(n, (c) => this.typeOf(c) === "ExecutableDirectiveLocation" || this.typeOf(c) === "TypeSystemDirectiveLocation");
+        const leaf = inner ? inner.namedChild(0) ?? inner : n;
+        out.push({ name: leaf.text, node: leaf });
+        continue;
+      }
+      const kids = n.namedChildren;
+      for (let i = kids.length - 1; i >= 0; i--) {
+        const c = kids[i];
+        if (c) stack.push(c);
+      }
+    }
+    return out;
+  }
+  /**
+   * Every `NamedType` in a subtree, in source order and deduplicated.
+   *
+   * `ImplementsInterfaces` and `UnionMemberTypes` are left-recursive, so
+   * `implements A & B & C` produces `I > I > I` in a tree-sitter build that
+   * keeps the nesting, and a flat `I > [implements, A, &, B, &, C]` in one that
+   * inlines the auxiliary repeat. Reading only DIRECT children — which is what
+   * this analyzer used to do — therefore loses every implemented interface but
+   * the last, and every union member but the last, on any grammar that nests.
+   * Walking the subtree is correct for both shapes.
+   */
+  collectNamedTypes(node) {
+    const out = [];
+    const seen = /* @__PURE__ */ new Set();
+    const stack = [node];
+    while (stack.length) {
+      const n = stack.pop();
+      if (this.typeOf(n) === "NamedType") {
+        const name = this.nameOf(n);
+        if (name && !seen.has(name)) {
+          seen.add(name);
+          out.push({ name, node: n });
+        }
+        continue;
+      }
+      const kids = n.namedChildren;
+      for (let i = kids.length - 1; i >= 0; i--) {
+        const c = kids[i];
+        if (c) stack.push(c);
+      }
+    }
+    return out;
+  }
+  namedTypeNode(typeNode) {
+    return this.findDescendant(typeNode, (n) => this.typeOf(n) === "NamedType");
+  }
+  /** Resolve a `Type`/`TypeCondition` node to its base named type name. */
+  namedTypeName(typeNode) {
+    const named = this.namedTypeNode(typeNode);
+    return named ? this.nameOf(named) : void 0;
+  }
+  /**
+   * Non-null-ness read off the grammar, not off the text. `typeNode.text`
+   * containing `!` was the previous implementation; a type NAME may legally
+   * contain `!` nowhere, but a future grammar could wrap the marker, and the
+   * `NonNullType` node is the fact.
+   */
+  isNonNullType(typeNode) {
+    const first = typeNode.namedChild(0);
+    return first?.type === "NonNullType";
+  }
+  /** The `Value` of a `DefaultValue` child, as its exact source spelling. */
+  defaultValueOf(node) {
+    const dv = this.firstChildOfType(node, "DefaultValue");
+    if (!dv) return void 0;
+    const value = this.firstChildOfType(dv, "Value");
+    return value?.text;
+  }
+  /**
+   * Every `EnumValue` in a VALUE position — a reference — with its line.
+   *
+   * The grammar puts an `EnumValue` node in two different places, and conflating
+   * them is the whole bug: `EnumValueDefinition > EnumValue` is a DECLARATION
+   * (already a symbol, with a `contains` edge from its enum), while
+   * `Value > EnumValue` is a REFERENCE to one. Only the second is a relationship,
+   * and the test is the parent, never the node type alone. Values nest
+   * (`ListValue > Value`, `ObjectField > Value`), so this descends rather than
+   * looking at direct children.
+   */
+  enumValueReferences(valueNode) {
+    const out = [];
+    if (!valueNode) return out;
+    const stack = [valueNode];
+    while (stack.length) {
+      const n = stack.pop();
+      if (this.typeOf(n) === "EnumValue" && n.parent?.type === "Value") {
+        const name = this.nameOf(n);
+        if (name) out.push({ name, line: this.lineOf(n) });
+        continue;
+      }
+      const kids = n.namedChildren;
+      for (let i = kids.length - 1; i >= 0; i--) {
+        const c = kids[i];
+        if (c) stack.push(c);
+      }
+    }
+    return out;
+  }
+  /**
+   * Emit `uses` edges for the enum values a value position names.
+   *
+   * `enumType` is supplied ONLY where the document itself states which enum the
+   * value belongs to — an `InputValueDefinition` or `VariableDefinition` carries
+   * its own `Type` sibling, so `color: Color = RED` proves `RED` is `Color.RED`.
+   * An executable field argument does not: `item(filter: { color: RED })` names
+   * the INPUT OBJECT, and reaching `Color` would need that object's declaration,
+   * which is in another file. So there the target stays the bare member name and
+   * the store's own unique-name strategy decides it — the same rule the analyzer
+   * already applies to a field selection.
+   */
+  emitEnumValueReferences(source, valueNode, enumType, addRelationship, metadata = {}) {
+    if (!source) return;
+    for (const ref of this.enumValueReferences(valueNode)) {
+      const target = enumType ? `${enumType}.${ref.name}` : ref.name;
+      addRelationship(source, target, ASTEngine.RelationshipType.Uses, ref.line, "enum_value_reference", { ...metadata, ...enumType ? { enumType } : {} });
+    }
+  }
+  argumentNames(argsNode) {
+    return this.childrenOfType(argsNode, "Argument").map((a) => this.nameOf(a)).filter((n) => !!n);
+  }
+  argumentPairs(argsNode) {
+    const pairs = [];
+    for (const arg of this.childrenOfType(argsNode, "InputValueDefinition")) {
+      const typeNode = this.firstChildOfType(arg, "Type");
+      pairs.push({
+        name: this.nameOf(arg),
+        type: typeNode ? this.namedTypeName(typeNode) : void 0,
+        typeNode: typeNode ?? void 0,
+        defaultNode: this.firstChildOfType(arg, "DefaultValue") ?? void 0
+      });
+    }
+    return pairs;
+  }
+  /**
+   * An argument's `isOptional` is GraphQL's own rule, not a guess from the
+   * `!`: a NON-NULL argument is required; a NULLABLE argument is optional only
+   * when it has a default. `f(x: Int)` is required, `f(x: Int = 1)` is not.
+   */
+  extractArguments(argsNode) {
+    const params = [];
+    for (const arg of this.childrenOfType(argsNode, "InputValueDefinition")) {
+      const name = this.nameOf(arg);
+      if (!name) continue;
+      const typeNode = this.firstChildOfType(arg, "Type");
+      const defaultValue = this.defaultValueOf(arg);
+      params.push({
+        name,
+        type: typeNode ? this.namedTypeName(typeNode) : void 0,
+        defaultValue,
+        // GraphQL's own rule, from §3.6.1: an argument is OPTIONAL only when it
+        // is NULLABLE **and** has a default. `f(a: Int)` is required even
+        // though `Int` is nullable, because a caller must pass something;
+        // `f(a: Int = 1)` is not. The previous implementation asked only
+        // `!typeNode.text.includes("!")`, so it reported both nullable shapes
+        // as optional and inverted the one distinction GraphQL makes.
+        isOptional: typeNode ? !this.isNonNullType(typeNode) && defaultValue !== void 0 : true
+      });
+    }
+    return params;
+  }
+  // ------------------------------------------------------------- descriptions
+  /**
+   * The description's VALUE, per specification §2.9.4.
+   *
+   * A `"…"` string is unquoted and its `EscapedCharacter` sequences are resolved
+   * by an explicit character scan — `\" \\ \/ \b \f \n \r \t \uXXXX` and
+   * `\\u{…}` — because the previous implementation returned the raw inner text
+   * with the backslashes still in it, so `"a \"quote\""` was published as
+   * `a \"quote\"`.
+   *
+   * A `"""…"""` block string is dedented as the specification defines: split on
+   * line terminators, take the common indent of every line after the first that
+   * has non-whitespace content, strip it, and drop leading and trailing blank
+   * lines. Then `\"""` becomes `"""`.
+   */
+  descriptionOf(node) {
+    const desc = this.firstChildOfType(node, "Description");
+    if (!desc) return void 0;
+    const sv = this.firstChildOfType(desc, "StringValue");
+    if (!sv) return void 0;
+    const raw = sv.text;
+    if (raw.length >= 6 && raw.startsWith('"""') && raw.endsWith('"""')) {
+      return this.blockStringValue(raw.slice(3, raw.length - 3));
+    }
+    if (raw.length >= 2 && raw.startsWith('"') && raw.endsWith('"')) {
+      return this.unescapeStringValue(raw.slice(1, raw.length - 1));
+    }
+    return raw;
+  }
+  /** §2.9.4 BlockStringValue: the common-indent algorithm, then the escape. */
+  blockStringValue(inner) {
+    const lines = inner.split("\n");
+    let common;
+    for (let i = 1; i < lines.length; i++) {
+      const line = lines[i];
+      let indent = 0;
+      while (indent < line.length && (line[indent] === " " || line[indent] === "	")) indent++;
+      if (indent === line.length) continue;
+      common = common === void 0 ? indent : Math.min(common, indent);
+    }
+    if (common !== void 0 && common > 0) {
+      for (let i = 1; i < lines.length; i++) lines[i] = lines[i].slice(common);
+    }
+    while (lines.length > 0 && lines[0].trim() === "") lines.shift();
+    while (lines.length > 0 && lines[lines.length - 1].trim() === "") lines.pop();
+    return lines.join("\n").replaceAll('\\"""', '"""');
+  }
+  /** §2.9.4 EscapedCharacter, resolved by scanning — no regular expression. */
+  unescapeStringValue(inner) {
+    let out = "";
+    for (let i = 0; i < inner.length; i++) {
+      const ch = inner[i];
+      if (ch !== "\\") {
+        out += ch;
+        continue;
+      }
+      const next = inner[++i];
+      switch (next) {
+        case "b":
+          out += "\b";
+          break;
+        case "f":
+          out += "\f";
+          break;
+        case "n":
+          out += "\n";
+          break;
+        case "r":
+          out += "\r";
+          break;
+        case "t":
+          out += "	";
+          break;
+        case "u": {
+          if (inner[i + 1] === "{") {
+            const close = inner.indexOf("}", i + 2);
+            if (close > 0) {
+              const code2 = Number.parseInt(inner.slice(i + 2, close), 16);
+              if (Number.isFinite(code2) && code2 >= 0 && code2 <= 1114111) {
+                out += String.fromCodePoint(code2);
+                i = close;
+                break;
+              }
+            }
+            out += "\\u";
+            break;
+          }
+          const hex = inner.slice(i + 1, i + 5);
+          const code = Number.parseInt(hex, 16);
+          if (hex.length === 4 && Number.isFinite(code)) {
+            out += String.fromCharCode(code);
+            i += 4;
+          } else {
+            out += "\\u";
+          }
+          break;
+        }
+        case void 0:
+          out += "\\";
+          break;
+        default:
+          out += next;
+          break;
+      }
+    }
+    return out;
+  }
+  // -------------------------------------------------------------------- ranges
+  /**
+   * 1-based line and column, byte offsets, and a leading `Description` skipped.
+   *
+   * The `Description` is a child of the definition node in this grammar, so a
+   * naive `nodeToRange` reports the DOCSTRING's line for every described type,
+   * field, argument, enum value and input field. On the GitHub public schema
+   * that is 3,131 of 3,332 symbols — 94 % of the file's symbols pointing at a
+   * line that does not contain the name they are named for. The M59/#861 rule
+   * (a decorated declaration's line belongs to the name, not to its decorator)
+   * is the same defect with a different decorator, and scala
+   * (`declaration-lines-825`), typescript and javascript already implement it.
+   */
+  nodeToRange(node) {
+    let anchor = node;
+    const firstChild = node.child(0);
+    if (firstChild && this.typeOf(firstChild) === "Description") {
+      const afterDescription = node.child(1);
+      if (afterDescription) anchor = afterDescription;
+    }
+    return {
+      startLine: anchor.startPosition.row + 1,
+      startColumn: anchor.startPosition.column + 1,
+      endLine: node.endPosition.row + 1,
+      endColumn: node.endPosition.column + 1,
+      startIndex: anchor.startIndex,
+      endIndex: node.endIndex
+    };
+  }
+  lineOf(node) {
+    return node ? node.startPosition.row + 1 : 0;
+  }
+  // ------------------------------------------------------------ node plumbing
+  /** The definition's own name: its direct `Name` child, or a wrapper's. */
+  nameOf(node) {
+    return this.firstChildOfType(node, "Name")?.text;
+  }
+  /**
+   * Is there a child matching `predicate`, ANONYMOUS children included?
+   *
+   * `findChild` walks `namedChild`, and `repeatable` is an anonymous keyword
+   * token in this grammar, so `directive @a repeatable on FIELD` reported
+   * `repeatable: false` — the specification's June-2018 feature was invisible
+   * on every directive that used it.
+   */
+  hasChild(node, predicate) {
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (child && predicate(child)) return true;
+    }
+    return false;
+  }
+  isAnyOf(node, ...types) {
+    return types.includes(this.typeOf(node));
+  }
+  /**
+   * A node's NAMED children, in ONE wasm call.
+   *
+   * web-tree-sitter documents `namedChild(index)` as *"fairly fast, but its cost
+   * is technically log(n), so if you might be iterating over a long list of
+   * children, you should use Node#namedChildren instead"*, and that getter
+   * materialises the whole list in a single call and CACHES it on the node. A
+   * `namedChildCount` + `namedChild(i)` loop is therefore the O(n log n)
+   * anti-pattern, and it was the one this analyzer used in nine places.
+   *
+   * The CPU profile of the 20,368-line GitHub public schema said so before this
+   * change: the tree-sitter accessor layer — `setValue`, `getValue`,
+   * `ts_node_named_child_wasm`, `ts_node_named_child_count_wasm`,
+   * `get namedChildCount` — was over 11% of self time, and `pushChildren`, which
+   * runs once per node, was its largest caller. The binding's own `children` /
+   * `namedChildren` getters also replace a per-child `unmarshalNode` with one
+   * bulk transfer, so this is fewer wasm round-trips as well as less arithmetic.
+   *
+   * The returned array is the BINDING'S OWN CACHE. It is read, never written.
+   */
+  namedChildrenOf(node) {
+    return node.namedChildren;
+  }
+  /**
+   * The first NAMED child of `type`, or null — with no closure and no per-index
+   * wasm call.
+   *
+   * `findChild(node, n => this.typeOf(n) === "X")` is the idiomatic spelling and it was
+   * used 40 times here, so it allocated 40 closures PER SYMBOL and reached `.type`
+   * through a call frame for every child it examined. The comparison is a string
+   * equality; the closure buys nothing. This is the same shape the SQL analyzer
+   * uses for its own direct-child reads, and it is the shape the profile asked
+   * for: `analyze` self time was 6.1% and the tree-sitter accessor layer was
+   * another ~9%, and both are dominated by the NUMBER of property reads rather
+   * than by any algorithm of ours.
+   */
+  firstChildOfType(node, type) {
+    if (!node) return null;
+    for (const child of node.namedChildren) {
+      if (child !== null && this.typeOf(child) === type) return child;
+    }
+    return null;
+  }
+  findChild(node, predicate) {
+    for (const child of node.namedChildren) {
+      if (child && predicate(child)) return child;
+    }
+    return null;
+  }
+  /**
+   * The first descendant satisfying `predicate`, in pre-order.
+   *
+   * ITERATIVE, and the recursion was a real defect rather than a style choice. This
+   * walks to the depth of the subtree when the predicate does not match early, and
+   * `[[[…[Int]]]]` is exactly that case: the `NamedType` sits at the BOTTOM, so the
+   * recursion went as deep as the nesting. Measured, list nesting **2,749 deep
+   * threw `RangeError: Maximum call stack size exceeded`**, and because the engine's
+   * guard turns any throw into a minimal result, that file yielded ZERO symbols and
+   * one opaque error — silently losing a whole type definition. The threshold is a
+   * function of stack-frame size, so it is a platform figure, not a guarantee.
+   *
+   * `A & B & C` was never affected, which is why the bug survived the corpus: the
+   * left-recursive rules put a `NamedType` at depth 1, so the predicate matched
+   * immediately and the recursion never went deep. 5,000 clauses still work.
+   *
+   * Children are pushed in reverse so they POP in order, which keeps this a
+   * pre-order DFS with first-match-wins — the same order, and the same result, as
+   * the recursion it replaces.
+   */
+  findDescendant(node, predicate) {
+    const stack = [];
+    const rootKids = node.namedChildren;
+    for (let i = rootKids.length - 1; i >= 0; i--) {
+      const c = rootKids[i];
+      if (c) stack.push(c);
+    }
+    while (stack.length) {
+      const n = stack.pop();
+      if (predicate(n)) return n;
+      const kids = n.namedChildren;
+      for (let i = kids.length - 1; i >= 0; i--) {
+        const c = kids[i];
+        if (c) stack.push(c);
+      }
+    }
+    return null;
+  }
+};
+export {
+  RealGraphqlAnalyzer
+};