circle-ir 3.12.1 → 3.15.0

package/dist/analysis/passes/blocking-main-thread-pass.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pass #83: blocking-main-thread (CWE-1050, category: performance)
+ *
+ * Detects synchronous/blocking operations inside HTTP request handlers
+ * that stall the Node.js event loop, degrading latency under load.
+ *
+ * Scope: JavaScript / TypeScript only.
+ *
+ * Differentiation from SyncIoAsyncPass (#48):
+ *   SyncIoAsyncPass catches *Sync calls inside any `async` function.
+ *   This pass focuses specifically on request handler context
+ *   (NestJS/Express/Koa/Fastify/Hono) and includes expensive crypto/hashing
+ *   operations that are particularly harmful in synchronous handlers.
+ *
+ * Detection strategy:
+ *   1. Identify request handler methods by:
+ *      a. HTTP method decorators in annotations (Get, Post, Put, Patch, Delete)
+ *      b. Common handler parameter names (req, res, ctx, c)
+ *      c. Conventional handler method names (handle, handler)
+ *   2. Within those method ranges, scan graph.ir.calls for:
+ *      a. Blocking *Sync calls (readFileSync, execSync, spawnSync, etc.)
+ *      b. Synchronous crypto operations (createHash, hashSync, pbkdf2Sync,
+ *         scryptSync, generateKeyPairSync)
+ *   3. Emit one warning per blocking call site.
+ */
+import type { AnalysisPass, PassContext } from '../../graph/analysis-pass.js';
+export interface BlockingMainThreadResult {
+    blockingInHandlers: Array<{
+        line: number;
+        method: string;
+        handler: string;
+        reason: 'sync-suffix' | 'crypto';
+    }>;
+}
+export declare class BlockingMainThreadPass implements AnalysisPass<BlockingMainThreadResult> {
+    readonly name = "blocking-main-thread";
+    readonly category: "performance";
+    run(ctx: PassContext): BlockingMainThreadResult;
+    private isRequestHandler;
+}

package/dist/analysis/passes/blocking-main-thread-pass.js

@@ -0,0 +1,112 @@
+/**
+ * Pass #83: blocking-main-thread (CWE-1050, category: performance)
+ *
+ * Detects synchronous/blocking operations inside HTTP request handlers
+ * that stall the Node.js event loop, degrading latency under load.
+ *
+ * Scope: JavaScript / TypeScript only.
+ *
+ * Differentiation from SyncIoAsyncPass (#48):
+ *   SyncIoAsyncPass catches *Sync calls inside any `async` function.
+ *   This pass focuses specifically on request handler context
+ *   (NestJS/Express/Koa/Fastify/Hono) and includes expensive crypto/hashing
+ *   operations that are particularly harmful in synchronous handlers.
+ *
+ * Detection strategy:
+ *   1. Identify request handler methods by:
+ *      a. HTTP method decorators in annotations (Get, Post, Put, Patch, Delete)
+ *      b. Common handler parameter names (req, res, ctx, c)
+ *      c. Conventional handler method names (handle, handler)
+ *   2. Within those method ranges, scan graph.ir.calls for:
+ *      a. Blocking *Sync calls (readFileSync, execSync, spawnSync, etc.)
+ *      b. Synchronous crypto operations (createHash, hashSync, pbkdf2Sync,
+ *         scryptSync, generateKeyPairSync)
+ *   3. Emit one warning per blocking call site.
+ */
+/** HTTP method decorator names (NestJS / Fastify / express-style, without the @ prefix). */
+const HTTP_DECORATORS = new Set([
+    'Get', 'Post', 'Put', 'Patch', 'Delete', 'All', 'Options', 'Head',
+    'Route', 'Handler',
+]);
+/** Parameter names that indicate an HTTP request handler. */
+const HANDLER_PARAM_NAMES = new Set([
+    'req', 'res', 'request', 'response', 'ctx', 'c', 'event',
+]);
+/** Method names that strongly suggest HTTP request handling. */
+const HANDLER_METHOD_NAMES = new Set([
+    'handle', 'handler', 'dispatch', 'invoke', 'serve',
+]);
+/** Synchronous crypto operations that are expensive in the request path. */
+const CRYPTO_BLOCKING_METHODS = new Set([
+    'createHash', 'hashSync', 'pbkdf2Sync', 'scryptSync',
+    'generateKeyPairSync', 'generateKeySync', 'deriveKeySync',
+]);
+const SYNC_SUFFIX_RE = /Sync$/;
+export class BlockingMainThreadPass {
+    name = 'blocking-main-thread';
+    category = 'performance';
+    run(ctx) {
+        const { graph, language } = ctx;
+        if (language !== 'javascript' && language !== 'typescript') {
+            return { blockingInHandlers: [] };
+        }
+        const file = graph.ir.meta.file;
+        // Collect request handler method line ranges
+        const handlerRanges = [];
+        for (const type of graph.ir.types) {
+            for (const method of type.methods) {
+                if (this.isRequestHandler(method)) {
+                    handlerRanges.push({
+                        start: method.start_line,
+                        end: method.end_line,
+                        name: method.name,
+                    });
+                }
+            }
+        }
+        if (handlerRanges.length === 0)
+            return { blockingInHandlers: [] };
+        const blockingInHandlers = [];
+        for (const call of graph.ir.calls) {
+            const name = call.method_name;
+            const isCrypto = CRYPTO_BLOCKING_METHODS.has(name);
+            const isSyncSuffix = SYNC_SUFFIX_RE.test(name);
+            if (!isCrypto && !isSyncSuffix)
+                continue;
+            const line = call.location.line;
+            const range = handlerRanges.find(r => line >= r.start && line <= r.end);
+            if (!range)
+                continue;
+            const reason = isCrypto ? 'crypto' : 'sync-suffix';
+            blockingInHandlers.push({ line, method: name, handler: range.name, reason });
+            ctx.addFinding({
+                id: `blocking-main-thread-${file}-${line}`,
+                pass: this.name,
+                category: this.category,
+                rule_id: this.name,
+                cwe: 'CWE-1050',
+                severity: 'medium',
+                level: 'warning',
+                message: `Blocking call \`${name}()\` inside request handler '${range.name}' ` +
+                    `stalls the event loop under concurrent load`,
+                file,
+                line,
+                fix: 'Move to an async equivalent or offload to a worker thread',
+                evidence: { handler: range.name, blocking_method: name, reason },
+            });
+        }
+        return { blockingInHandlers };
+    }
+    isRequestHandler(method) {
+        // NestJS / Fastify HTTP decorators
+        if (method.annotations.some(a => HTTP_DECORATORS.has(a)))
+            return true;
+        // Conventional handler method names
+        if (HANDLER_METHOD_NAMES.has(method.name))
+            return true;
+        // Express/Koa/Hono request handler patterns: (req, res) or (ctx)
+        const paramNames = method.parameters.map(p => p.name.toLowerCase());
+        return paramNames.some(n => HANDLER_PARAM_NAMES.has(n));
+    }
+}
+//# sourceMappingURL=blocking-main-thread-pass.js.map

package/dist/analysis/passes/blocking-main-thread-pass.js.map

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

package/dist/analysis/passes/excessive-allocation-pass.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Pass #84: excessive-allocation (CWE-770, category: performance)
+ *
+ * Detects collection/object allocations inside loop bodies that
+ * create unnecessary GC pressure and slow down hot paths.
+ * Each allocation forces the garbage collector to do extra work,
+ * degrading throughput in tight loops.
+ *
+ * Detection strategy:
+ *   1. Identify loop body line ranges via graph.loopBodies().
+ *   2. For each line within a loop body, scan source text for
+ *      language-specific allocation patterns.
+ *   3. Skip lines with explicit reuse signals (pool, cache, preallocat).
+ *   4. Emit one warning per allocation site.
+ *
+ * Languages: Java, JavaScript/TypeScript, Python, Rust. Bash — skipped.
+ */
+import type { AnalysisPass, PassContext } from '../../graph/analysis-pass.js';
+export interface ExcessiveAllocationResult {
+    allocationsInLoops: Array<{
+        line: number;
+        pattern: string;
+    }>;
+}
+export declare class ExcessiveAllocationPass implements AnalysisPass<ExcessiveAllocationResult> {
+    readonly name = "excessive-allocation";
+    readonly category: "performance";
+    run(ctx: PassContext): ExcessiveAllocationResult;
+}

package/dist/analysis/passes/excessive-allocation-pass.js

@@ -0,0 +1,85 @@
+/**
+ * Pass #84: excessive-allocation (CWE-770, category: performance)
+ *
+ * Detects collection/object allocations inside loop bodies that
+ * create unnecessary GC pressure and slow down hot paths.
+ * Each allocation forces the garbage collector to do extra work,
+ * degrading throughput in tight loops.
+ *
+ * Detection strategy:
+ *   1. Identify loop body line ranges via graph.loopBodies().
+ *   2. For each line within a loop body, scan source text for
+ *      language-specific allocation patterns.
+ *   3. Skip lines with explicit reuse signals (pool, cache, preallocat).
+ *   4. Emit one warning per allocation site.
+ *
+ * Languages: Java, JavaScript/TypeScript, Python, Rust. Bash — skipped.
+ */
+/** Allocation patterns keyed by language. */
+const ALLOC_PATTERNS = {
+    javascript: /\bnew\s+(Array|Map|Set|Object|WeakMap|WeakSet|Error|RegExp|Date|Buffer|Uint8Array|Int8Array|Float32Array|ArrayBuffer)\s*[(<]|\bArray\.from\s*\(|\bstructuredClone\s*\(|\bObject\.create\s*\(/,
+    typescript: /\bnew\s+(Array|Map|Set|Object|WeakMap|WeakSet|Error|RegExp|Date|Buffer|Uint8Array|Int8Array|Float32Array|ArrayBuffer)\s*[(<]|\bArray\.from\s*\(|\bstructuredClone\s*\(|\bObject\.create\s*\(/,
+    java: /\bnew\s+(ArrayList|HashMap|HashSet|LinkedList|TreeMap|TreeSet|PriorityQueue|ArrayDeque|StringBuilder|StringBuffer|CopyOnWriteArrayList|ConcurrentHashMap)\s*[(<]|\bnew\s+\w[\w.<>]*\[\s*[a-zA-Z]\w*/,
+    python: /\b(list|dict|set|tuple|bytearray|defaultdict|OrderedDict|Counter|deque)\s*\(\s*\)|\[\s*\]|\{\s*\}(?!\s*[}\]])/,
+    rust: /\b(Vec|HashMap|HashSet|BTreeMap|BTreeSet|VecDeque|LinkedList|String|Box|Rc|Arc)\s*::\s*new\s*\(/,
+};
+/** Signals that the allocation is intentional / is a reuse pattern. */
+const BENIGN_RE = /\bpool\b|\bcache\b|\breuse\b|\bpreallocat|\brecycl/i;
+export class ExcessiveAllocationPass {
+    name = 'excessive-allocation';
+    category = 'performance';
+    run(ctx) {
+        const { graph, code, language } = ctx;
+        if (language === 'bash') {
+            return { allocationsInLoops: [] };
+        }
+        const pattern = ALLOC_PATTERNS[language];
+        if (!pattern)
+            return { allocationsInLoops: [] };
+        const loops = graph.loopBodies();
+        if (loops.length === 0)
+            return { allocationsInLoops: [] };
+        const file = graph.ir.meta.file;
+        const codeLines = code.split('\n');
+        const allocationsInLoops = [];
+        const reported = new Set();
+        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 = pattern.exec(src);
+                if (!match)
+                    continue;
+                if (BENIGN_RE.test(src))
+                    continue;
+                // Extract a short label for the allocation pattern
+                const allocLabel = match[0].replace(/\s+/g, ' ').trim();
+                allocationsInLoops.push({ line: ln, pattern: allocLabel });
+                reported.add(ln);
+                ctx.addFinding({
+                    id: `excessive-allocation-${file}-${ln}`,
+                    pass: this.name,
+                    category: this.category,
+                    rule_id: this.name,
+                    cwe: 'CWE-770',
+                    severity: 'medium',
+                    level: 'warning',
+                    message: `Repeated allocation inside loop (lines ${loop.start_line}–${loop.end_line}): ` +
+                        `\`${allocLabel}\` creates GC pressure on every iteration`,
+                    file,
+                    line: ln,
+                    snippet: src.trim(),
+                    fix: 'Pre-allocate outside the loop and reset/reuse the collection each iteration',
+                    evidence: {
+                        allocation: allocLabel,
+                        loop_start: loop.start_line,
+                        loop_end: loop.end_line,
+                    },
+                });
+            }
+        }
+        return { allocationsInLoops };
+    }
+}
+//# sourceMappingURL=excessive-allocation-pass.js.map

package/dist/analysis/passes/excessive-allocation-pass.js.map

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

package/dist/analysis/passes/feature-envy-pass.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Pass #87: feature-envy (CWE-1060, category: architecture)
+ *
+ * @deprecated NOT REGISTERED IN THE DEFAULT PIPELINE
+ *
+ * This pass was removed from the default AnalysisPipeline in v3.14.0 because
+ * the call-count heuristic (external_max ≥ 4 AND margin > 2) fires trivially
+ * on legitimate delegation patterns — facades, controllers, service classes —
+ * and its fix suggestion ("move this method to OtherClass") is incorrect when
+ * the method's design intent is orchestration rather than feature envy.
+ * Confirming true feature envy requires understanding design intent, which is
+ * LLM territory.
+ *
+ * The raw signals this pass relies on are already present in CircleIR:
+ *   • ir.calls   — per-callsite receiver, receiver_type, location.line
+ *   • ir.types   — per-method start_line / end_line to scope the calls
+ *
+ * This file is retained so that circle-ir-ai can consume the per-method
+ * call-count breakdown and apply semantic reasoning to distinguish genuine
+ * feature envy from intentional delegation.
+ *
+ * Detects methods that call another class's methods far more often than
+ * their own class's — a sign that the method "envies" the other class
+ * and should probably be moved there.
+ *
+ * Detection strategy:
+ *   1. For each method in each class, collect all call sites in its line range.
+ *   2. Separate calls into:
+ *        internal — receiver is 'this' / 'self' / null (own class)
+ *        external — receiver_type != own class name (other classes)
+ *   3. Find the external type with the most calls (external_max).
+ *   4. Emit a note when:
+ *        external_max >= 4  (at least 4 calls to another class)
+ *      AND
+ *        external_max > internal + 2  (clearly prefers the other class)
+ *
+ * Languages: Java, TypeScript, Python. Bash / Rust — skipped.
+ */
+import type { AnalysisPass, PassContext } from '../../graph/analysis-pass.js';
+export interface FeatureEnvyResult {
+    envyMethods: Array<{
+        className: string;
+        methodName: string;
+        line: number;
+        enviedClass: string;
+        externalCalls: number;
+        internalCalls: number;
+    }>;
+}
+export declare class FeatureEnvyPass implements AnalysisPass<FeatureEnvyResult> {
+    readonly name = "feature-envy";
+    readonly category: "architecture";
+    run(ctx: PassContext): FeatureEnvyResult;
+}

package/dist/analysis/passes/feature-envy-pass.js

@@ -0,0 +1,132 @@
+/**
+ * Pass #87: feature-envy (CWE-1060, category: architecture)
+ *
+ * @deprecated NOT REGISTERED IN THE DEFAULT PIPELINE
+ *
+ * This pass was removed from the default AnalysisPipeline in v3.14.0 because
+ * the call-count heuristic (external_max ≥ 4 AND margin > 2) fires trivially
+ * on legitimate delegation patterns — facades, controllers, service classes —
+ * and its fix suggestion ("move this method to OtherClass") is incorrect when
+ * the method's design intent is orchestration rather than feature envy.
+ * Confirming true feature envy requires understanding design intent, which is
+ * LLM territory.
+ *
+ * The raw signals this pass relies on are already present in CircleIR:
+ *   • ir.calls   — per-callsite receiver, receiver_type, location.line
+ *   • ir.types   — per-method start_line / end_line to scope the calls
+ *
+ * This file is retained so that circle-ir-ai can consume the per-method
+ * call-count breakdown and apply semantic reasoning to distinguish genuine
+ * feature envy from intentional delegation.
+ *
+ * Detects methods that call another class's methods far more often than
+ * their own class's — a sign that the method "envies" the other class
+ * and should probably be moved there.
+ *
+ * Detection strategy:
+ *   1. For each method in each class, collect all call sites in its line range.
+ *   2. Separate calls into:
+ *        internal — receiver is 'this' / 'self' / null (own class)
+ *        external — receiver_type != own class name (other classes)
+ *   3. Find the external type with the most calls (external_max).
+ *   4. Emit a note when:
+ *        external_max >= 4  (at least 4 calls to another class)
+ *      AND
+ *        external_max > internal + 2  (clearly prefers the other class)
+ *
+ * Languages: Java, TypeScript, Python. Bash / Rust — skipped.
+ */
+/** Minimum external calls to flag feature envy (avoids trivial utility calls). */
+const MIN_EXTERNAL_CALLS = 4;
+/** How many more calls to external type than own type to flag. */
+const ENVY_MARGIN = 2;
+export class FeatureEnvyPass {
+    name = 'feature-envy';
+    category = 'architecture';
+    run(ctx) {
+        const { graph, language } = ctx;
+        if (language === 'bash' || language === 'rust') {
+            return { envyMethods: [] };
+        }
+        const file = graph.ir.meta.file;
+        const envyMethods = [];
+        for (const type of graph.ir.types) {
+            if (type.kind !== 'class')
+                continue;
+            const ownName = type.name;
+            for (const method of type.methods) {
+                const start = method.start_line;
+                const end = method.end_line;
+                // Collect calls within this method's line range
+                const callsInMethod = graph.ir.calls.filter(c => c.location.line >= start && c.location.line <= end);
+                if (callsInMethod.length === 0)
+                    continue;
+                let internalCalls = 0;
+                const externalCallCounts = new Map();
+                for (const call of callsInMethod) {
+                    const receiver = call.receiver?.toLowerCase();
+                    const receiverType = call.receiver_type;
+                    // Internal: receiver is 'this'/'self', null, or the own type
+                    if (receiver == null ||
+                        receiver === 'this' ||
+                        receiver === 'self' ||
+                        receiverType == null ||
+                        receiverType === ownName) {
+                        internalCalls++;
+                        continue;
+                    }
+                    // External: strip generic parameters from receiver_type
+                    const extType = receiverType.replace(/<.*>/, '').trim();
+                    if (extType && extType !== ownName) {
+                        externalCallCounts.set(extType, (externalCallCounts.get(extType) ?? 0) + 1);
+                    }
+                }
+                if (externalCallCounts.size === 0)
+                    continue;
+                // Find the most-called external type
+                let enviedClass = '';
+                let externalMax = 0;
+                for (const [typeName, count] of externalCallCounts) {
+                    if (count > externalMax) {
+                        externalMax = count;
+                        enviedClass = typeName;
+                    }
+                }
+                if (externalMax < MIN_EXTERNAL_CALLS)
+                    continue;
+                if (externalMax <= internalCalls + ENVY_MARGIN)
+                    continue;
+                envyMethods.push({
+                    className: ownName,
+                    methodName: method.name,
+                    line: method.start_line,
+                    enviedClass,
+                    externalCalls: externalMax,
+                    internalCalls,
+                });
+                ctx.addFinding({
+                    id: `feature-envy-${file}-${method.start_line}`,
+                    pass: this.name,
+                    category: this.category,
+                    rule_id: this.name,
+                    cwe: 'CWE-1060',
+                    severity: 'low',
+                    level: 'note',
+                    message: `Feature Envy: \`${ownName}.${method.name}()\` makes ${externalMax} calls to ` +
+                        `\`${enviedClass}\` vs ${internalCalls} calls to own class`,
+                    file,
+                    line: method.start_line,
+                    fix: `Consider moving \`${method.name}\` to \`${enviedClass}\`, ` +
+                        `or introducing a collaborator object`,
+                    evidence: {
+                        envied_class: enviedClass,
+                        external_calls: externalMax,
+                        internal_calls: internalCalls,
+                    },
+                });
+            }
+        }
+        return { envyMethods };
+    }
+}
+//# sourceMappingURL=feature-envy-pass.js.map

package/dist/analysis/passes/feature-envy-pass.js.map

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

package/dist/analysis/passes/god-class-pass.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Pass #86: god-class (CWE-1060, category: architecture)
+ *
+ * Detects "God Class" anti-pattern: a class that does too much, is poorly
+ * cohesive, and is heavily coupled to external types. These classes are hard
+ * to test, maintain, and evolve.
+ *
+ * Three CK metrics are computed inline (the metrics pipeline runs separately
+ * and its results are not available here):
+ *
+ *   WMC  — Weighted Methods per Class: Σ v(G) per method, where v(G) is
+ *           McCabe cyclomatic complexity = CFG edges − nodes + 2.
+ *           Fallback = 1 per method when CFG data is absent.
+ *
+ *   LCOM2 — Lack of Cohesion of Methods (0–1 scale):
+ *           (P − Q) / max(1, m*(m−1)/2)
+ *           P = method pairs sharing no fields, Q = pairs sharing ≥1 field.
+ *           Field access is inferred from DFG defs/uses whose variable name
+ *           matches a declared field name (name-match heuristic).
+ *
+ *   CBO  — Coupling Between Objects: count of distinct external type names
+ *           referenced in parameter types, field types, or call receiver_type
+ *           within the class, excluding primitives and same-class references.
+ *
+ * A finding is emitted when at least 2 of the 3 thresholds are exceeded:
+ *   WMC > 47   (SonarQube default)
+ *   LCOM2 > 0.8
+ *   CBO > 14   (SATD threshold)
+ *
+ * Languages: Java, TypeScript, Python. Bash / Rust — skipped.
+ */
+import type { AnalysisPass, PassContext } from '../../graph/analysis-pass.js';
+export interface GodClassResult {
+    godClasses: Array<{
+        className: string;
+        line: number;
+        wmc: number;
+        lcom2: number;
+        cbo: number;
+    }>;
+}
+export declare class GodClassPass implements AnalysisPass<GodClassResult> {
+    readonly name = "god-class";
+    readonly category: "architecture";
+    run(ctx: PassContext): GodClassResult;
+    /** Compute WMC = Σ v(G) for all methods. v(G) = edges − nodes + 2. */
+    private computeWMC;
+    /**
+     * Compute LCOM2 = (P − Q) / max(1, m*(m−1)/2) clamped to [0, 1].
+     * Uses DFG variable names intersected with declared field names.
+     */
+    private computeLCOM2;
+    /**
+     * Compute CBO = count of distinct external type names referenced in the class.
+     * Sources: call receiver_type, method parameter types, field types.
+     */
+    private computeCBO;
+}