gitnexus 1.6.10 → 1.6.11-rc.2

package/dist/core/ingestion/route-extractors/kotlin-const-resolver.d.ts

@@ -0,0 +1,377 @@
+/**
+ * Kotlin binding for the language-agnostic constant resolver (#2391 core).
+ *
+ * Supplies the two Kotlin-specific pieces — {@link resolveKotlinImport} (import
+ * specifier → file, honoring JVM package rules) and
+ * {@link extractKotlinModuleConstants} (tree → {@link ModuleConstants}) — plus
+ * the folding entry points {@link resolveKotlinConstant} and
+ * {@link foldKotlinOperands}, so callers stay language-oblivious.
+ *
+ * WHAT IS ACTUALLY SHARED WITH THE AGNOSTIC CORE. One value —
+ * {@link MAX_FOLD_LENGTH} — and five types. The core's own `resolveConstant` /
+ * `resolveOperands` are NOT called: the fold state machine below (cycle guard,
+ * success memo, depth caps, operand concatenation — roughly 200 of this file's
+ * lines) is a local fork, close enough to `java-const-resolver.ts`'s already
+ * forked copy that the two read as the same code with the language name
+ * swapped.
+ *
+ * That fork is a consequence, not an oversight. The core keys its maps by
+ * SIMPLE name, and a Kotlin operand can be a QUALIFIED reference at any
+ * position (`X = ApiPaths.Y + "/tail"`); handed to the core, `ApiPaths.Y` misses
+ * every map and floors the whole chain to null — see {@link computeKotlinFold},
+ * which resolves operands through the qualified-aware walk for exactly this
+ * reason. The import chase is Kotlin-specific too: a member import is spelled
+ * identically to a type import, so {@link resolveImportedName} has to try both
+ * readings, and the core exposes no hook for that. Java forked first on the same
+ * grounds. Teaching the core qualified names, and retiring both copies against
+ * it, is the standing follow-up; until then the honest description of this file
+ * is "a second fork", not "a binding over a shared fold".
+ *
+ * Kotlin shares the JVM package/import model with Java, so this binding mirrors
+ * `java-const-resolver.ts` in structure, naming and skip-floor discipline. The
+ * four places Kotlin genuinely differs are handled explicitly, not translated:
+ *
+ *  1. **Where a constant can live.** Java has one carrier (`static final` on a
+ *     type). Kotlin has three: a top-level `const val`/`val`, a member of an
+ *     `object`, and a member of a `companion object` — the last is referenced
+ *     through its ENCLOSING class (`Holder.NAME`), not through `Companion`.
+ *  2. **No `String` type gate.** Kotlin infers property types, so
+ *     `const val ORDERS = "/orders"` carries no type node to check. The
+ *     initializer decides: anything {@link parseKotlinConstOperands} cannot fold
+ *     to a string (a number, a call, a template) drops the constant.
+ *  3. **File names and directories are free.** `object ApiPaths` may live in
+ *     `Constants.kt`, and a file's `package` need not match the directory it
+ *     sits in, so a `<package>/<Name>.kt` PATH lookup is a convention and not a
+ *     rule. The authority is each file's DECLARED `package`, which
+ *     {@link extractKotlinModuleConstants} records and {@link resolveKotlinImport}
+ *     requires an exact match on; the path is only a tie-break among files that
+ *     already declare the right package.
+ *  4. **Member imports are unmarked.** Java spells them `import static a.b.C.F`;
+ *     Kotlin writes `import a.b.C.F`, which is byte-identical to a type import
+ *     of a class `F` in package `a.b.C`. Nothing in the syntax says which, so
+ *     the fold tries both readings (see `resolveImportedName`) instead of
+ *     guessing from casing.
+ *  5. **Any identifier may be backtick-quoted.** `` package com.example.`api` ``
+ *     and `package com.example.api` are the SAME package to the compiler, and a
+ *     keyword segment (`` com.example.`fun` ``) can only be spelled the quoted
+ *     way. The grammar keeps the backticks in the node text, so every identifier is
+ *     read through {@link unquoteKotlinIdentifier} before it becomes a map key
+ *     or a lookup name — see that function for what a verbatim comparison cost.
+ *
+ * THREE PLACES THIS BINDING NO LONGER MIRRORS JAVA, each because the mirrored
+ * behavior was wrong rather than merely different, and each open as a Java
+ * follow-up rather than fixed here:
+ *
+ *  * `java-const-resolver.ts` flattens nested types into one file-level
+ *    namespace and argues the collision away — "qualified refs carry the class
+ *    name, so nesting only matters for same-name fields, which flatten
+ *    last-wins". The argument does not hold: the collision is one level BELOW
+ *    the qualification, in the initializer, so a fully qualified `A.ROUTE` whose
+ *    initializer names a bare sibling `BASE` still resolves through whichever
+ *    same-named sibling was walked last. {@link extractKotlinModuleConstants}
+ *    keys by Kotlin's own visibility instead.
+ *  * Java's import resolution can lean on the `<package>/<Name>.java` layout the
+ *    language enforces. Kotlin's cannot, and inferring the package from the path
+ *    lets a path-suffix twin outrank the real declaration — so
+ *    {@link resolveKotlinImport} reads the declared `package` instead.
+ *  * Java's fold entry points take a file and a name, because a Java `static
+ *    final` reachable by simple name is reachable that way from anywhere in the
+ *    file. A Kotlin COMPANION member is not: it is bound unqualified only inside
+ *    its enclosing class body. {@link foldKotlinOperands} therefore also takes
+ *    the enclosing type chain of the reference site, which is what lets the
+ *    binding answer a bare reference by Kotlin's scoping rather than by "whoever
+ *    was walked last" — see {@link qualifyKotlinRefInEnclosingTypes}.
+ *
+ * Constant shapes this binding harvests:
+ *
+ *   const val TOP_LEVEL = "/api/v1"          // file top level
+ *   object ApiPaths {                        // object member
+ *       const val BASE = "/api/v1"
+ *       val ORDERS = BASE + "/orders"
+ *   }
+ *   class Holder { companion object { const val H = "/h" } }   // → Holder.H
+ *
+ * Reference shapes at annotation sites this binding resolves:
+ *   @PostMapping(ApiPaths.ORDERS)                      // qualified
+ *   @PostMapping(com.example.app.api.ApiPaths.ORDERS)  // FQN-qualified
+ *   @PostMapping(ORDERS)                               // single-name import
+ *   @PostMapping(ApiPaths.BASE + "/orders")            // inline concat
+ *
+ * Which ANNOTATIONS count as routes is a separate question this module has no
+ * say in — `spring-shared.ts` owns that map. Folding and annotation recognition
+ * compose; neither implies the other.
+ *
+ * Keying (parity with the Java and Python bindings): the repo map is keyed by
+ * unique POSIX file path, and an import that cannot be pinned to exactly one
+ * file returns null (skip floor), never a wrong path. A missing route is a
+ * missing fact; a wrongly folded one is a false edge in the graph. "Exactly one
+ * file" is decided from the DECLARED package, not from the path: a path is a
+ * repository-layout accident that any decoy directory can imitate, whereas the
+ * `package` header is the declaration the compiler itself resolves against.
+ *
+ * POSIX keys are a PRECONDITION this module cannot check cheaply, so it is
+ * enforced at the one boundary that produces them: `http-patterns/kotlin.ts`
+ * normalizes separators on both the write side (the `prepareRepo` map keys) and
+ * the read side (`scan`'s `fileRel`). It has to, because the orchestrator's file
+ * list comes from glob v13, which has no `posix: true` and joins with the
+ * platform separator — so on Windows the keys arrive backslashed and every
+ * `<pkg>/<Name>.kt` test in {@link resolveKotlinImport} would miss, silently
+ * disabling cross-file folding on that platform alone. Normalizing INSIDE this
+ * module instead cannot work: the resolver returns the key it matched, and a
+ * normalized return value would then miss in a map that was never normalized.
+ *
+ * WHERE THIS IS WIRED. Java reaches its binding from BOTH layers: the group
+ * extractor (`group/extractors/http-patterns/java.ts`) and the ingestion
+ * provider (`languages/java.ts`, via `extractModuleConstants` +
+ * `foldRoutePathOperands`). Kotlin is wired into the GROUP layer only, because
+ * the ingestion fold in `pipeline-phases/parse-impl.ts` runs exclusively over
+ * `decoratorRoutes` — and `languages/kotlin.ts` declares no
+ * `extractDecoratorRoutes`, since the ingestion Spring extractor (`spring.ts`)
+ * is bound to `tree-sitter-java` and its node types. Declaring the constant
+ * hooks on the Kotlin provider today would harvest a map on every Kotlin file
+ * that nothing consumes. An ingestion-side Kotlin route extractor is the
+ * prerequisite; when it lands, this binding is what its provider hooks should
+ * point at, and no change here is needed.
+ */
+import type Parser from 'tree-sitter';
+import { type ModuleConstants, type Operand, type RepoConstants } from './constant-resolver.js';
+export type { ImportBinding, ModuleConstants, Operand, RepoConstants, } from './constant-resolver.js';
+/**
+ * What {@link extractKotlinModuleConstants} returns: the agnostic
+ * {@link ModuleConstants} plus the one piece of per-file metadata JVM import
+ * resolution cannot be honest without — the file's declared `package`.
+ *
+ * Deliberately a KOTLIN-LOCAL widening rather than a field on the shared type.
+ * `ModuleConstants` is consumed by the Java, JS and Python bindings too, and
+ * none of them needs this: Python resolves imports from the module path, and
+ * Java's `package` is already pinned by the `<package>/<Name>.java` rule the
+ * language enforces. Adding a required field there would force three unrelated
+ * bindings to fill it in; adding an optional one would put a Kotlin-shaped hole
+ * in a type whose whole point is language neutrality.
+ *
+ * Read the metadata through {@link declaredPackageOf} and
+ * {@link unfoldableDeclarationsOf}, never by field access: a
+ * {@link RepoConstants} is typed over the agnostic shape, so an entry that some
+ * other producer put there carries no package and must be REJECTED as a
+ * candidate rather than silently treated as the default package. Missing
+ * unfoldable-declaration metadata instead means "none known", preserving the
+ * agnostic entry's existing behavior.
+ */
+export interface KotlinModuleConstants extends ModuleConstants {
+    /** The file's declared `package`, or `''` for the default package. */
+    readonly packageName: string;
+    /** Declaration keys whose initializer cannot be folded. */
+    readonly unfoldableDeclarations: ReadonlySet<string>;
+}
+/**
+ * Kotlin declaration keys known to exist but not fold, or an empty set when
+ * `mc` came from another language binding.
+ */
+export declare function unfoldableDeclarationsOf(mc: ModuleConstants | undefined): ReadonlySet<string>;
+/**
+ * The name a backtick-quoted Kotlin identifier denotes: `` `api` `` → `api`.
+ *
+ * Quotes are spelling, not part of the name. tree-sitter-kotlin keeps them in
+ * node text, so every identifier that becomes a map key or lookup is read
+ * through here. Applied per dot-separated segment — a quoted identifier cannot
+ * contain `.`. Both the declaration side ({@link declaredPackage}) and the
+ * import side ({@link resolveKotlinImport}) are normalized, because either may
+ * carry the quotes while the other spells the same name plainly.
+ */
+export declare function unquoteKotlinIdentifier(text: string): string;
+export declare function isKotlinConstantFile(source: string): boolean;
+/** Files and declaration ownership for one exact Kotlin package. */
+export interface KotlinPackageConstants {
+    readonly files: readonly string[];
+    /** Unique declaring file, or null when the package declares the name twice. */
+    readonly declarers: ReadonlyMap<string, string | null>;
+}
+/** One exact package-qualified declaration and its in-file lookup key. */
+interface KotlinImportTarget {
+    readonly fileKey: string;
+    readonly localName: string;
+}
+/**
+ * Repo-wide projections reused by every fold in one extraction run.
+ *
+ * `repo` includes importing files overlaid by `scan`; `constantKeys` and
+ * `byPackage` include only files that define a foldable or explicitly
+ * unfoldable declaration, preserving import ambiguity semantics.
+ */
+export interface KotlinConstantIndex {
+    readonly repo: RepoConstants;
+    readonly constantKeys: ReadonlySet<string>;
+    readonly byPackage: ReadonlyMap<string, KotlinPackageConstants>;
+    /** Exact FQN → unique file/local key, or null when the FQN is duplicated. */
+    readonly byFqn: ReadonlyMap<string, KotlinImportTarget | null>;
+}
+/** Build the immutable import projections once for a repo constant map. */
+export declare function buildKotlinConstantIndex(repo: RepoConstants): KotlinConstantIndex;
+/**
+ * Add one scan-time file without rebuilding the base index when it only imports
+ * constants. A newly discovered declaration is rare and rebuilds once for that
+ * file's scan, never once per route.
+ */
+export declare function overlayKotlinConstantIndex(index: KotlinConstantIndex, fileKey: string, mc: ModuleConstants): KotlinConstantIndex;
+/**
+ * Map a fully-qualified import specifier to the unique file key it refers to, or
+ * null when it cannot be pinned to exactly one file.
+ *
+ * A specifier is split at its last dot into the package it names and the
+ * declaration inside it (`com.example.app.api` + `ApiPaths`). Resolution then
+ * runs in three steps, all of them "unique or nothing":
+ *
+ *  0. **Declared package** — only files whose `package` header is EXACTLY the
+ *     sought package can carry the declaration (compared after
+ *     {@link unquoteKotlinIdentifier}, since backtick quoting is spelling and
+ *     not identity). This is the authority, and it
+ *     is checked first. Kotlin does not require a file's directory to match its
+ *     package, so the reverse test — "does this path end with the package?" —
+ *     answers a different question, one any decoy directory can satisfy: a file
+ *     at `src/x/com/example/api/ApiPaths.kt` declaring `package x.com.example.api`
+ *     is not `com.example.api.ApiPaths` and must never be folded as it, and a
+ *     path-suffix test also lets a root-level `package data` be impersonated by
+ *     `…/com/example/data/`. An entry with no recorded package is rejected, not
+ *     assumed to be the default package.
+ *  1. **Declared name** — when exactly one file declares the sought name, use
+ *     it. When two do, the FQN itself is duplicated in the repository and names
+ *     no single declaration, so return null. This is the general form of the
+ *     same-FQN check step 2 could only make for files that happen to follow the
+ *     file-name convention, and it is what stops a `src/test/…` copy of a
+ *     production constant from being folded into a production route.
+ *  2. **File named after the declaration** — when declaration metadata found no
+ *     owner, try the package-matching file ending
+ *     `com/example/app/api/ApiPaths.kt`. Kotlin does not require this (`object
+ *     ApiPaths` may live in `Constants.kt`), so it is only a fallback candidate;
+ *     the subsequent map lookup must still prove that it carries the value.
+ *  3. **Sole file in the package** — when declaration metadata cannot identify
+ *     the name, use the unique package-matching candidate. The set passed in
+ *     contains files with foldable or explicitly unfoldable declarations, so
+ *     unrelated files cannot create ambiguity once step 1 identifies a unique
+ *     declarer. With 2+ unidentified candidates it returns null.
+ *
+ * Steps 2 and 3 can still hand back a file that does not declare the wanted name
+ * (its package is right and it is the only candidate, but the name lives
+ * elsewhere or nowhere). That remains safe by construction: the fold looks the
+ * name up in that file's map, misses, and returns null.
+ *
+ * A "nearest shared directory" tie-break is deliberately NOT applied when a step
+ * has several candidates, for the reason the Java binding records: the JVM
+ * resolves duplicate FQNs by classpath order, not directory proximity, so a test
+ * fixture copy sitting closer in the tree can outrank the real dependency and
+ * yield a silently wrong literal. In a resolver whose whole contract is
+ * skip-or-correct, a plausible guess is the one answer that cannot be allowed.
+ *
+ * This can no longer be typed as the agnostic {@link ModuleConstants} consumer's
+ * `ImportResolver`, whose signature carries only file KEYS: deciding a candidate
+ * on its declared package needs the map those keys index. Nothing is lost — the
+ * core's own fold is not used here either (see the module header), and the
+ * alternative is a resolver that must guess from a path.
+ */
+export declare function resolveKotlinImport(_importingFileKey: string, rawModuleSpec: string, candidateKeys: ReadonlySet<string>, repo: RepoConstants): string | null;
+/** Indexed equivalent of {@link resolveKotlinImport}, with identical fallbacks. */
+export declare function resolveKotlinImportWithIndex(rawModuleSpec: string, index: KotlinConstantIndex): string | null;
+/**
+ * Parse a Kotlin constant initializer (or an inline annotation argument) into an
+ * operand list, or null when it is not a foldable string expression. Handles a
+ * bare string literal, a bare identifier (`X = Y`), a qualified reference
+ * (`X = ApiPaths.Y` — recorded as ONE ref named `ApiPaths.Y`), and
+ * left-associative `+` chains of the three. Everything else — numbers, calls,
+ * `when`/`if` expressions, templates, `buildString` — returns null, which makes
+ * the constant unresolvable (→ skip floor), never a wrong value.
+ *
+ * A chain nests: tree-sitter-kotlin parses `A + B + C` as
+ * `additive_expression(additive_expression(A, B), C)`, so every node here has
+ * exactly two operands and arbitrary-length chains fold by recursion. The same
+ * node type also carries `-`, which is not a string operation, so a `+` token
+ * must be present.
+ *
+ * A PARENTHESIZED operand (`(A + B) + "/c"`) is deliberately NOT unwrapped,
+ * matching `parseJavaConstOperands`, which has no parenthesis arm either. The
+ * shape is vanishingly rare in a route annotation and the cost of omitting it is
+ * a skipped route, not a wrong one; adding it to both bindings at once is the
+ * only way to keep them in parity, so it is left to a follow-up.
+ */
+export declare function parseKotlinConstOperands(node: Parser.SyntaxNode | null | undefined, depth?: number): Operand[] | null;
+/**
+ * Extract the declared package, file-level string constants and import bindings
+ * of one parsed Kotlin file into the {@link KotlinModuleConstants} shape the
+ * resolver consumes.
+ *
+ * Constants come from the three carriers Kotlin allows a caller to reach without
+ * an instance: file top level, `object` members, and `companion object` members.
+ * A `val` in a plain class or interface body is per-instance or abstract and is
+ * NOT collected — the Kotlin analogue of Java's `static final` requirement. `var`
+ * is rejected outright.
+ *
+ * KEYS FOLLOW KOTLIN'S OWN VISIBILITY, not a flattened namespace. Every constant
+ * is recorded under `<DeclaringType>.<NAME>`, the spelling a qualified reference
+ * uses, with a companion member keyed under its ENCLOSING CLASS (`Holder.NAME`)
+ * because that is how Kotlin source refers to it — `Companion` never appears in
+ * a reference. The SIMPLE name is recorded only for a TOP-LEVEL `val`, the one
+ * carrier whose bare binding really does span the file. A member of a named
+ * `object` gets no bare key, because `BASE` alone does not name `A.BASE` from
+ * anywhere outside `object A`'s own body. Writing one anyway (as this binding
+ * and the Java one both used to) fabricates a binding the language does not
+ * have, and a fabricated key outranks the genuine `import com.example.api.Paths.ORDERS`
+ * that {@link computeKotlinFold} consults only after literals and expressions.
+ *
+ * A COMPANION member gets no bare key either: it is bound unqualified inside
+ * its enclosing class body and nowhere else. {@link qualifyKotlinRefInEnclosingTypes}
+ * rewrites a bare name to `<EnclosingType>.<NAME>` when an enclosing type
+ * declares it, so the companion wins inside its own class and loses everywhere
+ * else.
+ *
+ * An initializer that names a SIBLING is resolved the same way, against its own
+ * scope chain, innermost first, before the file level: inside
+ * `object A { const val BASE = "/right"; const val ROUTE = BASE + "/m" }` the
+ * operand `BASE` is rewritten to `A.BASE`. Collecting every declaration before
+ * recording any keeps that independent of declaration order.
+ *
+ * A TOP-LEVEL initializer has an EMPTY scope chain, so its bare operands stay
+ * bare and resolve at file level — they must not pick up a companion key.
+ *
+ * A non-foldable rebind (`X = compute()`) DROPS X to unresolvable rather than
+ * leaving a stale literal — and drops a same-named import with it whenever the
+ * declaration shadows that import ANYWHERE (top level, or a companion inside its
+ * class). The import map has no scopes, so a companion's shadow is applied
+ * file-wide: the conservative direction, costing a route rather than publishing
+ * the imported value at a reference the compiler binds to the unfoldable member.
+ * An `object` member shadows nothing and must leave the import alone.
+ */
+export declare function extractKotlinModuleConstants(tree: Parser.Tree): KotlinModuleConstants;
+/**
+ * Resolve a single Kotlin constant referenced in `fileKey` to its literal string
+ * value, folding `+` concatenation and following import chains via
+ * {@link resolveKotlinImport}, or null when it cannot be fully folded.
+ *
+ * `name` may be simple (`ORDERS`, resolved via a single-name import or a
+ * same-file constant) or qualified (`ApiPaths.ORDERS`, resolved via the type
+ * import plus the target file's qualified alias).
+ */
+export declare function resolveKotlinConstant(fileKey: string, name: string, repo: RepoConstants, depth?: number, index?: KotlinConstantIndex): string | null;
+/**
+ * Fold an inline operand list (e.g. `ApiPaths.BASE + "/orders"`) against
+ * `fileKey`, or null when any piece is unresolvable (skip floor).
+ *
+ * `enclosingTypes` is the chain of type declarations the REFERENCE sits inside
+ * (innermost first), and it is applied to the entry operands only — everything
+ * deeper is either already qualified by
+ * {@link extractKotlinModuleConstants} against its own declaring scope, or lives
+ * in another file where this chain means nothing. Passing it empty answers
+ * "what does this name mean at file level", which is the right question for a
+ * reference outside any type and the only one a caller without position
+ * information can honestly ask.
+ *
+ * An empty result is a SUCCESS, not a skip. `const val ROOT = ""` folds to `""`,
+ * which `joinPath` then resolves against the class-level prefix exactly as it
+ * resolves the literal `@GetMapping("")` — both mean "the prefix itself", the
+ * Spring idiom for a collection root. Collapsing it into `null` would make a
+ * resolved-empty path indistinguishable from an unresolvable one — the skip
+ * floor is reserved for "could not fold", and nothing else in the resolver
+ * conflates the two: {@link resolveKotlinConstant} returns `''` for an empty
+ * constant, and `resolveOperands` in the shared core returns its fold
+ * unfiltered. Matches `foldJavaOperands`, so the two JVM bindings do not
+ * diverge on the same input.
+ */
+export declare function foldKotlinOperands(fileKey: string, operands: readonly Operand[], repo: RepoConstants, enclosingTypes?: readonly string[], index?: KotlinConstantIndex): string | null;