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

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;

package/dist/core/ingestion/utils/line-base.js

@@ -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 const toZeroBasedLine = (oneBasedLine) => Math.max(0, oneBasedLine - 1);

package/dist/core/ingestion/utils/symbol-labels.d.ts

@@ -0,0 +1,21 @@
+import type { NodeLabel } from '../../../_shared/index.js';
+/**
+ * Graph-node labels that represent a resolvable code symbol — a definition with
+ * its own source span (function, type, member, module-like container).
+ *
+ * These get EXACT source-span content in the FTS index: `csv-generator.ts`
+ * slices exactly `[startLine, endLine]` for them (no ±2 padding), while every
+ * other label keeps the context window. That exactness depends on the 0-based
+ * `startLine`/`endLine` invariant enforced by `line-base.ts` — the slice is only
+ * correct because all emitters store 0-based lines. Keep the two together.
+ *
+ * Single source of truth so the set can't silently drift the way the inline copy
+ * did in #2379.
+ *
+ * NOTE: `group/extractors/manifest-extractor.ts`'s `CUSTOM_CONTRACT_RESOLVE_QUERY`
+ * carries a near-identical hand-list that is intentionally a SUBSET — it excludes
+ * `Namespace`, `Variable`, `Module`. Unifying the two needs a contract-resolution
+ * behavior check (would widen which nodes resolve as contract symbols), so it is
+ * deliberately left separate for now.
+ */
+export declare const SYMBOL_NODE_LABELS: ReadonlySet<NodeLabel>;

package/dist/core/ingestion/utils/symbol-labels.js

@@ -0,0 +1,45 @@
+/**
+ * Graph-node labels that represent a resolvable code symbol — a definition with
+ * its own source span (function, type, member, module-like container).
+ *
+ * These get EXACT source-span content in the FTS index: `csv-generator.ts`
+ * slices exactly `[startLine, endLine]` for them (no ±2 padding), while every
+ * other label keeps the context window. That exactness depends on the 0-based
+ * `startLine`/`endLine` invariant enforced by `line-base.ts` — the slice is only
+ * correct because all emitters store 0-based lines. Keep the two together.
+ *
+ * Single source of truth so the set can't silently drift the way the inline copy
+ * did in #2379.
+ *
+ * NOTE: `group/extractors/manifest-extractor.ts`'s `CUSTOM_CONTRACT_RESOLVE_QUERY`
+ * carries a near-identical hand-list that is intentionally a SUBSET — it excludes
+ * `Namespace`, `Variable`, `Module`. Unifying the two needs a contract-resolution
+ * behavior check (would widen which nodes resolve as contract symbols), so it is
+ * deliberately left separate for now.
+ */
+export const SYMBOL_NODE_LABELS = new Set([
+    'Function',
+    'Method',
+    'Class',
+    'Interface',
+    'CodeElement',
+    'Struct',
+    'Enum',
+    'Macro',
+    'Typedef',
+    'Union',
+    'Namespace',
+    'Trait',
+    'Impl',
+    'TypeAlias',
+    'Const',
+    'Static',
+    'Variable',
+    'Property',
+    'Record',
+    'Delegate',
+    'Annotation',
+    'Constructor',
+    'Template',
+    'Module',
+]);

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

@@ -113,6 +113,21 @@ export interface ExtractedDecoratorRoute {
      * participate in `include_router(prefix=...)` joining.
      */
     decoratorReceiver?: string;
+    /**
+     * Raw text of a non-literal decorator path argument (`#2391`), e.g.
+     * `API_V1_WIDGETS_GET` or `API_V1 + "/widgets"`. Present only when the
+     * decorator's first argument was NOT a string literal, in which case
+     * `routePath` is empty and parse-impl resolves the constant cross-file (or
+     * drops the route on failure). Absent for ordinary string-literal routes.
+     */
+    routePathExpr?: string;
+    /**
+     * Parsed operand list for {@link routePathExpr} — an identifier reference or a
+     * `+`-concatenation, in the {@link Operand} shape the constant resolver folds.
+     * `undefined` when the expression was not a foldable string form (e.g. an
+     * attribute access), in which case the route is dropped at resolution.
+     */
+    routePathOperands?: Operand[];
     /**
      * FastAPI `app.include_router(prefix='/x')` prefix that applies to
      * this route. Filled by parse-impl after cross-file aggregation; the
@@ -131,6 +146,17 @@ export interface ExtractedDecoratorRoute {
      */
     handlerName?: string;
 }
+/**
+ * One Python file's module-level string constants (#2391), used by parse-impl to
+ * resolve non-literal decorator route paths cross-file. `constants` is the
+ * `Map`-based {@link ModuleConstants} shape — it survives the worker
+ * `postMessage` boundary (structured clone) and the parse cache
+ * (`mapReplacer`/`mapReviver`) without conversion.
+ */
+export interface ExtractedModuleConstants {
+    filePath: string;
+    constants: ModuleConstants;
+}
 export interface ExtractedToolDef {
     filePath: string;
     toolName: string;
@@ -211,6 +237,13 @@ export interface ParseWorkerResult {
      * predate the field; consumers must guard with `if (… ?? [])`).
      */
     routerModuleAliases?: ExtractedRouterModuleAlias[];
+    /**
+     * Per-file Python module-level string constants (#2391). parse-impl aggregates
+     * these into a repo-wide, file-path-keyed map and resolves each decorator
+     * route's non-literal path expression against it. Optional for cache backward
+     * compatibility (older entries predate the field; consumers guard with `?? []`).
+     */
+    moduleConstants?: ExtractedModuleConstants[];
     toolDefs: ExtractedToolDef[];
     ormQueries: ExtractedORMQuery[];
     constructorBindings: FileConstructorBindings[];
@@ -256,3 +289,4 @@ export interface ParseWorkerInput {
  * Appends results to the provided array (avoids allocation when no matches).
  */
 export declare function extractORMQueries(filePath: string, content: string, out: ExtractedORMQuery[]): void;
+import { type ModuleConstants, type Operand } from '../route-extractors/python-const-resolver.js';