gitnexus 1.6.10-rc.7 → 1.6.10-rc.9

package/README.md

@@ -535,17 +535,26 @@ After scope resolution, analyze prunes inert block-local value symbols (a functi
 
 Programmatic callers can pass `keepLocalValueSymbols: true` in `PipelineOptions` instead of setting the env var.
 
-### Hook augmentation/notifications are silently skipped
+### Hook augmentation and skip diagnostics
 
-The Claude Code / Antigravity hooks intentionally stay **silent** on normal skip
+The Claude Code / Antigravity hooks keep their **stderr** silent on normal skip
 paths so strict hook runners (e.g. Codex `PreToolUse`) never see unexpected
-output. A search may not be augmented — or a stale-index reminder may not appear
-on stderr — when the GitNexus MCP server owns the repo DB, when the DB-lock probe
-times out and fails closed, or when the index is already current.
-
-To see why a hook skipped, set `GITNEXUS_DEBUG=1` and re-run the action — the hook
-writes the reason (e.g. `[GitNexus] augment skipped: MCP server owns DB`) and the
-stale-index hint to its stderr:
+diagnostic output.
+
+When a GitNexus process holds the repo DB write lock (the common case — the MCP
+server is running, or the DB-lock probe timed out and failed closed), the local
+CLI `augment` can't run (LadybugDB is single-writer). Rather than drop the
+augmentation, the hook hands the agent a short, conditional MCP-query hint on
+stdout (the sanctioned `additionalContext` channel) — _"if the GitNexus MCP tools
+are live in this session, call `query` …"_ — so an agent that has the tools can
+still fetch graph-ranked context. The hint is throttled to at most once per repo
+per window (`GITNEXUS_MCP_HINT_THROTTLE_MS`, default 10 min; `0` disables), so an
+owner-locked session isn't nudged on every search. A stale-index reminder, or an
+already-current index, stays silent.
+
+To see why a hook skipped the CLI augment, set `GITNEXUS_DEBUG=1` and re-run the
+action — the hook writes the reason (e.g. `[GitNexus] augment skipped: MCP server
+owns DB`) and the stale-index hint to its stderr:
 
 ```bash
 GITNEXUS_DEBUG=1 <your command>   # surfaces hook skip/diagnostic reasons on stderr

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