gitnexus 1.6.10-rc.216 → 1.6.10-rc.217

package/dist/core/group/extractors/http-patterns/java.js

@@ -2,6 +2,7 @@ import Java from 'tree-sitter-java';
 import { compilePatterns, runCompiledPatterns, unquoteLiteral, } from '../tree-sitter-scanner.js';
 import { springAnnotationHttpMethods, intersectSpringHttpMethods, isRouteMemberKey, findEnclosingClass, joinPath, } from '../../../ingestion/route-extractors/spring-shared.js';
 import { REST_TEMPLATE_TO_HTTP, WEB_CLIENT_SHORT_TO_HTTP, WEB_CLIENT_LONG_VERB_RE, EXCHANGE_ANNOTATION_TO_HTTP, parseRequestLine, pushPrefix, scanSpringInheritanceProject, OPENFEIGN_FRAMEWORK, HTTP_INTERFACE_FRAMEWORK, FEIGN_CONFIDENCE, REQUEST_LINE_CONFIDENCE, EXCHANGE_CONFIDENCE, } from './spring-consumer-shared.js';
+import { extractJavaModuleConstants, foldJavaOperands, isJavaConstantFile, parseJavaConstOperands, } from '../../../ingestion/route-extractors/java-const-resolver.js';
 import { extractStaticPathExpression, inferOkHttpMethod, inferHttpClientMethod, okHttpUrlRootsAtBuilder, httpClientUriRootsAtNewBuilder, httpClientChainHasUriCall, } from './java-static-path.js';
 /**
  * Java HTTP plugin. Handles:
@@ -123,6 +124,34 @@ const JAVA_ROUTE_ANNOTATION_PATTERNS = compilePatterns({
                     key: (identifier) @key
                     value: [(string_literal) @value (element_value_array_initializer (string_literal) @value)]))))
             name: (identifier) @member) @node
+          (class_declaration
+            (modifiers
+              (annotation
+                name: [(identifier) (scoped_identifier)] @ann
+                arguments: (annotation_argument_list [(identifier) @value_expr (field_access) @value_expr (binary_expression) @value_expr])))) @node
+          (class_declaration
+            (modifiers
+              (annotation
+                name: [(identifier) (scoped_identifier)] @ann
+                arguments: (annotation_argument_list
+                  (element_value_pair
+                    key: (identifier) @key
+                    value: [(identifier) @value_expr (field_access) @value_expr (binary_expression) @value_expr]))))) @node
+          (method_declaration
+            (modifiers
+              (annotation
+                name: [(identifier) (scoped_identifier)] @ann
+                arguments: (annotation_argument_list [(identifier) @value_expr (field_access) @value_expr (binary_expression) @value_expr])))
+            name: (identifier) @member) @node
+          (method_declaration
+            (modifiers
+              (annotation
+                name: [(identifier) (scoped_identifier)] @ann
+                arguments: (annotation_argument_list
+                  (element_value_pair
+                    key: (identifier) @key
+                    value: [(identifier) @value_expr (field_access) @value_expr (binary_expression) @value_expr]))))
+            name: (identifier) @member) @node
         ]
       `,
         },
@@ -407,6 +436,7 @@ function scanRouteAnnotations(tree) {
     // feeds the OpenFeign *consumer* path in scan(). An interface carrying both
     // `@RequestMapping` and `@FeignClient(path)` lands a different value in each.
     const prefixByTypeId = new Map();
+    const typesWithUnfoldablePrefix = new Set();
     const feignPrefixByInterfaceId = new Map();
     const httpExchangePrefixByTypeId = new Map();
     const methodRoutes = [];
@@ -422,7 +452,10 @@ function scanRouteAnnotations(tree) {
         const annNode = captures.ann;
         const node = captures.node;
         const valueNode = captures.value;
-        if (!annNode || !node || !valueNode)
+        // A non-literal annotation value (constant ref / `+`-concat) is captured
+        // as @value_expr instead of @value — one of the two must be present.
+        const valueExprNode = captures.value_expr;
+        if (!annNode || !node || (!valueNode && !valueExprNode))
             continue;
         // Discrimination is on the trailing segment only (`simpleName`), so a
         // non-Spring annotation whose last segment collides with a route annotation
@@ -446,7 +479,7 @@ function scanRouteAnnotations(tree) {
                 const feignHttpMethod = httpMethods.length === 1 ? (httpMethods[0] === '*' ? 'GET' : httpMethods[0]) : null;
                 if (!isRouteMemberKey(keyNode))
                     continue;
-                const rawPath = unquoteLiteral(valueNode.text);
+                const rawPath = valueNode ? unquoteLiteral(valueNode.text) : null;
                 if (rawPath !== null) {
                     for (const httpMethod of httpMethods) {
                         methodRoutes.push({
@@ -458,11 +491,36 @@ function scanRouteAnnotations(tree) {
                         });
                     }
                 }
+                else {
+                    // Non-literal path (a constant reference or `+`-concatenation).
+                    // Defer to scan(): the fold needs the repo-wide constant map built
+                    // by prepareRepo. Capture the operand list now; resolution happens
+                    // in scan() against JavaRepoContext, and an unresolvable operand
+                    // list leaves the route skipped (KTD5 skip floor).
+                    const operands = parseJavaConstOperands(valueExprNode);
+                    if (operands !== null) {
+                        for (const httpMethod of httpMethods) {
+                            methodRoutes.push({
+                                methodNode: node,
+                                methodName: captures.member?.text ?? null,
+                                httpMethod,
+                                rawPath: '',
+                                feignHttpMethod,
+                                pathOperands: operands,
+                            });
+                        }
+                    }
+                }
             }
             else if (ann === 'RequestLine') {
                 // Feign packs verb + path in one literal; its only named argument is `value`.
                 if (keyNode && keyNode.text !== 'value')
                     continue;
+                // A constant-valued `@RequestLine` arrives as @value_expr, not @value —
+                // `valueNode` is undefined in that shape. Skip rather than dereference
+                // (constant folding for Feign verb+path literals is out of scope here).
+                if (!valueNode)
+                    continue;
                 const raw = unquoteLiteral(valueNode.text);
                 const parsed = raw !== null ? parseRequestLine(raw) : null;
                 if (parsed) {
@@ -479,7 +537,7 @@ function scanRouteAnnotations(tree) {
                 // (`accept`, `contentType`, …) are not routes.
                 if (keyNode && keyNode.text !== 'url' && keyNode.text !== 'value')
                     continue;
-                const rawPath = unquoteLiteral(valueNode.text);
+                const rawPath = valueNode ? unquoteLiteral(valueNode.text) : null;
                 if (rawPath !== null) {
                     exchangeRoutes.push({
                         methodNode: node,
@@ -496,6 +554,11 @@ function scanRouteAnnotations(tree) {
         if (ann === 'RequestMapping') {
             if (!isRouteMemberKey(keyNode))
                 continue;
+            if (!valueNode) {
+                // Constant-valued class prefix — see `typesWithUnfoldablePrefix`.
+                typesWithUnfoldablePrefix.add(node.id);
+                continue;
+            }
             const prefix = unquoteLiteral(valueNode.text);
             if (prefix !== null) {
                 pushPrefix(prefixByTypeId, node.id, prefix);
@@ -508,7 +571,7 @@ function scanRouteAnnotations(tree) {
             // Feign's `name`/`value` identify a service, not a path — only `path` is a prefix.
             if (!keyNode || keyNode.text !== 'path')
                 continue;
-            const prefix = unquoteLiteral(valueNode.text);
+            const prefix = valueNode ? unquoteLiteral(valueNode.text) : null;
             if (prefix !== null)
                 pushPrefix(feignPrefixByInterfaceId, node.id, prefix);
         }
@@ -517,7 +580,7 @@ function scanRouteAnnotations(tree) {
             // (or positionally). Applies to its `@(Get|...)Exchange` consumer methods.
             if (keyNode && keyNode.text !== 'url' && keyNode.text !== 'value')
                 continue;
-            const prefix = unquoteLiteral(valueNode.text);
+            const prefix = valueNode ? unquoteLiteral(valueNode.text) : null;
             if (prefix !== null)
                 pushPrefix(httpExchangePrefixByTypeId, node.id, prefix);
         }
@@ -566,6 +629,7 @@ function scanRouteAnnotations(tree) {
     }
     return {
         prefixByTypeId,
+        typesWithUnfoldablePrefix,
         feignPrefixByInterfaceId,
         httpExchangePrefixByTypeId,
         methodRoutes: constrainedMethodRoutes,
@@ -608,9 +672,22 @@ function collectImplementedInterfaces(typeNode) {
     return out;
 }
 function collectSpringTypes(filePath, tree) {
-    const { prefixByTypeId, methodRoutes } = scanRouteAnnotations(tree);
+    const { prefixByTypeId, typesWithUnfoldablePrefix, methodRoutes } = scanRouteAnnotations(tree);
     const routesByMethodId = new Map();
     for (const route of methodRoutes) {
+        // Constant-valued class prefix: no single prefix string exists here, so the
+        // inheritance view would publish this route unprefixed. Skip — same rule as
+        // scan() and as ingestion (R4 parity).
+        const owner = findEnclosingClass(route.methodNode);
+        if (owner && typesWithUnfoldablePrefix.has(owner.id))
+            continue;
+        // A constant-referencing route still carries `rawPath: ''` here — folding
+        // happens in scan() against the repo constant map, which this
+        // inheritance-view collector has no access to. Emitting it as an empty
+        // path would publish `POST /`-shaped noise into the shared type view;
+        // skip instead (ingestion keeps the same skip floor — R4 parity).
+        if (route.pathOperands)
+            continue;
         const routes = routesByMethodId.get(route.methodNode.id) ?? [];
         routes.push({ method: route.httpMethod, path: route.rawPath });
         routesByMethodId.set(route.methodNode.id, routes);
@@ -671,19 +748,121 @@ export const JAVA_HTTP_PLUGIN = {
     hasConsumerSignals(content) {
         return /\brestTemplate\b|\bwebClient\b|Request\.Builder|HttpRequest|HttpMethod\.|new\s+Http(Get|Post|Put|Delete|Patch)\b|@RequestLine|@FeignClient|Exchange/.test(content);
     },
-    scan(tree) {
+    prepareRepo(args) {
+        // Build the repo-wide Java string-constant map once per extract() run
+        // (mirrors the Python binding's cost-gated pre-pass). A cheap content
+        // gate keeps literal-only repos at zero parses: only files containing a
+        // `static final String` declaration are parsed for constants.
+        try {
+            // The orchestrator hands over a bare Parser (no language set yet);
+            // bind Java explicitly — Python's prepareRepo does the same — otherwise
+            // parseSourceSafe spins to its 15 s budget per file.
+            args.parser.setLanguage(Java);
+        }
+        catch {
+            // fall through: a parser that rejects binding cannot produce a constant
+            // map; per-file try/catch below then skips everything harmlessly.
+        }
+        const constants = new Map();
+        for (const rel of args.files) {
+            if (!rel.endsWith('.java'))
+                continue;
+            try {
+                const src = args.readFile(rel);
+                // Cheap content gate: only constant-DEFINITION candidates get parsed
+                // here (~hundreds of files). Import-only files (every controller)
+                // are deliberately NOT parsed in this pass — scan() lazily extracts
+                // the importing file's own import table from the tree it already
+                // holds when a constant-referencing route actually needs the fold.
+                // A gate that also matched `import ...;` would parse the entire
+                // repository here (tens of thousands of files) just to build import
+                // tables the fold can derive per-file on demand.
+                //
+                // The predicate is the SHARED one the ingestion provider uses, so the
+                // two subsystems agree on which files define constants. Its previous
+                // local spelling missed `final static String` and lowercase interface
+                // names, and admitted an interface that ingestion's gate rejected.
+                if (!src || !isJavaConstantFile(src)) {
+                    continue;
+                }
+                const tree = args.parseSource(args.parser, src);
+                if (!tree)
+                    continue;
+                const mc = extractJavaModuleConstants(tree);
+                if (mc.literals.size > 0 || mc.exprs.size > 0 || mc.imports.size > 0) {
+                    constants.set(rel, mc);
+                }
+            }
+            catch {
+                // Per-file resilience: one unreadable/oversized/ill-formed file must
+                // not forfeit the whole repo's constant map (a missing constants
+                // class only degrades refs that pointed at it).
+                continue;
+            }
+        }
+        return { constants };
+    },
+    scan(tree, repoContext, fileRel) {
         const out = [];
+        const javaCtx = repoContext;
         // ─── Spring providers + OpenFeign consumers (one query pass) ────
         // `scanRouteAnnotations` resolves every route-defining annotation —
         // class/interface prefixes, method shortcut/`@RequestMapping`s and native
         // `@RequestLine`s — from a single `matches()` pass over the tree.
-        const { prefixByTypeId, feignPrefixByInterfaceId, httpExchangePrefixByTypeId, methodRoutes, requestLines, exchangeRoutes, } = scanRouteAnnotations(tree);
+        const { prefixByTypeId, typesWithUnfoldablePrefix, feignPrefixByInterfaceId, httpExchangePrefixByTypeId, methodRoutes, requestLines, exchangeRoutes, } = scanRouteAnnotations(tree);
         // A `@(Get|...)Mapping` inside a `@FeignClient` interface is an OpenFeign
         // *consumer* (it describes a remote call); the same annotation inside a
         // class is a Spring *provider*. A mapping on a non-Feign interface has no
         // enclosing class and is dropped here — interface→controller inheritance is
         // handled by `scanProject`.
+        // Lazy per-file constants view. prepareRepo only indexes constant-
+        // DEFINING files (cheap gate); an importing controller is absent from
+        // that map. When a route actually references a constant, extract THIS
+        // file's import table from the tree scan() already holds (zero extra
+        // parses) and overlay it for the fold. Files whose routes are all
+        // literal — the overwhelming majority — never pay this cost.
+        let foldConstants;
+        const getFoldConstants = () => {
+            if (foldConstants !== undefined)
+                return foldConstants;
+            foldConstants = javaCtx?.constants;
+            if (!javaCtx?.constants || !fileRel)
+                return foldConstants;
+            if (javaCtx.constants.has(fileRel))
+                return foldConstants;
+            try {
+                const mc = extractJavaModuleConstants(tree);
+                if (mc.imports.size > 0) {
+                    const merged = new Map(javaCtx.constants);
+                    merged.set(fileRel, mc);
+                    foldConstants = merged;
+                }
+            }
+            catch {
+                // fold falls back to the repo-wide map (imports stay unresolved)
+            }
+            return foldConstants;
+        };
         for (const route of methodRoutes) {
+            // A constant-valued CLASS prefix cannot be folded here, so every method
+            // route under such a class is suppressed rather than emitted at a wrong
+            // (unprefixed) path — the same rule `classesWithArrayPrefix` already
+            // encodes for the array form, and the same rule ingestion applies.
+            const owner = findEnclosingClass(route.methodNode);
+            if (owner && typesWithUnfoldablePrefix.has(owner.id))
+                continue;
+            // Non-literal route path: fold the operand list against the repo-wide
+            // constant map. Skip (never a guessed path) when the fold fails or the
+            // repo context is absent (context-less fallback scanning).
+            if (route.pathOperands && javaCtx && fileRel) {
+                const resolved = foldJavaOperands(fileRel, route.pathOperands, getFoldConstants());
+                if (resolved === null)
+                    continue;
+                route.rawPath = resolved;
+            }
+            else if (route.pathOperands) {
+                continue;
+            }
             const enclosingInterface = findEnclosingInterface(route.methodNode);
             if (enclosingInterface && hasAnnotation(enclosingInterface, 'FeignClient')) {
                 if (!route.feignHttpMethod)

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

@@ -23,6 +23,7 @@ import type { CfgVisitor } from './cfg/types.js';
 import type { NodeLabel } from '../../_shared/index.js';
 import type { ExtractedRoute } from './route-extractors/laravel.js';
 import type { SharedSpringType } from './route-extractors/spring-shared.js';
+import type { ModuleConstants, Operand, RepoConstants } from './route-extractors/constant-resolver.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). */
@@ -39,6 +40,18 @@ export interface AstFrameworkPatternConfig {
  * Required fields must be explicitly set; optional fields have defaults
  * applied by defineLanguage().
  */
+/**
+ * Should the parse worker run {@link LanguageProviderConfig.extractModuleConstants}
+ * on this file?
+ *
+ * Exported so the DECISION is testable without booting a worker. It encodes the
+ * one rule that is easy to get backwards: a provider that declares no
+ * `moduleConstantHeuristic` harvests unconditionally. Writing the gate as
+ * `provider.moduleConstantHeuristic?.(content)` reads `undefined` as "skip" and
+ * silently disables the hook for every provider without a heuristic — which is
+ * exactly how Python's already-shipped harvest was turned off (#2391/#2980).
+ */
+export declare function shouldHarvestModuleConstants(provider: Pick<LanguageProvider, 'extractModuleConstants' | 'moduleConstantHeuristic'>, content: string): boolean;
 interface LanguageProviderConfig {
     readonly id: SupportedLanguages;
     /** File extensions that map to this language (e.g., ['.ts', '.tsx']) */
@@ -266,6 +279,51 @@ interface LanguageProviderConfig {
      * Default: undefined (no interface-inheritance route resolution).
      */
     readonly extractRouteInheritanceTypes?: (tree: Parser.Tree, filePath: string) => SharedSpringType[];
+    /**
+     * Harvest this file's module-level string constants (#2391 core, #2980 Java
+     * parity) into the language-agnostic {@link ModuleConstants} shape, so the
+     * parse phase can resolve non-literal decorator route paths cross-file.
+     *
+     * The worker calls this when BOTH hold:
+     *  - the provider declares no `moduleConstantHeuristic`, or the one it
+     *    declares matched — syntax-driven, e.g. a `static final String` field or
+     *    a constants-bearing import; NEVER a class-name pattern like
+     *    `*Constants`, which silently drops route constants living in classes
+     *    named e.g. `ApiPaths`/`Routes`, and
+     *  - the extraction yields something resolvable (a literal, an expression, or
+     *    an import binding), keeping the aggregate bounded on large repos.
+     *
+     * Default: undefined (no constant harvest; non-literal route paths of this
+     * language floor to skip).
+     */
+    readonly extractModuleConstants?: (tree: Parser.Tree) => ModuleConstants;
+    /**
+     * Cheap content heuristic deciding whether the worker should run
+     * {@link extractModuleConstants} on a file. Guards the harvest cost on huge
+     * repos: files that cannot contribute (no constant-bearing syntax) are not
+     * walked. Must be syntax-driven (field/import shape), not identifier
+     * pattern-matching on class names.
+     *
+     * Default: undefined — harvest EVERY file of this language. A gate is opt-in
+     * because getting it wrong silently drops routes that already resolve, and a
+     * missed gate only costs time. Declare one only where the cost bites (Java's
+     * Maven monorepos) and only after checking it against every shape
+     * {@link extractModuleConstants} accepts.
+     */
+    readonly moduleConstantHeuristic?: (content: string) => boolean;
+    /**
+     * Fold one file's non-literal route-path operand list
+     * (`routePathExpr`/`routePathOperands` of an `ExtractedDecoratorRoute`)
+     * against the repo-wide, file-path-keyed constant map, or null when it cannot
+     * be fully folded (skip floor — never a phantom path). Languages whose
+     * qualified refs resolve through class imports (`Outer.CONST`,
+     * `com.example.ApiPaths.USERS`) need this hook because the shared fold has no
+     * notion of qualified names; Python's bare-name refs use the shared default.
+     *
+     * Default: undefined (the parse phase falls back to the shared
+     * language-agnostic operand fold).
+     */
+    readonly foldRoutePathOperands?: (filePath: string, operands: readonly Operand[], repo: RepoConstants) => string | null;
     /** 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>;

package/dist/core/ingestion/language-provider.js

@@ -8,6 +8,27 @@
  * The providers table in `languages/index.ts` uses `satisfies Record<SupportedLanguages, LanguageProvider>`
  * so adding a language to the enum without creating a provider is a compiler error.
  */
+/**
+ * Everything a language needs to provide.
+ * Required fields must be explicitly set; optional fields have defaults
+ * applied by defineLanguage().
+ */
+/**
+ * Should the parse worker run {@link LanguageProviderConfig.extractModuleConstants}
+ * on this file?
+ *
+ * Exported so the DECISION is testable without booting a worker. It encodes the
+ * one rule that is easy to get backwards: a provider that declares no
+ * `moduleConstantHeuristic` harvests unconditionally. Writing the gate as
+ * `provider.moduleConstantHeuristic?.(content)` reads `undefined` as "skip" and
+ * silently disables the hook for every provider without a heuristic — which is
+ * exactly how Python's already-shipped harvest was turned off (#2391/#2980).
+ */
+export function shouldHarvestModuleConstants(provider, content) {
+    if (!provider.extractModuleConstants)
+        return false;
+    return !provider.moduleConstantHeuristic || provider.moduleConstantHeuristic(content);
+}
 const DEFAULTS = {
     mroStrategy: 'first-wins',
 };

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

@@ -13,6 +13,7 @@ import { defineLanguage } from '../language-provider.js';
 import { createLeadingDocDescriptionExtractor } from '../utils/ast-helpers.js';
 import { javaTypeConfig } from '../type-extractors/jvm.js';
 import { extractSpringRoutes, extractSpringTypes } from '../route-extractors/spring.js';
+import { extractJavaModuleConstants, foldJavaOperands, isJavaConstantFile, } from '../route-extractors/java-const-resolver.js';
 import { javaExportChecker } from '../export-detection.js';
 import { createImportResolver } from '../import-resolvers/resolver-factory.js';
 import { javaImportConfig } from '../import-resolvers/configs/jvm.js';
@@ -186,4 +187,24 @@ export const javaProvider = defineLanguage({
     // ── Route extraction ──
     extractDecoratorRoutes: extractSpringRoutes,
     extractRouteInheritanceTypes: extractSpringTypes,
+    // ── #2980: constant harvest + qualified-ref fold for non-literal mapping
+    // paths (`@PostMapping(ApiPaths.SAVE_V1)`) — kept behind provider hooks so
+    // the shared ingestion layers stay language-agnostic. The heuristic is
+    // SYNTAX-driven (field/import shape), never a class-name pattern: constant
+    // classes are routinely named `ApiPaths`/`Routes`/`Paths`, which a
+    // `*Constants`-style gate would silently drop (review round-2 High finding).
+    extractModuleConstants: extractJavaModuleConstants,
+    // One gate, shared with the group side's `prepareRepo` pre-pass so the two
+    // subsystems cannot disagree about which files define constants (see
+    // JAVA_CONSTANT_FILE_RE — the previous divergence dropped constant
+    // INTERFACES on this side only, which cost the graph its Route nodes while
+    // the group still published the contract).
+    moduleConstantHeuristic: (content) => isJavaConstantFile(content) ||
+        // `import com.winning.opt.common.ApiPaths;` — ANY class import can bind a
+        // constant ref (`ApiPaths.X` at an annotation site), so gate on the
+        // general import shape, not on the imported name. Ingestion-only: this
+        // side needs the importing controller's own import table, which the group
+        // side instead derives lazily from the tree it already holds.
+        /\bimport\s+(?:static\s+)?[\w.]+\s*;/.test(content),
+    foldRoutePathOperands: foldJavaOperands,
 });

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

@@ -28,6 +28,7 @@ import { createPythonCfgVisitor } from '../cfg/visitors/python.js';
 import { emitPythonScopeCaptures, pythonFunctionDefinitionLabel, interpretPythonImport, interpretPythonTypeBinding, pythonArityCompatibility, pythonBindingScopeFor, pythonImportOwningScope, pythonMergeBindings, pythonReceiverBinding, resolvePythonImportTarget, } from './python/index.js';
 import { extractDjangoRoutes } from '../route-extractors/django.js';
 import { discoverDjangoRootUrls } from '../route-extractors/django-root-discovery.js';
+import { extractPythonModuleConstants } from '../route-extractors/python-const-resolver.js';
 const BUILT_INS = new Set([
     'print',
     'len',
@@ -134,4 +135,16 @@ export const pythonProvider = defineLanguage({
     receiverBinding: pythonReceiverBinding,
     arityCompatibility: pythonArityCompatibility,
     resolveImportTarget: resolvePythonImportTarget,
+    // ── #2391 constant harvest, provider-hook form (#2980): module-level string
+    // constants + from-imports for non-literal decorator route paths. Bare-name
+    // refs fold through the shared resolver (no foldRoutePathOperands needed).
+    // No `moduleConstantHeuristic`: Python harvests unconditionally, exactly as
+    // #2391 shipped it. A content gate was tried here and removed on review — it
+    // required `NAME` immediately followed by `=`, so it silently dropped the two
+    // idiomatic typed-FastAPI shapes (`API: str = "/api"`,
+    // `API: Final[str] = "/api"`) and every composed constant whose RHS starts
+    // with an identifier (`USERS = BASE + "/users"`), i.e. it REGRESSED routes
+    // that already resolve on main. The worker treats a missing heuristic as
+    // default-open; only Java opts into a gate, where the cost actually bites.
+    extractModuleConstants: extractPythonModuleConstants,
 });

package/dist/core/ingestion/pipeline-phases/parse-impl.js

@@ -25,7 +25,7 @@ import { getLanguageFromFilename, } from '../../../_shared/index.js';
 import { readFileContents } from '../filesystem-walker.js';
 import { isLanguageAvailable, isGrammarRuntimeSkipped, createParserForLanguage, } from '../../tree-sitter/parser-loader.js';
 import { parseSourceSafe } from '../../tree-sitter/safe-parse.js';
-import { getProvider, providers } from '../languages/index.js';
+import { getProvider, getProviderForFile, providers } from '../languages/index.js';
 import { SCOPE_RESOLVERS } from '../scope-resolution/pipeline/registry.js';
 import { DATA_ROUTE_TABLE_SOURCE } from '../route-extractors/data-route-table.js';
 import { createWorkerPool, workerPoolDisabledByEnv, resolveAutoPoolSize, WorkerPoolInitializationError, WorkerPoolDisabledError, } from '../workers/worker-pool.js';
@@ -1058,8 +1058,15 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                 resolvedRoutes.push(dr);
                 continue;
             }
+            // Provider-driven fold (#2980): languages with qualified-ref semantics
+            // (Java `ApiPaths.X` / `com.example.ApiPaths.X`) fold through their
+            // provider hook; everything else uses the shared language-agnostic
+            // operand fold. No language names in the shared layer.
+            const fold = getProviderForFile(dr.filePath)?.foldRoutePathOperands;
             const value = dr.routePathOperands
-                ? resolveOperands(dr.filePath, dr.routePathOperands, repoConstants)
+                ? fold
+                    ? fold(dr.filePath, dr.routePathOperands, repoConstants)
+                    : resolveOperands(dr.filePath, dr.routePathOperands, repoConstants)
                 : null;
             if (value === null) {
                 skipped++;

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

@@ -23,6 +23,12 @@
  * (intra-procedural, function-local, def→use reachability — not module-level
  * cross-file value folding).
  */
+/** Max length of a folded path. Real route paths are well under this; a fold that
+ * exceeds it is a pathological self-multiplying concat (`X = A + A; A = B + B; …`)
+ * whose true value is genuinely huge — building it risks a `RangeError`/heap OOM,
+ * so we floor to `null` (skip) instead (#2393). The depth cap bounds recursion but
+ * NOT output size, which grows multiplicatively; this bounds the output. */
+export declare const MAX_FOLD_LENGTH = 8192;
 /**
  * One term of a constant's right-hand side. A `+`-concatenation
  * (`A + "/b" + C`) becomes an ordered `Operand[]`; a bare literal is a

package/dist/core/ingestion/route-extractors/constant-resolver.js

@@ -31,7 +31,7 @@ const MAX_RESOLVE_DEPTH = 8;
  * whose true value is genuinely huge — building it risks a `RangeError`/heap OOM,
  * so we floor to `null` (skip) instead (#2393). The depth cap bounds recursion but
  * NOT output size, which grows multiplicatively; this bounds the output. */
-const MAX_FOLD_LENGTH = 8192;
+export const MAX_FOLD_LENGTH = 8192;
 /**
  * Fold an operand list to its concatenated literal, or `null` if any operand is
  * unresolvable (an unknown name, a non-string term, a cycle, or a depth overrun).

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

@@ -0,0 +1,114 @@
+/**
+ * Java binding for the language-agnostic constant resolver (#2391 core).
+ *
+ * Supplies the two Java-specific pieces the shared fold in
+ * `constant-resolver.ts` needs — {@link resolveJavaImport} (import-specifier →
+ * file, honoring JVM package/classpath rules) and
+ * {@link extractJavaModuleConstants} (tree → {@link ModuleConstants}) — plus a
+ * pre-bound {@link resolveJavaConstant} wrapper so callers stay
+ * language-oblivious. The reusable fold, the cycle guard, and the depth cap
+ * all live in the agnostic core.
+ *
+ * Java constant shape (one per type declaration; nested classes flatten into
+ * the same file-level namespace, mirroring how `Outer.CONST` and a top-level
+ * `CONST` are indistinguishable at the fold layer):
+ *
+ *   public class ApiPathConstants {
+ *       public static final String DIAGNOSIS_SAVE_V1 = "/api/v1/diagnosis/add";
+ *       public static final String API_CIS_SAVE_SUMMARY = API_CIS_V1 + "summary/save";
+ *   }
+ *
+ * Reference shapes at annotation sites this binding resolves:
+ *   @PostMapping(ApiPathConstants.DIAGNOSIS_SAVE_V1)      // qualified
+ *   @PostMapping(com.winning.opt.X.ApiPathConstants.Y)    // FQN-qualified
+ *   @PostMapping(DIAGNOSIS_SAVE_V1)                       // static-imported
+ *   @PostMapping(API_CIS_V1 + "summary/save")             // inline concat
+ *
+ * Which ANNOTATIONS count as routes is a separate question this module has no
+ * say in: `spring-shared.ts` holds an exact-name map, so a vendor alias like
+ * `@WinPostMapping` yields no route on this base regardless of how its value
+ * folds (#2883). Folding and alias recognition compose; neither implies the
+ * other.
+ *
+ * Import shapes consumed:
+ *   import com.winning.opt.diagnosis.api.constants.ApiPathConstants;
+ *   import static com.winning.opt.diagnosis.api.constants.ApiPathConstants.API_CIS_V1;
+ *
+ * Keying (KTD4 parity with the Python binding): the repo map is keyed by
+ * unique POSIX file path. A Java import `com.a.b.CONSTS` resolves to the file
+ * whose path ends with `com/a/b/CONSTS.java`; when 2+ files share that suffix
+ * the import is ambiguous and returns null (skip floor), never a wrong path.
+ */
+import type Parser from 'tree-sitter';
+import { type ImportResolver, type ModuleConstants, type Operand, type RepoConstants } from './constant-resolver.js';
+export type { ImportBinding, ModuleConstants, Operand, RepoConstants, } from './constant-resolver.js';
+export declare function isJavaConstantFile(source: string): boolean;
+/**
+ * The Java {@link ImportResolver}: 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.
+ *
+ * `com.winning.opt.X.ApiPathConstants` → the file key ending in
+ * `com/winning/opt/X/ApiPathConstants.java`. Because the repo map is
+ * file-path-keyed and Maven multi-module trees repeat package roots across
+ * modules (`winning-opt-a/.../api/constants/ApiPathConstants.java` and
+ * `winning-opt-b/.../api/constants/ApiPathConstants.java`), suffix matching
+ * stays UNIQUE-suffix: an import whose full package+class path matches N files
+ * in N different modules cannot be pinned, so it returns null — the skip floor
+ * this module promises, never a wrong path.
+ *
+ * A nearest-shared-directory tie-break was tried here and removed on review:
+ * javac resolves duplicate FQNs by CLASSPATH ORDER, not directory proximity, so
+ * a `src/test` fixture copy or a module that merely sits 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.
+ */
+export declare const resolveJavaImport: ImportResolver;
+/**
+ * Parse a Java constant initializer into an operand list, or null when it is
+ * not a foldable string expression. Handles a bare string literal, a bare
+ * identifier (`X = Y`), qualified/static-import-free references
+ * (`X = CONSTS.Y` — recorded as ONE ref named `CONSTS.Y`), and
+ * left-associative `+` chains of the three. Everything else — numbers, calls,
+ * ternaries, method refs, `String.format`, enum constants — returns null,
+ * which makes the constant unresolvable (→ skip floor), never a wrong value.
+ */
+export declare function parseJavaConstOperands(node: Parser.SyntaxNode | null | undefined, depth?: number): Operand[] | null;
+/**
+ * Extract the file-level string constants and import bindings of one parsed
+ * Java file into the {@link ModuleConstants} shape the resolver consumes.
+ *
+ * Constants: every `static final String NAME = …` field of every type
+ * declaration in the file (nested classes included — their simple names
+ * would collide at the fold layer, but qualified refs carry the class name
+ * so nesting only matters for same-name fields, which flatten last-wins).
+ * Interface constants (`String NAME = "…"`) are implicitly static final and
+ * are collected too.
+ *
+ * References to OTHER constants via qualified names (`ApiPathConstants.X`)
+ * are stored as refs named `ApiPathConstants.X`; at the fold layer such a ref
+ * resolves through the import map (`ApiPathConstants` → module) followed by
+ * field lookup in the target file's OWN class-name-qualified namespace. To
+ * support that, constant names are ALSO recorded under
+ * `<DeclaringClass>.<FIELD>` (both spellings share one entry).
+ *
+ * Last-wins in source order; a non-foldable rebind (`X = compute()`) drops X
+ * to unresolvable rather than keeping a stale literal.
+ */
+export declare function extractJavaModuleConstants(tree: Parser.Tree): ModuleConstants;
+/**
+ * Resolve a single Java constant referenced in `fileKey` to its literal string
+ * value, folding `+` concatenation and following import chains via
+ * {@link resolveJavaImport}, or null when it cannot be fully folded.
+ *
+ * `name` may be simple (`DIAGNOSIS_SAVE_V1`, resolved via static import or
+ * same-file constant) or qualified (`ApiPathConstants.DIAGNOSIS_SAVE_V1`,
+ * resolved via the class import + the target file's qualified alias).
+ */
+export declare function resolveJavaConstant(fileKey: string, name: string, repo: RepoConstants, depth?: number): string | null;
+/**
+ * Fold an inline operand list (e.g. `API_CIS_V1 + "summary/save"`) against
+ * `fileKey`, or null when any piece is unresolvable (skip floor).
+ */
+export declare function foldJavaOperands(fileKey: string, operands: readonly Operand[], repo: RepoConstants): string | null;