gitnexus 1.6.8-rc.9 → 1.6.8

package/dist/core/ingestion/cfg/visitors/python-harvest.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Python def/use harvester — the Python analogue of
+ * {@link import('./typescript-harvest.js').TsHarvester} and the C-family
+ * harvesters ({@link import('./go-harvest.js').GoHarvester} et al.). Python is
+ * the most structurally divergent CFG target (indentation blocks, no braces,
+ * comprehensions, `with`, `try/except/else/finally`, `match/case`), so this
+ * harvester exercises the shared reaching-defs / CDG substrate against a grammar
+ * with none of the brace-family assumptions.
+ *
+ * Runs in the parse worker next to the Python CFG visitor, extracting
+ * per-statement variable definition/use facts that ride the side channel for the
+ * reaching-defs / CDG solvers. Output is the per-function binding table
+ * ({@link BindingEntry}[]) plus {@link StatementFacts} the visitor attaches to
+ * blocks as it walks. Each `call` ALSO records a taint {@link SiteRecord} (callee
+ * path, receiver, per-arg occurrence entries, result defs, spread marker, and an
+ * `at` anchor) via the shared {@link CallSiteFactAccumulator} — the same site
+ * substrate the C-family / Go / TS harvesters emit. Python has NO `new`
+ * expression (constructors are plain `call`s), so every site is `kind: 'call'`.
+ * The `at` anchor is the `call` node's start position, byte-aligned with the
+ * `@reference.call.*` CALLS-edge anchor (which also captures the whole `call`
+ * node), so the downstream resolved-callee-id join lands by exact position.
+ *
+ * Every node type and field literal below was grammar-validated against
+ * tree-sitter-python (0.23.x) via the introspection probe before use (mandatory
+ * pre-step). Python shapes pre-empted (verified by a real parse):
+ *  - functions: `function_definition` (fields `name`/`parameters`/`body`; async
+ *    is the SAME node with an `async` token child) and `lambda` (fields
+ *    `parameters`=`lambda_parameters`, `body`).
+ *  - parameters: bare `identifier`, `default_parameter` (fields `name`/`value`),
+ *    `typed_parameter` (no `name` field — the binder is a named child:
+ *    `identifier` / `list_splat_pattern` / `dictionary_splat_pattern`),
+ *    `typed_default_parameter` (fields `name`/`type`/`value`),
+ *    `list_splat_pattern` (`*args`), `dictionary_splat_pattern` (`**kwargs`).
+ *  - assignment targets: `assignment` (fields `left`/`right`/optional `type`;
+ *    LHS may be `identifier`, `pattern_list`, `tuple_pattern`, `list_pattern`,
+ *    `attribute`, or `subscript`), `augmented_assignment` (fields
+ *    `left`/`operator`/`right` — read+write), `named_expression` walrus (fields
+ *    `name`/`value`).
+ *  - unpacking patterns: `pattern_list` / `tuple_pattern` / `list_pattern`
+ *    nest `identifier` and `list_splat_pattern` (`*rest`) targets.
+ *  - binders: `for_statement` (fields `left`/`right`), `for_in_clause`
+ *    (comprehension binder, fields `left`/`right`), `with_item` (field `value`
+ *    = `as_pattern` whose `alias`=`as_pattern_target`, or a bare expression),
+ *    `except_clause` / `except_group_clause` (`as_pattern` → `as_pattern_target`),
+ *    `global_statement` / `nonlocal_statement` (identifier children).
+ *  - reads: `attribute` (fields `object`/`attribute`), `subscript` (fields
+ *    `value`/`subscript`), `call` (fields `function`/`arguments`),
+ *    `boolean_operator` (fields `left`/`operator`/`right`),
+ *    `conditional_expression` (ternary: consequent / condition / alternative in
+ *    source order), `parenthesized_expression`.
+ *
+ * TWO-PHASE, ORDER-INDEPENDENT (load-bearing — mirrors the TS / Go harvesters):
+ * the CFG walk is NOT source-order, so resolving names against a scope stack
+ * populated *during* the walk would mis-resolve. Phase 1 pre-scans the whole
+ * function subtree once, declaring every in-function name (Python's def-on-first-
+ * assignment scoping has a SINGLE function scope — there is no block scope, so
+ * the whole function body shares one table). Phase 2 resolves defs/uses against
+ * that finished table from any walk order.
+ *
+ * Python scope model (deliberately simplified, documented): Python binds names
+ * at FUNCTION scope on first assignment anywhere in the body (no block scope).
+ * We therefore declare all assignment / for / with / except / walrus /
+ * comprehension targets and parameters into the single function table.
+ * `global x` / `nonlocal x` names are recorded as SYNTHETIC module-level
+ * bindings (`name@module`) so their writes/reads share one binding with the
+ * outer scope rather than minting a confusing function-local. Comprehension
+ * targets technically have their OWN scope in Py3 (a leaked `i` after `[i for
+ * i in xs]` does NOT exist), but we declare them in the function table anyway —
+ * a documented over-approximation that keeps the comprehension target a real
+ * def (the plan's explicit ask) without modeling nested comprehension scopes.
+ *
+ * v1 def-semantics scope:
+ *   - `assignment` plain `=` — each identifier target in the (possibly nested)
+ *     LHS pattern is a def; a `*rest` splat target is a def; an `attribute` /
+ *     `subscript` target is NOT a scalar def (its root identifier is a use).
+ *   - `augmented_assignment` (`x += 1`) — def AND use the lvalue.
+ *   - `named_expression` walrus (`(n := f())`) — `n` is a def.
+ *   - `for_statement` / `for_in_clause` `left` — loop/comprehension targets are
+ *     defs; `right` is a use.
+ *   - `with_item` `as` alias (`with cm as fh`) — `fh` is a def.
+ *   - `except ... as e` — `e` is a `catch`-kind def (matters to the taint pass).
+ *   - parameters (incl. defaults, `*args`, `**kwargs`, typed) — `param`-kind defs.
+ * EXCLUDED, deliberately (TypeScript-CFA precedent): attribute / subscript
+ * writes (`obj.f = …`, `arr[i] = …`) are NOT scalar defs — their root
+ * identifiers are uses only. Nested function (`function_definition` / `lambda`)
+ * bodies are opaque in BOTH directions (reads of and writes to captured outer
+ * variables are invisible — callback flows are later-pass territory).
+ *
+ * MAY-DEFS: a def inside a conditionally-evaluated subexpression is a may-def
+ * (gen WITHOUT kill), so the not-taken path's prior def is not falsely killed.
+ * Python's conditional-def shapes: a walrus in the right operand of `or` / `and`
+ * short-circuit (`a or (x := b)`), a walrus in either non-test arm of a ternary
+ * (`(a := p) if c else (b := q)`), and a `case`-clause guard / pattern test.
+ *
+ * NOTE: nothing serialized here may carry a field named `nodeId` — the durable
+ * parsedfile-store reviver dedups objects keyed on that field name.
+ */
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+import type { BindingEntry, StatementFacts } from '../types.js';
+export declare class PythonHarvester {
+    private readonly fnNode;
+    private readonly bindings;
+    /** Single function-scope name → binding index (Python has no block scope). */
+    private readonly table;
+    private readonly synthetic;
+    /** Names declared `global`/`nonlocal` — resolve to the synthetic module binding. */
+    private readonly globalNames;
+    private readonly fnId;
+    /** >0 while walking a conditionally-evaluated subexpression — defs become may-defs. */
+    private conditionalDepth;
+    /**
+     * `call` node id → binding indices its single-target result is assigned to
+     * (`x = f()` ⇒ `[x]`). Populated just before the value walk reaches the call
+     * (see {@link registerResultDefs}) and consumed by {@link visitCall}. Mirrors
+     * the Go harvester's `resultDefTargets`.
+     */
+    private readonly resultDefTargets;
+    constructor(fnNode: SyntaxNode);
+    /** The completed binding table — pass to `CfgBuilder.finish`. */
+    bindingTable(): readonly BindingEntry[];
+    /** The function/lambda body node (a `block` for `def`, an expression for `lambda`). */
+    private bodyOf;
+    private declare;
+    /** Declare every parameter binder (incl. defaults, typed, `*args`, `**kwargs`). */
+    private declareParams;
+    /** Declare the binder identifier(s) of one parameter node. */
+    private declareParam;
+    /** Declare a binder that may be an identifier or a `*`/`**` splat pattern. */
+    private declareParamBinder;
+    /**
+     * Pre-scan the function body once, declaring every in-function name. Recurses
+     * into compound statements but NOT into nested `function_definition` / `lambda`
+     * bodies (opaque). `global`/`nonlocal` are processed FIRST in a sibling sweep
+     * so a later assignment to a global name does not mint a function-local.
+     */
+    private prescan;
+    /** Declare identifier/splat leaves of an assignment / loop target pattern. */
+    private declareTargets;
+    /** `with EXPR as TARGET` — declare the alias target(s). */
+    private declareWithItem;
+    /** `except E as e` — declare `e`. */
+    private declareExceptAlias;
+    /** The `as_pattern_target` child of an `as_pattern` (when no `alias` field). */
+    private asPatternTarget;
+    /** Declare an `as_pattern_target` (or its identifier child) as a binding. */
+    private declareAsTarget;
+    /** Def/use facts for one statement (or construct-header expression) node. */
+    facts(node: SyntaxNode): StatementFacts;
+    /** Facts for an expression whose WHOLE evaluation is conditional (case tests). */
+    factsConditional(node: SyntaxNode): StatementFacts;
+    /**
+     * Facts for a `for TARGET in ITER` / `for_in_clause` head: the loop target(s)
+     * are defs, the iterated expression is a use.
+     */
+    loopHeadFacts(headNode: SyntaxNode): StatementFacts;
+    /** Facts for a `with_item`: the `as` alias is a def, the value an use. */
+    withItemFacts(item: SyntaxNode): StatementFacts;
+    /** Facts for an `except E as e:` header: `e` is a def, `E` a use. */
+    exceptHeadFacts(clause: SyntaxNode): StatementFacts;
+    /** ENTRY-block facts for the parameters (defs only — incl. default-value uses). */
+    paramFacts(): StatementFacts | undefined;
+    /** Def the binder(s) of one parameter node and use any default-value expr. */
+    private defParam;
+    private defParamBinder;
+    private resolve;
+    private def;
+    private use;
+    /** Run `fn` with defs demoted to may-defs (conditionally-evaluated context). */
+    private conditional;
+    /**
+     * Def each identifier/splat leaf of an assignment / loop target pattern; route
+     * attribute / subscript targets to the value walk (root identifier is a use).
+     */
+    private defTargets;
+    /** Def an `as_pattern_target` (or its identifier child). */
+    private defAsTarget;
+    /** Value-position walk: collect uses; route def positions to the target handler. */
+    private walkValue;
+    /**
+     * A comprehension (`[body for t in src if g]`): each `for_in_clause` target is
+     * a def, its source a use; the `body` and any `if_clause` are uses. Kept INLINE
+     * (no separate CFG blocks) per the plan — the target binding is harvested so it
+     * is a real def. The `for_in_clause` source is walked in the ENCLOSING context
+     * (it reads outer names), the body/filter after the targets are bound.
+     */
+    private walkComprehension;
+    /**
+     * When `value`'s root (after stripping parens) is a `call`, remember that
+     * call site should carry `resultDefs` — the binding indices of `targets`
+     * (def-position identifiers). Consumed by {@link visitCall} once the value
+     * walk reaches the node. Single-target only (the caller restricts to a plain
+     * identifier LHS); the blank identifier (`_`) binds nothing and is skipped.
+     */
+    private registerResultDefs;
+    /** Strip `parenthesized_expression` wrappers around a value (`(f())`). */
+    private unwrapValue;
+    /**
+     * Explicit `call` handler. Records a call site (callee path, receiver, per-arg
+     * occurrence entries, result defs, spread marker) while reproducing EXACTLY
+     * the uses the old default descent recorded (callee chain root + arguments).
+     * Python has no `new` — every site is `kind: 'call'`.
+     */
+    private visitCall;
+    /**
+     * `attribute` chain walk shared by value position and callee position. Records
+     * the chain-root identifier as a use (identical to the old default descent)
+     * plus at most ONE member-read site — the INNERMOST access — when the root is
+     * an identifier; `skipFinalRead` suppresses it when that access is the callee
+     * (carried by the dotted path instead). Mirrors the Go harvester's `walkChain`.
+     */
+    private walkChain;
+}