@descryy/adapter-java 0.1.0

package/dist/extract.js

@@ -0,0 +1,892 @@
+/**
+ * Java units to Canonical IR.
+ *
+ * ## Why a breadth adapter reaches further in Java than in most languages
+ *
+ * Every import is explicit and fully qualified, every field and parameter
+ * carries a written type, and a public type's simple name is its file's name.
+ * None of that needs a type checker to read, so `repo.findById(id)` resolves
+ * from the declaration `private final OwnerRepository repo` alone — a call
+ * through a receiver, which in TypeScript needed R3.
+ *
+ * That is read as **R2 evidence, and never R3**. R2 is a reference resolved to a
+ * specific definition, which is exactly what happens here — the level names the
+ * evidence, not the machinery, and Java hands over the same evidence an LSP
+ * would without one being run. R3 is a *checked shape*, and a written annotation
+ * is not one: it can be shadowed, it can be generic, and nothing here verifies
+ * which overload the compiler would select. Claiming R3 for a name-level fact is
+ * the confusion DEC-058 was written about, where 83% of an adapter's edges
+ * claimed a level they had not earned.
+ *
+ * `IMPORTS` stays at R1. An import is module resolution and nothing more.
+ *
+ * ## What is deliberately not resolved
+ *
+ * `var` declarations, chained calls whose receiver is another call, generic type
+ * variables, and any name reachable only through a wildcard import that matches
+ * more than one analysed type. Each goes to the ledger with its reason. A
+ * missing edge is a disclosed gap; a guessed one corrupts every layer above.
+ */
+import { edgeId, endpointQsp, nodeId, normaliseEndpointPath, symbolQsp, testCaseQsp, } from "@descryy/ir";
+import { jpaModels } from "./jpa.js";
+import { jaxrsRoutes, springRoutes } from "./spring.js";
+import { clientCalls, endpointFor } from "./client.js";
+export const LANGUAGE = "java";
+/** Confidence by the level an edge's evidence earned, never the level reached. */
+const CONFIDENCE = { 0: 0.5, 1: 0.7, 2: 0.9, 3: 0.95 };
+/** A compilation unit with no `package` declaration. Not a legal package name,
+ *  so it cannot collide with one. */
+export const DEFAULT_PACKAGE = "(default)";
+const REASONS = {
+    // The final sentence used to read "A scope boundary, not an analysis gap."
+    // Measured on `okhttp`: of the 458 `outside` entries naming a qualified type,
+    // **238 are declared in a `.kt` file in the same repository** — `OkHttpClient`,
+    // `Response`, `RequestBody`. They are not a scope boundary; they are a
+    // language this run cannot read, which is `CLAUDE.md` rule 6's *fourth*
+    // category. The adapter cannot tell the two apart — deciding needs a
+    // repo-wide, cross-adapter declaration index it is not given — so it must
+    // stop claiming it can. `bench/cross-language-census.mjs`.
+    outside: "names a type this run did not analyse. Either a scope boundary — the JDK, a dependency " +
+        "on the classpath, a source root outside the analysed set — or a declaration this run " +
+        "could not read, in another language in this same repository. This adapter sees only " +
+        "Java sources and cannot tell the two apart.",
+    unmodelled: "the declaring type is in the analysed set but declares no such member — most often a " +
+        "member inherited from a supertype this run did not read. An analysis gap.",
+    untypedReceiver: "the receiver's type is not written down at this reference: a `var` declaration, a chained " +
+        "call, a generic type variable, or a name declared twice with different types.",
+    ambiguousWildcard: "reachable only through a wildcard import, and more than one analysed type matches the " +
+        "simple name. Resolving it would be a guess between equals.",
+    ambiguousDeclaration: "this fully-qualified name is declared in more than one module or source set, and none of " +
+        "them is the referring unit's own. Which one is on this code's classpath is a build fact " +
+        "this adapter does not read.",
+    unknownName: "no declaration for this simple name in the compilation unit, its imports, or its package.",
+    belowLevel: "resolved to a definition, but this run was capped below the level that evidence earns. " +
+        "Not an analysis gap and not a scope boundary — a limit the caller asked for.",
+    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.",
+};
+/**
+ * The qualified symbol path for a Java symbol.
+ *
+ * The Java package *is* the namespace, so no anchor has to be inferred the way a
+ * TypeScript package root does — DEC-047's entire problem does not exist here,
+ * and neither does DEC-077's duplicate-anchor collision. The nesting path is
+ * everything after the package: `Outer.Inner.method`.
+ */
+function qspFor(fqn, unit) {
+    const nested = unit.packageName !== "" && fqn.startsWith(`${unit.packageName}.`)
+        ? fqn.slice(unit.packageName.length + 1)
+        : fqn;
+    return symbolQsp(unit.identityPackage, nested.split("."));
+}
+/**
+ * Whether a unit's identity anchor names a test source set.
+ *
+ * `identityPackage` is `module/sourceSet/package` (`roots.ts`), so the source
+ * set is the second segment when there are three. A unit with no `src/` split
+ * has two segments and no source set, and returns false rather than guessing.
+ *
+ * `test`, `testFixtures` and `integrationTest` are the names Maven and Gradle
+ * declare, not a convention read off a path — the distinction `roots.ts`'s
+ * header exists for.
+ */
+function isTestSourceSet(identityPackage) {
+    const segments = identityPackage.split("/");
+    if (segments.length < 3)
+        return false;
+    return /^(test|.*[Tt]est.*)$/.test(segments[1] ?? "");
+}
+/**
+ * Choose among the candidates a scope produced, preferring the analysed unit's
+ * own identity package. Two survivors is genuinely ambiguous and is refused.
+ */
+function pick(from, candidates) {
+    if (candidates === undefined || candidates.length === 0)
+        return { reason: REASONS.outside };
+    const local = candidates.filter((each) => each.unit.identityPackage === from.identityPackage);
+    if (local.length === 1)
+        return { declared: local[0] };
+    if (candidates.length === 1)
+        return { declared: candidates[0] };
+    return { reason: REASONS.ambiguousDeclaration };
+}
+/**
+ * The scopes a written type name is searched in, in the order Java searches them.
+ *
+ * **Shared rather than written twice, and that is the point of pulling it out.**
+ * Two consumers now resolve a supertype name: the `INHERITS`/`IMPLEMENTS` edges,
+ * and JPA's `@MappedSuperclass` walk. A second copy of these rules would drift,
+ * and the failure it drifts into is not symmetric — an edge resolved by one rule
+ * and a column by another puts a **column on the wrong table**, which is a wrong
+ * answer rather than a missing one.
+ *
+ * `decides` marks a scope that settles the question even when it fails to
+ * resolve. An explicit single-type import is unambiguous by language rule, so a
+ * name it fails to resolve is not one a later scope may claim. Only the
+ * same-unit scope falls through, because a file may declare several types and
+ * only one of them can be the match.
+ */
+function scopesFor(index, unit, written) {
+    // A dotted name is one of two things and they are not distinguishable by
+    // spelling: `com.example.Order` is already fully qualified and needs no scope,
+    // `DiskLruCache.Snapshot` is a nested type named through its enclosing type
+    // and needs the *enclosing* name resolved first. Try the whole path as
+    // written, then resolve the head and re-attach the tail.
+    //
+    // Only the whole path used to be tried, so every reference to a repo-declared
+    // nested type was lost — 28 across the four corpora, `mall`'s `Criteria` ×19.
+    // `decides: true` on that single scope is what made it terminal.
+    if (written.includes(".")) {
+        const asWritten = index.get(written);
+        if (asWritten !== undefined)
+            return [{ candidates: asWritten, decides: true }];
+        const cut = written.lastIndexOf(".");
+        const head = written.slice(0, cut);
+        const tail = written.slice(cut + 1);
+        // The head is itself resolved by the normal rules — it may be an import, a
+        // same-package type, or another nested name — so this recurses rather than
+        // reimplementing the scope order a second time and letting the two drift.
+        const ordered = [];
+        for (const scope of scopesFor(index, unit, head)) {
+            for (const candidate of scope.candidates) {
+                const enclosing = candidate;
+                const fqn = enclosing.type?.fqn;
+                if (fqn === undefined)
+                    continue;
+                const nested = index.get(`${fqn}.${tail}`);
+                if (nested !== undefined)
+                    ordered.push({ candidates: nested, decides: true });
+            }
+        }
+        // Nothing found is a refusal, not a fallback to the bare tail. Resolving
+        // `A.B` as `B` is exactly the dropped qualifier this branch exists to stop.
+        return ordered.length > 0 ? ordered : [{ candidates: [], decides: true }];
+    }
+    const ordered = [];
+    // 1. Declared in this compilation unit, innermost first.
+    for (const type of unit.types) {
+        if (type.simpleName === written)
+            ordered.push({ candidates: index.get(type.fqn) ?? [], decides: false });
+    }
+    // 2. An explicit single-type import is unambiguous by language rule.
+    const imported = unit.singleTypeImports.get(written);
+    if (imported !== undefined) {
+        ordered.push({ candidates: index.get(imported) ?? [], decides: true });
+        return ordered;
+    }
+    // 3. Same package.
+    const samePackage = unit.packageName === "" ? written : `${unit.packageName}.${written}`;
+    const inPackage = index.get(samePackage);
+    if (inPackage !== undefined) {
+        ordered.push({ candidates: inPackage, decides: true });
+        return ordered;
+    }
+    // 4. Wildcard imports. Accepted only when exactly one analysed type matches:
+    //    two candidates is genuinely ambiguous in Java too, and picking one would
+    //    be a coin toss recorded as a fact.
+    const candidates = unit.wildcardImports.flatMap((wildcard) => [...(index.get(`${wildcard}.${written}`) ?? [])]);
+    if (candidates.length > 0)
+        ordered.push({ candidates, decides: true });
+    return ordered;
+}
+export function extract(input) {
+    const nodes = [];
+    const edges = [];
+    const unresolved = [];
+    const seenEdge = new Set();
+    const scope = input.scope;
+    /** Outbound HTTP calls, collected in the method loop and emitted with the routes. */
+    const clientCallSites = [];
+    /**
+     * Returns `false` when the edge's evidence outranks the level this run
+     * reached, so the caller can disclose the reference instead of dropping it.
+     *
+     * An edge may not claim a level the run did not reach — the Normaliser rejects
+     * it, and rightly: a run capped at R0 that emits R2 edges is claiming
+     * resolution it did not perform. Capping the number instead would be worse,
+     * because the edge would survive wearing a level its evidence never earned,
+     * which is DEC-058's defect exactly.
+     */
+    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 file = (unit, ref) => ({
+        file: unit.file,
+        line: ref.line,
+    });
+    const ledger = (from, edgeType, rawTarget, at, reason, attrs) => {
+        unresolved.push({
+            fromNodeId: from,
+            edgeType,
+            rawTarget: rawTarget.slice(0, 120),
+            file: at.file,
+            line: at.line,
+            producedBy: input.producedBy,
+            reason,
+            ...(attrs === undefined ? {} : { attrs }),
+        });
+    };
+    // -------------------------------------------------------------------------
+    // Nodes
+    // -------------------------------------------------------------------------
+    /**
+     * Fully-qualified Java name -> every analysed type that declares it.
+     *
+     * A list, not a single entry, and that is the whole lesson of the airbyte run:
+     * `io.airbyte.integrations.destination.redis.RedisDataFactory` is declared
+     * twice, in two source sets that never share a classpath. A `Map<string,
+     * Declared>` here silently keeps the last one and resolves every reference in
+     * both source sets to it — a wrong edge that no recall measurement can see,
+     * because the name was found.
+     */
+    const byFqn = new Map();
+    const byMember = new Map();
+    const moduleIdOf = new Map();
+    /** Simple name -> every analysed fully-qualified name that ends with it. */
+    const bySimpleName = new Map();
+    /**
+     * Every declared type, indexed before any node id exists — and it has to be.
+     *
+     * A JPA entity is a `MODEL` rather than a `CLASS`, and the id hashes the kind
+     * (DEC-004), so the kind must be settled before the id is minted. But settling
+     * it now needs `@MappedSuperclass` resolution *across* compilation units, and
+     * that needs an index. `byFqn` cannot be it, because `byFqn` holds ids.
+     *
+     * So the types are indexed twice, once without ids for the entity decision and
+     * once with them for the edges. The alternative was minting a `CLASS` id and
+     * rewriting it, which is the exact thing DEC-004 forbids.
+     */
+    const typesByFqn = new Map();
+    for (const unit of input.units) {
+        for (const type of unit.types) {
+            const bucket = typesByFqn.get(type.fqn);
+            if (bucket === undefined)
+                typesByFqn.set(type.fqn, [{ type, unit }]);
+            else
+                bucket.push({ type, unit });
+        }
+    }
+    /** A supertype name as written, resolved to its declaration. Same rules as edges. */
+    const resolveSuper = (unit, written) => {
+        for (const scope of scopesFor(typesByFqn, unit, written)) {
+            const found = pick(unit, scope.candidates);
+            if ("declared" in found)
+                return found.declared;
+            // An ambiguous supertype is refused rather than guessed: two candidates
+            // means two different tables, and picking one puts real columns on the
+            // wrong one.
+            if (scope.decides)
+                return undefined;
+        }
+        return undefined;
+    };
+    /**
+     * The entity map for the whole batch, resolved once before any id is minted.
+     *
+     * Keyed by `identityPackage::fqn` rather than by `fqn` alone, because a
+     * fully-qualified Java name is **not** unique across source sets — the airbyte
+     * duplicate that this file already records for `byFqn`. Keying on the fqn here
+     * would let a `@Entity` in one source set turn its namesake in another into a
+     * MODEL it never was.
+     */
+    const entitiesByType = new Map();
+    for (const unit of input.units) {
+        for (const model of jpaModels(unit, resolveSuper)) {
+            entitiesByType.set(`${unit.identityPackage}::${model.fqn}`, model);
+        }
+    }
+    for (const unit of input.units) {
+        const pkg = unit.identityPackage;
+        // The compilation unit is named by its *primary* type, which Java requires
+        // to match the file name. That is a symbol path, not a file path — DEC-004's
+        // rule is satisfied, and a moved file keeps its identity.
+        //
+        // `types[0]` was not that type. Nested declarations are appended before the
+        // type enclosing them, so a file whose outer class holds a private interface
+        // took its identity from the interface: `TeradataJdbcSourceAcceptanceTest.java`
+        // became the module `SqlConsumer`, a nested private interface on line 123.
+        // Two such files in one package would then share a module id.
+        //
+        // The stem is preferred because the language guarantees it names the public
+        // type; a top-level declaration is the fallback for a file with none, and the
+        // stem stands alone only when the file declares no top-level type at all.
+        const stem = unit.file.slice(unit.file.lastIndexOf("/") + 1).replace(/\.java$/, "");
+        const topLevel = unit.types.filter((each) => unit.packageName === ""
+            ? !each.fqn.includes(".")
+            : !each.fqn.slice(unit.packageName.length + 1).includes("."));
+        const unitName = topLevel.some((each) => each.simpleName === stem)
+            ? stem
+            : (topLevel[0]?.simpleName ?? stem);
+        const moduleId = nodeId(scope, "MODULE", symbolQsp(pkg, [unitName]), LANGUAGE);
+        moduleIdOf.set(unit.file, moduleId);
+        nodes.push({
+            id: moduleId,
+            type: "MODULE",
+            // The compilation unit is *named* with its extension and *identified*
+            // without one. Java requires a public type's simple name to equal its file
+            // name, so a bare `Status` is the name of both the module and the class it
+            // holds — and a corpus role bound on `(file, name)` then matches two nodes
+            // and correctly refuses to guess between them. `Status.java` is what a Java
+            // developer calls the unit and can never collide with a type.
+            name: `${unitName}.java`,
+            file: unit.file,
+            range: { startLine: 1, endLine: 1 },
+            language: LANGUAGE,
+            producedBy: input.producedBy,
+            resolution: 0,
+            attrs: unit.hasError ? { parsedWithErrors: true } : {},
+        });
+        // A JPA entity is a MODEL rather than a CLASS, and the node id hashes the
+        // kind (DEC-004) — so the kind has to be decided BEFORE the id is minted,
+        // not patched onto the node afterwards. Everything downstream reads the id
+        // out of `byFqn`, so one derivation keeps them in step. Resolved for the
+        // whole batch above, because inherited mappings cross compilation units.
+        for (const type of unit.types) {
+            const model = entitiesByType.get(`${unit.identityPackage}::${type.fqn}`);
+            const kind = model === undefined ? "CLASS" : "MODEL";
+            const id = nodeId(scope, kind, qspFor(type.fqn, unit), LANGUAGE);
+            const declaredAs = byFqn.get(type.fqn);
+            if (declaredAs === undefined)
+                byFqn.set(type.fqn, [{ id, type, unit }]);
+            else
+                declaredAs.push({ id, type, unit });
+            const bucket = bySimpleName.get(type.simpleName);
+            if (bucket === undefined)
+                bySimpleName.set(type.simpleName, [type.fqn]);
+            else
+                bucket.push(type.fqn);
+            const attrs = { declarationForm: type.kind };
+            if (model !== undefined) {
+                attrs["orm"] = "jpa";
+                if (model.table !== null)
+                    attrs["table"] = model.table;
+                // **Not gated on `input.reached`, and the exception is the point.** A
+                // mapped column is a declaration the framework itself enforces, not an
+                // inference, so its resolution is the evidence's rather than the run's
+                // (DEC-058) — the same reasoning adapter-python records for SQLAlchemy.
+                if (model.fields.length > 0)
+                    attrs["fields"] = model.fields;
+                if (model.undecided.length > 0)
+                    attrs["undecidedNullability"] = model.undecided;
+            }
+            nodes.push({
+                id,
+                type: kind,
+                name: type.simpleName,
+                file: unit.file,
+                range: { startLine: type.startLine, endLine: type.endLine },
+                language: LANGUAGE,
+                producedBy: input.producedBy,
+                resolution: 0,
+                attrs,
+            });
+            /**
+             * Overloads are one node, and the count is disclosed rather than hidden.
+             *
+             * A qualified symbol path carries no parameter types (DEC-011), so
+             * `getPet(String)` and `getPet(Integer)` name one symbol — and on
+             * `spring-petclinic` that produced three nodes sharing one id before this
+             * existed. Encoding parameters into the path would fix the collision by
+             * making Java's identity rule different from every other language's, which
+             * is the leak the IR boundary exists to prevent.
+             *
+             * What is lost is real and is stated: an edge into an overload set does not
+             * say which overload. That is a name-level fact, and DEC-058's rule caps it
+             * at the level its evidence earned.
+             */
+            const overloads = new Map();
+            for (const method of type.methods) {
+                const bucket = overloads.get(method.name);
+                if (bucket === undefined)
+                    overloads.set(method.name, [method]);
+                else
+                    bucket.push(method);
+            }
+            for (const [name, group] of overloads) {
+                const first = group[0];
+                // A `@Test` method is a test case, not a function that happens to be
+                // tested. Emitting both would put two nodes on one declaration and let a
+                // coverage query count it twice.
+                const isCase = group.some((each) => each.isTest);
+                const memberId = isCase
+                    ? nodeId(scope, "TEST_CASE", testCaseQsp(unit.identityPackage, [type.simpleName], name), LANGUAGE)
+                    : nodeId(scope, "FUNCTION", qspFor(first.fqn, unit), LANGUAGE);
+                byMember.set(`${unit.identityPackage}::${first.fqn}`, {
+                    id: memberId,
+                    method: first,
+                    ownerFqn: type.fqn,
+                });
+                // DEC-248: a CALLS edge out of this node can originate from *any*
+                // overload's body — `emitCall` below resolves a ref against its own
+                // `method` (the specific overload), not `member.method`, precisely so a
+                // ref found inside a later overload's body is attributed correctly to
+                // the shared symbol. A range pinned to `first`'s lines alone silently
+                // excludes every overload but the first, so an edge attributed to this
+                // node can point outside its own declared range — `spring-petclinic`'s
+                // `Owner.getPet(String)` was credited with a call that only exists in
+                // the neighbouring `getPet(Integer)` overload. The range now spans every
+                // overload in the group, so it always contains whichever one is the
+                // true source of an edge attributed to this node.
+                const startLine = Math.min(...group.map((each) => each.startLine));
+                const endLine = Math.max(...group.map((each) => each.endLine));
+                // Widening is only sound when the group's own declarations are what
+                // fill the span. Java does not require overloads — constructors above
+                // all — to sit next to each other, so the widened range can swallow an
+                // unrelated field or method declared in the gap between two of them.
+                // `language-problems.md` §3's row 5 named this a latent risk on top of
+                // the widening fix above; disclosed here rather than silently letting
+                // a change to that unrelated member attribute to this node in diff
+                // scoping.
+                const groupMembers = new Set(group);
+                const includesOtherMember = group.length > 1 &&
+                    (type.methods.some((each) => !groupMembers.has(each) && each.startLine > startLine && each.startLine < endLine) ||
+                        type.fieldDeclarations.some((field) => field.line > startLine && field.line < endLine));
+                nodes.push({
+                    id: memberId,
+                    type: isCase ? "TEST_CASE" : "FUNCTION",
+                    name: isCase ? `${type.simpleName}.${name}` : name,
+                    file: unit.file,
+                    range: { startLine, endLine },
+                    language: LANGUAGE,
+                    producedBy: input.producedBy,
+                    resolution: 0,
+                    attrs: {
+                        ...(group.length > 1 ? { overloads: group.length } : {}),
+                        ...(includesOtherMember ? { rangeIncludesOtherMembers: true } : {}),
+                    },
+                });
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Name resolution
+    // -------------------------------------------------------------------------
+    /**
+     * Pick the declaration of a fully-qualified name that the referring unit can
+     * actually see.
+     *
+     * Java's own rule is the classpath, which this adapter does not read. The
+     * approximation is the strictest one that cannot be wrong in the common case:
+     * a declaration in the same module and source set wins outright, one candidate
+     * overall is taken, and a genuine tie between two scopes is refused rather
+     * than broken arbitrarily.
+     */
+    /** Resolve a simple or qualified type name as written inside one unit. */
+    const resolveType = (unit, written) => {
+        for (const scope of scopesFor(byFqn, unit, written)) {
+            const found = pick(unit, scope.candidates);
+            if ("declared" in found)
+                return found;
+            if (scope.decides)
+                return found;
+        }
+        return { reason: bySimpleName.has(written) ? REASONS.unknownName : REASONS.outside };
+    };
+    /**
+     * The declared type of a field, following the scopes Java says are in scope.
+     *
+     * Two of them were missing, and both were found by the first recall
+     * measurement this project has taken rather than by any precision sample —
+     * a missing edge leaves nothing behind for a precision draw to land on.
+     *
+     * `viaThis` distinguishes `this.pet` from a bare `pet`. `this` names the
+     * instance, so it reaches the type's own fields and inherited ones and stops;
+     * a bare name additionally sees the *lexically enclosing* class's fields,
+     * which is how a `@Nested` test class reads the fields of the class holding it.
+     * Collapsing the two would resolve `this.x` against an outer class it cannot
+     * legally reach.
+     */
+    const fieldTypeOf = (owner, name, viaThis) => {
+        const search = [owner];
+        const seen = new Set();
+        if (!viaThis) {
+            // Lexically enclosing types, innermost first: `pkg.Outer.Inner` -> `pkg.Outer`.
+            let fqn = owner.type.fqn;
+            for (;;) {
+                const cut = fqn.lastIndexOf(".");
+                if (cut === -1)
+                    break;
+                fqn = fqn.slice(0, cut);
+                const enclosing = (byFqn.get(fqn) ?? []).find((each) => each.unit.identityPackage === owner.unit.identityPackage);
+                if (enclosing === undefined)
+                    continue;
+                search.push(enclosing);
+            }
+        }
+        while (search.length > 0) {
+            const current = search.shift();
+            const key = `${current.unit.identityPackage}::${current.type.fqn}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            if (current.type.fields.has(name)) {
+                const written = current.type.fields.get(name);
+                return written === null || written === undefined ? { poisoned: true } : { written };
+            }
+            for (const superName of [...current.type.extendsNames, ...current.type.implementsNames]) {
+                const resolved = resolveType(current.unit, superName);
+                if ("declared" in resolved)
+                    search.push(resolved.declared);
+            }
+        }
+        return undefined;
+    };
+    /** Find a method by name on a type or anywhere up its analysed supertype chain. */
+    const findMember = (start, name) => {
+        const seen = new Set();
+        const queue = [start];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            const key = `${current.unit.identityPackage}::${current.type.fqn}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const direct = byMember.get(`${key}.${name}`);
+            if (direct !== undefined)
+                return direct;
+            for (const superName of [...current.type.extendsNames, ...current.type.implementsNames]) {
+                const resolved = resolveType(current.unit, superName);
+                if ("declared" in resolved)
+                    queue.push(resolved.declared);
+            }
+        }
+        return undefined;
+    };
+    // -------------------------------------------------------------------------
+    // Edges
+    // -------------------------------------------------------------------------
+    for (const unit of input.units) {
+        const moduleId = moduleIdOf.get(unit.file);
+        if (moduleId === undefined)
+            continue;
+        // IMPORTS — module to module. A wildcard import names a package and not a
+        // compilation unit, so it has nothing to point at and is disclosed instead.
+        for (const each of unit.importLines) {
+            if (each.wildcard) {
+                ledger(moduleId, "IMPORTS", `${each.fqn}.*`, { file: unit.file, line: each.line }, REASONS.ambiguousWildcard);
+                continue;
+            }
+            // A static import names a member; the module it comes from is its owner.
+            const ownerFqn = byFqn.has(each.fqn) ? each.fqn : each.fqn.slice(0, each.fqn.lastIndexOf("."));
+            const target = pick(unit, byFqn.get(ownerFqn));
+            if ("reason" in target) {
+                ledger(moduleId, "IMPORTS", each.fqn, { file: unit.file, line: each.line }, target.reason);
+                continue;
+            }
+            const targetModule = moduleIdOf.get(target.declared.unit.file);
+            if (targetModule !== undefined)
+                push({ from: moduleId, to: targetModule, type: "IMPORTS" }, 1);
+        }
+        for (const type of unit.types) {
+            const declared = (byFqn.get(type.fqn) ?? []).find((each) => each.unit.file === unit.file && each.type.fqn === type.fqn);
+            if (declared === undefined)
+                continue;
+            const relate = (names, edgeType) => {
+                for (const written of names) {
+                    const resolved = resolveType(unit, written);
+                    if ("declared" in resolved) {
+                        if (push({ from: declared.id, to: resolved.declared.id, type: edgeType }, 2))
+                            continue;
+                        ledger(declared.id, edgeType, written, { file: unit.file, line: type.startLine }, REASONS.belowLevel);
+                        continue;
+                    }
+                    ledger(declared.id, edgeType, written, { file: unit.file, line: type.startLine }, resolved.reason);
+                }
+            };
+            relate(type.extendsNames, "INHERITS");
+            relate(type.implementsNames, "IMPLEMENTS");
+            for (const ref of type.typeRefs)
+                emitTypeRef(declared.id, unit, ref);
+            for (const method of type.methods) {
+                const member = byMember.get(`${unit.identityPackage}::${method.fqn}`);
+                if (member === undefined)
+                    continue;
+                // The caller's half of the HTTP boundary. Collected here, where the
+                // enclosing FUNCTION node and the receiver scopes are both in hand, and
+                // emitted with the routes below so both halves mint one `API_ENDPOINT`.
+                {
+                    const read = clientCalls(method, member.id, (name) => writtenReceiverType(method, declared, name), 
+                    // `identityPackage` is `module/sourceSet/package`, so the second
+                    // segment is the source set the build declared — read from the
+                    // anchor rather than pattern-matched off the file path.
+                    isTestSourceSet(unit.identityPackage));
+                    clientCallSites.push(...read.calls);
+                    for (const refusal of read.refusals) {
+                        ledger(refusal.fromId, "USES_API", refusal.raw, { file: unit.file, line: 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 }),
+                            });
+                    }
+                }
+                for (const ref of method.refs) {
+                    if (ref.kind === "type") {
+                        emitTypeRef(member.id, unit, ref);
+                        continue;
+                    }
+                    if (ref.kind === "member") {
+                        // A dotted access whose receiver is a declared variable is a field
+                        // read, not a type reference. Nothing is emitted and nothing is
+                        // filed: the ledger records references that *could* have been edges,
+                        // and this one was never a candidate.
+                        if (method.locals.has(ref.name) || type.fields.has(ref.name))
+                            continue;
+                        emitTypeRef(member.id, unit, ref);
+                        continue;
+                    }
+                    // `method`, not `member.method`. An overload set shares one node, and
+                    // the node carries the *first* overload — so resolving a receiver
+                    // against `member.method.locals` would type overload A's variables
+                    // with overload B's declarations. Same name, different parameter,
+                    // different type: a wrong edge, and one no recall measurement could
+                    // ever see.
+                    emitCall(member, method, declared, 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, file(unit, ref), REASONS.belowLevel);
+            }
+            return;
+        }
+        ledger(from, "USES_TYPE", ref.name, file(unit, ref), resolved.reason);
+    }
+    function emitCall(member, method, owner, unit, ref) {
+        // A coverage relation is a claim about a target. An unresolved reference has
+        // no target to make it about, so it is filed as the call it plainly is —
+        // the TypeScript adapter learned this by putting 21,223 assertion calls into
+        // its own test-coverage denominator.
+        const resolvedType = method.isTest ? "TESTS" : "CALLS";
+        const target = receiverTarget(method, owner, unit, ref);
+        if ("reason" in target) {
+            ledger(member.id, "CALLS", ref.raw, file(unit, ref), target.reason);
+            return;
+        }
+        let found = findMember(target.declared, ref.name);
+        // An unqualified name may be bound by a static import rather than declared
+        // on the enclosing type. The language guarantees that binding, so following
+        // it is resolution and not inference — and without it every JUnit assertion
+        // and every statically-imported helper is unresolvable.
+        if (found === undefined && ref.receiver === undefined) {
+            const owningType = unit.staticMemberImports.get(ref.name);
+            if (owningType !== undefined) {
+                const declaring = pick(unit, byFqn.get(owningType));
+                if ("declared" in declaring)
+                    found = findMember(declaring.declared, ref.name);
+            }
+        }
+        if (found === undefined) {
+            ledger(member.id, "CALLS", ref.raw, file(unit, ref), REASONS.unmodelled);
+            return;
+        }
+        // The evidence is a reference resolved to a specific definition, which is
+        // what R2 names — reached here through the language's own declarations
+        // rather than through an LSP. DEC-058's rule is that the level describes the
+        // evidence, not the machinery that produced it.
+        if (!push({ from: member.id, to: found.id, type: resolvedType }, 2)) {
+            ledger(member.id, "CALLS", ref.raw, file(unit, ref), REASONS.belowLevel);
+        }
+    }
+    /** Which type a call's receiver names, from what the source wrote down. */
+    function receiverTarget(method, owner, unit, ref) {
+        const receiver = ref.receiver;
+        if (receiver === undefined || receiver === "this")
+            return { declared: owner };
+        // `this.types.findPetTypes()` — the receiver is a field, named explicitly.
+        // Left unhandled, `this.types` was looked up as though it were a variable
+        // called "this.types" and then as a type of that name, and neither exists:
+        // three of the four recall misses on `spring-petclinic` were this one idiom,
+        // which is how every constructor-injected Spring field is written.
+        const viaThis = receiver.startsWith("this.");
+        const bare = viaThis ? receiver.slice("this.".length) : receiver;
+        if (bare.includes("."))
+            return { reason: REASONS.untypedReceiver };
+        // A local or parameter shadows a field, exactly as the language says — but
+        // `this.x` names the field regardless of what locals are in scope.
+        if (!viaThis) {
+            const local = method.locals.get(bare);
+            if (local === null)
+                return { reason: REASONS.untypedReceiver };
+            if (local !== undefined)
+                return resolveType(unit, local);
+        }
+        const field = fieldTypeOf(owner, bare, viaThis);
+        if (field !== undefined) {
+            return "poisoned" in field ? { reason: REASONS.untypedReceiver } : resolveType(unit, field.written);
+        }
+        if (viaThis)
+            return { reason: REASONS.untypedReceiver };
+        // `Type.staticMethod()` — a receiver that is itself a type name.
+        const asType = resolveType(unit, receiver);
+        if ("declared" in asType)
+            return asType;
+        // Anything else is a chained call, a field of an unread supertype, or an
+        // expression. None of them wrote a type down at this reference.
+        return { reason: /^[A-Z]/.test(receiver) ? asType.reason : REASONS.untypedReceiver };
+    }
+    /**
+     * The receiver's type **as written**, without resolving it.
+     *
+     * Deliberately not `receiverTarget`. That function answers "which analysed
+     * declaration does this receiver name", and every HTTP client type —
+     * `RestTemplate`, `WebClient` — is a Spring class **outside the analysed
+     * set**, so it correctly returns `outside` for all of them. The client reader
+     * does not need a declaration; it needs the name the source wrote, to compare
+     * against a closed set.
+     *
+     * The scope order is the same and is deliberately kept to the two cases that
+     * carry a written type — a local or parameter, then a field. Anything else
+     * (`Type.staticMethod()`, a chained builder, an expression) has no written
+     * type at this reference and returns `undefined`, which the caller turns into
+     * a disclosed refusal rather than a guess.
+     *
+     * A `function` declaration rather than a `const` arrow so it hoists: the
+     * method loop that calls it runs earlier in `extract`'s body than this point.
+     */
+    function writtenReceiverType(method, owner, receiver) {
+        const viaThis = receiver.startsWith("this.");
+        const bare = viaThis ? receiver.slice("this.".length) : receiver;
+        if (bare.includes("."))
+            return undefined;
+        if (!viaThis) {
+            const local = method.locals.get(bare);
+            // `null` is a poisoned entry — declared twice, or `var`. Not a name.
+            if (local === null)
+                return undefined;
+            if (local !== undefined)
+                return local;
+        }
+        const field = fieldTypeOf(owner, bare, viaThis);
+        if (field === undefined || "poisoned" in field)
+            return undefined;
+        return field.written;
+    }
+    ;
+    // --- Spring routes -------------------------------------------------------
+    //
+    // R2 and no lower, for the reason the Go adapter records: telling a controller
+    // from an ordinary class 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) {
+        const routeNodes = new Map();
+        const endpointNodes = new Map();
+        for (const unit of input.units) {
+            // Spring and JAX-RS are read independently — each gated on its own
+            // provenance in `spring.ts` — and merged here because both mint the
+            // same `API_ROUTE`/`API_ENDPOINT` shape (`SpringRoute`). See
+            // `language-problems.md` §3's JAX-RS row.
+            for (const route of [...springRoutes(unit), ...jaxrsRoutes(unit)]) {
+                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
+                    // controllers mapped to overlapping prefixes, Spring and JAX-RS both
+                    // serving the same route) 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` 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(
+                    // Every unit gets a MODULE node in the Nodes section above, before
+                    // this Edges section ever runs — always present.
+                    moduleIdOf.get(unit.file), "SERVES_API", name, { file: unit.file, line: 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);
+            }
+        }
+        // --- 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. A call to a route this run did *not* read still mints its endpoint —
+        // that is the point of `API_ENDPOINT` being the join node: either side can
+        // exist without the other (golden 08's note).
+        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",
+                // **The distinction the census forced.** 12 of Java's 16 relative-path
+                // call sites are in test files and none are production, so a consumer
+                // reading these as service-to-service coupling would be wrong about
+                // nearly all of them. `test` means this edge feeds *Verification
+                // status* — which routes have integration coverage — and not the
+                // confidence label. DEC-189.
+                attrs: { callerKind: call.callerKind, via: call.method },
+            }, 2);
+        }
+        nodes.push(...routeNodes.values(), ...endpointNodes.values());
+    }
+    return { nodes, edges, unresolved };
+}
+//# sourceMappingURL=extract.js.map