gitnexus 1.6.10-rc.215 → 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/import-resolvers/php.js

@@ -36,12 +36,23 @@ export function resolvePhpImportInternal(importPath, composerConfig, allFiles, n
         return null;
     if (composerConfig) {
         const sorted = getSortedPsr4(composerConfig);
+        const authoritativePsr4 = composerConfig.authoritativePsr4 ?? new Set(sorted.map(([namespace]) => namespace));
+        let matchedAuthoritativeNamespace = false;
+        let hasAuthoritativeCatchAllNamespace = false;
+        const ownershipPath = normalized.replace(/^\/+/, '');
         for (const [nsPrefix, dirPrefix] of sorted) {
-            const nsPrefixSlash = nsPrefix.replace(/\\/g, '/');
-            if (normalized.startsWith(nsPrefixSlash + '/') || normalized === nsPrefixSlash) {
-                const remainder = normalized.slice(nsPrefixSlash.length).replace(/^\//, '');
+            const nsPrefixSlash = nsPrefix.replace(/\\/g, '/').replace(/\/+$/, '');
+            const isCatchAll = nsPrefixSlash === '';
+            if (isCatchAll ||
+                ownershipPath.startsWith(nsPrefixSlash + '/') ||
+                ownershipPath === nsPrefixSlash) {
+                const isAuthoritative = authoritativePsr4.has(nsPrefix);
+                matchedAuthoritativeNamespace ||= isAuthoritative;
+                hasAuthoritativeCatchAllNamespace ||= isAuthoritative && isCatchAll;
+                const remainder = ownershipPath.slice(nsPrefixSlash.length).replace(/^\//, '');
                 // 1. Try class-style PSR-4: full path → file (e.g. App\Models\User → app/Models/User.php)
-                const filePath = dirPrefix + (remainder ? '/' + remainder : '') + '.php';
+                const mappedPath = dirPrefix === '' ? remainder : dirPrefix + (remainder ? '/' + remainder : '');
+                const filePath = mappedPath + '.php';
                 if (allFiles.has(filePath))
                     return filePath;
                 if (index) {
@@ -51,44 +62,60 @@ export function resolvePhpImportInternal(importPath, composerConfig, allFiles, n
                 }
                 // 2. Function/constant fallback: strip last segment (symbol name), scan namespace directory.
                 //    e.g. App\Models\getUser → directory app/Models/, find first .php file in that dir.
-                const lastSlash = remainder.lastIndexOf('/');
-                const nsDir = lastSlash >= 0 ? dirPrefix + '/' + remainder.slice(0, lastSlash) : dirPrefix;
-                // Prefer SuffixIndex directory lookup (O(log n + matches)) over linear scan.
-                //
-                // An EMPTY bucket is a final answer, not a miss to retry with the scan
-                // below — which is what the `else` restores, and what this comment
-                // always claimed. Re-scanning on empty was the last per-import
-                // workspace traversal left in PHP resolution after #2901: any `use`
-                // matching a PSR-4 prefix whose directory holds no direct `.php` child
-                // (`App\Legacy\Ghost`) paid a full pass, measured at 201 traversals for
-                // 200 imports.
-                //
-                // The bucket is a superset of what the scan can find, for BOTH index
-                // shapes that reach here. A root-anchored direct child `nsDir/<x>.php`
-                // has its directory exactly equal to `nsDir`, and `nsDir` is always one
-                // of that directory's own suffixes — so the shared `dirMap` (keyed on
-                // every directory suffix) necessarily contains it, as does the
-                // root-anchored parity index `languages/php/import-target.ts` builds.
-                // Empty superset therefore implies empty scan, and control falls
-                // through to the next PSR-4 prefix exactly as before.
-                if (index) {
-                    const candidates = index.getFilesInDir(nsDir, '.php');
-                    if (candidates.length > 0)
-                        return candidates[0];
-                }
-                else {
-                    // Linear scan, only when a SuffixIndex is genuinely unavailable.
-                    const nsDirPrefix = nsDir.endsWith('/') ? nsDir : nsDir + '/';
-                    for (const f of allFiles) {
-                        if (f.startsWith(nsDirPrefix) &&
-                            f.endsWith('.php') &&
-                            !f.slice(nsDirPrefix.length).includes('/')) {
-                            return f;
+                // A root/catch-all mapping cannot safely infer a symbol's declaring
+                // file from an arbitrary sibling. The higher-level PHP resolver has
+                // parsed symbol-kind and declaration evidence for function/const
+                // imports; class imports must not inherit this directory heuristic.
+                if (!isCatchAll && dirPrefix !== '') {
+                    const lastSlash = remainder.lastIndexOf('/');
+                    const relativeNamespace = lastSlash >= 0 ? remainder.slice(0, lastSlash) : '';
+                    const nsDir = relativeNamespace === '' ? dirPrefix : `${dirPrefix}/${relativeNamespace}`;
+                    // Prefer SuffixIndex directory lookup (O(log n + matches)) over linear scan.
+                    //
+                    // An EMPTY bucket is a final answer, not a miss to retry with the scan
+                    // below — which is what the `else` restores, and what this comment
+                    // always claimed. Re-scanning on empty was the last per-import
+                    // workspace traversal left in PHP resolution after #2901: any `use`
+                    // matching a PSR-4 prefix whose directory holds no direct `.php` child
+                    // (`App\Legacy\Ghost`) paid a full pass, measured at 201 traversals for
+                    // 200 imports.
+                    //
+                    // The bucket is a superset of what the scan can find, for BOTH index
+                    // shapes that reach here. A root-anchored direct child `nsDir/<x>.php`
+                    // has its directory exactly equal to `nsDir`, and `nsDir` is always one
+                    // of that directory's own suffixes — so the shared `dirMap` (keyed on
+                    // every directory suffix) necessarily contains it, as does the
+                    // root-anchored parity index `languages/php/import-target.ts` builds.
+                    // Empty superset therefore implies empty scan, and control falls
+                    // through to the next PSR-4 prefix exactly as before.
+                    if (index) {
+                        const candidates = index.getFilesInDir(nsDir, '.php');
+                        if (candidates.length > 0)
+                            return candidates[0];
+                    }
+                    else {
+                        // Linear scan, only when a SuffixIndex is genuinely unavailable.
+                        const nsDirPrefix = nsDir.endsWith('/') ? nsDir : nsDir + '/';
+                        for (const f of allFiles) {
+                            if (f.startsWith(nsDirPrefix) &&
+                                f.endsWith('.php') &&
+                                !f.slice(nsDirPrefix.length).includes('/')) {
+                                return f;
+                            }
                         }
                     }
                 }
             }
         }
+        // A non-empty PSR-4 map is authoritative for namespaces it does not own.
+        // Preserve the existing mapped-namespace fallback behavior; #2962 is the
+        // conservative external-namespace gate, not a rewrite of mapped lookup.
+        // A catch-all owns every namespace, so its misses remain authoritative.
+        if (authoritativePsr4.size > 0 &&
+            !composerConfig.hasUnmodeledAutoload &&
+            (!matchedAuthoritativeNamespace || hasAuthoritativeCatchAllNamespace)) {
+            return null;
+        }
     }
     // Fallback: suffix matching (works without composer.json)
     const pathParts = normalized.split('/').filter(Boolean);

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

@@ -14,10 +14,19 @@ export interface GoModuleConfig {
 export interface ComposerConfig {
     /** Map of namespace prefix -> directory (e.g., "App\\" -> "app/") */
     psr4: Map<string, string>;
+    /** Production `autoload.psr-4` prefixes that may gate external namespaces.
+     *  Absent on legacy/manual configs, where every mapping remains authoritative. */
+    authoritativePsr4?: ReadonlySet<string>;
+    /** True when Composer also declares an autoload mechanism this resolver does not model. */
+    hasUnmodeledAutoload?: boolean;
     /** PSR-4 entries sorted by namespace length descending (longest match wins).
      *  Cached once at config load time to avoid re-sorting on every import. */
     psr4Sorted?: readonly [string, string][];
 }
+/** Parse one Composer manifest without performing I/O. */
+export declare function parseComposerConfig(value: unknown, baseDir?: string): ComposerConfig | null;
+/** Merge package-local Composer manifests into one repository-relative config. */
+export declare function mergeComposerConfigs(configs: readonly ComposerConfig[]): ComposerConfig | null;
 /** C# project config parsed from .csproj files */
 export interface CSharpProjectConfig {
     /** Root namespace from <RootNamespace> or assembly name (default: project directory name) */

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

@@ -5,6 +5,93 @@ import path from 'path';
 import { isDev } from './utils/env.js';
 import { mapConcurrent } from '../../lib/utils.js';
 import { logger } from '../logger.js';
+function normalizeComposerDirectory(baseDir, directory) {
+    const normalizedBase = baseDir.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+    const normalizedDirectory = directory
+        .replace(/\\/g, '/')
+        .replace(/^(?:\.\/)+/, '')
+        .replace(/\/+$/, '');
+    if (normalizedBase === '')
+        return normalizedDirectory;
+    if (normalizedDirectory === '')
+        return normalizedBase;
+    return path.posix.normalize(`${normalizedBase}/${normalizedDirectory}`);
+}
+/** Parse one Composer manifest without performing I/O. */
+export function parseComposerConfig(value, baseDir = '') {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const composer = value;
+    const autoload = composer.autoload;
+    const autoloadDev = composer['autoload-dev'];
+    if (autoload === undefined && autoloadDev === undefined)
+        return null;
+    const psr4 = new Map();
+    const authoritativePsr4 = new Set();
+    let hasUnmodeledAutoload = false;
+    const addSection = (sectionValue, authoritative) => {
+        if (typeof sectionValue !== 'object' || sectionValue === null || Array.isArray(sectionValue)) {
+            return;
+        }
+        const section = sectionValue;
+        if ('psr-0' in section || 'classmap' in section)
+            hasUnmodeledAutoload = true;
+        const rawPsr4 = section['psr-4'];
+        if (typeof rawPsr4 !== 'object' || rawPsr4 === null || Array.isArray(rawPsr4))
+            return;
+        for (const [namespace, directories] of Object.entries(rawPsr4)) {
+            const stringDirectories = Array.isArray(directories)
+                ? directories.filter((entry) => typeof entry === 'string')
+                : typeof directories === 'string'
+                    ? [directories]
+                    : [];
+            if (stringDirectories.length === 0)
+                continue;
+            if (stringDirectories.length > 1)
+                hasUnmodeledAutoload = true;
+            const normalizedNamespace = namespace.replace(/\\+$/, '');
+            const normalizedDirectory = normalizeComposerDirectory(baseDir, stringDirectories[0]);
+            const existing = psr4.get(normalizedNamespace);
+            if (existing !== undefined && existing !== normalizedDirectory) {
+                hasUnmodeledAutoload = true;
+                continue;
+            }
+            if (existing === undefined)
+                psr4.set(normalizedNamespace, normalizedDirectory);
+            if (authoritative)
+                authoritativePsr4.add(normalizedNamespace);
+        }
+    };
+    // Production mappings win duplicate prefixes. Development mappings remain
+    // usable for test code but do not establish authority for the external gate.
+    addSection(autoload, true);
+    addSection(autoloadDev, false);
+    return { psr4, authoritativePsr4, hasUnmodeledAutoload };
+}
+/** Merge package-local Composer manifests into one repository-relative config. */
+export function mergeComposerConfigs(configs) {
+    if (configs.length === 0)
+        return null;
+    const psr4 = new Map();
+    const authoritativePsr4 = new Set();
+    let hasUnmodeledAutoload = false;
+    for (const config of configs) {
+        hasUnmodeledAutoload ||= config.hasUnmodeledAutoload === true;
+        for (const [namespace, directory] of config.psr4) {
+            const existing = psr4.get(namespace);
+            if (existing !== undefined && existing !== directory) {
+                hasUnmodeledAutoload = true;
+                continue;
+            }
+            if (existing === undefined)
+                psr4.set(namespace, directory);
+        }
+        for (const namespace of config.authoritativePsr4 ?? config.psr4.keys()) {
+            authoritativePsr4.add(namespace);
+        }
+    }
+    return { psr4, authoritativePsr4, hasUnmodeledAutoload };
+}
 /** Project the one-pass {@link CSharpProjectScan} into the
  *  {@link CSharpNamespaceEvidence} both import-resolution legs thread to the
  *  #1881 gate — one shape, two carriers (`ImportConfigs.csharpNamespaces` for
@@ -85,20 +172,13 @@ export async function loadComposerConfig(repoRoot) {
     try {
         const composerPath = path.join(repoRoot, 'composer.json');
         const raw = await fs.readFile(composerPath, 'utf-8');
-        const composer = JSON.parse(raw);
-        const psr4Raw = composer.autoload?.['psr-4'] ?? {};
-        const psr4Dev = composer['autoload-dev']?.['psr-4'] ?? {};
-        const merged = { ...psr4Raw, ...psr4Dev };
-        const psr4 = new Map();
-        for (const [ns, dir] of Object.entries(merged)) {
-            const nsNorm = ns.replace(/\\+$/, '');
-            const dirNorm = dir.replace(/\\/g, '/').replace(/\/+$/, '');
-            psr4.set(nsNorm, dirNorm);
-        }
+        const config = parseComposerConfig(JSON.parse(raw));
+        if (config === null)
+            return null;
         if (isDev) {
-            logger.info(`📦 Loaded ${psr4.size} PSR-4 mappings from composer.json`);
+            logger.info(`📦 Loaded ${config.psr4.size} PSR-4 mappings from composer.json`);
         }
-        return { psr4 };
+        return config;
     }
     catch {
         return null;

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>;