gitnexus 1.6.11-rc.8 → 1.6.11

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

@@ -95,6 +95,7 @@
  *   @PostMapping(ApiPaths.ORDERS)                      // qualified
  *   @PostMapping(com.example.app.api.ApiPaths.ORDERS)  // FQN-qualified
  *   @PostMapping(ORDERS)                               // single-name import
+ *   @PostMapping(ORDERS) after import com.example.api.* // package-star import
  *   @PostMapping(ApiPaths.BASE + "/orders")            // inline concat
  *
  * Which ANNOTATIONS count as routes is a separate question this module has no
@@ -122,19 +123,15 @@
  *
  * 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.
+ * provider (`languages/java.ts`). Kotlin now does the same: the group extractor
+ * (`group/extractors/http-patterns/kotlin.ts`) plus `languages/kotlin.ts`
+ * (`extractDecoratorRoutes`, `extractModuleConstants`, `foldRoutePathOperands`).
+ * The dedicated ingestion walker is `route-extractors/kotlin-spring.ts`; it
+ * does not reuse Java `spring.ts`.
  */
 import { unquoteSpringLiteral } from './spring-shared.js';
-import { MAX_FOLD_LENGTH, } from './constant-resolver.js';
+import { MAX_FOLD_LENGTH, unfoldableDeclarationsOf, } from './constant-resolver.js';
+export { unfoldableDeclarationsOf } from './constant-resolver.js';
 /**
  * The declared `package` of the file `mc` describes, or null when the entry did
  * not come from {@link extractKotlinModuleConstants} and therefore cannot be
@@ -144,14 +141,11 @@ function declaredPackageOf(mc) {
     const declared = mc?.packageName;
     return typeof declared === 'string' ? declared : null;
 }
-const NO_UNFOLDABLE_DECLARATIONS = new Set();
-/**
- * Kotlin declaration keys known to exist but not fold, or an empty set when
- * `mc` came from another language binding.
- */
-export function unfoldableDeclarationsOf(mc) {
-    const declarations = mc?.unfoldableDeclarations;
-    return declarations instanceof Set ? declarations : NO_UNFOLDABLE_DECLARATIONS;
+const NO_TOP_LEVEL_DECLARATIONS = new Set();
+/** Kotlin top-level names known to shadow package-star imports. */
+function topLevelDeclarationsOf(mc) {
+    const declarations = mc?.topLevelDeclarations;
+    return declarations instanceof Set ? declarations : NO_TOP_LEVEL_DECLARATIONS;
 }
 /** Source extensions a Kotlin declaration can live in. */
 const KOTLIN_EXTENSIONS = ['.kt', '.kts'];
@@ -365,6 +359,13 @@ function declaresTopLevelName(mc, name) {
 }
 /** Does this file contribute declarations to Kotlin import ambiguity? */
 function contributesKotlinConstants(mc) {
+    return (mc.literals.size > 0 ||
+        mc.exprs.size > 0 ||
+        unfoldableDeclarationsOf(mc).size > 0 ||
+        topLevelDeclarationsOf(mc).size > 0);
+}
+/** Foldable or explicitly unfoldable constants that must live in index projections. */
+function hasIndexedConstants(mc) {
     return mc.literals.size > 0 || mc.exprs.size > 0 || unfoldableDeclarationsOf(mc).size > 0;
 }
 /** Top-level names declared by one file (`Outer.X` contributes `Outer`). */
@@ -380,6 +381,8 @@ function topLevelDeclarationNames(mc) {
         const dot = key.indexOf('.');
         names.add(dot < 0 ? key : key.slice(0, dot));
     }
+    for (const name of topLevelDeclarationsOf(mc))
+        names.add(name);
     return names;
 }
 /** Every declaration key recorded for a file, foldable or not. */
@@ -428,17 +431,71 @@ export function buildKotlinConstantIndex(repo) {
     }
     return { repo, constantKeys, byPackage: mutablePackages, byFqn };
 }
+/** Read-only one-entry overlay without copying the repo-wide constant map. */
+class KotlinConstantOverlay {
+    base;
+    overlayKey;
+    overlayValue;
+    [Symbol.toStringTag] = 'KotlinConstantOverlay';
+    constructor(base, overlayKey, overlayValue) {
+        this.base = base;
+        this.overlayKey = overlayKey;
+        this.overlayValue = overlayValue;
+    }
+    get size() {
+        return this.base.size + (this.base.has(this.overlayKey) ? 0 : 1);
+    }
+    get(key) {
+        return key === this.overlayKey ? this.overlayValue : this.base.get(key);
+    }
+    has(key) {
+        return key === this.overlayKey || this.base.has(key);
+    }
+    *entries() {
+        let replaced = false;
+        for (const [key, value] of this.base) {
+            if (key === this.overlayKey) {
+                replaced = true;
+                yield [key, this.overlayValue];
+            }
+            else {
+                yield [key, value];
+            }
+        }
+        if (!replaced)
+            yield [this.overlayKey, this.overlayValue];
+    }
+    *keys() {
+        for (const [key] of this.entries())
+            yield key;
+    }
+    *values() {
+        for (const [, value] of this.entries())
+            yield value;
+    }
+    [Symbol.iterator]() {
+        return this.entries();
+    }
+    forEach(callbackfn, thisArg) {
+        for (const [key, value] of this.entries())
+            callbackfn.call(thisArg, value, key, this);
+    }
+}
 /**
  * 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 function overlayKotlinConstantIndex(index, fileKey, mc) {
+    // Same-file shadows are read from `mc` itself. Rebuild only when this key's
+    // constant projections would change; a controller with a class name but no
+    // foldable constants stays on the overlay so scan stays linear.
+    const existing = index.repo.get(fileKey);
+    if (!hasIndexedConstants(mc) && (!existing || !hasIndexedConstants(existing))) {
+        return { ...index, repo: new KotlinConstantOverlay(index.repo, fileKey, mc) };
+    }
     const repo = new Map(index.repo);
-    const replacing = repo.has(fileKey);
     repo.set(fileKey, mc);
-    if (!replacing && !contributesKotlinConstants(mc))
-        return { ...index, repo };
     return buildKotlinConstantIndex(repo);
 }
 /**
@@ -728,9 +785,9 @@ function declaredPackage(root) {
         .join('.');
 }
 /**
- * Extract the declared package, file-level string constants and import bindings
- * of one parsed Kotlin file into the {@link KotlinModuleConstants} shape the
- * resolver consumes.
+ * Extract the declared package, file-level string constants, named imports and
+ * package-star import scopes 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.
@@ -777,20 +834,26 @@ export function extractKotlinModuleConstants(tree) {
     const literals = new Map();
     const exprs = new Map();
     const imports = new Map();
+    const wildcardImports = [];
     const unfoldableDeclarations = new Set();
+    const topLevelDeclarations = new Set();
     // Pass 1: imports.
     const walkImports = (node) => {
         if (node.type === 'import_header') {
-            // `import a.b.*` binds no single name — nothing to key the fold on, and
-            // guessing which package member a bare reference came from is exactly the
-            // wrong answer. Skipped, so such a reference floors to skip.
             const isWildcard = node.children.some((c) => c.type === 'wildcard_import');
             const identifier = node.children.find((c) => c.type === 'identifier');
-            if (!isWildcard && identifier) {
+            if (identifier) {
                 const segments = identifier.namedChildren
                     .filter((c) => c.type === 'simple_identifier')
                     .map((c) => unquoteKotlinIdentifier(c.text));
-                if (segments.length >= 2) {
+                if (isWildcard) {
+                    // Package star (`pkg.*`) or classifier star (`Type.*`). Resolution
+                    // decides which reading the specifier actually names.
+                    const scope = segments.join('.');
+                    if (scope.length > 0 && !wildcardImports.includes(scope))
+                        wildcardImports.push(scope);
+                }
+                else if (segments.length >= 2) {
                     const spec = segments.join('.');
                     const originalName = segments[segments.length - 1];
                     const aliasNode = node.children
@@ -859,6 +922,25 @@ export function extractKotlinModuleConstants(tree) {
     };
     /** Prepend a qualified scope unless it is already the innermost scope. */
     const withScope = (scope, scopes) => scope === null || scopes[0] === scope ? scopes : [scope, ...scopes];
+    // Package-star imports have lower priority than declarations in this file,
+    // including declarations the string-constant extractor intentionally does
+    // not harvest (a `var`, plain class, or unfoldable property). Record their
+    // names separately so a star import cannot turn one of those shadows into a
+    // false route constant.
+    for (const child of tree.rootNode.children ?? []) {
+        if (child.type === 'property_declaration') {
+            const declaration = child.children.find((c) => c.type === 'variable_declaration');
+            const name = declaration?.namedChildren.find((c) => c.type === 'simple_identifier');
+            if (name)
+                topLevelDeclarations.add(unquoteKotlinIdentifier(name.text));
+            continue;
+        }
+        if (child.type === 'object_declaration' || child.type === 'class_declaration') {
+            const name = child.children.find((c) => c.type === 'type_identifier');
+            if (name)
+                topLevelDeclarations.add(unquoteKotlinIdentifier(name.text));
+        }
+    }
     const walkDeclarations = (node, enclosingType, scopes) => {
         for (const child of node.children ?? []) {
             if (child.type === 'object_declaration') {
@@ -958,8 +1040,10 @@ export function extractKotlinModuleConstants(tree) {
         literals,
         exprs,
         imports,
+        wildcardImports,
         packageName: declaredPackage(tree.rootNode),
         unfoldableDeclarations,
+        topLevelDeclarations,
     };
 }
 function newFoldState(repo, index) {
@@ -1032,8 +1116,81 @@ function resolveImportedName(fileKey, imp, state, depth) {
         return null;
     return resolveWithState(owner.fileKey, `${owner.localName}.${imp.originalName}`, state, depth);
 }
+/**
+ * Resolve one name contributed by Kotlin star imports.
+ *
+ * Star imports have lower priority than local declarations and explicit
+ * imports; callers enforce that ordering before reaching this helper. A name
+ * must identify one declaration across every imported scope. Two stars
+ * exporting the same name, a duplicated FQN, or a package and a classifier
+ * that disagree on the target, floor to null rather than guessing.
+ *
+ * A specifier is tried as a package (`import pkg.*`) and as a classifier
+ * (`import Type.*` — object, class, or companion members). Kotlin allows both.
+ */
+function resolveKotlinWildcardImportTarget(mc, name, index) {
+    const scopes = mc.wildcardImports;
+    if (!scopes || scopes.length === 0)
+        return null;
+    let resolved = null;
+    for (const rawScope of scopes) {
+        const scope = unquoteKotlinDottedName(rawScope);
+        const candidates = [];
+        const bucket = index.byPackage.get(scope);
+        if (bucket?.declarers.has(name)) {
+            const fileKey = bucket.declarers.get(name);
+            if (fileKey === null || fileKey === undefined)
+                return null;
+            candidates.push({ fileKey, localName: name });
+        }
+        const owner = index.byFqn.get(scope);
+        if (owner === null)
+            return null;
+        if (owner !== undefined) {
+            const localName = `${owner.localName}.${name}`;
+            const target = index.repo.get(owner.fileKey);
+            if (target &&
+                (target.literals.has(localName) ||
+                    target.exprs.has(localName) ||
+                    unfoldableDeclarationsOf(target).has(localName))) {
+                candidates.push({ fileKey: owner.fileKey, localName });
+            }
+        }
+        for (const candidate of candidates) {
+            if (resolved !== null &&
+                (resolved.fileKey !== candidate.fileKey || resolved.localName !== candidate.localName)) {
+                return null;
+            }
+            resolved = candidate;
+        }
+    }
+    return resolved;
+}
+/**
+ * Resolve a top-level name visible from the importing file's own package.
+ * `undefined` means the package does not declare the name; `null` means it is
+ * ambiguous and must floor rather than fall through to a star import.
+ */
+function resolveKotlinSamePackageTarget(fileKey, name, index) {
+    const packageName = declaredPackageOf(index.repo.get(fileKey));
+    if (packageName === null)
+        return undefined;
+    const bucket = index.byPackage.get(packageName);
+    if (!bucket?.declarers.has(name))
+        return undefined;
+    const declaringFile = bucket.declarers.get(name);
+    if (declaringFile === null || declaringFile === undefined)
+        return null;
+    // Same-file literals, expressions, and shadows are handled before this step.
+    if (declaringFile === fileKey)
+        return undefined;
+    return { fileKey: declaringFile, localName: name };
+}
 function computeKotlinFold(fileKey, name, state, depth) {
     const { repo } = state.index;
+    const mc = repo.get(fileKey);
+    if (!mc)
+        return null;
     // Qualified reference (`ApiPaths.ORDERS`): constants and imports are keyed by
     // their IN-FILE name, so a dotted name never hits directly. Split head.tail,
     // resolve the head through the importing file's type import, then look the
@@ -1056,6 +1213,19 @@ function computeKotlinFold(fileKey, name, state, depth) {
             // uses the declaring type's real name.
             return resolveWithState(target.fileKey, `${target.localName}.${tail}`, state, depth + 1);
         }
+        // A same-file top-level declaration outranks every star import.
+        if (!topLevelDeclarationsOf(mc).has(head)) {
+            const samePackageTarget = resolveKotlinSamePackageTarget(fileKey, head, state.index);
+            if (samePackageTarget === null)
+                return null;
+            if (samePackageTarget !== undefined) {
+                return resolveWithState(samePackageTarget.fileKey, `${samePackageTarget.localName}.${tail}`, state, depth + 1);
+            }
+            const wildcardTarget = resolveKotlinWildcardImportTarget(mc, head, state.index);
+            if (wildcardTarget !== null) {
+                return resolveWithState(wildcardTarget.fileKey, `${wildcardTarget.localName}.${tail}`, state, depth + 1);
+            }
+        }
         // Un-imported qualified name (FQN form `com.example.app.api.ApiPaths.ORDERS`):
         // try the longest dotted prefix that resolves to a file.
         const parts = name.split('.');
@@ -1077,9 +1247,6 @@ function computeKotlinFold(fileKey, name, state, depth) {
     // an operand may itself be a QUALIFIED reference (`X = ApiPaths.Y + "/tail"`)
     // and the core only knows bare names: it would look `ApiPaths.Y` up in maps
     // keyed by simple name, miss, and floor the whole chain to null.
-    const mc = repo.get(fileKey);
-    if (!mc)
-        return null;
     const literal = mc.literals.get(name);
     if (literal !== undefined)
         return literal;
@@ -1089,6 +1256,20 @@ function computeKotlinFold(fileKey, name, state, depth) {
     const imp = mc.imports.get(name);
     if (imp !== undefined)
         return resolveImportedName(fileKey, imp, state, depth + 1);
+    // Any local declaration still shadows a lower-priority package-star import,
+    // including a var/plain type that is absent from the constant maps.
+    if (topLevelDeclarationsOf(mc).has(name) || unfoldableDeclarationsOf(mc).has(name))
+        return null;
+    const samePackageTarget = resolveKotlinSamePackageTarget(fileKey, name, state.index);
+    if (samePackageTarget === null)
+        return null;
+    if (samePackageTarget !== undefined) {
+        return resolveWithState(samePackageTarget.fileKey, samePackageTarget.localName, state, depth + 1);
+    }
+    const wildcardTarget = resolveKotlinWildcardImportTarget(mc, name, state.index);
+    if (wildcardTarget !== null) {
+        return resolveWithState(wildcardTarget.fileKey, wildcardTarget.localName, state, depth + 1);
+    }
     return null;
 }
 /**

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

@@ -0,0 +1,13 @@
+/**
+ * Kotlin Spring MVC route annotations for the ingestion pipeline (#3130).
+ *
+ * This module only walks a caller-provided tree. In particular, it does not
+ * import or load tree-sitter-kotlin at module initialization, so platforms
+ * without the optional grammar can still load the language-provider registry.
+ */
+import type Parser from 'tree-sitter';
+import type { ExtractedDecoratorRoute } from '../workers/parse-worker.js';
+/**
+ * Extract direct Spring handler methods from concrete Kotlin RestControllers.
+ */
+export declare function extractKotlinSpringRoutes(tree: Parser.Tree, filePath: string, lineOffset?: number): ExtractedDecoratorRoute[];

package/dist/core/ingestion/route-extractors/kotlin-spring.js

@@ -0,0 +1,259 @@
+import { intersectSpringHttpMethods, isClassLevelMappingAnnotation, springAnnotationHttpMethods, unquoteSpringLiteral, } from './spring-shared.js';
+import { extractKotlinModuleConstants, parseKotlinConstOperands, unfoldableDeclarationsOf, unquoteKotlinIdentifier, } from './kotlin-const-resolver.js';
+/** Direct declaration annotations in source order. */
+function declarationAnnotations(node) {
+    const modifiers = node.namedChildren.find((child) => child.type === 'modifiers');
+    return modifiers?.namedChildren.filter((child) => child.type === 'annotation') ?? [];
+}
+/** `@Foo`, `@Foo(...)`, or `@a.b.Foo(...)` → `Foo`. */
+function annotationName(annotation) {
+    const constructor = annotation.namedChildren.find((child) => child.type === 'constructor_invocation');
+    const userType = annotation.namedChildren.find((child) => child.type === 'user_type') ??
+        constructor?.namedChildren.find((child) => child.type === 'user_type');
+    const identifiers = userType?.namedChildren.filter((child) => child.type === 'type_identifier') ?? [];
+    const identifier = identifiers.at(-1);
+    return identifier ? unquoteKotlinIdentifier(identifier.text) : null;
+}
+function annotationArguments(annotation) {
+    const constructor = annotation.namedChildren.find((child) => child.type === 'constructor_invocation');
+    const values = constructor?.namedChildren.find((child) => child.type === 'value_arguments');
+    return values?.namedChildren.filter((child) => child.type === 'value_argument') ?? [];
+}
+/**
+ * Kotlin represents positional and named annotation arguments with the same
+ * `value_argument` node. A direct `=` token distinguishes the named form.
+ */
+function readAnnotationArgument(argument) {
+    const named = argument.children.some((child) => child.type === '=');
+    if (!named) {
+        const expression = argument.namedChild(0);
+        return expression ? { expression } : null;
+    }
+    const key = argument.namedChild(0);
+    const expression = argument.namedChild(1);
+    if (key?.type !== 'simple_identifier' || !expression)
+        return null;
+    return { name: unquoteKotlinIdentifier(key.text), expression };
+}
+function routeArguments(annotation) {
+    const out = [];
+    for (const argument of annotationArguments(annotation)) {
+        const parsed = readAnnotationArgument(argument);
+        if (!parsed)
+            return null;
+        if (parsed.name === undefined || parsed.name === 'path' || parsed.name === 'value') {
+            out.push(parsed);
+        }
+    }
+    return out;
+}
+/** A fully static Kotlin string literal: no `$name` or `${expr}` children. */
+function isPlainStringLiteral(node) {
+    return (node.type === 'string_literal' &&
+        node.namedChildren.every((child) => child.type === 'string_content'));
+}
+/**
+ * Empty `[]` / `arrayOf()` is Spring "no path", not an unresolvable prefix.
+ * tree-sitter-kotlin may put a zero-width recovery child inside `[]`.
+ */
+function isEmptyKotlinPathCollection(node) {
+    if (node.type === 'collection_literal') {
+        return node.namedChildren.every((child) => child.text.length === 0);
+    }
+    if (node.type !== 'call_expression')
+        return false;
+    const callee = node.namedChild(0);
+    if (callee?.type !== 'simple_identifier' || unquoteKotlinIdentifier(callee.text) !== 'arrayOf') {
+        return false;
+    }
+    const suffix = node.namedChildren.find((child) => child.type === 'call_suffix');
+    const args = suffix?.namedChildren.find((child) => child.type === 'value_arguments');
+    if (!args)
+        return true;
+    return args.namedChildren.every((child) => child.type !== 'value_argument');
+}
+function isKotlinInterface(node) {
+    return node.children.some((child) => child.type === 'interface');
+}
+function isAbstractOrSealedClass(node) {
+    const modifiers = node.namedChildren.find((child) => child.type === 'modifiers');
+    return (modifiers?.namedChildren.some((child) => {
+        if (child.type !== 'inheritance_modifier' && child.type !== 'class_modifier') {
+            return false;
+        }
+        const text = child.text.trim();
+        return text === 'abstract' || text === 'sealed';
+    }) === true);
+}
+function directFunctions(node) {
+    const body = node.namedChildren.find((child) => child.type === 'class_body');
+    return body?.namedChildren.filter((child) => child.type === 'function_declaration') ?? [];
+}
+function functionName(node) {
+    const field = node.childForFieldName('name');
+    const identifier = field?.type === 'simple_identifier'
+        ? field
+        : node.namedChildren.find((child) => child.type === 'simple_identifier');
+    return identifier ? unquoteKotlinIdentifier(identifier.text) : null;
+}
+function typeName(node) {
+    const identifier = node.children.find((child) => child.type === 'type_identifier');
+    return identifier ? unquoteKotlinIdentifier(identifier.text) : null;
+}
+/**
+ * Qualified enclosing type paths, innermost first. Kotlin companion members
+ * are keyed through their enclosing class, so companion_object itself adds no
+ * segment.
+ */
+function enclosingTypeNames(node) {
+    const simpleNames = [];
+    for (let current = node.parent; current; current = current.parent) {
+        if (current.type !== 'class_declaration' && current.type !== 'object_declaration')
+            continue;
+        const name = typeName(current);
+        if (name)
+            simpleNames.push(name);
+    }
+    return simpleNames.map((_, index) => simpleNames.slice(index).reverse().join('.'));
+}
+function declarationExists(constants, name) {
+    return (constants.literals.has(name) ||
+        constants.exprs.has(name) ||
+        unfoldableDeclarationsOf(constants).has(name));
+}
+/**
+ * The provider fold hook has a language-neutral three-argument signature and
+ * cannot receive a Kotlin reference site's enclosing type chain. Qualify only
+ * names whose owner is proven by this same tree; unresolved/imported names are
+ * left untouched for the repo-wide resolver.
+ */
+function qualifySameFileOperands(operands, functionNode, constants) {
+    const enclosingTypes = enclosingTypeNames(functionNode);
+    return operands.map((operand) => {
+        if (operand.kind === 'literal')
+            return operand;
+        for (const owner of enclosingTypes) {
+            const qualified = `${owner}.${operand.name}`;
+            if (declarationExists(constants, qualified)) {
+                return { kind: 'ref', name: qualified };
+            }
+        }
+        return operand;
+    });
+}
+/**
+ * Read the one optional class-level RequestMapping. A present route member must
+ * be exactly one plain string literal, an empty `[]`/`arrayOf()` (no prefix),
+ * or absent; constants, interpolation, non-empty collections, duplicate
+ * mappings, and dynamic expressions fail closed for the whole class.
+ */
+function classMapping(annotations) {
+    const mappings = annotations.filter((annotation) => isClassLevelMappingAnnotation(annotationName(annotation) ?? ''));
+    if (mappings.length === 0)
+        return { prefix: '', methods: ['*'] };
+    if (mappings.length !== 1)
+        return null;
+    const mapping = mappings[0];
+    const paths = routeArguments(mapping);
+    if (paths === null || paths.length > 1)
+        return null;
+    let prefix = '';
+    if (paths.length === 1) {
+        const path = paths[0].expression;
+        if (isEmptyKotlinPathCollection(path)) {
+            prefix = '';
+        }
+        else if (isPlainStringLiteral(path)) {
+            const literal = unquoteSpringLiteral(path.text);
+            if (literal === null)
+                return null;
+            prefix = literal;
+        }
+        else {
+            return null;
+        }
+    }
+    const mappingName = annotationName(mapping);
+    if (!mappingName)
+        return null;
+    const methods = springAnnotationHttpMethods(mappingName, mapping.text);
+    return methods.length === 0 ? null : { prefix, methods };
+}
+/**
+ * Extract direct Spring handler methods from concrete Kotlin RestControllers.
+ */
+export function extractKotlinSpringRoutes(tree, filePath, lineOffset = 0) {
+    const routes = [];
+    let moduleConstants;
+    for (const classNode of tree.rootNode.descendantsOfType('class_declaration')) {
+        if (isKotlinInterface(classNode) || isAbstractOrSealedClass(classNode))
+            continue;
+        const annotations = declarationAnnotations(classNode);
+        const annotationNames = annotations.map(annotationName);
+        if (!annotationNames.includes('RestController'))
+            continue;
+        if (annotationNames.includes('FeignClient'))
+            continue;
+        const ownerMapping = classMapping(annotations);
+        if (ownerMapping === null)
+            continue;
+        for (const functionNode of directFunctions(classNode)) {
+            const handlerName = functionName(functionNode);
+            if (!handlerName)
+                continue;
+            for (const annotation of declarationAnnotations(functionNode)) {
+                const decoratorName = annotationName(annotation);
+                if (!decoratorName)
+                    continue;
+                const methodMethods = springAnnotationHttpMethods(decoratorName, annotation.text);
+                const methods = intersectSpringHttpMethods(ownerMapping.methods, methodMethods);
+                if (methods.length === 0)
+                    continue;
+                const paths = routeArguments(annotation);
+                if (paths === null || paths.length > 1)
+                    continue;
+                let routePath = '';
+                let routePathExpr;
+                let routePathOperands;
+                if (paths.length === 1) {
+                    const expression = paths[0].expression;
+                    if (isEmptyKotlinPathCollection(expression)) {
+                        routePath = '';
+                    }
+                    else if (isPlainStringLiteral(expression)) {
+                        const literal = unquoteSpringLiteral(expression.text);
+                        if (literal === null)
+                            continue;
+                        routePath = literal;
+                    }
+                    else {
+                        const operands = parseKotlinConstOperands(expression);
+                        if (operands === null)
+                            continue;
+                        moduleConstants ??= extractKotlinModuleConstants(tree);
+                        routePathExpr = expression.text;
+                        routePathOperands = qualifySameFileOperands(operands, functionNode, moduleConstants);
+                    }
+                }
+                for (const httpMethod of methods) {
+                    routes.push({
+                        filePath,
+                        routePath,
+                        httpMethod,
+                        decoratorName,
+                        lineNumber: annotation.startPosition.row + lineOffset,
+                        ...(ownerMapping.prefix ? { prefix: ownerMapping.prefix } : {}),
+                        handlerName,
+                        ...(routePathExpr === undefined
+                            ? {}
+                            : {
+                                routePathExpr,
+                                routePathOperands,
+                            }),
+                    });
+                }
+            }
+        }
+    }
+    return routes;
+}

package/dist/core/ingestion/route-extractors/python-decorator-handler.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Return the function name attached to a Python decorator's immediate
+ * `decorated_definition`; reject every other shape rather than climbing.
+ */
+import type { SyntaxNode } from '../utils/ast-helpers.js';
+export declare function pythonDecoratorRouteHandlerName(decoratorNode: SyntaxNode): string | undefined;

package/dist/core/ingestion/route-extractors/python-decorator-handler.js

@@ -0,0 +1,16 @@
+/**
+ * Return the function name attached to a Python decorator's immediate
+ * `decorated_definition`; reject every other shape rather than climbing.
+ */
+export function pythonDecoratorRouteHandlerName(decoratorNode) {
+    const decorated = decoratorNode.parent;
+    if (decorated === null || decorated.type !== 'decorated_definition')
+        return undefined;
+    // `async def` is still a `function_definition` in tree-sitter-python (the
+    // `async` keyword is an anonymous child), so async handlers need no branch.
+    const definition = decorated.childForFieldName('definition');
+    if (!definition || definition.type !== 'function_definition')
+        return undefined;
+    const name = definition.childForFieldName('name')?.text;
+    return name !== undefined && name.length > 0 ? name : undefined;
+}