gitnexus 1.6.6-rc.81 → 1.6.6-rc.82

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

@@ -19,9 +19,13 @@ const FASTAPI_VERBS = {
     delete: 'DELETE',
     patch: 'PATCH',
 };
-// ─── Provider: FastAPI @app.get/... ──────────────────────────────────
-const FASTAPI_PATTERNS = compilePatterns({
-    name: 'python-fastapi',
+// ─── Provider: FastAPI @app.<verb> / @router.<verb> ──────────────────
+// Two separate patterns so we can tag detections by decorator object.
+// Only `@router.*` detections participate in `include_router(prefix=)`
+// path-prefix joining (see `PythonRepoContext` + `joinPrefix`); `@app.*`
+// routes already carry their final path verbatim.
+const FASTAPI_APP_PATTERNS = compilePatterns({
+    name: 'python-fastapi-app',
     language: Python,
     patterns: [
         {
@@ -37,6 +41,133 @@ const FASTAPI_PATTERNS = compilePatterns({
         },
     ],
 });
+const FASTAPI_ROUTER_PATTERNS = compilePatterns({
+    name: 'python-fastapi-router',
+    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 . (string) @path)))
+      `,
+        },
+    ],
+});
+// ─── include_router(<router_obj>, prefix='/x') across the repo ────────
+// Two shapes are common:
+//   app.include_router(assistant.router, prefix='/ai')
+//   app.include_router(my_router, prefix='/ai')
+// The first names the originating module via `<module>.router`; the second
+// references a name imported into the host file. We capture both.
+const INCLUDE_ROUTER_ATTR_PATTERNS = compilePatterns({
+    name: 'python-fastapi-include-router-attr',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            // Match any `<host>.include_router(<module>.router, ..., prefix='/x')`
+            // call. We deliberately do NOT pin `<host>` to the literal name `app`
+            // — production code routinely uses `api`, `application`, `asgi_app`,
+            // etc. The shape (`include_router` invoked with a router argument and
+            // a `prefix=` keyword) is specific enough on its own; restricting the
+            // host produces false negatives without removing meaningful false
+            // positives.
+            query: `
+        (call
+          function: (attribute
+            attribute: (identifier) @incl (#eq? @incl "include_router"))
+          arguments: (argument_list
+            (attribute
+              object: (identifier) @router_module
+              attribute: (identifier) @router_attr (#eq? @router_attr "router"))
+            (keyword_argument
+              name: (identifier) @kw (#eq? @kw "prefix")
+              value: (string) @prefix)))
+      `,
+        },
+    ],
+});
+const INCLUDE_ROUTER_NAME_PATTERNS = compilePatterns({
+    name: 'python-fastapi-include-router-name',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            // Same `<host>` rationale as INCLUDE_ROUTER_ATTR_PATTERNS — see above.
+            query: `
+        (call
+          function: (attribute
+            attribute: (identifier) @incl (#eq? @incl "include_router"))
+          arguments: (argument_list
+            (identifier) @router_name
+            (keyword_argument
+              name: (identifier) @kw (#eq? @kw "prefix")
+              value: (string) @prefix)))
+      `,
+        },
+    ],
+});
+// `from .api.assistant import router` style — used together with
+// INCLUDE_ROUTER_NAME so we can map a local name back to its module
+// path, then back to the file the router was declared in.
+const FROM_IMPORT_ROUTER_PATTERNS = compilePatterns({
+    name: 'python-fastapi-from-import-router',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (import_from_statement
+          module_name: (_) @module
+          name: (dotted_name (identifier) @imported (#eq? @imported "router")))
+      `,
+        },
+        {
+            meta: {},
+            query: `
+        (import_from_statement
+          module_name: (_) @module
+          name: (aliased_import
+            name: (dotted_name (identifier) @imported (#eq? @imported "router"))
+            alias: (identifier) @alias))
+      `,
+        },
+    ],
+});
+// `from api import users` / `from api import users as u` — module-level
+// imports where the imported name is itself the module that owns
+// `<name>.router`. Lets Shape A (`<host>.include_router(<name>.router, …)`)
+// look up the full package path of `<name>` and pin the prefix onto the
+// exact file (`api/users.py`) rather than every file basenamed `users.py`.
+const FROM_IMPORT_MODULE_PATTERNS = compilePatterns({
+    name: 'python-fastapi-from-import-module',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (import_from_statement
+          module_name: (_) @module
+          name: (dotted_name (identifier) @imported))
+      `,
+        },
+        {
+            meta: {},
+            query: `
+        (import_from_statement
+          module_name: (_) @module
+          name: (aliased_import
+            name: (dotted_name (identifier) @imported)
+            alias: (identifier) @alias))
+      `,
+        },
+    ],
+});
 // ─── Consumer: requests.get/post/... ──────────────────────────────────
 const REQUESTS_VERB_PATTERNS = compilePatterns({
     name: 'python-requests-verb',
@@ -405,14 +536,183 @@ const HTTPX_ASYNC_CLIENT_GENERIC_PATTERNS = compilePatterns({
         },
     ],
 });
+/** Strip `.py` and return the bare basename (e.g. `api/users.py` → `users`). */
+function fileShortKey(rel) {
+    const slash = rel.lastIndexOf('/');
+    const file = slash >= 0 ? rel.slice(slash + 1) : rel;
+    return file.endsWith('.py') ? file.slice(0, -3) : file;
+}
+/**
+ * Long key for a `.py` file: parent directory + stem, joined with `/`.
+ * Files at the repo root return the empty string (no parent), in which
+ * case callers should fall back to the short key.
+ */
+function fileLongKey(rel) {
+    const noExt = rel.endsWith('.py') ? rel.slice(0, -3) : rel;
+    const lastSlash = noExt.lastIndexOf('/');
+    if (lastSlash < 0)
+        return '';
+    const beforeLast = noExt.slice(0, lastSlash);
+    const stem = noExt.slice(lastSlash + 1);
+    const prevSlash = beforeLast.lastIndexOf('/');
+    const parent = prevSlash >= 0 ? beforeLast.slice(prevSlash + 1) : beforeLast;
+    return `${parent}/${stem}`;
+}
+/** Last `.`-separated segment of a (possibly relative) module path. */
+function lastSegmentOfDotted(text) {
+    const stripped = text.replace(/^\.+/, '');
+    if (!stripped)
+        return '';
+    const dot = stripped.lastIndexOf('.');
+    return dot >= 0 ? stripped.slice(dot + 1) : stripped;
+}
+/**
+ * Last two `.`-separated segments of a (possibly relative) module path
+ * joined with `/`, e.g. `api.users` → `api/users`. Single-segment paths
+ * and pure-dot inputs return the empty string; callers should fall back
+ * to the short key in that case.
+ */
+function lastTwoSegmentsAsLongKey(text) {
+    const stripped = text.replace(/^\.+/, '');
+    if (!stripped)
+        return '';
+    const last = stripped.lastIndexOf('.');
+    if (last <= 0)
+        return '';
+    const beforeLast = stripped.slice(0, last);
+    const stem = stripped.slice(last + 1);
+    const prev = beforeLast.lastIndexOf('.');
+    const parent = prev >= 0 ? beforeLast.slice(prev + 1) : beforeLast;
+    return `${parent}/${stem}`;
+}
+function recordPrefix(target, key, prefix) {
+    const set = target.get(key) ?? new Set();
+    set.add(prefix);
+    target.set(key, set);
+}
+function buildPythonRepoContext(files, parser, readFile, parseSource) {
+    const prefixesByLongKey = new Map();
+    const prefixesByShortKey = new Map();
+    // Pre-pass over .py files. We deliberately run this even on files
+    // that don't contain `include_router` — the cost of an extra parse
+    // is bounded by the file count, and detecting `include_router`
+    // beforehand would require its own grep/scan.
+    for (const rel of files) {
+        if (!rel.endsWith('.py'))
+            continue;
+        const src = readFile(rel);
+        if (!src)
+            continue;
+        if (!src.includes('include_router'))
+            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);
+            }
+            else {
+                recordPrefix(prefixesByShortKey, 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);
+            }
+        }
+    }
+    return { prefixesByLongKey, prefixesByShortKey };
+}
+function joinPrefix(prefix, route) {
+    // Mirror FastAPI's path joining: trim trailing slash off prefix,
+    // ensure exactly one leading slash on the result.
+    const p = prefix.replace(/\/+$/, '');
+    const r = route.startsWith('/') ? route : `/${route}`;
+    return `${p}${r}`;
+}
 export const PYTHON_HTTP_PLUGIN = {
     name: 'python-http',
     language: Python,
-    scan(tree) {
+    prepareRepo({ files, parser, readFile, parseSource }) {
+        return buildPythonRepoContext(files, parser, readFile, parseSource);
+    },
+    scan(tree, repoContext, fileRel) {
         const out = [];
         const httpxAsyncClients = collectHttpxAsyncClients(tree);
-        // Providers: FastAPI
-        for (const match of runCompiledPatterns(FASTAPI_PATTERNS, tree)) {
+        const ctx = repoContext;
+        // 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)
@@ -432,6 +732,45 @@ export const PYTHON_HTTP_PLUGIN = {
                 confidence: 0.8,
             });
         }
+        // Providers: FastAPI @router.<verb>("/path") — must be joined
+        // with the prefix(es) declared at the include_router site. When
+        // no prefix is found we still emit the unprefixed path so this
+        // 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;
+            // 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.
+            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 paths = prefixSet && prefixSet.size > 0
+                ? [...prefixSet].map((p) => joinPrefix(p, rawPath))
+                : [rawPath];
+            for (const p of paths) {
+                out.push({
+                    role: 'provider',
+                    framework: 'fastapi',
+                    method: httpMethod,
+                    path: p,
+                    name: null,
+                    confidence: 0.8,
+                });
+            }
+        }
         // Consumers: requests.<verb>
         for (const match of runCompiledPatterns(REQUESTS_VERB_PATTERNS, tree)) {
             const methodNode = match.captures.method;

package/dist/core/group/extractors/http-patterns/types.d.ts

@@ -47,15 +47,47 @@ export interface HttpDetection {
  * `LanguagePatterns.language` in `tree-sitter-scanner.ts` — the
  * grammar modules export different shapes.
  */
+/**
+ * Per-repo state a plugin can build during a `prepareRepo` pass before
+ * any per-file `scan` is invoked. The orchestrator threads this opaque
+ * value back into each `scan` call so plugins can resolve cross-file
+ * facts (e.g. FastAPI `app.include_router(prefix=...)` mappings live
+ * in `main.py` but apply to handlers declared in `api/*.py`).
+ *
+ * Plugins that have no cross-file state can omit `prepareRepo` and
+ * receive `undefined`.
+ */
+export type RepoContext = unknown;
 export interface HttpLanguagePlugin {
     /** Human-readable plugin name for diagnostics. */
     name: string;
     /** tree-sitter grammar object (passed to the shared parser). */
     language: unknown;
+    /**
+     * Optional pre-pass: walk the relevant files in the repo and produce
+     * an opaque context that `scan` can use to resolve cross-file facts.
+     * Implementations must not throw — return undefined on any error so
+     * the orchestrator falls back to context-less scanning.
+     */
+    prepareRepo?(args: {
+        repoPath: string;
+        files: string[];
+        parser: Parser;
+        readFile: (rel: string) => string | null;
+        parseSource: (parser: Parser, src: string) => Parser.Tree | null;
+    }): RepoContext | undefined;
     /**
      * Scan a parsed tree and return zero or more HTTP detections. Plugins
      * must not throw — they should swallow per-match errors so a single
      * malformed construct does not abort the whole file.
+     *
+     * `repoContext` is whatever the plugin's `prepareRepo` produced (or
+     * `undefined` if there is no `prepareRepo`).
+     *
+     * `fileRel` is the repo-relative path of the file being scanned;
+     * plugins that resolve cross-file facts (e.g. FastAPI router prefix
+     * joining) need it to key into `repoContext`. Optional so existing
+     * single-file plugins can keep their unary `scan(tree)` shape.
      */
-    scan(tree: Parser.Tree): HttpDetection[];
+    scan(tree: Parser.Tree, repoContext?: RepoContext, fileRel?: string): HttpDetection[];
 }

package/dist/core/group/extractors/http-route-extractor.js

@@ -141,7 +141,35 @@ export class HttpRouteExtractor {
         // both graph-assisted enrichment and source-scan emission.
         const parser = new Parser();
         const cachedDetections = new Map();
-        const getDetections = (rel) => {
+        // Per-plugin cross-file context (e.g. Python's FastAPI router →
+        // include_router(prefix=...) map). Built lazily on first
+        // `getDetections` call for a file the plugin handles, scoped to the
+        // file list returned by `getScannedFiles`. Stored by plugin name so
+        // a repo with multiple languages keeps each plugin's context
+        // independent.
+        const repoContextByPlugin = new Map();
+        const ensureRepoContext = async (plugin) => {
+            if (!plugin || typeof plugin.prepareRepo !== 'function')
+                return undefined;
+            if (repoContextByPlugin.has(plugin.name))
+                return repoContextByPlugin.get(plugin.name);
+            try {
+                const ctx = plugin.prepareRepo({
+                    repoPath,
+                    files: await getScannedFiles(),
+                    parser,
+                    readFile: (rel) => readSafe(repoPath, rel),
+                    parseSource: (p, src) => parseSourceSafe(p, src),
+                });
+                repoContextByPlugin.set(plugin.name, ctx);
+                return ctx;
+            }
+            catch {
+                repoContextByPlugin.set(plugin.name, undefined);
+                return undefined;
+            }
+        };
+        const getDetections = async (rel) => {
             const cached = cachedDetections.get(rel);
             if (cached)
                 return cached;
@@ -150,6 +178,7 @@ export class HttpRouteExtractor {
                 cachedDetections.set(rel, []);
                 return [];
             }
+            const repoContext = await ensureRepoContext(plugin);
             const content = readSafe(repoPath, rel);
             if (!content) {
                 cachedDetections.set(rel, []);
@@ -158,7 +187,7 @@ export class HttpRouteExtractor {
             try {
                 parser.setLanguage(plugin.language);
                 const tree = parseSourceSafe(parser, content);
-                const detections = plugin.scan(tree);
+                const detections = plugin.scan(tree, repoContext, rel);
                 cachedDetections.set(rel, detections);
                 return detections;
             }
@@ -179,9 +208,9 @@ export class HttpRouteExtractor {
         const graphProviders = dbExecutor != null ? await this.extractProvidersGraph(dbExecutor, getDetections) : [];
         // Source scan always runs to capture routes in languages/files not covered
         // by graph edges; the glob and per-file parse results are cached above.
-        const providers = this.mergeGraphAndSourceContracts(graphProviders, this.extractProvidersSourceScan(await getScannedFiles(), getDetections));
+        const providers = this.mergeGraphAndSourceContracts(graphProviders, await this.extractProvidersSourceScan(await getScannedFiles(), getDetections));
         const graphConsumers = dbExecutor != null ? await this.extractConsumersGraph(dbExecutor, getDetections) : [];
-        const consumers = this.mergeGraphAndSourceContracts(graphConsumers, this.extractConsumersSourceScan(await getScannedFiles(), getDetections));
+        const consumers = this.mergeGraphAndSourceContracts(graphConsumers, await this.extractConsumersSourceScan(await getScannedFiles(), getDetections));
         return [...providers, ...consumers];
     }
     async scanFiles(repoPath) {
@@ -219,7 +248,7 @@ export class HttpRouteExtractor {
             // helpers — tree-sitter gives both pieces of information
             // structurally. Always run the lookup: even when method is set by
             // `methodFromRouteReason`, we still need the handler name.
-            const detections = filePath ? getDetections(filePath) : [];
+            const detections = filePath ? await getDetections(filePath) : [];
             const providerDetections = detections.filter((d) => d.role === 'provider');
             let handlerName = null;
             const normalizedRoute = normalizeHttpPath(routePath);
@@ -293,10 +322,10 @@ export class HttpRouteExtractor {
         return out;
     }
     // ─── Source-scan providers ─────────────────────────────────────────
-    extractProvidersSourceScan(files, getDetections) {
+    async extractProvidersSourceScan(files, getDetections) {
         const out = [];
         for (const rel of files) {
-            const detections = getDetections(rel);
+            const detections = await getDetections(rel);
             for (const d of detections) {
                 if (d.role !== 'provider')
                     continue;
@@ -338,7 +367,7 @@ export class HttpRouteExtractor {
             let method = 'GET';
             // Prefer the plugin's detected method if we can find a matching
             // fetch/axios call in the same file.
-            const detections = filePath ? getDetections(filePath) : [];
+            const detections = filePath ? await getDetections(filePath) : [];
             // Symmetric to the provider path: if multiple consumer calls in
             // the same file share the same normalized path (e.g. a GET
             // fetch AND a POST fetch to `/api/orders`), `.find()` silently
@@ -388,10 +417,10 @@ export class HttpRouteExtractor {
         return out;
     }
     // ─── Source-scan consumers ─────────────────────────────────────────
-    extractConsumersSourceScan(files, getDetections) {
+    async extractConsumersSourceScan(files, getDetections) {
         const out = [];
         for (const rel of files) {
-            const detections = getDetections(rel);
+            const detections = await getDetections(rel);
             for (const d of detections) {
                 if (d.role !== 'consumer')
                     continue;

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

@@ -4,6 +4,7 @@ import { ASTCache } from './ast-cache.js';
 import type { ParsedFile } from '../../_shared/index.js';
 import { WorkerPool } from './workers/worker-pool.js';
 import type { ParseWorkerResult, ExtractedImport, ExtractedCall, ExtractedAssignment, ExtractedRoute, ExtractedFetchCall, ExtractedDecoratorRoute, ExtractedToolDef, FileConstructorBindings, FileScopeBindings, ExtractedORMQuery, FetchWrapperDef } from './workers/parse-worker.js';
+import type { ExtractedRouterImport, ExtractedRouterInclude, ExtractedRouterModuleAlias } from './route-extractors/fastapi-router-bindings.js';
 export type FileProgressCallback = (current: number, total: number, filePath: string) => void;
 export interface WorkerExtractedData {
     imports: ExtractedImport[];
@@ -14,6 +15,9 @@ export interface WorkerExtractedData {
     fetchCalls: ExtractedFetchCall[];
     fetchWrapperDefs: FetchWrapperDef[];
     decoratorRoutes: ExtractedDecoratorRoute[];
+    routerIncludes: ExtractedRouterInclude[];
+    routerImports: ExtractedRouterImport[];
+    routerModuleAliases: ExtractedRouterModuleAlias[];
     toolDefs: ExtractedToolDef[];
     ormQueries: ExtractedORMQuery[];
     constructorBindings: FileConstructorBindings[];

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

@@ -37,6 +37,9 @@ export const mergeChunkResults = (graph, symbolTable, chunkResults) => {
     const allFetchCalls = [];
     const allFetchWrapperDefs = [];
     const allDecoratorRoutes = [];
+    const allRouterIncludes = [];
+    const allRouterImports = [];
+    const allRouterModuleAliases = [];
     const allToolDefs = [];
     const allORMQueries = [];
     const allConstructorBindings = [];
@@ -82,6 +85,12 @@ export const mergeChunkResults = (graph, symbolTable, chunkResults) => {
             allFetchWrapperDefs.push(item);
         for (const item of result.decoratorRoutes)
             allDecoratorRoutes.push(item);
+        for (const item of result.routerIncludes ?? [])
+            allRouterIncludes.push(item);
+        for (const item of result.routerImports ?? [])
+            allRouterImports.push(item);
+        for (const item of result.routerModuleAliases ?? [])
+            allRouterModuleAliases.push(item);
         for (const item of result.toolDefs)
             allToolDefs.push(item);
         if (result.ormQueries)
@@ -105,6 +114,9 @@ export const mergeChunkResults = (graph, symbolTable, chunkResults) => {
         fetchCalls: allFetchCalls,
         fetchWrapperDefs: allFetchWrapperDefs,
         decoratorRoutes: allDecoratorRoutes,
+        routerIncludes: allRouterIncludes,
+        routerImports: allRouterImports,
+        routerModuleAliases: allRouterModuleAliases,
         toolDefs: allToolDefs,
         ormQueries: allORMQueries,
         constructorBindings: allConstructorBindings,
@@ -138,6 +150,9 @@ outRawResults) => {
             fetchCalls: [],
             fetchWrapperDefs: [],
             decoratorRoutes: [],
+            routerIncludes: [],
+            routerImports: [],
+            routerModuleAliases: [],
             toolDefs: [],
             ormQueries: [],
             constructorBindings: [],

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

@@ -237,6 +237,9 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     const allFetchWrapperDefs = [];
     const allExtractedRoutes = [];
     const allDecoratorRoutes = [];
+    const allRouterIncludes = [];
+    const allRouterImports = [];
+    const allRouterModuleAliases = [];
     const allToolDefs = [];
     const allORMQueries = [];
     const deferredWorkerCalls = [];
@@ -543,6 +546,18 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                     for (const item of chunkWorkerData.decoratorRoutes)
                         allDecoratorRoutes.push(item);
                 }
+                if (chunkWorkerData.routerIncludes?.length) {
+                    for (const item of chunkWorkerData.routerIncludes)
+                        allRouterIncludes.push(item);
+                }
+                if (chunkWorkerData.routerImports?.length) {
+                    for (const item of chunkWorkerData.routerImports)
+                        allRouterImports.push(item);
+                }
+                if (chunkWorkerData.routerModuleAliases?.length) {
+                    for (const item of chunkWorkerData.routerModuleAliases)
+                        allRouterModuleAliases.push(item);
+                }
                 if (chunkWorkerData.toolDefs?.length) {
                     for (const item of chunkWorkerData.toolDefs)
                         allToolDefs.push(item);
@@ -878,6 +893,143 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     importCtx.resolveCache.clear();
     importCtx.index = EMPTY_INDEX;
     importCtx.normalizedFileList = [];
+    // FastAPI router-prefix resolution (cross-file).
+    //
+    // 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
+    //     bare local name (Shape B).
+    //   • `routerImports`  — every `from <module> import router [as <alias>]`,
+    //     mapping a local name to a module key (the basename of the source
+    //     module). These let us resolve Shape-B router includes back to the
+    //     module that defines the router.
+    //
+    // We build `module-basename → Set<prefix>` and then walk
+    // `allDecoratorRoutes`: any decorator route emitted from a `router.<verb>`
+    // decorator inherits its file-basename's prefix. When a router is mounted
+    // under multiple prefixes we duplicate the route entry, mirroring FastAPI's
+    // runtime behaviour.
+    if (allRouterIncludes.length > 0 && allDecoratorRoutes.length > 0) {
+        const importsByFile = new Map();
+        for (const imp of allRouterImports) {
+            let m = importsByFile.get(imp.filePath);
+            if (!m) {
+                m = new Map();
+                importsByFile.set(imp.filePath, m);
+            }
+            m.set(imp.localName, {
+                moduleKey: imp.moduleKey,
+                moduleKeyLong: imp.moduleKeyLong,
+            });
+        }
+        // Module-alias map keyed by file: `localName` (the imported module
+        // identifier in this file) → long key. Shape-A receivers like
+        // `users.router` are matched against this map; the long key, when
+        // present, scopes the prefix to the precise source file.
+        const moduleAliasesByFile = new Map();
+        for (const alias of allRouterModuleAliases) {
+            let m = moduleAliasesByFile.get(alias.filePath);
+            if (!m) {
+                m = new Map();
+                moduleAliasesByFile.set(alias.filePath, m);
+            }
+            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).
+        const prefixesByLongKey = new Map();
+        const prefixesByShortKey = new Map();
+        const recordPrefix = (target, key, prefix) => {
+            let set = target.get(key);
+            if (!set) {
+                set = new Set();
+                target.set(key, set);
+            }
+            set.add(prefix);
+        };
+        for (const inc of allRouterIncludes) {
+            // 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
+            // the same file imports `<module>` via `from <pkg> import <module>`
+            // (recorded in `allRouterModuleAliases`) we promote to a long key.
+            const dotIdx = inc.routerExpr.indexOf('.router');
+            if (dotIdx > 0) {
+                const moduleShort = inc.routerExpr.slice(0, dotIdx);
+                const aliasLong = moduleAliasesByFile.get(inc.filePath)?.get(moduleShort);
+                if (aliasLong) {
+                    recordPrefix(prefixesByLongKey, aliasLong, inc.prefix);
+                }
+                else {
+                    recordPrefix(prefixesByShortKey, moduleShort, inc.prefix);
+                }
+                continue;
+            }
+            // Shape B: bare local name. Resolve through this file's imports. The
+            // import line gives us a long key whenever the module path was multi-
+            // segment, so cross-package collisions are eliminated for Shape B.
+            const localImp = importsByFile.get(inc.filePath)?.get(inc.routerExpr);
+            if (!localImp)
+                continue;
+            if (localImp.moduleKeyLong) {
+                recordPrefix(prefixesByLongKey, localImp.moduleKeyLong, inc.prefix);
+            }
+            else {
+                recordPrefix(prefixesByShortKey, localImp.moduleKey, inc.prefix);
+            }
+        }
+        if (prefixesByLongKey.size > 0 || prefixesByShortKey.size > 0) {
+            const fileLongKey = (rel) => {
+                // Strip `.py`, then take the last two path segments. `api/users.py`
+                // → `api/users`. Files at the repo root return the empty string,
+                // which can never match a long-key entry (those always include a
+                // parent directory) and so fall through to the short-key lookup.
+                const noExt = rel.endsWith('.py') ? rel.slice(0, -3) : rel;
+                const lastSlash = noExt.lastIndexOf('/');
+                if (lastSlash < 0)
+                    return '';
+                const beforeLast = noExt.slice(0, lastSlash);
+                const stem = noExt.slice(lastSlash + 1);
+                const prevSlash = beforeLast.lastIndexOf('/');
+                const parent = prevSlash >= 0 ? beforeLast.slice(prevSlash + 1) : beforeLast;
+                return `${parent}/${stem}`;
+            };
+            const fileShortKey = (rel) => {
+                const slash = rel.lastIndexOf('/');
+                const file = slash >= 0 ? rel.slice(slash + 1) : rel;
+                return file.endsWith('.py') ? file.slice(0, -3) : file;
+            };
+            const expanded = [];
+            for (const dr of allDecoratorRoutes) {
+                if (dr.decoratorReceiver !== 'router' || !dr.filePath.endsWith('.py')) {
+                    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`.
+                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;
+                if (!prefixes || prefixes.size === 0) {
+                    expanded.push(dr);
+                    continue;
+                }
+                for (const prefix of prefixes) {
+                    expanded.push({ ...dr, prefix });
+                }
+            }
+            allDecoratorRoutes.length = 0;
+            for (const dr of expanded)
+                allDecoratorRoutes.push(dr);
+        }
+    }
     return {
         exportedTypeMap,
         allFetchCalls,

package/dist/core/ingestion/pipeline-phases/routes.js

@@ -150,7 +150,6 @@ export const routesPhase = {
                 }
             }
         }
-        const ensureSlash = (path) => (path.startsWith('/') ? path : '/' + path);
         let duplicateRoutes = 0;
         const namedRouteRegistry = new Map();
         const addRoute = (url, entry) => {
@@ -173,7 +172,8 @@ export const routesPhase = {
             }
         }
         for (const dr of allDecoratorRoutes) {
-            addRoute(ensureSlash(dr.routePath), {
+            const url = normalizeExtractedRoutePath(dr.routePath, dr.prefix ?? null);
+            addRoute(url, {
                 filePath: dr.filePath,
                 source: `decorator-${dr.decoratorName}`,
             });

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

@@ -0,0 +1,134 @@
+/**
+ * FastAPI router-prefix detection — pure functions, no worker thread.
+ *
+ * NOT A WORKER. This module exports plain synchronous functions; it
+ * does not import `worker_threads`, does not call `parentPort`, and
+ * is not a new worker entry point. It lives next to the other route
+ * extractors (expo, nextjs, php, laravel) for that reason.
+ *
+ * The implementation was historically inlined in `workers/parse-worker.ts`,
+ * but parse-worker.ts is itself the worker entry point and cannot be
+ * loaded from the main thread (see the same constraint used by
+ * `test/unit/call-attribution-issue-1166.test.ts`). Splitting the pure
+ * 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
+ * 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.
+ *
+ *   • {@link ExtractedRouterImport} — every
+ *     `from <module> import router [as <alias>]`, captured for both
+ *     absolute and relative module paths (`from .calls import …`).
+ *     parse-impl uses the imports to resolve Shape-B local names back
+ *     to the file that declares the router.
+ *
+ * Module keying is two-tiered to avoid prefix bleed between same-named
+ * files in different packages (e.g. `api/users.py` vs `admin/users.py`):
+ *
+ *   • 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.
+ *
+ * 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.
+ *
+ * `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.
+ */
+export interface ExtractedRouterInclude {
+    filePath: string;
+    routerExpr: string;
+    prefix: string;
+    lineNumber: number;
+}
+/**
+ * One `from <module> import router [as <alias>]` discovered in a
+ * Python file.
+ *
+ * `moduleKey` is the short key (last `.`-segment of the module path,
+ * e.g. `api.users` → `users`). `moduleKeyLong` is the long key (last
+ * two segments joined with `/`, e.g. `api/users`); it is the empty
+ * string / undefined when the import is single-segment (e.g.
+ * `from users import router`) or pure-dots (e.g. `from . import
+ * router`). The long key, when present, gives parse-impl a precise
+ * way to bind a Shape-B `include_router` call to exactly one Python
+ * file even when other packages contain a same-named module.
+ */
+export interface ExtractedRouterImport {
+    filePath: string;
+    localName: string;
+    moduleKey: string;
+    moduleKeyLong?: string;
+}
+/**
+ * One `from <package> import <module>` discovered in a Python file
+ * where `<module>` is later used as a Shape-A include receiver
+ * (`<host>.include_router(<module>.router, prefix='/x')`). Without
+ * this record parse-impl would have to fall back to the short key
+ * `<module>`, which collides between e.g. `api/users.py` and
+ * `admin/users.py`. The record carries the long key
+ * (`<package>/<module>`) so parse-impl can pin the prefix onto the
+ * exact source file.
+ *
+ * Only emitted when the import path was multi-segment (a single
+ * `from users import users` would yield no long key). All fields
+ * carry the same module-key semantics as
+ * {@link ExtractedRouterImport}.
+ */
+export interface ExtractedRouterModuleAlias {
+    filePath: string;
+    /** Local name in the importing file (== imported name or its alias). */
+    localName: string;
+    /** Long key (`<parent>/<stem>`) — non-empty for every emitted record. */
+    moduleKeyLong: string;
+}
+/**
+ * Last `.`-separated segment of a (possibly relative) Python module
+ * path. Strips any leading dots first so `from .api.assistant import
+ * …` and `from api.assistant import …` both yield `assistant`.
+ * Pure-dot inputs (`.`, `..`) have no segment and return the empty
+ * string; callers should skip empty results.
+ */
+export declare function lastDottedSegment(text: string): string;
+/**
+ * Last two `.`-separated segments of a (possibly relative) module
+ * path joined with `/`, e.g. `api.users` → `api/users`. Mirrors the
+ * long-key shape used for files (`api/users.py` → `api/users`).
+ * Returns the empty string when no parent segment is available
+ * (single-segment imports or pure dots); callers should fall back
+ * to the short key in that case.
+ */
+export declare function lastTwoSegmentsAsPath(text: string): string;
+/**
+ * Scan a single Python file's source text for FastAPI router
+ * `include_router` sites and `from <module> import router` imports,
+ * appending raw records to the supplied collectors.
+ *
+ * `outModuleAliases` is optional: when supplied, every multi-segment
+ * `from <pkg> import <name>` (other than `router` itself) is recorded
+ * as a module alias so parse-impl can pin Shape-A
+ * `<name>.include_router(...)` calls onto the exact module file. When
+ * omitted, the function preserves the pre-existing behaviour and
+ * skips the alias collection — this keeps the function signature
+ * back-compat with older callers (and the parse-cache replay path).
+ */
+export declare function extractFastAPIRouterBindings(filePath: string, content: string, outIncludes: ExtractedRouterInclude[], outImports: ExtractedRouterImport[], outModuleAliases?: ExtractedRouterModuleAlias[]): void;

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

@@ -0,0 +1,208 @@
+/**
+ * FastAPI router-prefix detection — pure functions, no worker thread.
+ *
+ * NOT A WORKER. This module exports plain synchronous functions; it
+ * does not import `worker_threads`, does not call `parentPort`, and
+ * is not a new worker entry point. It lives next to the other route
+ * extractors (expo, nextjs, php, laravel) for that reason.
+ *
+ * The implementation was historically inlined in `workers/parse-worker.ts`,
+ * but parse-worker.ts is itself the worker entry point and cannot be
+ * loaded from the main thread (see the same constraint used by
+ * `test/unit/call-attribution-issue-1166.test.ts`). Splitting the pure
+ * 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
+ * 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.
+ *
+ *   • {@link ExtractedRouterImport} — every
+ *     `from <module> import router [as <alias>]`, captured for both
+ *     absolute and relative module paths (`from .calls import …`).
+ *     parse-impl uses the imports to resolve Shape-B local names back
+ *     to the file that declares the router.
+ *
+ * Module keying is two-tiered to avoid prefix bleed between same-named
+ * files in different packages (e.g. `api/users.py` vs `admin/users.py`):
+ *
+ *   • 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.
+ *
+ * The functions in this module are pure (no Worker / parentPort
+ * dependency) so they can be unit-tested directly without booting a
+ * worker thread.
+ */
+// `<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;
+// `<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;
+// 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`).
+// The latter is the common case and the only one we can map back to
+// a module stem.
+const FROM_IMPORT_ROUTER_RE = /^\s*from\s+(\.+|\.*[A-Za-z_][\w.]*)\s+import\s+([^#\n]+)/gm;
+/**
+ * Last `.`-separated segment of a (possibly relative) Python module
+ * path. Strips any leading dots first so `from .api.assistant import
+ * …` and `from api.assistant import …` both yield `assistant`.
+ * Pure-dot inputs (`.`, `..`) have no segment and return the empty
+ * string; callers should skip empty results.
+ */
+export function lastDottedSegment(text) {
+    const stripped = text.replace(/^\.+/, '');
+    if (!stripped)
+        return '';
+    const dot = stripped.lastIndexOf('.');
+    return dot >= 0 ? stripped.slice(dot + 1) : stripped;
+}
+/**
+ * Last two `.`-separated segments of a (possibly relative) module
+ * path joined with `/`, e.g. `api.users` → `api/users`. Mirrors the
+ * long-key shape used for files (`api/users.py` → `api/users`).
+ * Returns the empty string when no parent segment is available
+ * (single-segment imports or pure dots); callers should fall back
+ * to the short key in that case.
+ */
+export function lastTwoSegmentsAsPath(text) {
+    const stripped = text.replace(/^\.+/, '');
+    if (!stripped)
+        return '';
+    const last = stripped.lastIndexOf('.');
+    if (last <= 0)
+        return '';
+    const beforeLast = stripped.slice(0, last);
+    const stem = stripped.slice(last + 1);
+    const prev = beforeLast.lastIndexOf('.');
+    const parent = prev >= 0 ? beforeLast.slice(prev + 1) : beforeLast;
+    return `${parent}/${stem}`;
+}
+/**
+ * Scan a single Python file's source text for FastAPI router
+ * `include_router` sites and `from <module> import router` imports,
+ * appending raw records to the supplied collectors.
+ *
+ * `outModuleAliases` is optional: when supplied, every multi-segment
+ * `from <pkg> import <name>` (other than `router` itself) is recorded
+ * as a module alias so parse-impl can pin Shape-A
+ * `<name>.include_router(...)` calls onto the exact module file. When
+ * omitted, the function preserves the pre-existing behaviour and
+ * skips the alias collection — this keeps the function signature
+ * back-compat with older callers (and the parse-cache replay path).
+ */
+export function extractFastAPIRouterBindings(filePath, content, outIncludes, outImports, outModuleAliases) {
+    if (!content.includes('include_router') && !content.includes('router'))
+        return;
+    // `from <module> import router [as <alias>]`. We capture every name
+    // in the import list. `router` (with or without an `as` alias) maps
+    // to outImports; every other name lands in outModuleAliases when a
+    // long key is available, so Shape-A `<name>.router` includes can be
+    // pinned to the exact module file.
+    if (content.includes(' import ')) {
+        FROM_IMPORT_ROUTER_RE.lastIndex = 0;
+        let m;
+        while ((m = FROM_IMPORT_ROUTER_RE.exec(content)) !== null) {
+            const moduleText = m[1];
+            const importList = m[2];
+            const moduleShort = lastDottedSegment(moduleText);
+            if (!moduleShort)
+                continue;
+            // Long key for the imported MODULE itself (used by router
+            // imports — `from api.users import router` sets
+            // `moduleKeyLong = api/users`).
+            const moduleLong = lastTwoSegmentsAsPath(moduleText);
+            // Strip surrounding parens / trailing whitespace; split on
+            // commas. (Multiline import groups already have their newlines
+            // present in the captured list.)
+            const cleaned = importList.replace(/[()]/g, '').trim();
+            for (const rawPart of cleaned.split(',')) {
+                const part = rawPart.trim();
+                if (!part)
+                    continue;
+                // `router` or `router as foo` → ExtractedRouterImport.
+                const routerAlias = /^router(?:\s+as\s+([A-Za-z_]\w*))?$/.exec(part);
+                if (routerAlias) {
+                    const localName = routerAlias[1] ?? 'router';
+                    outImports.push({
+                        filePath,
+                        localName,
+                        moduleKey: moduleShort,
+                        ...(moduleLong ? { moduleKeyLong: moduleLong } : {}),
+                    });
+                    continue;
+                }
+                // Any other `<name>` or `<name> as <alias>` — recorded as a
+                // module alias so parse-impl can pin Shape-A includes. The
+                // long key here is computed against the IMPORTED MODULE PATH
+                // (`<moduleText>.<name>`), not the package path that `<name>`
+                // was imported FROM. `from api import users` therefore yields
+                // `api/users`, the same long key as the file it points at.
+                if (!outModuleAliases)
+                    continue;
+                const otherAlias = /^([A-Za-z_]\w*)(?:\s+as\s+([A-Za-z_]\w*))?$/.exec(part);
+                if (!otherAlias)
+                    continue;
+                const importedName = otherAlias[1];
+                const localName = otherAlias[2] ?? importedName;
+                const aliasLong = lastTwoSegmentsAsPath(`${moduleText}.${importedName}`);
+                if (!aliasLong)
+                    continue;
+                outModuleAliases.push({
+                    filePath,
+                    localName,
+                    moduleKeyLong: aliasLong,
+                });
+            }
+        }
+    }
+    if (!content.includes('include_router'))
+        return;
+    // Shape A: `<host>.include_router(<module>.router, prefix='/x')`.
+    INCLUDE_ROUTER_ATTR_RE.lastIndex = 0;
+    let m;
+    while ((m = INCLUDE_ROUTER_ATTR_RE.exec(content)) !== null) {
+        outIncludes.push({
+            filePath,
+            routerExpr: `${m[1]}.router`,
+            prefix: m[3],
+            lineNumber: content.substring(0, m.index).split('\n').length,
+        });
+    }
+    // Shape B: `<host>.include_router(my_router, prefix='/x')`.
+    // Resolution to a module key happens in parse-impl using
+    // outImports from the same file.
+    INCLUDE_ROUTER_NAME_RE.lastIndex = 0;
+    while ((m = INCLUDE_ROUTER_NAME_RE.exec(content)) !== null) {
+        // Skip cases that already matched Shape A — INCLUDE_ROUTER_NAME_RE
+        // 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);
+        if (/^\s*\.\s*router/.test(dotProbe))
+            continue;
+        outIncludes.push({
+            filePath,
+            routerExpr: m[1],
+            prefix: m[3],
+            lineNumber: content.substring(0, m.index).split('\n').length,
+        });
+    }
+}

package/dist/core/ingestion/workers/parse-worker.d.ts

@@ -1,5 +1,6 @@
 import { SupportedLanguages } from '../../../_shared/index.js';
 import type { ExtractedHeritage } from '../model/heritage-map.js';
+import type { ExtractedRouterInclude, ExtractedRouterImport, ExtractedRouterModuleAlias } from '../route-extractors/fastapi-router-bindings.js';
 import { type MixedChainStep } from '../utils/call-analysis.js';
 import type { ConstructorBinding } from '../type-env.js';
 import type { NamedBinding } from '../named-bindings/types.js';
@@ -111,6 +112,19 @@ export interface ExtractedDecoratorRoute {
     httpMethod: string;
     decoratorName: string;
     lineNumber: number;
+    /**
+     * Decorator receiver identifier (e.g. `router` for `@router.get(...)`,
+     * `app` for `@app.get(...)`). Used by parse-impl to decide which routes
+     * participate in `include_router(prefix=...)` joining.
+     */
+    decoratorReceiver?: string;
+    /**
+     * FastAPI `app.include_router(prefix='/x')` prefix that applies to
+     * this route. Filled by parse-impl after cross-file aggregation; the
+     * routes phase joins it via `normalizeExtractedRoutePath`. `null` /
+     * absent ⇒ no prefix applies.
+     */
+    prefix?: string | null;
 }
 export interface ExtractedToolDef {
     filePath: string;
@@ -172,6 +186,18 @@ export interface ParseWorkerResult {
     fetchCalls: ExtractedFetchCall[];
     fetchWrapperDefs: FetchWrapperDef[];
     decoratorRoutes: ExtractedDecoratorRoute[];
+    routerIncludes: ExtractedRouterInclude[];
+    routerImports: ExtractedRouterImport[];
+    /**
+     * Optional. `from <pkg> import <module>` records from Python files
+     * where `<module>` is later used as a Shape-A include receiver
+     * (`<host>.include_router(<module>.router, prefix='/x')`). parse-impl
+     * uses these to promote Shape-A short-key entries to long keys, so
+     * same-named modules in different packages don't share prefixes.
+     * Optional for cache backward compatibility (older cache entries
+     * predate the field; consumers must guard with `if (… ?? [])`).
+     */
+    routerModuleAliases?: ExtractedRouterModuleAlias[];
     toolDefs: ExtractedToolDef[];
     ormQueries: ExtractedORMQuery[];
     constructorBindings: FileConstructorBindings[];

package/dist/core/ingestion/workers/parse-worker.js

@@ -434,6 +434,9 @@ const processBatch = (files, onProgress) => {
         fetchCalls: [],
         fetchWrapperDefs: [],
         decoratorRoutes: [],
+        routerIncludes: [],
+        routerImports: [],
+        routerModuleAliases: [],
         toolDefs: [],
         ormQueries: [],
         constructorBindings: [],
@@ -649,6 +652,16 @@ export function extractORMQueries(filePath, content, out) {
         }
     }
 }
+// ============================================================================
+// FastAPI router prefix detection (Python)
+// ============================================================================
+//
+// The extraction lives in `../route-extractors/fastapi-router-bindings`
+// (a pure-function module — NOT a worker, no `worker_threads`, no
+// `parentPort`). It's imported here only so the worker entry can call it
+// per file; this module does not re-export it. Downstream consumers
+// import the function and its types directly from `route-extractors/`.
+import { extractFastAPIRouterBindings } from '../route-extractors/fastapi-router-bindings.js';
 const processFileGroup = (files, language, queryString, result, onFileProcessed) => {
     let query;
     try {
@@ -849,6 +862,7 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
             if (captureMap['decorator'] && captureMap['decorator.name']) {
                 const decoratorName = captureMap['decorator.name'].text;
                 const decoratorArg = captureMap['decorator.arg']?.text;
+                const decoratorReceiver = captureMap['decorator.receiver']?.text;
                 const decoratorNode = captureMap['decorator'];
                 // Store by the decorator's end line — the definition follows immediately after
                 fileDecorators.set(decoratorNode.endPosition.row, {
@@ -867,6 +881,7 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                         httpMethod,
                         decoratorName,
                         lineNumber: decoratorNode.startPosition.row + lineOffset,
+                        ...(decoratorReceiver ? { decoratorReceiver } : {}),
                     });
                 }
                 // MCP/RPC tool detection: @mcp.tool(), @app.tool(), @server.tool()
@@ -1546,6 +1561,13 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
         }
         // Extract ORM queries (Prisma, Supabase)
         extractORMQueries(file.path, parseContent, result.ormQueries);
+        // Extract FastAPI include_router(prefix=...) and `from <mod> import router`
+        // sites. parse-impl aggregates these into a per-module prefix map and
+        // injects the resolved prefix onto each ExtractedDecoratorRoute that
+        // came from a `@router.<verb>` decorator. Python-only.
+        if (language === SupportedLanguages.Python) {
+            extractFastAPIRouterBindings(file.path, parseContent, result.routerIncludes, result.routerImports, (result.routerModuleAliases ??= []));
+        }
         // Vue: emit CALLS edges for components used in <template>
         if (language === SupportedLanguages.Vue) {
             const templateComponents = extractTemplateComponents(file.content);
@@ -1576,6 +1598,9 @@ let accumulated = {
     fetchCalls: [],
     fetchWrapperDefs: [],
     decoratorRoutes: [],
+    routerIncludes: [],
+    routerImports: [],
+    routerModuleAliases: [],
     toolDefs: [],
     ormQueries: [],
     constructorBindings: [],
@@ -1604,6 +1629,14 @@ const mergeResult = (target, src) => {
     appendAll(target.fetchCalls, src.fetchCalls);
     appendAll(target.fetchWrapperDefs, src.fetchWrapperDefs);
     appendAll(target.decoratorRoutes, src.decoratorRoutes);
+    if (src.routerIncludes)
+        appendAll(target.routerIncludes, src.routerIncludes);
+    if (src.routerImports)
+        appendAll(target.routerImports, src.routerImports);
+    if (src.routerModuleAliases) {
+        target.routerModuleAliases ??= [];
+        appendAll(target.routerModuleAliases, src.routerModuleAliases);
+    }
     appendAll(target.toolDefs, src.toolDefs);
     appendAll(target.ormQueries, src.ormQueries);
     appendAll(target.constructorBindings, src.constructorBindings);
@@ -1687,6 +1720,9 @@ parentPort.on('message', (msg) => {
                 fetchCalls: [],
                 fetchWrapperDefs: [],
                 decoratorRoutes: [],
+                routerIncludes: [],
+                routerImports: [],
+                routerModuleAliases: [],
                 toolDefs: [],
                 ormQueries: [],
                 constructorBindings: [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.6-rc.81",
+  "version": "1.6.6-rc.82",
   "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",