circle-ir 3.8.4 → 3.9.8

package/dist/analysis/passes/stale-doc-ref-pass.js

@@ -0,0 +1,96 @@
+/**
+ * Pass #33: stale-doc-ref
+ *
+ * Flags doc comment references ({@link ClassName} and @see ClassName) that
+ * point to symbols not found in the file's type declarations or imports.
+ * Stale doc refs cause confusion and erode documentation trustworthiness.
+ *
+ * Category: maintainability | Severity: low | Level: note | CWE: none
+ */
+// Matches /** ... */ blocks (non-greedy, multiline)
+const DOC_BLOCK_RE = /\/\*\*([\s\S]*?)\*\//g;
+// Matches {@link Foo.Bar#method} or {@link Foo}
+const LINK_RE = /\{@link\s+([\w.#]+)/g;
+// Matches @see Foo.Bar or @see Foo
+const SEE_RE = /@see\s+([\w.#]+)/g;
+/**
+ * Normalize a symbol reference: strip method fragment (#method) and
+ * take the last dot-separated segment (so "java.util.List" → "List").
+ */
+function normalizeRef(raw) {
+    const withoutMethod = raw.split('#')[0];
+    const parts = withoutMethod.split('.');
+    return parts[parts.length - 1] ?? raw;
+}
+/**
+ * Return the 1-based line number of the start of a match within `code`.
+ */
+function lineOfIndex(code, index) {
+    let line = 1;
+    for (let i = 0; i < index && i < code.length; i++) {
+        if (code[i] === '\n')
+            line++;
+    }
+    return line;
+}
+export class StaleDocRefPass {
+    name = 'stale-doc-ref';
+    category = 'maintainability';
+    run(ctx) {
+        const staleRefs = [];
+        // Build known-symbol set from types + imports
+        const knownSymbols = new Set();
+        for (const t of ctx.graph.ir.types) {
+            knownSymbols.add(t.name);
+        }
+        for (const imp of ctx.graph.ir.imports) {
+            if (imp.imported_name && imp.imported_name !== '*' && imp.imported_name !== 'default') {
+                knownSymbols.add(imp.imported_name);
+            }
+            if (imp.alias) {
+                knownSymbols.add(imp.alias);
+            }
+        }
+        const code = ctx.code;
+        DOC_BLOCK_RE.lastIndex = 0;
+        let blockMatch;
+        while ((blockMatch = DOC_BLOCK_RE.exec(code)) !== null) {
+            const blockStart = blockMatch.index;
+            const blockText = blockMatch[0];
+            // Extract all refs from the block
+            const refs = [];
+            LINK_RE.lastIndex = 0;
+            let m;
+            while ((m = LINK_RE.exec(blockText)) !== null) {
+                refs.push({ raw: m[1], offsetInBlock: m.index });
+            }
+            SEE_RE.lastIndex = 0;
+            while ((m = SEE_RE.exec(blockText)) !== null) {
+                refs.push({ raw: m[1], offsetInBlock: m.index });
+            }
+            for (const { raw, offsetInBlock } of refs) {
+                const normalized = normalizeRef(raw);
+                if (!knownSymbols.has(normalized)) {
+                    const absIdx = blockStart + offsetInBlock;
+                    const line = lineOfIndex(code, absIdx);
+                    staleRefs.push({ line, ref: normalized });
+                    const finding = {
+                        id: `stale-doc-ref-${ctx.graph.ir.meta.file.replace(/[^a-z0-9]/gi, '-')}-${line}`,
+                        pass: 'stale-doc-ref',
+                        category: 'maintainability',
+                        rule_id: 'stale-doc-ref',
+                        severity: 'low',
+                        level: 'note',
+                        message: `Doc comment references unknown symbol '${normalized}'. Update or remove the stale reference.`,
+                        file: ctx.graph.ir.meta.file,
+                        line,
+                        evidence: { ref: normalized, raw },
+                    };
+                    ctx.addFinding(finding);
+                }
+            }
+        }
+        return { staleRefs };
+    }
+}
+//# sourceMappingURL=stale-doc-ref-pass.js.map

package/dist/analysis/passes/stale-doc-ref-pass.js.map

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

package/dist/analysis/passes/string-concat-loop-pass.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Pass #50: string-concat-loop (CWE-1046, category: performance)
+ *
+ * Detects string concatenation using `+=` inside loop bodies, which creates
+ * O(n²) string allocations. Each iteration copies the entire accumulated
+ * string, making this a common performance anti-pattern.
+ *
+ * Detection strategy:
+ *   1. Identify loop body line ranges via CFG back-edges (graph.loopBodies()).
+ *   2. For each line within a loop body, scan for `identifier +=` pattern.
+ *   3. Filter out obvious numeric variable names (i, count, sum, etc.) and
+ *      numeric-looking RHS literals to avoid FP on arithmetic accumulation.
+ */
+import type { AnalysisPass, PassContext } from '../../graph/analysis-pass.js';
+export interface StringConcatLoopResult {
+    /** `+=` expressions inside loop bodies that are likely string concatenation. */
+    concatInLoops: Array<{
+        line: number;
+        variable: string;
+    }>;
+}
+export declare class StringConcatLoopPass implements AnalysisPass<StringConcatLoopResult> {
+    readonly name = "string-concat-loop";
+    readonly category: "performance";
+    run(ctx: PassContext): StringConcatLoopResult;
+}

package/dist/analysis/passes/string-concat-loop-pass.js

@@ -0,0 +1,87 @@
+/**
+ * Pass #50: string-concat-loop (CWE-1046, category: performance)
+ *
+ * Detects string concatenation using `+=` inside loop bodies, which creates
+ * O(n²) string allocations. Each iteration copies the entire accumulated
+ * string, making this a common performance anti-pattern.
+ *
+ * Detection strategy:
+ *   1. Identify loop body line ranges via CFG back-edges (graph.loopBodies()).
+ *   2. For each line within a loop body, scan for `identifier +=` pattern.
+ *   3. Filter out obvious numeric variable names (i, count, sum, etc.) and
+ *      numeric-looking RHS literals to avoid FP on arithmetic accumulation.
+ */
+/** Matches `varName +=` at a token boundary. Group 1 = variable name. */
+const CONCAT_RE = /\b([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\+=/;
+/**
+ * Variable names that almost certainly hold numeric values.
+ * These can safely be skipped even if they appear in `+=` expressions.
+ */
+const NUMERIC_VAR_RE = /^(i|j|k|n|m|x|y|z|count|sum|total|size|index|len|length|num|idx|score|counter|offset|pos|col|row|result|ret|value|acc|bits|byte|bytes|flag|flags|step|delta|diff|dist|min|max|avg|mean|page|line|err|error)$/i;
+/** Variable name suffixes that strongly suggest numeric accumulation. */
+const NUMERIC_SUFFIX_RE = /(Count|Sum|Total|Size|Index|Length|Offset|Position|Score|Counter|Num|Amount|Val|Idx|Len|Max|Min|Avg|Delta|Diff|Step|Flag|Flags|Bits|Byte|Bytes|Calls|Items|Nodes|Edges|Blocks|Lines|Chars|Entries|Records|Rows)$/;
+/**
+ * Matches a right-hand side that starts with a digit or decimal point —
+ * these are numeric literals so the `+=` is arithmetic, not string concat.
+ */
+const NUMERIC_RHS_RE = /^\s*[\d.]/;
+export class StringConcatLoopPass {
+    name = 'string-concat-loop';
+    category = 'performance';
+    run(ctx) {
+        const { graph, code } = ctx;
+        const file = graph.ir.meta.file;
+        const loops = graph.loopBodies();
+        if (loops.length === 0)
+            return { concatInLoops: [] };
+        const codeLines = code.split('\n');
+        const concatInLoops = [];
+        const reported = new Set(); // one finding per line
+        for (const loop of loops) {
+            for (let ln = loop.start_line; ln <= loop.end_line; ln++) {
+                if (reported.has(ln))
+                    continue;
+                const src = codeLines[ln - 1] ?? '';
+                const match = CONCAT_RE.exec(src);
+                if (!match)
+                    continue;
+                const varName = match[1];
+                // Skip obviously-numeric variable names
+                if (NUMERIC_VAR_RE.test(varName))
+                    continue;
+                if (NUMERIC_SUFFIX_RE.test(varName))
+                    continue;
+                // Skip if the RHS after `+=` starts with a digit/decimal (numeric literal)
+                const opIdx = src.indexOf('+=');
+                const afterOp = opIdx >= 0 ? src.slice(opIdx + 2) : '';
+                if (NUMERIC_RHS_RE.test(afterOp))
+                    continue;
+                concatInLoops.push({ line: ln, variable: varName });
+                reported.add(ln);
+                ctx.addFinding({
+                    id: `string-concat-loop-${file}-${ln}`,
+                    pass: this.name,
+                    category: this.category,
+                    rule_id: this.name,
+                    cwe: 'CWE-1046',
+                    severity: 'low',
+                    level: 'warning',
+                    message: `String concatenation with '+=' inside a loop: '${varName}' grows O(n²). ` +
+                        `Each iteration copies the entire accumulated string.`,
+                    file,
+                    line: ln,
+                    snippet: src.trim(),
+                    fix: `Accumulate parts in an array and join() after the loop, ` +
+                        `or use StringBuilder (Java) / StringJoiner`,
+                    evidence: {
+                        variable: varName,
+                        loop_start: loop.start_line,
+                        loop_end: loop.end_line,
+                    },
+                });
+            }
+        }
+        return { concatInLoops };
+    }
+}
+//# sourceMappingURL=string-concat-loop-pass.js.map

package/dist/analysis/passes/string-concat-loop-pass.js.map

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

package/dist/analysis/passes/sync-io-async-pass.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pass #48: sync-io-async (CWE-1050, category: performance)
+ *
+ * Detects synchronous (blocking) I/O calls made inside async functions in
+ * JavaScript/TypeScript. Blocking calls stall the Node.js event loop,
+ * negating the benefits of async/await and starving other concurrent work.
+ *
+ * Detection strategy:
+ *   1. Collect async method line ranges from types[].methods where
+ *      modifiers include 'async'.
+ *   2. For each call site within an async range, check if the method name
+ *      ends in 'Sync' (Node.js blocking variants) or is in the curated
+ *      BLOCKING_METHODS set.
+ */
+import type { AnalysisPass, PassContext } from '../../graph/analysis-pass.js';
+export interface SyncIoAsyncResult {
+    /** Blocking calls found inside async functions. */
+    blockingInAsyncFns: Array<{
+        line: number;
+        method: string;
+        enclosingMethod: string;
+    }>;
+}
+export declare class SyncIoAsyncPass implements AnalysisPass<SyncIoAsyncResult> {
+    readonly name = "sync-io-async";
+    readonly category: "performance";
+    run(ctx: PassContext): SyncIoAsyncResult;
+}

package/dist/analysis/passes/sync-io-async-pass.js

@@ -0,0 +1,80 @@
+/**
+ * Pass #48: sync-io-async (CWE-1050, category: performance)
+ *
+ * Detects synchronous (blocking) I/O calls made inside async functions in
+ * JavaScript/TypeScript. Blocking calls stall the Node.js event loop,
+ * negating the benefits of async/await and starving other concurrent work.
+ *
+ * Detection strategy:
+ *   1. Collect async method line ranges from types[].methods where
+ *      modifiers include 'async'.
+ *   2. For each call site within an async range, check if the method name
+ *      ends in 'Sync' (Node.js blocking variants) or is in the curated
+ *      BLOCKING_METHODS set.
+ */
+/**
+ * Methods that are always blocking regardless of name convention.
+ * Kept intentionally small — only add names with virtually no async usage.
+ */
+const BLOCKING_METHODS = new Set([
+    'sleep', // Python time.sleep / any sync sleep utility
+]);
+/** Any method whose name ends in 'Sync' is a blocking Node.js API variant. */
+const SYNC_SUFFIX_RE = /Sync$/;
+export class SyncIoAsyncPass {
+    name = 'sync-io-async';
+    category = 'performance';
+    run(ctx) {
+        const { graph, language } = ctx;
+        // Only relevant for JS/TS (and Python for sleep)
+        if (language !== 'javascript' && language !== 'typescript' && language !== 'python') {
+            return { blockingInAsyncFns: [] };
+        }
+        const file = graph.ir.meta.file;
+        // Collect async method line ranges
+        const asyncRanges = [];
+        for (const type of graph.ir.types) {
+            for (const method of type.methods) {
+                if (method.modifiers.includes('async')) {
+                    asyncRanges.push({
+                        start: method.start_line,
+                        end: method.end_line,
+                        name: method.name,
+                    });
+                }
+            }
+        }
+        if (asyncRanges.length === 0)
+            return { blockingInAsyncFns: [] };
+        const blockingInAsyncFns = [];
+        for (const call of graph.ir.calls) {
+            const name = call.method_name;
+            if (!SYNC_SUFFIX_RE.test(name) && !BLOCKING_METHODS.has(name))
+                continue;
+            const line = call.location.line;
+            const range = asyncRanges.find(r => line >= r.start && line <= r.end);
+            if (!range)
+                continue;
+            blockingInAsyncFns.push({ line, method: name, enclosingMethod: range.name });
+            ctx.addFinding({
+                id: `sync-io-async-${file}-${line}`,
+                pass: this.name,
+                category: this.category,
+                rule_id: this.name,
+                cwe: 'CWE-1050',
+                severity: 'medium',
+                level: 'warning',
+                message: `Blocking call \`${name}()\` inside async function '${range.name}' stalls the event loop`,
+                file,
+                line,
+                fix: `Replace \`${name}\` with its async equivalent and await the result`,
+                evidence: {
+                    blocking_method: name,
+                    async_method: range.name,
+                },
+            });
+        }
+        return { blockingInAsyncFns };
+    }
+}
+//# sourceMappingURL=sync-io-async-pass.js.map

package/dist/analysis/passes/sync-io-async-pass.js.map

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

package/dist/analysis/passes/taint-matcher-pass.d.ts

@@ -0,0 +1,24 @@
+/**
+ * TaintMatcherPass
+ *
+ * First pass in the analysis pipeline. Merges language-plugin built-in
+ * sources/sinks into the config, runs config-based taint matching, and
+ * extracts @sanitizer-annotated method names from type declarations.
+ */
+import type { TaintSource, TaintSink, TaintSanitizer } from '../../types/index.js';
+import type { TaintConfig } from '../../types/config.js';
+import type { AnalysisPass, PassContext } from '../../graph/analysis-pass.js';
+export interface TaintMatcherResult {
+    sources: TaintSource[];
+    sinks: TaintSink[];
+    sanitizers: TaintSanitizer[];
+    /** Method names annotated with @sanitizer (for ConstantPropagationPass). */
+    sanitizerMethods: string[];
+    /** Final merged config (with plugin extensions applied). */
+    config: TaintConfig;
+}
+export declare class TaintMatcherPass implements AnalysisPass<TaintMatcherResult> {
+    readonly name = "taint-matcher";
+    readonly category: "security";
+    run(ctx: PassContext): TaintMatcherResult;
+}

package/dist/analysis/passes/taint-matcher-pass.js

@@ -0,0 +1,71 @@
+/**
+ * TaintMatcherPass
+ *
+ * First pass in the analysis pipeline. Merges language-plugin built-in
+ * sources/sinks into the config, runs config-based taint matching, and
+ * extracts @sanitizer-annotated method names from type declarations.
+ */
+import { analyzeTaint } from '../taint-matcher.js';
+import { getLanguagePlugin } from '../../languages/index.js';
+export class TaintMatcherPass {
+    name = 'taint-matcher';
+    category = 'security';
+    run(ctx) {
+        const { graph, language, config } = ctx;
+        const { calls, types } = graph.ir;
+        // Merge language-plugin built-in sources/sinks.
+        // Plugins (e.g. Bash) define patterns directly on the plugin rather than
+        // in YAML config files; splice them in here so they behave identically.
+        let mergedConfig = config;
+        const plugin = getLanguagePlugin(language);
+        if (plugin) {
+            const pluginSources = plugin.getBuiltinSources();
+            const pluginSinks = plugin.getBuiltinSinks();
+            if (pluginSources.length > 0 || pluginSinks.length > 0) {
+                mergedConfig = {
+                    ...config,
+                    sources: [
+                        ...config.sources,
+                        ...pluginSources.map(s => ({
+                            method: s.method,
+                            class: s.class,
+                            annotation: s.annotation,
+                            type: s.type,
+                            severity: s.severity,
+                            return_tainted: s.returnTainted ?? false,
+                        })),
+                    ],
+                    sinks: [
+                        ...config.sinks,
+                        ...pluginSinks.map(s => ({
+                            method: s.method,
+                            class: s.class,
+                            type: s.type,
+                            cwe: s.cwe,
+                            severity: s.severity,
+                            arg_positions: s.argPositions,
+                        })),
+                    ],
+                };
+            }
+        }
+        const taint = analyzeTaint(calls, types, mergedConfig);
+        // Extract method names annotated with @sanitizer (Javadoc comments).
+        const sanitizerMethods = [];
+        for (const type of types) {
+            for (const method of type.methods) {
+                if (method.annotations.includes('sanitizer')) {
+                    sanitizerMethods.push(method.name);
+                }
+            }
+        }
+        return {
+            sources: taint.sources,
+            sinks: taint.sinks,
+            sanitizers: taint.sanitizers ?? [],
+            sanitizerMethods,
+            config: mergedConfig,
+        };
+    }
+}
+//# sourceMappingURL=taint-matcher-pass.js.map

package/dist/analysis/passes/taint-matcher-pass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"taint-matcher-pass.js","sourceRoot":"","sources":["../../../src/analysis/passes/taint-matcher-pass.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAY7D,MAAM,OAAO,gBAAgB;IAClB,IAAI,GAAG,eAAe,CAAC;IACvB,QAAQ,GAAG,UAAmB,CAAC;IAExC,GAAG,CAAC,GAAgB;QAClB,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;QACxC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC;QAElC,gDAAgD;QAChD,yEAAyE;QACzE,wEAAwE;QACxE,IAAI,YAAY,GAAG,MAAM,CAAC;QAC1B,MAAM,MAAM,GAAG,iBAAiB,CAAC,QAA4D,CAAC,CAAC;QAC/F,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,aAAa,GAAG,MAAM,CAAC,iBAAiB,EAAE,CAAC;YACjD,MAAM,WAAW,GAAG,MAAM,CAAC,eAAe,EAAE,CAAC;YAC7C,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACvD,YAAY,GAAG;oBACb,GAAG,MAAM;oBACT,OAAO,EAAE;wBACP,GAAG,MAAM,CAAC,OAAO;wBACjB,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;4BACzB,MAAM,EAAE,CAAC,CAAC,MAAM;4BAChB,KAAK,EAAE,CAAC,CAAC,KAAK;4BACd,UAAU,EAAE,CAAC,CAAC,UAAU;4BACxB,IAAI,EAAE,CAAC,CAAC,IAAkB;4BAC1B,QAAQ,EAAE,CAAC,CAAC,QAAQ;4BACpB,cAAc,EAAE,CAAC,CAAC,aAAa,IAAI,KAAK;yBACzC,CAAC,CAAC;qBACJ;oBACD,KAAK,EAAE;wBACL,GAAG,MAAM,CAAC,KAAK;wBACf,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;4BACvB,MAAM,EAAE,CAAC,CAAC,MAAM;4BAChB,KAAK,EAAE,CAAC,CAAC,KAAK;4BACd,IAAI,EAAE,CAAC,CAAC,IAAgB;4BACxB,GAAG,EAAE,CAAC,CAAC,GAAG;4BACV,QAAQ,EAAE,CAAC,CAAC,QAAQ;4BACpB,aAAa,EAAE,CAAC,CAAC,YAAY;yBAC9B,CAAC,CAAC;qBACJ;iBACF,CAAC;YACJ,CAAC;QACH,CAAC;QAED,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;QAEvD,qEAAqE;QACrE,MAAM,gBAAgB,GAAa,EAAE,CAAC;QACtC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBAClC,IAAI,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;oBAC7C,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBACrC,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO;YACL,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,EAAE;YAClC,gBAAgB;YAChB,MAAM,EAAE,YAAY;SACrB,CAAC;IACJ,CAAC;CACF"}

package/dist/analysis/passes/taint-propagation-pass.d.ts

@@ -0,0 +1,22 @@
+/**
+ * TaintPropagationPass
+ *
+ * Propagates taint through the DFG to find verified source-to-sink flows,
+ * then supplements with three additional flow-detection strategies that the
+ * DFG-based analysis may miss:
+ *   - Array element flows (tainted array[idx] → sink)
+ *   - Collection/iterator flows (list.get(), queue.poll(), etc.)
+ *   - Direct parameter-to-sink flows (interprocedural parameter used at sink)
+ *
+ * Depends on: sink-filter, constant-propagation
+ */
+import type { TaintFlowInfo } from '../../types/index.js';
+import type { AnalysisPass, PassContext } from '../../graph/analysis-pass.js';
+export interface TaintPropagationPassResult {
+    flows: TaintFlowInfo[];
+}
+export declare class TaintPropagationPass implements AnalysisPass<TaintPropagationPassResult> {
+    readonly name = "taint-propagation";
+    readonly category: "security";
+    run(ctx: PassContext): TaintPropagationPassResult;
+}