@descryy/adapter-java 0.1.0

package/dist/parse.d.ts

@@ -0,0 +1,297 @@
+/**
+ * One Java compilation unit, read into the shape the resolver wants.
+ *
+ * The walk is hand-written rather than expressed as tree-sitter queries. A query
+ * returns matches; what this needs is *containment* — which class a method
+ * belongs to, which method a call sits in, which type a field was declared with —
+ * and containment is exactly what a match set discards. The TypeScript and Python
+ * extractors are both shaped this way for the same reason.
+ */
+import type { Node } from "@descryy/adapter-treesitter";
+export type TypeKind = "class" | "interface" | "enum" | "record" | "annotation";
+export interface JavaRef {
+    /**
+     * `call` — a method invocation.
+     * `type` — a name in type position: a field's type, a parameter, a `new`.
+     * `member` — a name reached through a dotted access, `Status.PENDING`.
+     *
+     * `member` is a *candidate* and nothing more. `x.y` is a type reference when
+     * `x` names a type and a field read when it names a variable, and which one it
+     * is cannot be known until the enclosing scope is built. The parse records the
+     * question; the resolver answers it against the declarations it has, and drops
+     * the reference when the receiver turns out to be a variable.
+     */
+    readonly kind: "call" | "type" | "member";
+    /** The name being referred to: a method name, or a type's simple name. */
+    readonly name: string;
+    /**
+     * For a call, the text of the receiver: `undefined` when unqualified, `"this"`
+     * for `this.f()`, otherwise the identifier or dotted path as written.
+     */
+    readonly receiver: string | undefined;
+    readonly line: number;
+    /** The source text of the whole reference, for the ledger. */
+    readonly raw: string;
+    /**
+     * For a call, the first argument **when it is a bare string literal**.
+     *
+     * `undefined` covers three different situations on purpose — no arguments, a
+     * non-literal first argument, and a literal glued to something else — because
+     * the client-call reader treats all three identically: it declines. A path
+     * assembled at run time is not a path this adapter can read (DEC-127), and an
+     * endpoint template invented here would join a caller to a route it never
+     * calls.
+     *
+     * Only the first argument, because every client method this feeds takes the
+     * URL first: `getForEntity(url, type)`, `exchange(url, method, …)`,
+     * `uri(path)`. A reader that searched all arguments for something
+     * path-shaped would find request bodies.
+     *
+     * Optional rather than `string | undefined`, because a `type` or `member` ref
+     * has no arguments at all and writing `firstStringArgument: undefined` on
+     * every one of them would assert a question was asked and came back empty.
+     */
+    readonly firstStringArgument?: string;
+    /**
+     * The first argument's raw source text, captured whether or not it is a
+     * literal — DEC-242's `blockedBy`/`refusalClass` classification needs to see
+     * *what* blocked resolution (`System.getenv("BACKEND_URL")`, a bare parameter
+     * name) when {@link firstStringArgument} is absent. Same three-way
+     * `undefined` as that field: no arguments, or a `type`/`member` ref that was
+     * never asked. Unlike `firstStringArgument`, set for every non-literal shape
+     * too — the classifier, not this parse, decides what to do with it.
+     */
+    readonly firstArgumentText?: string;
+}
+/**
+ * An annotation as written, retained rather than reduced to a boolean.
+ *
+ * Until the Spring extractor there was exactly one consumer of annotations —
+ * `isTest` — and it collapsed them to a flag at parse time. A framework
+ * extractor cannot work from a flag: it needs the annotation's **name** to admit
+ * a route and its **arguments** to know the path, and the path is the whole
+ * finding.
+ *
+ * `name` is the simple name. `@GetMapping` and
+ * `@org.springframework.web.bind.annotation.GetMapping` are the same annotation
+ * written two ways, and the qualified form is kept in `qualified` so provenance
+ * can be checked against the import table without re-parsing.
+ */
+export interface JavaAnnotation {
+    /** Simple name: `GetMapping`. */
+    readonly name: string;
+    /** As written, which may be qualified: `org.springframework...GetMapping`. */
+    readonly qualified: string;
+    readonly line: number;
+    /**
+     * The unnamed argument's string literals — `@GetMapping("/{id}")` gives one.
+     *
+     * **A list rather than a single value, because the array form is common and
+     * every element is a real declaration.** `@GetMapping({"/a", "/b"})` serves
+     * two paths, and taking only the first would silently halve the answer.
+     * Measured before this shape was chosen: `shopizer` writes **140** of its 356
+     * mappings in the array form against 216 plain, so a single-value reader loses
+     * 39% of one corpus with nothing in the output to show for it.
+     *
+     * Quotes stripped. Empty when the annotation is a marker, or when the argument
+     * is not a literal — a constant reference or a concatenation. **A non-literal
+     * argument yields nothing rather than its source text**: a path assembled at
+     * runtime is not a path this adapter can read, and DEC-127 refuses it rather
+     * than guessing.
+     */
+    readonly values: readonly string[];
+    /**
+     * Named arguments whose values are string literals — `path = "/x"`,
+     * `value = {"/a", "/b"}`. A list per key, for the reason above. Non-literal
+     * values are omitted.
+     *
+     * `method = RequestMethod.GET` is deliberately *not* here: it is a field
+     * access, not a literal. Verbs are read separately by the extractor, which
+     * knows the enum, because a parse that special-cased Spring's enum would be a
+     * framework leaking into the language layer.
+     */
+    readonly named: ReadonlyMap<string, readonly string[]>;
+    /** Every argument's raw source text, for the cases a literal reader must refuse. */
+    readonly rawArguments: readonly string[];
+}
+export interface JavaMethod {
+    readonly name: string;
+    /** Fully-qualified: `pkg.Outer.Inner.method`. Parameters are not part of it. */
+    readonly fqn: string;
+    readonly startLine: number;
+    readonly endLine: number;
+    readonly isTest: boolean;
+    /** Annotations on the declaration, in source order. See {@link JavaAnnotation}. */
+    readonly annotations: JavaAnnotation[];
+    /**
+     * The declared return type, read once with the same four answers a field gets.
+     *
+     * Spring's `@Controller` handlers are the reason. A bare `@Controller`
+     * returns *view names*, so DEC-127 refuses its handlers unless one opts out
+     * with `@ResponseBody` — and that rule disclosed, with a population, that it
+     * drops handlers returning `ResponseEntity<T>`, which are real API routes
+     * needing no such annotation. The blocker recorded there was that the parse
+     * did not carry the return type. It does now.
+     *
+     * `readTypeName` rather than a `string | undefined`: absent (a constructor),
+     * `void`, and unreadable are three different facts, and collapsing them into
+     * one sentinel is the defect this file already paid 126 wrong columns for.
+     */
+    readonly returnType: TypeRead;
+    readonly refs: JavaRef[];
+    /**
+     * Local variables and parameters, name -> declared type simple name.
+     *
+     * `null` marks a name declared twice with different types, or declared with
+     * `var`. A name whose type is uncertain resolves to nothing at all rather than
+     * to the first guess — the whole receiver-typing gain below rests on the
+     * declared type being *the* type, so an ambiguous entry must poison itself.
+     */
+    readonly locals: Map<string, string | null>;
+    /**
+     * Names declared in the method's own parameter list — a subset of
+     * {@link locals}'s keys, kept separately because DEC-242's `varies-per-call`
+     * classification needs *parameter*, not *local*: a call argument that is a
+     * bare parameter name is a caller-supplied value with no fixed answer to
+     * state; a local variable might still be assigned from a constant.
+     */
+    readonly parameterNames: Set<string>;
+}
+/**
+ * A field declaration, kept alongside the `fields` name→type map.
+ *
+ * The map exists for receiver typing and answers "what type is this name". JPA
+ * needs three more things the map cannot carry: the **annotations**, the
+ * **line**, and whether the declared type is a **primitive**.
+ *
+ * The last one is load-bearing and is DEC-127 §3's named hazard. `long` cannot
+ * hold null and `Long` can, so `long totalAmount` is a NOT NULL column with no
+ * annotation anywhere to say so. An extractor reading the type as text without
+ * knowing the distinction gets golden 06 wrong in the direction that matters —
+ * and golden 06 fails an adapter that reports the fields and loses `nullable`.
+ */
+export interface JavaField {
+    readonly name: string;
+    /** Declared type's base name, generics stripped: `Long`, `long`, `String`. */
+    readonly declaredType: string | undefined;
+    /** True for the eight Java primitives, which can never be null. */
+    readonly primitive: boolean;
+    readonly line: number;
+    readonly annotations: JavaAnnotation[];
+    /**
+     * Keyword modifiers as written: `private`, `static`, `final`, `transient`.
+     *
+     * A field's *modifiers* decide whether it is persistent at all, and reading
+     * only its annotations cannot see that. JPA persists no `static` and no
+     * `transient` field — `private static final long serialVersionUID = 1L;` is
+     * on almost every entity in a real codebase and is not a column. Emitting it
+     * is a wrong answer with a plausible name, not a silence.
+     */
+    readonly modifiers: readonly string[];
+}
+export interface JavaType {
+    readonly simpleName: string;
+    readonly fqn: string;
+    readonly kind: TypeKind;
+    readonly startLine: number;
+    readonly endLine: number;
+    /** Supertype names exactly as written — simple or qualified. */
+    readonly extendsNames: string[];
+    readonly implementsNames: string[];
+    /** Annotations on the type declaration. See {@link JavaAnnotation}. */
+    readonly annotations: JavaAnnotation[];
+    readonly methods: JavaMethod[];
+    /** Field name -> declared type simple name, `null` when ambiguous. */
+    readonly fields: Map<string, string | null>;
+    /** Field declarations with their annotations. See {@link JavaField}. */
+    readonly fieldDeclarations: JavaField[];
+    /** Types named in field declarations, for `USES_TYPE`. */
+    readonly typeRefs: JavaRef[];
+}
+export interface JavaUnit {
+    readonly file: string;
+    readonly packageName: string;
+    /**
+     * The identity scope this unit's symbols hash under: `module/sourceSet/pkg`.
+     *
+     * Set by the adapter rather than by the parse, because deriving it needs the
+     * repository on disk. See `roots.ts` for why a Java package alone is not
+     * enough to identify a Java type.
+     */
+    readonly identityPackage: string;
+    /** Simple name -> fully-qualified name, from `import a.b.C;`. */
+    readonly singleTypeImports: Map<string, string>;
+    /**
+     * Member name -> declaring type, from `import static a.b.C.method;`.
+     *
+     * Java has no re-export, and this is the closest thing it has: an unqualified
+     * name in one file bound to a definition declared in another, with no new
+     * symbol created in between. It is also how every JUnit assertion is written,
+     * so without it a test file's calls are almost entirely unresolvable.
+     */
+    readonly staticMemberImports: Map<string, string>;
+    /** Package names from `import a.b.*;`. */
+    readonly wildcardImports: string[];
+    /** Every import as written, for `IMPORTS` edges and the ledger. */
+    readonly importLines: {
+        readonly fqn: string;
+        readonly wildcard: boolean;
+        readonly line: number;
+    }[];
+    readonly types: JavaType[];
+    readonly hasError: boolean;
+}
+/**
+ * What reading a type node produced — four answers, because there are four facts.
+ *
+ * This used to be `string | undefined`, and the `undefined` stood for three
+ * different things at once. **That cost 126 of `shopizer`'s 700 columns, in the
+ * wrong direction, silently:** `jpa.ts` needed to know whether a field's type was
+ * a primitive, asked this function for a name, got `undefined`, and read it as
+ * "not a primitive". Both readings of the sentinel were defensible and only one
+ * was right, which is the signature of a sentinel doing too much work.
+ *
+ * `bench/lib/README.md` names the rule and the repair: *every negative branch
+ * owes two different answers to two different questions — I looked and there is
+ * nothing, versus I did not look here. Give them different return values at
+ * construction time.* A guard at the one call site that got burned would have
+ * closed that call site and left the next reader to make the same inference from
+ * the same sentinel, with nothing failing.
+ *
+ * - `named` — a type with a declaration somewhere. The only kind an edge may
+ *   point at.
+ * - `primitive` — one of the eight, or `void`. **There is no declaration, by
+ *   design.** Not a gap, and the fact `jpa.ts` needs: a primitive column can
+ *   never be null, whatever the annotations do or do not say.
+ * - `absent` — no type node at all. A constructor's return type. Nothing to look
+ *   at, and nothing missing.
+ * - `unreadable` — a type node this reader could not name. A real gap, and the
+ *   only one of the four that should ever grow.
+ */
+export type TypeRead = {
+    readonly kind: "named";
+    readonly name: string;
+} | {
+    readonly kind: "primitive";
+    readonly name: string;
+} | {
+    readonly kind: "absent";
+} | {
+    readonly kind: "unreadable";
+};
+/**
+ * Read a type node, stripped of everything that is not identity.
+ *
+ * `List<String>` is a use of `List`; `Owner[]` is a use of `Owner`; `a.b.C` is a
+ * use of `C` qualified by a package. Generic arguments are deliberately *not*
+ * followed here — the caller walks them separately when it wants them, so that a
+ * field of type `Map<String, Owner>` can record a dependency on `Owner` without
+ * `Map` and `Owner` being confused for one another.
+ *
+ * A caller wanting a name for an edge asks for `kind === "named"` and gets the
+ * same behaviour it always had. A caller wanting to know *why* there is no name
+ * can now find out. See {@link TypeRead}.
+ */
+export declare function readTypeName(node: Node | null): TypeRead;
+export declare function readUnit(root: Node, file: string, hasError: boolean): JavaUnit;
+//# sourceMappingURL=parse.d.ts.map

package/dist/parse.d.ts.map

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