gitnexus 1.6.9 → 1.6.10-aptos.1

package/dist/core/ingestion/pipeline-phases/spring-config.js

@@ -0,0 +1,433 @@
+/**
+ * Phase: springConfig
+ *
+ * Adds key-only nodes for statically readable Spring
+ * `application*.properties` / `application*.yml` / `application*.yaml` files.
+ * Language-specific ScopeResolver hooks attach consumers later. Configuration
+ * values are deliberately never copied into the graph because they may contain
+ * credentials and key identity is sufficient for impact analysis.
+ *
+ * @deps    structure
+ * @reads   Spring application configuration files
+ * @writes  Property nodes and DEFINES edges
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { SPRING_CONFIG_DESCRIPTION } from '../frameworks/spring/config-bindings.js';
+import { generateId } from '../../../lib/utils.js';
+import { getPhaseOutput } from './types.js';
+const require = createRequire(import.meta.url);
+const yaml = require('js-yaml');
+// js-yaml 5 dropped DEFAULT_SCHEMA; CORE plus these tags is what it used to be, so
+// explicitly tagged values keep parsing instead of throwing (an unknown tag aborts
+// the whole file). None of them can execute code.
+const SPRING_YAML_SCHEMA = yaml.CORE_SCHEMA.withTags(yaml.mergeTag, yaml.timestampTag, yaml.binaryTag, yaml.omapTag, yaml.pairsTag, yaml.setTag);
+const MAX_CONFIG_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_YAML_TRAVERSAL_DEPTH = 128;
+const MAX_YAML_TRAVERSAL_NODES = 100_000;
+/** Match only Spring Boot's conventional application config file names. */
+export function classifySpringConfigFile(filePath) {
+    const base = path.posix.basename(filePath.replaceAll('\\', '/'));
+    const match = /^application(?:-([^.]+))?\.(properties|ya?ml)$/i.exec(base);
+    if (match === null)
+        return null;
+    return {
+        filePath,
+        ...(match[1] ? { profile: match[1] } : {}),
+        format: match[2].toLowerCase() === 'properties' ? 'properties' : 'yaml',
+    };
+}
+function unescapePropertyKey(raw) {
+    return raw
+        .replace(/\\u([0-9a-fA-F]{4})/g, (_match, hex) => String.fromCharCode(Number.parseInt(hex, 16)))
+        .replace(/\\([:=#!\\ ])/g, '$1');
+}
+function logicalPropertiesLines(content) {
+    const physical = content.split(/\r?\n/);
+    const logical = [];
+    let current = '';
+    let startLine = 1;
+    for (let index = 0; index < physical.length; index++) {
+        const line = physical[index];
+        if (current.length === 0)
+            startLine = index + 1;
+        current += current.length === 0 ? line : line.trimStart();
+        let trailingBackslashes = 0;
+        for (let cursor = current.length - 1; cursor >= 0 && current[cursor] === '\\'; cursor--) {
+            trailingBackslashes++;
+        }
+        if (trailingBackslashes % 2 === 1) {
+            current = current.slice(0, -1);
+            continue;
+        }
+        logical.push({ text: current, line: startLine });
+        current = '';
+    }
+    if (current.length > 0)
+        logical.push({ text: current, line: startLine });
+    return logical;
+}
+/** Parse `.properties` keys without retaining their values. */
+export function parseSpringProperties(content, filePath, profile) {
+    const keys = [];
+    const seen = new Set();
+    for (const logical of logicalPropertiesLines(content)) {
+        const trimmed = logical.text.trimStart();
+        if (trimmed.length === 0 || trimmed.startsWith('#') || trimmed.startsWith('!'))
+            continue;
+        let separator = -1;
+        let escaped = false;
+        for (let index = 0; index < trimmed.length; index++) {
+            const char = trimmed[index];
+            if (!escaped && (char === '=' || char === ':' || /\s/.test(char))) {
+                separator = index;
+                break;
+            }
+            escaped = !escaped && char === '\\';
+            if (char !== '\\')
+                escaped = false;
+        }
+        const rawKey = (separator === -1 ? trimmed : trimmed.slice(0, separator)).trim();
+        const key = unescapePropertyKey(rawKey);
+        if (key.length === 0 || seen.has(key))
+            continue;
+        seen.add(key);
+        keys.push({
+            key,
+            filePath,
+            line: logical.line,
+            ...(profile ? { profile } : {}),
+            format: 'properties',
+        });
+    }
+    return keys;
+}
+function consumeYamlTraversalBudget(state, depth) {
+    if (depth > MAX_YAML_TRAVERSAL_DEPTH) {
+        throw new Error(`Spring YAML traversal depth exceeds ${MAX_YAML_TRAVERSAL_DEPTH}`);
+    }
+    state.remainingNodes--;
+    if (state.remainingNodes < 0) {
+        throw new Error(`Spring YAML traversal exceeds ${MAX_YAML_TRAVERSAL_NODES} nodes`);
+    }
+}
+function isObjectValue(value) {
+    return value !== null && typeof value === 'object';
+}
+// Aliases are resolved to their anchor event by name while the tree is built,
+// so following one here is a single pointer hop.
+function resolveYamlAliasEvent(event) {
+    return event?.aliasOf ?? event;
+}
+function yamlMappingPairs(event) {
+    const pairs = [];
+    for (let index = 0; index + 1 < event.children.length; index += 2) {
+        const keyEvent = event.children[index];
+        const valueEvent = event.children[index + 1];
+        if (keyEvent.kind !== 'scalar')
+            continue;
+        pairs.push({ key: String(keyEvent.result), keyEvent, valueEvent });
+    }
+    return pairs;
+}
+/**
+ * First match in a pre-order walk of `event`, following sequences and `<<` merge
+ * chains. Iterative: children are pushed in reverse so the explicit stack pops
+ * them in declaration order, which is what makes "first match" mean the same
+ * thing it did when this recursed.
+ */
+function findYamlMappingLocation(event, key, traversal) {
+    const visited = new Set();
+    const stack = [{ event, depth: 0 }];
+    while (stack.length > 0) {
+        const step = stack.pop();
+        if (step === undefined)
+            break;
+        consumeYamlTraversalBudget(traversal, step.depth);
+        const resolved = resolveYamlAliasEvent(step.event);
+        if (resolved === undefined || visited.has(resolved))
+            continue;
+        visited.add(resolved);
+        if (resolved.kind === 'sequence') {
+            for (let index = resolved.children.length - 1; index >= 0; index--) {
+                stack.push({ event: resolved.children[index], depth: step.depth + 1 });
+            }
+            continue;
+        }
+        if (resolved.kind !== 'mapping')
+            continue;
+        const pairs = yamlMappingPairs(resolved);
+        const direct = pairs.find((pair) => pair.key === key);
+        if (direct !== undefined) {
+            return { valueEvent: direct.valueEvent, line: direct.keyEvent.startLine };
+        }
+        const merges = pairs.filter((pair) => pair.key === '<<');
+        for (let index = merges.length - 1; index >= 0; index--) {
+            stack.push({ event: merges[index].valueEvent, depth: step.depth + 1 });
+        }
+    }
+    return undefined;
+}
+/**
+ * Flatten a document to `dotted.key -> line`, iteratively. Children are pushed in
+ * reverse so the stack pops them in declaration order, keeping `out` in the same
+ * insertion order — and the traversal budget consumed in the same sequence — as
+ * the recursive walk this replaced.
+ */
+function flattenYamlValue(value, event, prefix, out, traversal) {
+    const stack = [
+        { kind: 'visit', value, event, prefix, sourceLine: event?.startLine ?? 1, depth: 0 },
+    ];
+    while (stack.length > 0) {
+        const step = stack.pop();
+        if (step === undefined)
+            break;
+        if (step.kind === 'leave') {
+            traversal.activeObjects.delete(step.object);
+            continue;
+        }
+        const { value: current, prefix: currentPrefix, sourceLine, depth } = step;
+        consumeYamlTraversalBudget(traversal, depth);
+        const resolvedEvent = resolveYamlAliasEvent(step.event);
+        const trackedObject = isObjectValue(current) ? current : undefined;
+        if (trackedObject !== undefined) {
+            if (traversal.activeObjects.has(trackedObject))
+                continue;
+            traversal.activeObjects.add(trackedObject);
+            stack.push({ kind: 'leave', object: trackedObject });
+        }
+        if (Array.isArray(current)) {
+            if (current.length === 0 && currentPrefix.length > 0 && !out.has(currentPrefix)) {
+                out.set(currentPrefix, sourceLine);
+            }
+            for (let index = current.length - 1; index >= 0; index--) {
+                stack.push({
+                    kind: 'visit',
+                    value: current[index],
+                    event: resolvedEvent?.children[index],
+                    prefix: `${currentPrefix}[${index}]`,
+                    sourceLine,
+                    depth: depth + 1,
+                });
+            }
+            continue;
+        }
+        if (current !== null &&
+            typeof current === 'object' &&
+            (resolvedEvent?.kind === 'mapping' || resolvedEvent === undefined)) {
+            // js-yaml 5 builds `!!set` as a native Set, whose members are not own
+            // properties; v4 built a plain `{member: null}` object. Enumerate them so a
+            // tagged set still contributes one key per member instead of a bare leaf.
+            const entries = current instanceof Set
+                ? [...current].map((member) => [String(member), null])
+                : Object.entries(current);
+            if (entries.length === 0 && currentPrefix.length > 0 && !out.has(currentPrefix)) {
+                out.set(currentPrefix, sourceLine);
+            }
+            for (let index = entries.length - 1; index >= 0; index--) {
+                const [key, nested] = entries[index];
+                const location = findYamlMappingLocation(resolvedEvent, key, traversal);
+                stack.push({
+                    kind: 'visit',
+                    value: nested,
+                    event: location?.valueEvent,
+                    prefix: currentPrefix.length === 0 ? key : `${currentPrefix}.${key}`,
+                    sourceLine: location?.line ?? sourceLine,
+                    depth: depth + 1,
+                });
+            }
+            continue;
+        }
+        if (currentPrefix.length > 0 && !out.has(currentPrefix))
+            out.set(currentPrefix, sourceLine);
+    }
+}
+// js-yaml 5 reports node positions as source offsets; map them to 1-based lines.
+function makeLineResolver(source) {
+    const lineStarts = [0];
+    for (let index = 0; index < source.length; index++) {
+        if (source[index] === '\n')
+            lineStarts.push(index + 1);
+    }
+    return (offset) => {
+        let low = 0;
+        let high = lineStarts.length - 1;
+        let line = 0;
+        while (low <= high) {
+            const mid = (low + high) >> 1;
+            if (lineStarts[mid] <= offset) {
+                line = mid;
+                low = mid + 1;
+            }
+            else {
+                high = mid - 1;
+            }
+        }
+        return line + 1;
+    };
+}
+/**
+ * Rebuild the parse tree from js-yaml 5's event stream (v4's `listener` option
+ * was removed). Returns each document's root event, with aliases already
+ * resolved to their anchor event so merged/aliased keys keep the line where
+ * they were declared.
+ *
+ * One node per event, so this pass is bounded by MAX_CONFIG_FILE_BYTES alone —
+ * MAX_YAML_TRAVERSAL_NODES governs the later walk, which can revisit a shared
+ * anchor many times and so needs a budget this linear pass does not.
+ */
+function buildYamlEventTree(events, source) {
+    const lineOf = makeLineResolver(source);
+    const anchors = new Map();
+    const stack = [];
+    const documentRoots = [];
+    const anchorName = (start, end) => start >= 0 && end > start ? source.slice(start, end) : null;
+    const attach = (node) => {
+        stack[stack.length - 1]?.children.push(node);
+    };
+    const register = (name, node) => {
+        if (name !== null)
+            anchors.set(name, node);
+    };
+    for (const event of events) {
+        switch (event.type) {
+            case yaml.EVENT_DOCUMENT:
+                // Anchors are document-scoped. constructFromEvents already rejects a
+                // cross-document alias before we get here, so this only keeps the two
+                // layers from disagreeing.
+                anchors.clear();
+                stack.push({
+                    startLine: 1,
+                    kind: null,
+                    result: undefined,
+                    aliasOf: undefined,
+                    children: [],
+                });
+                break;
+            case yaml.EVENT_MAPPING:
+            case yaml.EVENT_SEQUENCE: {
+                const node = {
+                    startLine: lineOf(event.start),
+                    kind: event.type === yaml.EVENT_MAPPING ? 'mapping' : 'sequence',
+                    result: undefined,
+                    aliasOf: undefined,
+                    children: [],
+                };
+                register(anchorName(event.anchorStart, event.anchorEnd), node);
+                attach(node);
+                stack.push(node);
+                break;
+            }
+            case yaml.EVENT_SCALAR: {
+                const node = {
+                    startLine: lineOf(event.valueStart),
+                    kind: 'scalar',
+                    result: yaml.getScalarValue(source, event),
+                    aliasOf: undefined,
+                    children: [],
+                };
+                register(anchorName(event.anchorStart, event.anchorEnd), node);
+                attach(node);
+                break;
+            }
+            case yaml.EVENT_ALIAS: {
+                const target = anchors.get(anchorName(event.anchorStart, event.anchorEnd) ?? '');
+                attach({ startLine: 1, kind: 'alias', result: undefined, aliasOf: target, children: [] });
+                break;
+            }
+            case yaml.EVENT_POP: {
+                const done = stack.pop();
+                // Documents are the only top-level containers, so a pop that empties the
+                // stack closes a document; its single child is the document's root value.
+                if (done !== undefined && stack.length === 0)
+                    documentRoots.push(done.children[0]);
+                break;
+            }
+        }
+    }
+    return documentRoots;
+}
+/** Parse and flatten YAML leaves without retaining their values. */
+export function parseSpringYaml(content, filePath, profile) {
+    const flattened = new Map();
+    const traversal = {
+        remainingNodes: MAX_YAML_TRAVERSAL_NODES,
+        activeObjects: new Set(),
+    };
+    const events = yaml.parseEvents(content, { maxDepth: MAX_YAML_TRAVERSAL_DEPTH });
+    const documents = yaml.constructFromEvents(events, {
+        source: content,
+        schema: SPRING_YAML_SCHEMA,
+        json: true,
+    });
+    const documentEvents = buildYamlEventTree(events, content);
+    documents.forEach((document, index) => flattenYamlValue(document, documentEvents[index], '', flattened, traversal));
+    return [...flattened.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, line]) => ({
+        key,
+        filePath,
+        line,
+        ...(profile ? { profile } : {}),
+        format: 'yaml',
+    }));
+}
+function configKeyNodeId(entry) {
+    return generateId('Property', `spring-config:${entry.filePath}:${entry.key}`);
+}
+async function readConfigKeys(repoPath, scannedFiles) {
+    const keys = [];
+    for (const scanned of scannedFiles) {
+        const classified = classifySpringConfigFile(scanned.path);
+        if (classified === null || scanned.size > MAX_CONFIG_FILE_BYTES)
+            continue;
+        try {
+            const content = await fs.readFile(path.join(repoPath, scanned.path), 'utf8');
+            keys.push(...(classified.format === 'properties'
+                ? parseSpringProperties(content, classified.filePath, classified.profile)
+                : parseSpringYaml(content, classified.filePath, classified.profile)));
+        }
+        catch {
+            // Malformed configuration is not a reason to fail the entire code index.
+            // Fail closed: no keys and therefore no misleading bindings for this file.
+        }
+    }
+    return keys;
+}
+export const springConfigPhase = {
+    name: 'springConfig',
+    deps: ['structure'],
+    async execute(ctx, deps) {
+        const { scannedFiles } = getPhaseOutput(deps, 'structure');
+        const configKeys = await readConfigKeys(ctx.repoPath, scannedFiles);
+        for (const entry of configKeys) {
+            const nodeId = configKeyNodeId(entry);
+            ctx.graph.addNode({
+                id: nodeId,
+                label: 'Property',
+                properties: {
+                    name: entry.key,
+                    filePath: entry.filePath,
+                    startLine: entry.line,
+                    endLine: entry.line,
+                    description: entry.profile
+                        ? `${SPRING_CONFIG_DESCRIPTION} (profile: ${entry.profile})`
+                        : SPRING_CONFIG_DESCRIPTION,
+                },
+            });
+            const fileId = generateId('File', entry.filePath);
+            if (ctx.graph.getNode(fileId) !== undefined) {
+                ctx.graph.addRelationship({
+                    id: generateId('DEFINES', `${fileId}->${nodeId}`),
+                    sourceId: fileId,
+                    targetId: nodeId,
+                    type: 'DEFINES',
+                    confidence: 1,
+                    reason: 'spring-config:key',
+                });
+            }
+        }
+        return { configKeys: configKeys.length };
+    },
+};

package/dist/core/ingestion/pipeline-phases/standalone-ingest.d.ts

@@ -0,0 +1,16 @@
+import type { PipelinePhase } from './types.js';
+/**
+ * Shared output contract for compiler-backed or otherwise standalone ingesters.
+ * Claimed files are excluded from the generic parser to prevent duplicate nodes.
+ */
+export interface StandaloneIngestOutput {
+    readonly ingestedFiles: ReadonlySet<string>;
+    /**
+     * Operator-actionable warnings the ingester wants surfaced in the persistent
+     * CLI summary (e.g. a package it had to skip or ingest at degraded fidelity).
+     * Language-neutral: the pipeline passes these through without interpreting.
+     */
+    readonly ingestWarnings?: readonly string[];
+}
+/** Default no-op used when the caller does not supply a standalone ingester. */
+export declare const emptyStandaloneIngestPhase: PipelinePhase<StandaloneIngestOutput>;

package/dist/core/ingestion/pipeline-phases/standalone-ingest.js

@@ -0,0 +1,6 @@
+/** Default no-op used when the caller does not supply a standalone ingester. */
+export const emptyStandaloneIngestPhase = {
+    name: 'standaloneIngest',
+    deps: ['structure'],
+    execute: () => Promise.resolve({ ingestedFiles: new Set() }),
+};

package/dist/core/ingestion/pipeline.d.ts

@@ -16,7 +16,7 @@
  */
 import { type PipelineProgress } from '../../_shared/index.js';
 import { PipelineResult } from '../../types/pipeline.js';
-import { type PipelinePhase } from './pipeline-phases/index.js';
+import { type StandaloneIngestOutput, type PipelinePhase } from './pipeline-phases/index.js';
 export interface PipelineOptions {
     /**
      * Skip MRO, community detection, and process extraction for faster test runs.
@@ -186,6 +186,8 @@ export interface PipelineOptions {
      * `process.env` state across invocations. When undefined, the env var decides.
      */
     keepLocalValueSymbols?: boolean;
+    /** Optional compiler-backed or otherwise standalone ingester. */
+    standaloneIngestPhase?: PipelinePhase<StandaloneIngestOutput>;
     /**
      * Extra fetch-wrapper function names to treat as HTTP consumers, threaded
      * from `.gitnexusrc` `fetchWrappers` via `AnalyzeOptions` (#1589/#1852
@@ -201,7 +203,7 @@ export interface PipelineOptions {
  *
  * Phase dependency graph:
  *
- *   scan → structure → [markdown, cobol] → parse → [routes, tools, orm]
+ *   scan → structure → [standaloneIngest, springConfig, markdown, cobol] → parse → [routes, tools, orm]
  *     → crossFile → scopeResolution → pruneLocalSymbols
  *     → mro → di → communities → processes
  *

package/dist/core/ingestion/pipeline.js

@@ -15,14 +15,14 @@
  * See ARCHITECTURE.md for the full phase dependency diagram.
  */
 import { createKnowledgeGraph } from '../graph/graph.js';
-import { runPipeline, getPhaseOutput, scanPhase, structurePhase, markdownPhase, cobolPhase, parsePhase, routesPhase, toolsPhase, ormPhase, crossFilePhase, scopeResolutionPhase, pruneLocalSymbolsPhase, taintSummariesPhase, callSummariesPhase, mroPhase, diPhase, communitiesPhase, processesPhase, PhaseRegistry, } from './pipeline-phases/index.js';
+import { runPipeline, getPhaseOutput, scanPhase, structurePhase, emptyStandaloneIngestPhase, markdownPhase, cobolPhase, parsePhase, routesPhase, toolsPhase, ormPhase, crossFilePhase, scopeResolutionPhase, springConfigPhase, pruneLocalSymbolsPhase, taintSummariesPhase, callSummariesPhase, mroPhase, diPhase, communitiesPhase, processesPhase, PhaseRegistry, } from './pipeline-phases/index.js';
 // ── Phase registry ─────────────────────────────────────────────────────────
 /**
  * All pipeline phases with their dependency relationships.
  *
  * Phase dependency graph:
  *
- *   scan → structure → [markdown, cobol] → parse → [routes, tools, orm]
+ *   scan → structure → [standaloneIngest, springConfig, markdown, cobol] → parse → [routes, tools, orm]
  *     → crossFile → scopeResolution → pruneLocalSymbols
  *     → mro → di → communities → processes
  *
@@ -37,9 +37,12 @@ import { runPipeline, getPhaseOutput, scanPhase, structurePhase, markdownPhase,
  * options combination.
  */
 export function buildPhaseList(options) {
+    const { standaloneIngestPhase = emptyStandaloneIngestPhase } = options ?? {};
     return (new PhaseRegistry()
         .register(scanPhase)
         .register(structurePhase)
+        .register(standaloneIngestPhase)
+        .register(springConfigPhase)
         .register(markdownPhase)
         .register(cobolPhase)
         .register(parsePhase)
@@ -78,6 +81,14 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
     const { totalFiles, usedWorkerPool } = getPhaseOutput(results, 'parse');
     let communityResult;
     let processResult;
+    // Standalone-ingest warnings, passed through opaquely (language-neutral).
+    let ingestWarnings;
+    try {
+        ingestWarnings = getPhaseOutput(results, 'standaloneIngest').ingestWarnings;
+    }
+    catch {
+        /* phase filtered out of this run — nothing to surface */
+    }
     const scopeResolutionOutput = getPhaseOutput(results, 'scopeResolution');
     const resolutionOutcomes = scopeResolutionOutput.resolutionOutcomes;
     // Streamed PDG-emit manifest (#2202): present only when streaming was on.
@@ -107,5 +118,6 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
         resolutionOutcomes,
         usedWorkerPool,
         pdgEmitManifest,
+        ingestWarnings,
     };
 };

package/dist/core/ingestion/resolve-references.js

@@ -66,6 +66,12 @@ export function resolveReferenceSites(input) {
     let referencesEmitted = 0;
     let unresolved = 0;
     for (const site of scopes.referenceSites) {
+        // value-ref sites resolve post-finalize (imports live in finalized
+        // bindings the registries can't see — same reason free calls need
+        // `emitFreeCallFallback`). `emitPropertyDispatchCalls` owns their
+        // resolution and emission entirely (#2437).
+        if (site.kind === 'value-ref')
+            continue;
         sitesProcessed++;
         const resolutions = lookupForSite(site, classRegistry, methodRegistry, fieldRegistry, macroRegistry);
         if (resolutions.length === 0) {
@@ -113,6 +119,7 @@ export function resolveReferenceSites(input) {
  *   | `type-reference` | ClassRegistry     | CLASS_KINDS                  |
  *   | `read`/`write`   | FieldRegistry     | FIELD_KINDS                  |
  *   | `import-use`     | tiered fallback   | METHOD ∪ CLASS ∪ FIELD       |
+ *   | `value-ref`      | (skipped here)    | post-finalize walker in `emitPropertyDispatchCalls` |
  *   | `macro`          | MacroRegistry     | MACRO_KINDS (`Macro` only)   |
  *
  * `macro` has its own single-kind registry so a macro invocation
@@ -166,6 +173,11 @@ function lookupForSite(site, classRegistry, methodRegistry, fieldRegistry, macro
                 return methodHits;
             return fieldRegistry.lookup(site.name, site.inScope);
         }
+        case 'value-ref': {
+            // Unreachable — filtered before lookup (post-finalize resolution in
+            // `emitPropertyDispatchCalls`, #2437). Kept for switch exhaustiveness.
+            return [];
+        }
         case 'macro': {
             // Macro-only namespace: resolves against `Macro`-labeled defs, never
             // functions. No receiver, no arity — see `MacroRegistry`.

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;