@descryy/adapter-java 0.1.0

package/dist/client.js

@@ -0,0 +1,471 @@
+/**
+ * The caller's half of the HTTP boundary: `USES_API`, golden pattern 08.
+ *
+ * `SERVES_API` is minted in `extract.ts` from a route's annotations. This reads
+ * the other end — an outbound call with a statically knowable path — and mints
+ * the **same** `API_ENDPOINT` node from the same `endpointQsp`, so the two join
+ * without either side knowing the other ran. DEC-115's one hard constraint: two
+ * producers that mint different ids do not conflict, they silently fail to join.
+ *
+ *     FUNCTION ──USES_API──▶ API_ENDPOINT ◀──SERVES_API── API_ROUTE
+ *
+ * ## What these edges actually mean, and why it must be said in the edge
+ *
+ * Measured before this was written (`bench/client-call-census.mjs`, DEC-189):
+ * across `shopizer`, `mall`, `morphia`, `okhttp` and `spring-petclinic` there
+ * are **16** client call sites carrying a repository-relative literal path.
+ * **Twelve are in test files, four are on a mock transport, and none are
+ * production code.**
+ *
+ * So in Java these edges are almost entirely `TEST_CASE`-shaped: an integration
+ * test driving `TestRestTemplate` at the application's own routes. That is real
+ * and it is useful — it answers *which routes have integration coverage*, which
+ * is the **Verification status** axis (AI layer §20, §42), a separate axis from
+ * the confidence label. It is **not** service-to-service coupling, and a
+ * consumer reading it as "this service calls that service" would be wrong.
+ *
+ * The distinction therefore travels **in the edge**, as `attrs.callerKind`, not
+ * in a comment here. A count in a decision record is invisible to a consumer;
+ * `attrs` is what the edge carries. (`attrs` is not read above the IR — which is
+ * exactly why the same fact is also stated in the disclosure below, where a
+ * reader will see it.)
+ *
+ * ## Why the receiver's type is required
+ *
+ * `execute`, `put`, `delete` and `uri` are ordinary method names. Admitting a
+ * call on its name alone would emit `USES_API` for `list.put("/tmp/x")`, and a
+ * wrong edge here joins a caller to a route it never calls — which root-cause
+ * traversal then follows. So a call is admitted only when its receiver's
+ * **declared type** is a known client. That is R2 evidence: a reference resolved
+ * to a definition through a written annotation, exactly as the rest of this
+ * adapter reads receivers.
+ *
+ * The cost is disclosed rather than hidden: a chained builder
+ * (`new Request.Builder().url("/")`) has no receiver with a written type and is
+ * refused. All four such sites in the corpora are `mockWebServer`, so nothing
+ * real is lost today — but the refusal is a rule, not a measurement, and it will
+ * cost real call sites in a codebase that chains.
+ *
+ * ## Ledger row D-FIX-3: a known client this reader does not extract
+ *
+ * Everything above requires the receiver's type to already be in
+ * {@link CLIENT_TYPES} before any refusal fires — so a call through a client
+ * this adapter has never heard of took neither branch. It matched no name in
+ * {@link URL_FIRST}'s companion set below, `typeOfReceiver` was never asked,
+ * and the reference fell out of the loop with `continue` before reaching a
+ * single `refuse(...)` call. **Zero edges and zero ledger rows is the same
+ * output a repository with no HTTP calls at all produces.** Sherpa's
+ * TypeScript diagnosis found the identical shape — 26 wrapped-`axios` call
+ * sites across 14 files, none reaching the refusal ledger — and it is the
+ * reason this row exists rather than being filed as ordinary recall.
+ *
+ * {@link BUILDER_CLIENT_TYPES} closes it for the two client families measured
+ * on the reference corpora (`bench/client-call-census.mjs`'s `CLIENTS.java`
+ * list, `okhttp3.OkHttpClient` and `java.net.http.HttpClient`) — **not by
+ * reading their calls**, but by recognising the receiver type and filing a
+ * refusal for every call through it. Both clients pass the outbound request as
+ * a **separately constructed object** (`Request`, `HttpRequest`) rather than a
+ * literal argument on the call itself, so building real extraction for them is
+ * a different, larger row — a second `firstStringArgument`-shaped read through
+ * a builder chain — and is out of scope here. What is in scope is closing the
+ * silence: **every** call through a receiver whose declared type names one of
+ * these clients is now accounted for, either as an edge (impossible for these
+ * two, by construction) or as a ledger row.
+ *
+ * ### Why the trigger is receiver-type resolution, not a file-level import scan
+ *
+ * The population D-FIX-3 was scoped against is "a file that imports a known
+ * HTTP client and makes calls the extractor did not claim." Read literally,
+ * that would fire on **every** method call in a file that merely imports
+ * `okhttp3.OkHttpClient` anywhere — including calls with no relation to it —
+ * which is exactly the "fires on everything" failure the row warns against.
+ * This adapter already has a narrower, previously-measured discriminator for
+ * the identical question: `typeOfReceiver`, R2 evidence, a written declaration
+ * this reader can point at. Reusing it means the new population is *provably*
+ * bounded to calls whose receiver is declared as one of these types — no
+ * broader — and it costs nothing new: `writtenReceiverType` in `extract.ts`
+ * already resolves an arbitrary type name syntactically, whether or not this
+ * adapter goes on to model it, so `OkHttpClient` and `HttpClient` resolve
+ * exactly as `RestTemplate` does today.
+ *
+ * ### The reconciliation this row makes an assertion rather than a discipline
+ *
+ * `candidateClientRefs` (below) recomputes, independently of the loop in
+ * {@link clientCalls}, which references in a method are candidates at all —
+ * same predicate, factored out so a future edit to the loop cannot silently
+ * narrow what counts as a candidate without the test that calls both noticing.
+ * `test/client.test.ts` asserts `calls.length + refusals.length ===
+ * candidateClientRefs(method).length` on every fixture, which is the shape
+ * DEC-098 found missing the hard way: a guard that dropped 113 of 140 call
+ * sites with no edge, no row, and no failing test.
+ */
+import { endpointQsp, nodeId } from "@descryy/ir";
+/**
+ * Client types whose methods name an outbound HTTP call.
+ *
+ * `TestRestTemplate` is here deliberately. It is Spring's own integration-test
+ * client and it drives **real HTTP at the application's real routes** — the
+ * transport is what decides whether a call site is a route reference, not the
+ * directory the file sits in. That distinction cost this project a gate: a
+ * census that split on the file path reported two `mockWebServer` calls as
+ * production code.
+ */
+const CLIENT_TYPES = new Set([
+    "RestTemplate",
+    "TestRestTemplate",
+    "WebClient",
+    "RestClient",
+    "AsyncRestTemplate",
+]);
+/**
+ * Methods that take a URL or path as their first argument.
+ *
+ * `exchange` and `execute` are `RestTemplate`'s general forms; `uri` is
+ * `WebClient`'s fluent builder step. Every one is admitted only in combination
+ * with a receiver of a {@link CLIENT_TYPES} type.
+ */
+const URL_FIRST = new Set([
+    "getForObject",
+    "getForEntity",
+    "postForObject",
+    "postForEntity",
+    "postForLocation",
+    "patchForObject",
+    "put",
+    "delete",
+    "exchange",
+    "execute",
+    "uri",
+]);
+/**
+ * Known HTTP clients this reader recognises by declared type but does not
+ * extract — see "Ledger row D-FIX-3" above. Keyed by type name, valued by the
+ * method names on that type which initiate a request; every such call is
+ * refused, unconditionally, because the URL and verb live inside a request
+ * object built in a separate expression rather than in this call's own
+ * arguments — there is nothing for `firstStringArgument` to read.
+ *
+ * `java.net.http.HttpClient`'s simple name is `HttpClient`, distinct from
+ * Spring's `WebClient` — no collision with {@link CLIENT_TYPES}.
+ */
+const BUILDER_CLIENT_TYPES = {
+    OkHttpClient: new Set(["newCall"]),
+    HttpClient: new Set(["send", "sendAsync"]),
+};
+/**
+ * `WebClient`/`RestClient`'s own intermediate builder-step interfaces —
+ * `WebClient.RequestHeadersUriSpec`, `RestClient.RequestBodyUriSpec`, and
+ * their siblings, always referred to by simple name since nobody writes the
+ * outer-class-qualified form. Reached when the chain is split across a local
+ * variable (`var spec = client.get(); spec.uri("/x");`) rather than written
+ * inline — the other half of ledger row D-FIX-3, alongside the inline chain
+ * {@link BUILDER_VERB} closes. This adapter has no initializer-tracing (the
+ * verb-bearing `.get()`/`.post()` call is a separate statement, gone by the
+ * time `spec`'s declared type is the only thing left to read), so every call
+ * through one of these is refused rather than silently dropped — the same
+ * "account for it as an edge or a ledger row, never nothing" standard
+ * {@link BUILDER_CLIENT_TYPES} already holds OkHttp/`HttpClient` to.
+ */
+const WEBCLIENT_SPLIT_BUILDER_TYPES = new Set([
+    "RequestHeadersUriSpec",
+    "RequestBodyUriSpec",
+    "RequestHeadersSpec",
+    "RequestBodySpec",
+]);
+/**
+ * `WebClient`/`RestClient`'s fluent verb-starters — the call that opens the
+ * chain a real call site always uses (`client.get().uri("/x")...`), not the
+ * client's own declared type's method. This is why {@link URL_FIRST}'s `uri`
+ * entry alone was never enough: nothing in `VERB` maps `uri` to a verb,
+ * because `uri` never carries one — the verb sits one call earlier in the
+ * chain, on the call `uri`'s receiver expression *is*. See ledger row
+ * D-FIX-3 in the file header.
+ *
+ * `head`/`options` are real `WebClientRequestSpec`/`RestClient` entry points
+ * with no `VERB`-string precedent elsewhere in this file, so they are spelled
+ * out here rather than derived.
+ */
+const BUILDER_VERB = {
+    get: "GET",
+    post: "POST",
+    put: "PUT",
+    patch: "PATCH",
+    delete: "DELETE",
+    head: "HEAD",
+    options: "OPTIONS",
+};
+/**
+ * Matches `parse.ts`'s `receiverName` chain encoding for a `method_invocation`
+ * object: `<base>.<name>()`. The literal `()` is a label, not a copy of the
+ * call's real arguments — see that function's doc.
+ */
+const CHAIN_PATTERN = /^(.+)\.([A-Za-z_$][A-Za-z0-9_$]*)\(\)$/;
+/** Every method name either extraction path or the builder-client path acts on. */
+const TRACKED_METHODS = new Set([...URL_FIRST, ...Object.values(BUILDER_CLIENT_TYPES).flatMap((s) => [...s])]);
+/**
+ * The HTTP verb a method name implies.
+ *
+ * `exchange`, `execute` and `uri` take the verb as a *separate argument* — an
+ * enum reference, not a literal — so they cannot be read here and are refused
+ * rather than defaulted to `GET`. A wrong verb produces an `endpointQsp` that
+ * joins nothing, which is a silent miss, or worse joins the wrong route.
+ */
+const VERB = {
+    getForObject: "GET",
+    getForEntity: "GET",
+    postForObject: "POST",
+    postForEntity: "POST",
+    postForLocation: "POST",
+    patchForObject: "PATCH",
+    put: "PUT",
+    delete: "DELETE",
+};
+const CAPABILITY_GAP = { blockedBy: null, refusalClass: "capability-gap" };
+const VARIES_PER_CALL = { blockedBy: null, refusalClass: "varies-per-call" };
+/** `System.getenv("X")`, `System.getenv().get("X")`, and Spring's `env`/`environment`-named `Environment.getProperty("X")`. */
+const ENV_READ_PATTERNS = [
+    /^System\.getenv\(\s*"[^"]*"\s*\)$/,
+    /^System\.getenv\(\s*\)\.get\(\s*"[^"]*"\s*\)$/,
+    /^\w*(?:[Ee]nv|[Ee]nvironment)\w*\.getProperty\(\s*"[^"]*"\s*\)$/,
+];
+/** Same heuristic as every other adapter's — see `adapter-rust/src/client.ts`'s doc. */
+function argumentKindOf(text) {
+    if (text.endsWith(")") && text.includes("("))
+        return "call";
+    if (text.includes("+"))
+        return "concatenation";
+    if (/^[A-Za-z_$][A-Za-z0-9_$]*(\.[A-Za-z_$][A-Za-z0-9_$]*)*$/.test(text))
+        return "field";
+    return "other";
+}
+/**
+ * Why the first argument of a client call could not be read as a literal
+ * path — mirrors `firstArgumentTextOf`'s own reach: a bare identifier, a
+ * known environment-read call, or something this reader does not trace.
+ */
+function diagnoseArgument(text, parameterNames) {
+    if (text === undefined)
+        return CAPABILITY_GAP;
+    const trimmed = text.trim();
+    if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(trimmed) && parameterNames.has(trimmed))
+        return VARIES_PER_CALL;
+    if (ENV_READ_PATTERNS.some((pattern) => pattern.test(trimmed))) {
+        return { blockedBy: trimmed, refusalClass: "value-unknown" };
+    }
+    return { ...CAPABILITY_GAP, argumentKind: argumentKindOf(trimmed) };
+}
+/** A path this reader will claim: repository-relative, no scheme, no assembly. */
+function relativePath(value) {
+    if (!value.startsWith("/"))
+        return undefined;
+    // `//host/path` is protocol-relative and names another origin.
+    if (value.startsWith("//"))
+        return undefined;
+    // A query string is not part of the route template. `?` and everything after
+    // it is dropped, because `SERVES_API` never mints one and keeping it would
+    // guarantee the join fails.
+    const cut = value.indexOf("?");
+    return cut === -1 ? value : value.slice(0, cut);
+}
+/**
+ * A literal this reader can say, with no ambiguity, names a *different*
+ * origin — an explicit scheme (`http://...`) or a protocol-relative URL
+ * (`//host/...`). Anything else that fails {@link relativePath} (a bare
+ * relative path with no leading slash, e.g. `"orders/5"`) is NOT covered by
+ * this check and must not be reported through it.
+ *
+ * Split out after DEC-260's C# origin-check row found the shared bug one
+ * language over: `adapter-csharp` originally treated "does not start with
+ * `/`" as sufficient evidence of another origin, and that misfired on real
+ * `jellyfin`/`eShopOnWeb` call sites — bare relative paths resolved against
+ * `HttpClient.BaseAddress` at runtime, same-repository calls incorrectly
+ * filed as a scope boundary. Spring's `RestTemplate`/`WebClient` support the
+ * identical pattern (`RootUriTemplateHandler`, `WebClient.baseUrl(...)`), so
+ * the same rule, applied here unchanged since before that row, carries the
+ * identical latent defect — confirmed synthetically
+ * (`restTemplate.getForObject("orders/5", String.class)` was filed as
+ * "another origin" before this fix). **Not observed in either admitted
+ * corpus** (`spring-petclinic`, `shopizer` — all 3 real `USES_API` refusals
+ * naming another origin are unambiguous `http://` URLs, unaffected by this
+ * change), so this closes a rule that was correct only because nothing had
+ * tested it yet, not a live regression.
+ */
+function namesAnotherOrigin(value) {
+    return /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(value) || value.startsWith("//");
+}
+/**
+ * Every reference in a method that {@link clientCalls} will act on — an edge,
+ * a refusal, or (only past this point, where the receiver's type is unknown)
+ * a true silence. Factored out of the loop below so the reconciliation
+ * assertion in `test/client.test.ts` recomputes candidacy independently of
+ * whatever the loop does with each candidate: a future edit that narrows the
+ * loop's own filter without touching this function fails the test instead of
+ * silently dropping call sites the way DEC-098's `containerOf` guard did.
+ *
+ * Receiver-type resolution is deliberately **not** done here — it needs
+ * `extract.ts`'s scope tables, which this module does not have — so a
+ * candidate here may still turn out to be a true silence in
+ * {@link clientCalls} if `typeOfReceiver` returns `undefined`. That is the
+ * one gap this reconciliation cannot close, and it is the same gap every
+ * other refusal ledger in this project discloses rather than guesses past:
+ * an unresolved receiver is not evidence the call is or is not a client.
+ */
+export function candidateClientRefs(method) {
+    return method.refs.filter((ref) => ref.kind === "call" &&
+        TRACKED_METHODS.has(ref.name) &&
+        ref.receiver !== undefined &&
+        ref.receiver !== "this");
+}
+/**
+ * Read one method's calls for outbound HTTP.
+ *
+ * `typeOfReceiver` resolves a receiver name to its declared type's simple name
+ * and is supplied by the caller, because the scope rules for that live in
+ * `extract.ts` and a second copy of them would drift — the failure that
+ * `scopesFor`'s own header records.
+ */
+export function clientCalls(method, fromId, typeOfReceiver, inTestSourceSet) {
+    const calls = [];
+    const refusals = [];
+    /**
+     * Read `ref`'s first argument as a path and either push a `ClientCall` or a
+     * refusal — the shared tail every admitted verb reaches, whether the verb
+     * came from `VERB[ref.name]` directly or from a builder-chain's opening
+     * call via {@link BUILDER_VERB}.
+     */
+    const readPathAndEmit = (receiverType, ref, verb, refuse) => {
+        if (ref.firstStringArgument === undefined) {
+            refuse(`an HTTP call through ${receiverType}, but its path is not a bare string literal — a ` +
+                `variable, a concatenation, or a builder. A path assembled at run time is not one ` +
+                `this adapter can read, and an endpoint template invented here would join this ` +
+                `caller to a route it never calls.`, diagnoseArgument(ref.firstArgumentText, method.parameterNames));
+            return;
+        }
+        const template = relativePath(ref.firstStringArgument);
+        if (template === undefined) {
+            if (namesAnotherOrigin(ref.firstStringArgument)) {
+                refuse(`an HTTP call through ${receiverType} to \`${ref.firstStringArgument}\`, which names ` +
+                    `another origin rather than a path in this repository. A scope boundary, not a gap.`, { blockedBy: null, refusalClass: "out-of-scope" });
+                return;
+            }
+            // A bare relative path with no leading slash and no scheme —
+            // structurally identical to C#'s `HttpClient.BaseAddress` case. It may
+            // resolve inside this repository, against a configured root URI
+            // (`RootUriTemplateHandler`, `WebClient.baseUrl(...)`), or it may not;
+            // this reader does not see that configuration, so neither an edge nor
+            // an out-of-scope claim is honest here — rule 2, applied to a
+            // classification rather than an edge. Not a per-call value and not a
+            // named blocking expression either, so `capability-gap` rather than
+            // `varies-per-call`: nothing here is caller-supplied, this reader just
+            // cannot see the base configuration.
+            refuse(`an HTTP call through ${receiverType} to \`${ref.firstStringArgument}\`, a relative path ` +
+                `with no leading slash. This reader cannot tell whether it resolves inside this repository ` +
+                `— against a configured base URI this call site does not state — or elsewhere, so neither ` +
+                `an endpoint nor a scope boundary is claimed.`, CAPABILITY_GAP);
+            return;
+        }
+        calls.push({
+            fromId,
+            method: ref.name,
+            template,
+            verb,
+            line: ref.line,
+            // **The source set, not just the annotation.** `method.isTest` reads
+            // `@Test`, and shopizer's `ServicesTestSupport.getHeader` drives
+            // `TestRestTemplate` from an unannotated helper — so annotation alone
+            // labelled two of nine edges `production` when both sit in
+            // `src/test/java`. The build system states which source set is test code;
+            // inferring it from the annotation asks a narrower question than the one
+            // being answered. If the framework will tell you, never infer it.
+            callerKind: method.isTest || inTestSourceSet ? "test" : "production",
+        });
+    };
+    for (const ref of candidateClientRefs(method)) {
+        // WebClient/RestClient's fluent chain: `client.get().uri("/x")`. The
+        // receiver `parse.ts` hands back for the `uri` call is the *opening* call
+        // encoded as text (`client.get()`), not a name `typeOfReceiver` can look
+        // up directly — so the base is resolved instead, and the verb comes from
+        // the chain, not from `uri` itself. See ledger row D-FIX-3 and
+        // {@link BUILDER_VERB}'s doc.
+        const chain = ref.name === "uri" ? CHAIN_PATTERN.exec(ref.receiver) : null;
+        if (chain !== null) {
+            // Both groups are guaranteed by `CHAIN_PATTERN`'s two capturing groups
+            // once `exec` succeeds — `noUncheckedIndexedAccess` cannot see that from
+            // the pattern alone.
+            const base = chain[1];
+            const opener = chain[2];
+            const receiverType = typeOfReceiver(base);
+            if (receiverType === undefined || !CLIENT_TYPES.has(receiverType))
+                continue;
+            const refuse = (reason, diagnosis) => {
+                refusals.push({ fromId, raw: ref.raw, line: ref.line, reason, ...diagnosis });
+            };
+            const verb = BUILDER_VERB[opener];
+            if (verb === undefined) {
+                refuse(`an HTTP call through ${receiverType}, but \`${opener}\` takes its method as a ` +
+                    `separate argument — an enum reference this adapter does not read. Refused rather ` +
+                    `than defaulted to GET: a wrong verb mints an endpoint that joins the wrong route, ` +
+                    `or none, and root-cause traversal would follow it.`, CAPABILITY_GAP);
+                continue;
+            }
+            readPathAndEmit(receiverType, ref, verb, refuse);
+            continue;
+        }
+        const receiverType = typeOfReceiver(ref.receiver);
+        if (receiverType === undefined)
+            continue;
+        const refuse = (reason, diagnosis) => {
+            refusals.push({ fromId, raw: ref.raw, line: ref.line, reason, ...diagnosis });
+        };
+        const builderMethods = BUILDER_CLIENT_TYPES[receiverType];
+        if (builderMethods?.has(ref.name) === true) {
+            refuse(`an HTTP call through ${receiverType}, via a request object built in a separate expression ` +
+                `— this adapter reads only a path passed directly as this call's own argument, not one ` +
+                `assembled through a separate constructor or builder chain and passed in.`, CAPABILITY_GAP);
+            continue;
+        }
+        if (WEBCLIENT_SPLIT_BUILDER_TYPES.has(receiverType) && ref.name === "uri") {
+            refuse(`a WebClient/RestClient \`.uri(...)\` call through a ${receiverType} held in a variable — ` +
+                `the opening \`.get()\`/\`.post()\`/... call that carries the verb is a separate statement ` +
+                `this adapter does not trace back to, so the verb is unrecoverable here even though the ` +
+                `path is a literal. See ledger row D-FIX-3's split-variable case.`, CAPABILITY_GAP);
+            continue;
+        }
+        if (!CLIENT_TYPES.has(receiverType))
+            continue;
+        if (!URL_FIRST.has(ref.name))
+            continue;
+        const verb = VERB[ref.name];
+        if (verb === undefined) {
+            refuse(`an HTTP call through ${receiverType}, but \`${ref.name}\` takes its method as a ` +
+                `separate argument — an enum reference this adapter does not read. Refused rather ` +
+                `than defaulted to GET: a wrong verb mints an endpoint that joins the wrong route, ` +
+                `or none, and root-cause traversal would follow it.`, CAPABILITY_GAP);
+            continue;
+        }
+        readPathAndEmit(receiverType, ref, verb, refuse);
+    }
+    return { calls, refusals };
+}
+/**
+ * The `API_ENDPOINT` a call joins to — minted identically to the route side.
+ *
+ * Shares `endpointQsp` with `extract.ts`'s `SERVES_API` block rather than
+ * recomputing the id, because the two must agree exactly and the failure when
+ * they do not is silent.
+ */
+export function endpointFor(scope, call, producedBy, normalise) {
+    const template = normalise(call.template);
+    return {
+        id: nodeId(scope, "API_ENDPOINT", endpointQsp(call.verb, call.template), null),
+        type: "API_ENDPOINT",
+        name: `${call.verb} ${template}`,
+        file: null,
+        range: null,
+        language: null,
+        producedBy,
+        resolution: 2,
+        attrs: { method: call.verb, pathTemplate: template },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/extract.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 { type IdentityScope, type IREdge, type IRNode, type ResolutionLevel, type UnresolvedRef } from "@descryy/ir";
+import type { JavaUnit } from "./parse.ts";
+export declare const LANGUAGE = "java";
+/** A compilation unit with no `package` declaration. Not a legal package name,
+ *  so it cannot collide with one. */
+export declare const DEFAULT_PACKAGE = "(default)";
+export interface ExtractInput {
+    readonly repo: string;
+    readonly scope: IdentityScope;
+    readonly producedBy: string;
+    readonly reached: ResolutionLevel;
+    readonly units: readonly JavaUnit[];
+}
+export interface Extraction {
+    readonly nodes: readonly IRNode[];
+    readonly edges: readonly IREdge[];
+    readonly unresolved: readonly UnresolvedRef[];
+}
+export declare function extract(input: ExtractInput): Extraction;
+//# sourceMappingURL=extract.d.ts.map

package/dist/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAOL,KAAK,aAAa,EAClB,KAAK,MAAM,EACX,KAAK,MAAM,EACX,KAAK,eAAe,EACpB,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAiC,QAAQ,EAAE,MAAM,YAAY,CAAC;AAK1E,eAAO,MAAM,QAAQ,SAAS,CAAC;AAK/B;qCACqC;AACrC,eAAO,MAAM,eAAe,cAAc,CAAC;AAwC3C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;CAC/C;AAwJD,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,UAAU,CA+vBvD"}