cgraphx 2.0.2 → 2.0.3

package/dist/core/code/engine/core/ingestion/languages/python/captures.js

@@ -0,0 +1,299 @@
+"use strict";
+/**
+ * `emitScopeCaptures` for Python.
+ *
+ * Drives the scope query against `tree-sitter-python` and groups raw
+ * matches into `CaptureMatch[]` for the central extractor, then layers
+ * two synthesized streams on top:
+ *
+ *   1. **Per-name import statements** — `import a, b` and
+ *      `from m import x, y` decompose to one match per imported name
+ *      (see `import-decomposer.ts`).
+ *   2. **Receiver type bindings** — methods emit an implicit `self` / `cls`
+ *      binding, and `__init__` assignments from annotated parameters emit
+ *      class-scoped instance-field bindings (see `receiver-binding.ts`).
+ *
+ * Pure given the input source text. No I/O, no globals consulted.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitPythonScopeCaptures = emitPythonScopeCaptures;
+const ast_helpers_js_1 = require("../../utils/ast-helpers.js");
+const import_decomposer_js_1 = require("./import-decomposer.js");
+const query_js_1 = require("./query.js");
+const receiver_binding_js_1 = require("./receiver-binding.js");
+const depends_references_js_1 = require("./depends-references.js");
+const arity_metadata_js_1 = require("./arity-metadata.js");
+const cache_stats_js_1 = require("./cache-stats.js");
+const constants_js_1 = require("../../constants.js");
+const safe_parse_js_1 = require("../../../tree-sitter/safe-parse.js");
+const simple_hooks_js_1 = require("./simple-hooks.js");
+const callable_flow_captures_js_1 = require("../../utils/callable-flow-captures.js");
+const receiver_chain_captures_js_1 = require("../../utils/receiver-chain-captures.js");
+const PYTHON_CALLABLE_CAPTURE_OPTIONS = {
+    functionNodeTypes: new Set(['function_definition', 'lambda']),
+    callNodeTypes: new Set(['call']),
+    parameterListNodeTypes: new Set(['parameters', 'argument_list']),
+    parameterNodeTypes: new Set([
+        'identifier',
+        'default_parameter',
+        'typed_parameter',
+        'typed_default_parameter',
+        'list_splat_pattern',
+        'dictionary_splat_pattern',
+    ]),
+    bindingNodeTypes: new Set(['assignment', 'named_expression']),
+    assignmentNodeTypes: new Set(['assignment', 'named_expression']),
+    identifierNodeTypes: new Set(['identifier']),
+    functionScopedValueBindings: true,
+};
+function emitPythonScopeCaptures(sourceText, _filePath, cachedTree) {
+    // Skip the parse when the caller (the scope-resolution orchestrator's
+    // `treeCache`) already produced a Tree for this source — empty under
+    // worker-pool runs, so cache miss = re-parse. The cachedTree parameter
+    // is typed as `unknown` at the
+    // contract layer (see `LanguageProvider.emitScopeCaptures`); cast
+    // here at the use site.
+    let tree = cachedTree;
+    if (tree === undefined) {
+        try {
+            tree = (0, safe_parse_js_1.parseSourceSafe)((0, query_js_1.getPythonParser)(), sourceText, undefined, {
+                bufferSize: (0, constants_js_1.getTreeSitterBufferSize)(sourceText),
+            });
+        }
+        catch (err) {
+            throw scopeExtractionError('parse', _filePath, err);
+        }
+        (0, cache_stats_js_1.recordCacheMiss)();
+    }
+    else {
+        (0, cache_stats_js_1.recordCacheHit)();
+    }
+    let rawMatches;
+    try {
+        rawMatches = (0, query_js_1.getPythonScopeQuery)().matches(tree.rootNode);
+    }
+    catch (err) {
+        throw scopeExtractionError('scope query', _filePath, err);
+    }
+    const out = [];
+    for (const m of rawMatches) {
+        // Group captures by their tag name. Tree-sitter strips the leading
+        // `@`; we put it back so the central extractor's prefix lookups
+        // (`@scope.`, `@declaration.`, …) work.
+        const grouped = {};
+        // Parallel tag -> captured SyntaxNode map. The tree-sitter query already
+        // hands us each matched node as `c.node`, so anchor nodes can be used
+        // directly (or via a bounded LOCAL walk) instead of re-deriving them with
+        // `findNodeAtRange(tree.rootNode, ...)`, which scanned all of root's named
+        // children on every match -> O(matches x rootChildren). That was the #1848
+        // hotpath in Go (fixed in eaf0a305); the same shape lived here in Python.
+        const nodeMap = {};
+        for (const c of m.captures) {
+            const tag = '@' + c.name;
+            grouped[tag] = (0, ast_helpers_js_1.nodeToCapture)(tag, c.node);
+            nodeMap[tag] = c.node;
+        }
+        if (Object.keys(grouped).length === 0)
+            continue;
+        if (grouped['@import.statement'] !== undefined) {
+            // `@import.statement` is captured directly ON the `import_statement` /
+            // `import_from_statement` node (query: `(import_statement) @import.statement`
+            // and `(import_from_statement) @import.statement`), so the captured node IS
+            // the one the old findNodeAtRange re-derived. `splitImportStatement`
+            // dispatches on those two types; a captured node of any other type would
+            // have made the old range+type lookup return null -> the defensive raw
+            // fallback, which the type guard below reproduces exactly.
+            const stmtNode = nodeMap['@import.statement'];
+            if (stmtNode.type === 'import_from_statement' || stmtNode.type === 'import_statement') {
+                for (const piece of (0, import_decomposer_js_1.splitImportStatement)(stmtNode))
+                    out.push(piece);
+            }
+            else {
+                // Defensive fallback: emit the raw match.
+                // Structural receiver chain for a call whose receiver is itself an
+                // expression, so resolution can type it by folding over structure
+                // instead of re-parsing the receiver's source text. Self-gating: a
+                // non-call match, an absent receiver, or a chain with no nameable base
+                // all leave `grouped` untouched.
+                (0, receiver_chain_captures_js_1.synthesizeReceiverChainCapture)(grouped, nodeMap['@reference.receiver']);
+                out.push(grouped);
+            }
+            continue;
+        }
+        if (grouped['@scope.function'] !== undefined) {
+            // Structural receiver chain for a call whose receiver is itself an
+            // expression, so resolution can type it by folding over structure
+            // instead of re-parsing the receiver's source text. Self-gating: a
+            // non-call match, an absent receiver, or a chain with no nameable base
+            // all leave `grouped` untouched.
+            (0, receiver_chain_captures_js_1.synthesizeReceiverChainCapture)(grouped, nodeMap['@reference.receiver']);
+            out.push(grouped);
+            // `@scope.function` is captured directly on the `function_definition`
+            // node (query: `(function_definition) @scope.function`), so it IS the
+            // node the old findNodeAtRange re-derived at that range.
+            const scopeNode = nodeMap['@scope.function'];
+            const fnNode = scopeNode.type === 'function_definition' ? scopeNode : null;
+            if (fnNode !== null) {
+                const parameterNames = (0, arity_metadata_js_1.computePythonArityMetadata)(fnNode).parameterNames;
+                if (parameterNames.length > 0) {
+                    grouped['@scope.lexical-names'] = (0, ast_helpers_js_1.syntheticCapture)('@scope.lexical-names', fnNode, JSON.stringify(parameterNames));
+                }
+                const synth = (0, receiver_binding_js_1.synthesizeReceiverTypeBinding)(fnNode);
+                if (synth !== null)
+                    out.push(synth);
+                out.push(...(0, receiver_binding_js_1.synthesizeConstructorFieldTypeBindings)(fnNode));
+                for (const depRef of (0, depends_references_js_1.synthesizeDependsReferences)(fnNode))
+                    out.push(depRef);
+            }
+            continue;
+        }
+        if (grouped['@declaration.function'] !== undefined) {
+            // Synthesize arity captures on the declaration match so the
+            // central scope-extractor picks them up alongside @declaration.name.
+            // The anchor range is the function_definition itself — we resolve
+            // the node and pipe it through the arity helper.
+            const anchorCap = grouped['@declaration.function'];
+            // `@declaration.function` is captured directly on the `function_definition`
+            // node (query: `(function_definition name: (identifier) @declaration.name)
+            // @declaration.function`), so use the captured node, not a root re-walk.
+            const anchorNode = nodeMap['@declaration.function'];
+            const fnNode = anchorNode.type === 'function_definition' ? anchorNode : null;
+            if (fnNode !== null) {
+                if ((0, simple_hooks_js_1.pythonFunctionDefinitionLabel)(fnNode, 'Function') === 'Method') {
+                    delete grouped['@declaration.function'];
+                    grouped['@declaration.method'] = { ...anchorCap, name: '@declaration.method' };
+                }
+                const arity = (0, arity_metadata_js_1.computePythonArityMetadata)(fnNode);
+                if (arity.parameterCount !== undefined) {
+                    grouped['@declaration.parameter-count'] = (0, ast_helpers_js_1.syntheticCapture)('@declaration.parameter-count', fnNode, String(arity.parameterCount));
+                }
+                if (arity.requiredParameterCount !== undefined) {
+                    grouped['@declaration.required-parameter-count'] = (0, ast_helpers_js_1.syntheticCapture)('@declaration.required-parameter-count', fnNode, String(arity.requiredParameterCount));
+                }
+                if (arity.parameterTypes !== undefined) {
+                    // Serialize as JSON so the consumer can round-trip without
+                    // inventing a quoting convention for type names that may
+                    // contain commas (`Dict[str, int]`).
+                    grouped['@declaration.parameter-types'] = (0, ast_helpers_js_1.syntheticCapture)('@declaration.parameter-types', fnNode, JSON.stringify(arity.parameterTypes));
+                }
+            }
+            // Structural receiver chain for a call whose receiver is itself an
+            // expression, so resolution can type it by folding over structure
+            // instead of re-parsing the receiver's source text. Self-gating: a
+            // non-call match, an absent receiver, or a chain with no nameable base
+            // all leave `grouped` untouched.
+            (0, receiver_chain_captures_js_1.synthesizeReceiverChainCapture)(grouped, nodeMap['@reference.receiver']);
+            out.push(grouped);
+            continue;
+        }
+        // Structural receiver chain for a call whose receiver is itself an
+        // expression, so resolution can type it by folding over structure
+        // instead of re-parsing the receiver's source text. Self-gating: a
+        // non-call match, an absent receiver, or a chain with no nameable base
+        // all leave `grouped` untouched.
+        (0, receiver_chain_captures_js_1.synthesizeReceiverChainCapture)(grouped, nodeMap['@reference.receiver']);
+        out.push(grouped);
+    }
+    out.push(...synthesizePythonInheritanceReferences(tree.rootNode));
+    out.push(...(0, callable_flow_captures_js_1.synthesizeCallableFlowCaptures)(tree.rootNode, PYTHON_CALLABLE_CAPTURE_OPTIONS));
+    return out;
+}
+/**
+ * Synthesize `@reference.inherits` captures from Python class superclass
+ * lists so the registry-primary scope-resolution path emits EXTENDS edges
+ * (mirrors C#'s `synthesizeCsharpInheritanceReferences` / C++'s
+ * `emitCppInheritanceCaptures` / TypeScript's `synthesizeTsInheritanceReferences`).
+ * Without this, Python inheritance edges came only from the legacy
+ * heritage-capture leg (removed in #942), which is dropped for registry-primary
+ * languages in the worker pipeline (issue #1951).
+ *
+ * Scope matches the legacy Python heritage leg (config-driven since #1940):
+ * every direct base in the `superclasses` `argument_list`, resolved to its bare
+ * simple name. Three base shapes that the previous synth DROPPED — and so
+ * silently omitted in production while the legacy heritage leg captured them
+ * — are now handled (#1951):
+ *
+ *   - `class C(pkg.Base)`     → `attribute`  (trailing `.attribute` id → `Base`)
+ *   - `class C(pkg.sub.Base)` → nested `attribute` (recurse → `Base`)
+ *   - `class C(Generic[T])`   → `subscript`  (`.value` id → `Generic`)
+ *
+ * The bare-name text MUST agree with `normalizeSupertypeName` (the legacy leg's
+ * reduction in heritage-extractors/supertype-alternation.ts) so both legs emit
+ * the same edge under the CI scope-parity gate: `pkg.Base` → `Base`,
+ * `Generic[T]` → `Generic`, `pkg.Container[str]` → `Container`. Verified by a
+ * real tree-sitter-python parse. The simple `identifier` base keeps its exact
+ * prior capture (the base node itself).
+ *
+ * Tuple/multi bases (`class C(A, pkg.B, Gen[T])`) already iterate here — each
+ * `argument_list` named child is one base. Python has no interfaces, so every
+ * base resolves to a Class and the central `preEmitInheritanceEdges` pass emits
+ * EXTENDS; the EXTENDS-vs-IMPLEMENTS split is decided downstream from the
+ * resolved target's symbol kind, so all bases are emitted with the same
+ * `inherits` kind here.
+ */
+function synthesizePythonInheritanceReferences(root) {
+    const out = [];
+    (0, ast_helpers_js_1.walkNamedTree)(root, (node) => {
+        if (node.type !== 'class_definition')
+            return;
+        const superclasses = node.childForFieldName('superclasses');
+        if (superclasses === null || superclasses.type !== 'argument_list')
+            return;
+        for (let i = 0; i < superclasses.namedChildCount; i++) {
+            const base = superclasses.namedChild(i);
+            if (base === null)
+                continue;
+            const nameNode = pythonBaseLookupNameNode(base);
+            if (nameNode === null)
+                continue;
+            out.push({
+                '@reference.inherits': (0, ast_helpers_js_1.nodeToCapture)('@reference.inherits', base),
+                '@reference.name': (0, ast_helpers_js_1.nodeToCapture)('@reference.name', nameNode),
+            });
+        }
+    });
+    return out;
+}
+/**
+ * Reduce a Python superclass base node to the bare simple-identifier node whose
+ * `.text` is the lookup name `findClassBindingInScope` resolves. Mirrors the
+ * TypeScript `terminalTsTypeNameNode` / C++ `extractBaseLookupName` reference
+ * patterns, and its returned node's `.text` is contractually equal to
+ * `normalizeSupertypeName(base)` for every shape (real-parse verified):
+ *
+ *   - `identifier`  (`Base`)            → the node itself
+ *   - `attribute`   (`pkg.Base`,
+ *                    `pkg.sub.Base`)    → trailing `attribute:` identifier → `Base`
+ *   - `subscript`   (`Generic[T]`,
+ *                    `pkg.Container[T]`)→ `value:` (recurse, strips `[...]` and
+ *                                          any qualifier) → `Generic` / `Container`
+ *
+ * Returns null for any other shape (no leaf identifier reachable), so it never
+ * emits a spurious edge.
+ */
+function pythonBaseLookupNameNode(base) {
+    switch (base.type) {
+        case 'identifier':
+            return base;
+        case 'attribute': {
+            // `pkg.Base` / `pkg.sub.Base`: the `attribute:` field is the trailing
+            // simple-identifier segment (`Base`); recurse so chained dotted paths
+            // still resolve to the final identifier.
+            const attr = base.childForFieldName('attribute');
+            return attr === null ? null : pythonBaseLookupNameNode(attr);
+        }
+        case 'subscript': {
+            // `Generic[T]` / `pkg.Container[str]`: the `value:` field is the
+            // subscripted base (identifier or attribute); recurse to strip the
+            // `[...]` slice and any qualifier, reaching the bare base name.
+            const value = base.childForFieldName('value');
+            return value === null ? null : pythonBaseLookupNameNode(value);
+        }
+        default:
+            return null;
+    }
+}
+function scopeExtractionError(stage, filePath, err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return new Error(`[python] tree-sitter ${stage} failed for ${filePath}: ${reason}; skipping scope extraction for this file`);
+}

package/dist/core/code/engine/core/ingestion/languages/python/depends-references.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * Synthesize `@reference.call.free` captures for FastAPI `Depends(callable)`
+ * parameter defaults.
+ *
+ * `Depends(get_db)` passes `get_db` as a callable that the DI framework
+ * calls on every request. The route handler is functionally a caller of
+ * the dependency — impact analysis needs that edge.
+ *
+ * Tree-sitter can't express "the first argument of a call named Depends
+ * inside a parameter default" in a single static query, so we synthesize
+ * reference captures in code, mirroring the receiver-binding pattern.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.synthesizeDependsReferences = synthesizeDependsReferences;
+const ast_helpers_js_1 = require("../../utils/ast-helpers.js");
+/**
+ * Inspect a `function_definition` node's parameters for `Depends(callable)`
+ * defaults. Returns one `@reference.call.free` CaptureMatch per dependency.
+ */
+function synthesizeDependsReferences(fnNode) {
+    const params = fnNode.childForFieldName('parameters');
+    if (params === null)
+        return [];
+    const results = [];
+    for (let i = 0; i < params.namedChildCount; i++) {
+        const param = params.namedChild(i);
+        if (param === null)
+            continue;
+        if (param.type !== 'typed_default_parameter' && param.type !== 'default_parameter') {
+            continue;
+        }
+        const defaultValue = param.childForFieldName('value');
+        if (defaultValue === null)
+            continue;
+        const callNode = defaultValue.type === 'call' ? defaultValue : null;
+        if (callNode === null)
+            continue;
+        const fnIdent = callNode.childForFieldName('function');
+        if (fnIdent === null || fnIdent.type !== 'identifier' || fnIdent.text !== 'Depends')
+            continue;
+        const args = callNode.childForFieldName('arguments');
+        if (args === null || args.namedChildCount === 0)
+            continue;
+        const firstArg = args.namedChild(0);
+        if (firstArg === null)
+            continue;
+        if (firstArg.type === 'identifier') {
+            results.push({
+                '@reference.call.free': (0, ast_helpers_js_1.nodeToCapture)('@reference.call.free', firstArg),
+                '@reference.name': (0, ast_helpers_js_1.nodeToCapture)('@reference.name', firstArg),
+            });
+            continue;
+        }
+        if (firstArg.type === 'attribute') {
+            const attrName = firstArg.childForFieldName('attribute');
+            const obj = firstArg.childForFieldName('object');
+            if (attrName !== null && obj !== null) {
+                results.push({
+                    '@reference.call.member': (0, ast_helpers_js_1.nodeToCapture)('@reference.call.member', attrName),
+                    '@reference.name': (0, ast_helpers_js_1.nodeToCapture)('@reference.name', attrName),
+                    '@reference.receiver': (0, ast_helpers_js_1.nodeToCapture)('@reference.receiver', obj),
+                });
+            }
+        }
+    }
+    return results;
+}

package/dist/core/code/engine/core/ingestion/languages/python/import-decomposer.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Decompose a Python `import_statement` / `import_from_statement` into
+ * one `CaptureMatch` per imported name.
+ *
+ * Why split here? The `LanguageProvider.interpretImport` contract is
+ * one `ParsedImport` per call. Tree-sitter delivers `import a, b as c`
+ * and `from m import x, y, z` as a single match each, so without
+ * decomposition we'd lose names. The synthesized markers
+ * (`@import.kind` / `@import.name` / `@import.alias` / `@import.source`)
+ * carry everything `interpretPythonImport` needs to recover the original
+ * `ParsedImport` shape — see `interpret.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitImportStatement = splitImportStatement;
+const ast_helpers_js_1 = require("../../utils/ast-helpers.js");
+function splitImportStatement(stmtNode) {
+    if (stmtNode.type === 'import_statement')
+        return splitImportStmt(stmtNode);
+    if (stmtNode.type === 'import_from_statement')
+        return splitImportFromStmt(stmtNode);
+    return [];
+}
+function splitImportStmt(stmtNode) {
+    // `import a, b as c, d.e`
+    const out = [];
+    for (let i = 0; i < stmtNode.namedChildCount; i++) {
+        const child = stmtNode.namedChild(i);
+        if (child === null)
+            continue;
+        if (child.type === 'dotted_name') {
+            out.push(buildImportMatch(stmtNode, {
+                kind: 'plain',
+                source: child.text,
+                name: child.text.split('.')[0],
+                atNode: child,
+            }));
+        }
+        else if (child.type === 'aliased_import') {
+            const dotted = (0, ast_helpers_js_1.findChild)(child, 'dotted_name');
+            const alias = (0, ast_helpers_js_1.findChild)(child, 'identifier');
+            if (dotted !== null && alias !== null) {
+                out.push(buildImportMatch(stmtNode, {
+                    kind: 'aliased',
+                    source: dotted.text,
+                    name: dotted.text,
+                    alias: alias.text,
+                    atNode: child,
+                }));
+            }
+        }
+    }
+    return out;
+}
+function splitImportFromStmt(stmtNode) {
+    // `from m import a, b as c` / `from m import *` / `from . import x`
+    const out = [];
+    const moduleField = stmtNode.childForFieldName('module_name');
+    const moduleText = moduleField?.text ?? '';
+    // Wildcard? tree-sitter-python represents `*` as a `wildcard_import`
+    // child and emits no name children.
+    const wildcardChild = (0, ast_helpers_js_1.findChild)(stmtNode, 'wildcard_import');
+    if (wildcardChild !== null) {
+        out.push(buildImportMatch(stmtNode, {
+            kind: 'wildcard',
+            source: moduleText,
+            name: '*',
+            atNode: wildcardChild,
+        }));
+        return out;
+    }
+    // Names = every dotted_name / aliased_import that isn't the module.
+    for (let i = 0; i < stmtNode.namedChildCount; i++) {
+        const child = stmtNode.namedChild(i);
+        if (child === null)
+            continue;
+        if (moduleField !== null && child.startIndex === moduleField.startIndex)
+            continue;
+        if (child.type === 'dotted_name') {
+            out.push(buildImportMatch(stmtNode, {
+                kind: 'from',
+                source: moduleText,
+                name: child.text,
+                atNode: child,
+            }));
+        }
+        else if (child.type === 'aliased_import') {
+            const dotted = (0, ast_helpers_js_1.findChild)(child, 'dotted_name');
+            const alias = (0, ast_helpers_js_1.findChild)(child, 'identifier');
+            if (dotted !== null && alias !== null) {
+                out.push(buildImportMatch(stmtNode, {
+                    kind: 'from-alias',
+                    source: moduleText,
+                    name: dotted.text,
+                    alias: alias.text,
+                    atNode: child,
+                }));
+            }
+        }
+    }
+    return out;
+}
+function buildImportMatch(stmtNode, spec) {
+    const stmtCap = (0, ast_helpers_js_1.nodeToCapture)('@import.statement', stmtNode);
+    const m = {
+        '@import.statement': stmtCap,
+        '@import.kind': (0, ast_helpers_js_1.syntheticCapture)('@import.kind', spec.atNode, spec.kind),
+        '@import.source': (0, ast_helpers_js_1.syntheticCapture)('@import.source', spec.atNode, spec.source),
+        '@import.name': (0, ast_helpers_js_1.syntheticCapture)('@import.name', spec.atNode, spec.name),
+    };
+    if (spec.alias !== undefined) {
+        m['@import.alias'] = (0, ast_helpers_js_1.syntheticCapture)('@import.alias', spec.atNode, spec.alias);
+    }
+    return m;
+}