@descryy/adapter-go 0.1.0

package/dist/extract.js

@@ -0,0 +1,871 @@
+/**
+ * Go files to Canonical IR.
+ *
+ * ## The package is the unit, and that changes resolution rather than identity
+ *
+ * Files in one Go package share a namespace completely: an unqualified name in
+ * one file resolves to a declaration in another that never mentions it. So the
+ * resolver's first scope is not the file but the package, which is the opposite
+ * of Java and TypeScript, where a file must import what it uses.
+ *
+ * Identity is the easy half. A package's import path is a declared name that
+ * other code writes verbatim, so `qsp = importPath::Symbol` needs none of the
+ * anchor inference TypeScript needs (DEC-047) or the source-set disambiguation
+ * Java needs. Go states it.
+ *
+ * ## What is deliberately not claimed
+ *
+ * **Interface satisfaction.** Go's is structural: a type implements an interface
+ * by having the right methods, and nothing in the source says so. Computing it
+ * needs full method-set comparison, which is R3 evidence, and guessing it from
+ * name similarity would be exactly the kind of edge that corrupts every layer
+ * above. `IMPLEMENTS` is therefore never emitted, and `capabilities()` says so.
+ * Embedding *is* explicit and becomes `INHERITS`.
+ *
+ * `:=` with anything but a composite literal, dot imports, and any receiver that
+ * is not a written name all go to the ledger with their reason.
+ */
+import { edgeId, endpointQsp, nodeId, normaliseEndpointPath, symbolQsp, testCaseQsp, } from "@descryy/ir";
+import { isUniverse } from "./parse.js";
+import { endpointFor } from "./client.js";
+export const LANGUAGE = "go";
+const CONFIDENCE = { 0: 0.5, 1: 0.7, 2: 0.9, 3: 0.95 };
+const REASONS = {
+    outside: "names a package this run did not analyse — the standard library, a module in the build " +
+        "cache, or a directory outside the analysed set. A scope boundary, not an analysis gap.",
+    unmodelled: "the package is in the analysed set but declares no such symbol — most often a method " +
+        "promoted from an embedded type this run did not read. An analysis gap.",
+    untypedReceiver: "the receiver's type is not written down at this reference: a `:=` whose right-hand side " +
+        "is not a composite literal, a chained call, or a name declared twice with different types.",
+    dotImport: "reached through a dot import, which binds a whole package into this file's scope. Telling " +
+        "such a name from a package-local one needs the imported package's declarations.",
+    noImportPath: "no go.mod covers this directory, so the package has no import path and nothing else can " +
+        "name it. Disclosed rather than given an invented identity.",
+    unknownName: "no declaration for this name in the package, its imports, or the analysed set.",
+    routeIdCollision: "this route's method and path are identical to one already emitted, so it collapsed onto " +
+        "the same API_ROUTE node and this declaration's own SERVES_API edge and location were " +
+        "dropped. The endpoint is real; this specific declaration is not the one the graph kept.",
+};
+/** How many hops of `var A = B; var B = C` to follow before giving up. */
+const ALIAS_PASSES = 4;
+/**
+ * The namespace a file's declarations belong to.
+ *
+ * Usually the import path — but not always, and the exception is written down.
+ * Go's **external test package** is a second package living in the same
+ * directory: `package storage_test` beside `package storage`. It is a distinct
+ * namespace that must import its neighbour by path like anybody else, and it is
+ * legal for it to redeclare a name the neighbour already has.
+ *
+ * Treating the directory as the namespace collapsed both `contextDone` and
+ * `makeInt64Pointer` on prometheus — `promql/engine.go` and
+ * `promql/engine_test.go` each declare one, two different functions with one
+ * node id, and the build-constraint disclosure quietly absorbed the collision.
+ * That is the same defect the Java source-set anchoring fixed, arriving through
+ * a different door.
+ *
+ * The rule is Go's own, not a heuristic: an external test package exists only in
+ * `_test.go` files and only under a package clause ending in `_test`. Its name
+ * carries a `:test` suffix, which no import path can contain — so nothing else
+ * can ever name these symbols, which is exactly true of them.
+ */
+function namespaceOf(unit) {
+    return unit.file.endsWith("_test.go") && unit.packageName.endsWith("_test")
+        ? `${unit.importPath}:test`
+        : unit.importPath;
+}
+export function extract(input) {
+    const nodes = [];
+    const edges = [];
+    const unresolved = [];
+    const seenEdge = new Set();
+    const scope = input.scope;
+    const push = (edge, level) => {
+        if (level > input.reached)
+            return false;
+        if (edge.from === edge.to)
+            return true;
+        const key = edgeId(edge.from, edge.to, edge.type);
+        if (seenEdge.has(key))
+            return true;
+        seenEdge.add(key);
+        edges.push({
+            ...edge,
+            producedBy: input.producedBy,
+            resolution: level,
+            confidence: CONFIDENCE[level] ?? 0.5,
+        });
+        return true;
+    };
+    const ledger = (from, edgeType, rawTarget, unit, line, reason, attrs) => {
+        unresolved.push({
+            fromNodeId: from,
+            edgeType,
+            rawTarget: rawTarget.slice(0, 120),
+            file: unit.file,
+            line,
+            producedBy: input.producedBy,
+            reason,
+            ...(attrs === undefined ? {} : { attrs }),
+        });
+    };
+    // -------------------------------------------------------------------------
+    // Nodes
+    // -------------------------------------------------------------------------
+    const packages = new Map();
+    const moduleIdOf = new Map();
+    /**
+     * Node id -> the other files declaring that symbol under a different build
+     * constraint. Attached to the node afterwards, so the graph states that a
+     * choice was made rather than appearing to have found only one declaration.
+     */
+    const alternates = new Map();
+    /** Subtest -> its node id, for the second pass that emits its edges. */
+    const subtestIds = new Map();
+    /**
+     * Two `t.Run` calls with the same literal name under one test are legal and
+     * are two different subtests. `occurrence` keeps both instead of collapsing
+     * them, exactly as it does for a repeated `it("…")` title.
+     */
+    const testOccurrence = new Map();
+    const describe = (unit) => unit.buildConstraint === undefined ? unit.file : `${unit.file} (//go:build ${unit.buildConstraint})`;
+    for (const unit of input.files) {
+        if (unit.importPath === "")
+            continue;
+        const namespace = namespaceOf(unit);
+        let pkg = packages.get(namespace);
+        if (pkg === undefined) {
+            pkg = { importPath: namespace, types: new Map(), funcs: new Map(), files: [] };
+            packages.set(namespace, pkg);
+        }
+        pkg.files.push(unit);
+        // The file is the MODULE, as in every other adapter. Go's importable unit is
+        // the package, but a fileless MODULE is not representable — the Normaliser
+        // requires a source file for every node type outside DEC-014's three — so
+        // the package lives in the qualified symbol path instead of in a node.
+        const stem = unit.file.slice(unit.file.lastIndexOf("/") + 1).replace(/\.go$/, "");
+        const moduleId = nodeId(scope, "MODULE", symbolQsp(namespace, [stem]), LANGUAGE);
+        moduleIdOf.set(unit.file, moduleId);
+        nodes.push({
+            id: moduleId,
+            type: "MODULE",
+            name: `${stem}.go`,
+            file: unit.file,
+            range: { startLine: 1, endLine: 1 },
+            language: LANGUAGE,
+            producedBy: input.producedBy,
+            resolution: 0,
+            attrs: unit.hasError ? { parsedWithErrors: true } : {},
+        });
+        for (const type of unit.types) {
+            const id = nodeId(scope, "CLASS", symbolQsp(namespace, [type.name]), LANGUAGE);
+            // A name declared twice in one package does not compile — *unless* the two
+            // declarations sit behind mutually exclusive build constraints, which is
+            // legal and common: `gin` declares `Binding` in both `binding.go`
+            // (`!nomsgpack`) and `binding_nomsgpack.go` (`nomsgpack`). Exactly one is
+            // ever compiled and this adapter is not told which, so the symbol is one
+            // node and the alternatives are disclosed on it.
+            const existing = pkg.types.get(type.name);
+            if (existing !== undefined) {
+                alternates.set(id, [...(alternates.get(id) ?? []), describe(unit)]);
+                continue;
+            }
+            pkg.types.set(type.name, { id, type, unit });
+            nodes.push({
+                id,
+                type: "CLASS",
+                name: type.name,
+                file: unit.file,
+                range: { startLine: type.startLine, endLine: type.endLine },
+                language: LANGUAGE,
+                producedBy: input.producedBy,
+                resolution: 0,
+                attrs: { declarationForm: type.form },
+            });
+        }
+        for (const fn of unit.funcs) {
+            const isCase = fn.isTest;
+            const id = isCase
+                ? nodeId(scope, "TEST_CASE", testCaseQsp(namespace, [], fn.name), LANGUAGE)
+                : nodeId(scope, "FUNCTION", symbolQsp(namespace, fn.key.split(".")), LANGUAGE);
+            if (pkg.funcs.has(fn.key)) {
+                alternates.set(id, [...(alternates.get(id) ?? []), describe(unit)]);
+                continue;
+            }
+            pkg.funcs.set(fn.key, { id, fn, unit });
+            nodes.push({
+                id,
+                type: isCase ? "TEST_CASE" : "FUNCTION",
+                name: fn.name,
+                file: unit.file,
+                range: { startLine: fn.startLine, endLine: fn.endLine },
+                language: LANGUAGE,
+                producedBy: input.producedBy,
+                resolution: 0,
+                attrs: fn.receiver === undefined ? {} : { receiver: fn.receiver },
+            });
+            // A subtest is a test case in its own right — `go test` names it, runs it
+            // and reports it separately — so it is a node, and the test it sits in is
+            // its suite. Dropping the suite would drop half of its identity (DEC-011).
+            for (const subtest of fn.subtests) {
+                const title = `${namespace}::${[...subtest.suite, subtest.name].join("::")}`;
+                const occurrence = (testOccurrence.get(title) ?? 0) + 1;
+                testOccurrence.set(title, occurrence);
+                const subtestId = nodeId(scope, "TEST_CASE", testCaseQsp(namespace, subtest.suite, subtest.name, occurrence), LANGUAGE);
+                subtestIds.set(subtest, subtestId);
+                nodes.push({
+                    id: subtestId,
+                    type: "TEST_CASE",
+                    name: subtest.name,
+                    file: unit.file,
+                    range: { startLine: subtest.startLine, endLine: subtest.endLine },
+                    language: LANGUAGE,
+                    producedBy: input.producedBy,
+                    resolution: 0,
+                    attrs: { suite: subtest.suite },
+                });
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Resolution
+    // -------------------------------------------------------------------------
+    /** A written type name, split into its package qualifier and its own name. */
+    const split = (written) => {
+        const cut = written.indexOf(".");
+        if (cut === -1)
+            return { name: written };
+        return { qualifier: written.slice(0, cut), name: written.slice(cut + 1) };
+    };
+    const resolveType = (unit, written) => {
+        const { qualifier, name } = split(written);
+        if (qualifier === undefined) {
+            // The whole package, not just this file — Go's defining scope rule.
+            const own = packages.get(namespaceOf(unit))?.types.get(name);
+            if (own !== undefined)
+                return { declared: own };
+            return { reason: REASONS.unknownName };
+        }
+        const path = unit.imports.get(qualifier);
+        if (path === undefined)
+            return { reason: REASONS.outside };
+        const target = packages.get(path)?.types.get(name);
+        return target === undefined ? { reason: REASONS.outside } : { declared: target };
+    };
+    /**
+     * A method on a type, following embedded types the way Go promotes them.
+     *
+     * Promotion is the one place Go's implicit behaviour is worth following,
+     * because embedding is written down: `struct { Base }` says so in the source.
+     * Interface satisfaction is not written down anywhere and is not followed.
+     */
+    const findMethod = (start, name, depth = 0) => {
+        if (depth > 8)
+            return undefined;
+        const pkg = packages.get(namespaceOf(start.unit));
+        const direct = pkg?.funcs.get(`${start.type.name}.${name}`);
+        if (direct !== undefined)
+            return direct;
+        for (const embedded of start.type.embeds) {
+            const resolved = resolveType(start.unit, embedded);
+            if (!("declared" in resolved))
+                continue;
+            const found = findMethod(resolved.declared, name, depth + 1);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    };
+    /** A field on a type, following embedding the way Go promotes it. */
+    const findField = (start, name, depth = 0) => {
+        if (depth > 8)
+            return undefined;
+        const direct = start.type.fields.get(name);
+        if (direct !== undefined)
+            return direct;
+        for (const embedded of start.type.embeds) {
+            const resolved = resolveType(start.unit, embedded);
+            if (!("declared" in resolved))
+                continue;
+            const found = findField(resolved.declared, name, depth + 1);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    };
+    /**
+     * A package-level value's written type, from any file of the same package.
+     *
+     * Go's package scope is shared across files completely, so a `var` declared
+     * in one file types a reference in another. Searching only the reference's
+     * own file would reproduce the wrong scope.
+     */
+    const packageVarType = (unit, name) => {
+        const pkg = packages.get(namespaceOf(unit));
+        for (const file of pkg?.files ?? []) {
+            const written = file.packageVars.get(name);
+            if (written !== undefined)
+                return written;
+        }
+        return undefined;
+    };
+    /**
+     * The element type of a collection: `[]Order` and `map[string]Order` -> `Order`.
+     *
+     * Only the two forms that write the element type down. A channel or a generic
+     * instantiation is left alone rather than guessed at.
+     */
+    const elementOf = (written) => {
+        const slice = /^\[\s*\d*\s*\]\s*\*?(.+)$/.exec(written);
+        if (slice?.[1] !== undefined)
+            return slice[1].trim();
+        const map = /^map\[[^\]]*\]\s*\*?(.+)$/.exec(written);
+        if (map?.[1] !== undefined)
+            return map[1].trim();
+        return undefined;
+    };
+    /**
+     * The type of a receiver written as `x`, `x.field`, or `x.field.field`.
+     *
+     * Every hop reads a declared type: the local's own, then the field's, out of
+     * the struct declaration. `enh.lb.Set(…)` and `it.br.readVarint()` are the
+     * shape — four of the eleven measured recall misses across gin and prometheus
+     * — and Java closed the same gap with the same evidence.
+     */
+    const typeOfPath = (unit, scope, path, depth = 0) => {
+        const parts = path.split(".");
+        const head = parts[0];
+        if (head === undefined)
+            return { reason: REASONS.untypedReceiver };
+        // A function-local name first, then a package-level one. Package scope was
+        // never consulted, so `var JSON = jsonBinding{}` followed by `JSON.Bind(…)`
+        // read as an untyped receiver even though the type is written two lines up.
+        const written = scope.locals.get(head) ?? packageVarType(unit, head);
+        let current;
+        if (written !== undefined && written !== null) {
+            current = resolveType(unit, written);
+        }
+        else {
+            const fromCall = resultTypeOf(unit, scope, head, depth);
+            if (fromCall === undefined)
+                return { reason: REASONS.untypedReceiver };
+            current = fromCall;
+        }
+        for (const field of parts.slice(1)) {
+            if (!("declared" in current))
+                return current;
+            const fieldType = findField(current.declared, field);
+            if (fieldType === undefined || fieldType === null)
+                return { reason: REASONS.untypedReceiver };
+            current = resolveType(current.declared.unit, fieldType);
+        }
+        return current;
+    };
+    /**
+     * The type a `x, err := f(…)` binding got from `f`'s declared results.
+     *
+     * The result type is written in the *callee's* file, so it is resolved against
+     * the callee's unit — a bare `Config` there means that package's `Config`.
+     * `depth` stops a mutually recursive pair of bindings from looping.
+     */
+    const resultTypeOf = (unit, scope, name, depth) => {
+        if (depth > 4)
+            return undefined;
+        const binding = scope.pending.get(name);
+        if (binding === undefined)
+            return undefined;
+        let callee;
+        if (binding.receiver === undefined) {
+            callee = packages.get(namespaceOf(unit))?.funcs.get(binding.name);
+        }
+        else {
+            const path = unit.imports.get(binding.receiver);
+            if (path !== undefined) {
+                callee = packages.get(path)?.funcs.get(binding.name);
+            }
+            else {
+                // `x := y.Method(…)` — the callee is itself reached through a value.
+                const owner = typeOfPath(unit, scope, binding.receiver, depth + 1);
+                if ("declared" in owner)
+                    callee = findMethod(owner.declared, binding.name);
+            }
+        }
+        if (callee === undefined)
+            return undefined;
+        const written = callee.fn.results[binding.index];
+        if (written === undefined)
+            return undefined;
+        return resolveType(callee.unit, written);
+    };
+    /** A written function name — bare or `pkg.Name` — against the analysed set. */
+    const resolveFuncName = (unit, written) => {
+        const { qualifier, name } = split(written);
+        if (qualifier === undefined)
+            return packages.get(namespaceOf(unit))?.funcs.get(name);
+        const path = unit.imports.get(qualifier);
+        return path === undefined ? undefined : packages.get(path)?.funcs.get(name);
+    };
+    /**
+     * Re-export bindings: `var ValidateOrder = validation.ValidateOrder`.
+     *
+     * The binding is registered under the *target's* declaration, so a call
+     * through it terminates at the definition and no node is created for the
+     * binding itself — which is exactly what golden 03 asserts.
+     *
+     * A real declaration always wins; Go would not compile both anyway. A binding
+     * whose target is not a function in the analysed set simply does not bind, and
+     * nothing is filed: a package-level `var` is usually an ordinary value, and
+     * filing every one of them as a failed edge would claim they were candidates.
+     */
+    for (let pass = 0; pass < ALIAS_PASSES; pass += 1) {
+        let bound = 0;
+        for (const unit of input.files) {
+            const pkg = packages.get(namespaceOf(unit));
+            if (pkg === undefined)
+                continue;
+            for (const alias of unit.aliases) {
+                if (pkg.funcs.has(alias.name))
+                    continue;
+                const target = resolveFuncName(unit, alias.target);
+                if (target === undefined)
+                    continue;
+                pkg.funcs.set(alias.name, target);
+                bound += 1;
+            }
+        }
+        if (bound === 0)
+            break;
+    }
+    // -------------------------------------------------------------------------
+    // Edges
+    // -------------------------------------------------------------------------
+    /** The caller's half of the HTTP boundary, minted with the routes below. */
+    const clientCallSites = [];
+    for (const unit of input.files) {
+        const moduleId = moduleIdOf.get(unit.file);
+        if (moduleId === undefined) {
+            continue;
+        }
+        // IMPORTS. Go imports a *package*, and a package is its files — so the edge
+        // fans out to each file of the target. That is not an approximation: a file
+        // importing a package depends on every declaration in it, which is exactly
+        // what blast radius needs to traverse.
+        for (const each of unit.importPaths) {
+            const target = packages.get(each.path);
+            if (target === undefined) {
+                ledger(moduleId, "IMPORTS", each.path, unit, each.line, REASONS.outside);
+                continue;
+            }
+            for (const file of target.files) {
+                const id = moduleIdOf.get(file.file);
+                if (id !== undefined)
+                    push({ from: moduleId, to: id, type: "IMPORTS" }, 1);
+            }
+        }
+        for (const type of unit.types) {
+            const declared = packages.get(namespaceOf(unit))?.types.get(type.name);
+            if (declared === undefined || declared.unit.file !== unit.file)
+                continue;
+            for (const embedded of type.embeds) {
+                const resolved = resolveType(unit, embedded);
+                if ("declared" in resolved) {
+                    if (!push({ from: declared.id, to: resolved.declared.id, type: "INHERITS" }, 2)) {
+                        ledger(declared.id, "INHERITS", embedded, unit, type.startLine, REASONS.unknownName);
+                    }
+                    continue;
+                }
+                ledger(declared.id, "INHERITS", embedded, unit, type.startLine, resolved.reason);
+            }
+            for (const ref of type.typeRefs)
+                emitTypeRef(declared.id, unit, ref);
+        }
+        for (const fn of unit.funcs) {
+            const declared = packages.get(namespaceOf(unit))?.funcs.get(fn.key);
+            if (declared === undefined || declared.unit.file !== unit.file)
+                continue;
+            emitRefs(declared.id, fn, fn.isTest, unit);
+            for (const subtest of fn.subtests) {
+                const subtestId = subtestIds.get(subtest);
+                if (subtestId !== undefined)
+                    emitRefs(subtestId, subtest, true, unit);
+            }
+            // The caller's half of the HTTP boundary — DEC-262's fork, Go's half.
+            // Collected here, where the enclosing FUNCTION's own id is finally known,
+            // and emitted with the routes below so both halves mint one API_ENDPOINT.
+            for (const call of fn.clientCalls)
+                clientCallSites.push({ ...call, fromId: declared.id });
+            for (const refusal of fn.clientRefusals) {
+                ledger(declared.id, "USES_API", refusal.raw, unit, refusal.line, refusal.reason, 
+                // Unset `refusalClass` stays legal and means unclassified — DEC-242 — so
+                // `attrs` is omitted entirely rather than sent with an `undefined` field.
+                refusal.refusalClass === undefined
+                    ? undefined
+                    : {
+                        blockedBy: refusal.blockedBy,
+                        refusalClass: refusal.refusalClass,
+                        ...(refusal.argumentKind === undefined ? {} : { argumentKind: refusal.argumentKind }),
+                    });
+            }
+        }
+    }
+    function emitRefs(from, scope, isTest, unit) {
+        for (const ref of scope.refs) {
+            if (ref.kind === "type") {
+                emitTypeRef(from, unit, ref);
+                continue;
+            }
+            if (ref.kind === "member") {
+                // `x.Field` where `x` is a variable is a field read, not a dependency
+                // on a type. Nothing is emitted and nothing is filed — the ledger
+                // records references that could have been edges, and this was never a
+                // candidate.
+                if (ref.receiver !== undefined && scope.locals.has(ref.receiver))
+                    continue;
+                emitTypeRef(from, unit, ref);
+                continue;
+            }
+            emitCall(from, scope, isTest, unit, ref);
+        }
+    }
+    function emitTypeRef(from, unit, ref) {
+        const resolved = resolveType(unit, ref.name);
+        if ("declared" in resolved) {
+            if (!push({ from, to: resolved.declared.id, type: "USES_TYPE" }, 2)) {
+                ledger(from, "USES_TYPE", ref.name, unit, ref.line, REASONS.unknownName);
+            }
+            return;
+        }
+        ledger(from, "USES_TYPE", ref.name, unit, ref.line, resolved.reason);
+    }
+    /**
+     * `T(x)` — a conversion, which Go spells exactly like a call.
+     *
+     * Safe because Go has one namespace per package: a name that resolves to a
+     * declared type cannot also be a function, so this is not a guess between two
+     * readings. The local check is the one real hazard — a variable may shadow a
+     * type name, and then the call is a call.
+     */
+    function emitConversion(from, scope, unit, ref, pkg) {
+        if (scope.locals.has(ref.name))
+            return false;
+        const type = pkg?.types.get(ref.name);
+        if (type === undefined)
+            return false;
+        if (!push({ from, to: type.id, type: "USES_TYPE" }, 2)) {
+            ledger(from, "USES_TYPE", ref.raw, unit, ref.line, REASONS.unknownName);
+        }
+        return true;
+    }
+    /** A method call whose receiver's type the site itself states, or a call result. */
+    function emitAgainstOwner(from, unit, ref, edgeType, owner) {
+        if (!("declared" in owner)) {
+            ledger(from, "CALLS", ref.raw, unit, ref.line, owner.reason);
+            return;
+        }
+        const target = findMethod(owner.declared, ref.name);
+        if (target === undefined) {
+            ledger(from, "CALLS", ref.raw, unit, ref.line, REASONS.unmodelled);
+            return;
+        }
+        if (!push({ from, to: target.id, type: edgeType }, 2)) {
+            ledger(from, "CALLS", ref.raw, unit, ref.line, REASONS.unknownName);
+        }
+    }
+    function emitCall(from, scope, isTest, unit, ref) {
+        const edgeType = isTest ? "TESTS" : "CALLS";
+        const receiver = ref.receiver;
+        // `p.(*listPostings).Len()` and `(IndentedJSON{data}).Render(w)` — the site
+        // states the receiver's type, so nothing is inferred.
+        if (ref.receiverType !== undefined) {
+            emitAgainstOwner(from, unit, ref, edgeType, resolveType(unit, ref.receiverType));
+            return;
+        }
+        // `xs[i].M()` — the element type is written in the collection's own
+        // declaration, so following it is resolution rather than inference. A
+        // collection whose element type is not written down (a channel, a generic
+        // instantiation) falls through to the ledger unchanged.
+        if (ref.receiverIndex !== undefined) {
+            const collection = scope.locals.get(ref.receiverIndex) ?? packageVarType(unit, ref.receiverIndex);
+            const element = collection === undefined || collection === null ? undefined : elementOf(collection);
+            if (element === undefined) {
+                ledger(from, "CALLS", ref.raw, unit, ref.line, REASONS.untypedReceiver);
+                return;
+            }
+            emitAgainstOwner(from, unit, ref, edgeType, resolveType(unit, element));
+            return;
+        }
+        // `engine().RunUnix(file)` — the receiver is a call result, and the result
+        // type is written in the callee's signature.
+        if (ref.receiverCall !== undefined) {
+            const binding = ref.receiverCall;
+            let callee;
+            if (binding.receiver === undefined) {
+                callee = packages.get(namespaceOf(unit))?.funcs.get(binding.name);
+            }
+            else {
+                const path = unit.imports.get(binding.receiver);
+                if (path !== undefined)
+                    callee = packages.get(path)?.funcs.get(binding.name);
+                else {
+                    const owner = typeOfPath(unit, scope, binding.receiver);
+                    if ("declared" in owner)
+                        callee = findMethod(owner.declared, binding.name);
+                }
+            }
+            const written = callee?.fn.results[0];
+            if (callee === undefined || written === undefined) {
+                ledger(from, "CALLS", ref.raw, unit, ref.line, REASONS.untypedReceiver);
+                return;
+            }
+            emitAgainstOwner(from, unit, ref, edgeType, resolveType(callee.unit, written));
+            return;
+        }
+        // Unqualified: a package-level function, visible across every file of the
+        // package without any import.
+        if (receiver === undefined) {
+            const own = packages.get(namespaceOf(unit));
+            const target = own?.funcs.get(ref.name);
+            if (target === undefined) {
+                if (emitConversion(from, scope, unit, ref, own))
+                    return;
+                // `len(x)`, `append(…)`, `int64(n)` — the universe block, checked only
+                // after the package's own declarations because a package may legally
+                // shadow a builtin. Filing these said "no declaration for this name",
+                // which is not merely unhelpful but false, about 11,000 times on
+                // prometheus. The same fix `baseTypeName` already had, on the other side.
+                if (isUniverse(ref.name))
+                    return;
+                ledger(from, "CALLS", ref.raw, unit, ref.line, REASONS.unknownName);
+                return;
+            }
+            if (!push({ from, to: target.id, type: edgeType }, 2)) {
+                ledger(from, "CALLS", ref.raw, unit, ref.line, REASONS.unknownName);
+            }
+            return;
+        }
+        if (receiver === "(computed)") {
+            ledger(from, "CALLS", ref.raw, unit, ref.line, REASONS.untypedReceiver);
+            return;
+        }
+        // `pkg.F()` — the receiver is an imported package rather than a value.
+        const imported = receiver.includes(".") ? undefined : unit.imports.get(receiver);
+        if (imported !== undefined) {
+            const other = packages.get(imported);
+            const target = other?.funcs.get(ref.name);
+            if (target === undefined) {
+                if (emitConversion(from, scope, unit, ref, other))
+                    return;
+                ledger(from, "CALLS", ref.raw, unit, ref.line, REASONS.outside);
+                return;
+            }
+            if (!push({ from, to: target.id, type: edgeType }, 2)) {
+                ledger(from, "CALLS", ref.raw, unit, ref.line, REASONS.unknownName);
+            }
+            return;
+        }
+        // `x.M()`, `x.field.M()` — the receiver is a value whose type is written
+        // down, here or in the declaration of whatever it was taken from.
+        const owner = typeOfPath(unit, scope, receiver);
+        if (!("declared" in owner)) {
+            ledger(from, "CALLS", ref.raw, unit, ref.line, owner.reason);
+            return;
+        }
+        const target = findMethod(owner.declared, ref.name);
+        if (target === undefined) {
+            ledger(from, "CALLS", ref.raw, unit, ref.line, REASONS.unmodelled);
+            return;
+        }
+        if (!push({ from, to: target.id, type: edgeType }, 2)) {
+            ledger(from, "CALLS", ref.raw, unit, ref.line, REASONS.unknownName);
+        }
+    }
+    // Disclosure, not decoration: a symbol declared in several build variants has
+    // one node, and the node says which files it stood in for.
+    const disclosed = nodes.map((node) => {
+        const others = alternates.get(node.id);
+        if (others === undefined)
+            return node;
+        return { ...node, attrs: { ...node.attrs, buildConstrainedAlternates: others } };
+    });
+    // -------------------------------------------------------------------------
+    // Routes — DEC-117. Last, because every ledger row is attributed to a MODULE
+    // that the pass above has already minted.
+    // -------------------------------------------------------------------------
+    const routeNodes = new Map();
+    const endpointNodes = new Map();
+    for (const unit of input.files) {
+        const moduleId = moduleIdOf.get(unit.file);
+        if (moduleId === undefined)
+            continue;
+        for (const refusal of unit.routeRefusals) {
+            ledger(moduleId, "SERVES_API", refusal.rawTarget, unit, refusal.line, refusal.reason);
+        }
+        // R2 and no lower. Telling a router from an application is provenance, and a
+        // route emitted from the R0 or R1 rung is a claim stronger than the run that
+        // produced it — which the Normaliser rejects as RESOLUTION_EXCEEDS_BATCH.
+        if (input.reached < 2)
+            continue;
+        for (const route of unit.routes) {
+            const template = normaliseEndpointPath(route.template);
+            const name = `${route.method} ${route.template}`;
+            // Repo-scoped and template-as-written: which service serves a path is
+            // exactly what the join must not erase.
+            const routeId = nodeId(scope, "API_ROUTE", name, LANGUAGE);
+            if (!routeNodes.has(routeId)) {
+                routeNodes.set(routeId, {
+                    id: routeId,
+                    type: "API_ROUTE",
+                    name,
+                    file: unit.file,
+                    range: { startLine: route.line, endLine: route.line },
+                    language: LANGUAGE,
+                    producedBy: input.producedBy,
+                    resolution: 2,
+                    attrs: {
+                        method: route.method,
+                        pathTemplate: template,
+                        rawTemplate: route.template,
+                        written: route.written,
+                        framework: route.framework,
+                    },
+                });
+            }
+            else {
+                // A second declaration claiming the same method+path — real (two
+                // routers mapped to overlapping prefixes) rather than a bug in this
+                // reader, but silent until now: nothing distinguished it from
+                // "checked, only one declaration exists". Same write pattern named
+                // across five language adapters in `language-problems.md` §0.2 #10,
+                // fixed here the way `adapter-python`/`adapter-java` already fixed
+                // it — a ledger row on the collision branch, not a change to the
+                // underlying node-identity question (`DEC-A-routes-ts-reconciliation`).
+                ledger(moduleId, "SERVES_API", name, unit, route.line, REASONS.routeIdCollision);
+            }
+            // Workspace-scoped, fileless, language-less, and minted with the SAME
+            // endpointQsp every other producer uses — DEC-115's one hard constraint.
+            // Two producers that mint different ids do not conflict, they silently
+            // fail to join.
+            const endpointId = nodeId(scope, "API_ENDPOINT", endpointQsp(route.method, route.template), null);
+            if (!endpointNodes.has(endpointId)) {
+                endpointNodes.set(endpointId, {
+                    id: endpointId,
+                    type: "API_ENDPOINT",
+                    name: `${route.method} ${template}`,
+                    file: null,
+                    range: null,
+                    language: null,
+                    producedBy: input.producedBy,
+                    resolution: 2,
+                    attrs: { method: route.method, pathTemplate: template },
+                });
+            }
+            push({ from: routeId, to: endpointId, type: "SERVES_API" }, 2);
+        }
+    }
+    // --- gRPC routes — see `grpc.ts`'s own header for the wire-path-is-read, not-
+    // invented rationale and the `method: "RPC"` sentinel. Cross-file by nature:
+    // a `_FullMethodName` const and the `Register<Service>Server(...)` call site
+    // that uses it are almost always in different files, so this pass runs after
+    // every unit's own consts have been collected, not per-unit like HTTP routes.
+    if (input.reached >= 2) {
+        const grpcMethodsByNamespace = new Map();
+        for (const unit of input.files) {
+            if (unit.grpcMethodConsts.length === 0)
+                continue;
+            const namespace = namespaceOf(unit);
+            let byService = grpcMethodsByNamespace.get(namespace);
+            if (byService === undefined) {
+                byService = new Map();
+                grpcMethodsByNamespace.set(namespace, byService);
+            }
+            for (const found of unit.grpcMethodConsts) {
+                const list = byService.get(found.service) ?? [];
+                list.push({ method: found.method, path: found.path });
+                byService.set(found.service, list);
+            }
+        }
+        for (const unit of input.files) {
+            const moduleId = moduleIdOf.get(unit.file);
+            if (moduleId === undefined || unit.grpcRegistrations.length === 0)
+                continue;
+            for (const registration of unit.grpcRegistrations) {
+                const targetNamespace = registration.targetPackageAlias === undefined
+                    ? namespaceOf(unit)
+                    : unit.imports.get(registration.targetPackageAlias);
+                // An unresolved package, or a naming coincidence with no corroborating
+                // const in the resolved package, is not evidence — stay silent, the
+                // same standard `readCall` in `routes.ts` holds a bare `x.Get(...)` to.
+                const methods = targetNamespace === undefined ? undefined : grpcMethodsByNamespace.get(targetNamespace)?.get(registration.service);
+                if (methods === undefined || methods.length === 0)
+                    continue;
+                for (const method of methods) {
+                    const template = normaliseEndpointPath(method.path);
+                    const name = `RPC ${method.path}`;
+                    const routeId = nodeId(scope, "API_ROUTE", name, LANGUAGE);
+                    if (!routeNodes.has(routeId)) {
+                        routeNodes.set(routeId, {
+                            id: routeId,
+                            type: "API_ROUTE",
+                            name,
+                            file: unit.file,
+                            range: { startLine: registration.line, endLine: registration.line },
+                            language: LANGUAGE,
+                            producedBy: input.producedBy,
+                            resolution: 2,
+                            attrs: {
+                                method: "RPC",
+                                pathTemplate: template,
+                                rawTemplate: method.path,
+                                written: method.path,
+                                framework: "grpc",
+                            },
+                        });
+                    }
+                    else {
+                        // Same collision-disclosure fix as the HTTP route loop above —
+                        // §0.2 #10.
+                        ledger(moduleId, "SERVES_API", name, unit, registration.line, REASONS.routeIdCollision);
+                    }
+                    const endpointId = nodeId(scope, "API_ENDPOINT", endpointQsp("RPC", method.path), null);
+                    if (!endpointNodes.has(endpointId)) {
+                        endpointNodes.set(endpointId, {
+                            id: endpointId,
+                            type: "API_ENDPOINT",
+                            name: `RPC ${template}`,
+                            file: null,
+                            range: null,
+                            language: null,
+                            producedBy: input.producedBy,
+                            resolution: 2,
+                            attrs: { method: "RPC", pathTemplate: template },
+                        });
+                    }
+                    push({ from: routeId, to: endpointId, type: "SERVES_API" }, 2);
+                }
+            }
+        }
+    }
+    // --- The caller's half -----------------------------------------------------
+    //
+    // Mints into the SAME `endpointNodes` map, so a call to a route this run also
+    // read produces one node with two edges rather than two nodes with one each.
+    // R2 and no lower, same reason as routes above: an edge emitted from a rung
+    // the run did not reach is a claim stronger than the run that produced it.
+    if (input.reached >= 2) {
+        for (const call of clientCallSites) {
+            const endpoint = endpointFor(scope, call, input.producedBy, normaliseEndpointPath);
+            if (!endpointNodes.has(endpoint.id))
+                endpointNodes.set(endpoint.id, endpoint);
+            push({
+                from: call.fromId,
+                to: endpoint.id,
+                type: "USES_API",
+                attrs: { callerKind: call.callerKind, via: call.method },
+            }, 2);
+        }
+    }
+    const withRoutes = [...disclosed, ...routeNodes.values(), ...endpointNodes.values()];
+    return { nodes: withRoutes, edges, unresolved };
+}
+export { REASONS };
+//# sourceMappingURL=extract.js.map