gitnexus 1.6.10-rc.2 → 1.6.10-rc.21

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

@@ -751,6 +751,7 @@ export function extractORMQueries(filePath, content, out) {
 // 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';
+import { extractPythonModuleConstants, parseConstOperands, } from '../route-extractors/python-const-resolver.js';
 /**
  * Report a non-fatal worker issue to the pool over IPC so a caught error is not
  * invisible to the operator (#2264). The pool logs it on the main thread AND
@@ -813,7 +814,7 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
         try {
             tree = parseSourceSafe(parser, parseContent, undefined, {
                 bufferSize: getTreeSitterBufferSize(parseContent),
-            });
+            }, file.path);
         }
         catch (err) {
             reportWarning(`Failed to parse file ${file.path}: ${err instanceof Error ? err.message : String(err)}`);
@@ -986,6 +987,12 @@ 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;
+                // #2391: the first positional arg captured as either a string node
+                // (`arg_str`, present even for the empty-string literal `""` which has no
+                // `string_content`) or a non-literal expression (`arg_expr`: an
+                // identifier or a `+`-concatenation).
+                const decoratorArgStr = captureMap['decorator.arg_str'];
+                const decoratorArgExpr = captureMap['decorator.arg_expr'];
                 const decoratorReceiver = captureMap['decorator.receiver']?.text;
                 const decoratorNode = captureMap['decorator'];
                 // Store by the decorator's end line — the definition follows immediately after
@@ -994,19 +1001,39 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                     arg: decoratorArg,
                 });
                 if (ROUTE_DECORATOR_NAMES.has(decoratorName)) {
-                    const routePath = decoratorArg || '';
                     const method = decoratorName.replace('Mapping', '').toUpperCase();
                     const httpMethod = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'].includes(method)
                         ? method
                         : 'GET';
-                    result.decoratorRoutes.push({
+                    const base = {
                         filePath: file.path,
-                        routePath,
                         httpMethod,
                         decoratorName,
                         lineNumber: decoratorNode.startPosition.row + lineOffset,
                         ...(decoratorReceiver ? { decoratorReceiver } : {}),
-                    });
+                    };
+                    if (decoratorArgStr) {
+                        // String-literal path (the fast path, unchanged). Empty-string
+                        // literal `""` has no `string_content` → `decoratorArg` undefined →
+                        // routePath '' (a valid path under an APIRouter prefix).
+                        result.decoratorRoutes.push({ ...base, routePath: decoratorArg ?? '' });
+                    }
+                    else if (decoratorArgExpr) {
+                        // #2391 non-literal path (imported/composed constant). Emit the raw
+                        // expression + its operands for cross-file resolution in parse-impl;
+                        // `routePath` stays empty until resolved (or the route is dropped).
+                        const operands = decoratorArgExpr.type === 'identifier'
+                            ? [{ kind: 'ref', name: decoratorArgExpr.text }]
+                            : parseConstOperands(decoratorArgExpr);
+                        result.decoratorRoutes.push({
+                            ...base,
+                            routePath: '',
+                            routePathExpr: decoratorArgExpr.text,
+                            ...(operands ? { routePathOperands: operands } : {}),
+                        });
+                    }
+                    // Otherwise the first arg is absent or an unsupported shape
+                    // (attribute access, call, …) → skip; never a phantom `POST /`.
                 }
                 // MCP/RPC tool detection: @mcp.tool(), @app.tool(), @server.tool()
                 if (decoratorName === 'tool') {
@@ -1839,6 +1866,14 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
         // came from a `@router.<verb>` decorator. Python-only.
         if (language === SupportedLanguages.Python) {
             extractFastAPIRouterBindings(file.path, parseContent, result.routerIncludes, result.routerImports, (result.routerModuleAliases ??= []), (result.routerConstructorPrefixes ??= []));
+            // #2391: harvest module-level string constants + from-imports so parse-impl
+            // can resolve non-literal decorator route paths cross-file. Only emit for
+            // files that carry something resolvable (a constant definition or an import
+            // binding) to keep the aggregate bounded on large repos.
+            const constants = extractPythonModuleConstants(tree);
+            if (constants.literals.size > 0 || constants.exprs.size > 0 || constants.imports.size > 0) {
+                (result.moduleConstants ??= []).push({ filePath: file.path, constants });
+            }
         }
         // Language-specific decorator route extraction via provider hook.
         // The provider's extractDecoratorRoutes walks the AST for framework-specific

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

@@ -32,6 +32,10 @@ export const mergeResult = (target, src) => {
         target.routerModuleAliases ??= [];
         appendAll(target.routerModuleAliases, src.routerModuleAliases);
     }
+    if (src.moduleConstants) {
+        target.moduleConstants ??= [];
+        appendAll(target.moduleConstants, src.moduleConstants);
+    }
     if (src.springTypes) {
         target.springTypes ??= [];
         appendAll(target.springTypes, src.springTypes);

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

@@ -135,6 +135,19 @@ export interface WorkerPoolOptions {
     pdg?: boolean;
     /** Per-function source-line cap for worker-side CFG construction (0 ⇒ no cap). */
     pdgMaxFunctionLines?: number;
+    /**
+     * Max wall time `terminate()` waits for a retired worker that has NOT yet
+     * reached a JS-visible safe point before giving up on terminating it
+     * (#2432). Terminating a worker thread that is inside an N-API call aborts
+     * the whole process (`Napi::Error` → `std::terminate` → SIGABRT) — and the
+     * same abort fires at plain process exit, so the drain is what makes
+     * shutdown safe. On expiry the worker is left running (unref'd, with its
+     * at-safe-point terminate listener still armed) and a diagnostic is logged.
+     * Default 30000ms — above the C++ capture budget
+     * (`GITNEXUS_CPP_CAPTURE_BUDGET_MS`, 20000ms) so the drain converges for
+     * the known pathological class. 0 ⇒ no wait (test hook).
+     */
+    shutdownDrainMs?: number;
 }
 export declare class WorkerPoolDispatchError extends Error {
     /**
@@ -193,6 +206,7 @@ interface ResolvedWorkerPoolOptions {
     maxRespawnsPerSlot: number;
     maxCumulativeTimeoutMs: number;
     consecutiveFailureThreshold: number;
+    shutdownDrainMs: number;
 }
 export declare function resolveWorkerPoolOptions(options?: WorkerPoolOptions, poolSize?: number): ResolvedWorkerPoolOptions;
 /**

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

@@ -231,6 +231,8 @@ function nonNegativeInteger(value) {
         ? Math.floor(parsed)
         : undefined;
 }
+/** See {@link WorkerPoolOptions.shutdownDrainMs}. */
+const DEFAULT_SHUTDOWN_DRAIN_MS = 30_000;
 export function resolveWorkerPoolOptions(options = {}, poolSize) {
     const subBatchIdleTimeoutMs = positiveInteger(options.subBatchIdleTimeoutMs) ??
         positiveInteger(process.env.GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS) ??
@@ -252,6 +254,9 @@ export function resolveWorkerPoolOptions(options = {}, poolSize) {
         consecutiveFailureThreshold: positiveInteger(options.consecutiveFailureThreshold) ??
             positiveInteger(process.env.GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD) ??
             Math.max(DEFAULT_CONSECUTIVE_FAILURE_THRESHOLD_FLOOR, poolSize ?? 0),
+        shutdownDrainMs: nonNegativeInteger(options.shutdownDrainMs) ??
+            nonNegativeInteger(process.env.GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS) ??
+            DEFAULT_SHUTDOWN_DRAIN_MS,
     };
 }
 /**
@@ -608,13 +613,50 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
     // Set by `terminate()` (below). Also read by the self-healing startup loop so
     // a terminate during startup aborts pending backoff/retries (#1741).
     let terminated = false;
+    /** Resolves `true` when `promise` settles within `ms`, else `false`. The
+     *  timer is unref'd so an expiring drain never holds the process open. */
+    const settledWithin = (promise, ms) => {
+        if (ms <= 0)
+            return Promise.resolve(false);
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => resolve(false), ms);
+            timer.unref?.();
+            void promise.then(() => {
+                clearTimeout(timer);
+                resolve(true);
+            });
+        });
+    };
     const terminateTrackedWorkers = async (liveWorkers) => {
         const retired = Array.from(retiredWorkers);
         await Promise.all([
             ...liveWorkers.map((worker) => worker?.terminate().catch(() => undefined)),
-            ...retired.map((record) => record.terminate()),
+            ...retired.map(async (record) => {
+                // #2432: a retired worker that has not reached a JS-visible safe
+                // point may be inside an N-API call — terminating it aborts the
+                // WHOLE process (`Napi::Error` → std::terminate → SIGABRT). Drain:
+                // wait (bounded) for its safe point; on expiry leave it running —
+                // it is unref'd and its at-safe-point terminate listener stays
+                // armed — and log which file wedged it.
+                if (!record.safeToTerminate) {
+                    const drained = await settledWithin(record.safePoint, poolOptions.shutdownDrainMs);
+                    if (!drained) {
+                        logger.warn({
+                            workerIndex: record.workerIndex,
+                            reason: record.reason,
+                            drainMs: poolOptions.shutdownDrainMs,
+                        }, `Worker ${record.workerIndex} is still inside native code after the ` +
+                            `${poolOptions.shutdownDrainMs}ms shutdown drain; leaving it un-terminated ` +
+                            `to avoid a native abort (#2432). It will be terminated at its next safe point.`);
+                        return;
+                    }
+                }
+                await record.terminate();
+            }),
         ]);
-        retiredWorkers.clear();
+        // Undrained records stay tracked so a repeated shutdown call can retry
+        // their (now possibly safe) terminate; record.terminate() removes each
+        // drained record via its cleanup.
     };
     for (let i = 0; i < size; i++) {
         workers[i] = spawnAndCapture(workerUrl);
@@ -788,6 +830,18 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
             const retireWorkerAfterTimeout = (worker, workerIndex, reason) => {
                 let cleaned = false;
                 let terminateStarted = false;
+                let resolveSafePoint;
+                const safePoint = new Promise((resolve) => {
+                    resolveSafePoint = resolve;
+                });
+                // A message/messageerror proves the worker is executing JS again; an
+                // exit/error means the thread is gone. Either way `worker.terminate()`
+                // can no longer land mid-N-API call (#2432), so shutdown's drain may
+                // stop waiting.
+                function markSafeToTerminate() {
+                    record.safeToTerminate = true;
+                    resolveSafePoint();
+                }
                 function cleanupRetired() {
                     if (cleaned)
                         return;
@@ -806,6 +860,7 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
                     await worker.terminate().catch(() => undefined);
                 }
                 function terminateWhenBackInJs() {
+                    markSafeToTerminate();
                     void terminateRetired();
                 }
                 function onRetiredMessage(raw) {
@@ -816,8 +871,14 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
                         terminateWhenBackInJs();
                     }
                 }
-                const onRetiredError = () => cleanupRetired();
-                const onRetiredExit = () => cleanupRetired();
+                const onRetiredError = () => {
+                    markSafeToTerminate();
+                    cleanupRetired();
+                };
+                const onRetiredExit = () => {
+                    markSafeToTerminate();
+                    cleanupRetired();
+                };
                 const onRetiredMessageError = () => terminateWhenBackInJs();
                 const record = {
                     worker,
@@ -825,6 +886,8 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
                     reason,
                     cleanup: cleanupRetired,
                     terminate: terminateRetired,
+                    safeToTerminate: false,
+                    safePoint,
                 };
                 retiredWorkers.add(record);
                 worker.on('message', onRetiredMessage);
@@ -890,8 +953,25 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
                 const liveWorkers = workers.slice();
                 for (let i = 0; i < workers.length; i++)
                     workers[i] = undefined;
+                // #2432: a live worker with a job in flight may be inside an N-API
+                // call — direct terminate risks the same native abort as the retired
+                // case. Route busy workers through the retire path (terminate at
+                // their next JS-visible safe point); idle workers are parked in the
+                // JS event loop and terminate safely right away.
+                const idleWorkers = [];
+                for (let i = 0; i < liveWorkers.length; i++) {
+                    const worker = liveWorkers[i];
+                    if (worker === undefined)
+                        continue;
+                    if (busySlots.has(i)) {
+                        retireWorkerAfterTimeout(worker, i, 'circuit breaker tripped with job in flight');
+                    }
+                    else {
+                        idleWorkers.push(worker);
+                    }
+                }
                 activeSlots.clear();
-                void terminateTrackedWorkers(liveWorkers);
+                void terminateTrackedWorkers(idleWorkers);
             };
             const maybeDone = () => {
                 if (stopped)

package/dist/core/lbug/csv-generator.js

@@ -17,6 +17,7 @@ import path from 'path';
 import { NODE_TABLES } from './schema.js';
 import { RelPairRouter } from './rel-pair-routing.js';
 import { parseTruthyEnv } from '../ingestion/utils/env.js';
+import { SYMBOL_NODE_LABELS } from '../ingestion/utils/symbol-labels.js';
 import { applyCjkSegmentationIfEnabled } from '../search/cjk-segmentation.js';
 /**
  * Deterministic output ordering — optional (out-of-core / windowed-resolve
@@ -187,6 +188,10 @@ class FileContentCache {
 export const normalizeFtsText = (text) => text.replace(/[\r\n\t]+/g, ' ');
 /** Composes both FTS-text transforms for the `description` column — one place for the six emission sites below to call, instead of repeating the composition. */
 const formatFtsDescription = (description) => normalizeFtsText(applyCjkSegmentationIfEnabled(description));
+// Labels that get exact source-span content (no ±2 window). Single source of
+// truth in `symbol-labels.ts` — see there for why the exactness depends on the
+// 0-based line invariant. Kept as a named alias to read intent at the use site.
+const EXACT_SYMBOL_CONTENT_LABELS = SYMBOL_NODE_LABELS;
 const extractContent = async (node, contentCache) => {
     const filePath = node.properties.filePath;
     const content = await contentCache.get(filePath);
@@ -209,8 +214,9 @@ const extractContent = async (node, contentCache) => {
     if (startLine === undefined || endLine === undefined)
         return '';
     const lines = content.split('\n');
-    const start = Math.max(0, startLine - 2);
-    const end = Math.min(lines.length - 1, endLine + 2);
+    const exactSymbolContent = EXACT_SYMBOL_CONTENT_LABELS.has(node.label);
+    const start = Math.max(0, exactSymbolContent ? startLine : startLine - 2);
+    const end = Math.min(lines.length - 1, exactSymbolContent ? endLine : endLine + 2);
     const snippet = lines.slice(start, end + 1).join('\n');
     const MAX_SNIPPET = 5000;
     const capped = snippet.length > MAX_SNIPPET ? snippet.slice(0, MAX_SNIPPET) + '\n... [truncated]' : snippet;

package/dist/core/lbug/cypher-escape.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Escape a value for embedding in a single-quoted Cypher string literal.
+ *
+ * LadybugDB's parser uses backslash escapes and REJECTS SQL-style `''`
+ * doubling — `'we''ird'` is a parser error, not an escaped quote (#2409
+ * review). Every call site that used doubling produced a query that never
+ * parsed; the failures were invisible wherever the site swallowed errors
+ * (per-file deletes skipping quoted paths, importer BFS returning [],
+ * augment/wiki batch lookups silently missing rows).
+ *
+ * Backslashes are escaped first, then quotes — reversing the order would
+ * double the backslash that the quote escape just introduced. For values
+ * inside single-quoted literals only; table/label names go through
+ * `escapeTableName` in lbug-adapter instead.
+ *
+ * NOT for CSV emission: the COPY path (csv-generator.ts) quotes fields for
+ * LadybugDB's CSV reader (`ESCAPE='"'`), a different grammar with its own
+ * rules — its `''` usages are not this bug.
+ */
+export declare const escapeCypherString: (value: string) => string;

package/dist/core/lbug/cypher-escape.js

@@ -0,0 +1,20 @@
+/**
+ * Escape a value for embedding in a single-quoted Cypher string literal.
+ *
+ * LadybugDB's parser uses backslash escapes and REJECTS SQL-style `''`
+ * doubling — `'we''ird'` is a parser error, not an escaped quote (#2409
+ * review). Every call site that used doubling produced a query that never
+ * parsed; the failures were invisible wherever the site swallowed errors
+ * (per-file deletes skipping quoted paths, importer BFS returning [],
+ * augment/wiki batch lookups silently missing rows).
+ *
+ * Backslashes are escaped first, then quotes — reversing the order would
+ * double the backslash that the quote escape just introduced. For values
+ * inside single-quoted literals only; table/label names go through
+ * `escapeTableName` in lbug-adapter instead.
+ *
+ * NOT for CSV emission: the COPY path (csv-generator.ts) quotes fields for
+ * LadybugDB's CSV reader (`ESCAPE='"'`), a different grammar with its own
+ * rules — its `''` usages are not this bug.
+ */
+export const escapeCypherString = (value) => value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");

package/dist/core/lbug/extension-load-error.d.ts

@@ -0,0 +1,67 @@
+export type ExtensionLoadErrorKind = 'missing_file' | 'corrupt_file' | 'missing_dependency' | 'unknown';
+export interface ExtensionLoadDiagnosis {
+    readonly kind: ExtensionLoadErrorKind;
+    /** Actionable, literal-English remedy suited to the class. */
+    readonly remedy: string;
+}
+/**
+ * On-disk file corruption / wrong-platform. FORCE INSTALL re-downloads.
+ * Kept byte-identical to `FILE_CORRUPTION_SIGNATURES` in
+ * scripts/install-duckdb-extension.mjs (that `.mjs` cannot import this `.ts`;
+ * the duplication is deliberate — the two serve different call sites). Note
+ * `/not a valid/i` already covers Windows error 193 ("is not a valid Win32
+ * application"), so a truncated Windows download is caught here, before the
+ * missing-dependency branch.
+ */
+export declare const FILE_CORRUPTION_SIGNATURES: readonly RegExp[];
+/**
+ * Classify a collapsed LadybugDB LOAD error. Order is most-specific-first and is
+ * load-bearing: corrupt-file is tested before missing-dependency so a truncated
+ * Windows download (error 193, matched by `/not a valid/i`) routes to
+ * FORCE-reinstall rather than to the runtime-install remedy.
+ */
+export declare function classifyExtensionLoadError(reason: string | undefined | null): ExtensionLoadDiagnosis;
+/** Well-formedness of the extension binary for the host platform + arch. */
+export type ExtensionBinaryState = 'absent' | 'corrupt' | 'valid' | 'indeterminate';
+/**
+ * Pull the extension file path out of lbug's load error. lbug's wrapper is
+ * English regardless of OS language — `Failed to load library: {path} which is
+ * needed by extension: {name}` (real lbug), or the quoted `Failed to load
+ * library '{path}': {reason}` variant — so the path is recoverable in any locale.
+ * Only paths ending in `.lbug_extension` are accepted, so a regex misfire can
+ * never point the inspector at an arbitrary file.
+ */
+export declare function extractExtensionPath(reason: string | undefined | null): string | null;
+/**
+ * A structural verdict on a binary header. `indeterminate` means the probe could
+ * not prove validity OR corruption from what it read (e.g. the PE header sits past
+ * the BINARY_HEADER_BYTES window) — the caller defers to the string classifier
+ * rather than assert a false verdict.
+ */
+type HeaderVerdict = 'valid' | 'corrupt' | 'indeterminate';
+/**
+ * Decide whether a binary header is a well-formed shared library for the given
+ * platform + architecture — using only the file's structure, no localized text.
+ * Pure and injectable (platform/arch as params) so every format+arch combination
+ * is unit-testable regardless of the host it runs on.
+ */
+export declare function classifyBinaryHeader(buf: Buffer, bytesRead: number, platform: NodeJS.Platform, arch: string): HeaderVerdict;
+/**
+ * Best-effort language-independent inspection of the extension file. Reads the
+ * header and classifies it; never throws — a missing file is `absent`, an
+ * unreadable one is `indeterminate`.
+ */
+export declare function inspectExtensionBinary(extensionPath: string | null | undefined): ExtensionBinaryState;
+/**
+ * Diagnose a LadybugDB load failure, preferring a LANGUAGE-INDEPENDENT structural
+ * check of the extension binary over the localized error text:
+ *   - file absent             → missing_file
+ *   - present but malformed    → corrupt_file       (bad magic / wrong architecture)
+ *   - present and well-formed   → missing_dependency (a valid binary the loader rejected)
+ * The path comes from lbug's own English wrapper, so this holds in any OS display
+ * language. When the file cannot be located or read, it falls back to the string
+ * classifier (which still carries the language-independent hedged fallback). This
+ * is the entry point every surface should call.
+ */
+export declare function diagnoseExtensionLoad(reason: string | undefined | null): ExtensionLoadDiagnosis;
+export {};