gitnexus 1.6.10-rc.7 → 1.6.10-rc.8

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

@@ -1,6 +1,7 @@
 import Python from 'tree-sitter-python';
 import { compilePatterns, runCompiledPatterns, unquoteLiteral, } from '../tree-sitter-scanner.js';
 import { normalizeExtractedRoutePath } from '../../../ingestion/route-extractors/route-path.js';
+import { extractPythonModuleConstants, parseConstOperands, resolveOperands, } from '../../../ingestion/route-extractors/python-const-resolver.js';
 /**
  * Python HTTP plugin. Handles:
  *   - FastAPI `@app.get("/path")` provider decorators
@@ -67,6 +68,44 @@ const FASTAPI_ROUTER_PATTERNS = compilePatterns({
         },
     ],
 });
+// #2391: `@router.<verb>` / `@app.<verb>` whose first argument is a non-literal
+// path — a bare imported constant or a `+`-concatenation. The path is resolved
+// against the repo-wide constant map (parity with the ingestion side) and, on
+// failure, the route is skipped (no provider contract) exactly like ingestion.
+const FASTAPI_ROUTER_EXPR_PATTERNS = compilePatterns({
+    name: 'python-fastapi-router-expr',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (decorator
+          (call
+            function: (attribute
+              object: (identifier) @obj (#eq? @obj "router")
+              attribute: (identifier) @method (#match? @method "^(get|post|put|delete|patch)$"))
+            arguments: (argument_list . [(identifier) (binary_operator)] @path)))
+      `,
+        },
+    ],
+});
+const FASTAPI_APP_EXPR_PATTERNS = compilePatterns({
+    name: 'python-fastapi-app-expr',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (decorator
+          (call
+            function: (attribute
+              object: (identifier) @obj (#eq? @obj "app")
+              attribute: (identifier) @method (#match? @method "^(get|post|put|delete|patch)$"))
+            arguments: (argument_list . [(identifier) (binary_operator)] @path)))
+      `,
+        },
+    ],
+});
 // ─── Provider: Flask `app.add_url_rule('/path', view_func=handler)` ───
 // The imperative Flask route registration: unlike `@app.route` (whose handler
 // is the decorated function, same-file), `view_func` is frequently an IMPORTED
@@ -830,111 +869,153 @@ function recordPrefix(target, key, prefix) {
     set.add(prefix);
     target.set(key, set);
 }
+// Cheap cost-gate pre-filter: a `@router`/`@app.<verb>(` call whose first
+// argument is non-literal — either it STARTS with an identifier (a bare constant
+// or the head of `CONST + "/x"`), or it is a string-literal-LEADING concat
+// (`"/api" + SUFFIX`) detected by a `+` before the decorator's closing paren
+// (#2393). `[^)]*` spans the whole argument, including a Black-formatted concat
+// that wraps across lines, but stays bounded by the decorator's own `)`. Gating
+// the literal-leading case on the `+` (not merely a leading quote) keeps a plain
+// string route `@router.get("/x")` OFF the gate, so a literal-only repo pays no
+// parse pass. Deliberately loose — a false positive only costs a parse; a false
+// negative would silently drop the feature.
+const NONLITERAL_ROUTE_DECORATOR_RE = /@\s*(?:app|router)\s*\.\s*(?:get|post|put|delete|patch)\s*\(\s*(?:[A-Za-z_]|["'][^)]*\+)/;
 function buildPythonRepoContext(files, parser, readFile, parseSource) {
     const prefixesByLongKey = new Map();
     const prefixesByShortKey = new Map();
-    // Cross-file pre-pass: only `include_router` sites need it — they bind a
-    // prefix declared in one file to a router defined in another. Same-file
-    // `APIRouter(prefix=...)` is resolved in scan() from the file's own tree, so
-    // APIRouter-only files are left out here and never parsed twice.
+    // Single read pass (#2393): slurp every `.py` file's content ONCE. This used to
+    // be two passes — the include_router pre-pass below and the #2391 constant cost
+    // gate each re-read every `.py` file. The composed-route cost gate is computed
+    // in the same pass so a literal-only repo still does exactly one read and zero
+    // parses.
+    const pyContents = new Map();
+    let hasComposedRoute = false;
     for (const rel of files) {
         if (!rel.endsWith('.py'))
             continue;
         const src = readFile(rel);
         if (!src)
             continue;
-        if (!src.includes('include_router'))
+        pyContents.set(rel, src);
+        if (!hasComposedRoute && NONLITERAL_ROUTE_DECORATOR_RE.test(src))
+            hasComposedRoute = true;
+    }
+    // Single PARSE pass (#2391): parse each `.py` at most once and feed BOTH the
+    // include_router prefix pre-pass and the composed-constant map below. This used
+    // to be two loops, so an include_router file in a composed repo was parsed
+    // twice. A file that needs neither pass is not parsed at all (cost gates intact).
+    //
+    // Cross-file pre-pass: only `include_router` sites need it — they bind a prefix
+    // declared in one file to a router defined in another. Same-file
+    // `APIRouter(prefix=...)` is resolved in scan() from the file's own tree.
+    const constantsByFile = new Map();
+    for (const [rel, src] of pyContents) {
+        const needsRouter = src.includes('include_router');
+        if (!needsRouter && !hasComposedRoute)
             continue;
         parser.setLanguage(Python);
         const tree = parseSource(parser, src);
         if (!tree)
             continue;
-        const localNameToModule = new Map();
-        for (const m of runCompiledPatterns(FROM_IMPORT_ROUTER_PATTERNS, tree)) {
-            const moduleNode = m.captures.module;
-            const aliasNode = m.captures.alias;
-            const importedNode = m.captures.imported;
-            if (!moduleNode || !importedNode)
-                continue;
-            const localName = aliasNode?.text ?? importedNode.text;
-            const moduleShort = lastSegmentOfDotted(moduleNode.text);
-            if (!moduleShort)
-                continue;
-            const moduleLong = lastTwoSegmentsAsLongKey(moduleNode.text);
-            localNameToModule.set(localName, { moduleShort, moduleLong });
-        }
-        // Module-alias map: name imported from a multi-segment package →
-        // long key. Lets Shape A look up the precise file for `<name>.router`
-        // even when `<name>` collides with another package's basename.
-        const localNameToModuleAlias = new Map();
-        for (const m of runCompiledPatterns(FROM_IMPORT_MODULE_PATTERNS, tree)) {
-            const moduleNode = m.captures.module;
-            const importedNode = m.captures.imported;
-            const aliasNode = m.captures.alias;
-            if (!moduleNode || !importedNode)
-                continue;
-            // Skip the `router` shape — already handled by FROM_IMPORT_ROUTER_PATTERNS
-            // above and stored under its router-aware semantics.
-            if (importedNode.text === 'router')
-                continue;
-            const moduleLong = lastTwoSegmentsAsLongKey(`${moduleNode.text}.${importedNode.text}`);
-            if (!moduleLong)
-                continue;
-            const localName = aliasNode?.text ?? importedNode.text;
-            localNameToModuleAlias.set(localName, moduleLong);
-        }
-        // Shape A: `<host>.include_router(<module>.router, prefix='/x')`.
-        // The call site gives us only a short module name. We promote to a
-        // long key when the same file imports `<module>` via either
-        // `from <pkg> import <module>` (recorded in `localNameToModuleAlias`
-        // — the typical pattern) or, less commonly, a router-aware import
-        // statement. Only fall back to the basename short key when neither
-        // alias is available.
-        for (const m of runCompiledPatterns(INCLUDE_ROUTER_ATTR_PATTERNS, tree)) {
-            const modNode = m.captures.router_module;
-            const prefixNode = m.captures.prefix;
-            if (!modNode || !prefixNode)
-                continue;
-            const prefix = unquoteLiteral(prefixNode.text);
-            if (prefix === null)
-                continue;
-            const moduleShort = modNode.text;
-            const aliasLong = localNameToModuleAlias.get(moduleShort);
-            const sameFileImport = localNameToModule.get(moduleShort);
-            const longKey = aliasLong ?? sameFileImport?.moduleLong;
-            if (longKey) {
-                recordPrefix(prefixesByLongKey, longKey, prefix);
+        if (needsRouter) {
+            const localNameToModule = new Map();
+            for (const m of runCompiledPatterns(FROM_IMPORT_ROUTER_PATTERNS, tree)) {
+                const moduleNode = m.captures.module;
+                const aliasNode = m.captures.alias;
+                const importedNode = m.captures.imported;
+                if (!moduleNode || !importedNode)
+                    continue;
+                const localName = aliasNode?.text ?? importedNode.text;
+                const moduleShort = lastSegmentOfDotted(moduleNode.text);
+                if (!moduleShort)
+                    continue;
+                const moduleLong = lastTwoSegmentsAsLongKey(moduleNode.text);
+                localNameToModule.set(localName, { moduleShort, moduleLong });
             }
-            else {
-                recordPrefix(prefixesByShortKey, moduleShort, prefix);
+            // Module-alias map: name imported from a multi-segment package →
+            // long key. Lets Shape A look up the precise file for `<name>.router`
+            // even when `<name>` collides with another package's basename.
+            const localNameToModuleAlias = new Map();
+            for (const m of runCompiledPatterns(FROM_IMPORT_MODULE_PATTERNS, tree)) {
+                const moduleNode = m.captures.module;
+                const importedNode = m.captures.imported;
+                const aliasNode = m.captures.alias;
+                if (!moduleNode || !importedNode)
+                    continue;
+                // Skip the `router` shape — already handled by FROM_IMPORT_ROUTER_PATTERNS
+                // above and stored under its router-aware semantics.
+                if (importedNode.text === 'router')
+                    continue;
+                const moduleLong = lastTwoSegmentsAsLongKey(`${moduleNode.text}.${importedNode.text}`);
+                if (!moduleLong)
+                    continue;
+                const localName = aliasNode?.text ?? importedNode.text;
+                localNameToModuleAlias.set(localName, moduleLong);
             }
-        }
-        // Shape B: `<host>.include_router(my_router, prefix='/x')` — resolve
-        // `my_router` via the import map built above. Whenever the import
-        // statement supplied a multi-segment module path the long key is
-        // recorded, eliminating cross-package collisions.
-        for (const m of runCompiledPatterns(INCLUDE_ROUTER_NAME_PATTERNS, tree)) {
-            const nameNode = m.captures.router_name;
-            const prefixNode = m.captures.prefix;
-            if (!nameNode || !prefixNode)
-                continue;
-            const localImp = localNameToModule.get(nameNode.text);
-            if (!localImp)
-                continue;
-            const prefix = unquoteLiteral(prefixNode.text);
-            if (prefix === null)
-                continue;
-            if (localImp.moduleLong) {
-                recordPrefix(prefixesByLongKey, localImp.moduleLong, prefix);
+            // Shape A: `<host>.include_router(<module>.router, prefix='/x')`.
+            // The call site gives us only a short module name. We promote to a
+            // long key when the same file imports `<module>` via either
+            // `from <pkg> import <module>` (recorded in `localNameToModuleAlias`
+            // — the typical pattern) or, less commonly, a router-aware import
+            // statement. Only fall back to the basename short key when neither
+            // alias is available.
+            for (const m of runCompiledPatterns(INCLUDE_ROUTER_ATTR_PATTERNS, tree)) {
+                const modNode = m.captures.router_module;
+                const prefixNode = m.captures.prefix;
+                if (!modNode || !prefixNode)
+                    continue;
+                const prefix = unquoteLiteral(prefixNode.text);
+                if (prefix === null)
+                    continue;
+                const moduleShort = modNode.text;
+                const aliasLong = localNameToModuleAlias.get(moduleShort);
+                const sameFileImport = localNameToModule.get(moduleShort);
+                const longKey = aliasLong ?? sameFileImport?.moduleLong;
+                if (longKey) {
+                    recordPrefix(prefixesByLongKey, longKey, prefix);
+                }
+                else {
+                    recordPrefix(prefixesByShortKey, moduleShort, prefix);
+                }
             }
-            else {
-                recordPrefix(prefixesByShortKey, localImp.moduleShort, prefix);
+            // Shape B: `<host>.include_router(my_router, prefix='/x')` — resolve
+            // `my_router` via the import map built above. Whenever the import
+            // statement supplied a multi-segment module path the long key is
+            // recorded, eliminating cross-package collisions.
+            for (const m of runCompiledPatterns(INCLUDE_ROUTER_NAME_PATTERNS, tree)) {
+                const nameNode = m.captures.router_name;
+                const prefixNode = m.captures.prefix;
+                if (!nameNode || !prefixNode)
+                    continue;
+                const localImp = localNameToModule.get(nameNode.text);
+                if (!localImp)
+                    continue;
+                const prefix = unquoteLiteral(prefixNode.text);
+                if (prefix === null)
+                    continue;
+                if (localImp.moduleLong) {
+                    recordPrefix(prefixesByLongKey, localImp.moduleLong, prefix);
+                }
+                else {
+                    recordPrefix(prefixesByShortKey, localImp.moduleShort, prefix);
+                }
+            }
+        }
+        // #2391: build the repo-wide constant map for resolving non-literal decorator
+        // paths (KTD6 cost gate: only when `hasComposedRoute`). Parse EVERY `.py` so
+        // the resolvable set matches the ingestion aggregate (R4 parity) — a narrower
+        // set would return null where ingestion resolves.
+        if (hasComposedRoute) {
+            const mc = extractPythonModuleConstants(tree);
+            if (mc.literals.size > 0 || mc.exprs.size > 0 || mc.imports.size > 0) {
+                constantsByFile.set(rel, mc);
             }
         }
     }
     return {
         prefixesByLongKey,
         prefixesByShortKey,
+        constantsByFile,
     };
 }
 function joinPrefix(prefix, route) {
@@ -971,32 +1052,67 @@ export const PYTHON_HTTP_PLUGIN = {
         // statements, so an imperatively-registered handler (Flask `view_func`) that
         // is an imported (possibly aliased) symbol resolves to its real definition.
         const importMap = buildPythonImportMap(tree);
-        // Providers: FastAPI @app.<verb>("/path") — already absolute path.
-        for (const match of runCompiledPatterns(FASTAPI_APP_PATTERNS, tree)) {
-            const methodNode = match.captures.method;
-            const pathNode = match.captures.path;
-            if (!methodNode || !pathNode)
-                continue;
-            const httpMethod = FASTAPI_VERBS[methodNode.text];
-            if (!httpMethod)
-                continue;
-            const path = unquoteLiteral(pathNode.text);
-            if (path === null)
-                continue;
+        // #2391: fold a non-literal decorator argument (bare constant or
+        // `+`-concatenation) to its literal path against the repo constant map, or
+        // `null` → skip (the same floor the ingestion side applies, so provider
+        // contracts and graph Route nodes agree on both resolved and dropped routes).
+        const resolveExprArg = (argNode) => {
+            const cbf = ctx?.constantsByFile;
+            if (!cbf || !fileRel)
+                return null;
+            // Build an operand list and fold via `resolveOperands` — the SAME entry the
+            // ingestion side uses (parse-impl folds `routePathOperands`). Using the
+            // by-name `resolveConstant` here would enter `foldName` one depth shallower,
+            // so at the MAX_RESOLVE_DEPTH boundary the group would resolve a chain
+            // ingestion drops, breaking R4 parity (#2393).
+            const operands = argNode.type === 'identifier'
+                ? [{ kind: 'ref', name: argNode.text }]
+                : parseConstOperands(argNode);
+            return operands ? resolveOperands(fileRel, operands, cbf) : null;
+        };
+        const emitAppProvider = (httpMethod, pathVal, line) => {
             out.push({
                 role: 'provider',
                 framework: 'fastapi',
                 method: httpMethod,
-                path,
+                path: pathVal,
                 name: null,
                 // The decorated handler has no captured name → resolve by line-span
                 // containment. Best-effort fallback: FastAPI routes are graph-backed
                 // (ingestion decorator routes) and the function span starts at `def`
                 // (decorators excluded), so this lands the single-decorator case and
                 // degrades to file-level for multi-decorator stacks.
-                line: pathNode.startPosition.row + 1,
+                line,
                 confidence: 0.8,
             });
+        };
+        // Providers: FastAPI @app.<verb>("/path") — already absolute path.
+        for (const match of runCompiledPatterns(FASTAPI_APP_PATTERNS, tree)) {
+            const methodNode = match.captures.method;
+            const pathNode = match.captures.path;
+            if (!methodNode || !pathNode)
+                continue;
+            const httpMethod = FASTAPI_VERBS[methodNode.text];
+            if (!httpMethod)
+                continue;
+            const path = unquoteLiteral(pathNode.text);
+            if (path === null)
+                continue;
+            emitAppProvider(httpMethod, path, pathNode.startPosition.row + 1);
+        }
+        // Providers: FastAPI @app.<verb>(CONST | A + "/x") — resolved composed path.
+        for (const match of runCompiledPatterns(FASTAPI_APP_EXPR_PATTERNS, tree)) {
+            const methodNode = match.captures.method;
+            const pathNode = match.captures.path;
+            if (!methodNode || !pathNode)
+                continue;
+            const httpMethod = FASTAPI_VERBS[methodNode.text];
+            if (!httpMethod)
+                continue;
+            const resolved = resolveExprArg(pathNode);
+            if (resolved === null)
+                continue; // skip floor
+            emitAppProvider(httpMethod, resolved, pathNode.startPosition.row + 1);
         }
         // Django providers come from the graph Route nodes (includes composed by
         // the ingestion route extractor), not a per-file source scan — see the note
@@ -1020,17 +1136,11 @@ export const PYTHON_HTTP_PLUGIN = {
         // change is strictly additive vs. the prior @app-only behaviour;
         // when the same router is mounted under multiple prefixes we emit
         // one detection per prefix.
-        for (const match of runCompiledPatterns(FASTAPI_ROUTER_PATTERNS, tree)) {
-            const methodNode = match.captures.method;
-            const pathNode = match.captures.path;
-            if (!methodNode || !pathNode)
-                continue;
-            const httpMethod = FASTAPI_VERBS[methodNode.text];
-            if (!httpMethod)
-                continue;
-            const rawPath = unquoteLiteral(pathNode.text);
-            if (rawPath === null)
-                continue;
+        // Join a `@router.<verb>` path with the include_router / APIRouter prefix(es)
+        // that apply to this file and emit one provider detection per prefix. Shared
+        // by the literal and the #2391 non-literal (resolved) router loops so both
+        // stack prefixes identically.
+        const emitRouterProvider = (httpMethod, rawPath, line) => {
             // Long key first (precise, package-aware), short key as fallback.
             // Mirrors the ingestion-side resolution in parse-impl.ts so the
             // graph nodes and group contracts agree on which prefix applies.
@@ -1053,10 +1163,38 @@ export const PYTHON_HTTP_PLUGIN = {
                     path: p,
                     name: null,
                     // Best-effort containment fallback — see the @app provider note above.
-                    line: pathNode.startPosition.row + 1,
+                    line,
                     confidence: 0.8,
                 });
             }
+        };
+        for (const match of runCompiledPatterns(FASTAPI_ROUTER_PATTERNS, tree)) {
+            const methodNode = match.captures.method;
+            const pathNode = match.captures.path;
+            if (!methodNode || !pathNode)
+                continue;
+            const httpMethod = FASTAPI_VERBS[methodNode.text];
+            if (!httpMethod)
+                continue;
+            const rawPath = unquoteLiteral(pathNode.text);
+            if (rawPath === null)
+                continue;
+            emitRouterProvider(httpMethod, rawPath, pathNode.startPosition.row + 1);
+        }
+        // Providers: FastAPI @router.<verb>(CONST | A + "/x") — resolved composed path
+        // (#2391). Null resolution → skip, so provider/graph parity holds.
+        for (const match of runCompiledPatterns(FASTAPI_ROUTER_EXPR_PATTERNS, tree)) {
+            const methodNode = match.captures.method;
+            const pathNode = match.captures.path;
+            if (!methodNode || !pathNode)
+                continue;
+            const httpMethod = FASTAPI_VERBS[methodNode.text];
+            if (!httpMethod)
+                continue;
+            const resolved = resolveExprArg(pathNode);
+            if (resolved === null)
+                continue;
+            emitRouterProvider(httpMethod, resolved, pathNode.startPosition.row + 1);
         }
         // Providers: Flask `app.add_url_rule('/path', view_func=handler, methods=[…])`.
         // The handler is a `view_func` identifier, frequently an imported (possibly

package/dist/core/ingestion/parsing-processor.d.ts

@@ -3,7 +3,7 @@ import type { SymbolTableWriter } from './model/index.js';
 import { type ExportedTypeMap } from './call-processor.js';
 import type { ParsedFile } from '../../_shared/index.js';
 import { WorkerPool } from './workers/worker-pool.js';
-import type { ParseWorkerResult, ExtractedRoute, ExtractedFetchCall, ExtractedDecoratorRoute, ExtractedToolDef, FileScopeBindings, ExtractedORMQuery, FetchWrapperDef } from './workers/parse-worker.js';
+import type { ParseWorkerResult, ExtractedRoute, ExtractedFetchCall, ExtractedDecoratorRoute, ExtractedModuleConstants, ExtractedToolDef, FileScopeBindings, ExtractedORMQuery, FetchWrapperDef } from './workers/parse-worker.js';
 import type { ExtractedRouterConstructorPrefix, ExtractedRouterImport, ExtractedRouterInclude, ExtractedRouterModuleAlias } from './route-extractors/fastapi-router-bindings.js';
 import type { SharedSpringType } from './route-extractors/spring-shared.js';
 export type FileProgressCallback = (current: number, total: number, filePath: string) => void;
@@ -16,6 +16,8 @@ export interface WorkerExtractedData {
     routerImports: ExtractedRouterImport[];
     routerConstructorPrefixes: ExtractedRouterConstructorPrefix[];
     routerModuleAliases: ExtractedRouterModuleAlias[];
+    /** Per-file Python module constants for cross-file route-path resolution (#2391). */
+    moduleConstants: ExtractedModuleConstants[];
     toolDefs: ExtractedToolDef[];
     ormQueries: ExtractedORMQuery[];
     /** Project-wide Spring class/interface views for the #2288 inheritance pass. */

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

@@ -24,6 +24,7 @@ export const mergeChunkResults = (graph, symbolTable, chunkResults, exportedType
     const allRouterImports = [];
     const allRouterConstructorPrefixes = [];
     const allRouterModuleAliases = [];
+    const allModuleConstants = [];
     const allSpringTypes = [];
     const allToolDefs = [];
     const allORMQueries = [];
@@ -76,6 +77,8 @@ export const mergeChunkResults = (graph, symbolTable, chunkResults, exportedType
         }
         for (const item of result.routerModuleAliases ?? [])
             allRouterModuleAliases.push(item);
+        for (const item of result.moduleConstants ?? [])
+            allModuleConstants.push(item);
         for (const item of result.springTypes ?? [])
             allSpringTypes.push(item);
         for (const item of result.toolDefs)
@@ -99,6 +102,7 @@ export const mergeChunkResults = (graph, symbolTable, chunkResults, exportedType
         routerImports: allRouterImports,
         routerConstructorPrefixes: allRouterConstructorPrefixes,
         routerModuleAliases: allRouterModuleAliases,
+        moduleConstants: allModuleConstants,
         toolDefs: allToolDefs,
         ormQueries: allORMQueries,
         springTypes: allSpringTypes,

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

@@ -28,6 +28,7 @@ import { parseSourceSafe } from '../../tree-sitter/safe-parse.js';
 import { getProvider, providers } from '../languages/index.js';
 import { createWorkerPool, workerPoolDisabledByEnv, resolveAutoPoolSize, WorkerPoolInitializationError, WorkerPoolDisabledError, } from '../workers/worker-pool.js';
 import { normalizeExtractedRoutePath } from '../route-extractors/route-path.js';
+import { resolveOperands, } from '../route-extractors/python-const-resolver.js';
 import { resolveInheritedSpringRoutes, } from '../route-extractors/spring-shared.js';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -464,6 +465,9 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     const allRouterImports = [];
     const allRouterConstructorPrefixes = [];
     const allRouterModuleAliases = [];
+    // Per-file Python module constants (#2391); resolved into decorator route paths
+    // below, after cross-file aggregation, alongside the include_router prefix pass.
+    const allModuleConstants = [];
     const allSpringTypes = [];
     const allToolDefs = [];
     const allORMQueries = [];
@@ -610,6 +614,10 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                     for (const item of chunkWorkerData.routerModuleAliases)
                         allRouterModuleAliases.push(item);
                 }
+                if (chunkWorkerData.moduleConstants?.length) {
+                    for (const item of chunkWorkerData.moduleConstants)
+                        allModuleConstants.push(item);
+                }
                 if (chunkWorkerData.springTypes?.length) {
                     for (const item of chunkWorkerData.springTypes)
                         allSpringTypes.push(item);
@@ -925,6 +933,40 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     }
     // FastAPI router-prefix resolution (cross-file).
     //
+    // #2391: resolve non-literal FastAPI decorator route paths (imported/composed
+    // string constants) BEFORE the include_router/APIRouter prefix pass below, so a
+    // resolved path is then prefix-joined like any literal path. Each such route
+    // carries `routePathExpr`/`routePathOperands` and an empty `routePath`; we fold
+    // the operands against the repo-wide, file-path-keyed constant map. On failure
+    // we DROP the route (KTD5 skip floor) rather than emit a phantom `POST /`.
+    if (allDecoratorRoutes.some((dr) => dr.routePathExpr !== undefined)) {
+        const repoConstants = new Map();
+        for (const { filePath, constants } of allModuleConstants) {
+            repoConstants.set(filePath, constants);
+        }
+        const resolvedRoutes = [];
+        let skipped = 0;
+        for (const dr of allDecoratorRoutes) {
+            if (dr.routePathExpr === undefined) {
+                resolvedRoutes.push(dr);
+                continue;
+            }
+            const value = dr.routePathOperands
+                ? resolveOperands(dr.filePath, dr.routePathOperands, repoConstants)
+                : null;
+            if (value === null) {
+                skipped++;
+                continue;
+            }
+            resolvedRoutes.push({ ...dr, routePath: value });
+        }
+        allDecoratorRoutes.length = 0;
+        for (const dr of resolvedRoutes)
+            allDecoratorRoutes.push(dr);
+        if (isDev && skipped > 0) {
+            logger.info(`  🧩 Resolved composed route constants; ${skipped} unresolved route(s) skipped`);
+        }
+    }
     // Workers emit two kinds of records per Python file:
     //   • `routerIncludes` — every `app.include_router(<routerExpr>, prefix='/x')`
     //     site, where `routerExpr` is either `<module>.router` (Shape A) or a

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

@@ -0,0 +1,83 @@
+/**
+ * Language-agnostic string-constant folding for route-path resolution (#2391).
+ *
+ * Route decorators/annotations frequently build their path from a constant rather
+ * than a string literal — `@router.post(API_V1_WIDGETS_GET)` (Python),
+ * `@GetMapping(PathConstants.WIDGETS)` (Spring), and the Kotlin/C# equivalents are
+ * the same shape. This module folds such a constant — or an inline
+ * `+`-concatenation — to its literal value, following `+` operands and import
+ * chains across a repo-wide, file-keyed constant map.
+ *
+ * The FOLD is language-neutral: it walks {@link Operand} lists and
+ * {@link ModuleConstants} that ANY language's extractor can produce, and defers
+ * the one language-specific decision — mapping an import specifier to the file it
+ * refers to — to a caller-supplied {@link ImportResolver}. A language binding
+ * (e.g. `python-const-resolver.ts`) provides that resolver plus a tree →
+ * {@link ModuleConstants} extractor and, if wanted, thin pre-bound wrappers.
+ *
+ * This mirrors how `route-path.ts` (URL normalization) and `spring-shared.ts`
+ * (annotation primitives) are shared across the ingestion and group layers and
+ * across languages: the reusable core lives in one place; per-language semantics
+ * plug in. It deliberately does NOT reuse `ScopeResolver` (which resolves symbol
+ * IDENTITIES, not literal string VALUES) or the `--pdg` `REACHING_DEF` layer
+ * (intra-procedural, function-local, def→use reachability — not module-level
+ * cross-file value folding).
+ */
+/**
+ * One term of a constant's right-hand side. A `+`-concatenation
+ * (`A + "/b" + C`) becomes an ordered `Operand[]`; a bare literal is a
+ * single-element list.
+ */
+export type Operand = {
+    readonly kind: 'literal';
+    readonly value: string;
+} | {
+    readonly kind: 'ref';
+    readonly name: string;
+};
+/**
+ * A `from <module> import <name> [as <local>]` (or the language's equivalent)
+ * binding. `module` is the import specifier as written (e.g. `.constants`,
+ * `..pkg.constants`, `api.constants`) so the {@link ImportResolver} can apply
+ * language-specific rules; `originalName` is the exported name in the target
+ * module (pre-alias). The map key is the local (in-file) name.
+ */
+export interface ImportBinding {
+    readonly module: string;
+    readonly originalName: string;
+}
+/**
+ * String-valued module-level constants of one source file. `literals` are
+ * fully-resolved (`X = "/a"`); `exprs` are unresolved operand lists
+ * (`X = A + "/b"`); `imports` maps a local name to the module it was imported
+ * from. All string keys are the in-file (local) names.
+ */
+export interface ModuleConstants {
+    readonly literals: Map<string, string>;
+    readonly exprs: Map<string, readonly Operand[]>;
+    readonly imports: Map<string, ImportBinding>;
+}
+/** Repo-wide map: unique file key (e.g. `app/constants.py`) → that file's
+ * {@link ModuleConstants}. */
+export type RepoConstants = ReadonlyMap<string, ModuleConstants>;
+/**
+ * Resolve an import specifier (as written) from `importingFileKey` to the unique
+ * repo file key it refers to, or `null` when it cannot be pinned to exactly one
+ * file. This is the sole language-specific dependency of the fold: Python uses
+ * leading-dot relative imports + `.py`-suffix rules; a JVM binding would use
+ * package/classpath rules. Returning `null` on ambiguity keeps the fold honest —
+ * an unresolvable or ambiguous import floors to skip, never a wrong path.
+ */
+export type ImportResolver = (importingFileKey: string, moduleSpec: string, repoKeys: ReadonlySet<string>) => string | null;
+/**
+ * Resolve a single named constant referenced in `fileKey` to its literal string
+ * value, folding `+` concatenation and following import chains via
+ * `resolveImport`, or `null` when it cannot be fully folded.
+ */
+export declare function resolveConstant(fileKey: string, name: string, repo: RepoConstants, resolveImport: ImportResolver): string | null;
+/**
+ * Resolve an inline operand list (an unnamed `+`-expression captured directly at
+ * a decorator/annotation argument, e.g. `@router.get(API_V1 + "/widgets")`)
+ * against `fileKey`.
+ */
+export declare function resolveOperands(fileKey: string, operands: readonly Operand[], repo: RepoConstants, resolveImport: ImportResolver): string | null;