circle-ir 3.8.3 → 3.9.7

package/dist/analysis/passes/unused-variable-pass.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pass #82: unused-variable (CWE-561, category: reliability)
+ *
+ * Detects local variables that are declared but whose value is never read.
+ * This includes variables whose value is overwritten before any read
+ * (the initial assignment is "dead" from a data-flow perspective).
+ *
+ * Detection strategy:
+ *   1. For each `kind='local'` DFG def:
+ *      - Skip intentional throwaway names (`_`, `err`, `e`, loop variables…).
+ *      - Skip variables in `catch` blocks (common pattern to capture but ignore
+ *        exceptions: `catch (err) { ... }`).
+ *      - Call `graph.usesOfDef(def.id)` — returns uses with `def_id === defId`.
+ *      - If the result is empty, no code ever reads the value stored by this
+ *        definition → flag as unused.
+ *
+ * Notes:
+ *   - Test files are excluded to reduce noise (test helpers often define
+ *     variables for side-effect checks).
+ *   - Parameters (`kind='param'`) are excluded — unused parameters are common
+ *     in callbacks and overriding methods and produce too many false positives.
+ *   - Fields (`kind='field'`) are excluded — class fields are often read via
+ *     `this.x` in ways the DFG may not track precisely.
+ */
+import type { AnalysisPass, PassContext } from '../../graph/analysis-pass.js';
+export interface UnusedVariableResult {
+    unusedVars: Array<{
+        line: number;
+        variable: string;
+    }>;
+}
+export declare class UnusedVariablePass implements AnalysisPass<UnusedVariableResult> {
+    readonly name = "unused-variable";
+    readonly category: "reliability";
+    run(ctx: PassContext): UnusedVariableResult;
+}

package/dist/analysis/passes/unused-variable-pass.js

@@ -0,0 +1,150 @@
+/**
+ * Pass #82: unused-variable (CWE-561, category: reliability)
+ *
+ * Detects local variables that are declared but whose value is never read.
+ * This includes variables whose value is overwritten before any read
+ * (the initial assignment is "dead" from a data-flow perspective).
+ *
+ * Detection strategy:
+ *   1. For each `kind='local'` DFG def:
+ *      - Skip intentional throwaway names (`_`, `err`, `e`, loop variables…).
+ *      - Skip variables in `catch` blocks (common pattern to capture but ignore
+ *        exceptions: `catch (err) { ... }`).
+ *      - Call `graph.usesOfDef(def.id)` — returns uses with `def_id === defId`.
+ *      - If the result is empty, no code ever reads the value stored by this
+ *        definition → flag as unused.
+ *
+ * Notes:
+ *   - Test files are excluded to reduce noise (test helpers often define
+ *     variables for side-effect checks).
+ *   - Parameters (`kind='param'`) are excluded — unused parameters are common
+ *     in callbacks and overriding methods and produce too many false positives.
+ *   - Fields (`kind='field'`) are excluded — class fields are often read via
+ *     `this.x` in ways the DFG may not track precisely.
+ */
+/** Variable names that are intentionally declared-but-not-read. */
+const SKIP_NAMES = new Set([
+    '_', 'unused',
+    'e', 'err', 'error', 'ex', 'exception',
+    'i', 'j', 'k', 'n', 'idx', 'index',
+    // TypeScript/JavaScript built-in type keywords that the DFG extractor may
+    // accidentally surface as phantom variable defs from type annotations.
+    'boolean', 'string', 'number', 'object', 'symbol', 'undefined',
+    'null', 'never', 'void', 'any', 'unknown', 'bigint',
+]);
+export class UnusedVariablePass {
+    name = 'unused-variable';
+    category = 'reliability';
+    run(ctx) {
+        const { graph, code } = ctx;
+        const file = graph.ir.meta.file;
+        // Skip test files — test scaffolding often has unused vars intentionally
+        if (/[./](?:test|spec)[./]/.test(file) || /\.(?:test|spec)\.[jt]s$/.test(file)) {
+            return { unusedVars: [] };
+        }
+        const codeLines = code.split('\n');
+        const unusedVars = [];
+        const reported = new Set(); // deduplicate by variable+line
+        for (const def of graph.ir.dfg.defs) {
+            if (def.kind !== 'local')
+                continue;
+            const variable = def.variable;
+            // Skip intentional throwaway / loop variable names
+            if (variable.startsWith('_'))
+                continue;
+            if (SKIP_NAMES.has(variable))
+                continue;
+            // Skip catch-block variables (e.g. `catch (err)`)
+            const lineText = codeLines[def.line - 1] ?? '';
+            if (/\bcatch\s*\(/.test(lineText))
+                continue;
+            // Skip exported symbols — they are consumed by other modules and
+            // single-file DFG analysis cannot see cross-file uses.
+            if (/\bexport\b/.test(lineText))
+                continue;
+            // No uses of this specific definition → unused (per DFG)
+            const uses = graph.usesOfDef(def.id);
+            if (uses.length > 0)
+                continue;
+            // Text-search fallback: covers cross-scope uses that the DFG misses (e.g.
+            // module-level constants referenced inside a class method body, or
+            // conditional reassignments where the DFG links the final read only to
+            // the last def so earlier defs appear unused).
+            const otherDefs = graph.ir.dfg.defs.filter(d => d.variable === variable && d.id !== def.id);
+            const otherDefLines = new Set(otherDefs.map(d => d.line));
+            const escapedName = variable.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const namePattern = new RegExp(`\\b${escapedName}\\b`);
+            if (otherDefLines.size === 0) {
+                // Single def — simple text search: any occurrence on another line suppresses.
+                const usedElsewhere = codeLines.some((line, idx) => idx !== def.line - 1 && namePattern.test(line));
+                if (usedElsewhere)
+                    continue;
+            }
+            else {
+                // Multiple defs exist.
+                //
+                // Case A — current def IS a true declaration (let/const/var, Java type, Rust let):
+                //   Only suppress if a non-def use is found that precedes ALL intermediate defs.
+                //   This preserves "overwrite-before-read" detection: if a later def appears
+                //   between this def and the text-found use, the value was overwritten and the
+                //   use belongs to the later def.
+                //
+                // Case B — current def is a bare reassignment (part of a conditional pattern):
+                //   Suppress if the variable appears anywhere on a non-def line.  This handles
+                //   sibling-if-block assignments (`if (x) { fw = 'a'; } if (y) { fw = 'b'; }
+                //   return fw;`) where the DFG links the return only to the last branch def.
+                const lineText = codeLines[def.line - 1] ?? '';
+                const isTrueDeclaration = /\b(?:let|const|var)\s+[\w{[]/.test(lineText)
+                    || /\b(?:int|long|float|double|boolean|byte|char|short|var|final)\b/.test(lineText)
+                    || /\b[A-Z]\w*(?:<[^>]*>)?\s+\w/.test(lineText)
+                    || /\blet\s+(?:mut\s+)?\w/.test(lineText);
+                if (isTrueDeclaration) {
+                    // Case A: suppress only if use appears before any intermediate def.
+                    const usedBeforeNextDef = codeLines.some((line, idx) => {
+                        const lineNum = idx + 1;
+                        if (lineNum === def.line || otherDefLines.has(lineNum))
+                            return false;
+                        if (!namePattern.test(line))
+                            return false;
+                        // If any other def for this variable sits between our def and this use,
+                        // the value was overwritten → this use belongs to the later def → don't suppress.
+                        return !otherDefs.some(d => d.line > def.line && d.line < lineNum);
+                    });
+                    if (usedBeforeNextDef)
+                        continue;
+                }
+                else {
+                    // Case B: bare reassignment — suppress if used on any non-def line.
+                    const usedOnNonDefLine = codeLines.some((line, idx) => {
+                        const lineNum = idx + 1;
+                        return lineNum !== def.line && !otherDefLines.has(lineNum) && namePattern.test(line);
+                    });
+                    if (usedOnNonDefLine)
+                        continue;
+                }
+            }
+            const key = `${variable}-${def.line}`;
+            if (reported.has(key))
+                continue;
+            reported.add(key);
+            unusedVars.push({ line: def.line, variable });
+            ctx.addFinding({
+                id: `unused-variable-${file}-${def.line}`,
+                pass: this.name,
+                category: this.category,
+                rule_id: this.name,
+                cwe: 'CWE-561',
+                severity: 'low',
+                level: 'note',
+                message: `'${variable}' is assigned but its value is never read`,
+                file,
+                line: def.line,
+                snippet: lineText.trim(),
+                fix: `Remove the assignment or use the value of '${variable}'`,
+                evidence: { variable },
+            });
+        }
+        return { unusedVars };
+    }
+}
+//# sourceMappingURL=unused-variable-pass.js.map

package/dist/analysis/passes/unused-variable-pass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unused-variable-pass.js","sourceRoot":"","sources":["../../../src/analysis/passes/unused-variable-pass.ts"],"names":[],"mappings":"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"}

package/dist/analysis/passes/variable-shadowing-pass.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pass #79: variable-shadowing (CWE-1109, category: reliability)
+ *
+ * Detects when an inner scope declares a variable with the same name as an
+ * outer-scope declaration or function parameter, hiding the outer binding and
+ * making code harder to reason about.
+ *
+ * Detection strategy:
+ *   1. Build a ScopeGraph to identify which defs are true declarations vs
+ *      bare reassignments.
+ *   2. For each method, group DFG defs by variable name.
+ *   3. Flag two kinds of shadowing within the same method:
+ *      - Param shadow  : a `kind='param'` def + a later `kind='local'` def
+ *        that is a real declaration (has a decl keyword, or Python which has
+ *        no keywords but every local assignment implicitly shadows a param).
+ *      - Outer-local shadow : two or more `kind='local'` defs that both have
+ *        a declaration keyword (e.g. `let x = 1` then `let x = 2` in a
+ *        nested block).
+ *
+ * Note on Python: Python variables have function scope (not block scope), so
+ * two assignments to the same name within a function do NOT shadow each other.
+ * However, a local assignment that shares a name with a parameter DOES shadow
+ * the parameter (from the assignment point onward). The pass flags that case
+ * for Python regardless of `hasDeclKeyword` (since Python has no decl keywords).
+ */
+import type { AnalysisPass, PassContext } from '../../graph/analysis-pass.js';
+export interface VariableShadowingResult {
+    shadows: Array<{
+        /** Line of the shadowing (inner) declaration. */
+        line: number;
+        variable: string;
+        /** Line of the shadowed (outer) declaration or parameter. */
+        shadowedAt: number;
+        kind: 'param' | 'outer-local';
+    }>;
+}
+export declare class VariableShadowingPass implements AnalysisPass<VariableShadowingResult> {
+    readonly name = "variable-shadowing";
+    readonly category: "reliability";
+    run(ctx: PassContext): VariableShadowingResult;
+}

package/dist/analysis/passes/variable-shadowing-pass.js

@@ -0,0 +1,211 @@
+/**
+ * Pass #79: variable-shadowing (CWE-1109, category: reliability)
+ *
+ * Detects when an inner scope declares a variable with the same name as an
+ * outer-scope declaration or function parameter, hiding the outer binding and
+ * making code harder to reason about.
+ *
+ * Detection strategy:
+ *   1. Build a ScopeGraph to identify which defs are true declarations vs
+ *      bare reassignments.
+ *   2. For each method, group DFG defs by variable name.
+ *   3. Flag two kinds of shadowing within the same method:
+ *      - Param shadow  : a `kind='param'` def + a later `kind='local'` def
+ *        that is a real declaration (has a decl keyword, or Python which has
+ *        no keywords but every local assignment implicitly shadows a param).
+ *      - Outer-local shadow : two or more `kind='local'` defs that both have
+ *        a declaration keyword (e.g. `let x = 1` then `let x = 2` in a
+ *        nested block).
+ *
+ * Note on Python: Python variables have function scope (not block scope), so
+ * two assignments to the same name within a function do NOT shadow each other.
+ * However, a local assignment that shares a name with a parameter DOES shadow
+ * the parameter (from the assignment point onward). The pass flags that case
+ * for Python regardless of `hasDeclKeyword` (since Python has no decl keywords).
+ */
+import { ScopeGraph } from '../../graph/scope-graph.js';
+/**
+ * Variable names that should never be flagged as shadowing — either because
+ * they are JS/TS keywords that the DFG extractor may phantom-extract, or
+ * because they are built-in TypeScript primitive type names that appear in
+ * type annotations and get incorrectly treated as variable defs.
+ */
+const SKIP_NAMES = new Set([
+    // JS/TS declaration keywords (phantom defs from DFG parsing keywords as vars)
+    'let', 'const', 'var',
+    // TypeScript primitive type names (phantom defs from type annotations)
+    'boolean', 'string', 'number', 'object', 'symbol', 'undefined',
+    'null', 'never', 'void', 'any', 'unknown', 'bigint',
+]);
+/**
+ * Returns true when `innerLine` is inside a block that is nested within the
+ * block containing `outerLine`. Returns false when the outer block was closed
+ * before `innerLine` (i.e. they are in sibling scopes, not nested scopes).
+ *
+ * Strategy: scan lines from `outerLine` to `innerLine - 1` (1-based) counting
+ * brace pairs. A relative balance below zero means the outer block was closed —
+ * the two declarations are siblings, not a real shadowing relationship.
+ *
+ * Note: ignores braces inside string literals or comments, which may produce
+ * occasional false negatives (missed shadows) but never false positives.
+ */
+function isInNestedScope(codeLines, outerLine, innerLine) {
+    let balance = 0;
+    let hasOpened = false; // true once we've seen the outer block's opening {
+    for (let ln = outerLine; ln < innerLine; ln++) {
+        const text = codeLines[ln - 1] ?? ''; // ln is 1-based
+        for (const ch of text) {
+            if (ch === '{') {
+                balance++;
+                hasOpened = true;
+            }
+            else if (ch === '}') {
+                balance--;
+                if (balance < 0)
+                    return false; // outer block closed before opening — sibling
+                // If the outer block opened and has now fully closed, the inner def is
+                // outside it (sibling scope, not nested).
+                if (hasOpened && balance === 0)
+                    return false;
+            }
+        }
+    }
+    return true;
+}
+export class VariableShadowingPass {
+    name = 'variable-shadowing';
+    category = 'reliability';
+    run(ctx) {
+        const { graph, code, language } = ctx;
+        const file = graph.ir.meta.file;
+        const codeLines = code.split('\n');
+        const scope = new ScopeGraph(graph, code, language);
+        const shadows = [];
+        const reported = new Set(); // deduplicate by variable+line
+        for (const type of graph.ir.types) {
+            for (const method of type.methods) {
+                const entries = scope.defsInMethod(method.start_line, method.end_line);
+                // Group entries by variable name
+                const byVar = new Map();
+                for (const entry of entries) {
+                    const existing = byVar.get(entry.def.variable);
+                    if (existing) {
+                        existing.push(entry);
+                    }
+                    else {
+                        byVar.set(entry.def.variable, [entry]);
+                    }
+                }
+                for (const [variable, varEntries] of byVar) {
+                    if (varEntries.length < 2)
+                        continue;
+                    // Skip keywords, TS primitive types, and common throwaway names
+                    if (SKIP_NAMES.has(variable))
+                        continue;
+                    // Skip PascalCase identifiers — these are almost always type annotation
+                    // phantoms (class names, interface names, generic type params) that the
+                    // DFG extractor incorrectly surfaces as variable defs.
+                    if (variable.length > 0 && variable[0] >= 'A' && variable[0] <= 'Z')
+                        continue;
+                    const params = varEntries.filter(e => e.def.kind === 'param');
+                    const locals = varEntries.filter(e => e.def.kind === 'local');
+                    // -------------------------------------------------------
+                    // Case 1: Param shadowed by a local declaration
+                    // -------------------------------------------------------
+                    if (params.length > 0 && locals.length > 0) {
+                        const paramEntry = params[0];
+                        for (const local of locals) {
+                            // For Python: every assignment to a param name shadows it.
+                            // For other languages: only flag if the line is a real declaration.
+                            if (language !== 'python' && !local.hasDeclKeyword)
+                                continue;
+                            if (local.def.line <= paramEntry.def.line)
+                                continue;
+                            const key = `${variable}-${local.def.line}`;
+                            if (reported.has(key))
+                                continue;
+                            reported.add(key);
+                            shadows.push({
+                                line: local.def.line,
+                                variable,
+                                shadowedAt: paramEntry.def.line,
+                                kind: 'param',
+                            });
+                            ctx.addFinding({
+                                id: `variable-shadowing-${file}-${local.def.line}`,
+                                pass: this.name,
+                                category: this.category,
+                                rule_id: this.name,
+                                cwe: 'CWE-1109',
+                                severity: 'medium',
+                                level: 'warning',
+                                message: `'${variable}' shadows the parameter declared at line ${paramEntry.def.line}`,
+                                file,
+                                line: local.def.line,
+                                fix: `Rename the inner variable to avoid hiding the parameter '${variable}'`,
+                                evidence: {
+                                    variable,
+                                    outer_kind: 'param',
+                                    outer_line: paramEntry.def.line,
+                                },
+                            });
+                        }
+                        continue; // skip outer-local check when params are involved
+                    }
+                    // -------------------------------------------------------
+                    // Case 2: Outer local shadowed by an inner local declaration
+                    // -------------------------------------------------------
+                    if (locals.length >= 2) {
+                        // Python has no decl keywords → skip outer-local shadow for Python
+                        if (language === 'python')
+                            continue;
+                        // Only consider entries that are true declarations
+                        const declLocals = locals
+                            .filter(e => e.hasDeclKeyword)
+                            .sort((a, b) => a.def.line - b.def.line);
+                        if (declLocals.length < 2)
+                            continue;
+                        const outerEntry = declLocals[0];
+                        for (let i = 1; i < declLocals.length; i++) {
+                            const inner = declLocals[i];
+                            // Skip if the outer block was already closed before the inner
+                            // declaration — those are sibling scopes, not nested scopes.
+                            if (!isInNestedScope(codeLines, outerEntry.def.line, inner.def.line))
+                                continue;
+                            const key = `${variable}-${inner.def.line}`;
+                            if (reported.has(key))
+                                continue;
+                            reported.add(key);
+                            shadows.push({
+                                line: inner.def.line,
+                                variable,
+                                shadowedAt: outerEntry.def.line,
+                                kind: 'outer-local',
+                            });
+                            ctx.addFinding({
+                                id: `variable-shadowing-${file}-${inner.def.line}`,
+                                pass: this.name,
+                                category: this.category,
+                                rule_id: this.name,
+                                cwe: 'CWE-1109',
+                                severity: 'medium',
+                                level: 'warning',
+                                message: `'${variable}' shadows the outer declaration at line ${outerEntry.def.line}`,
+                                file,
+                                line: inner.def.line,
+                                fix: `Rename the inner variable to avoid hiding the outer '${variable}'`,
+                                evidence: {
+                                    variable,
+                                    outer_kind: 'local',
+                                    outer_line: outerEntry.def.line,
+                                },
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        return { shadows };
+    }
+}
+//# sourceMappingURL=variable-shadowing-pass.js.map

package/dist/analysis/passes/variable-shadowing-pass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variable-shadowing-pass.js","sourceRoot":"","sources":["../../../src/analysis/passes/variable-shadowing-pass.ts"],"names":[],"mappings":"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"}

package/dist/analysis/path-finder.d.ts

@@ -5,6 +5,7 @@
  * through variable assignments, method calls, and returns.
  */
 import type { DFG, CallInfo, TaintSource, TaintSink, TaintSanitizer, SourceType, SinkType } from '../types/index.js';
+import { CodeGraph } from '../graph/index.js';
 /**
  * A single hop in the taint path
  */
@@ -68,24 +69,13 @@ export interface PathFinderConfig {
  * PathFinder - Enumerate taint paths through the DFG
  */
 export declare class PathFinder {
-    private dfg;
-    private calls;
+    private graph;
     private sources;
     private sinks;
     private sanitizers;
     private config;
-    private defById;
-    private defsByLine;
-    private defsByVar;
-    private usesByLine;
-    private usesByDefId;
-    private callsByLine;
     private sanitizerLines;
-    constructor(dfg: DFG, calls: CallInfo[], sources: TaintSource[], sinks: TaintSink[], sanitizers: TaintSanitizer[], config?: PathFinderConfig);
-    /**
-     * Build all lookup maps for efficient querying
-     */
-    private buildLookupMaps;
+    constructor(graphOrDfg: CodeGraph | DFG, callsOrSources: CallInfo[] | TaintSource[], sourcesOrSinks: TaintSource[] | TaintSink[], sinksOrSanitizers: TaintSink[] | TaintSanitizer[], sanitizersOrConfig?: TaintSanitizer[] | PathFinderConfig, config?: PathFinderConfig);
     /**
      * Find all taint paths from sources to sinks
      */