gitnexus 1.6.13-rc.56 → 1.6.13-rc.57

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

@@ -1,6 +1,8 @@
 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 { extractFastAPIRouterBindings, } from '../../../ingestion/route-extractors/fastapi-router-bindings.js';
+import { mergeMountPrefixes, resolveFastAPIRouterPrefixes, } from '../../../ingestion/route-extractors/fastapi-router-prefixes.js';
 import { extractPythonModuleConstants, parseConstOperands, resolveOperands, } from '../../../ingestion/route-extractors/python-const-resolver.js';
 /**
  * Python HTTP plugin. Handles:
@@ -883,6 +885,10 @@ const NONLITERAL_ROUTE_DECORATOR_RE = /@\s*(?:app|router)\s*\.\s*(?:get|post|put
 function buildPythonRepoContext(files, parser, readFile, parseSource) {
     const prefixesByLongKey = new Map();
     const prefixesByShortKey = new Map();
+    const routerIncludes = [];
+    const routerImports = [];
+    const routerModuleAliases = [];
+    const routerConstructorPrefixes = [];
     // 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
@@ -900,6 +906,15 @@ function buildPythonRepoContext(files, parser, readFile, parseSource) {
         if (!hasComposedRoute && NONLITERAL_ROUTE_DECORATOR_RE.test(src))
             hasComposedRoute = true;
     }
+    for (const [rel, src] of pyContents) {
+        if (src.includes('include_router')) {
+            extractFastAPIRouterBindings(rel, src, routerIncludes, routerImports, routerModuleAliases, routerConstructorPrefixes);
+        }
+    }
+    // Resolve against every repo path, empty files included, so module
+    // ambiguity matches ingestion (which passes all scanned paths).
+    const { prefixesByFile, resolvedIncludes } = resolveFastAPIRouterPrefixes(files, routerIncludes, routerImports, routerModuleAliases, routerConstructorPrefixes);
+    const resolvedIncludeKeys = new Set([...resolvedIncludes].map((inc) => JSON.stringify([inc.filePath, inc.routerExpr, inc.prefix])));
     // 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
@@ -968,6 +983,8 @@ function buildPythonRepoContext(files, parser, readFile, parseSource) {
                 if (prefix === null)
                     continue;
                 const moduleShort = modNode.text;
+                if (resolvedIncludeKeys.has(JSON.stringify([rel, `${moduleShort}.router`, prefix])))
+                    continue;
                 const aliasLong = localNameToModuleAlias.get(moduleShort);
                 const sameFileImport = localNameToModule.get(moduleShort);
                 const longKey = aliasLong ?? sameFileImport?.moduleLong;
@@ -993,6 +1010,8 @@ function buildPythonRepoContext(files, parser, readFile, parseSource) {
                 const prefix = unquoteLiteral(prefixNode.text);
                 if (prefix === null)
                     continue;
+                if (resolvedIncludeKeys.has(JSON.stringify([rel, nameNode.text, prefix])))
+                    continue;
                 if (localImp.moduleLong) {
                     recordPrefix(prefixesByLongKey, localImp.moduleLong, prefix);
                 }
@@ -1013,6 +1032,7 @@ function buildPythonRepoContext(files, parser, readFile, parseSource) {
         }
     }
     return {
+        prefixesByFile,
         prefixesByLongKey,
         prefixesByShortKey,
         constantsByFile,
@@ -1145,14 +1165,13 @@ export const PYTHON_HTTP_PLUGIN = {
         // 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.
+            // Exact file matches plus the legacy long/short fallback. This mirrors
+            // ingestion so graph Route nodes and contracts agree on mounted paths.
             const longKey = fileRel ? fileLongKey(fileRel) : '';
             const longPrefixes = longKey ? ctx?.prefixesByLongKey.get(longKey) : undefined;
             const shortKey = fileRel ? fileShortKey(fileRel) : '';
             const shortPrefixes = longPrefixes || !shortKey ? undefined : ctx?.prefixesByShortKey.get(shortKey);
-            const prefixSet = longPrefixes ?? shortPrefixes;
+            const prefixSet = mergeMountPrefixes(fileRel ? ctx?.prefixesByFile.get(fileRel.replace(/\\/g, '/')) : undefined, longPrefixes ?? shortPrefixes);
             // Stack the same-file APIRouter(prefix=...) under any cross-file
             // include_router prefix.
             const localPath = constructorPrefix ? joinPrefix(constructorPrefix, rawPath) : rawPath;

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

@@ -30,6 +30,7 @@ import { classifyContentLanguages } from '../content-language-classification.js'
 import { SCOPE_RESOLVERS } from '../scope-resolution/pipeline/registry.js';
 import { DATA_ROUTE_TABLE_SOURCE } from '../route-extractors/data-route-table.js';
 import { createWorkerPool, workerPoolDisabledByEnv, resolveAutoPoolSize, envWorkerPoolSize, resolveHostParallelism, WorkerPoolInitializationError, WorkerPoolDisabledError, } from '../workers/worker-pool.js';
+import { mergeMountPrefixes, resolveFastAPIRouterPrefixes, } from '../route-extractors/fastapi-router-prefixes.js';
 import { normalizeExtractedRoutePath } from '../route-extractors/route-path.js';
 import { resolveOperands } from '../route-extractors/python-const-resolver.js';
 import { prepareRouteConstantsByProvider } from '../language-provider.js';
@@ -1326,11 +1327,9 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
             }
             m.set(alias.localName, alias.moduleKeyLong);
         }
-        // Two parallel maps: long-key (precise) and short-key (basename
-        // fallback). Long-key entries are preferred when the file's own long
-        // key matches; short-key entries match any file with that basename and
-        // remain the fallback when no long key is known (e.g. Shape A includes
-        // without a corresponding import statement).
+        // Exact-file matches handle import-resolved mounts (including nested
+        // routers). These long/short maps preserve the older fallback for mounts
+        // whose import cannot be resolved to one file.
         const prefixesByLongKey = new Map();
         const prefixesByShortKey = new Map();
         // Constructor prefixes are `router`-only (the apply gate below and the
@@ -1338,6 +1337,7 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         // flat file-key → prefix map suffices — mirrors the group layer's shape.
         const constructorPrefixesByLongKey = new Map();
         const constructorPrefixesByShortKey = new Map();
+        const { prefixesByFile, resolvedIncludes } = resolveFastAPIRouterPrefixes(allPaths, allRouterIncludes, allRouterImports, allRouterModuleAliases, allRouterConstructorPrefixes);
         const recordPrefix = (target, key, prefix) => {
             let set = target.get(key);
             if (!set) {
@@ -1347,6 +1347,10 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
             set.add(prefix);
         };
         for (const inc of allRouterIncludes) {
+            // Unprefixed includes only exist as propagation edges; recording `''`
+            // here would shadow a real short-key prefix for the same module.
+            if (resolvedIncludes.has(inc) || !inc.prefix)
+                continue;
             // Shape A: `<module>.router`. The worker emits `routerExpr` already
             // including `.router`, so split it back. We only know a short module
             // key here — the call site doesn't carry the dotted package path. If
@@ -1377,7 +1381,8 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                 recordPrefix(prefixesByShortKey, localImp.moduleKey, inc.prefix);
             }
         }
-        if (prefixesByLongKey.size > 0 ||
+        if (prefixesByFile.size > 0 ||
+            prefixesByLongKey.size > 0 ||
             prefixesByShortKey.size > 0 ||
             allRouterConstructorPrefixes.length > 0) {
             const fileLongKey = (rel) => {
@@ -1415,15 +1420,14 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                     expanded.push(dr);
                     continue;
                 }
-                // Long-key lookup first; only fall back to the short key when no
-                // long-key prefix targets this file. This avoids prefix leakage
-                // between e.g. `api/users.py` and `admin/users.py`.
+                // Exact file matches plus the legacy long/short fallback for mounts
+                // whose import could not be resolved.
                 const longKey = fileLongKey(dr.filePath);
                 const longPrefixes = longKey ? prefixesByLongKey.get(longKey) : undefined;
                 const shortPrefixes = longPrefixes
                     ? undefined
                     : prefixesByShortKey.get(fileShortKey(dr.filePath));
-                const prefixes = longPrefixes ?? shortPrefixes;
+                const prefixes = mergeMountPrefixes(prefixesByFile.get(dr.filePath.replace(/\\/g, '/')), longPrefixes ?? shortPrefixes);
                 // Constructor prefixes are keyed like include_router prefixes:
                 // long-key entries are precise, while short-key entries are only
                 // valid for repo-root/single-segment files where `fileLongKey`

package/dist/core/ingestion/route-extractors/fastapi-router-bindings.d.ts

@@ -13,17 +13,19 @@
  * extraction here lets unit tests import the function directly without
  * booting a worker, satisfying DoD §2.7.
  *
- * Worker phase is per-file, so the heavy cross-file resolution lives in
- * `pipeline-phases/parse-impl.ts`. Here we only extract two raw record
+ * Worker phase is per-file, so the cross-file resolution lives in
+ * `fastapi-router-prefixes.ts` and `pipeline-phases/parse-impl.ts`. Here we extract raw record
  * kinds and let the pipeline aggregate them across files:
  *
  *   • {@link ExtractedRouterInclude} — every
- *     `<host>.include_router(<routerExpr>, prefix='/x')` site, where
- *     `<routerExpr>` is either `<module>.router` (Shape A) or a bare
- *     local name (Shape B). `<host>` is intentionally unconstrained:
- *     production code uses `app`, `api`, `application`, `asgi_app`,
- *     etc., and the call shape (`include_router` invoked with a
- *     `prefix=` keyword) is specific enough on its own.
+ *     `<host>.include_router(<routerExpr>, prefix='/x')` mount, plus
+ *     unprefixed `<host>.include_router(<routerExpr>[, <other kwargs>])`
+ *     calls recorded with `prefix: ''`. `<routerExpr>` is either
+ *     `<module>.router` (Shape A) or a bare local name (Shape B). The
+ *     extractor leaves `<host>` unconstrained (production code uses `app`,
+ *     `api`, `application`, `asgi_app`, …); unprefixed records are only
+ *     propagation edges, and `fastapi-router-prefixes.ts` passes a parent
+ *     prefix through them only when the host is `router`.
  *
  *   • {@link ExtractedRouterImport} — every
  *     `from <module> import router [as <alias>]`, captured for both
@@ -37,25 +39,25 @@
  *   • short key — basename without `.py`                  (`users`)
  *   • long  key — `<parent-dir>/<basename>`               (`api/users`)
  *
- * Imports always carry the short key and, when the module path was
- * multi-segment, also the long key. parse-impl matches against the
- * long key first and falls back to the short key, so cross-package
- * collisions are eliminated for Shape B and minimised for Shape A.
+ * Imports retain their module path for exact-file resolution. The short and
+ * long keys remain for the conservative fallback when that resolution fails.
  *
  * The functions in this module are pure (no Worker / parentPort
  * dependency) so they can be unit-tested directly without booting a
  * worker thread.
  */
 /**
- * One `<host>.include_router(<routerExpr>, prefix='/x')` site.
+ * One `<host>.include_router(<routerExpr>, prefix='/x')` site, or a
+ * simple child include without a local prefix.
  *
  * `routerExpr` is the raw text of the first argument — either
  * `<module>.router` (Shape A) or a bare local name (Shape B).
- * parse-impl resolves Shape B against {@link ExtractedRouterImport}
- * records emitted by the same file.
+ * Cross-file resolution uses {@link ExtractedRouterImport} records
+ * emitted by the same file.
  */
 export interface ExtractedRouterInclude {
     filePath: string;
+    host: string;
     routerExpr: string;
     prefix: string;
     lineNumber: number;
@@ -76,6 +78,7 @@ export interface ExtractedRouterInclude {
 export interface ExtractedRouterImport {
     filePath: string;
     localName: string;
+    modulePath: string;
     moduleKey: string;
     moduleKeyLong?: string;
 }
@@ -98,6 +101,7 @@ export interface ExtractedRouterModuleAlias {
     filePath: string;
     /** Local name in the importing file (== imported name or its alias). */
     localName: string;
+    modulePath: string;
     /** Long key (`<parent>/<stem>`) — non-empty for every emitted record. */
     moduleKeyLong: string;
 }

package/dist/core/ingestion/route-extractors/fastapi-router-bindings.js

@@ -13,17 +13,19 @@
  * extraction here lets unit tests import the function directly without
  * booting a worker, satisfying DoD §2.7.
  *
- * Worker phase is per-file, so the heavy cross-file resolution lives in
- * `pipeline-phases/parse-impl.ts`. Here we only extract two raw record
+ * Worker phase is per-file, so the cross-file resolution lives in
+ * `fastapi-router-prefixes.ts` and `pipeline-phases/parse-impl.ts`. Here we extract raw record
  * kinds and let the pipeline aggregate them across files:
  *
  *   • {@link ExtractedRouterInclude} — every
- *     `<host>.include_router(<routerExpr>, prefix='/x')` site, where
- *     `<routerExpr>` is either `<module>.router` (Shape A) or a bare
- *     local name (Shape B). `<host>` is intentionally unconstrained:
- *     production code uses `app`, `api`, `application`, `asgi_app`,
- *     etc., and the call shape (`include_router` invoked with a
- *     `prefix=` keyword) is specific enough on its own.
+ *     `<host>.include_router(<routerExpr>, prefix='/x')` mount, plus
+ *     unprefixed `<host>.include_router(<routerExpr>[, <other kwargs>])`
+ *     calls recorded with `prefix: ''`. `<routerExpr>` is either
+ *     `<module>.router` (Shape A) or a bare local name (Shape B). The
+ *     extractor leaves `<host>` unconstrained (production code uses `app`,
+ *     `api`, `application`, `asgi_app`, …); unprefixed records are only
+ *     propagation edges, and `fastapi-router-prefixes.ts` passes a parent
+ *     prefix through them only when the host is `router`.
  *
  *   • {@link ExtractedRouterImport} — every
  *     `from <module> import router [as <alias>]`, captured for both
@@ -37,10 +39,8 @@
  *   • short key — basename without `.py`                  (`users`)
  *   • long  key — `<parent-dir>/<basename>`               (`api/users`)
  *
- * Imports always carry the short key and, when the module path was
- * multi-segment, also the long key. parse-impl matches against the
- * long key first and falls back to the short key, so cross-package
- * collisions are eliminated for Shape B and minimised for Shape A.
+ * Imports retain their module path for exact-file resolution. The short and
+ * long keys remain for the conservative fallback when that resolution fails.
  *
  * The functions in this module are pure (no Worker / parentPort
  * dependency) so they can be unit-tested directly without booting a
@@ -49,10 +49,18 @@
 // `<host>.include_router(<module>.router, ..., prefix='/x')` (Shape A).
 // `<host>` is left unrestricted — common production names include
 // `app`, `api`, `application`, `asgi_app`. Pinning to the literal
-// `app` would silently drop these.
-const INCLUDE_ROUTER_ATTR_RE = /\b(?:[A-Za-z_][\w.]*)\.include_router\s*\(\s*([A-Za-z_][\w]*)\.router\b[^)]*?\bprefix\s*=\s*(['"])([^'"]*)\2/g;
+// `app` would silently drop these. Arguments before `prefix=` may hold one
+// level of nested calls (`dependencies=[Depends(auth)]`); the two
+// alternatives start on disjoint characters, so matching stays linear.
+const INCLUDE_ROUTER_ATTR_RE = /\b([A-Za-z_][\w.]*)\.include_router\s*\(\s*([A-Za-z_][\w]*)\.router\b(?:[^()]|\([^()]*\))*?\bprefix\s*=\s*(['"])([^'"]*)\3/g;
 // `<host>.include_router(<local_name>, ..., prefix='/x')` (Shape B).
-const INCLUDE_ROUTER_NAME_RE = /\b(?:[A-Za-z_][\w.]*)\.include_router\s*\(\s*([A-Za-z_][\w]*)\b[^)]*?\bprefix\s*=\s*(['"])([^'"]*)\2/g;
+const INCLUDE_ROUTER_NAME_RE = /\b([A-Za-z_][\w.]*)\.include_router\s*\(\s*([A-Za-z_][\w]*)\b(?:[^()]|\([^()]*\))*?\bprefix\s*=\s*(['"])([^'"]*)\3/g;
+// A child router may be included without a local prefix and inherit the
+// prefix of its parent router when that parent is mounted elsewhere. Other
+// keyword arguments (with one level of nested calls, like the prefixed
+// patterns) and a trailing comma are allowed; a `prefix=` anywhere in the
+// call declines the match so it never double-fires with those patterns.
+const INCLUDE_ROUTER_UNPREFIXED_RE = /\b([A-Za-z_][\w.]*)\.include_router\s*\(\s*([A-Za-z_]\w*(?:\.router)?)\s*(?:,(?!(?:[^()]|\([^()]*\))*?\bprefix\s*=)(?:[^()]|\([^()]*\))*)?\)/g;
 // Module path: a sequence of dots (`.`, `..`, `...`) for "current
 // package" imports, OR an optional leading-dot prefix followed by a
 // dotted identifier (`api.users`, `.api.users`, `..siblings.users`).
@@ -175,6 +183,7 @@ export function extractFastAPIRouterBindings(filePath, content, outIncludes, out
                     outImports.push({
                         filePath,
                         localName,
+                        modulePath: moduleText,
                         moduleKey: moduleShort,
                         ...(moduleLong ? { moduleKeyLong: moduleLong } : {}),
                     });
@@ -199,6 +208,7 @@ export function extractFastAPIRouterBindings(filePath, content, outIncludes, out
                 outModuleAliases.push({
                     filePath,
                     localName,
+                    modulePath: `${moduleText}.${importedName}`,
                     moduleKeyLong: aliasLong,
                 });
             }
@@ -231,8 +241,9 @@ export function extractFastAPIRouterBindings(filePath, content, outIncludes, out
     while ((m = INCLUDE_ROUTER_ATTR_RE.exec(content)) !== null) {
         outIncludes.push({
             filePath,
-            routerExpr: `${m[1]}.router`,
-            prefix: m[3],
+            host: m[1],
+            routerExpr: `${m[2]}.router`,
+            prefix: m[4],
             lineNumber: content.substring(0, m.index).split('\n').length,
         });
     }
@@ -245,14 +256,25 @@ export function extractFastAPIRouterBindings(filePath, content, outIncludes, out
         // is intentionally permissive and would re-capture `<mod>.router`
         // as the bare name `mod`. Discriminate by re-checking the
         // immediate source around the captured argument position.
-        const argStart = m.index + m[0].indexOf(m[1]);
-        const dotProbe = content.slice(argStart + m[1].length, argStart + m[1].length + 8);
+        const argStart = m.index + m[0].indexOf(m[2], m[0].indexOf('(') + 1);
+        const dotProbe = content.slice(argStart + m[2].length, argStart + m[2].length + 8);
         if (/^\s*\.\s*router/.test(dotProbe))
             continue;
         outIncludes.push({
             filePath,
-            routerExpr: m[1],
-            prefix: m[3],
+            host: m[1],
+            routerExpr: m[2],
+            prefix: m[4],
+            lineNumber: content.substring(0, m.index).split('\n').length,
+        });
+    }
+    INCLUDE_ROUTER_UNPREFIXED_RE.lastIndex = 0;
+    while ((m = INCLUDE_ROUTER_UNPREFIXED_RE.exec(content)) !== null) {
+        outIncludes.push({
+            filePath,
+            host: m[1],
+            routerExpr: m[2],
+            prefix: '',
             lineNumber: content.substring(0, m.index).split('\n').length,
         });
     }

package/dist/core/ingestion/route-extractors/fastapi-router-prefixes.d.ts

@@ -0,0 +1,21 @@
+import type { ExtractedRouterConstructorPrefix, ExtractedRouterImport, ExtractedRouterInclude, ExtractedRouterModuleAlias } from './fastapi-router-bindings.js';
+export interface ResolvedFastAPIRouterPrefixes {
+    prefixesByFile: Map<string, Set<string>>;
+    resolvedIncludes: Set<ExtractedRouterInclude>;
+}
+/**
+ * Prefixes that apply to one router file: exact import-resolved mounts plus
+ * the legacy long/short-key prefixes of mounts the resolver could not bind.
+ * Shared by ingestion and the group extractor so both surfaces agree.
+ */
+export declare function mergeMountPrefixes(exact: ReadonlySet<string> | undefined, legacy: ReadonlySet<string> | undefined): ReadonlySet<string> | undefined;
+/**
+ * Carry mounted prefixes through exact, import-resolved router includes.
+ *
+ * Only a host literally named `router` passes its mounted prefix on to the
+ * routers it includes, and resolution is per file rather than per variable:
+ * `api_router = APIRouter(); api_router.include_router(x.router)` does not
+ * pass through, and a prefixed `api_router.include_router(...)` is treated
+ * as a root mount. Unprefixed includes from any other host are ignored.
+ */
+export declare function resolveFastAPIRouterPrefixes(files: Iterable<string>, includes: readonly ExtractedRouterInclude[], imports: readonly ExtractedRouterImport[], moduleAliases: readonly ExtractedRouterModuleAlias[], constructorPrefixes?: readonly ExtractedRouterConstructorPrefix[]): ResolvedFastAPIRouterPrefixes;

package/dist/core/ingestion/route-extractors/fastapi-router-prefixes.js

@@ -0,0 +1,153 @@
+import { normalizeExtractedRoutePath } from './route-path.js';
+/** Resolve only imports that identify one Python file in this repository. */
+function resolveModuleFile(importer, modulePath, files, absoluteModules) {
+    const leadingDots = /^\.+/.exec(modulePath)?.[0].length ?? 0;
+    const dotted = modulePath.slice(leadingDots);
+    if (!dotted)
+        return undefined;
+    const moduleSegments = dotted.split('.');
+    if (!moduleSegments.every((part) => /^[A-Za-z_]\w*$/.test(part)))
+        return undefined;
+    let stem;
+    if (leadingDots > 0) {
+        const directory = importer.replace(/\\/g, '/').split('/').slice(0, -1);
+        const parentLevels = leadingDots - 1;
+        if (parentLevels > directory.length)
+            return undefined;
+        stem = [...directory.slice(0, directory.length - parentLevels), ...moduleSegments].join('/');
+    }
+    else {
+        stem = moduleSegments.join('/');
+    }
+    if (leadingDots === 0)
+        return absoluteModules.get(stem) ?? undefined;
+    const candidates = [`${stem}.py`, `${stem}/__init__.py`].filter((candidate) => files.has(candidate));
+    return candidates.length === 1 ? candidates[0] : undefined;
+}
+/**
+ * Prefixes that apply to one router file: exact import-resolved mounts plus
+ * the legacy long/short-key prefixes of mounts the resolver could not bind.
+ * Shared by ingestion and the group extractor so both surfaces agree.
+ */
+export function mergeMountPrefixes(exact, legacy) {
+    if (!exact)
+        return legacy;
+    if (!legacy)
+        return exact;
+    return new Set([...exact, ...legacy]);
+}
+/**
+ * Carry mounted prefixes through exact, import-resolved router includes.
+ *
+ * Only a host literally named `router` passes its mounted prefix on to the
+ * routers it includes, and resolution is per file rather than per variable:
+ * `api_router = APIRouter(); api_router.include_router(x.router)` does not
+ * pass through, and a prefixed `api_router.include_router(...)` is treated
+ * as a root mount. Unprefixed includes from any other host are ignored.
+ */
+export function resolveFastAPIRouterPrefixes(files, includes, imports, moduleAliases, constructorPrefixes = []) {
+    const fileSet = new Set([...files].map((file) => file.replace(/\\/g, '/')));
+    const constructorPrefixByFile = new Map(constructorPrefixes.map((ctor) => [ctor.filePath.replace(/\\/g, '/'), ctor.prefix]));
+    const absoluteModules = new Map();
+    for (const file of fileSet) {
+        if (!file.endsWith('.py'))
+            continue;
+        const stem = file.endsWith('/__init__.py')
+            ? file.slice(0, -'/__init__.py'.length)
+            : file.slice(0, -'.py'.length);
+        const parts = stem.split('/');
+        for (let i = 0; i < parts.length; i++) {
+            const suffix = parts.slice(i).join('/');
+            const previous = absoluteModules.get(suffix);
+            absoluteModules.set(suffix, previous === undefined ? file : previous === file ? file : null);
+        }
+    }
+    const importsByFile = new Map();
+    for (const imp of [...imports, ...moduleAliases]) {
+        const modulePath = imp.modulePath;
+        if (!modulePath)
+            continue;
+        const file = imp.filePath.replace(/\\/g, '/');
+        const bindings = importsByFile.get(file) ?? new Map();
+        bindings.set(imp.localName, { modulePath });
+        importsByFile.set(file, bindings);
+    }
+    const prefixesByFile = new Map();
+    const resolvedIncludes = new Set();
+    const childIncludes = new Map();
+    const bareMounts = new Set();
+    for (const inc of includes) {
+        const source = inc.filePath.replace(/\\/g, '/');
+        const localName = inc.routerExpr.endsWith('.router')
+            ? inc.routerExpr.slice(0, -'.router'.length)
+            : inc.routerExpr;
+        const modulePath = importsByFile.get(source)?.get(localName)?.modulePath;
+        if (!modulePath)
+            continue;
+        const target = resolveModuleFile(source, modulePath, fileSet, absoluteModules);
+        if (!target)
+            continue;
+        if (inc.host === 'router') {
+            const children = childIncludes.get(source) ?? [];
+            children.push({ target, prefix: inc.prefix, include: inc });
+            childIncludes.set(source, children);
+        }
+        else if (inc.prefix) {
+            const prefixes = prefixesByFile.get(target) ?? new Set();
+            prefixes.add(inc.prefix);
+            prefixesByFile.set(target, prefixes);
+            resolvedIncludes.add(inc);
+        }
+        else {
+            bareMounts.add(target);
+        }
+    }
+    // A router mounted without a prefix still seeds traversal (with an empty
+    // prefix) so its own `APIRouter(prefix=...)` reaches its children. Like its
+    // own routes, it only does so when no prefixed mount targets the file.
+    const roots = [
+        ...[...prefixesByFile].flatMap(([file, prefixes]) => [...prefixes].map((prefix) => ({ file, prefix }))),
+        ...[...bareMounts]
+            .filter((file) => !prefixesByFile.has(file))
+            .map((file) => ({ file, prefix: '' })),
+    ];
+    // `expanded` memoizes (file, prefix) frames so diamond-shaped include graphs
+    // stay linear in distinct prefixes; the per-path `visited` set still stops
+    // cycles whose edges keep growing the prefix.
+    const expanded = new Set();
+    for (const { file, prefix } of roots) {
+        const stack = [{ file, prefix, visited: new Set([file]) }];
+        for (let current = stack.pop(); current; current = stack.pop()) {
+            const frameKey = `${current.file}\0${current.prefix}`;
+            if (expanded.has(frameKey))
+                continue;
+            expanded.add(frameKey);
+            // The parent's own `APIRouter(prefix=...)` sits between its mount
+            // prefix and the child include prefix.
+            const ctorPrefix = constructorPrefixByFile.get(current.file);
+            const parentPrefix = ctorPrefix
+                ? normalizeExtractedRoutePath(ctorPrefix, current.prefix)
+                : current.prefix;
+            for (const edge of childIncludes.get(current.file) ?? []) {
+                if (current.visited.has(edge.target))
+                    continue;
+                const normalized = normalizeExtractedRoutePath(edge.prefix, parentPrefix);
+                // An all-empty chain adds no prefix; record nothing so the child
+                // keeps its legacy fallback, but keep walking for deeper prefixes.
+                const joined = normalized === '/' ? '' : normalized;
+                if (joined) {
+                    const targetPrefixes = prefixesByFile.get(edge.target) ?? new Set();
+                    targetPrefixes.add(joined);
+                    prefixesByFile.set(edge.target, targetPrefixes);
+                    resolvedIncludes.add(edge.include);
+                }
+                stack.push({
+                    file: edge.target,
+                    prefix: joined,
+                    visited: new Set([...current.visited, edge.target]),
+                });
+            }
+        }
+    }
+    return { prefixesByFile, resolvedIncludes };
+}

package/dist/storage/parse-cache.js

@@ -810,7 +810,10 @@ import { copyV8CacheIfPresent, tryLoadV8Cache, writeV8CacheFile } from './v8-sid
 // v122 (#3414): Python decorator identity models restoring helper calls and
 // treats match-pattern captures and nested nonlocal rebinds as shadowing.
 // Warm v121 captures carry the old verdicts.
-const SCHEMA_BUMP = 122;
+// v123 (#3408): FastAPI include records now carry `host`, router imports carry
+// `modulePath`, and unprefixed child includes are emitted. Warm v122 records
+// lack them, so nested router-prefix propagation would stay inert.
+const SCHEMA_BUMP = 123;
 const GITNEXUS_PKG_VERSION = (() => {
     try {
         // package.json sits at gitnexus/package.json — two levels up from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.13-rc.56",
+  "version": "1.6.13-rc.57",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",