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

package/dist/core/ingestion/languages/cpp/captures.js

@@ -12,6 +12,27 @@ import { markCppInlineNamespaceRange } from './inline-namespaces.js';
 import { extractCppTemplateConstraints } from './constraint-extractor.js';
 import { captureCppMemberLookupFacts } from './member-lookup.js';
 import { CPP_BRACED_INIT_TYPE_PREFIX } from './conversion-rank.js';
+import { logger } from '../../../logger.js';
+/**
+ * Per-file wall-clock budget for the capture-emit loop (#2432). A worker
+ * thread stuck in this loop cannot be terminated safely (terminating a
+ * thread mid-N-API call aborts the whole process with Napi::Error), so the
+ * loop must bound itself: on breach we return the captures accumulated so
+ * far with a warning — degraded coverage for one file, never a crash or a
+ * thrown error (a throw here would make the language-group catch drop every
+ * remaining file in the batch).
+ *
+ * `GITNEXUS_CPP_CAPTURE_BUDGET_MS`: unset/invalid/negative → 20000; explicit
+ * 0 → expires immediately (deterministic test hook).
+ */
+const CPP_CAPTURE_BUDGET_DEFAULT_MS = 20_000;
+function cppCaptureBudgetMs() {
+    const raw = process.env.GITNEXUS_CPP_CAPTURE_BUDGET_MS;
+    if (raw === undefined || raw === '')
+        return CPP_CAPTURE_BUDGET_DEFAULT_MS;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : CPP_CAPTURE_BUDGET_DEFAULT_MS;
+}
 export function emitCppScopeCaptures(sourceText, filePath, cachedTree) {
     let tree = cachedTree;
     if (tree === undefined) {
@@ -21,10 +42,27 @@ export function emitCppScopeCaptures(sourceText, filePath, cachedTree) {
     }
     const rawMatches = getCppScopeQuery().matches(tree.rootNode);
     const out = [];
+    // #2432: reset the per-file lookup index. The identifier-argument type
+    // lookups below used to re-walk the AST per identifier (full-tree DFS in
+    // isKnownEnumName, per-scope declaration scans) — O(calls × args × treeSize)
+    // per file, 151s on a 194KB file that parses in 46ms. The index makes each
+    // lookup O(1) after a single lazily-built pass.
+    resetCppFileLookupIndex();
     // Track ranges where typedef-struct/enum was captured as its concrete type
     // so we can suppress the duplicate @declaration.typedef match.
     const concreteTypedefRanges = new Set();
+    // #2432: per-file deadline for the loop below (see cppCaptureBudgetMs).
+    // Checked every 64 matches — post-index a single iteration is microseconds,
+    // so the check granularity costs nothing and bounds the drift past the
+    // deadline to well under a second.
+    const budgetMs = cppCaptureBudgetMs();
+    const deadline = Date.now() + budgetMs;
+    let matchIndex = 0;
     for (const m of rawMatches) {
+        if ((matchIndex++ & 63) === 0 && Date.now() >= deadline) {
+            logger.warn({ filePath, budgetMs, processedMatches: matchIndex - 1, totalMatches: rawMatches.length }, `C++ capture extraction exceeded its ${budgetMs}ms budget for ${filePath}; returning partial captures for this file (#2432).`);
+            break;
+        }
         const grouped = {};
         // Parallel tag -> captured SyntaxNode map. The tree-sitter query already
         // hands us each matched node as `c.node`, so anchors resolve via a
@@ -960,6 +998,47 @@ function inferCppBracedInitType(node) {
         ? `${CPP_BRACED_INIT_TYPE_PREFIX}${first}:${elementTypes.length}`
         : `${CPP_BRACED_INIT_TYPE_PREFIX}unknown:${elementTypes.length}`;
 }
+let fileLookupIndex = {
+    enumNames: null,
+    scopeDecls: new Map(),
+    fnParams: new Map(),
+};
+function resetCppFileLookupIndex() {
+    fileLookupIndex = { enumNames: null, scopeDecls: new Map(), fnParams: new Map() };
+}
+/**
+ * First-declaration-wins map of the scope's `declaration` children that
+ * carry a concrete (non-placeholder) type and a nameable declarator —
+ * exactly the entries the replaced per-identifier scans could match.
+ */
+function scopeDeclarationsFor(scope) {
+    const cached = fileLookupIndex.scopeDecls.get(scope.id);
+    if (cached !== undefined)
+        return cached;
+    const decls = new Map();
+    for (let i = 0; i < scope.childCount; i++) {
+        const stmt = scope.child(i);
+        if (stmt === null || stmt.type !== 'declaration')
+            continue;
+        const typeNode = stmt.childForFieldName('type');
+        if (typeNode === null)
+            continue;
+        if (typeNode.type === 'placeholder_type_specifier')
+            continue;
+        const declarator = stmt.childForFieldName('declarator');
+        if (declarator === null)
+            continue;
+        const nameChild = declaredNameNode(declarator);
+        if (nameChild === null)
+            continue;
+        const name = extractDeclaratorLeafName(nameChild);
+        if (name === '' || decls.has(name))
+            continue;
+        decls.set(name, stmt);
+    }
+    fileLookupIndex.scopeDecls.set(scope.id, decls);
+    return decls;
+}
 /**
  * Look up the declared type of a variable by scanning sibling declarations
  * in the enclosing compound_statement (function body). Handles:
@@ -991,27 +1070,14 @@ function lookupDeclaredTypeForIdentifier(identNode) {
     const paramType = lookupFunctionParameterType(scope, varName);
     if (paramType !== '')
         return paramType;
-    // Scan declarations in the scope for a matching variable name
-    for (let i = 0; i < scope.childCount; i++) {
-        const stmt = scope.child(i);
-        if (stmt === null || stmt.type !== 'declaration')
-            continue;
-        const typeNode = stmt.childForFieldName('type');
-        if (typeNode === null)
-            continue;
-        // Skip auto/placeholder types — those need chain-follow, not literal
-        if (typeNode.type === 'placeholder_type_specifier')
-            continue;
-        // Check init_declarator children for the variable name
-        const declarator = stmt.childForFieldName('declarator');
-        if (declarator === null)
-            continue;
-        const nameChild = declaredNameNode(declarator);
-        if (nameChild !== null && extractDeclaratorLeafName(nameChild) === varName) {
-            return normalizeCppTypeText(typeNode.text);
-        }
-    }
-    return '';
+    // Indexed scope-declaration lookup (#2432; was a per-identifier scan).
+    const stmt = scopeDeclarationsFor(scope).get(varName);
+    if (stmt === undefined)
+        return '';
+    const typeNode = stmt.childForFieldName('type');
+    if (typeNode === null)
+        return '';
+    return normalizeCppTypeText(typeNode.text);
 }
 function lookupDeclaredTypeClassForIdentifier(identNode) {
     const varName = identNode.text;
@@ -1026,28 +1092,20 @@ function lookupDeclaredTypeClassForIdentifier(identNode) {
     const paramTypeClass = lookupFunctionParameterTypeClass(scope, varName, identNode);
     if (paramTypeClass !== undefined)
         return paramTypeClass;
-    for (let i = 0; i < scope.childCount; i++) {
-        const stmt = scope.child(i);
-        if (stmt === null || stmt.type !== 'declaration')
-            continue;
-        const typeNode = stmt.childForFieldName('type');
-        if (typeNode === null)
-            continue;
-        if (typeNode.type === 'placeholder_type_specifier')
-            continue;
-        const declarator = stmt.childForFieldName('declarator');
-        if (declarator === null)
-            continue;
-        const nameChild = declaredNameNode(declarator);
-        if (nameChild === null || extractDeclaratorLeafName(nameChild) !== varName)
-            continue;
-        const typeClass = classifyCppParameterType(typeNode.text, nameChild.text, stmt.text.replace(/;\s*$/, ''));
-        if (isKnownEnumName(identNode, typeClass.base)) {
-            return { ...typeClass, base: `enum:${typeClass.base}` };
-        }
-        return typeClass;
+    // Indexed scope-declaration lookup (#2432; was a per-identifier scan).
+    const stmt = scopeDeclarationsFor(scope).get(varName);
+    if (stmt === undefined)
+        return unknownTypeClass('unknown');
+    const typeNode = stmt.childForFieldName('type');
+    const declarator = stmt.childForFieldName('declarator');
+    const nameChild = declarator !== null ? declaredNameNode(declarator) : null;
+    if (typeNode === null || nameChild === null)
+        return unknownTypeClass('unknown');
+    const typeClass = classifyCppParameterType(typeNode.text, nameChild.text, stmt.text.replace(/;\s*$/, ''));
+    if (isKnownEnumName(identNode, typeClass.base)) {
+        return { ...typeClass, base: `enum:${typeClass.base}` };
     }
-    return unknownTypeClass('unknown');
+    return typeClass;
 }
 function lookupFunctionParameterType(scope, varName) {
     const param = findEnclosingFunctionParameter(scope, varName);
@@ -1078,27 +1136,45 @@ function findEnclosingFunctionParameter(scope, varName) {
     let node = scope.parent;
     while (node !== null) {
         if (node.type === 'function_definition' || node.type === 'function_declarator') {
-            const fnDecl = node.type === 'function_declarator'
-                ? node
-                : findFirstDescendantOfType(node, 'function_declarator');
-            const params = fnDecl?.childForFieldName('parameters') ?? null;
-            if (params !== null) {
-                for (let i = 0; i < params.namedChildCount; i++) {
-                    const param = params.namedChild(i);
-                    if (param === null || param.type !== 'parameter_declaration')
-                        continue;
-                    const declarator = param.childForFieldName('declarator');
-                    if (declarator !== null && extractDeclaratorLeafName(declarator) === varName) {
-                        return param;
-                    }
-                }
-            }
-            return null;
+            return enclosingFunctionParametersFor(node)?.get(varName) ?? null;
         }
         node = node.parent;
     }
     return null;
 }
+/**
+ * First-wins map of a function's `parameter_declaration`s by declarator
+ * leaf name (#2432; was a per-identifier scan). `null` when the function
+ * has no parameter list — the caller returns null without walking further
+ * up, preserving the replaced scan's early-return.
+ */
+function enclosingFunctionParametersFor(fnNode) {
+    const cached = fileLookupIndex.fnParams.get(fnNode.id);
+    if (cached !== undefined)
+        return cached;
+    const fnDecl = fnNode.type === 'function_declarator'
+        ? fnNode
+        : findFirstDescendantOfType(fnNode, 'function_declarator');
+    const params = fnDecl?.childForFieldName('parameters') ?? null;
+    let index = null;
+    if (params !== null) {
+        index = new Map();
+        for (let i = 0; i < params.namedChildCount; i++) {
+            const param = params.namedChild(i);
+            if (param === null || param.type !== 'parameter_declaration')
+                continue;
+            const declarator = param.childForFieldName('declarator');
+            if (declarator === null)
+                continue;
+            const name = extractDeclaratorLeafName(declarator);
+            if (name === '' || index.has(name))
+                continue;
+            index.set(name, param);
+        }
+    }
+    fileLookupIndex.fnParams.set(fnNode.id, index);
+    return index;
+}
 function declaredNameNode(declarator) {
     if (declarator.type !== 'init_declarator')
         return declarator;
@@ -1126,24 +1202,31 @@ function normalizeCppTypeText(text) {
 function isKnownEnumName(node, typeName) {
     if (typeName === '' || typeName === 'unknown')
         return false;
-    let root = node;
-    while (root.parent !== null)
-        root = root.parent;
-    const stack = [root];
-    while (stack.length > 0) {
-        const cur = stack.pop();
-        if (cur.type === 'enum_specifier') {
-            const name = cur.childForFieldName('name');
-            if (name?.text === typeName)
-                return true;
-        }
-        for (let i = 0; i < cur.childCount; i++) {
-            const child = cur.child(i);
-            if (child !== null)
-                stack.push(child);
+    // One full-tree DFS per FILE (lazy), not per identifier argument — the
+    // per-identifier walk here was the dominant cost of #2432 (87s of a 151s
+    // extraction on a file that parses in 46ms).
+    if (fileLookupIndex.enumNames === null) {
+        let root = node;
+        while (root.parent !== null)
+            root = root.parent;
+        const names = new Set();
+        const stack = [root];
+        while (stack.length > 0) {
+            const cur = stack.pop();
+            if (cur.type === 'enum_specifier') {
+                const name = cur.childForFieldName('name');
+                if (name !== null)
+                    names.add(name.text);
+            }
+            for (let i = 0; i < cur.childCount; i++) {
+                const child = cur.child(i);
+                if (child !== null)
+                    stack.push(child);
+            }
         }
+        fileLookupIndex.enumNames = names;
     }
-    return false;
+    return fileLookupIndex.enumNames.has(typeName);
 }
 /**
  * Detect whether a `namespace_definition` AST node is inline.

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

@@ -7,6 +7,7 @@
  */
 import path from 'node:path';
 import { generateId } from '../../lib/utils.js';
+import { toZeroBasedLine } from './utils/line-base.js';
 const HEADING_RE = /^(#{1,6})\s+(.+)$/;
 const LINK_RE = /\[([^\]]*)\]\(([^)]+)\)/g;
 const MD_EXTENSIONS = new Set(['.md', '.mdx']);
@@ -59,8 +60,8 @@ export const processMarkdown = (graph, files, allPathSet) => {
                 properties: {
                     name: heading,
                     filePath: file.path,
-                    startLine: lineNum,
-                    endLine,
+                    startLine: toZeroBasedLine(lineNum),
+                    endLine: toZeroBasedLine(endLine),
                     level,
                     description: `h${level}`,
                 },

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

@@ -3,7 +3,7 @@ import type { SymbolTableWriter } from './model/index.js';
 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 { ParseWorkerResult, ExtractedRoute, ExtractedFetchCall, ExtractedDecoratorRoute, ExtractedModuleConstants, ExtractedToolDef, FileScopeBindings, ExtractedORMQuery, FetchWrapperDef } from './workers/parse-worker.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;
@@ -16,6 +16,8 @@ export interface WorkerExtractedData {
     routerImports: ExtractedRouterImport[];
     routerConstructorPrefixes: ExtractedRouterConstructorPrefix[];
     routerModuleAliases: ExtractedRouterModuleAlias[];
+    /** Per-file Python module constants for cross-file route-path resolution (#2391). */
+    moduleConstants: ExtractedModuleConstants[];
     toolDefs: ExtractedToolDef[];
     ormQueries: ExtractedORMQuery[];
     /** Project-wide Spring class/interface views for the #2288 inheritance pass. */

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

@@ -24,6 +24,7 @@ export const mergeChunkResults = (graph, symbolTable, chunkResults, exportedType
     const allRouterImports = [];
     const allRouterConstructorPrefixes = [];
     const allRouterModuleAliases = [];
+    const allModuleConstants = [];
     const allSpringTypes = [];
     const allToolDefs = [];
     const allORMQueries = [];
@@ -76,6 +77,8 @@ export const mergeChunkResults = (graph, symbolTable, chunkResults, exportedType
         }
         for (const item of result.routerModuleAliases ?? [])
             allRouterModuleAliases.push(item);
+        for (const item of result.moduleConstants ?? [])
+            allModuleConstants.push(item);
         for (const item of result.springTypes ?? [])
             allSpringTypes.push(item);
         for (const item of result.toolDefs)
@@ -99,6 +102,7 @@ export const mergeChunkResults = (graph, symbolTable, chunkResults, exportedType
         routerImports: allRouterImports,
         routerConstructorPrefixes: allRouterConstructorPrefixes,
         routerModuleAliases: allRouterModuleAliases,
+        moduleConstants: allModuleConstants,
         toolDefs: allToolDefs,
         ormQueries: allORMQueries,
         springTypes: allSpringTypes,

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

@@ -28,6 +28,7 @@ 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 { resolveOperands, } from '../route-extractors/python-const-resolver.js';
 import { resolveInheritedSpringRoutes, } from '../route-extractors/spring-shared.js';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -464,6 +465,9 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     const allRouterImports = [];
     const allRouterConstructorPrefixes = [];
     const allRouterModuleAliases = [];
+    // Per-file Python module constants (#2391); resolved into decorator route paths
+    // below, after cross-file aggregation, alongside the include_router prefix pass.
+    const allModuleConstants = [];
     const allSpringTypes = [];
     const allToolDefs = [];
     const allORMQueries = [];
@@ -610,6 +614,10 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                     for (const item of chunkWorkerData.routerModuleAliases)
                         allRouterModuleAliases.push(item);
                 }
+                if (chunkWorkerData.moduleConstants?.length) {
+                    for (const item of chunkWorkerData.moduleConstants)
+                        allModuleConstants.push(item);
+                }
                 if (chunkWorkerData.springTypes?.length) {
                     for (const item of chunkWorkerData.springTypes)
                         allSpringTypes.push(item);
@@ -925,6 +933,40 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     }
     // FastAPI router-prefix resolution (cross-file).
     //
+    // #2391: resolve non-literal FastAPI decorator route paths (imported/composed
+    // string constants) BEFORE the include_router/APIRouter prefix pass below, so a
+    // resolved path is then prefix-joined like any literal path. Each such route
+    // carries `routePathExpr`/`routePathOperands` and an empty `routePath`; we fold
+    // the operands against the repo-wide, file-path-keyed constant map. On failure
+    // we DROP the route (KTD5 skip floor) rather than emit a phantom `POST /`.
+    if (allDecoratorRoutes.some((dr) => dr.routePathExpr !== undefined)) {
+        const repoConstants = new Map();
+        for (const { filePath, constants } of allModuleConstants) {
+            repoConstants.set(filePath, constants);
+        }
+        const resolvedRoutes = [];
+        let skipped = 0;
+        for (const dr of allDecoratorRoutes) {
+            if (dr.routePathExpr === undefined) {
+                resolvedRoutes.push(dr);
+                continue;
+            }
+            const value = dr.routePathOperands
+                ? resolveOperands(dr.filePath, dr.routePathOperands, repoConstants)
+                : null;
+            if (value === null) {
+                skipped++;
+                continue;
+            }
+            resolvedRoutes.push({ ...dr, routePath: value });
+        }
+        allDecoratorRoutes.length = 0;
+        for (const dr of resolvedRoutes)
+            allDecoratorRoutes.push(dr);
+        if (isDev && skipped > 0) {
+            logger.info(`  🧩 Resolved composed route constants; ${skipped} unresolved route(s) skipped`);
+        }
+    }
     // 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

package/dist/core/ingestion/route-extractors/constant-resolver.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Language-agnostic string-constant folding for route-path resolution (#2391).
+ *
+ * Route decorators/annotations frequently build their path from a constant rather
+ * than a string literal — `@router.post(API_V1_WIDGETS_GET)` (Python),
+ * `@GetMapping(PathConstants.WIDGETS)` (Spring), and the Kotlin/C# equivalents are
+ * the same shape. This module folds such a constant — or an inline
+ * `+`-concatenation — to its literal value, following `+` operands and import
+ * chains across a repo-wide, file-keyed constant map.
+ *
+ * The FOLD is language-neutral: it walks {@link Operand} lists and
+ * {@link ModuleConstants} that ANY language's extractor can produce, and defers
+ * the one language-specific decision — mapping an import specifier to the file it
+ * refers to — to a caller-supplied {@link ImportResolver}. A language binding
+ * (e.g. `python-const-resolver.ts`) provides that resolver plus a tree →
+ * {@link ModuleConstants} extractor and, if wanted, thin pre-bound wrappers.
+ *
+ * This mirrors how `route-path.ts` (URL normalization) and `spring-shared.ts`
+ * (annotation primitives) are shared across the ingestion and group layers and
+ * across languages: the reusable core lives in one place; per-language semantics
+ * plug in. It deliberately does NOT reuse `ScopeResolver` (which resolves symbol
+ * IDENTITIES, not literal string VALUES) or the `--pdg` `REACHING_DEF` layer
+ * (intra-procedural, function-local, def→use reachability — not module-level
+ * cross-file value folding).
+ */
+/**
+ * One term of a constant's right-hand side. A `+`-concatenation
+ * (`A + "/b" + C`) becomes an ordered `Operand[]`; a bare literal is a
+ * single-element list.
+ */
+export type Operand = {
+    readonly kind: 'literal';
+    readonly value: string;
+} | {
+    readonly kind: 'ref';
+    readonly name: string;
+};
+/**
+ * A `from <module> import <name> [as <local>]` (or the language's equivalent)
+ * binding. `module` is the import specifier as written (e.g. `.constants`,
+ * `..pkg.constants`, `api.constants`) so the {@link ImportResolver} can apply
+ * language-specific rules; `originalName` is the exported name in the target
+ * module (pre-alias). The map key is the local (in-file) name.
+ */
+export interface ImportBinding {
+    readonly module: string;
+    readonly originalName: string;
+}
+/**
+ * String-valued module-level constants of one source file. `literals` are
+ * fully-resolved (`X = "/a"`); `exprs` are unresolved operand lists
+ * (`X = A + "/b"`); `imports` maps a local name to the module it was imported
+ * from. All string keys are the in-file (local) names.
+ */
+export interface ModuleConstants {
+    readonly literals: Map<string, string>;
+    readonly exprs: Map<string, readonly Operand[]>;
+    readonly imports: Map<string, ImportBinding>;
+}
+/** Repo-wide map: unique file key (e.g. `app/constants.py`) → that file's
+ * {@link ModuleConstants}. */
+export type RepoConstants = ReadonlyMap<string, ModuleConstants>;
+/**
+ * Resolve an import specifier (as written) from `importingFileKey` to the unique
+ * repo file key it refers to, or `null` when it cannot be pinned to exactly one
+ * file. This is the sole language-specific dependency of the fold: Python uses
+ * leading-dot relative imports + `.py`-suffix rules; a JVM binding would use
+ * package/classpath rules. Returning `null` on ambiguity keeps the fold honest —
+ * an unresolvable or ambiguous import floors to skip, never a wrong path.
+ */
+export type ImportResolver = (importingFileKey: string, moduleSpec: string, repoKeys: ReadonlySet<string>) => string | null;
+/**
+ * Resolve a single named constant referenced in `fileKey` to its literal string
+ * value, folding `+` concatenation and following import chains via
+ * `resolveImport`, or `null` when it cannot be fully folded.
+ */
+export declare function resolveConstant(fileKey: string, name: string, repo: RepoConstants, resolveImport: ImportResolver): string | null;
+/**
+ * Resolve an inline operand list (an unnamed `+`-expression captured directly at
+ * a decorator/annotation argument, e.g. `@router.get(API_V1 + "/widgets")`)
+ * against `fileKey`.
+ */
+export declare function resolveOperands(fileKey: string, operands: readonly Operand[], repo: RepoConstants, resolveImport: ImportResolver): string | null;

package/dist/core/ingestion/route-extractors/constant-resolver.js

@@ -0,0 +1,131 @@
+/**
+ * Language-agnostic string-constant folding for route-path resolution (#2391).
+ *
+ * Route decorators/annotations frequently build their path from a constant rather
+ * than a string literal — `@router.post(API_V1_WIDGETS_GET)` (Python),
+ * `@GetMapping(PathConstants.WIDGETS)` (Spring), and the Kotlin/C# equivalents are
+ * the same shape. This module folds such a constant — or an inline
+ * `+`-concatenation — to its literal value, following `+` operands and import
+ * chains across a repo-wide, file-keyed constant map.
+ *
+ * The FOLD is language-neutral: it walks {@link Operand} lists and
+ * {@link ModuleConstants} that ANY language's extractor can produce, and defers
+ * the one language-specific decision — mapping an import specifier to the file it
+ * refers to — to a caller-supplied {@link ImportResolver}. A language binding
+ * (e.g. `python-const-resolver.ts`) provides that resolver plus a tree →
+ * {@link ModuleConstants} extractor and, if wanted, thin pre-bound wrappers.
+ *
+ * This mirrors how `route-path.ts` (URL normalization) and `spring-shared.ts`
+ * (annotation primitives) are shared across the ingestion and group layers and
+ * across languages: the reusable core lives in one place; per-language semantics
+ * plug in. It deliberately does NOT reuse `ScopeResolver` (which resolves symbol
+ * IDENTITIES, not literal string VALUES) or the `--pdg` `REACHING_DEF` layer
+ * (intra-procedural, function-local, def→use reachability — not module-level
+ * cross-file value folding).
+ */
+/** Depth ceiling for the import/constant chase. A heuristic bound, not a proven
+ * one; overrun floors to `null` (skip), never a wrong value. */
+const MAX_RESOLVE_DEPTH = 8;
+/** Max length of a folded path. Real route paths are well under this; a fold that
+ * exceeds it is a pathological self-multiplying concat (`X = A + A; A = B + B; …`)
+ * whose true value is genuinely huge — building it risks a `RangeError`/heap OOM,
+ * so we floor to `null` (skip) instead (#2393). The depth cap bounds recursion but
+ * NOT output size, which grows multiplicatively; this bounds the output. */
+const MAX_FOLD_LENGTH = 8192;
+/**
+ * Fold an operand list to its concatenated literal, or `null` if any operand is
+ * unresolvable (an unknown name, a non-string term, a cycle, or a depth overrun).
+ */
+function foldExpr(fileKey, operands, state, depth) {
+    if (depth > MAX_RESOLVE_DEPTH)
+        return null;
+    let out = '';
+    for (const op of operands) {
+        if (op.kind === 'literal') {
+            out += op.value;
+        }
+        else {
+            const resolved = foldName(fileKey, op.name, state, depth + 1);
+            if (resolved === null)
+                return null;
+            out += resolved;
+        }
+        if (out.length > MAX_FOLD_LENGTH)
+            return null; // pathological self-multiplying concat → drop
+    }
+    return out;
+}
+function foldName(fileKey, name, state, depth) {
+    if (depth > MAX_RESOLVE_DEPTH)
+        return null;
+    const guard = `${fileKey}::${name}`;
+    // Memoize successful folds. `visited` (below) is the ACTIVE resolution stack
+    // for cycle detection — popped on unwind so `A + A` / diamonds fold instead of
+    // false-cycling (#2393) — but popping it alone reintroduces recomputation: a
+    // wide shared-descendant DAG re-folds each child once per reference, O(fanout^depth),
+    // which can exhaust the heap. The never-popped `memo` caps that at O(nodes): a
+    // name resolved on one branch is returned directly on the next. Only SUCCESSES
+    // are cached — a `null` may be transient (a name that is a cycle on the current
+    // branch can resolve on another), so caching it would be unsound.
+    const memoized = state.memo.get(guard);
+    if (memoized !== undefined)
+        return memoized;
+    if (state.visited.has(guard))
+        return null; // cycle: `name` is on the active stack
+    state.visited.add(guard);
+    try {
+        const result = computeFold(fileKey, name, state, depth);
+        if (result !== null)
+            state.memo.set(guard, result);
+        return result;
+    }
+    finally {
+        state.visited.delete(guard);
+    }
+}
+/** The literal/expr/import resolution for one name. Cycle guard + memo live in
+ * {@link foldName}; this is the pure lookup body. */
+function computeFold(fileKey, name, state, depth) {
+    const mc = state.repo.get(fileKey);
+    if (!mc)
+        return null;
+    const literal = mc.literals.get(name);
+    if (literal !== undefined)
+        return literal;
+    const expr = mc.exprs.get(name);
+    if (expr !== undefined)
+        return foldExpr(fileKey, expr, state, depth + 1);
+    const imp = mc.imports.get(name);
+    if (imp !== undefined) {
+        const targetKey = state.resolveImport(fileKey, imp.module, state.repoKeys);
+        if (targetKey === null)
+            return null;
+        return foldName(targetKey, imp.originalName, state, depth + 1);
+    }
+    return null;
+}
+function newState(repo, resolveImport) {
+    return {
+        repo,
+        repoKeys: new Set(repo.keys()),
+        resolveImport,
+        visited: new Set(),
+        memo: new Map(),
+    };
+}
+/**
+ * Resolve a single named constant referenced in `fileKey` to its literal string
+ * value, folding `+` concatenation and following import chains via
+ * `resolveImport`, or `null` when it cannot be fully folded.
+ */
+export function resolveConstant(fileKey, name, repo, resolveImport) {
+    return foldName(fileKey, name, newState(repo, resolveImport), 0);
+}
+/**
+ * Resolve an inline operand list (an unnamed `+`-expression captured directly at
+ * a decorator/annotation argument, e.g. `@router.get(API_V1 + "/widgets")`)
+ * against `fileKey`.
+ */
+export function resolveOperands(fileKey, operands, repo, resolveImport) {
+    return foldExpr(fileKey, operands, newState(repo, resolveImport), 0);
+}