gitnexus 1.6.13-rc.55 → 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/languages/python/builtin-descriptors.js

@@ -80,6 +80,8 @@ function bindingOf(identifier) {
     if (parent === null)
         return null;
     const shadow = { node: identifier, effect: 'shadow' };
+    if (inCasePattern(identifier))
+        return isCaseCapture(identifier) ? shadow : null;
     switch (parent.type) {
         case 'assignment':
         case 'augmented_assignment':
@@ -117,11 +119,9 @@ function bindingOf(identifier) {
                 : null;
         case 'dotted_name': {
             const owner = parent.parent;
-            // `import a.b` binds `a`; `case name:` captures a single name.
+            // `import a.b` binds `a`.
             if (owner?.type === 'import_statement')
                 return parent.firstNamedChild?.id === node.id ? shadow : null;
-            if (owner?.type === 'case_pattern')
-                return parent.namedChildCount === 1 ? shadow : null;
             if (owner?.type !== 'import_from_statement' || !isField(parent, 'name'))
                 return null;
             return importsFromBuiltins(owner) ? { node: identifier, effect: 'builtin' } : shadow;
@@ -174,9 +174,145 @@ function descriptorBindings(node) {
         const redirect = redirected.get(`${found.text}@${scopeOf(found)?.id}`) ?? null;
         add(found.text, { ...binding, redirect });
     }
+    addHelperCalls(tree.rootNode, bindings, redirected);
     bindingsByTree.set(tree, bindings);
     return bindings;
 }
+/**
+ * A bare module-level call to a same-file helper that always restores a
+ * descriptor name through `global` runs that restore at the call. Record it
+ * there as a module binding, so the call's position orders it.
+ */
+function addHelperCalls(root, bindings, redirected) {
+    // Helper function name -> its `def` and, per descriptor name, the restore
+    // its call performs.
+    const helpers = new Map();
+    for (const [name, list] of bindings) {
+        const byHelper = new Map();
+        for (const binding of list) {
+            if (binding.redirect !== 'global')
+                continue;
+            const fn = scopeOf(binding.node);
+            if (fn === null)
+                continue;
+            const entry = byHelper.get(fn.id);
+            if (entry === undefined)
+                byHelper.set(fn.id, { fn, globals: [binding] });
+            else
+                entry.globals.push(binding);
+        }
+        for (const { fn, globals } of byHelper.values()) {
+            const effect = restoreOnCall(fn, globals);
+            const helper = fn.childForFieldName('name')?.text;
+            if (effect === null || helper === undefined)
+                continue;
+            const entry = helpers.get(helper) ?? { fn, restores: new Map() };
+            entry.restores.set(name, effect);
+            helpers.set(helper, entry);
+        }
+    }
+    if (helpers.size === 0)
+        return;
+    // A call only denotes the helper when its `def` is the name's one module
+    // binding. A local of the same name elsewhere cannot rebind it.
+    if (root.descendantsOfType('wildcard_import').length > 0)
+        return;
+    const bindingCounts = new Map();
+    for (const found of root.descendantsOfType('identifier')) {
+        if (!helpers.has(found.text) || bindingOf(found) === null)
+            continue;
+        const scope = scopeOf(found);
+        if (scope !== null && redirected.get(`${found.text}@${scope.id}`) !== 'global')
+            continue;
+        bindingCounts.set(found.text, (bindingCounts.get(found.text) ?? 0) + 1);
+    }
+    for (const [helper, count] of bindingCounts)
+        if (count > 1)
+            helpers.delete(helper);
+    const touched = new Set();
+    for (const statement of root.namedChildren) {
+        // Only a call that is the whole statement surely runs when reached.
+        if (statement.type !== 'expression_statement' || statement.namedChildCount !== 1)
+            continue;
+        const call = statement.firstNamedChild;
+        const callee = call?.type === 'call' ? call.childForFieldName('function') : null;
+        const helper = callee?.type === 'identifier' ? helpers.get(callee.text) : undefined;
+        // The call reaches the helper only once its `def` statement has run, and
+        // an argument-free call binds only when every parameter is optional.
+        if (helper === undefined || statement.startIndex < helper.fn.endIndex)
+            continue;
+        if ((call?.childForFieldName('arguments')?.namedChildCount ?? 0) > 0)
+            continue;
+        for (const [name, effect] of helper.restores) {
+            const list = bindings.get(name);
+            if (list === undefined)
+                continue;
+            list.push({ node: callee, effect, redirect: null });
+            touched.add(list);
+        }
+    }
+    for (const list of touched)
+        list.sort((a, b) => a.node.startIndex - b.node.startIndex);
+}
+/**
+ * Does this name in a case pattern capture? Value patterns (`a.b`), class
+ * names and keyword keys are reads. Every other name is a capture.
+ */
+function isCaseCapture(identifier) {
+    const parent = identifier.parent;
+    if (parent?.type === 'keyword_pattern')
+        return parent.firstNamedChild?.id !== identifier.id;
+    if (parent?.type !== 'dotted_name')
+        return true;
+    if (parent.namedChildCount > 1)
+        return false;
+    return !(parent.parent?.type === 'class_pattern' && parent.parent.firstNamedChild?.id === parent.id);
+}
+/** Is `node` inside a `match` case pattern? */
+function inCasePattern(node) {
+    for (let parent = node.parent; parent !== null; parent = parent.parent) {
+        if (parent.type === 'case_pattern')
+            return true;
+    }
+    return false;
+}
+/**
+ * The restore a call to `fn` always performs on a module global, or `null`.
+ * `fn` must be a plain module-level `def` whose body runs on call (not a
+ * generator or coroutine), and every `global` binding of the name in it must
+ * be a restore in a simple statement that no earlier `return` can skip.
+ */
+function restoreOnCall(fn, globals) {
+    if (fn.type !== 'function_definition' || fn.parent?.type !== 'module')
+        return null;
+    if (fn.children.some((child) => child.type === 'async'))
+        return null;
+    const required = fn
+        .childForFieldName('parameters')
+        ?.namedChildren.some((param) => param.type === 'identifier' ||
+        (param.type === 'typed_parameter' && param.firstNamedChild?.type === 'identifier'));
+    if (required === true)
+        return null;
+    const body = fn.childForFieldName('body');
+    // `globals` is in source order, so the last restore is the one that sticks.
+    const first = globals[0];
+    const last = globals[globals.length - 1];
+    if (body === null || first === undefined || last === undefined)
+        return null;
+    for (const binding of globals) {
+        const statement = statementIn(binding.node, body);
+        if (binding.effect === 'shadow' ||
+            statement === null ||
+            !SIMPLE_STATEMENTS.has(statement.type)) {
+            return null;
+        }
+    }
+    const escapes = body
+        .descendantsOfType(['yield', 'return_statement'])
+        .some((node) => scopeOf(node)?.id === fn.id &&
+        (node.type === 'yield' || node.startIndex < first.node.startIndex));
+    return escapes ? null : last.effect;
+}
 /**
  * The scope that owns names bound at `node`: a function or lambda body, a
  * class body, a comprehension, or the module (`null`). A walrus target skips
@@ -207,6 +343,10 @@ function statementIn(node, body) {
         current = current.parent;
     return current.parent === null ? null : current;
 }
+/** Does `outer` span `node`? */
+function contains(outer, node) {
+    return node.startIndex >= outer.startIndex && node.endIndex <= outer.endIndex;
+}
 /** Can `binding` run before `use` in the same scope, including an earlier
  *  iteration of an enclosing loop? */
 function mayRunBefore(binding, use, scope) {
@@ -214,8 +354,7 @@ function mayRunBefore(binding, use, scope) {
         return true;
     for (let loop = use.parent; loop !== null && loop.id !== scope?.id; loop = loop.parent) {
         if ((loop.type === 'for_statement' || loop.type === 'while_statement') &&
-            binding.startIndex >= loop.startIndex &&
-            binding.endIndex <= loop.endIndex) {
+            contains(loop, binding)) {
             return true;
         }
     }
@@ -270,6 +409,13 @@ function lookupName(bindings, use) {
         const owned = bindings.some((binding) => binding.redirect === null && scopeOf(binding.node)?.id === fn.id);
         if (!owned)
             continue;
+        // A nested function can rebind this cell whenever it is called; that
+        // order is not modelled, so assume it ran.
+        const rebound = bindings.some((binding) => binding.effect === 'shadow' &&
+            binding.redirect === 'nonlocal' &&
+            contains(fn, binding.node));
+        if (rebound)
+            return 'shadow';
         // Any binding makes the name local to this function, so the class body
         // reads that cell. An unbound cell raises NameError, not the builtin.
         return namespaceState(bindings, fn, use) === 'builtin' ? 'builtin' : 'shadow';
@@ -287,16 +433,14 @@ function lookupName(bindings, use) {
         // is called; that order is not modelled, so assume it ran.
         if (binding.redirect === 'nonlocal') {
             const outer = functions[functions.length - 1];
-            const inside = outer !== undefined &&
-                binding.node.startIndex >= outer.startIndex &&
-                binding.node.endIndex <= outer.endIndex;
-            if (inside)
+            if (outer !== undefined && contains(outer, binding.node))
                 return 'shadow';
         }
         if (binding.redirect === 'global') {
             // The function can only be called once the top-level statement that
-            // defines it has run. Whether a call happens is unknown, so a restoring
-            // `global` delete is ignored and a rebinding one is assumed.
+            // defines it has run. Whether a call happens is unknown, so a rebinding
+            // one is assumed. A restore counts only at a proven call site (see
+            // `addHelperCalls`).
             const top = statementIn(binding.node, binding.node.tree.rootNode);
             if (deferred || (top !== null && mayRunBefore(top, use, null)))
                 return 'shadow';

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

@@ -807,7 +807,13 @@ import { copyV8CacheIfPresent, tryLoadV8Cache, writeV8CacheFile } from './v8-sid
 // comments, honors rebinding of builtin descriptor names visible where the
 // decorator is evaluated, and withholds subtype capacity from descriptor
 // stacks. Warm v120 captures carry the old verdicts.
-const SCHEMA_BUMP = 121;
+// 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.
+// 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.55",
+  "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",