@oddessentials/odd-ai-reviewers 1.7.4 → 1.9.0

package/dist/agents/control_flow/safe-source-patterns.js

@@ -0,0 +1,137 @@
+/**
+ * Safe-Source Pattern Definitions
+ *
+ * Declarative registry of patterns for recognizing provably non-tainted data sources.
+ * Safe sources are excluded from taint tracking to prevent false positives.
+ *
+ * Per contract: safe-source-patterns.md v1.0
+ * Per FR-001 through FR-004: Each pattern matches a specific, provable AST shape.
+ */
+// =============================================================================
+// Registry Constants
+// =============================================================================
+export const SAFE_SOURCE_REGISTRY_VERSION = '1.0';
+export const EXPECTED_PATTERN_COUNT = 9;
+/**
+ * All vulnerability types for patterns that prevent taint universally.
+ */
+export const ALL_VULN_TYPES = [
+    'injection',
+    'null_deref',
+    'auth_bypass',
+    'xss',
+    'path_traversal',
+    'prototype_pollution',
+    'ssrf',
+];
+// =============================================================================
+// Pattern Registry
+// =============================================================================
+export const SAFE_SOURCE_PATTERNS = [
+    // Pattern 1: Constant Literal Declarations (FR-001)
+    {
+        id: 'constant-literal-string',
+        name: 'Constant String Literal',
+        description: 'Module-scope const with string literal initializer',
+        preventsTaintFor: ALL_VULN_TYPES,
+        match: {
+            type: 'constant_declaration',
+            requireModuleScope: true,
+            requireLiteralInitializer: true,
+        },
+        confidence: 'high',
+    },
+    {
+        id: 'constant-literal-number',
+        name: 'Constant Number Literal',
+        description: 'Module-scope const with numeric literal initializer',
+        preventsTaintFor: ALL_VULN_TYPES,
+        match: {
+            type: 'constant_declaration',
+            requireModuleScope: true,
+            requireLiteralInitializer: true,
+        },
+        confidence: 'high',
+    },
+    {
+        id: 'constant-literal-array',
+        name: 'Constant Literal Array',
+        description: 'Module-scope const with array of literal values',
+        preventsTaintFor: ALL_VULN_TYPES,
+        match: {
+            type: 'constant_declaration',
+            requireModuleScope: true,
+            requireLiteralInitializer: true,
+        },
+        confidence: 'high',
+    },
+    // Pattern 2: Built-in Directory References (FR-002)
+    {
+        id: 'builtin-dirname',
+        name: 'Built-in __dirname',
+        description: 'Node.js __dirname built-in reference',
+        preventsTaintFor: ['path_traversal'],
+        match: {
+            type: 'builtin_reference',
+            identifiers: ['__dirname'],
+        },
+        confidence: 'high',
+    },
+    {
+        id: 'builtin-filename',
+        name: 'Built-in __filename',
+        description: 'Node.js __filename built-in reference',
+        preventsTaintFor: ['path_traversal'],
+        match: {
+            type: 'builtin_reference',
+            identifiers: ['__filename'],
+        },
+        confidence: 'high',
+    },
+    {
+        id: 'builtin-import-meta-dirname',
+        name: 'import.meta.dirname',
+        description: 'ESM import.meta.dirname reference',
+        preventsTaintFor: ['path_traversal'],
+        match: {
+            type: 'builtin_reference',
+            identifiers: ['import.meta.dirname'],
+        },
+        confidence: 'high',
+    },
+    {
+        id: 'builtin-import-meta-url',
+        name: 'import.meta.url',
+        description: 'ESM import.meta.url reference',
+        preventsTaintFor: ['path_traversal'],
+        match: {
+            type: 'builtin_reference',
+            identifiers: ['import.meta.url'],
+        },
+        confidence: 'high',
+    },
+    // Pattern 3: Safe Directory Listing Returns (FR-003)
+    {
+        id: 'safe-readdir',
+        name: 'Safe Directory Listing',
+        description: 'fs.readdirSync/readdir with provably safe argument',
+        preventsTaintFor: ['path_traversal'],
+        match: {
+            type: 'safe_function_return',
+            callTargets: ['readdirSync', 'readdir'],
+        },
+        confidence: 'medium',
+    },
+    // Pattern 4: Constant Array Element Access (FR-004)
+    {
+        id: 'constant-element-access',
+        name: 'Constant Array Element Access',
+        description: 'Element access on a module-scope const literal array',
+        preventsTaintFor: ['injection', 'xss'],
+        match: {
+            type: 'constant_element_access',
+        },
+        confidence: 'high',
+    },
+];
+//# sourceMappingURL=safe-source-patterns.js.map

package/dist/agents/control_flow/safe-source-patterns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-source-patterns.js","sourceRoot":"","sources":["../../../src/agents/control_flow/safe-source-patterns.ts"],"names":[],"mappings":"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"}

package/dist/agents/control_flow/scope-stack.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Scope Stack — Lexical scope tracking for declaration-identity resolution.
+ *
+ * Provides a scope stack that maps variable names to their declaring AST nodes,
+ * enabling scope-aware variable resolution without a full TypeChecker.
+ *
+ * Used by safe-source-detector and vulnerability-detector to replace name-based
+ * tracking with declaration-identity tracking.
+ */
+import ts from 'typescript';
+/**
+ * Produce a deterministic identity string for an AST node.
+ * Format: `file:line:col` (1-based line, 0-based column).
+ *
+ * IMPORTANT: Never embed ts.Node references in serializable data structures.
+ * Use this helper to produce a stable key for maps, sets, and stored state.
+ */
+export declare function nodeIdentityKey(node: ts.Node, sourceFile: ts.SourceFile): string;
+/**
+ * A variable name extracted from a destructuring assignment target
+ * (BinaryExpression LHS). This is the Expression-based counterpart to the
+ * simple `{ name, node }` returned by `extractBindingNames()` for
+ * BindingPattern nodes in VariableDeclarations.
+ */
+export interface DestructuringBinding {
+    /** Local binding name (after rename resolution) */
+    name: string;
+    /** AST node representing the binding */
+    node: ts.Node;
+    /** Position in array destructuring (for per-element taint) */
+    index?: number;
+    /**
+     * For nested bindings inside an array element container (e.g. `[{ a }]`),
+     * the position of the parent container in the enclosing array.
+     * Used by the vulnerability detector to look up the correct RHS element
+     * when `index` is not set on nested bindings.
+     */
+    parentIndex?: number;
+    /** Original property key (for renamed destructuring, e.g. `{ orig: renamed }`) */
+    propertyKey?: string;
+    /**
+     * For nested bindings inside an object property (e.g. `{ a: { b } }`),
+     * the chain of property keys from the root to this binding's immediate container.
+     * Used by the vulnerability detector to traverse into nested RHS objects.
+     * Example: `{ a: { b: { c } } }` → binding `c` has outerKeys: ['a', 'b']
+     */
+    outerKeys?: string[];
+    /** Whether this is a rest element (`...rest`) */
+    isRest: boolean;
+    /** Nesting depth (0 = top-level, max 10) */
+    depth: number;
+}
+/**
+ * Extract binding names from a destructuring assignment target.
+ *
+ * Handles `ArrayLiteralExpression` and `ObjectLiteralExpression` patterns
+ * used on the LHS of a `BinaryExpression` (assignment targets).
+ *
+ * This is the Expression-based counterpart to `extractBindingNames()` which
+ * handles `BindingPattern` nodes in `VariableDeclarations`.
+ *
+ * For simple identifiers: `x = 1` → [{ name: 'x', ... }]
+ * For array destructuring: `[a, b] = arr` → [{ name: 'a', index: 0 }, { name: 'b', index: 1 }]
+ * For object destructuring: `({ a, b: c } = obj)` → [{ name: 'a' }, { name: 'c', propertyKey: 'b' }]
+ * For rest elements: `[a, ...rest] = arr` → [{ name: 'a', index: 0 }, { name: 'rest', isRest: true }]
+ * For nested: `[{ a }] = arr` → [{ name: 'a', depth: 1 }]
+ *
+ * @param target - The LHS of a destructuring assignment
+ * @param maxDepth - Maximum recursion depth (default 10)
+ * @returns Array of extracted bindings with metadata
+ */
+export declare function extractBindingsFromAssignmentTarget(target: ts.Expression, maxDepth?: number): DestructuringBinding[];
+/**
+ * Returns true if `node` introduces a new lexical scope.
+ */
+export declare function isScopeNode(node: ts.Node): boolean;
+/**
+ * Returns true if `node` introduces a function-level scope (not block-level).
+ * Used to determine the correct scope for `var` declarations, which are hoisted
+ * to the enclosing function (or source file) rather than the enclosing block.
+ */
+export declare function isFunctionScopeNode(node: ts.Node): boolean;
+/**
+ * Extract all binding identifiers from a BindingName (handles destructuring).
+ *
+ * For simple identifiers: `const x = 1` -> ['x']
+ * For object destructuring: `const { a, b: c } = obj` -> ['a', 'c']
+ * For array destructuring: `const [a, , b] = arr` -> ['a', 'b']
+ * For nested: `const { a: [b, c] } = obj` -> ['b', 'c']
+ */
+export declare function extractBindingNames(name: ts.BindingName): {
+    name: string;
+    node: ts.Node;
+}[];
+/**
+ * A lexical scope stack for resolving identifier names to declaration nodes.
+ *
+ * Usage:
+ * 1. Walk the AST. On entering a scope-creating node, call `enterScope(node)`.
+ * 2. For each variable/const/let declaration, call `addDeclaration(name, declNode)`.
+ * 3. To resolve an identifier, call `resolveDeclaration(name)` — returns the
+ *    innermost declaration node for that name, or undefined if not found.
+ * 4. On leaving a scope-creating node, call `leaveScope()`.
+ */
+export declare class ScopeStack {
+    private stack;
+    /** Current nesting depth (0 when no scope is entered). */
+    get depth(): number;
+    /** Enter a new lexical scope. */
+    enterScope(node: ts.Node): void;
+    /** Leave the innermost scope. */
+    leaveScope(): void;
+    /** Register a declaration in the current (innermost) scope. */
+    addDeclaration(name: string, node: ts.Node): void;
+    /**
+     * Register a `var` declaration in the nearest function-level scope.
+     * `var` is hoisted to the enclosing function (or source file), not
+     * the enclosing block.
+     */
+    addVarDeclaration(name: string, node: ts.Node): void;
+    /**
+     * Resolve a name to its declaring node by walking the stack from innermost
+     * scope outward. Returns the declaring node, or undefined if the name is
+     * not declared in any enclosing scope.
+     */
+    resolveDeclaration(name: string): ts.Node | undefined;
+    /** Check whether a given declaration node is visible in the current scope chain. */
+    isInScope(declarationNode: ts.Node): boolean;
+}
+/**
+ * Register a variable declaration in the scope stack, handling:
+ * - Simple identifiers (`const x`)
+ * - Destructuring patterns (`const { a, b } = obj`, `const [a, b] = arr`)
+ * - `var` hoisting (registers in the nearest function scope, not block scope)
+ * - Catch clause variable binding
+ */
+export declare function registerDeclaration(node: ts.VariableDeclaration, scope: ScopeStack, sourceFile?: ts.SourceFile, declarationsByKey?: Map<string, ts.Node>): void;
+/**
+ * Register all declaration types for a given node in the scope stack.
+ * This is the canonical helper used by all scope-walking code.
+ */
+export declare function registerNodeDeclarations(node: ts.Node, scope: ScopeStack, sourceFile?: ts.SourceFile, declarationsByKey?: Map<string, ts.Node>): void;
+/**
+ * Build a ScopeStack that is populated with all declarations in `sourceFile`.
+ * This performs a full AST walk and registers every variable/const/let/var
+ * declaration, function parameter, catch variable, and function declaration name.
+ *
+ * Returns a Map from each AST node to the ScopeStack state at that point,
+ * keyed by node identity string. This is used for point-in-time resolution.
+ *
+ * For simpler use cases, use `walkWithScope()` instead.
+ */
+export declare function buildDeclarationMap(sourceFile: ts.SourceFile): Map<string, ts.Node>;
+/**
+ * Walk an AST with scope tracking, invoking a callback for each node.
+ * The callback receives the current ScopeStack, which can be used to
+ * resolve identifiers at any point during the walk.
+ *
+ * Declarations are registered automatically for:
+ * - Variable declarations (`const x`, `let y`, `var z` with hoisting)
+ * - Destructuring patterns (`const { a } = obj`, `const [a] = arr`)
+ * - Function declaration names
+ * - Function/method/arrow parameters (including destructured)
+ * - Catch clause variables
+ */
+export declare function walkWithScope(sourceFile: ts.SourceFile, callback: (node: ts.Node, scope: ScopeStack, sourceFile: ts.SourceFile) => void): void;
+//# sourceMappingURL=scope-stack.d.ts.map

package/dist/agents/control_flow/scope-stack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-stack.d.ts","sourceRoot":"","sources":["../../../src/agents/control_flow/scope-stack.ts"],"names":[],"mappings":"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"}