gitnexus 1.6.8-rc.20 → 1.6.8-rc.21

package/dist/cli/ai-context.js

@@ -136,6 +136,7 @@ This project is indexed by GitNexus as **${projectName}**${noStats ? '' : ` (${s
 - **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
 - When exploring unfamiliar code, use \`query({query: "concept"})\` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
 - When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use \`context({name: "symbolName"})\`.
+- For security review, \`explain({target: "fileOrSymbol"})\` lists taint findings (source→sink flows; needs \`analyze --pdg\`).
 
 ## Never Do
 

package/dist/cli/skill-gen.js

@@ -485,6 +485,7 @@ const renderSkillMarkdown = (community, projectName, members, files, entryPoints
     lines.push(`1. \`context({name: "${firstEntry}"})\` \u2014 see callers and callees`);
     lines.push(`2. \`query({query: "${community.label.toLowerCase()}"})\` \u2014 find related execution flows`);
     lines.push('3. Read key files listed above for implementation details');
+    lines.push('4. `explain({target: "<file or symbol>"})` — persisted taint findings (source→sink data flows), when indexed with `--pdg`');
     lines.push('');
     return lines.join('\n');
 };

package/dist/core/ingestion/cfg/emit.d.ts

@@ -19,7 +19,7 @@
  * kind cannot be its own edge type and is queried via `reason`.
  */
 import type { KnowledgeGraph } from '../../graph/types.js';
-import type { FunctionCfg } from './types.js';
+import type { BindingEntry, FunctionCfg } from './types.js';
 /**
  * Default per-function CFG edge cap. A pathological generated function could
  * otherwise emit an unbounded edge set; the cap bounds graph growth and is
@@ -56,6 +56,13 @@ export interface CfgEmitResult {
     /** Number of functions that hit the cap. */
     cappedFunctions: number;
 }
+/**
+ * The single BasicBlock id template (module doc). Exported for the M3 taint
+ * emit path (taint/emit.ts), whose TAINTED/SANITIZES edges must address the
+ * SAME persisted block nodes — a re-derived copy of this template would
+ * silently dangle the moment either drifted.
+ */
+export declare const basicBlockId: (filePath: string, functionStartLine: number, functionStartColumn: number, blockIndex: number) => string;
 /**
  * Whether an untrusted `cfgSideChannel` element is safe to feed to
  * {@link emitFileCfgs}. Deliberately NOT full FunctionCfg validation — it
@@ -106,6 +113,14 @@ export interface ReachingDefEmitResult {
     /** Total statement-level facts the solver produced (pre-dedup telemetry). */
     facts: number;
 }
+/**
+ * Stable identity for a binding inside edge ids (#2082 M2 KTD3/KTD9):
+ * `name:declLine:declCol` for declared bindings, `name@module` for synthetic
+ * ones. Distinct same-name bindings never share a key; identifier characters
+ * cannot contain the id separators. Exported for the M3 taint emit path —
+ * TAINTED/SANITIZES ids key bindings with the same discipline.
+ */
+export declare const bindingKey: (b: BindingEntry) => string;
 /**
  * Compute reaching definitions per function and persist the bounded
  * REACHING_DEF projection (#2082 M2 U4).

package/dist/core/ingestion/cfg/emit.js

@@ -28,7 +28,13 @@ export const DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION = 4000;
 export const REACHING_DEF_FACTS_PER_EDGE_CAP = 4;
 /** Derived emit-path fact limit at the default edge cap (bench/doc anchor). */
 export const DEFAULT_PDG_MAX_REACHING_DEF_FACTS_PER_FUNCTION = REACHING_DEF_FACTS_PER_EDGE_CAP * DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION;
-const basicBlockId = (filePath, functionStartLine, functionStartColumn, blockIndex) => `BasicBlock:${filePath}:${functionStartLine}:${functionStartColumn}:${blockIndex}`;
+/**
+ * The single BasicBlock id template (module doc). Exported for the M3 taint
+ * emit path (taint/emit.ts), whose TAINTED/SANITIZES edges must address the
+ * SAME persisted block nodes — a re-derived copy of this template would
+ * silently dangle the moment either drifted.
+ */
+export const basicBlockId = (filePath, functionStartLine, functionStartColumn, blockIndex) => `BasicBlock:${filePath}:${functionStartLine}:${functionStartColumn}:${blockIndex}`;
 /**
  * Whether an untrusted `cfgSideChannel` element is safe to feed to
  * {@link emitFileCfgs}. Deliberately NOT full FunctionCfg validation — it
@@ -185,9 +191,10 @@ export function emitFileCfgs(graph, cfgs, maxEdgesPerFunction = DEFAULT_MAX_CFG_
  * Stable identity for a binding inside edge ids (#2082 M2 KTD3/KTD9):
  * `name:declLine:declCol` for declared bindings, `name@module` for synthetic
  * ones. Distinct same-name bindings never share a key; identifier characters
- * cannot contain the id separators.
+ * cannot contain the id separators. Exported for the M3 taint emit path —
+ * TAINTED/SANITIZES ids key bindings with the same discipline.
  */
-const bindingKey = (b) => b.synthetic ? `${b.name}@module` : `${b.name}:${b.declLine}:${b.declColumn}`;
+export const bindingKey = (b) => b.synthetic ? `${b.name}@module` : `${b.name}:${b.declLine}:${b.declColumn}`;
 /**
  * Compute reaching definitions per function and persist the bounded
  * REACHING_DEF projection (#2082 M2 U4).

package/dist/core/ingestion/cfg/reaching-defs.d.ts

@@ -41,6 +41,13 @@ export interface ProgramPoint {
     readonly stmtIndex: number;
     readonly line: number;
 }
+/**
+ * Canonical `block:stmt` string key for a program point. Colon-separated to
+ * match the codebase's `blockIndex:stmtIndex` id conventions. Shared by the
+ * taint propagation engine (dedup/state keys) and the taint emit path
+ * (persisted edge-id material) so the two never drift.
+ */
+export declare function pointKey(p: ProgramPoint): string;
 /** One def→use fact: the definition at `def` reaches the use at `use`. */
 export interface DefUseFact {
     /** Index into {@link FunctionDefUse.bindings}. */

package/dist/core/ingestion/cfg/reaching-defs.js

@@ -1,3 +1,12 @@
+/**
+ * Canonical `block:stmt` string key for a program point. Colon-separated to
+ * match the codebase's `blockIndex:stmtIndex` id conventions. Shared by the
+ * taint propagation engine (dedup/state keys) and the taint emit path
+ * (persisted edge-id material) so the two never drift.
+ */
+export function pointKey(p) {
+    return `${p.blockIndex}:${p.stmtIndex}`;
+}
 /**
  * def-site key: packs (blockIndex, stmtIndex) into one number. The stride is
  * a per-BLOCK statement bound, and `maxFunctionLines` caps LINES, not

package/dist/core/ingestion/cfg/types.d.ts

@@ -40,6 +40,90 @@ export interface BindingEntry {
      */
     readonly synthetic?: boolean;
 }
+/**
+ * One occurrence of a binding inside a call/new site's argument position
+ * (#2083 M3 U1). A bare `number` is a DIRECT occurrence (binding index into
+ * {@link FunctionCfg.bindings}); a `[bindingIdx, viaSiteIdx]` tuple marks an
+ * occurrence that reaches this argument THROUGH the nested site at
+ * `viaSiteIdx` (an index into the SAME statement's {@link StatementFacts.sites}
+ * array). The tag is load-bearing for sanitizer interposition (plan KTD4a):
+ * a flat per-arg binding set cannot distinguish `exec(escape(x))` (kill) from
+ * `exec(x)` (finding) — the single most common safe pattern would
+ * false-positive without it.
+ */
+export type SiteArgOccurrence = number | readonly [number, number];
+/**
+ * One call site, constructor call, or value-position member read harvested
+ * from a statement (#2083 M3 U1, plan KTD2). Worker-side substrate for the M3
+ * taint pass: the M2 facts carry no expression structure, and the main thread
+ * cannot re-parse (the #1983 OOM shape). Spec-AGNOSTIC — records structure
+ * only, never source/sink/sanitizer-ness (matching is a main-thread concern).
+ *
+ * Integer indices: binding fields (`receiver`/`object`/`resultDefs`/arg
+ * occurrences) index {@link FunctionCfg.bindings}; site references (`parent`,
+ * via-tags) index the OWNING statement's `sites` array. JSON-plain; NO field
+ * here may be named `nodeId` (durable parsedfile-store reviver hazard — see
+ * {@link BindingEntry}).
+ */
+export interface SiteRecord {
+    readonly kind: 'call' | 'new' | 'member-read';
+    /**
+     * Dotted callee path for call/new sites whose callee chain is rooted at an
+     * identifier/`this`/`super` (`child_process.exec`, `req.body.toString`).
+     * Optional chaining is normalized (`a?.b()` ⇒ `a.b`); string-literal
+     * subscripts fold into the path (`cp["exec"]` ⇒ `cp.exec`). Absent when the
+     * chain is not statically resolvable (dynamic key, call-rooted chain).
+     */
+    readonly callee?: string;
+    /**
+     * Binding index of the callee chain's ROOT identifier when the callee is a
+     * member chain (`userInput.trim()` ⇒ `userInput`). Method calls launder
+     * taint without it (plan KTD5 receiver-position TITO). Absent for bare
+     * calls (`exec(x)`) and non-identifier roots.
+     */
+    readonly receiver?: number;
+    /**
+     * Per-argument-position occurrence entries (trailing empty positions are
+     * trimmed; absent when no argument carries a binding occurrence). For
+     * `template: true` sites every substitution occurrence aggregates at
+     * position 0 (tagged templates have no positional argument list).
+     */
+    readonly args?: ReadonlyArray<readonly SiteArgOccurrence[]>;
+    /**
+     * Bindings defined by a declarator/assignment whose ENTIRE value (after
+     * unwrapping parens/`await`/`as`/`!`) is this call — `const b = escape(t)`
+     * ⇒ `[b]`. Per-declarator: `const a = t, b = escape(t)` attaches `[b]`
+     * only. Kill placement (KTD4b) keys on this: a sanitizer kills exactly the
+     * defs that receive its result directly.
+     */
+    readonly resultDefs?: readonly number[];
+    /**
+     * `[siteIdx, argIdx]` of the innermost enclosing call/new site argument
+     * position this site occurs in (`exec(escape(x))` ⇒ escape's parent is
+     * `[execSiteIdx, 0]`). Absent for top-level sites.
+     */
+    readonly parent?: readonly [number, number];
+    /**
+     * Index of the FIRST spread argument (`exec(...args)` ⇒ 0). Presence means
+     * position matching must degrade soundly (any sink position ≥ this index —
+     * plan KTD2/U2). A number (not boolean) because the matcher needs the index.
+     */
+    readonly spread?: number;
+    /** Tagged-template call (`sql\`…${id}\``) — argument positions are not positional. */
+    readonly template?: boolean;
+    /**
+     * String-literal first argument when the callee is bare `require` —
+     * CommonJS aliases resolve like ESM imports on the main thread (KTD7).
+     */
+    readonly requireArg?: string;
+    /** Member read: binding index of the object root (`req.body` ⇒ `req`). */
+    readonly object?: number;
+    /**
+     * Member read: property name (`req.body` ⇒ `'body'`; `req["body"]`
+     * included; dynamic `req[key]` is never recorded — documented KTD10 FN).
+     */
+    readonly property?: string;
+}
 /**
  * Def/use facts for one harvested statement (or construct header), in
  * execution order within its block (#2082 M2 U1). `defs`/`uses` are indices
@@ -55,12 +139,19 @@ export interface BindingEntry {
  * treating them as must-defs would falsely kill the prior def on the
  * not-taken path (a taint false negative on core JS idioms). Optional —
  * absent means none.
+ *
+ * `sites` (#2083 M3 U1): call/member-read structure for the taint pass —
+ * see {@link SiteRecord}. Optional and omit-when-empty; absent on pre-M3
+ * channels and on statements with no calls or member reads. Sites inside
+ * nested functions are NOT recorded (consistent with def/use invisibility —
+ * the enclosing `arr.forEach(...)` call IS, with receiver `arr`).
  */
 export interface StatementFacts {
     readonly line: number;
     readonly defs: readonly number[];
     readonly uses: readonly number[];
     readonly mayDefs?: readonly number[];
+    readonly sites?: readonly SiteRecord[];
 }
 /** A basic block: a maximal straight-line run of statements between leaders. */
 export interface BasicBlockData {

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

@@ -64,6 +64,16 @@ export declare class TsHarvester {
      * here falsely kills the prior def on the not-taken path).
      */
     private conditionalDepth;
+    /**
+     * Call/new node id → bindings whose declarator/assignment VALUE is exactly
+     * that call (#2083 M3 U1). Registered by the declarator/assignment handlers
+     * BEFORE the value walk, consumed by {@link visitCall} when it reaches the
+     * node — the indirection keeps result-def attribution per-declarator
+     * (`const a = t, b = escape(t)` attaches `[b]` to the escape site only) and
+     * top-level-only (`const c = cond ? escape(b) : b` attaches nothing — the
+     * bypass occurrence must keep `c` taintable, plan KTD4a).
+     */
+    private readonly resultDefTargets;
     constructor(fnNode: SyntaxNode);
     /** The completed binding table — pass to `CfgBuilder.finish`. */
     table(): readonly BindingEntry[];
@@ -103,4 +113,32 @@ export declare class TsHarvester {
     private walkValue;
     /** Assignment-target walk: identifiers bind; member/subscript targets are uses. */
     private walkDefPattern;
+    /** Strip value-transparent wrappers (`(x)`, `x!`, `x as T`, `await x`). */
+    private unwrapValueWrappers;
+    /**
+     * When `value`'s root (after unwrapping) is a call/new node, remember that
+     * its site should carry `resultDefs: defs` — consumed by {@link visitCall}
+     * once the value walk reaches the node.
+     */
+    private registerResultDefs;
+    /**
+     * Explicit call/new handler: records a call site (callee path, receiver,
+     * per-arg occurrence entries, spread/template markers, require literal,
+     * result defs) while reproducing EXACTLY the uses the old default descent
+     * recorded — callee chain root + dynamic subscript indices + arguments.
+     */
+    private visitCall;
+    /**
+     * Member/subscript chain walk shared by value position, write position, and
+     * callee position. Use-recording is identical to the old default descent
+     * (chain-root identifier once, dynamic subscript index expressions, full
+     * walk of non-identifier roots) — NO double-recording. Member-read sites:
+     * at most ONE per chain — the INNERMOST access — and only when the chain
+     * root is an identifier and the access's key is static (`.prop` or a
+     * string-literal subscript); `skipFinalRead` suppresses it when that access
+     * is the final one (callee / write target). Optional chaining (`?.`) never
+     * appears in the output (field-based traversal normalizes it); dynamic
+     * computed keys record nothing (documented KTD10 FN).
+     */
+    private walkChain;
 }