gitnexus 1.6.9-rc.25 → 1.6.9-rc.27

package/README.md

@@ -363,6 +363,7 @@ Configure the behavior with two environment variables:
 | -------------------------------------------- | ---------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `GITNEXUS_LBUG_EXTENSION_INSTALL`            | `auto`, `load-only`, `never` | `auto`              | `auto` runs one bounded INSTALL if LOAD fails. `load-only` only uses already-installed extensions (recommended for offline / firewalled environments). `never` skips optional extensions entirely.                                                                                       |
 | `GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS` | positive integer             | `15000`             | Wall-clock budget for the out-of-process `INSTALL` child before it is killed.                                                                                                                                                                                                            |
+| `GITNEXUS_FTS_STEMMER`                       | supported LadybugDB stemmer  | `porter`            | Stemmer used when rebuilding BM25/FTS indexes. Use `none` for CJK-heavy repositories, or a language stemmer such as `german`, `french`, or `spanish` when that better matches repository comments and identifiers. Re-run `gitnexus analyze --repair-fts` after changing it.              |
 | `GITNEXUS_WAL_CHECKPOINT_THRESHOLD`          | integer `>= -1`              | `67108864` (64 MiB) | LadybugDB WAL auto-checkpoint threshold during analyze (bytes). Auto-checkpoint remains enabled; `-1` keeps Ladybug's stock ~16 MiB. Larger thresholds reduce checkpoint frequency but increase the WAL size at rotation time — choose a smaller value on disk-constrained environments. |
 
 ```bash
@@ -371,6 +372,9 @@ GITNEXUS_LBUG_EXTENSION_INSTALL=load-only npx gitnexus analyze
 
 # Slow network: give extension downloads more time
 GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS=30000 npx gitnexus analyze
+
+# CJK-heavy codebase: rebuild keyword indexes without English stemming
+GITNEXUS_FTS_STEMMER=none npx gitnexus analyze --repair-fts
 ```
 
 ### Analysis runs out of memory

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

@@ -1,5 +1,6 @@
 import Python from 'tree-sitter-python';
 import { compilePatterns, runCompiledPatterns, unquoteLiteral, } from '../tree-sitter-scanner.js';
+import { normalizeExtractedRoutePath } from '../../../ingestion/route-extractors/route-path.js';
 /**
  * Python HTTP plugin. Handles:
  *   - FastAPI `@app.get("/path")` provider decorators
@@ -146,6 +147,25 @@ const INCLUDE_ROUTER_NAME_PATTERNS = compilePatterns({
         },
     ],
 });
+const API_ROUTER_PREFIX_PATTERNS = compilePatterns({
+    name: 'python-fastapi-apirouter-prefix',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (assignment
+          left: (identifier) @router_name (#eq? @router_name "router")
+          right: (call
+            function: (identifier) @factory (#eq? @factory "APIRouter")
+            arguments: (argument_list
+              (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.
@@ -813,10 +833,10 @@ function recordPrefix(target, key, prefix) {
 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.
+    // Cross-file pre-pass: only `include_router` sites need it — they bind a
+    // prefix declared in one file to a router defined in another. Same-file
+    // `APIRouter(prefix=...)` is resolved in scan() from the file's own tree, so
+    // APIRouter-only files are left out here and never parsed twice.
     for (const rel of files) {
         if (!rel.endsWith('.py'))
             continue;
@@ -912,14 +932,16 @@ function buildPythonRepoContext(files, parser, readFile, parseSource) {
             }
         }
     }
-    return { prefixesByLongKey, prefixesByShortKey };
+    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}`;
+    // Delegate to the shared route-path normalizer so the group contract and the
+    // ingestion Route node join prefixes identically — one helper, no
+    // trailing-slash drift on empty routes (`APIRouter(prefix="/x")` + `@get("")`).
+    return normalizeExtractedRoutePath(route, prefix);
 }
 export const PYTHON_HTTP_PLUGIN = {
     name: 'python-http',
@@ -979,6 +1001,19 @@ export const PYTHON_HTTP_PLUGIN = {
         // Django providers come from the graph Route nodes (includes composed by
         // the ingestion route extractor), not a per-file source scan — see the note
         // at the top of this file.
+        // Same-file `router = APIRouter(prefix="/x")` (router-only). Read from this
+        // file's own tree, so there is no cross-file map and no prefix bleed across
+        // same-stem files; it stacks under any include_router(prefix=...) below.
+        let constructorPrefix;
+        for (const m of runCompiledPatterns(API_ROUTER_PREFIX_PATTERNS, tree)) {
+            const prefixNode = m.captures.prefix;
+            if (!prefixNode)
+                continue;
+            const p = unquoteLiteral(prefixNode.text);
+            if (p === null)
+                continue;
+            constructorPrefix = p;
+        }
         // 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
@@ -1004,9 +1039,12 @@ export const PYTHON_HTTP_PLUGIN = {
             const shortKey = fileRel ? fileShortKey(fileRel) : '';
             const shortPrefixes = longPrefixes || !shortKey ? undefined : ctx?.prefixesByShortKey.get(shortKey);
             const prefixSet = longPrefixes ?? shortPrefixes;
+            // Stack the same-file APIRouter(prefix=...) under any cross-file
+            // include_router prefix.
+            const localPath = constructorPrefix ? joinPrefix(constructorPrefix, rawPath) : rawPath;
             const paths = prefixSet && prefixSet.size > 0
-                ? [...prefixSet].map((p) => joinPrefix(p, rawPath))
-                : [rawPath];
+                ? [...prefixSet].map((p) => joinPrefix(p, localPath))
+                : [localPath];
             for (const p of paths) {
                 out.push({
                     role: 'provider',

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

@@ -4,7 +4,7 @@ import { type ExportedTypeMap } from './call-processor.js';
 import type { ParsedFile } from '../../_shared/index.js';
 import { WorkerPool } from './workers/worker-pool.js';
 import type { ParseWorkerResult, ExtractedRoute, ExtractedFetchCall, ExtractedDecoratorRoute, ExtractedToolDef, FileScopeBindings, ExtractedORMQuery, FetchWrapperDef } from './workers/parse-worker.js';
-import type { ExtractedRouterImport, ExtractedRouterInclude, ExtractedRouterModuleAlias } from './route-extractors/fastapi-router-bindings.js';
+import type { ExtractedRouterConstructorPrefix, ExtractedRouterImport, ExtractedRouterInclude, ExtractedRouterModuleAlias } from './route-extractors/fastapi-router-bindings.js';
 import type { SharedSpringType } from './route-extractors/spring-shared.js';
 export type FileProgressCallback = (current: number, total: number, filePath: string) => void;
 export interface WorkerExtractedData {
@@ -14,6 +14,7 @@ export interface WorkerExtractedData {
     decoratorRoutes: ExtractedDecoratorRoute[];
     routerIncludes: ExtractedRouterInclude[];
     routerImports: ExtractedRouterImport[];
+    routerConstructorPrefixes: ExtractedRouterConstructorPrefix[];
     routerModuleAliases: ExtractedRouterModuleAlias[];
     toolDefs: ExtractedToolDef[];
     ormQueries: ExtractedORMQuery[];

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

@@ -22,6 +22,7 @@ export const mergeChunkResults = (graph, symbolTable, chunkResults, exportedType
     const allDecoratorRoutes = [];
     const allRouterIncludes = [];
     const allRouterImports = [];
+    const allRouterConstructorPrefixes = [];
     const allRouterModuleAliases = [];
     const allSpringTypes = [];
     const allToolDefs = [];
@@ -70,6 +71,9 @@ export const mergeChunkResults = (graph, symbolTable, chunkResults, exportedType
             allRouterIncludes.push(item);
         for (const item of result.routerImports ?? [])
             allRouterImports.push(item);
+        for (const item of result.routerConstructorPrefixes ?? []) {
+            allRouterConstructorPrefixes.push(item);
+        }
         for (const item of result.routerModuleAliases ?? [])
             allRouterModuleAliases.push(item);
         for (const item of result.springTypes ?? [])
@@ -93,6 +97,7 @@ export const mergeChunkResults = (graph, symbolTable, chunkResults, exportedType
         decoratorRoutes: allDecoratorRoutes,
         routerIncludes: allRouterIncludes,
         routerImports: allRouterImports,
+        routerConstructorPrefixes: allRouterConstructorPrefixes,
         routerModuleAliases: allRouterModuleAliases,
         toolDefs: allToolDefs,
         ormQueries: allORMQueries,

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

@@ -27,6 +27,7 @@ import { isLanguageAvailable, isGrammarRuntimeSkipped, createParserForLanguage,
 import { parseSourceSafe } from '../../tree-sitter/safe-parse.js';
 import { getProvider, providers } from '../languages/index.js';
 import { createWorkerPool, workerPoolDisabledByEnv, resolveAutoPoolSize, WorkerPoolInitializationError, WorkerPoolDisabledError, } from '../workers/worker-pool.js';
+import { normalizeExtractedRoutePath } from '../route-extractors/route-path.js';
 import { resolveInheritedSpringRoutes, } from '../route-extractors/spring-shared.js';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -461,6 +462,7 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     const allDecoratorRoutes = [];
     const allRouterIncludes = [];
     const allRouterImports = [];
+    const allRouterConstructorPrefixes = [];
     const allRouterModuleAliases = [];
     const allSpringTypes = [];
     const allToolDefs = [];
@@ -599,6 +601,11 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                     for (const item of chunkWorkerData.routerImports)
                         allRouterImports.push(item);
                 }
+                if (chunkWorkerData.routerConstructorPrefixes?.length) {
+                    for (const item of chunkWorkerData.routerConstructorPrefixes) {
+                        allRouterConstructorPrefixes.push(item);
+                    }
+                }
                 if (chunkWorkerData.routerModuleAliases?.length) {
                     for (const item of chunkWorkerData.routerModuleAliases)
                         allRouterModuleAliases.push(item);
@@ -932,7 +939,8 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     // 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) {
+    if ((allRouterIncludes.length > 0 || allRouterConstructorPrefixes.length > 0) &&
+        allDecoratorRoutes.length > 0) {
         const importsByFile = new Map();
         for (const imp of allRouterImports) {
             let m = importsByFile.get(imp.filePath);
@@ -965,6 +973,11 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         // without a corresponding import statement).
         const prefixesByLongKey = new Map();
         const prefixesByShortKey = new Map();
+        // Constructor prefixes are `router`-only (the apply gate below and the
+        // group-layer tree-sitter both pin to the literal name `router`), so a
+        // flat file-key → prefix map suffices — mirrors the group layer's shape.
+        const constructorPrefixesByLongKey = new Map();
+        const constructorPrefixesByShortKey = new Map();
         const recordPrefix = (target, key, prefix) => {
             let set = target.get(key);
             if (!set) {
@@ -1004,7 +1017,9 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                 recordPrefix(prefixesByShortKey, localImp.moduleKey, inc.prefix);
             }
         }
-        if (prefixesByLongKey.size > 0 || prefixesByShortKey.size > 0) {
+        if (prefixesByLongKey.size > 0 ||
+            prefixesByShortKey.size > 0 ||
+            allRouterConstructorPrefixes.length > 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,
@@ -1025,6 +1040,15 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                 const file = slash >= 0 ? rel.slice(slash + 1) : rel;
                 return file.endsWith('.py') ? file.slice(0, -3) : file;
             };
+            for (const ctor of allRouterConstructorPrefixes) {
+                const longKey = fileLongKey(ctor.filePath);
+                if (longKey) {
+                    constructorPrefixesByLongKey.set(longKey, ctor.prefix);
+                }
+                else {
+                    constructorPrefixesByShortKey.set(fileShortKey(ctor.filePath), ctor.prefix);
+                }
+            }
             const expanded = [];
             for (const dr of allDecoratorRoutes) {
                 if (dr.decoratorReceiver !== 'router' || !dr.filePath.endsWith('.py')) {
@@ -1040,12 +1064,24 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                     ? undefined
                     : prefixesByShortKey.get(fileShortKey(dr.filePath));
                 const prefixes = 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`
+                // returns ''. Do not fall back from a missing long-key match to the
+                // short key or a root `users.py` prefix can leak onto
+                // `admin/users.py`.
+                const constructorPrefix = longKey
+                    ? constructorPrefixesByLongKey.get(longKey)
+                    : constructorPrefixesByShortKey.get(fileShortKey(dr.filePath));
+                const routePath = constructorPrefix
+                    ? normalizeExtractedRoutePath(dr.routePath, constructorPrefix)
+                    : dr.routePath;
                 if (!prefixes || prefixes.size === 0) {
-                    expanded.push(dr);
+                    expanded.push(routePath === dr.routePath ? dr : { ...dr, routePath });
                     continue;
                 }
                 for (const prefix of prefixes) {
-                    expanded.push({ ...dr, prefix });
+                    expanded.push({ ...dr, routePath, prefix });
                 }
             }
             allDecoratorRoutes.length = 0;

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

@@ -101,6 +101,10 @@ export interface ExtractedRouterModuleAlias {
     /** Long key (`<parent>/<stem>`) — non-empty for every emitted record. */
     moduleKeyLong: string;
 }
+export interface ExtractedRouterConstructorPrefix {
+    filePath: string;
+    prefix: string;
+}
 /**
  * Last `.`-separated segment of a (possibly relative) Python module
  * path. Strips any leading dots first so `from .api.assistant import
@@ -131,4 +135,4 @@ export declare function lastTwoSegmentsAsPath(text: string): string;
  * 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;
+export declare function extractFastAPIRouterBindings(filePath: string, content: string, outIncludes: ExtractedRouterInclude[], outImports: ExtractedRouterImport[], outModuleAliases?: ExtractedRouterModuleAlias[], outConstructorPrefixes?: ExtractedRouterConstructorPrefix[]): void;

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

@@ -59,6 +59,8 @@ const INCLUDE_ROUTER_NAME_RE = /\b(?:[A-Za-z_][\w.]*)\.include_router\s*\(\s*([A
 // 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;
+const API_ROUTER_ASSIGN_RE = /\brouter\s*=\s*APIRouter\s*\(/g;
+const API_ROUTER_PREFIX_ARG_RE = /\bprefix\s*=\s*(['"])([^'"]*)\1/;
 /**
  * Last `.`-separated segment of a (possibly relative) Python module
  * path. Strips any leading dots first so `from .api.assistant import
@@ -94,6 +96,36 @@ export function lastTwoSegmentsAsPath(text) {
     const parent = prev >= 0 ? beforeLast.slice(prev + 1) : beforeLast;
     return `${parent}/${stem}`;
 }
+function findMatchingParen(content, openIndex) {
+    let depth = 0;
+    let quote = null;
+    for (let i = openIndex; i < content.length; i++) {
+        const ch = content[i];
+        if (quote) {
+            if (ch === '\\') {
+                i++;
+                continue;
+            }
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (ch === '(' || ch === '[' || ch === '{') {
+            depth++;
+            continue;
+        }
+        if (ch === ')' || ch === ']' || ch === '}') {
+            depth--;
+            if (depth === 0 && ch === ')')
+                return i;
+        }
+    }
+    return -1;
+}
 /**
  * Scan a single Python file's source text for FastAPI router
  * `include_router` sites and `from <module> import router` imports,
@@ -107,7 +139,7 @@ export function lastTwoSegmentsAsPath(text) {
  * 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) {
+export function extractFastAPIRouterBindings(filePath, content, outIncludes, outImports, outModuleAliases, outConstructorPrefixes) {
     if (!content.includes('include_router') && !content.includes('router'))
         return;
     // `from <module> import router [as <alias>]`. We capture every name
@@ -172,6 +204,25 @@ export function extractFastAPIRouterBindings(filePath, content, outIncludes, out
             }
         }
     }
+    if (outConstructorPrefixes && content.includes('APIRouter') && content.includes('prefix')) {
+        API_ROUTER_ASSIGN_RE.lastIndex = 0;
+        // Only `router = APIRouter(...)` is captured (the apply gate and the
+        // group-layer tree-sitter both pin to the literal name `router`).
+        while (API_ROUTER_ASSIGN_RE.exec(content) !== null) {
+            const openParen = API_ROUTER_ASSIGN_RE.lastIndex - 1;
+            const closeParen = findMatchingParen(content, openParen);
+            if (closeParen < 0)
+                continue;
+            const args = content.slice(openParen + 1, closeParen);
+            const prefixMatch = API_ROUTER_PREFIX_ARG_RE.exec(args);
+            if (!prefixMatch)
+                continue;
+            outConstructorPrefixes.push({
+                filePath,
+                prefix: prefixMatch[2],
+            });
+        }
+    }
     if (!content.includes('include_router'))
         return;
     // Shape A: `<host>.include_router(<module>.router, prefix='/x')`.

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

@@ -1,6 +1,6 @@
 import { SupportedLanguages } from '../../../_shared/index.js';
 import type { SkippedPath } from './clone-safety.js';
-import type { ExtractedRouterInclude, ExtractedRouterImport, ExtractedRouterModuleAlias } from '../route-extractors/fastapi-router-bindings.js';
+import type { ExtractedRouterConstructorPrefix, 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 { NodeLabel, ParameterTypeClass } from '../../../_shared/index.js';
@@ -191,6 +191,7 @@ export interface ParseWorkerResult {
     decoratorRoutes: ExtractedDecoratorRoute[];
     routerIncludes: ExtractedRouterInclude[];
     routerImports: ExtractedRouterImport[];
+    routerConstructorPrefixes?: ExtractedRouterConstructorPrefix[];
     /**
      * Optional. Project-wide `SharedSpringType` view of route-defining
      * class/interface declarations, produced by the provider's

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

@@ -504,6 +504,7 @@ const processBatch = (files, onProgress) => {
         decoratorRoutes: [],
         routerIncludes: [],
         routerImports: [],
+        routerConstructorPrefixes: [],
         routerModuleAliases: [],
         toolDefs: [],
         ormQueries: [],
@@ -1821,7 +1822,7 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
         // 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 ??= []));
+            extractFastAPIRouterBindings(file.path, parseContent, result.routerIncludes, result.routerImports, (result.routerModuleAliases ??= []), (result.routerConstructorPrefixes ??= []));
         }
         // Language-specific decorator route extraction via provider hook.
         // The provider's extractDecoratorRoutes walks the AST for framework-specific
@@ -1870,6 +1871,7 @@ let accumulated = {
     decoratorRoutes: [],
     routerIncludes: [],
     routerImports: [],
+    routerConstructorPrefixes: [],
     routerModuleAliases: [],
     toolDefs: [],
     ormQueries: [],
@@ -1989,6 +1991,7 @@ parentPort.on('message', (msg) => {
                 decoratorRoutes: [],
                 routerIncludes: [],
                 routerImports: [],
+                routerConstructorPrefixes: [],
                 routerModuleAliases: [],
                 toolDefs: [],
                 ormQueries: [],

package/dist/core/ingestion/workers/result-merge.js

@@ -24,6 +24,10 @@ export const mergeResult = (target, src) => {
         appendAll(target.routerIncludes, src.routerIncludes);
     if (src.routerImports)
         appendAll(target.routerImports, src.routerImports);
+    if (src.routerConstructorPrefixes) {
+        target.routerConstructorPrefixes ??= [];
+        appendAll(target.routerConstructorPrefixes, src.routerConstructorPrefixes);
+    }
     if (src.routerModuleAliases) {
         target.routerModuleAliases ??= [];
         appendAll(target.routerModuleAliases, src.routerModuleAliases);

package/dist/core/lbug/lbug-adapter.d.ts

@@ -286,6 +286,12 @@ export declare const loadFTSExtension: (targetConn?: lbug.Connection, opts?: Ext
  * unavailable so semantic search can fall back to exact scan.
  */
 export declare const loadVectorExtension: (targetConn?: lbug.Connection, opts?: ExtensionEnsureOptions) => Promise<boolean>;
+/**
+ * Default stemmer for FTS indexes. Single source so the analyze path
+ * (`getSearchFTSStemmer`) and the read-only `createFTSIndex`/`ensureFTSIndex`
+ * defaults can never silently diverge.
+ */
+export declare const DEFAULT_FTS_STEMMER = "porter";
 /**
  * Create a full-text search index on a table
  * @param tableName - The node table name (e.g., 'File', 'CodeSymbol')

package/dist/core/lbug/lbug-adapter.js

@@ -2081,6 +2081,12 @@ export const loadVectorExtension = async (targetConn, opts = {}) => {
         vectorExtensionLoaded = true;
     return loaded;
 };
+/**
+ * Default stemmer for FTS indexes. Single source so the analyze path
+ * (`getSearchFTSStemmer`) and the read-only `createFTSIndex`/`ensureFTSIndex`
+ * defaults can never silently diverge.
+ */
+export const DEFAULT_FTS_STEMMER = 'porter';
 /**
  * Create a full-text search index on a table
  * @param tableName - The node table name (e.g., 'File', 'CodeSymbol')
@@ -2088,7 +2094,7 @@ export const loadVectorExtension = async (targetConn, opts = {}) => {
  * @param properties - List of properties to index (e.g., ['name', 'code'])
  * @param stemmer - Stemming algorithm (default: 'porter')
  */
-export const createFTSIndex = async (tableName, indexName, properties, stemmer = 'porter') => {
+export const createFTSIndex = async (tableName, indexName, properties, stemmer = DEFAULT_FTS_STEMMER) => {
     if (!conn) {
         throw new Error('LadybugDB not initialized. Call initLbug first.');
     }
@@ -2176,7 +2182,7 @@ export const createVectorIndex = async () => {
  * the index is owned by `gitnexus analyze` (writable) and either already
  * exists or will be created on the next analyze.
  */
-export const ensureFTSIndex = async (tableName, indexName, properties, stemmer = 'porter') => {
+export const ensureFTSIndex = async (tableName, indexName, properties, stemmer = DEFAULT_FTS_STEMMER) => {
     const key = ftsIndexKey(tableName, indexName);
     if (ensuredFTSIndexes.has(key))
         return;

package/dist/core/run-analyze.js

@@ -14,7 +14,7 @@ import { execFileSync } from 'child_process';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
 import { resetDegradedParseCounter } from './tree-sitter/safe-parse.js';
 import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, closeLbugBeforeExit, loadCachedEmbeddings, deleteNodesForFile, deleteAllCommunitiesAndProcesses, deleteAllInterprocTaintPaths, deleteAllCallSummaries, queryImporters, loadFTSExtension, } from './lbug/lbug-adapter.js';
-import { createSearchFTSIndexes, verifySearchFTSIndexes } from './search/fts-indexes.js';
+import { createSearchFTSIndexes, initialiseSearchFTSStemmer, verifySearchFTSIndexes, } from './search/fts-indexes.js';
 import { resolveAnalyzeInstallPolicy } from './lbug/extension-loader.js';
 import { startWalCheckpointDriver, } from './lbug/wal-checkpoint-driver.js';
 import { getStoragePaths, resolveBranchPlacement, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, isRepoRegistered, cleanupOldKuzuFiles, INCREMENTAL_SCHEMA_VERSION, } from '../storage/repo-manager.js';
@@ -255,6 +255,10 @@ export const pdgModeMismatch = (recorded, options) => {
 export async function runFullAnalysis(repoPath, options, callbacks) {
     const log = (msg) => callbacks.onLog?.(msg);
     const progress = (phase, percent, message) => callbacks.onProgress(phase, percent, message);
+    // Resolve + validate operator-provided FTS config once, before the expensive
+    // parse/load phases. A typo fails here in ms; createSearchFTSIndexes reuses
+    // the cached value via getSearchFTSStemmer.
+    initialiseSearchFTSStemmer();
     // Scope the degraded-parse log throttle to this run. On a reused process
     // (e.g. tests, or any host that calls runFullAnalysis more than once) the
     // module-level counter would otherwise stay saturated and suppress every

package/dist/core/search/fts-indexes.d.ts

@@ -2,5 +2,19 @@ export interface CreateSearchFTSIndexesOptions {
     onIndexStart?: (table: string, indexName: string) => void;
     onIndexReady?: (table: string, indexName: string) => void;
 }
+/**
+ * Resolve + validate `GITNEXUS_FTS_STEMMER` once, up front at analyze startup,
+ * and cache it. An invalid value throws here — in milliseconds — instead of
+ * ~85% into a run (after the expensive parse/scope-resolution work). The cached
+ * value is what {@link getSearchFTSStemmer} returns for the rest of the run, so
+ * config is read and validated in exactly one place.
+ */
+export declare function initialiseSearchFTSStemmer(): string;
+/**
+ * Return the stemmer resolved by {@link initialiseSearchFTSStemmer}. Falls back
+ * to resolving on demand when init was never called (read-only hosts, unit
+ * tests) so validation always applies.
+ */
+export declare function getSearchFTSStemmer(): string;
 export declare function createSearchFTSIndexes(options?: CreateSearchFTSIndexesOptions): Promise<void>;
 export declare function verifySearchFTSIndexes(executeQuery: (cypher: string) => Promise<unknown[]>): Promise<string[]>;

package/dist/core/search/fts-indexes.js

@@ -1,6 +1,71 @@
-import { createFTSIndex, dropFTSIndex } from '../lbug/lbug-adapter.js';
+import { createFTSIndex, dropFTSIndex, DEFAULT_FTS_STEMMER } from '../lbug/lbug-adapter.js';
 import { FTS_INDEXES } from './fts-schema.js';
+// Stemmers shipped by the LadybugDB FTS extension. Mirrors the lowercase token
+// set in the extension bundled with @ladybugdb/core 0.17.x (see package.json).
+// Keep in sync on a LadybugDB minor bump — a value here that the installed
+// extension rejects would pass validation but fail at CREATE_FTS_INDEX.
+const SUPPORTED_FTS_STEMMERS = new Set([
+    'arabic',
+    'basque',
+    'catalan',
+    'danish',
+    'dutch',
+    'english',
+    'finnish',
+    'french',
+    'german',
+    'greek',
+    'hindi',
+    'hungarian',
+    'indonesian',
+    'irish',
+    'italian',
+    'lithuanian',
+    'nepali',
+    'norwegian',
+    'none',
+    'porter',
+    'portuguese',
+    'romanian',
+    'russian',
+    'serbian',
+    'spanish',
+    'swedish',
+    'tamil',
+    'turkish',
+]);
+let resolvedStemmer;
+/** Read + validate `GITNEXUS_FTS_STEMMER`. Throws on an unsupported value. */
+function resolveFTSStemmer() {
+    const raw = process.env.GITNEXUS_FTS_STEMMER?.trim().toLowerCase();
+    if (!raw)
+        return DEFAULT_FTS_STEMMER;
+    if (SUPPORTED_FTS_STEMMERS.has(raw))
+        return raw;
+    throw new Error(`Invalid GITNEXUS_FTS_STEMMER "${process.env.GITNEXUS_FTS_STEMMER}". ` +
+        `Expected one of: ${[...SUPPORTED_FTS_STEMMERS].sort().join(', ')}.`);
+}
+/**
+ * Resolve + validate `GITNEXUS_FTS_STEMMER` once, up front at analyze startup,
+ * and cache it. An invalid value throws here — in milliseconds — instead of
+ * ~85% into a run (after the expensive parse/scope-resolution work). The cached
+ * value is what {@link getSearchFTSStemmer} returns for the rest of the run, so
+ * config is read and validated in exactly one place.
+ */
+export function initialiseSearchFTSStemmer() {
+    resolvedStemmer = resolveFTSStemmer();
+    return resolvedStemmer;
+}
+/**
+ * Return the stemmer resolved by {@link initialiseSearchFTSStemmer}. Falls back
+ * to resolving on demand when init was never called (read-only hosts, unit
+ * tests) so validation always applies.
+ */
+export function getSearchFTSStemmer() {
+    return resolvedStemmer ?? resolveFTSStemmer();
+}
 export async function createSearchFTSIndexes(options) {
+    const stemmer = getSearchFTSStemmer();
     for (const { table, indexName, properties } of FTS_INDEXES) {
         options?.onIndexStart?.(table, indexName);
         // Drop first so the live `properties` always win. `createFTSIndex` is
@@ -15,7 +80,7 @@ export async function createSearchFTSIndexes(options) {
         // runs inside the existing FTS phase. Gate on a stored schema fingerprint if
         // this rebuild cost ever shows up in analyze profiles.
         await dropFTSIndex(table, indexName);
-        await createFTSIndex(table, indexName, [...properties]);
+        await createFTSIndex(table, indexName, [...properties], stemmer);
         options?.onIndexReady?.(table, indexName);
     }
 }

package/dist/storage/parse-cache.js

@@ -52,7 +52,7 @@ import { fileURLToPath } from 'url';
 // the main thread (the #1983 OOM). Because the two stores share this version,
 // any future change to the `ParsedFile` serialization shape MUST bump
 // SCHEMA_BUMP so both invalidate in lockstep.
-const SCHEMA_BUMP = 8; // #2288: ParseWorkerResult gained `springTypes` (Spring interface-inheritance) + `decoratorRoutes` semantics changed (interface routes suppressed at extraction, inherited routes appended in parse-impl)
+const SCHEMA_BUMP = 9; // #2312: ParseWorkerResult gained `routerConstructorPrefixes` for FastAPI APIRouter(prefix=...) replay
 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.9-rc.25",
+  "version": "1.6.9-rc.27",
   "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",