@descryy/adapter-java 0.2.0 → 0.3.0

package/dist/extract.js

@@ -1,31 +1,22 @@
 /**
  * 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.
+ * carries a written type, so `repo.findById(id)` resolves from the declaration
+ * `private final OwnerRepository repo` alone — a call through a receiver,
+ * which in TypeScript needed R3.
  *
- * ## What is deliberately not resolved
+ * That is **R2 evidence, never R3**: a reference resolved to a specific
+ * definition. R3 is a *checked shape*, and a written annotation is not one —
+ * it can be shadowed, be generic, and nothing here verifies overload
+ * selection. Claiming R3 for a name-level fact is the confusion DEC-058 was
+ * written about (83% of an adapter's edges once claimed an unearned level).
+ * `IMPORTS` stays at R1 — module resolution, nothing more.
  *
- * `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.
+ * Deliberately unresolved: `var` declarations, chained calls whose receiver is
+ * another call, generic type variables, and names reachable only through an
+ * ambiguous wildcard import. 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";
@@ -38,14 +29,11 @@ const CONFIDENCE = { 0: 0.5, 1: 0.7, 2: 0.9, 3: 0.95 };
  *  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`.
+    // Measured on `okhttp`: of 458 `outside` entries naming a qualified type,
+    // 238 are declared in a `.kt` file in the same repo — not a scope boundary
+    // but an unreadable-language case (rule 6's fourth category). The adapter
+    // can't tell the two apart without a cross-adapter declaration index it
+    // isn't given. `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 " +
@@ -69,10 +57,10 @@ const REASONS = {
 /**
  * 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`.
+ * The Java package *is* the namespace, so no anchor has to be inferred the way
+ * a TypeScript package root does — DEC-047's and DEC-077's problems don't
+ * exist here. The nesting path is everything after the package:
+ * `Outer.Inner.method`.
  */
 function qspFor(fqn, unit) {
     const nested = unit.packageName !== "" && fqn.startsWith(`${unit.packageName}.`)
@@ -83,13 +71,11 @@ function qspFor(fqn, unit) {
 /**
  * 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.
+ * `identityPackage` is `module/sourceSet/package` (`roots.ts`) — the source
+ * set is the second segment when there are three; a unit with no `src/` split
+ * has two segments and returns false rather than guessing. `test`,
+ * `testFixtures`, `integrationTest` are names Maven/Gradle declare, not a
+ * path convention.
  */
 function isTestSourceSet(identityPackage) {
     const segments = identityPackage.split("/");
@@ -97,10 +83,8 @@ function isTestSourceSet(identityPackage) {
         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.
- */
+/** Choose among a scope's candidates, preferring the 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 };
@@ -114,29 +98,23 @@ function pick(from, candidates) {
 /**
  * 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.
+ * Shared rather than duplicated: both the `INHERITS`/`IMPLEMENTS` edges and
+ * JPA's `@MappedSuperclass` walk resolve a supertype name this way, and a
+ * second copy would drift — putting a column on the wrong table, not just a
+ * missing edge.
  *
- * `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.
+ * `decides` marks a scope that settles the question even on failure 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, since a file may declare several types.
  */
 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.
+    // A dotted name is either already fully qualified (`com.example.Order`, no
+    // scope needed) or a nested type named through its enclosing type
+    // (`DiskLruCache.Snapshot`, enclosing name resolved first) — not
+    // distinguishable by spelling, so try the whole path, then head+tail.
+    // Only the whole path used to be tried, dropping 28 nested-type references
+    // across the corpora (`mall`'s `Criteria` x19).
     if (written.includes(".")) {
         const asWritten = index.get(written);
         if (asWritten !== undefined)
@@ -144,9 +122,8 @@ function scopesFor(index, unit, written) {
         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.
+        // The head resolves by the normal rules (import, same-package, nested) —
+        // recurse rather than reimplementing the scope order and letting it drift.
         const ordered = [];
         for (const scope of scopesFor(index, unit, head)) {
             for (const candidate of scope.candidates) {
@@ -159,8 +136,8 @@ function scopesFor(index, unit, written) {
                     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.
+        // A refusal, not a fallback to the bare tail — resolving `A.B` as `B`
+        // is the dropped qualifier this branch exists to stop.
         return ordered.length > 0 ? ordered : [{ candidates: [], decides: true }];
     }
     const ordered = [];
@@ -182,9 +159,9 @@ function scopesFor(index, unit, written) {
         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.
+    // 4. Wildcard imports. Accepted only when exactly one analysed type matches —
+    //    two candidates is genuinely ambiguous, and picking one is a coin toss
+    //    recorded as fact.
     const candidates = unit.wildcardImports.flatMap((wildcard) => [...(index.get(`${wildcard}.${written}`) ?? [])]);
     if (candidates.length > 0)
         ordered.push({ candidates, decides: true });
@@ -200,13 +177,10 @@ export function extract(input) {
     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.
+     * reached, so the caller can disclose it instead of dropping it silently.
+     * An edge may not claim an unreached level — the Normaliser rejects it, and
+     * capping the number instead would let the edge survive wearing a level its
+     * evidence never earned (DEC-058's defect exactly).
      */
     const push = (edge, level) => {
         if (level > input.reached)
@@ -241,18 +215,14 @@ export function extract(input) {
             ...(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.
+     * A list, not a single entry: the airbyte run declares
+     * `...RedisDataFactory` twice in two source sets that never share a
+     * classpath. A single-entry map would silently keep the last one and
+     * resolve both source sets to it — a wrong edge no recall measurement
+     * can catch, since the name was found.
      */
     const byFqn = new Map();
     const byMember = new Map();
@@ -260,16 +230,13 @@ export function extract(input) {
     /** 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.
+     * Every declared type, indexed before any node id exists. A JPA entity is a
+     * `MODEL` not a `CLASS`, and the id hashes the kind (DEC-004) — so the kind
+     * must be settled before minting, but that needs `@MappedSuperclass`
+     * resolution across compilation units, which needs an index `byFqn` can't
+     * be (it holds ids). So types are indexed twice: once without ids for the
+     * entity decision, once with them for edges — the alternative, minting then
+     * rewriting a `CLASS` id, is exactly what DEC-004 forbids.
      */
     const typesByFqn = new Map();
     for (const unit of input.units) {
@@ -287,9 +254,8 @@ export function extract(input) {
             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.
+            // Ambiguous supertype 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;
         }
@@ -297,12 +263,10 @@ export function extract(input) {
     };
     /**
      * 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.
+     * Keyed by `identityPackage::fqn`, not `fqn` alone — a fqn isn't unique
+     * across source sets (the same airbyte duplicate `byFqn` records), and
+     * keying on fqn alone would let an `@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) {
@@ -312,19 +276,14 @@ export function extract(input) {
     }
     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.
+        // Named by its *primary* type, which Java requires to match the file name
+        // — a symbol path, not a file path, so a moved file keeps its identity
+        // (DEC-004). `types[0]` was not that type: nested declarations are
+        // appended before their enclosing type, so a file whose outer class held
+        // a private interface took its identity from the interface instead
+        // (`TeradataJdbcSourceAcceptanceTest.java` became module `SqlConsumer`).
+        // The stem is preferred since the language guarantees it names the public
+        // type; a top-level declaration is the fallback when the file has none.
         const stem = unit.file.slice(unit.file.lastIndexOf("/") + 1).replace(/\.java$/, "");
         const topLevel = unit.types.filter((each) => unit.packageName === ""
             ? !each.fqn.includes(".")
@@ -337,12 +296,11 @@ export function extract(input) {
         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.
+            // Named with its extension, identified without one — Java requires a
+            // public type's simple name to equal its file name, so a bare `Status`
+            // names both the module and its class, and a `(file, name)`-bound corpus
+            // role correctly refuses to guess between them. `Status.java` can never
+            // collide with a type name.
             name: `${unitName}.java`,
             file: unit.file,
             range: { startLine: 1, endLine: 1 },
@@ -351,11 +309,9 @@ export function extract(input) {
             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.
+        // Kind decided BEFORE the id is minted (DEC-004), not patched on after —
+        // everything downstream reads the id out of `byFqn`. Resolved for the
+        // whole batch above, since 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";
@@ -375,10 +331,10 @@ export function extract(input) {
                 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.
+                // Not gated on `input.reached`, deliberately — a mapped column is a
+                // declaration the framework enforces, not an inference, so its
+                // resolution is the evidence's rather than the run's (DEC-058), same
+                // as adapter-python's SQLAlchemy reasoning.
                 if (model.fields.length > 0)
                     attrs["fields"] = model.fields;
                 if (model.undecided.length > 0)
@@ -396,18 +352,13 @@ export function extract(input) {
                 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.
+             * Overloads are one node, count disclosed rather than hidden. A
+             * qualified symbol path carries no parameter types (DEC-011), so
+             * `getPet(String)`/`getPet(Integer)` name one symbol — encoding
+             * parameters into the path would fix the collision by making Java's
+             * identity rule leak language specifics above the IR boundary. What's
+             * lost: an edge into an overload set doesn't say which overload — a
+             * name-level fact, capped by DEC-058's rule at the level it earned.
              */
             const overloads = new Map();
             for (const method of type.methods) {
@@ -419,9 +370,8 @@ export function extract(input) {
             }
             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.
+                // A `@Test` method is a test case, not a tested function — emitting
+                // both would double the node 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)
@@ -431,27 +381,19 @@ export function extract(input) {
                     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.
+                // DEC-248: a CALLS edge can originate from *any* overload's body —
+                // `emitCall` resolves against the specific overload, not
+                // `member.method` — so the range must span every overload, not just
+                // `first`'s lines, or an edge can point outside its own node's range
+                // (`spring-petclinic`'s `Owner.getPet(String)` was once credited with
+                // a call only in the neighbouring `getPet(Integer)`).
                 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.
+                // Widening is sound only when the group's own declarations fill the
+                // span — Java doesn't require overloads to sit adjacent, so the
+                // widened range can swallow an unrelated member in the gap
+                // (`language-problems.md` §3 row 5). Disclosed rather than letting a
+                // change to that member misattribute 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) ||
@@ -473,20 +415,14 @@ export function extract(input) {
             }
         }
     }
-    // -------------------------------------------------------------------------
-    // Name resolution
-    // -------------------------------------------------------------------------
     /**
-     * Pick the declaration of a fully-qualified name that the referring unit can
-     * actually see.
+     * Resolve a simple or qualified type name as written inside one unit.
      *
-     * 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.
+     * Java's own rule is the classpath, which this adapter doesn't read. The
+     * approximation: a declaration in the same module/source set wins outright,
+     * one candidate overall is taken, and a genuine tie 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);
@@ -500,22 +436,17 @@ export function extract(input) {
     /**
      * 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.
+     * `viaThis` distinguishes `this.pet` from a bare `pet`: `this` reaches only
+     * the type's own and inherited fields; a bare name additionally sees the
+     * *lexically enclosing* class's fields (how a `@Nested` test class reads its
+     * holder's fields). Collapsing the two would resolve `this.x` against an
+     * outer class it can't 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`.
+            // Enclosing types, innermost first: `pkg.Outer.Inner` -> `pkg.Outer`.
             let fqn = owner.type.fqn;
             for (;;) {
                 const cut = fqn.lastIndexOf(".");
@@ -567,14 +498,11 @@ export function extract(input) {
         }
         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
+        // IMPORTS — module to module. A wildcard import names a package, not a
         // compilation unit, so it has nothing to point at and is disclosed instead.
         for (const each of unit.importLines) {
             if (each.wildcard) {
@@ -616,20 +544,19 @@ export function extract(input) {
                 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`.
+                // The caller's half of the HTTP boundary, collected here (enclosing
+                // FUNCTION node and receiver scopes 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.
+                    // Source set read from the identity-package anchor, not 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.
+                        // Unset `refusalClass` means unclassified (DEC-242) — `attrs`
+                        // omitted entirely rather than sent with an `undefined` field.
                         refusal.refusalClass === undefined
                             ? undefined
                             : {
@@ -646,20 +573,18 @@ export function extract(input) {
                     }
                     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.
+                        // read, not a type reference — never a candidate edge, so nothing
+                        // is emitted or filed.
                         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.
+                    // `method`, not `member.method` — an overload set's node carries
+                    // only the *first* overload, so resolving against
+                    // `member.method.locals` would type overload A's variables with
+                    // overload B's declarations: a wrong edge no recall measurement
+                    // could see.
                     emitCall(member, method, declared, unit, ref);
                 }
             }
@@ -676,10 +601,10 @@ export function extract(input) {
         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.
+        // A coverage relation is a claim about a target; an unresolved reference
+        // has none, so it's filed as the call it plainly is — the TypeScript
+        // adapter learned this the hard way (21,223 assertion calls once counted
+        // in its test-coverage denominator).
         const resolvedType = method.isTest ? "TESTS" : "CALLS";
         const target = receiverTarget(method, owner, unit, ref);
         if ("reason" in target) {
@@ -688,9 +613,8 @@ export function extract(input) {
         }
         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.
+        // on the enclosing type — the language guarantees that binding, so
+        // following it is resolution, not inference.
         if (found === undefined && ref.receiver === undefined) {
             const owningType = unit.staticMemberImports.get(ref.name);
             if (owningType !== undefined) {
@@ -703,10 +627,9 @@ export function extract(input) {
             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.
+        // A reference resolved to a specific definition is R2 evidence, reached
+        // here through the language's declarations rather than an LSP — DEC-058:
+        // the level describes the evidence, not the machinery.
         if (!push({ from: member.id, to: found.id, type: resolvedType }, 2)) {
             ledger(member.id, "CALLS", ref.raw, file(unit, ref), REASONS.belowLevel);
         }
@@ -716,17 +639,16 @@ export function extract(input) {
         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.
+        // `this.types.findPetTypes()` — an explicitly-named field receiver. Left
+        // unhandled, `this.types` resolved as neither a variable nor a type and
+        // was 3 of 4 recall misses on `spring-petclinic` — 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.
+        // A local/parameter shadows a field, as the language says — but `this.x`
+        // names the field regardless of locals in scope.
         if (!viaThis) {
             const local = method.locals.get(bare);
             if (local === null)
@@ -744,28 +666,23 @@ export function extract(input) {
         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.
+        // Anything else — a chained call, a field of an unread supertype, an
+        // expression — wrote no 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 receiver's type **as written**, without resolving it. Deliberately
+     * not `receiverTarget`: HTTP client types (`RestTemplate`, `WebClient`) are
+     * Spring classes outside the analysed set, so that function correctly
+     * returns `outside` for them — this one just needs the written name 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.
+     * Scope order kept to the two cases with a written type: local/parameter,
+     * then field. Anything else returns `undefined`, turned 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` declaration, not `const` arrow, so it hoists — the method loop
+     * calling it runs earlier in `extract`'s body.
      */
     function writtenReceiverType(method, owner, receiver) {
         const viaThis = receiver.startsWith("this.");
@@ -786,25 +703,21 @@ export function extract(input) {
         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.
+    // R2 and no lower — telling a controller from an ordinary class is
+    // provenance, and a route emitted below R2 claims more than the run
+    // produced (Normaliser rejects it 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.
+            // Spring and JAX-RS read independently (each gated on its own
+            // provenance in `spring.ts`), merged here since both mint the same
+            // `API_ROUTE`/`API_ENDPOINT` shape.
             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.
+                // Repo-scoped, template-as-written — which service serves a path is
+                // what the join must not erase.
                 const routeId = nodeId(scope, "API_ROUTE", name, LANGUAGE);
                 if (!routeNodes.has(routeId)) {
                     routeNodes.set(routeId, {
@@ -826,24 +739,18 @@ export function extract(input) {
                     });
                 }
                 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`).
+                    // A second declaration claiming the same method+path is real (two
+                    // controllers on overlapping prefixes, Spring and JAX-RS both
+                    // serving one route), not a bug — was silent until now. Fixed the
+                    // way `adapter-python` did: a ledger row on the collision branch,
+                    // not a change to node identity (`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.
+                    // Every unit gets a MODULE node in the Nodes section above — 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.
+                // Workspace-scoped, fileless, language-less, minted with the SAME
+                // endpointQsp every producer uses (DEC-115) — mismatched ids don't
+                // 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, {
@@ -861,13 +768,10 @@ export function extract(input) {
                 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).
+        // 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, not two.
+        // A call to a route this run didn't read still mints its endpoint —
+        // `API_ENDPOINT` is the join node; either side can exist alone (golden 08).
         for (const call of clientCallSites) {
             const endpoint = endpointFor(scope, call, input.producedBy, normaliseEndpointPath);
             if (!endpointNodes.has(endpoint.id))
@@ -876,12 +780,9 @@ export function extract(input) {
                 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.
+                // 12 of Java's 16 relative-path call sites are test files, none
+                // production — `test` feeds Verification status (integration
+                // coverage), not the confidence label. DEC-189.
                 attrs: { callerKind: call.callerKind, via: call.method },
             }, 2);
         }