@backbencher/brain 0.0.0-stage → 0.1.1

package/dist/real-protobuf-analyzer-3OKUCZ7T.js

@@ -0,0 +1,867 @@
+import {
+  dirOf,
+  fileClaimForTarget
+} from "./chunk-EWMWK7WN.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-protobuf-analyzer.ts
+import * as path from "path";
+var hasJsWhitespace = (c) => c === 9 || c === 10 || c === 11 || c === 12 || c === 13 || c === 32 || c === 160 || c === 5760 || c >= 8192 && c <= 8202 || c === 8232 || c === 8233 || c === 8239 || c === 8287 || c === 12288 || c === 65279;
+var stripPackagePrefix = (s) => {
+  let i = 0;
+  while (i < s.length && hasJsWhitespace(s.charCodeAt(i))) i++;
+  if (!s.startsWith("package", i)) return s;
+  i += 7;
+  if (i >= s.length || !hasJsWhitespace(s.charCodeAt(i))) return s;
+  while (i < s.length && hasJsWhitespace(s.charCodeAt(i))) i++;
+  return s.slice(i);
+};
+var stripTrailingSemicolon = (s) => {
+  let e = s.length;
+  while (e > 0 && hasJsWhitespace(s.charCodeAt(e - 1))) e--;
+  if (e > 0 && s.charCodeAt(e - 1) === 59) e--;
+  return s.slice(0, e);
+};
+var stripOneTrailingSlash = (s) => s.endsWith("/") ? s.slice(0, -1) : s;
+var hasPathSeparator = (s) => s.includes("/") || s.includes("\\");
+var hasUriSchemePrefix = (s) => {
+  const isLetter = (c) => c >= 65 && c <= 90 || c >= 97 && c <= 122;
+  if (s.length === 0 || !isLetter(s.charCodeAt(0))) return false;
+  for (let i = 1; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c === 58) return true;
+    if (!isLetter(c) && !(c >= 48 && c <= 57) && c !== 43 && c !== 46 && c !== 45) return false;
+  }
+  return false;
+};
+var PROTOBUF_DECLARATION_SPEC = {
+  typeNodes: { message: "class", enum: "enum", service: "interface" },
+  memberNodes: [],
+  baseNodes: [],
+  nameResolver: (n) => {
+    const children = (n.namedChildren ?? []).filter((c) => c !== null && c !== void 0);
+    const own = children.find((c) => String(c.type).endsWith("_name"))?.text ?? n.childForFieldName("name")?.text ?? "";
+    if (own.length === 0) return "";
+    let root = n;
+    while (root.parent !== null && root.parent !== void 0) root = root.parent;
+    const rootChildren = (root.namedChildren ?? []).filter((c) => c !== null && c !== void 0);
+    const packages = [];
+    for (const c of rootChildren) {
+      if (String(c.type) !== "package") continue;
+      const text = stripTrailingSemicolon(stripPackagePrefix(String(c.text ?? ""))).trim();
+      if (text.length > 0) packages.push(text);
+    }
+    return packages.length > 0 ? `${packages.join(".")}.${own}` : own;
+  }
+};
+var PROTOBUF_EXTERNAL_NAMESPACES = [
+  "google.protobuf",
+  "google.api",
+  // `google.rpc` is the Google API's error-code/status surface (`google.rpc.Status`,
+  // `google.rpc.Code`, `google/rpc/error_details.proto`), and it was missing from a list whose
+  // job is exactly the runtime namespaces no admitted file declares FOR THE PROJECT THAT READS
+  // THEM. MEASURED whole population before adding it
+  // (validation/m14/fixtures/protobuf/measurements/claim-pricing.mts §A): the entry attaches to
+  // 30 `uses` edges — 17 read in projects that do NOT ship `google/rpc` (docker 6,
+  // waypoint 10, kubernetes 1) and are `unresolved` today, 13 read in `pb-googleapis`, which
+  // DOES ship `google/rpc/status.proto` and where the edges resolve today. The 13 are the
+  // `resolved -> extOK` shape §8.2 of `FOUR-CLAUSE-protobuf.md` already pre-authorized for
+  // `google.protobuf` (415 such moves): a per-file analyzer cannot know which project it is in,
+  // so a namespace claim is a statement about the LIST and the arbiter checks it against the
+  // list — never the symbol table. Widening an array is a visible, reviewable act, which is
+  // what makes the 13 acceptable in exchange for closing 17.
+  "google.rpc",
+  "gogoproto",
+  "protoc-gen-openapiv2"
+];
+function protobufExternalNamespaceOf(target) {
+  if (target.length === 0) return null;
+  const segs = target.split(".");
+  for (let n = segs.length; n >= 1; n--) {
+    const cand = segs.slice(0, n).join(".");
+    if (PROTOBUF_EXTERNAL_NAMESPACES.includes(cand)) return cand;
+  }
+  return null;
+}
+var RealProtobufAnalyzer = class {
+  analyze(rootNode, content, filePath, context) {
+    const symbols = [];
+    const relationships = [];
+    const imports = [];
+    const typeCache = /* @__PURE__ */ new Map();
+    const idOf = (n) => n.id ?? -1;
+    const typeOf = (n) => {
+      const id = idOf(n);
+      const hit = typeCache.get(id);
+      if (hit !== void 0) return hit;
+      const t = n.type;
+      typeCache.set(id, t);
+      return t;
+    };
+    const kids = (n) => {
+      const out = [];
+      for (const c of n.children) if (c && c.isNamed) out.push(c);
+      return out;
+    };
+    const firstOfType = (n, t) => {
+      for (const c of kids(n)) if (typeOf(c) === t) return c;
+      return null;
+    };
+    const lineOf = (n) => n ? n.startPosition.row + 1 : 0;
+    const lineOfOf = (startIndex) => {
+      let row = 1;
+      for (let i = 0; i < startIndex && i < content.length; i++) if (content.charCodeAt(i) === 10) row++;
+      return row;
+    };
+    const unquote = (s) => {
+      if (!s || s.length < 2) return s ?? "";
+      const a = s[0];
+      const b = s[s.length - 1];
+      if ((a === '"' || a === "'") && a === b) return s.slice(1, -1);
+      return s;
+    };
+    const prevSiblingOf = (parent, child) => {
+      const all = parent.children;
+      for (let i = 0; i < all.length; i++) {
+        const c = all[i];
+        if (c && c.startIndex === child.startIndex && c.endIndex === child.endIndex) {
+          return i > 0 ? all[i - 1] : null;
+        }
+      }
+      return null;
+    };
+    const docComments = /* @__PURE__ */ new Map();
+    {
+      const lineStarts = [0];
+      for (let i = 0; i < content.length; i++) {
+        if (content.charCodeAt(i) === 10) lineStarts.push(i + 1);
+      }
+      const onOwnLine = (n) => {
+        const s = lineStarts[n.startPosition.row];
+        if (s === void 0 || s > n.startIndex) return true;
+        for (let i = s; i < n.startIndex; i++) {
+          const c = content.charCodeAt(i);
+          if (c !== 32 && c !== 9 && c !== 13) return false;
+        }
+        return true;
+      };
+      const stack2 = [rootNode];
+      while (stack2.length) {
+        const n = stack2.pop();
+        let pending = [];
+        for (const c of n.children) {
+          if (!c) continue;
+          if (typeOf(c) === "comment") {
+            if (onOwnLine(c)) pending.push(c.text.trim());
+            continue;
+          }
+          if (pending.length && c.isNamed) {
+            docComments.set(idOf(c), pending);
+            pending = [];
+          }
+          stack2.push(c);
+        }
+      }
+    }
+    const nodeToRange = (node) => {
+      let anchor = node;
+      for (const c of node.children) {
+        if (!c) continue;
+        if (typeOf(c) === "comment") continue;
+        anchor = c;
+        break;
+      }
+      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
+      };
+    };
+    const fileDecls = kids(rootNode);
+    let pkg = "";
+    let syntax = null;
+    let edition = null;
+    const fileOptions = [];
+    const importDirs = /* @__PURE__ */ new Set();
+    for (const d of fileDecls) {
+      if (typeOf(d) !== "import") continue;
+      const mod = unquote(String(d.childForFieldName("path")?.text ?? ""));
+      if (mod.length === 0) continue;
+      const cut = mod.lastIndexOf("/");
+      importDirs.add(cut > 0 ? mod.slice(0, cut) : "");
+    }
+    const projectNames = context?.projectIndex?.symbolNames instanceof Set ? context.projectIndex.symbolNames : void 0;
+    for (const d of fileDecls) {
+      const t = typeOf(d);
+      if (t === "package") pkg = firstOfType(d, "full_ident")?.text ?? "";
+      else if (t === "syntax") {
+        const all = d.children;
+        let value = null;
+        for (let i = 0; i < all.length; i++) {
+          const c = all[i];
+          if (c && !c.isNamed && c.text === "=") {
+            const nxt = all[i + 1];
+            if (nxt) value = unquote(nxt.text);
+            break;
+          }
+        }
+        syntax = value;
+      } else if (t === "edition") {
+        edition = unquote(d.childForFieldName("value")?.text) || unquote(firstOfType(d, "string")?.text) || null;
+      } else if (t === "option") {
+        const k = kids(d);
+        fileOptions.push({
+          name: k[0]?.text ?? "",
+          value: k[1]?.text ?? "",
+          line: lineOf(d)
+        });
+      }
+    }
+    const SymbolKind = ASTEngine.SymbolKind;
+    const qualify = (owner, name) => owner ? `${owner}.${name}` : name;
+    const declaredIds = /* @__PURE__ */ new Set();
+    const usedIds = /* @__PURE__ */ new Set();
+    const metaOf = /* @__PURE__ */ new Map();
+    const uniqueId = (base, kind) => {
+      if (!usedIds.has(base)) return base;
+      let n = 0;
+      let cand = `${base}#${kind}`;
+      while (usedIds.has(cand)) {
+        n++;
+        cand = `${base}#${kind}${n}`;
+      }
+      return cand;
+    };
+    const declaredTypeIds = /* @__PURE__ */ new Set();
+    const slotClaims = /* @__PURE__ */ new Map();
+    const isTypeDeclaring = (kind) => kind === ASTEngine.SymbolKind.Class || kind === ASTEngine.SymbolKind.Enum;
+    const addSymbol = (id, s) => {
+      const real = uniqueId(id, String(s.kind));
+      const fieldNumber = s.metadata && s.metadata.fieldNumber !== void 0 ? s.metadata.fieldNumber : null;
+      if (s.kind === ASTEngine.SymbolKind.Property && fieldNumber !== null) {
+        const slotKey = `${String(s.ownerName ?? "")}\0${fieldNumber}`;
+        const prev = slotClaims.get(slotKey);
+        if (prev) {
+          const later = (s.range.startIndex ?? 0) > prev.startIndex;
+          const srcStart = later ? s.range.startIndex ?? 0 : prev.startIndex;
+          if (!collectOnly) {
+            addRel(
+              later ? real : prev.id,
+              later ? prev.id : real,
+              RelationshipTypeOverrides,
+              lineOfOf(srcStart),
+              { role: "fieldSlot", fieldNumber }
+            );
+          }
+        }
+        slotClaims.set(slotKey, { id: real, startIndex: s.range.startIndex ?? 0, name: String(s.name) });
+      }
+      usedIds.add(real);
+      declaredIds.add(real);
+      if (isTypeDeclaring(s.kind)) declaredTypeIds.add(real);
+      if (collectOnly) return real;
+      s.metadata = { ...s.metadata, id: real, qualifiedName: real };
+      s.qualifiedName = real;
+      metaOf.set(real, s.metadata);
+      symbols.push(s);
+      return real;
+    };
+    const ownerMeta = (id, fn) => {
+      const m = metaOf.get(id);
+      if (m) fn(m);
+    };
+    const fileRanges = [];
+    let collectOnly = false;
+    const evidenceClassFor = (type) => {
+      if (type === ASTEngine.RelationshipType.Imports) return "import_based";
+      if (type === ASTEngine.RelationshipType.Exports) return "structural";
+      return "structural";
+    };
+    const addRel = (source, target, type, line, metadata = {}) => {
+      if (collectOnly) return;
+      relationships.push({
+        source,
+        target,
+        type,
+        relationshipType: type,
+        line_number: line,
+        confidence: 1,
+        metadata: {
+          evidenceClass: evidenceClassFor(type),
+          // THE NAMESPACE CLAIM (task-19). Attached ONLY where this edge is a TYPE REFERENCE that
+          // this file does not declare AND whose namespace is one of the declared runtime
+          // namespaces above — i.e. exactly the class that used to read `unresolved` with no claim
+          // at all. The `declaredTypeIds` guard is what keeps the lane from certifying a reference
+          // its own file already answers; it is also why this adoption moves no `resolved` edge.
+          ...type === ASTEngine.RelationshipType.References && !declaredTypeIds.has(target) && protobufExternalNamespaceOf(target) !== null ? { languageNamespace: [...PROTOBUF_EXTERNAL_NAMESPACES] } : {},
+          ...metadata
+        }
+      });
+    };
+    const resolveRef = (text, scope) => {
+      if (text.startsWith(".")) return text.slice(1);
+      const chain = [];
+      if (scope) {
+        const segs = scope.split(".");
+        for (let i = segs.length; i > 0; i--) {
+          const cand = segs.slice(0, i).join(".");
+          if (!pkg || cand === pkg || cand.startsWith(pkg + ".")) chain.push(cand);
+        }
+      }
+      if (pkg) chain.push(pkg);
+      chain.push(null);
+      for (const base of chain) {
+        const cand = base ? `${base}.${text}` : text;
+        if (declaredTypeIds.has(cand)) return cand;
+      }
+      if (text.includes(".")) {
+        const hit = resolveViaImports(text, scope);
+        if (hit !== null) return hit;
+        return text;
+      }
+      const bare = resolveBareViaImports(text, scope);
+      if (bare !== null) return bare;
+      return qualify(pkg || null, text);
+    };
+    const resolveBareViaImports = (text, scope) => {
+      if (importDirs.size === 0) return null;
+      const chain = specScopeChain(scope);
+      for (const base of chain) {
+        if (base.length === 0) continue;
+        const dir = base.split(".").join("/");
+        if (!importDirs.has(dir)) continue;
+        for (const other of chain) {
+          if (other.length === 0) continue;
+          const otherDir = other.split(".").join("/");
+          if (otherDir !== dir && otherDir.endsWith(dir)) return null;
+        }
+        return `${base}.${text}`;
+      }
+      return null;
+    };
+    const specScopeChain = (scope) => {
+      const chain = [];
+      const push = (v) => {
+        if (!chain.includes(v)) chain.push(v);
+      };
+      if (scope) {
+        const segs = scope.split(".");
+        for (let i = segs.length; i > 0; i--) push(segs.slice(0, i).join("."));
+      }
+      if (pkg) {
+        const segs = pkg.split(".");
+        for (let i = segs.length; i > 0; i--) push(segs.slice(0, i).join("."));
+      }
+      push("");
+      return chain;
+    };
+    const resolveViaImports = (text, scope) => {
+      if (importDirs.size === 0) return null;
+      const lastDot = text.lastIndexOf(".");
+      if (lastDot <= 0) return null;
+      const rootedAt = text.slice(0, lastDot);
+      const typeName = text.slice(lastDot + 1);
+      const chain = specScopeChain(scope);
+      for (const base of chain) {
+        const packageOf = base.length > 0 ? `${base}.${rootedAt}` : rootedAt;
+        const dir = packageOf.split(".").join("/");
+        if (!importDirs.has(dir)) {
+          const candidate = `${packageOf}.${typeName}`;
+          if (projectNames !== void 0 && projectNames.has(candidate)) return candidate;
+          continue;
+        }
+        for (const other of chain) {
+          const otherPackage = other.length > 0 ? `${other}.${rootedAt}` : rootedAt;
+          const otherDir = otherPackage.split(".").join("/");
+          if (otherDir !== dir && otherDir.endsWith(dir)) return null;
+        }
+        return `${packageOf}.${typeName}`;
+      }
+      return null;
+    };
+    const refTypeOf = (typeNode) => {
+      if (!typeNode) return null;
+      const inner = firstOfType(typeNode, "message_or_enum_type");
+      return inner ? inner.text : null;
+    };
+    const idOwner = (ctx) => ctx.viaExtension ? ctx.scope : ctx.owner;
+    const addFieldLike = (node, nameNode, ctx, extra) => {
+      const name = nameNode.text;
+      if (!name) return null;
+      const meta = { ...extra };
+      if (ctx.oneof) meta.oneof = ctx.oneof;
+      if (ctx.viaExtension) meta.viaExtension = true;
+      const id = addSymbol(qualify(idOwner(ctx), name), {
+        name,
+        kind: SymbolKind.Property,
+        range: nodeToRange(node),
+        ownerName: ctx.owner ?? void 0,
+        ownerKind: ctx.ownerKind ?? void 0,
+        metadata: meta
+      });
+      if (ctx.owner) {
+        addRel(ctx.owner, id, RelationshipTypeContains, lineOf(node), {
+          member: "field",
+          // `viaExtension` on the EDGE as well as on the symbol. It was on the
+          // symbol only, so a consumer reading `google.protobuf.MessageOptions
+          // -contains-> audit_ticket` could not tell an extension field added in
+          // another file from a field declared in the message's own body — and the
+          // header's claim that the edge carries it was false. Measured over the
+          // corpus before this change: 0 of the extension-derived `contains` edges
+          // carried `viaExtension`, because `addFieldLike` set it on the symbol's
+          // metadata object and the `addRel` call passed only `member`.
+          ...ctx.viaExtension ? { viaExtension: true } : {}
+        });
+      }
+      return id;
+    };
+    const RelationshipTypeContains = ASTEngine.RelationshipType.Contains;
+    const RelationshipTypeReferences = ASTEngine.RelationshipType.References;
+    const RelationshipTypeImports = ASTEngine.RelationshipType.Imports;
+    const RelationshipTypeExports = ASTEngine.RelationshipType.Exports;
+    const RelationshipTypeOverrides = ASTEngine.RelationshipType.Overrides;
+    const emitField = (node, ctx) => {
+      const typeNode = firstOfType(node, "type");
+      const body = firstOfType(node, "message_body");
+      const numNode = firstOfType(node, "field_number");
+      const label = (node.children ?? []).filter((c) => c && !c.isNamed).map((c) => c.text).find((t) => t === "optional" || t === "required" || t === "repeated");
+      if (!typeNode && body) {
+        const gname = node.childForFieldName("name")?.text ?? firstOfType(node, "identifier")?.text;
+        if (gname) {
+          const typeOwner = idOwner(ctx);
+          const typeId = addSymbol(qualify(typeOwner, gname), {
+            name: gname,
+            kind: SymbolKind.Class,
+            range: nodeToRange(node),
+            ownerName: typeOwner ?? void 0,
+            // Inside an `extend`, `ctx.ownerKind` is the EXTENDEE's kind, which is
+            // not the kind of the scope the type is being declared in, so it is
+            // omitted rather than asserted. Outside an `extend` the two agree and it
+            // is carried through unchanged.
+            ...ctx.viaExtension ? {} : { ownerKind: ctx.ownerKind ?? void 0 },
+            // `isGroupType` and nothing else: a type declared at the block's own
+            // scope is not an extension member, so it does not carry `viaExtension`.
+            // The group's FIELD below still does.
+            metadata: { isGroupType: true }
+          });
+          if (typeOwner) addRel(typeOwner, typeId, RelationshipTypeContains, lineOf(node), { member: "groupType" });
+          const fieldId2 = addSymbol(qualify(idOwner(ctx), gname), {
+            name: gname,
+            kind: SymbolKind.Property,
+            range: nodeToRange(node),
+            ownerName: ctx.owner ?? void 0,
+            ownerKind: ctx.ownerKind ?? void 0,
+            metadata: {
+              type: gname,
+              isGroup: true,
+              fieldNumber: numNode?.text ?? null,
+              ...label ? { label } : {},
+              ...ctx.viaExtension ? { viaExtension: true } : {}
+            }
+          });
+          if (ctx.owner) addRel(ctx.owner, fieldId2, RelationshipTypeContains, lineOf(node), { member: "field", ...ctx.viaExtension ? { viaExtension: true } : {} });
+          addRel(fieldId2, typeId, RelationshipTypeReferences, lineOf(node), { role: "groupType" });
+          const inner = {
+            ...ctx,
+            owner: typeId,
+            scope: typeId,
+            ownerKind: SymbolKind.Class,
+            oneof: null,
+            viaExtension: false
+          };
+          pushAll(kids(body), inner);
+          return;
+        }
+      }
+      const nameNode = firstOfType(node, "identifier");
+      if (!nameNode) return;
+      const ref = refTypeOf(typeNode);
+      const fieldId = addFieldLike(node, nameNode, ctx, {
+        type: ref ?? typeNode?.text ?? null,
+        ...ref ? {} : { scalar: true },
+        fieldNumber: numNode?.text ?? null,
+        ...label ? { label } : {}
+      });
+      if (fieldId && ref) {
+        addRel(fieldId, resolveRef(ref, ctx.scope), RelationshipTypeReferences, lineOf(node), { role: "fieldType" });
+      }
+    };
+    const emitMapField = (node, ctx) => {
+      const nameNode = firstOfType(node, "identifier");
+      if (!nameNode) return;
+      const keyNode = firstOfType(node, "key_type");
+      const valType = firstOfType(node, "type");
+      const valRef = refTypeOf(valType);
+      const numNode = firstOfType(node, "field_number");
+      const fieldId = addFieldLike(node, nameNode, ctx, {
+        isMap: true,
+        mapKey: keyNode?.text ?? null,
+        mapValue: valRef ?? valType?.text ?? null,
+        ...valRef ? {} : { valueIsScalar: true },
+        fieldNumber: numNode?.text ?? null
+      });
+      if (fieldId && valRef) {
+        addRel(fieldId, resolveRef(valRef, ctx.scope), RelationshipTypeReferences, lineOf(node), {
+          role: "mapValueType"
+        });
+      }
+    };
+    const emitOneofField = (node, ctx) => {
+      const nameNode = firstOfType(node, "identifier");
+      if (!nameNode) return;
+      const typeNode = firstOfType(node, "type");
+      const ref = refTypeOf(typeNode);
+      const fieldId = addFieldLike(node, nameNode, ctx, {
+        type: ref ?? typeNode?.text ?? null,
+        ...ref ? {} : { scalar: true },
+        fieldNumber: firstOfType(node, "field_number")?.text ?? null
+      });
+      if (fieldId && ref) {
+        addRel(fieldId, resolveRef(ref, ctx.scope), RelationshipTypeReferences, lineOf(node), { role: "oneofFieldType" });
+      }
+    };
+    const emitEnumField = (node, ctx) => {
+      const nameNode = firstOfType(node, "identifier");
+      if (!nameNode) return;
+      const name = nameNode.text;
+      const id = addSymbol(qualify(idOwner(ctx), name), {
+        name,
+        kind: SymbolKind.EnumMember,
+        range: nodeToRange(node),
+        ownerName: ctx.owner ?? void 0,
+        ownerKind: SymbolKind.Enum,
+        metadata: {
+          value: firstOfType(node, "int_lit")?.text ?? null,
+          ...ctx.viaExtension ? { viaExtension: true } : {}
+        }
+      });
+      if (ctx.owner) addRel(ctx.owner, id, RelationshipTypeContains, lineOf(node), { member: "enumValue", ...ctx.viaExtension ? { viaExtension: true } : {} });
+    };
+    const emitRpc = (node, ctx) => {
+      const nameNode = firstOfType(node, "rpc_name");
+      if (!nameNode) return;
+      const name = nameNode.text;
+      const types = kids(node).filter((c) => typeOf(c) === "message_or_enum_type");
+      const request = types[0]?.text ?? null;
+      const response = types[1]?.text ?? null;
+      const isStreaming = (t) => {
+        if (!t) return false;
+        const p = prevSiblingOf(node, t);
+        return !!p && !p.isNamed && p.text === "stream";
+      };
+      const clientStreaming = isStreaming(types[0]);
+      const serverStreaming = isStreaming(types[1]);
+      const id = addSymbol(qualify(ctx.owner, name), {
+        name,
+        kind: SymbolKind.Method,
+        range: nodeToRange(node),
+        ownerName: ctx.owner ?? void 0,
+        ownerKind: SymbolKind.Interface,
+        ...request ? { parameters: [{ name: "request", type: request }] } : {},
+        ...response ? { returnType: response } : {},
+        metadata: {
+          ...request ? { requestType: request } : {},
+          ...response ? { responseType: response } : {},
+          clientStreaming,
+          serverStreaming
+        }
+      });
+      if (ctx.owner) addRel(ctx.owner, id, RelationshipTypeContains, lineOf(node), { member: "rpc", ...ctx.viaExtension ? { viaExtension: true } : {} });
+      if (request) addRel(id, resolveRef(request, ctx.scope), RelationshipTypeReferences, lineOf(node), { role: "rpcRequest" });
+      if (response) addRel(id, resolveRef(response, ctx.scope), RelationshipTypeReferences, lineOf(node), { role: "rpcResponse" });
+    };
+    const stack = [];
+    const pushAll = (children, ctx) => {
+      for (const c of children) stack.push({ node: c, ctx });
+    };
+    const visit = (node, ctx) => {
+      switch (typeOf(node)) {
+        case "message": {
+          const nameNode = firstOfType(node, "message_name");
+          if (!nameNode) return;
+          const name = nameNode.text;
+          const id = addSymbol(qualify(ctx.owner, name), {
+            name,
+            kind: SymbolKind.Class,
+            range: nodeToRange(node),
+            ...docComments.has(idOf(node)) ? { comments: docComments.get(idOf(node)) } : {},
+            ownerName: ctx.owner ?? void 0,
+            ownerKind: ctx.ownerKind ?? void 0,
+            metadata: { isMessage: true, ...ctx.viaExtension ? { viaExtension: true } : {} }
+          });
+          if (ctx.owner) addRel(ctx.owner, id, RelationshipTypeContains, lineOf(node), { member: "nestedType", ...ctx.viaExtension ? { viaExtension: true } : {} });
+          const body = firstOfType(node, "message_body");
+          if (body) {
+            const inner = { ...ctx, owner: id, scope: id, ownerKind: SymbolKind.Class, oneof: null };
+            pushAll(kids(body), inner);
+          }
+          return;
+        }
+        case "enum": {
+          const nameNode = firstOfType(node, "enum_name");
+          if (!nameNode) return;
+          const name = nameNode.text;
+          const id = addSymbol(qualify(ctx.owner, name), {
+            name,
+            kind: SymbolKind.Enum,
+            range: nodeToRange(node),
+            ...docComments.has(idOf(node)) ? { comments: docComments.get(idOf(node)) } : {},
+            ownerName: ctx.owner ?? void 0,
+            ownerKind: ctx.ownerKind ?? void 0,
+            metadata: { isEnum: true, ...ctx.viaExtension ? { viaExtension: true } : {} }
+          });
+          if (ctx.owner) addRel(ctx.owner, id, RelationshipTypeContains, lineOf(node), { member: "nestedType", ...ctx.viaExtension ? { viaExtension: true } : {} });
+          const body = firstOfType(node, "enum_body");
+          if (body) {
+            const inner = { ...ctx, owner: id, scope: id, ownerKind: SymbolKind.Enum, oneof: null };
+            pushAll(kids(body), inner);
+          }
+          return;
+        }
+        case "service": {
+          const nameNode = firstOfType(node, "service_name");
+          if (!nameNode) return;
+          const name = nameNode.text;
+          const id = addSymbol(qualify(ctx.owner, name), {
+            name,
+            kind: SymbolKind.Interface,
+            range: nodeToRange(node),
+            ...docComments.has(idOf(node)) ? { comments: docComments.get(idOf(node)) } : {},
+            ownerName: ctx.owner ?? void 0,
+            ownerKind: ctx.ownerKind ?? void 0,
+            metadata: { isService: true, ...ctx.viaExtension ? { viaExtension: true } : {} }
+          });
+          if (ctx.owner) addRel(ctx.owner, id, RelationshipTypeContains, lineOf(node), { member: "nestedType", ...ctx.viaExtension ? { viaExtension: true } : {} });
+          const inner = { ...ctx, owner: id, scope: id, ownerKind: SymbolKind.Interface, oneof: null };
+          pushAll(
+            kids(node).filter((c) => typeOf(c) !== "service_name"),
+            inner
+          );
+          return;
+        }
+        case "extend": {
+          const target = firstOfType(node, "full_ident")?.text ?? firstOfType(node, "message_or_enum_type")?.text;
+          const body = firstOfType(node, "message_body");
+          if (!target || !body) return;
+          const resolved = resolveRef(target, ctx.scope);
+          const inner = {
+            ...ctx,
+            owner: resolved,
+            // `scope` is DELIBERATELY NOT `resolved`. The block's members belong
+            // to the extended type, but a type written inside the block is
+            // looked up from where the block is WRITTEN, because `extend` does
+            // not open a scope. Inheriting `ctx.scope` unchanged is what makes a
+            // nested `extend` resolve against the enclosing messages; setting it
+            // to `resolved` would resolve against a type the language never made
+            // a scope of, and the walk would find nothing.
+            scope: ctx.scope,
+            ownerKind: SymbolKind.Class,
+            oneof: null,
+            viaExtension: true
+          };
+          pushAll(kids(body), inner);
+          return;
+        }
+        case "oneof": {
+          const kn = kids(node);
+          const nameNode = kn.find((c) => typeOf(c) === "identifier");
+          if (!nameNode) return;
+          const name = nameNode.text;
+          const id = addSymbol(qualify(ctx.owner, name), {
+            name,
+            kind: SymbolKind.Union,
+            range: nodeToRange(node),
+            ...docComments.has(idOf(node)) ? { comments: docComments.get(idOf(node)) } : {},
+            ownerName: ctx.owner ?? void 0,
+            ownerKind: ctx.ownerKind ?? void 0,
+            metadata: { isOneof: true }
+          });
+          if (ctx.owner) addRel(ctx.owner, id, RelationshipTypeContains, lineOf(node), { member: "oneof", ...ctx.viaExtension ? { viaExtension: true } : {} });
+          const inner = { ...ctx, oneof: id };
+          pushAll(kids(node), inner);
+          return;
+        }
+        case "reserved":
+        case "extensions": {
+          const what = typeOf(node) === "reserved" ? "reserved" : "extensions";
+          const ranges = kids(node).filter((c) => typeOf(c) === "ranges").flatMap((r) => kids(r).filter((c) => typeOf(c) === "range").map((c) => c.text));
+          const names = kids(node).filter((c) => typeOf(c) === "field_names").flatMap((f) => kids(f).map((c) => unquote(c.text)));
+          if (ctx.owner) ownerMeta(ctx.owner, (m) => {
+            const list = m[what] ?? [];
+            list.push(...ranges.length ? ranges.map((t) => ({ range: t })) : names.map((t) => ({ name: t })));
+            m[what] = list;
+          });
+          else
+            fileRanges.push(
+              ...ranges.length ? ranges.map((t) => ({ kind: what, range: t })) : names.map((t) => ({ kind: what, name: t }))
+            );
+          return;
+        }
+        case "field":
+          emitField(node, ctx);
+          return;
+        case "map_field":
+          emitMapField(node, ctx);
+          return;
+        case "oneof_field":
+          emitOneofField(node, ctx);
+          return;
+        case "enum_field":
+          emitEnumField(node, ctx);
+          return;
+        case "rpc":
+          emitRpc(node, ctx);
+          return;
+        default:
+          return;
+      }
+    };
+    const root = { pkg, owner: pkg || null, scope: pkg || null, ownerKind: null, oneof: null, viaExtension: false };
+    const drain = () => {
+      while (stack.length) {
+        const item = stack.pop();
+        const d = item.node;
+        const t = typeOf(d);
+        if (t === "import") {
+          const raw = d.childForFieldName("path")?.text ?? firstOfType(d, "string")?.text ?? "";
+          const path2 = unquote(raw);
+          let modifier = null;
+          for (const c of d.children) {
+            if (!c || c.isNamed) continue;
+            if (c.text === "public" || c.text === "weak" || c.text === "option") {
+              modifier = c.text;
+              break;
+            }
+          }
+          if (!collectOnly) {
+            imports.push({
+              module: path2,
+              path: path2,
+              items: [],
+              isDefaultImport: false,
+              isNamespaceImport: false,
+              range: nodeToRange(d),
+              metadata: { ...modifier ? { modifier } : {} }
+            });
+            if (path2) {
+              const selfMod = pkg.length > 0 ? pkg : filePath.split("/").pop() || filePath;
+              const moduleMeta = { modulePath: path2, filePath, ...pkg.length > 0 ? { moduleOwner: "package" } : { moduleOwner: "basename" } };
+              if (modifier === "public") {
+                addRel(selfMod, path2, RelationshipTypeExports, lineOf(d), {
+                  ...moduleMeta,
+                  viaPublicImport: true
+                });
+                addRel(selfMod, path2, RelationshipTypeImports, lineOf(d), {
+                  ...moduleMeta,
+                  ...modifier ? { modifier } : {},
+                  viaPublicImport: true
+                });
+              } else {
+                addRel(selfMod, path2, RelationshipTypeImports, lineOf(d), {
+                  ...moduleMeta,
+                  ...modifier ? { modifier } : {},
+                  // The editions FEATURE import resolves an option's definition
+                  // rather than a message, which is why it is not a re-export even
+                  // though it names a file this one depends on.
+                  ...modifier === "option" ? { isFeatureImport: true } : {}
+                });
+              }
+            }
+          }
+          continue;
+        }
+        if (t === "package") {
+          addSymbol(pkg, {
+            name: pkg,
+            kind: SymbolKind.Namespace,
+            range: nodeToRange(d),
+            metadata: { isProtoPackage: true }
+          });
+          continue;
+        }
+        visit(d, item.ctx);
+      }
+    };
+    collectOnly = true;
+    pushAll(fileDecls, root);
+    drain();
+    collectOnly = false;
+    usedIds.clear();
+    metaOf.clear();
+    slotClaims.clear();
+    fileRanges.length = 0;
+    stack.length = 0;
+    pushAll(fileDecls, root);
+    drain();
+    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 && r.type !== ASTEngine.RelationshipType.Exports) continue;
+        const md = r.metadata;
+        if (!md || typeof md.importProjectFile === "string") continue;
+        const written = String(r.target ?? "");
+        const extraCandidates = [];
+        const target = written.trim();
+        if (target.length > 0 && !target.includes("://") && !target.startsWith("/")) {
+          const fileRel = path.relative(path.resolve(claimRoot), filePath).split(path.sep).join("/");
+          let rel = stripOneTrailingSlash(dirOf(fileRel));
+          while (rel.length > 0) {
+            extraCandidates.push(`${rel}/${target}`);
+            rel = stripOneTrailingSlash(dirOf(rel));
+          }
+        }
+        const claim = fileClaimForTarget({
+          projectRoot: claimRoot,
+          filePath,
+          written,
+          admittedExtensions: ["proto"],
+          extraCandidates
+        });
+        if (claim === null) {
+          const src = String(r.target ?? "");
+          if (hasPathSeparator(src) || hasUriSchemePrefix(src)) md.sourcePathClaim = [src];
+          continue;
+        }
+        md.importProjectFile = claim;
+      }
+    }
+    return {
+      symbols,
+      relationships,
+      imports,
+      metadata: {
+        ...syntax ? { syntax } : {},
+        ...edition ? { edition } : {},
+        ...pkg ? { protoPackage: pkg } : {},
+        ...fileOptions.length ? { fileOptions } : {},
+        ...fileRanges.length ? { fileRanges } : {},
+        // A COUNTED work measure, not a duration. `typeCache.size` is the number
+        // of distinct nodes the walk actually read, which is what a linearity
+        // claim needs: it is deterministic and load-independent, where a wall
+        // clock on a shared machine moved this lane's own ratio between 0.94 and
+        // 2.05 across runs of identical code, and exceeded its bound only when
+        // other lanes were running. A gate whose verdict depends on what else the
+        // machine is doing is not a gate.
+        visitedNodes: typeCache.size,
+        filePath,
+        symbolCount: symbols.length,
+        relationshipCount: relationships.length
+      }
+    };
+  }
+};
+export {
+  PROTOBUF_DECLARATION_SPEC,
+  RealProtobufAnalyzer
+};