@descryy/adapter-java 0.4.1 → 0.5.1

package/dist/external.js

@@ -0,0 +1,262 @@
+/**
+ * The dependency boundary, Java side.
+ *
+ * `LoggerFactory.getLogger(Foo.class)` leaves the repository. Today that becomes
+ * a ledger row saying "names a type this run did not analyse" and the call graph
+ * stops. This module answers the one question that turns the boundary into a
+ * fact the graph can hold: **which package, and which symbol in it.**
+ *
+ * ## The rule everything here rests on: attribute only from a binding the
+ * developer wrote
+ *
+ * In Go (`adapter-go/src/external.ts`, the model for this file) that binding is
+ * the file's own `import` block. Java's is the same statement, and it is the
+ * cleanest of the ten: `import org.slf4j.Logger;` binds the simple name `Logger`
+ * to a fully-qualified name **written in the file**, and `import static
+ * org.junit.jupiter.api.Assertions.assertEquals;` binds a bare member name to
+ * the type that declares it. Nothing here reads `pom.xml`'s dependency list, a
+ * Gradle configuration, `~/.m2`, or a jar. Two reasons, the same two Go gives:
+ *
+ * 1. Most checkouts have no dependencies fetched, so an identity taken from a
+ *    resolved classpath would exist for some runs and not others.
+ * 2. It would *move* the first time somebody ran `mvn dependency:resolve`.
+ *
+ * ## Why the Maven coordinate is not the identity
+ *
+ * `org.slf4j:slf4j-api` is the obvious answer and it is the one this module
+ * refuses. A jar's package-to-coordinate mapping lives in the jar, and the root
+ * `pom.xml`'s `<dependencies>` block binds a coordinate to no package at all —
+ * so there is no declared mapping to read without the resolved classpath. The
+ * **package** is written, in the import statement, by the developer, in the
+ * file. So the package is the identity, exactly as Go's import path is Go's and
+ * PHP's namespace is PHP's.
+ *
+ * ## The three shapes Java attributes, and what each costs
+ *
+ *   - `import a.b.C;` … `C x` or `C.m()` — a single-type import. The direct
+ *     analogue of Go's package-qualified call.
+ *   - `import a.b.C;` … `C x; x.m()` — a call through a local or field whose
+ *     **written type** is an imported name. Java writes its types down where Go
+ *     and PHP do not, and this is the half that makes Java worth doing.
+ *   - `import static a.b.C.m;` … `m()` — a bare name bound by a static import.
+ *     This is how every JUnit assertion is written, so without it a test file's
+ *     calls are almost entirely unattributable. Python's `from x import y` is
+ *     the same shape and was the larger half there too.
+ *
+ * ## What Java makes harder than Go, and the refusals it earns
+ *
+ * Go has no fallback: an unqualified name is package-local, full stop. Java has
+ * three, and none of them is a binding a developer wrote:
+ *
+ *   - **`java.lang` is imported implicitly.** `String`, `Integer`, `Exception`
+ *     appear with no import statement anywhere. A language rule filling a
+ *     silence is not a written binding, so they are declined — the same call
+ *     PHP's `external.ts` makes about its global-namespace fallback.
+ *   - **A wildcard import binds no name.** `import java.util.*;` then `List`
+ *     could be `java.util.List` or a type from any other wildcard in the file,
+ *     and telling them apart needs the classpath this module refuses to read.
+ *     Python's `from x import *` refusal, for the same reason.
+ *   - **Same-package types resolve without an import.** A name settled that way
+ *     is ours by construction, and `resolveType` has already claimed it.
+ *
+ * One more refusal is Java-specific and is a **precision** refusal rather than a
+ * recall one: `extract.ts`'s `REASONS.outside` discloses that some `outside`
+ * rows are declarations in *another language in this same repository* — 238 of
+ * `okhttp`'s 458 are in `.kt` files. The own-package check below is what keeps
+ * those from being called dependencies, and it is whole-segment, so a Kotlin
+ * class in a package this repository's Java sources also declare is ours.
+ *
+ * **Everything this module does not attribute is a deliberate refusal.** Rule 2
+ * prices a wrong edge far above a missing one.
+ */
+/**
+ * Provenance of the platform-package list, carried on every attributed node.
+ * A property of the language and its JDK, frozen into this source — never read
+ * from whatever JDK a developer happens to have installed, which would make the
+ * answer depend on the machine.
+ *
+ * `javax` is split rather than taken whole: `javax.swing` ships with the JDK and
+ * `javax.persistence` never did. Taking the whole prefix either way is a wrong
+ * disclosure on thousands of nodes, and the list is short enough to write down.
+ */
+export const PLATFORM_BASIS = "jdk-21 java./jdk./sun./com.sun. roots, plus the JDK's own javax subpackages";
+/** Package roots the JDK owns outright. */
+const PLATFORM_ROOTS = ["java", "jdk", "sun", "com.sun"];
+/** The `javax` subpackages the JDK ships. Everything else under `javax` is a jar. */
+const PLATFORM_JAVAX = new Set([
+    "javax.accessibility", "javax.annotation", "javax.crypto", "javax.imageio",
+    "javax.lang", "javax.management", "javax.naming", "javax.net", "javax.print",
+    "javax.rmi", "javax.script", "javax.security", "javax.smartcardio", "javax.sound",
+    "javax.sql", "javax.swing", "javax.tools", "javax.transaction", "javax.xml",
+]);
+/**
+ * The packages whose whole purpose is to make a call target dynamic.
+ *
+ * `java.lang.reflect.Method.invoke` and `java.lang.invoke`'s method handles are
+ * where a Java call graph deliberately stops being readable, and golden pattern
+ * 12 — the corpus's most important fixture — forbids a `CALLS` edge out of a
+ * method that dispatches through them *to any target at any resolution*. The
+ * edge this module would otherwise mint is true (`method.invoke` really does
+ * reach `Method.invoke`), and it is still the one edge that pattern exists to
+ * forbid: it makes a traversal look as though it continued through a site where
+ * the graph cannot see the next hop.
+ *
+ * So these are declined, and the cost is disclosed rather than argued away:
+ * measured at 3 nodes and 3 edges on `airbyte`, and 0 of either on
+ * `spring-petclinic`. Neither subject moved a recall point.
+ * Filed as `DEC-NEXT-external-nodes-through-the-reflection-packages`.
+ */
+const DYNAMIC_DISPATCH_PACKAGES = ["java.lang.reflect", "java.lang.invoke"];
+/** Is `name` the package `prefix`, or inside it? Whole segments only — a raw
+ *  `startsWith` would put `com.acme.servicebus` inside `com.acme.service`, which
+ *  is the vendor-namespace hazard rule 2 prices above a missing edge. */
+function isUnder(name, prefix) {
+    return name === prefix || name.startsWith(`${prefix}.`);
+}
+function isPlatform(pkg) {
+    for (const root of PLATFORM_ROOTS) {
+        if (isUnder(pkg, root))
+            return true;
+    }
+    const head = pkg.split(".").slice(0, 2).join(".");
+    return PLATFORM_JAVAX.has(head);
+}
+/** A package segment, by Java's own naming convention: packages are lowercase
+ *  and types are capitalised. Read from the source text and nothing else — the
+ *  alternative is the classpath, which this module does not read. */
+function isPackageSegment(segment) {
+    return /^[a-z_$]/.test(segment);
+}
+/**
+ * A fully-qualified name split into the package that names it and the symbol
+ * chain inside it: `java.util.Map.Entry` -> `java.util` + `Map.Entry`.
+ *
+ * `null` when the convention does not settle it — no lowercase prefix (a
+ * default-package name, or a name already inside a type) or no capitalised
+ * segment at all (`foo.bar.baz`, which is a value traversal and not a type).
+ */
+export function splitQualifiedName(fqn) {
+    const parts = fqn.split(".");
+    if (parts.some((part) => part === ""))
+        return null;
+    let cut = 0;
+    while (cut < parts.length && isPackageSegment(parts[cut]))
+        cut += 1;
+    if (cut === 0 || cut === parts.length)
+        return null;
+    return { pkg: parts.slice(0, cut).join("."), symbols: parts.slice(cut) };
+}
+/** Generic arguments and array brackets are not part of a name's identity, and
+ *  the type arguments inside them are separate references the extractor already
+ *  files on their own. */
+export function bareTypeName(written) {
+    const cut = written.indexOf("<");
+    const head = (cut === -1 ? written : written.slice(0, cut)).trim();
+    return head.replace(/(\[\s*\])+$/, "").replace(/\.\.\.$/, "").trim();
+}
+/** The fully-qualified name a written type resolves to, and what bound it. */
+function qualify(written, imports) {
+    const name = bareTypeName(written);
+    if (name === "")
+        return null;
+    const separator = name.indexOf(".");
+    const head = separator === -1 ? name : name.slice(0, separator);
+    const imported = imports.singleTypeImports.get(head);
+    if (imported !== undefined && imported !== "") {
+        const rest = separator === -1 ? "" : name.slice(separator + 1);
+        return { fqn: rest === "" ? imported : `${imported}.${rest}`, binding: "single-type-import" };
+    }
+    // Written out in full at the reference. The developer wrote every segment, so
+    // it is as much a written binding as an import is — and unlike PHP's leading
+    // `\`, Java marks it with nothing, so the naming convention is what separates
+    // `java.util.List` from `status.value` and from `Status.PENDING`.
+    if (separator !== -1 && splitQualifiedName(name) !== null && isPackageSegment(head)) {
+        return { fqn: name, binding: "written-fully-qualified" };
+    }
+    // Nothing written bound it: `java.lang`, a wildcard import, the same package,
+    // or a nested type reached through an enclosing name we never resolved.
+    return null;
+}
+/** Ours, whether or not this run read it. */
+function isOurs(fqn, context) {
+    if (context.analysed.has(fqn))
+        return true;
+    for (const own of context.ownPackages) {
+        if (own !== "" && isUnder(fqn, own))
+            return true;
+    }
+    return false;
+}
+function attribute(fqn, binding, extra, context) {
+    if (isOurs(fqn, context))
+        return null;
+    const split = splitQualifiedName(fqn);
+    if (split === null)
+        return null;
+    for (const dynamic of DYNAMIC_DISPATCH_PACKAGES) {
+        if (isUnder(split.pkg, dynamic))
+            return null;
+    }
+    const symbolPath = [...split.symbols, ...extra];
+    if (symbolPath.some((part) => part === ""))
+        return null;
+    return {
+        moduleOrNamespace: split.pkg,
+        symbolPath,
+        binding,
+        thirdParty: !isPlatform(split.pkg),
+    };
+}
+/**
+ * The package and type behind a **type reference** that left the repository, or
+ * `null` when no binding the developer wrote settles it.
+ *
+ * `written` is the name exactly as the source wrote it — `Logger`,
+ * `java.util.List`, `Map.Entry`.
+ */
+export function attributeExternalType(written, context) {
+    const qualified = qualify(written, context.imports);
+    if (qualified === null)
+        return null;
+    return attribute(qualified.fqn, qualified.binding, [], context);
+}
+/**
+ * The package, type and member behind a **call** that left the repository, or
+ * `null` when no binding the developer wrote settles it.
+ *
+ * `receiverType` is the receiver's type **as the source wrote it**: the declared
+ * type of a local or field, or the type name itself for a static call. It is
+ * never inferred — a `var`, a chained call or a generic type variable writes no
+ * type at the reference and `extract.ts` hands `undefined` here for all three.
+ */
+export function attributeExternalCall(receiverType, method, context) {
+    if (receiverType === undefined || method === "")
+        return null;
+    const qualified = qualify(receiverType, context.imports);
+    if (qualified === null)
+        return null;
+    return attribute(qualified.fqn, qualified.binding, [method], context);
+}
+/**
+ * The package, type and member behind an **unqualified call bound by a static
+ * import**, or `null` when no such binding exists.
+ *
+ * `assertEquals(a, b)` under `import static org.junit.jupiter.api.Assertions.assertEquals;`
+ * is a binding the developer wrote and the language guarantees it — following it
+ * is resolution, not inference. A bare name with no static import is declined:
+ * it is the enclosing type's own member, or an inherited one from a supertype
+ * this run did not read, and neither is a dependency.
+ *
+ * `import static a.b.C.*;` binds no name and is never recorded in
+ * `staticMemberImports`, so it cannot arrive here — Python's `import *` refusal
+ * in the form Java's parse already applies.
+ */
+export function attributeExternalStaticCall(method, context) {
+    if (method === "")
+        return null;
+    const owner = context.imports.staticMemberImports.get(method);
+    if (owner === undefined || owner === "")
+        return null;
+    return attribute(owner, "static-import", [method], context);
+}
+//# sourceMappingURL=external.js.map

package/dist/external.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external.js","sourceRoot":"","sources":["../src/external.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AA2CH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,6EAA6E,CAAC;AAE5G,2CAA2C;AAC3C,MAAM,cAAc,GAAsB,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;AAE5E,qFAAqF;AACrF,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC;IAClD,qBAAqB,EAAE,kBAAkB,EAAE,cAAc,EAAE,eAAe;IAC1E,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa;IAC5E,WAAW,EAAE,cAAc,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,aAAa;IACjF,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,mBAAmB,EAAE,WAAW;CAC5E,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,yBAAyB,GAAsB,CAAC,mBAAmB,EAAE,kBAAkB,CAAC,CAAC;AAE/F;;yEAEyE;AACzE,SAAS,OAAO,CAAC,IAAY,EAAE,MAAc;IAC3C,OAAO,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,UAAU,CAAC,GAAW;IAC7B,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;QAClC,IAAI,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;IACtC,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClD,OAAO,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC;AAED;;qEAEqE;AACrE,SAAS,gBAAgB,CAAC,OAAe;IACvC,OAAO,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IACnD,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,OAAO,GAAG,GAAG,KAAK,CAAC,MAAM,IAAI,gBAAgB,CAAC,KAAK,CAAC,GAAG,CAAE,CAAC;QAAE,GAAG,IAAI,CAAC,CAAC;IACrE,IAAI,GAAG,KAAK,CAAC,IAAI,GAAG,KAAK,KAAK,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACnD,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;AAC3E,CAAC;AAED;;0BAE0B;AAC1B,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACnE,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACvE,CAAC;AAED,8EAA8E;AAC9E,SAAS,OAAO,CACd,OAAe,EACf,OAAwB;IAExB,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAE7B,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,OAAO,CAAC,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACrD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;QAC9C,MAAM,IAAI,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;QAC/D,OAAO,EAAE,GAAG,EAAE,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,IAAI,IAAI,EAAE,EAAE,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChG,CAAC;IAED,8EAA8E;IAC9E,6EAA6E;IAC7E,8EAA8E;IAC9E,kEAAkE;IAClE,IAAI,SAAS,KAAK,CAAC,CAAC,IAAI,kBAAkB,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;QACpF,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,yBAAyB,EAAE,CAAC;IAC3D,CAAC;IAED,8EAA8E;IAC9E,wEAAwE;IACxE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,6CAA6C;AAC7C,SAAS,MAAM,CAAC,GAAW,EAAE,OAAwB;IACnD,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACtC,IAAI,GAAG,KAAK,EAAE,IAAI,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;IACnD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,SAAS,CAChB,GAAW,EACX,OAAgB,EAChB,KAAwB,EACxB,OAAwB;IAExB,IAAI,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,KAAK,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,KAAK,MAAM,OAAO,IAAI,yBAAyB,EAAE,CAAC;QAChD,IAAI,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;IAC/C,CAAC;IACD,MAAM,UAAU,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,CAAC;IAChD,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IACxD,OAAO;QACL,iBAAiB,EAAE,KAAK,CAAC,GAAG;QAC5B,UAAU;QACV,OAAO;QACP,UAAU,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC;KACnC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAe,EACf,OAAwB;IAExB,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACpD,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO,SAAS,CAAC,SAAS,CAAC,GAAG,EAAE,SAAS,CAAC,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CACnC,YAAgC,EAChC,MAAc,EACd,OAAwB;IAExB,IAAI,YAAY,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC7D,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO,SAAS,CAAC,SAAS,CAAC,GAAG,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,2BAA2B,CACzC,MAAc,EACd,OAAwB;IAExB,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IACrD,OAAO,SAAS,CAAC,KAAK,EAAE,eAAe,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC"}

package/dist/extract.d.ts

@@ -60,5 +60,34 @@ export interface Extraction {
     readonly edges: readonly IREdge[];
     readonly unresolved: readonly UnresolvedRef[];
 }
+/**
+ * The fallback graph when `extract()` throws mid-run, per
+ * `DEC-NEXT-degraded-graph-shape-for-adapters-without-one.md`.
+ *
+ * `FILE`, not `MODULE`: a Java module's identity here is `identityPackage`,
+ * and `identityPackage` is derived from `unit.packageName` — the `package
+ * a.b.c;` statement *inside* the file (`roots.ts`'s `identityPackage`,
+ * layered over a source-set anchor only when one resolves; the package name
+ * itself is never filesystem-derivable, since Java allows — and this corpus
+ * contains — a file whose directory does not match its declared package).
+ * A mid-extraction throw means exactly this machinery cannot be trusted to
+ * have run to completion. Unlike Go's import path or Rust's crate/module
+ * path — both resolved from the file's own location plus a manifest, never
+ * from parsed content — nothing about a Java file's identity is recoverable
+ * without a successful parse. `FILE` (via the shared
+ * `@descryy/adapter-common#fileNode` helper) is the fact that survives: the
+ * file exists, on disk, at this path, and that is all this function claims.
+ *
+ * One disclosure row, not one per file — the fact is about the run. Anchored
+ * to the first file's `FILE` node because the ledger requires a `fromNodeId`
+ * and `FILE` is the only node type this path emits.
+ */
+export declare function degradedGraph(input: {
+    readonly repo: string;
+    readonly workspace: string | undefined;
+    readonly producedBy: string;
+    readonly files: readonly string[];
+    readonly cause: string;
+}): Extraction;
 export declare function extract(input: ExtractInput): Extraction;
 //# sourceMappingURL=extract.d.ts.map

package/dist/extract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;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;AAC1E,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAKpD,eAAO,MAAM,QAAQ,SAAS,CAAC;AAK/B;qCACqC;AACrC,eAAO,MAAM,eAAe,cAAc,CAAC;AAyC3C,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;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CACnD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CA6BtF;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;AA6ID,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,UAAU,CAqrBvD"}
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAQL,KAAK,aAAa,EAClB,KAAK,MAAM,EACX,KAAK,MAAM,EACX,KAAK,eAAe,EACpB,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAIrB,OAAO,KAAK,EAAiC,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC1E,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAepD,eAAO,MAAM,QAAQ,SAAS,CAAC;AAiB/B;qCACqC;AACrC,eAAO,MAAM,eAAe,cAAc,CAAC;AA2E3C,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;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CACnD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CA6BtF;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;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,GAAG,UAAU,CA0Bb;AA6ID,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,UAAU,CA+lCvD"}