gitnexus 1.6.9 → 1.6.10-rc.10

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);
+}

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

@@ -0,0 +1,75 @@
+/**
+ * Python binding for the language-agnostic constant resolver (#2391).
+ *
+ * Supplies the two Python-specific pieces the shared fold in
+ * `constant-resolver.ts` needs — {@link resolvePythonImport} (import-specifier →
+ * file, honoring leading-dot relative imports and `.py` module files) and
+ * {@link extractPythonModuleConstants} (tree → {@link ModuleConstants}) — plus
+ * pre-bound {@link resolveConstant}/{@link resolveOperands} wrappers so Python
+ * callers stay language-oblivious. The reusable fold, the cycle guard, and the
+ * depth cap all live in the agnostic core; a JVM/other language binding reuses
+ * that core with its own `ImportResolver` + extractor.
+ *
+ * Keying (KTD4): the repo map is keyed by unique POSIX file path, NOT the
+ * dot-stripped module basename. `from .constants import X`,
+ * `from ..pkg.constants import X`, and `from constants import X` all collapse to
+ * the basename `constants` — a ubiquitous filename — so basename keying would
+ * resolve one package's routes to another's literal (a confidently WRONG path,
+ * worse than an unresolved one). A relative import is therefore resolved against
+ * the importing file's package directory (walk up one level per leading dot); an
+ * absolute import is matched by unique path suffix and returns `null` (skip
+ * floor) when ambiguous.
+ */
+import { type SyntaxNode } from '../utils/ast-helpers.js';
+import type Parser from 'tree-sitter';
+import { type ImportResolver, type ModuleConstants, type Operand, type RepoConstants } from './constant-resolver.js';
+export type { ImportBinding, ModuleConstants, Operand, RepoConstants, } from './constant-resolver.js';
+/**
+ * The Python {@link ImportResolver}: map an import specifier to the unique file
+ * key it refers to, or `null` when it cannot be pinned to exactly one file (KTD4).
+ *
+ * Relative imports (`.constants`, `..pkg.mod`) resolve against the importing
+ * file's directory — one level up per leading dot beyond the first — and must
+ * hit an existing file key exactly. Absolute imports (`api.constants`) are
+ * matched by unique path suffix; a suffix shared by 2+ files is ambiguous and
+ * returns `null` rather than an arbitrary winner.
+ */
+export declare const resolvePythonImport: ImportResolver;
+/**
+ * Resolve a single named Python constant referenced in `fileKey` to its literal
+ * value, or `null`. Python-bound wrapper over the agnostic fold.
+ */
+export declare function resolveConstant(fileKey: string, name: string, repo: RepoConstants): string | null;
+/**
+ * Resolve an inline Python operand list (an unnamed `+`-expression at a decorator
+ * argument, e.g. `@router.get(API_V1 + "/widgets")`) against `fileKey`.
+ * Python-bound wrapper over the agnostic fold.
+ */
+export declare function resolveOperands(fileKey: string, operands: readonly Operand[], repo: RepoConstants): string | null;
+/**
+ * Parse a Python right-hand side into an operand list, or `null` when it is not a
+ * foldable string expression. Handles a bare string literal, a bare identifier
+ * (`X = Y`), and left-associative `+` chains of the two (`A + "/b" + C`).
+ * Everything else — numbers, calls, attribute access (`settings.X`), f-strings,
+ * conditional expressions (`x if c else y`), `concatenated_string` adjacency, and
+ * non-`+` operators — returns `null`, which makes the constant unresolvable
+ * (→ skip floor), never a wrong value.
+ */
+export declare function parseConstOperands(node: SyntaxNode | null | undefined, depth?: number): Operand[] | null;
+/**
+ * Extract the module-level string constants and `from … import …` bindings of
+ * one parsed Python file into the {@link ModuleConstants} shape the resolver
+ * consumes. Only top-level (`module`-direct) statements are walked — function-
+ * and class-local names never become route path constants and must not leak in.
+ *
+ * Assignment semantics are last-wins in source order (matches Python): a rebind
+ * to a non-string (`X = "/a"; X = build()`) drops `X` to unresolvable rather than
+ * keeping the stale literal; `X += "/b"` folds onto the prior representation.
+ *
+ * Assignment RHS references are SNAPSHOTTED at the assignment line (`snapshot`),
+ * not resolved lazily against a name's final binding — so `ROUTE = BASE; BASE +=
+ * "/v1"` leaves `ROUTE` at BASE's value AT the `ROUTE =` line, never the mutated
+ * one. Without this, an aliased-then-rebound constant resolved to a confidently
+ * wrong path (#2393).
+ */
+export declare function extractPythonModuleConstants(tree: Parser.Tree): ModuleConstants;

package/dist/core/ingestion/route-extractors/python-const-resolver.js

@@ -0,0 +1,299 @@
+/**
+ * Python binding for the language-agnostic constant resolver (#2391).
+ *
+ * Supplies the two Python-specific pieces the shared fold in
+ * `constant-resolver.ts` needs — {@link resolvePythonImport} (import-specifier →
+ * file, honoring leading-dot relative imports and `.py` module files) and
+ * {@link extractPythonModuleConstants} (tree → {@link ModuleConstants}) — plus
+ * pre-bound {@link resolveConstant}/{@link resolveOperands} wrappers so Python
+ * callers stay language-oblivious. The reusable fold, the cycle guard, and the
+ * depth cap all live in the agnostic core; a JVM/other language binding reuses
+ * that core with its own `ImportResolver` + extractor.
+ *
+ * Keying (KTD4): the repo map is keyed by unique POSIX file path, NOT the
+ * dot-stripped module basename. `from .constants import X`,
+ * `from ..pkg.constants import X`, and `from constants import X` all collapse to
+ * the basename `constants` — a ubiquitous filename — so basename keying would
+ * resolve one package's routes to another's literal (a confidently WRONG path,
+ * worse than an unresolved one). A relative import is therefore resolved against
+ * the importing file's package directory (walk up one level per leading dot); an
+ * absolute import is matched by unique path suffix and returns `null` (skip
+ * floor) when ambiguous.
+ */
+import { extractStringContent } from '../utils/ast-helpers.js';
+import { resolveConstant as foldConstant, resolveOperands as foldOperands, } from './constant-resolver.js';
+function dirOf(fileKey) {
+    const slash = fileKey.lastIndexOf('/');
+    return slash >= 0 ? fileKey.slice(0, slash) : '';
+}
+/** Collapse `a/b/../c` and `./` segments in a POSIX-ish path. */
+function normalizePosix(path) {
+    const out = [];
+    for (const seg of path.split('/')) {
+        if (seg === '' || seg === '.')
+            continue;
+        if (seg === '..') {
+            if (out.length > 0 && out[out.length - 1] !== '..')
+                out.pop();
+            else
+                out.push('..');
+        }
+        else {
+            out.push(seg);
+        }
+    }
+    return out.join('/');
+}
+/**
+ * The Python {@link ImportResolver}: map an import specifier to the unique file
+ * key it refers to, or `null` when it cannot be pinned to exactly one file (KTD4).
+ *
+ * Relative imports (`.constants`, `..pkg.mod`) resolve against the importing
+ * file's directory — one level up per leading dot beyond the first — and must
+ * hit an existing file key exactly. Absolute imports (`api.constants`) are
+ * matched by unique path suffix; a suffix shared by 2+ files is ambiguous and
+ * returns `null` rather than an arbitrary winner.
+ */
+export const resolvePythonImport = (importingFileKey, moduleSpec, repoKeys) => {
+    const dots = moduleSpec.length - moduleSpec.replace(/^\.+/, '').length;
+    const bare = moduleSpec.slice(dots);
+    const modPath = bare.replace(/\./g, '/');
+    if (dots > 0) {
+        // 1 dot = current package (the importing file's dir); each extra dot walks
+        // up one more level. If the walk would climb ABOVE the repo root (more extra
+        // dots than the importing file has directory levels), the import escapes the
+        // tree → null, rather than clamping to an unrelated root-level `<name>.py`.
+        const dir = dirOf(importingFileKey);
+        const depth = dir === '' ? 0 : dir.split('/').length;
+        const walk = dots - 1;
+        if (walk > depth)
+            return null;
+        let base = dir;
+        for (let i = 0; i < walk; i++)
+            base = dirOf(base);
+        // `from . import X` / `from .. import X` (no module after the dots): the
+        // module IS the package, whose file is `<base>/__init__.py`, not a sibling
+        // `<base>.py`.
+        const candidate = modPath === ''
+            ? base === ''
+                ? '__init__.py'
+                : `${base}/__init__.py`
+            : normalizePosix(`${base}/${modPath}`) + '.py';
+        return repoKeys.has(candidate) ? candidate : null;
+    }
+    // Absolute: match by unique path suffix. `api.constants` -> `api/constants.py`.
+    const suffix = `${modPath}.py`;
+    let hit = null;
+    for (const key of repoKeys) {
+        if (key === suffix || key.endsWith(`/${suffix}`)) {
+            if (hit !== null)
+                return null; // ambiguous — refuse to guess
+            hit = key;
+        }
+    }
+    return hit;
+};
+/**
+ * Resolve a single named Python constant referenced in `fileKey` to its literal
+ * value, or `null`. Python-bound wrapper over the agnostic fold.
+ */
+export function resolveConstant(fileKey, name, repo) {
+    return foldConstant(fileKey, name, repo, resolvePythonImport);
+}
+/**
+ * Resolve an inline Python operand list (an unnamed `+`-expression at a decorator
+ * argument, e.g. `@router.get(API_V1 + "/widgets")`) against `fileKey`.
+ * Python-bound wrapper over the agnostic fold.
+ */
+export function resolveOperands(fileKey, operands, repo) {
+    return foldOperands(fileKey, operands, repo, resolvePythonImport);
+}
+/**
+ * Parse a Python right-hand side into an operand list, or `null` when it is not a
+ * foldable string expression. Handles a bare string literal, a bare identifier
+ * (`X = Y`), and left-associative `+` chains of the two (`A + "/b" + C`).
+ * Everything else — numbers, calls, attribute access (`settings.X`), f-strings,
+ * conditional expressions (`x if c else y`), `concatenated_string` adjacency, and
+ * non-`+` operators — returns `null`, which makes the constant unresolvable
+ * (→ skip floor), never a wrong value.
+ */
+export function parseConstOperands(node, depth = 0) {
+    if (!node)
+        return null;
+    // Defense-in-depth: bound the recursion so an adversarial deep `+`-chain floors
+    // to null (skip) rather than risking a stack overflow. 64 is far beyond any real
+    // route-path constant chain; tree-sitter caps expression nesting well below the
+    // JS stack limit today, so this is a belt-and-suspenders guard, not a reachable
+    // crash. Mirrors the fold engine's MAX_RESOLVE_DEPTH.
+    if (depth > 64)
+        return null;
+    if (node.type === 'string') {
+        const value = extractStringContent(node);
+        return value === null ? null : [{ kind: 'literal', value }];
+    }
+    if (node.type === 'identifier') {
+        return [{ kind: 'ref', name: node.text }];
+    }
+    if (node.type === 'binary_operator') {
+        const isPlus = (node.children ?? []).some((c) => c.type === '+');
+        if (!isPlus)
+            return null;
+        const left = parseConstOperands(node.childForFieldName('left'), depth + 1);
+        const right = parseConstOperands(node.childForFieldName('right'), depth + 1);
+        if (left === null || right === null)
+            return null;
+        return [...left, ...right];
+    }
+    return null;
+}
+/**
+ * Extract the module-level string constants and `from … import …` bindings of
+ * one parsed Python file into the {@link ModuleConstants} shape the resolver
+ * consumes. Only top-level (`module`-direct) statements are walked — function-
+ * and class-local names never become route path constants and must not leak in.
+ *
+ * Assignment semantics are last-wins in source order (matches Python): a rebind
+ * to a non-string (`X = "/a"; X = build()`) drops `X` to unresolvable rather than
+ * keeping the stale literal; `X += "/b"` folds onto the prior representation.
+ *
+ * Assignment RHS references are SNAPSHOTTED at the assignment line (`snapshot`),
+ * not resolved lazily against a name's final binding — so `ROUTE = BASE; BASE +=
+ * "/v1"` leaves `ROUTE` at BASE's value AT the `ROUTE =` line, never the mutated
+ * one. Without this, an aliased-then-rebound constant resolved to a confidently
+ * wrong path (#2393).
+ */
+export function extractPythonModuleConstants(tree) {
+    const literals = new Map();
+    const exprs = new Map();
+    const imports = new Map();
+    // Monotonic counter for synthetic import-alias keys (see the `+=`-on-import
+    // case in the augmented-assignment branch below). Per-file, so keys are unique
+    // within this file's ModuleConstants.
+    let importAliasSeq = 0;
+    // The three maps are ONE logical namespace keyed by local name: a write to any
+    // one clears the other two, so last-binding-in-source-order wins (matches
+    // Python) and a name never carries a stale binding from a different map (#2391,
+    // #2393). Without this, `from .c import X; X = <dynamic>` would keep the stale
+    // import and resolve a confidently WRONG path instead of dropping.
+    // Apply an assignment result, honoring last-wins: clear any prior binding for
+    // `name` (including a shadowed import), then set the new one (a `null` rep
+    // leaves it cleared = unresolvable).
+    const setName = (name, ops) => {
+        literals.delete(name);
+        exprs.delete(name);
+        imports.delete(name);
+        if (ops === null)
+            return;
+        if (ops.length === 1 && ops[0].kind === 'literal')
+            literals.set(name, ops[0].value);
+        else
+            exprs.set(name, ops);
+    };
+    // Bind an import for `localName`, clearing any prior local literal/expr of the
+    // same name (an import shadows an earlier assignment, and vice versa).
+    const bindImport = (localName, binding) => {
+        literals.delete(localName);
+        exprs.delete(localName);
+        imports.set(localName, binding);
+    };
+    // Freeze a name's CURRENT binding into a stable operand list that is immune to
+    // any LATER rebind of `name`: a literal value, a copy of the current expr (whose
+    // refs are themselves already frozen, see `snapshot`), or an import preserved
+    // under a synthetic `$imp$N` key (`$` can never appear in a Python identifier, so
+    // it cannot collide with a real name). Returns null when `name` is not yet bound
+    // (a forward reference — left lazy).
+    const freeze = (name) => {
+        const lit = literals.get(name);
+        if (lit !== undefined)
+            return [{ kind: 'literal', value: lit }];
+        const ex = exprs.get(name);
+        if (ex !== undefined)
+            return [...ex];
+        const imp = imports.get(name);
+        if (imp !== undefined) {
+            const aliasKey = `$imp$${importAliasSeq++}`;
+            imports.set(aliasKey, imp);
+            return [{ kind: 'ref', name: aliasKey }];
+        }
+        return null;
+    };
+    // Snapshot an assignment RHS: replace each ref to an ALREADY-BOUND name with that
+    // name's frozen value, so a later rebind of that name does not retroactively
+    // change this binding — Python assigns by value at this source line, so
+    // `ROUTE = BASE; BASE += "/v1"` must leave ROUTE at BASE's value AT the `ROUTE =`
+    // line, never the mutated one (#2393). Unbound refs (forward references) stay
+    // lazy. Because every assignment snapshots, stored exprs only ever contain
+    // literals, frozen `$imp$N` refs, or lazy forward refs — never a live mutable ref.
+    const snapshot = (ops) => {
+        if (ops === null)
+            return null;
+        const out = [];
+        for (const op of ops) {
+            if (op.kind === 'literal') {
+                out.push(op);
+                continue;
+            }
+            const frozen = freeze(op.name);
+            if (frozen === null)
+                out.push(op);
+            else
+                out.push(...frozen);
+        }
+        return out;
+    };
+    const handleImport = (node) => {
+        const moduleNode = node.childForFieldName('module_name');
+        const moduleSpec = moduleNode?.text;
+        if (!moduleSpec)
+            return;
+        for (let i = 0; i < node.namedChildCount; i++) {
+            const child = node.namedChild(i);
+            if (!child || child.id === moduleNode?.id)
+                continue;
+            if (child.type === 'dotted_name') {
+                bindImport(child.text, { module: moduleSpec, originalName: child.text });
+            }
+            else if (child.type === 'aliased_import') {
+                const nameNode = child.childForFieldName('name');
+                const aliasNode = child.childForFieldName('alias');
+                if (nameNode && aliasNode) {
+                    bindImport(aliasNode.text, { module: moduleSpec, originalName: nameNode.text });
+                }
+            }
+        }
+    };
+    for (let i = 0; i < tree.rootNode.namedChildCount; i++) {
+        const stmt = tree.rootNode.namedChild(i);
+        if (!stmt)
+            continue;
+        if (stmt.type === 'import_from_statement') {
+            handleImport(stmt);
+            continue;
+        }
+        if (stmt.type !== 'expression_statement')
+            continue;
+        const inner = stmt.namedChild(0);
+        if (!inner)
+            continue;
+        if (inner.type === 'assignment') {
+            const left = inner.childForFieldName('left');
+            if (left?.type !== 'identifier')
+                continue; // only bare-name module constants
+            setName(left.text, snapshot(parseConstOperands(inner.childForFieldName('right'))));
+        }
+        else if (inner.type === 'augmented_assignment') {
+            const left = inner.childForFieldName('left');
+            if (left?.type !== 'identifier')
+                continue;
+            const name = left.text;
+            const isPlusEq = inner.childForFieldName('operator')?.text === '+=';
+            // `X += rhs` folds onto X's CURRENT frozen value (`freeze` handles a local
+            // literal/expr and an imported base via the `$imp$N` alias). Both sides are
+            // snapshotted so a later rebind cannot retroactively change this binding.
+            const prior = freeze(name);
+            const rhs = snapshot(parseConstOperands(inner.childForFieldName('right')));
+            setName(name, isPlusEq && prior && rhs ? [...prior, ...rhs] : null);
+        }
+    }
+    return { literals, exprs, imports };
+}

package/dist/core/ingestion/tree-sitter-queries.d.ts

@@ -1,6 +1,6 @@
 export declare const TYPESCRIPT_QUERIES: string;
 export declare const JAVASCRIPT_QUERIES: string;
-export declare const PYTHON_QUERIES = "\n(class_definition\n  name: (identifier) @name) @definition.class\n\n(function_definition\n  name: (identifier) @name) @definition.function\n\n(import_statement\n  name: (dotted_name) @import.source) @import\n\n; import numpy as np  \u2192  aliased_import captures the module name so the\n; import path is resolved and named-binding extraction stores \"np\" \u2192 \"numpy\".\n(import_statement\n  name: (aliased_import\n    name: (dotted_name) @import.source)) @import\n\n(import_from_statement\n  module_name: (dotted_name) @import.source) @import\n\n(import_from_statement\n  module_name: (relative_import) @import.source) @import\n\n(call\n  function: (identifier) @call.name) @call\n\n(call\n  function: (attribute\n    attribute: (identifier) @call.name)) @call\n\n; Class attribute type annotations \u2014 PEP 526: address: Address or address: Address = Address()\n; Both bare annotations (address: Address) and annotated assignments (name: str = \"test\")\n; are parsed as (assignment left: ... type: ...) in tree-sitter-python.\n(expression_statement\n  (assignment\n    left: (identifier) @name\n    type: (type)) @definition.property)\n\n; Plain variable assignments without type annotation: x = 5, MAX_SIZE = 100\n; Overlap with @definition.property (typed) is handled by parse-worker dedup.\n(expression_statement\n  (assignment\n    left: (identifier) @name)) @definition.variable\n\n; Write access: obj.field = value\n(assignment\n  left: (attribute\n    object: (_) @assignment.receiver\n    attribute: (identifier) @assignment.property)\n  right: (_)) @assignment\n\n; Write access: obj.field += value (compound assignment)\n(augmented_assignment\n  left: (attribute\n    object: (_) @assignment.receiver\n    attribute: (identifier) @assignment.property)\n  right: (_)) @assignment\n\n; Python HTTP clients: requests.get('/path'), httpx.post('/path'), session.get('/path')\n(call\n  function: (attribute\n    attribute: (identifier) @http_client.method)\n  arguments: (argument_list\n    (string (string_content) @http_client.url))) @http_client\n\n; Python decorators: @app.route, @router.get, etc.\n(decorator\n  (call\n    function: (attribute\n      object: (identifier) @decorator.receiver\n      attribute: (identifier) @decorator.name)\n    arguments: (argument_list\n      (string (string_content) @decorator.arg)?))) @decorator\n";
+export declare const PYTHON_QUERIES = "\n(class_definition\n  name: (identifier) @name) @definition.class\n\n(function_definition\n  name: (identifier) @name) @definition.function\n\n(import_statement\n  name: (dotted_name) @import.source) @import\n\n; import numpy as np  \u2192  aliased_import captures the module name so the\n; import path is resolved and named-binding extraction stores \"np\" \u2192 \"numpy\".\n(import_statement\n  name: (aliased_import\n    name: (dotted_name) @import.source)) @import\n\n(import_from_statement\n  module_name: (dotted_name) @import.source) @import\n\n(import_from_statement\n  module_name: (relative_import) @import.source) @import\n\n(call\n  function: (identifier) @call.name) @call\n\n(call\n  function: (attribute\n    attribute: (identifier) @call.name)) @call\n\n; Class attribute type annotations \u2014 PEP 526: address: Address or address: Address = Address()\n; Both bare annotations (address: Address) and annotated assignments (name: str = \"test\")\n; are parsed as (assignment left: ... type: ...) in tree-sitter-python.\n(expression_statement\n  (assignment\n    left: (identifier) @name\n    type: (type)) @definition.property)\n\n; Plain variable assignments without type annotation: x = 5, MAX_SIZE = 100\n; Overlap with @definition.property (typed) is handled by parse-worker dedup.\n(expression_statement\n  (assignment\n    left: (identifier) @name)) @definition.variable\n\n; Write access: obj.field = value\n(assignment\n  left: (attribute\n    object: (_) @assignment.receiver\n    attribute: (identifier) @assignment.property)\n  right: (_)) @assignment\n\n; Write access: obj.field += value (compound assignment)\n(augmented_assignment\n  left: (attribute\n    object: (_) @assignment.receiver\n    attribute: (identifier) @assignment.property)\n  right: (_)) @assignment\n\n; Python HTTP clients: requests.get('/path'), httpx.post('/path'), session.get('/path')\n(call\n  function: (attribute\n    attribute: (identifier) @http_client.method)\n  arguments: (argument_list\n    (string (string_content) @http_client.url))) @http_client\n\n; Python decorators: @app.route, @router.get, etc.\n; The first positional argument is captured three ways (#2391): a string literal\n; path via @decorator.arg (quote-free, the fast path); a bare constant name or a\n; plus-concatenation via @decorator.arg_expr (resolved cross-file by the constant\n; resolver). The anchored optional alternation pins to the FIRST arg and stays\n; optional, so no-arg decorators (@app.tool(), etc.) and non-path first args still\n; match.\n(decorator\n  (call\n    function: (attribute\n      object: (identifier) @decorator.receiver\n      attribute: (identifier) @decorator.name)\n    arguments: (argument_list\n      .\n      [\n        (string (string_content)? @decorator.arg) @decorator.arg_str\n        (identifier) @decorator.arg_expr\n        (binary_operator) @decorator.arg_expr\n      ]?))) @decorator\n";
 export declare const JAVA_QUERIES = "\n; Classes, Interfaces, Enums, Annotations\n(class_declaration name: (identifier) @name) @definition.class\n(interface_declaration name: (identifier) @name) @definition.interface\n(enum_declaration name: (identifier) @name) @definition.enum\n(annotation_type_declaration name: (identifier) @name) @definition.annotation\n\n; Methods & Constructors\n(method_declaration name: (identifier) @name) @definition.method\n(constructor_declaration name: (identifier) @name) @definition.constructor\n\n; Fields \u2014 typed field declarations inside class bodies\n(field_declaration\n  declarator: (variable_declarator\n    name: (identifier) @name)) @definition.property\n\n; Imports - capture any import declaration child as source\n(import_declaration (_) @import.source) @import\n\n; Calls\n(method_invocation name: (identifier) @call.name) @call\n(method_invocation object: (_) name: (identifier) @call.name) @call\n(method_reference) @call\n\n; Constructor calls: new Foo()\n(object_creation_expression type: (type_identifier) @call.name) @call\n\n; Local variable declarations inside method bodies\n(local_variable_declaration\n  declarator: (variable_declarator\n    name: (identifier) @name)) @definition.variable\n\n; Write access: obj.field = value\n(assignment_expression\n  left: (field_access\n    object: (_) @assignment.receiver\n    field: (identifier) @assignment.property)\n  right: (_)) @assignment\n";
 export declare const C_QUERIES = "\n; Functions (direct declarator)\n(function_definition declarator: (function_declarator declarator: (identifier) @name)) @definition.function\n(declaration declarator: (function_declarator declarator: (identifier) @name)) @definition.function\n\n; Functions returning pointers (pointer_declarator wraps function_declarator)\n(function_definition declarator: (pointer_declarator declarator: (function_declarator declarator: (identifier) @name))) @definition.function\n(declaration declarator: (pointer_declarator declarator: (function_declarator declarator: (identifier) @name))) @definition.function\n\n; Functions returning double pointers (nested pointer_declarator)\n(function_definition declarator: (pointer_declarator declarator: (pointer_declarator declarator: (function_declarator declarator: (identifier) @name)))) @definition.function\n\n; Structs, Unions, Enums, Typedefs\n(struct_specifier name: (type_identifier) @name) @definition.struct\n(type_definition\n  type: (struct_specifier\n    body: (field_declaration_list))\n  declarator: (type_identifier) @name) @definition.struct\n(union_specifier name: (type_identifier) @name) @definition.union\n(enum_specifier name: (type_identifier) @name) @definition.enum\n(type_definition\n  type: (enum_specifier\n    body: (enumerator_list))\n  declarator: (type_identifier) @name) @definition.enum\n(enumerator name: (identifier) @name) @definition.const\n(type_definition declarator: (type_identifier) @name) @definition.typedef\n\n; Macros\n(preproc_function_def name: (identifier) @name) @definition.macro\n(preproc_def name: (identifier) @name) @definition.macro\n\n; Includes\n(preproc_include path: (_) @import.source) @import\n\n; Calls\n(call_expression function: (identifier) @call.name) @call\n(call_expression function: (field_expression field: (field_identifier) @call.name)) @call\n\n; Variable declarations: int x = 5; or int x;\n(declaration\n  declarator: (init_declarator\n    declarator: (identifier) @name)) @definition.variable\n";
 export declare const GO_QUERIES = "\n; Functions & Methods\n(function_declaration name: (identifier) @name) @definition.function\n(method_declaration name: (field_identifier) @name) @definition.method\n(method_elem name: (field_identifier) @name) @definition.method\n\n; Types\n(type_declaration (type_spec name: (type_identifier) @name type: (struct_type))) @definition.struct\n(type_declaration (type_spec name: (type_identifier) @name type: (interface_type))) @definition.interface\n\n; Imports\n(import_declaration (import_spec path: (interpreted_string_literal) @import.source)) @import\n(import_declaration (import_spec_list (import_spec path: (interpreted_string_literal) @import.source))) @import\n\n; Struct fields \u2014 named field declarations inside struct types\n(field_declaration_list\n  (field_declaration\n    name: (field_identifier) @name) @definition.property)\n\n; Calls\n(call_expression function: (identifier) @call.name) @call\n(call_expression function: (selector_expression field: (field_identifier) @call.name)) @call\n\n; Const/var declarations\n(const_declaration (const_spec (identifier) @name)) @definition.const\n(var_declaration (var_spec (identifier) @name)) @definition.variable\n(var_declaration (var_spec_list (var_spec (identifier) @name))) @definition.variable\n\n; Short variable declaration: x := 5\n(short_var_declaration left: (expression_list (identifier) @name)) @definition.variable\n\n; Struct literal construction: User{Name: \"Alice\"}\n(composite_literal type: (type_identifier) @call.name) @call\n\n; Write access: obj.field = value\n(assignment_statement\n  left: (expression_list\n    (selector_expression\n      operand: (_) @assignment.receiver\n      field: (field_identifier) @assignment.property))\n  right: (_)) @assignment\n\n; Write access: obj.field++ / obj.field--\n(inc_statement\n  (selector_expression\n    operand: (_) @assignment.receiver\n    field: (field_identifier) @assignment.property)) @assignment\n(dec_statement\n  (selector_expression\n    operand: (_) @assignment.receiver\n    field: (field_identifier) @assignment.property)) @assignment\n";

package/dist/core/ingestion/tree-sitter-queries.js

@@ -717,13 +717,24 @@ export const PYTHON_QUERIES = `
     (string (string_content) @http_client.url))) @http_client
 
 ; Python decorators: @app.route, @router.get, etc.
+; The first positional argument is captured three ways (#2391): a string literal
+; path via @decorator.arg (quote-free, the fast path); a bare constant name or a
+; plus-concatenation via @decorator.arg_expr (resolved cross-file by the constant
+; resolver). The anchored optional alternation pins to the FIRST arg and stays
+; optional, so no-arg decorators (@app.tool(), etc.) and non-path first args still
+; match.
 (decorator
   (call
     function: (attribute
       object: (identifier) @decorator.receiver
       attribute: (identifier) @decorator.name)
     arguments: (argument_list
-      (string (string_content) @decorator.arg)?))) @decorator
+      .
+      [
+        (string (string_content)? @decorator.arg) @decorator.arg_str
+        (identifier) @decorator.arg_expr
+        (binary_operator) @decorator.arg_expr
+      ]?))) @decorator
 `;
 // Java queries - works with tree-sitter-java
 export const JAVA_QUERIES = `

package/dist/core/ingestion/utils/line-base.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Convert a 1-based source line number to the 0-based convention used by
+ * GraphNode `startLine`/`endLine`.
+ *
+ * The graph layer stores line numbers 0-based (tree-sitter `startPosition.row`),
+ * and this is load-bearing: the taint/PDG/CFG join and the MCP consumers all add
+ * `+ 1` to recover 1-based (see `summary-harvest-driver.ts` — "Function/Method
+ * node startLine is 0-based"). Most emitters get 0-based for free from
+ * tree-sitter. The exceptions are the regex-based COBOL/JCL processors (their
+ * parsers use `lineNum = i + 1`) and the scope-capture path (`Capture` ranges
+ * are 1-based per RFC §2.1). Those must convert to 0-based when they build a
+ * graph node, or the exact-content slice in `csv-generator.ts` drops the
+ * symbol's declaration line (#2379) and reported line numbers are off (#2377).
+ *
+ * Apply this ONLY at the graph-node `startLine:`/`endLine:` assignment. The
+ * parser-internal 1-based values (`.line`, `prog.startLine`) stay 1-based —
+ * they feed `L${line}` node/edge IDs and line-range containment checks that
+ * must not shift. The clamp guards degenerate inputs (line 0 / empty files).
+ */
+export declare const toZeroBasedLine: (oneBasedLine: number) => number;