@descryy/adapter-kotlin 0.4.0 → 0.5.0

package/dist/external.js

@@ -0,0 +1,226 @@
+/**
+ * The dependency boundary, Kotlin side.
+ *
+ * `client.get(url)` on an `io.ktor.client.HttpClient`, or `Json.encodeToString(x)`
+ * on `kotlinx.serialization.json.Json`, leaves the repository. Today that becomes
+ * a ledger row saying there is no declaration for the name in the analysed set,
+ * 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 all of these) that binding
+ * is the file's own `import` block. Kotlin's is the same statement — and Kotlin
+ * makes it stricter than Java does, which is why this file is shorter than
+ * `adapter-java/src/external.ts`:
+ *
+ *   - **A Kotlin import names a symbol, not only a type.** `import
+ *     io.ktor.server.request.receive` imports an extension function; `import
+ *     okhttp3.Request` imports a class; `import kotlin.test.assertEquals`
+ *     imports a top-level function. All three are the same statement and all
+ *     three bind one local name.
+ *   - **There is no inline fully-qualified fallback here.** Java attributes
+ *     `java.util.List` written out at the reference, because Java code writes
+ *     FQNs inline often enough to be worth the naming-convention rule it takes
+ *     to read one. Kotlin's `parse.ts` reports a receiver as a written *name*
+ *     and a dotted path is a value traversal far more often than a package, so
+ *     the same rule would buy little and cost precision. Only an import is read.
+ *
+ * Nothing here reads a Gradle configuration, a resolved classpath, `~/.m2` or a
+ * jar. Two reasons, the same two Go gives: most checkouts have no dependencies
+ * fetched, and an identity taken from a resolved classpath would *move* the
+ * first time somebody ran a build.
+ *
+ * ## Where the package ends and the symbol begins
+ *
+ * Java's `external.ts` cuts a fully-qualified name at its first capitalised
+ * segment, which works because a Java import always ends at a type. **A Kotlin
+ * import does not**: `io.ktor.server.request.receive` has no capitalised segment
+ * at all. So the cut here is the import statement's own structure first — the
+ * last segment is the imported symbol, the rest is where it lives — and the
+ * capitalisation rule only refines it, to keep a nested symbol
+ * (`okhttp3.Headers.Companion.of`) attached to the type that owns it rather than
+ * turned into three package segments.
+ *
+ * ## The refusals, and what each costs
+ *
+ *   - **A wildcard import binds no name.** `import io.ktor.util.*` then
+ *     `escapeHTML()` could come from that package or any other wildcard in the
+ *     file. Python's `from x import *` refusal, for the same reason.
+ *   - **Kotlin's default imports are never written.** `List`, `println`,
+ *     `String`, `require` arrive with no import statement anywhere, because the
+ *     compiler imports `kotlin.*`, `kotlin.collections.*`, `kotlin.io.*` and
+ *     `java.lang.*` into every file. A language rule filling a silence is not a
+ *     binding a developer wrote, and this is the single largest recall cost here.
+ *   - **A symbol under one of the repository's own packages is ours**, analysed
+ *     or not. Unanalysed code of ours is still ours.
+ *   - **The reflection packages are declined** — see `DYNAMIC_DISPATCH_PACKAGES`.
+ *
+ * **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 toolchain a developer happens to have installed.
+ *
+ * `kotlinx` is deliberately **not** here: `kotlinx.coroutines` and
+ * `kotlinx.serialization` are separately released libraries, not the standard
+ * library, and calling them platform would be a wrong disclosure on thousands
+ * of nodes. `javax` is split for the same reason `adapter-java` splits it.
+ */
+export const PLATFORM_BASIS = "kotlin-2 stdlib (kotlin.) plus jdk-21 java./jdk./sun./com.sun. roots and the JDK's own javax subpackages";
+const PLATFORM_ROOTS = ["kotlin", "java", "jdk", "sun", "com.sun"];
+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.
+ *
+ * Golden pattern 12 — the corpus's most important fixture — forbids a `CALLS`
+ * edge out of a method that dispatches reflectively, *to any target at any
+ * resolution*. An edge into `Method.invoke` or a `KFunction.call` would be
+ * true and would still be 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. `adapter-java` declines the same two JDK packages for the
+ * same reason. Filed as
+ * `DEC-NEXT-external-nodes-through-the-reflection-packages`.
+ */
+const DYNAMIC_DISPATCH_PACKAGES = [
+    "java.lang.reflect",
+    "java.lang.invoke",
+    "kotlin.reflect",
+];
+/** Is `name` the package `prefix`, or inside it? Whole segments only — a raw
+ *  `startsWith` would put `io.ktor.serverx` inside `io.ktor.server`, 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;
+    }
+    return PLATFORM_JAVAX.has(pkg.split(".").slice(0, 2).join("."));
+}
+/** A package segment, by the JVM's own naming convention: packages are
+ *  lowercase and types are capitalised. */
+function isPackageSegment(segment) {
+    return /^[a-z_$]/.test(segment);
+}
+/**
+ * An import path split into the package that holds it and the symbol chain
+ * inside that package.
+ *
+ * The import statement settles the coarse split by itself — the last segment is
+ * the symbol — and the capitalisation rule refines it so a nested symbol stays
+ * attached to the type that owns it:
+ *
+ *   `okhttp3.Request`                      -> `okhttp3`              + `Request`
+ *   `io.ktor.server.request.receive`       -> `io.ktor.server.request` + `receive`
+ *   `okhttp3.Headers.Companion.of`         -> `okhttp3`              + `Headers.Companion.of`
+ *
+ * `null` when the path names no package at all (a single segment), which an
+ * import of a dependency's symbol never is.
+ */
+export function splitImportPath(path) {
+    const parts = path.split(".");
+    if (parts.length < 2 || parts.some((part) => part === ""))
+        return null;
+    let cut = 0;
+    while (cut < parts.length && isPackageSegment(parts[cut]))
+        cut += 1;
+    // No capitalised segment anywhere: a top-level function or property, and the
+    // statement's own structure is the only thing that says where it lives.
+    if (cut === parts.length)
+        cut = parts.length - 1;
+    if (cut === 0)
+        return null;
+    return { pkg: parts.slice(0, cut).join("."), symbols: parts.slice(cut) };
+}
+function isOurs(path, context) {
+    for (const own of context.ownPackages) {
+        if (own !== "" && isUnder(path, own))
+            return true;
+    }
+    return false;
+}
+/**
+ * The package and symbol behind a name that left the repository, or `null` when
+ * no import the developer wrote binds it.
+ *
+ * `written` is the local name at the reference — a type name, a receiver, or a
+ * bare callee. `extra` is whatever was named on it: `["get"]` for a method call
+ * on an imported type, empty for a type reference.
+ */
+export function attributeExternal(written, extra, context) {
+    const name = written.trim();
+    if (name === "")
+        return null;
+    // A dotted name is a value traversal far more often than a package here, and
+    // reading one would need the type of its head — a question no import table
+    // answers. Java's inline-FQN branch is deliberately absent; see the header.
+    if (name.includes("."))
+        return null;
+    if (extra.some((part) => part === ""))
+        return null;
+    const imported = context.imports.get(name);
+    if (imported === undefined || imported.path === "")
+        return null;
+    if (isOurs(imported.path, context))
+        return null;
+    const split = splitImportPath(imported.path);
+    if (split === null)
+        return null;
+    for (const dynamic of DYNAMIC_DISPATCH_PACKAGES) {
+        if (isUnder(split.pkg, dynamic))
+            return null;
+    }
+    return {
+        moduleOrNamespace: split.pkg,
+        // The symbol the DEPENDENCY exports, never the local alias: `import a.b.C as
+        // D` is identified by `C`, because `D` is a fact about this file and not
+        // about the dependency.
+        symbolPath: [...split.symbols, ...extra],
+        binding: imported.aliased ? "import-alias" : "import",
+        thirdParty: !isPlatform(split.pkg),
+    };
+}
+/**
+ * This file's non-wildcard imports, as `attributeExternal` reads them.
+ *
+ * A wildcard is dropped: it names a package and binds no local name, so there
+ * is no written binding to read. A name bound twice by two different statements
+ * is dropped outright — which import wins is a question the source did not
+ * answer here, and Python's conditional-import refusal is the same call.
+ */
+export function externalImportTable(imports) {
+    const table = new Map();
+    const conflicted = new Set();
+    for (const each of imports) {
+        if (each.isWildcard)
+            continue;
+        if (each.path === "")
+            continue;
+        const local = each.alias ?? (each.path.split(".").pop() ?? "");
+        if (local === "")
+            continue;
+        const existing = table.get(local);
+        if (existing !== undefined && existing.path !== each.path) {
+            conflicted.add(local);
+            table.delete(local);
+            continue;
+        }
+        if (conflicted.has(local))
+            continue;
+        table.set(local, { path: each.path, aliased: each.alias !== undefined });
+    }
+    return table;
+}
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAgCH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GACzB,0GAA0G,CAAC;AAE7G,MAAM,cAAc,GAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;AAEtF,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;;;;;;;;;;;GAWG;AACH,MAAM,yBAAyB,GAAsB;IACnD,mBAAmB;IACnB,kBAAkB;IAClB,gBAAgB;CACjB,CAAC;AAEF;;sEAEsE;AACtE,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,OAAO,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAClE,CAAC;AAED;2CAC2C;AAC3C,SAAS,gBAAgB,CAAC,OAAe;IACvC,OAAO,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvE,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,6EAA6E;IAC7E,wEAAwE;IACxE,IAAI,GAAG,KAAK,KAAK,CAAC,MAAM;QAAE,GAAG,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IACjD,IAAI,GAAG,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3B,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,SAAS,MAAM,CAAC,IAAY,EAAE,OAAwB;IACpD,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACtC,IAAI,GAAG,KAAK,EAAE,IAAI,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;IACpD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,KAAwB,EACxB,OAAwB;IAExB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC7B,6EAA6E;IAC7E,2EAA2E;IAC3E,4EAA4E;IAC5E,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnD,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,IAAI,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAChE,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAEhD,MAAM,KAAK,GAAG,eAAe,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7C,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;IAED,OAAO;QACL,iBAAiB,EAAE,KAAK,CAAC,GAAG;QAC5B,6EAA6E;QAC7E,yEAAyE;QACzE,wBAAwB;QACxB,UAAU,EAAE,CAAC,GAAG,KAAK,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC;QACxC,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,QAAQ;QACrD,UAAU,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC;KACnC,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAA+G;IAE/G,MAAM,KAAK,GAAG,IAAI,GAAG,EAA8C,CAAC;IACpE,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,UAAU;YAAE,SAAS;QAC9B,IAAI,IAAI,CAAC,IAAI,KAAK,EAAE;YAAE,SAAS;QAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/D,IAAI,KAAK,KAAK,EAAE;YAAE,SAAS;QAC3B,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;YAC1D,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACtB,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACpB,SAAS;QACX,CAAC;QACD,IAAI,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,SAAS;QACpC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/extract.d.ts

@@ -24,6 +24,7 @@
  */
 import { type IRBatch, type ResolutionLevel } from "@descryy/ir";
 import type { KotlinFile } from "./parse.ts";
+import type { ShapeReach } from "./shape-reach.ts";
 export interface ExtractInput {
     readonly files: readonly KotlinFile[];
     readonly producedBy: string;
@@ -37,6 +38,12 @@ export interface ExtractInput {
      * conformance harness flags as `RESOLUTION_EXCEEDS_BATCH`.
      */
     readonly reached: ResolutionLevel;
+    /**
+     * The JPA entity map, read once by `adapter.ts` (it decides `reached`) and
+     * handed on unchanged so the batch is never read twice. `undefined` when
+     * nothing parsed.
+     */
+    readonly reach?: ShapeReach | undefined;
 }
 export declare function extract(input: ExtractInput): Pick<IRBatch, "nodes" | "edges" | "unresolved">;
 //# 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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAKL,KAAK,OAAO,EAGZ,KAAK,eAAe,EAErB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,YAAY,CAAC;AAqB9D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC;IACnF;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC;AASD,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,YAAY,CAAC,CA+tB5F"}
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAML,KAAK,OAAO,EAGZ,KAAK,eAAe,EAErB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,YAAY,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AA+CnD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC;IACnF;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CACzC;AASD,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,YAAY,CAAC,CA+/B5F"}