gitnexus 1.6.7 → 1.6.8-rc.10

package/dist/core/group/extractors/include-extractor.js

@@ -1,19 +1,19 @@
 import * as path from 'node:path';
 import * as fs from 'node:fs/promises';
-import { createRequire } from 'node:module';
 import { glob } from 'glob';
 import Parser from 'tree-sitter';
 import Cpp from 'tree-sitter-cpp';
-// `tree-sitter-c` is vendored prebuild-only (#2116) and may be absent on a
-// toolchain-less / `--ignore-scripts` install. Load it via a guarded `_require`
-// rather than a top-level `import C from 'tree-sitter-c'`, which would throw
-// ERR_MODULE_NOT_FOUND at module-load and crash analyze (#2091/#2093). When the
+import { requireVendoredGrammar } from '../../tree-sitter/vendored-grammars.js';
+// `tree-sitter-c` is vendored (#2116), loaded from `vendor/` by absolute path
+// (NEVER copied into node_modules — see vendored-grammars.ts / #2111). Load it
+// via a guarded call rather than a top-level `import C from 'tree-sitter-c'`,
+// which would throw ERR_MODULE_NOT_FOUND at module-load and crash analyze
+// (#2091/#2093). It may be absent on a platform without a prebuild; when the
 // binding is absent, `getLanguageForFile` returns null for `.c`/`.h` so C
 // include-extraction is skipped (C++ is unaffected — its binding always ships).
-const _require = createRequire(import.meta.url);
 let C = null;
 try {
-    C = _require('tree-sitter-c');
+    C = requireVendoredGrammar('tree-sitter-c');
 }
 catch {
     /* C grammar unavailable — C include extraction degrades to a no-op. */

package/dist/core/ingestion/language-provider.d.ts

@@ -20,6 +20,8 @@ import type { VariableExtractor } from './variable-types.js';
 import type { ImportResolverFn } from './import-resolvers/types.js';
 import type { SyntaxNode } from './utils/ast-helpers.js';
 import type { NodeLabel } from '../../_shared/index.js';
+import type Parser from 'tree-sitter';
+import type { ExtractedDecoratorRoute } from './workers/parse-worker.js';
 /** Tree-sitter query captures: capture name → AST node (or undefined if not captured). */
 export type CaptureMap = Record<string, SyntaxNode | undefined>;
 /** Configuration for AST-based framework detection patterns. */
@@ -145,6 +147,12 @@ interface LanguageProviderConfig {
      * `undefined` when no constraints exist / the node isn't a templated
      * function. Languages without SFINAE / concept semantics leave this
      * undefined and the disambiguation is a pass-through.
+     *
+     * Cloneability contract: the returned payload crosses the worker boundary
+     * via structured clone, so it MUST be structured-clone-safe (no functions,
+     * symbols, or tree-sitter `SyntaxNode`s — only plain data). Wrap the return
+     * with `assertCloneable` from `workers/clone-safety.ts` so a future leak is a
+     * compile error at the source instead of a runtime DataCloneError (#2143).
      */
     readonly extractTemplateConstraints?: (definitionNode: SyntaxNode) => unknown;
     /** Override the default node label for definition.function captures.
@@ -185,6 +193,17 @@ interface LanguageProviderConfig {
      *  When true, the worker extracts routes via the language's route extraction logic.
      *  Default: undefined (no route files). */
     readonly isRouteFile?: (filePath: string) => boolean;
+    /**
+     * Extract decorator-style route annotations from a parsed file.
+     *
+     * When defined, the parse worker calls this after per-file capture processing
+     * to extract framework route definitions that require AST-level analysis beyond
+     * generic `@decorator` captures (e.g., Java Spring class-level prefix joining,
+     * multi-class handling). The returned routes are appended to `decoratorRoutes`.
+     *
+     * Default: undefined (no language-specific decorator route extraction).
+     */
+    readonly extractDecoratorRoutes?: (tree: Parser.Tree, filePath: string, lineOffset: number) => ExtractedDecoratorRoute[];
     /** Built-in/stdlib names that should be filtered from the call graph for this language.
      *  Default: undefined (no language-specific filtering). */
     readonly builtInNames?: ReadonlySet<string>;
@@ -255,8 +274,12 @@ interface LanguageProviderConfig {
      * disk store WITHOUT a main-thread re-parse. The main thread restores them
      * via the matching `ScopeResolver.applyCaptureSideChannel` hook.
      *
-     * MUST return plain data (objects / arrays / primitives) so it round-trips
-     * through `JSON.stringify` + the parsedfile-store interning reviver.
+     * Cloneability contract: MUST return plain data (objects / arrays /
+     * primitives — no functions, symbols, or tree-sitter `SyntaxNode`s) so it
+     * survives BOTH the worker→main structured clone AND `JSON.stringify` + the
+     * parsedfile-store interning reviver. Wrap the return with `assertCloneable`
+     * from `workers/clone-safety.ts` so a future non-serializable leak is a
+     * compile error at the source instead of a runtime DataCloneError (#2143).
      *
      * Default: undefined (provider has no capture-time module-level side effects).
      */

package/dist/core/ingestion/languages/c-cpp.js

@@ -38,7 +38,8 @@ import { cCallConfig, cppCallConfig } from '../call-extractors/configs/c-cpp.js'
 import { stripUeMacros } from '../cpp-ue-preprocessor.js';
 import { emitCScopeCaptures, interpretCImport, interpretCTypeBinding, cArityCompatibility, cBindingScopeFor, cImportOwningScope, cReceiverBinding, collectCStaticLinkageSideChannel, } from './c/index.js';
 import { emitCppScopeCaptures, interpretCppImport, interpretCppTypeBinding, cppArityCompatibility, cppBindingScopeFor, cppImportOwningScope, cppReceiverBinding, collectCppCaptureSideChannel, } from './cpp/index.js';
-import { extractCppTemplateConstraints } from './cpp/constraint-extractor.js';
+import { extractCppTemplateConstraints, } from './cpp/constraint-extractor.js';
+import { assertCloneable } from '../workers/clone-safety.js';
 const C_BUILT_INS = new Set([
     'printf',
     'fprintf',
@@ -358,7 +359,10 @@ export const cProvider = defineLanguage({
     // `static` functions look non-file-local on the main thread and leak into
     // cross-file global free-call resolution / wildcard imports. See
     // `c/capture-side-channel.ts`.
-    collectCaptureSideChannel: collectCStaticLinkageSideChannel,
+    // `assertCloneable` is a runtime identity; it makes a future non-serializable
+    // value in the side-channel payload a compile error here, at the source, rather
+    // than a DataCloneError at the worker boundary (#2143).
+    collectCaptureSideChannel: (filePath) => assertCloneable(collectCStaticLinkageSideChannel(filePath)),
     interpretImport: interpretCImport,
     interpretTypeBinding: interpretCTypeBinding,
     bindingScopeFor: cBindingScopeFor,
@@ -431,7 +435,7 @@ export const cppProvider = defineLanguage({
     // just populated for this file into plain data on `ParsedFile.captureSideChannel`,
     // so the main thread can restore them via `applyCaptureSideChannel` WITHOUT a
     // re-parse (#1983). See `cpp/capture-side-channel.ts`.
-    collectCaptureSideChannel: collectCppCaptureSideChannel,
+    collectCaptureSideChannel: (filePath) => assertCloneable(collectCppCaptureSideChannel(filePath)),
     interpretImport: interpretCppImport,
     interpretTypeBinding: interpretCppTypeBinding,
     bindingScopeFor: cppBindingScopeFor,
@@ -482,5 +486,8 @@ function extractCppTemplateConstraintsForProvider(definitionNode) {
         }
         break;
     }
-    return extractCppTemplateConstraints(templateDecl, declarator);
+    // Guard the boundary at the source: a future non-cloneable member of the
+    // constraint payload becomes a compile error here, not a runtime
+    // DataCloneError at the worker post (#2143).
+    return assertCloneable(extractCppTemplateConstraints(templateDecl, declarator));
 }

package/dist/core/ingestion/languages/java.js

@@ -11,6 +11,7 @@ import { createClassExtractor } from '../class-extractors/generic.js';
 import { javaClassConfig } from '../class-extractors/configs/jvm.js';
 import { defineLanguage } from '../language-provider.js';
 import { javaTypeConfig } from '../type-extractors/jvm.js';
+import { extractSpringRoutes } from '../route-extractors/spring.js';
 import { javaExportChecker } from '../export-detection.js';
 import { createImportResolver } from '../import-resolvers/resolver-factory.js';
 import { javaImportConfig } from '../import-resolvers/configs/jvm.js';
@@ -103,4 +104,6 @@ export const javaProvider = defineLanguage({
     arityCompatibility: javaArityCompatibility,
     resolveImportTarget: resolveJavaImportTarget,
     orderSameNameTypeCandidates: orderJavaSameNameTypeCandidates,
+    // ── Route extraction ──
+    extractDecoratorRoutes: extractSpringRoutes,
 });

package/dist/core/ingestion/languages/kotlin/query.js

@@ -1,7 +1,8 @@
 import Parser from 'tree-sitter';
 import { SupportedLanguages } from '../../../../_shared/index.js';
-// `tree-sitter-kotlin` is an optionalDependency that may be absent on a default
-// install (or fail its native build). Loaded lazily + guarded via parser-loader
+// `tree-sitter-kotlin` is a vendored grammar (loaded from vendor/ by absolute
+// path, never node_modules — vendored-grammars.ts / #2111) that may be absent on
+// a platform without a matching prebuild. Loaded lazily + guarded via parser-loader
 // rather than statically imported: this module is pulled onto the main thread
 // eagerly by the scope-resolution registry and the language-provider index, so
 // a top-level `import Kotlin from 'tree-sitter-kotlin'` would throw

package/dist/core/ingestion/languages/kotlin.js

@@ -10,6 +10,7 @@ import { SupportedLanguages } from '../../../_shared/index.js';
 import { createClassExtractor } from '../class-extractors/generic.js';
 import { kotlinClassConfig } from '../class-extractors/configs/jvm.js';
 import { defineLanguage } from '../language-provider.js';
+import { assertCloneable } from '../workers/clone-safety.js';
 import { kotlinTypeConfig } from '../type-extractors/jvm.js';
 import { kotlinExportChecker } from '../export-detection.js';
 import { createImportResolver } from '../import-resolvers/resolver-factory.js';
@@ -166,7 +167,10 @@ export const kotlinProvider = defineLanguage({
     // so the main thread can restore them via `applyCaptureSideChannel` WITHOUT a
     // re-parse (#1983). Without this, companion/static dispatch emits no CALLS
     // edges on the worker path. See `kotlin/capture-side-channel.ts`.
-    collectCaptureSideChannel: collectKotlinCaptureSideChannel,
+    // `assertCloneable` is a runtime identity; it makes a future non-serializable
+    // value in the side-channel payload a compile error here, at the source, rather
+    // than a DataCloneError at the worker boundary (#2143).
+    collectCaptureSideChannel: (filePath) => assertCloneable(collectKotlinCaptureSideChannel(filePath)),
     interpretImport: interpretKotlinImport,
     interpretTypeBinding: interpretKotlinTypeBinding,
     bindingScopeFor: kotlinBindingScopeFor,

package/dist/core/ingestion/parsing-processor.js

@@ -144,6 +144,27 @@ chunkHash) => {
             .join(', ');
         logger.warn(`  Skipped unsupported languages: ${summary}`);
     }
+    // Clone-safety telemetry (#2112): files whose parse output carried a value
+    // the structured-clone algorithm couldn't serialize across the worker
+    // boundary. The worker sanitized/dropped the offending value so the run
+    // could complete; surface the (rare) data loss so it's visible and the
+    // offending extractor can be fixed at source.
+    const skippedPaths = [];
+    for (const result of chunkResults) {
+        for (const entry of result.skippedPaths ?? [])
+            skippedPaths.push(entry);
+    }
+    if (skippedPaths.length > 0) {
+        // Keep the per-file reason ("stripped N value(s) from nodes" /
+        // "dropped non-serializable parsedFiles entry") — it distinguishes a
+        // recoverable strip from a whole-record drop, which a path-only line loses.
+        const shown = skippedPaths
+            .slice(0, 10)
+            .map((e) => `${e.path} (${e.reason})`)
+            .join(', ');
+        const more = skippedPaths.length > 10 ? ` …and ${skippedPaths.length - 10} more` : '';
+        logger.warn(`  Sanitized ${skippedPaths.length} file(s) with non-serializable parse output: ${shown}${more}`);
+    }
     onFileProgress?.(total, total, 'done');
     return chunkResults;
 };

package/dist/core/ingestion/pipeline-phases/routes.js

@@ -297,22 +297,72 @@ export const routesPhase = {
         // scan JS/TS consumer files for calls to those wrapper functions with
         // URL-like string arguments and add them to allFetchCalls so
         // processNextjsFetchRoutes can create FETCHES edges.
-        if (allFetchWrapperDefs && allFetchWrapperDefs.length > 0 && routeRegistry.size > 0) {
-            const wrapperNames = new Set(allFetchWrapperDefs.map((d) => d.functionName));
+        // Wrapper names come from two sources: functions the parse phase
+        // auto-detected as calling the bare global `fetch()`, plus any names the
+        // user declared in `.gitnexusrc` `fetchWrappers` (#1589/#1852 residual).
+        // Config names let an axios/custom-client wrapper — or one named outside the
+        // built-in convention — still produce route_map consumers; without them it
+        // silently falls back to `consumers: []`. Configured names alone are enough
+        // to run the scan even when nothing was auto-detected.
+        // Configured names are already validated/trimmed/de-duped/capped by
+        // analyze-config.ts — trusted as-is (#1589/#1852 review F9, dropped the
+        // redundant re-trim/re-filter). The single filter below guards only the
+        // auto-detected `functionName`s, which have no shape guarantee.
+        const configuredWrappers = ctx.options?.fetchWrappers ?? [];
+        const wrapperNames = new Set([...(allFetchWrapperDefs ?? []).map((d) => d.functionName), ...configuredWrappers].filter((n) => typeof n === 'string' && n.trim().length > 0));
+        if (wrapperNames.size > 0 && routeRegistry.size > 0) {
             const jsFiles = allPaths.filter((p) => /\.[jt]sx?$/.test(p));
-            if (jsFiles.length > 0 && wrapperNames.size > 0) {
-                const jsContents = await readFileContents(ctx.repoPath, jsFiles);
-                for (const [filePath, content] of jsContents) {
-                    for (const name of wrapperNames) {
-                        const regex = new RegExp(`\\b${escapeRegex(name)}\\s*\\(\\s*['"\`](/[^'"\`\\s)]+)['"\`]`, 'g');
-                        let match;
-                        while ((match = regex.exec(content)) !== null) {
-                            allFetchCalls.push({
-                                filePath,
-                                fetchURL: match[1],
-                                lineNumber: content.substring(0, match.index).split('\n').length,
-                            });
+            if (jsFiles.length > 0) {
+                // Reuse contents already read for handler extraction; only read the
+                // remainder (mirrors the Expo block above). Avoids a second full read of
+                // files we already have in memory.
+                const unreadJsFiles = jsFiles.filter((p) => !handlerContents?.has(p));
+                const extraContents = unreadJsFiles.length > 0
+                    ? await readFileContents(ctx.repoPath, unreadJsFiles)
+                    : new Map();
+                // One alternation regex over every wrapper name per file — O(files), not
+                // O(files × wrappers) (#1852 review F3). Names are escaped and grouped
+                // non-capturing so capture group 1 stays the URL. The left boundary is a
+                // negative lookbehind, not `\b`: a bare configured name like `get` must
+                // match the free call `get('/x')` but NOT a member access `client.get(`
+                // (a `.get(` on an unrelated object), and `apiFetch` must not match
+                // `myApiFetch`. Member-style wrappers are configured with the dot
+                // (`client.get`), where the `.` is part of the pattern. The `u` flag +
+                // Unicode property classes make the boundary cover non-ASCII identifier
+                // characters too — ASCII `\w` would let `caféget('/x')` match `get`
+                // (#1852 review F10).
+                const alternation = [...wrapperNames].map(escapeRegex).join('|');
+                const wrapperCallRegex = new RegExp(`(?<![.\\p{L}\\p{N}_$])(?:${alternation})\\s*\\(\\s*['"\`](/[^'"\`\\s)]+)['"\`]`, 'gu');
+                const scanContent = (filePath, content) => {
+                    wrapperCallRegex.lastIndex = 0;
+                    // 1-based line number via a running newline counter: matches arrive in
+                    // ascending index, so accumulate newlines incrementally instead of
+                    // re-allocating `content.substring(0, match.index).split('\n')` on
+                    // every match (#1852 review F12). Output is identical.
+                    let line = 1;
+                    let scanned = 0;
+                    let match;
+                    while ((match = wrapperCallRegex.exec(content)) !== null) {
+                        for (; scanned < match.index; scanned++) {
+                            if (content.charCodeAt(scanned) === 10 /* '\n' */)
+                                line++;
                         }
+                        allFetchCalls.push({
+                            filePath,
+                            fetchURL: match[1],
+                            lineNumber: line,
+                        });
+                    }
+                };
+                for (const [filePath, content] of extraContents)
+                    scanContent(filePath, content);
+                // Also scan already-read JS/TS handler files (a handler can itself
+                // consume another route through a wrapper).
+                if (handlerContents) {
+                    for (const p of jsFiles) {
+                        const cached = handlerContents.get(p);
+                        if (cached !== undefined)
+                            scanContent(p, cached);
                     }
                 }
             }

package/dist/core/ingestion/pipeline.d.ts

@@ -104,6 +104,15 @@ export interface PipelineOptions {
      * `process.env` state across invocations. When undefined, the env var decides.
      */
     keepLocalValueSymbols?: boolean;
+    /**
+     * Extra fetch-wrapper function names to treat as HTTP consumers, threaded
+     * from `.gitnexusrc` `fetchWrappers` via `AnalyzeOptions` (#1589/#1852
+     * residual). The routes phase unions these with the auto-detected `fetch()`
+     * wrappers when scanning for `route_map` consumers, so a wrapper named outside
+     * the built-in convention (or built on axios / a custom client) is still
+     * traced. Empty/undefined leaves behavior unchanged.
+     */
+    fetchWrappers?: readonly string[];
 }
 /**
  * All pipeline phases with their dependency relationships.

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

@@ -0,0 +1,50 @@
+/**
+ * Shared Spring route-annotation primitives.
+ *
+ * These are the low-level building blocks the two Spring route extractors —
+ * the ingestion-layer `route-extractors/spring.ts` (produces graph `Route`
+ * nodes) and the group-layer `group/extractors/http-patterns/java.ts`
+ * (produces cross-repo HTTP contracts) — would otherwise each maintain
+ * independently. Centralising the annotation→method map, the enclosing-class
+ * lookup, and the route-key filter keeps those semantics in one place so the
+ * two extractors can't drift apart.
+ *
+ * This module lives in `ingestion/` (the lower layer); the group layer imports
+ * from it, matching the existing `group → ingestion` dependency direction
+ * (e.g. `group/extractors/include-extractor.ts` already imports
+ * `ingestion/import-resolvers/utils.ts`). It MUST NOT import anything from
+ * `group/` to avoid a dependency cycle.
+ */
+import type Parser from 'tree-sitter';
+/**
+ * Spring shortcut method-annotation → HTTP verb.
+ *
+ * `@RequestMapping` is intentionally absent: on a method it carries no implicit
+ * verb (the verb lives in its `method = RequestMethod.X` attribute), and on a
+ * class it is a URL prefix rather than a route. Callers handle `@RequestMapping`
+ * separately.
+ */
+export declare const METHOD_ANNOTATION_TO_HTTP: Record<string, string>;
+/**
+ * A named annotation argument contributes a route only when its member key is
+ * `path` or `value`; a positional argument (no key node) always qualifies.
+ * Drops Spring's non-route string attributes (`produces`, `consumes`,
+ * `headers`, `name`, `params`) that would otherwise be mis-read as routes.
+ */
+export declare function isRouteMemberKey(keyNode: Parser.SyntaxNode | undefined): boolean;
+/**
+ * Find the nearest enclosing `class_declaration` ancestor for a node, or null
+ * if the node is top-level. Tree-sitter's `SyntaxNode.parent` walks one level
+ * at a time.
+ */
+export declare function findEnclosingClass(node: Parser.SyntaxNode): Parser.SyntaxNode | null;
+/**
+ * Strip enclosing quotes from a tree-sitter string-literal node's text.
+ * Handles single / double / template (backtick) quotes and triple-quoted
+ * strings. Mirrors the safer semantics of the group layer's `unquoteLiteral`:
+ * returns `null` for empty / nullish input so callers can uniformly skip
+ * captures whose value is missing, and returns the text unchanged when it
+ * carries no recognisable surrounding quotes (some grammars expose string
+ * content without quotes already).
+ */
+export declare function unquoteSpringLiteral(raw: string): string | null;

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

@@ -0,0 +1,80 @@
+/**
+ * Shared Spring route-annotation primitives.
+ *
+ * These are the low-level building blocks the two Spring route extractors —
+ * the ingestion-layer `route-extractors/spring.ts` (produces graph `Route`
+ * nodes) and the group-layer `group/extractors/http-patterns/java.ts`
+ * (produces cross-repo HTTP contracts) — would otherwise each maintain
+ * independently. Centralising the annotation→method map, the enclosing-class
+ * lookup, and the route-key filter keeps those semantics in one place so the
+ * two extractors can't drift apart.
+ *
+ * This module lives in `ingestion/` (the lower layer); the group layer imports
+ * from it, matching the existing `group → ingestion` dependency direction
+ * (e.g. `group/extractors/include-extractor.ts` already imports
+ * `ingestion/import-resolvers/utils.ts`). It MUST NOT import anything from
+ * `group/` to avoid a dependency cycle.
+ */
+/**
+ * Spring shortcut method-annotation → HTTP verb.
+ *
+ * `@RequestMapping` is intentionally absent: on a method it carries no implicit
+ * verb (the verb lives in its `method = RequestMethod.X` attribute), and on a
+ * class it is a URL prefix rather than a route. Callers handle `@RequestMapping`
+ * separately.
+ */
+export const METHOD_ANNOTATION_TO_HTTP = {
+    GetMapping: 'GET',
+    PostMapping: 'POST',
+    PutMapping: 'PUT',
+    DeleteMapping: 'DELETE',
+    PatchMapping: 'PATCH',
+};
+/**
+ * A named annotation argument contributes a route only when its member key is
+ * `path` or `value`; a positional argument (no key node) always qualifies.
+ * Drops Spring's non-route string attributes (`produces`, `consumes`,
+ * `headers`, `name`, `params`) that would otherwise be mis-read as routes.
+ */
+export function isRouteMemberKey(keyNode) {
+    if (!keyNode)
+        return true;
+    return keyNode.text === 'path' || keyNode.text === 'value';
+}
+/**
+ * Find the nearest enclosing `class_declaration` ancestor for a node, or null
+ * if the node is top-level. Tree-sitter's `SyntaxNode.parent` walks one level
+ * at a time.
+ */
+export function findEnclosingClass(node) {
+    let cur = node.parent;
+    while (cur) {
+        if (cur.type === 'class_declaration')
+            return cur;
+        cur = cur.parent;
+    }
+    return null;
+}
+/**
+ * Strip enclosing quotes from a tree-sitter string-literal node's text.
+ * Handles single / double / template (backtick) quotes and triple-quoted
+ * strings. Mirrors the safer semantics of the group layer's `unquoteLiteral`:
+ * returns `null` for empty / nullish input so callers can uniformly skip
+ * captures whose value is missing, and returns the text unchanged when it
+ * carries no recognisable surrounding quotes (some grammars expose string
+ * content without quotes already).
+ */
+export function unquoteSpringLiteral(raw) {
+    if (!raw)
+        return null;
+    if ((raw.startsWith('"""') && raw.endsWith('"""')) ||
+        (raw.startsWith("'''") && raw.endsWith("'''"))) {
+        return raw.slice(3, -3);
+    }
+    const first = raw[0];
+    const last = raw[raw.length - 1];
+    if ((first === '"' || first === "'" || first === '`') && last === first && raw.length >= 2) {
+        return raw.slice(1, -1);
+    }
+    return raw;
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Spring route annotation extractor for the ingestion pipeline.
+ *
+ * Extracts `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`,
+ * `@PatchMapping`, and `@RequestMapping` annotations from Java source files
+ * and returns `ExtractedDecoratorRoute[]` with class-level `@RequestMapping`
+ * prefixes already resolved per-class.
+ *
+ * This module is the ingestion-layer counterpart of
+ * `group/extractors/http-patterns/java.ts` (which extracts HTTP contracts
+ * for cross-repo matching). It uses the same tree-sitter capture approach:
+ * a single predicate-free query matches all route annotations generically,
+ * then a for-loop discriminates class-level prefixes from method-level routes
+ * by reading `@node.type` and the annotation name.
+ *
+ * The query is predicate-free to avoid the tree-sitter 0.21.x hazard where
+ * `#match?` / `#eq?` predicates in a top-level `[...]` alternation silently
+ * drop sibling-branch matches (see group-layer `JAVA_ROUTE_ANNOTATION_PATTERNS`
+ * header comment for details).
+ */
+import Parser from 'tree-sitter';
+import type { ExtractedDecoratorRoute } from '../workers/parse-worker.js';
+/**
+ * Extract Spring route annotations from a parsed Java file.
+ *
+ * Uses a single tree-sitter query pass to capture all annotations, then
+ * discriminates class-level prefixes from method-level routes in a loop.
+ * Handles multiple classes per file, each with its own prefix.
+ *
+ * @param tree - tree-sitter parse tree
+ * @param filePath - relative file path (for `ExtractedDecoratorRoute.filePath`)
+ * @param lineOffset - line offset for pre-processing (usually 0)
+ * @returns Decorator routes with prefix already set per-class
+ */
+export declare function extractSpringRoutes(tree: Parser.Tree, filePath: string, lineOffset?: number): ExtractedDecoratorRoute[];

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

@@ -0,0 +1,136 @@
+/**
+ * Spring route annotation extractor for the ingestion pipeline.
+ *
+ * Extracts `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`,
+ * `@PatchMapping`, and `@RequestMapping` annotations from Java source files
+ * and returns `ExtractedDecoratorRoute[]` with class-level `@RequestMapping`
+ * prefixes already resolved per-class.
+ *
+ * This module is the ingestion-layer counterpart of
+ * `group/extractors/http-patterns/java.ts` (which extracts HTTP contracts
+ * for cross-repo matching). It uses the same tree-sitter capture approach:
+ * a single predicate-free query matches all route annotations generically,
+ * then a for-loop discriminates class-level prefixes from method-level routes
+ * by reading `@node.type` and the annotation name.
+ *
+ * The query is predicate-free to avoid the tree-sitter 0.21.x hazard where
+ * `#match?` / `#eq?` predicates in a top-level `[...]` alternation silently
+ * drop sibling-branch matches (see group-layer `JAVA_ROUTE_ANNOTATION_PATTERNS`
+ * header comment for details).
+ */
+import Parser from 'tree-sitter';
+import Java from 'tree-sitter-java';
+import { METHOD_ANNOTATION_TO_HTTP, isRouteMemberKey, findEnclosingClass, unquoteSpringLiteral, } from './spring-shared.js';
+/**
+ * Single predicate-free tree-sitter query that captures all route annotations
+ * on classes and methods. Discrimination by annotation name and node type
+ * happens in the loop below.
+ *
+ * Captures:
+ *   @ann   → annotation name identifier (RequestMapping, GetMapping, etc.)
+ *   @node  → enclosing declaration (class_declaration | method_declaration)
+ *   @value → the string-literal argument
+ *   @key   → the named-argument member key (absent for positional form)
+ */
+const ROUTE_ANNOTATION_QUERY = new Parser.Query(Java, `
+  [
+    (class_declaration
+      (modifiers
+        (annotation
+          name: (identifier) @ann
+          arguments: (annotation_argument_list (string_literal) @value)))) @node
+    (class_declaration
+      (modifiers
+        (annotation
+          name: (identifier) @ann
+          arguments: (annotation_argument_list
+            (element_value_pair
+              key: (identifier) @key
+              value: (string_literal) @value))))) @node
+    (method_declaration
+      (modifiers
+        (annotation
+          name: (identifier) @ann
+          arguments: (annotation_argument_list (string_literal) @value)))) @node
+    (method_declaration
+      (modifiers
+        (annotation
+          name: (identifier) @ann
+          arguments: (annotation_argument_list
+            (element_value_pair
+              key: (identifier) @key
+              value: (string_literal) @value))))) @node
+  ]
+`);
+/**
+ * Extract Spring route annotations from a parsed Java file.
+ *
+ * Uses a single tree-sitter query pass to capture all annotations, then
+ * discriminates class-level prefixes from method-level routes in a loop.
+ * Handles multiple classes per file, each with its own prefix.
+ *
+ * @param tree - tree-sitter parse tree
+ * @param filePath - relative file path (for `ExtractedDecoratorRoute.filePath`)
+ * @param lineOffset - line offset for pre-processing (usually 0)
+ * @returns Decorator routes with prefix already set per-class
+ */
+export function extractSpringRoutes(tree, filePath, lineOffset = 0) {
+    const matches = ROUTE_ANNOTATION_QUERY.matches(tree.rootNode);
+    // Phase 1: collect class-level @RequestMapping prefixes keyed by node id
+    const prefixByClassId = new Map();
+    for (const match of matches) {
+        const caps = {};
+        for (const { name, node } of match.captures) {
+            caps[name] = node;
+        }
+        const annNode = caps['ann'];
+        const node = caps['node'];
+        const valueNode = caps['value'];
+        const keyNode = caps['key'];
+        if (!annNode || !node || !valueNode)
+            continue;
+        if (node.type === 'class_declaration' && annNode.text === 'RequestMapping') {
+            if (!isRouteMemberKey(keyNode))
+                continue;
+            const prefix = unquoteSpringLiteral(valueNode.text);
+            if (prefix !== null)
+                prefixByClassId.set(node.id, prefix);
+        }
+    }
+    // Phase 2: collect method-level routes and resolve their class prefix
+    const routes = [];
+    for (const match of matches) {
+        const caps = {};
+        for (const { name, node } of match.captures) {
+            caps[name] = node;
+        }
+        const annNode = caps['ann'];
+        const node = caps['node'];
+        const valueNode = caps['value'];
+        const keyNode = caps['key'];
+        if (!annNode || !node || !valueNode)
+            continue;
+        if (node.type !== 'method_declaration')
+            continue;
+        const ann = annNode.text;
+        const httpMethod = METHOD_ANNOTATION_TO_HTTP[ann];
+        if (!httpMethod)
+            continue; // skip @RequestMapping on methods (ambiguous verb)
+        if (!isRouteMemberKey(keyNode))
+            continue;
+        const routePath = unquoteSpringLiteral(valueNode.text);
+        if (routePath === null)
+            continue;
+        const enclosingClass = findEnclosingClass(node);
+        const classPrefix = enclosingClass ? (prefixByClassId.get(enclosingClass.id) ?? '') : '';
+        routes.push({
+            filePath,
+            routePath,
+            httpMethod,
+            decoratorName: ann,
+            lineNumber: annNode.startPosition.row + lineOffset,
+            ...(classPrefix ? { prefix: classPrefix } : {}),
+        });
+    }
+    return routes;
+}