circle-ir 3.8.3 → 3.9.7

package/dist/analysis/passes/leaked-global-pass.js

@@ -0,0 +1,108 @@
+/**
+ * Pass #81: leaked-global (CWE-1109, category: reliability)
+ *
+ * Detects assignments to undeclared variables inside function bodies in
+ * JavaScript/TypeScript.  In non-strict mode JS (and absent `"use strict"`)
+ * writing to a variable that has no `let`/`const`/`var` declaration anywhere
+ * in the enclosing function silently creates (or mutates) a property on the
+ * global object — a classic source of hard-to-trace bugs.
+ *
+ * Detection strategy:
+ *   1. Language filter: JS/TS only.
+ *   2. Build a ScopeGraph for declaration-keyword awareness.
+ *   3. For each `kind='local'` def whose source line has NO declaration keyword:
+ *      - Skip intentional throwaway names (_, err, e, …) and loop vars.
+ *      - Skip if the variable IS declared (hasDeclKeyword=true) somewhere
+ *        else in the same enclosing function → it is a legitimate reassignment.
+ *      - Skip top-level assignments (methodStart === -1) — module-level bare
+ *        assignments are an ES module pattern.
+ *      - Flag the rest as potential global leaks.
+ */
+import { ScopeGraph } from '../../graph/scope-graph.js';
+/** Variable names that are intentionally never declared with a keyword. */
+const SKIP_NAMES = new Set([
+    '_', 'e', 'err', 'error', 'event', 'ex', 'exception',
+    'i', 'j', 'k', 'n', 'idx', 'index',
+]);
+export class LeakedGlobalPass {
+    name = 'leaked-global';
+    category = 'reliability';
+    run(ctx) {
+        const { graph, code, language } = ctx;
+        // JS/TS only — Python, Java, Rust all require explicit declarations
+        if (language !== 'javascript' && language !== 'typescript') {
+            return { leaks: [] };
+        }
+        const file = graph.ir.meta.file;
+        // Skip test files — test helpers often use bare assignments intentionally
+        if (/[./](?:test|spec)[./]/.test(file) || /\.(?:test|spec)\.[jt]s$/.test(file)) {
+            return { leaks: [] };
+        }
+        const scope = new ScopeGraph(graph, code, language);
+        const codeLines = code.split('\n');
+        const leaks = [];
+        const reported = new Set(); // deduplicate by line
+        for (const entry of scope.entries) {
+            const { def, hasDeclKeyword, methodStart } = entry;
+            // Only look at bare assignments (no let/const/var on this line)
+            if (hasDeclKeyword)
+                continue;
+            if (def.kind !== 'local')
+                continue;
+            const variable = def.variable;
+            // Intentionally-unnamed / loop variables → skip
+            if (variable.startsWith('_'))
+                continue;
+            if (SKIP_NAMES.has(variable))
+                continue;
+            // Top-level (module scope) assignments → not a leaked global
+            if (methodStart === -1)
+                continue;
+            // If the same variable has a declared def (let/const/var) anywhere in
+            // this function body, this line is a legitimate reassignment — not a leak.
+            if (scope.hasDeclaredDef(variable, methodStart))
+                continue;
+            // Text-search fallback: `let x;` (no initializer) creates no DFG def, so
+            // hasDeclaredDef misses it. Scan source lines within the method for any
+            // `let/const/var ... varName` declaration.
+            const methodInfo = graph.methodAtLine(def.line);
+            if (methodInfo) {
+                const { start_line, end_line } = methodInfo.method;
+                const escapedVar = variable.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                // Match: let/const/var followed (possibly after { or [ for destructuring) by the name
+                const declPattern = new RegExp(`\\b(?:let|const|var)\\b[^=;\\n]*\\b${escapedVar}\\b`);
+                const hasTextDecl = codeLines.slice(start_line - 1, end_line).some(l => declPattern.test(l));
+                if (hasTextDecl)
+                    continue;
+                // Also check module-level lines (before the method) for `let varName`
+                const moduleDecl = new RegExp(`^(?:export\\s+)?(?:let|const|var)\\b[^=;\\n]*\\b${escapedVar}\\b`);
+                const hasModuleDecl = codeLines.slice(0, start_line - 1).some(l => moduleDecl.test(l));
+                if (hasModuleDecl)
+                    continue;
+            }
+            if (reported.has(def.line))
+                continue;
+            reported.add(def.line);
+            const enclosingFunction = methodInfo?.method.name ?? null;
+            leaks.push({ line: def.line, variable, enclosingFunction });
+            const fnDesc = enclosingFunction ? ` inside '${enclosingFunction}'` : '';
+            ctx.addFinding({
+                id: `leaked-global-${file}-${def.line}`,
+                pass: this.name,
+                category: this.category,
+                rule_id: this.name,
+                cwe: 'CWE-1109',
+                severity: 'medium',
+                level: 'warning',
+                message: `'${variable}' is assigned without a declaration keyword${fnDesc} — ` +
+                    `creates an accidental global in non-strict mode`,
+                file,
+                line: def.line,
+                fix: `Add \`let\`, \`const\`, or \`var\` before the first assignment to '${variable}'`,
+                evidence: { variable, enclosing_function: enclosingFunction },
+            });
+        }
+        return { leaks };
+    }
+}
+//# sourceMappingURL=leaked-global-pass.js.map

package/dist/analysis/passes/leaked-global-pass.js.map

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

package/dist/analysis/passes/missing-await-pass.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Pass #24: missing-await (CWE-252, category: reliability)
+ *
+ * Detects calls to well-known async APIs in JavaScript/TypeScript where the
+ * returned Promise is silently discarded — the call result is neither awaited
+ * nor captured in a variable. This is the "fire-and-forget" pattern that hides
+ * errors and makes execution non-deterministic.
+ *
+ * Detection criteria (ALL must hold):
+ *   1. Language is javascript or typescript.
+ *   2. The method name is in the curated ASYNC_METHODS set.
+ *   3. The source line does NOT contain the `await` keyword.
+ *   4. There is no DFG definition at the call's line (result not assigned).
+ *
+ * Deliberately narrow to keep false-positive rate near zero. Only methods that
+ * are essentially always async in practice are included. The `return async()`
+ * pattern is excluded (legitimate "pass-through Promise" idiom).
+ */
+import type { CallInfo } from '../../types/index.js';
+import type { AnalysisPass, PassContext } from '../../graph/analysis-pass.js';
+export interface MissingAwaitPassResult {
+    /** Calls where a Promise return value is silently discarded. */
+    missingAwaitCalls: CallInfo[];
+}
+export declare class MissingAwaitPass implements AnalysisPass<MissingAwaitPassResult> {
+    readonly name = "missing-await";
+    readonly category: "reliability";
+    run(ctx: PassContext): MissingAwaitPassResult;
+}

package/dist/analysis/passes/missing-await-pass.js

@@ -0,0 +1,90 @@
+/**
+ * Pass #24: missing-await (CWE-252, category: reliability)
+ *
+ * Detects calls to well-known async APIs in JavaScript/TypeScript where the
+ * returned Promise is silently discarded — the call result is neither awaited
+ * nor captured in a variable. This is the "fire-and-forget" pattern that hides
+ * errors and makes execution non-deterministic.
+ *
+ * Detection criteria (ALL must hold):
+ *   1. Language is javascript or typescript.
+ *   2. The method name is in the curated ASYNC_METHODS set.
+ *   3. The source line does NOT contain the `await` keyword.
+ *   4. There is no DFG definition at the call's line (result not assigned).
+ *
+ * Deliberately narrow to keep false-positive rate near zero. Only methods that
+ * are essentially always async in practice are included. The `return async()`
+ * pattern is excluded (legitimate "pass-through Promise" idiom).
+ */
+/**
+ * Methods that are async in virtually every JS/TS codebase.
+ * Grouped by domain for maintainability.
+ */
+const ASYNC_METHODS = new Set([
+    // Node.js fs.promises / util.promisify (the async variants)
+    'readFile', 'writeFile', 'appendFile', 'unlink', 'rmdir', 'mkdir',
+    'readdir', 'stat', 'lstat', 'access', 'rename', 'copyFile',
+    // Network / HTTP
+    'fetch',
+    // Database — raw clients
+    'query', 'execute',
+    // Mongoose ODM
+    'findOne', 'findById', 'findByIdAndUpdate', 'findByIdAndDelete',
+    'findOneAndUpdate', 'findOneAndDelete', 'countDocuments', 'aggregate',
+    // Sequelize / TypeORM overlap
+    'findAll', 'findAndCountAll', 'bulkCreate',
+    // Prisma
+    'findFirst', 'findUnique', 'findMany',
+    // Generic lifecycle
+    'connect', 'disconnect',
+]);
+export class MissingAwaitPass {
+    name = 'missing-await';
+    category = 'reliability';
+    run(ctx) {
+        const { graph, code, language } = ctx;
+        // Only JS/TS: other languages either don't have async/await or surface
+        // missing-await through their type systems (Rust, Java).
+        if (language !== 'javascript' && language !== 'typescript') {
+            return { missingAwaitCalls: [] };
+        }
+        const lines = code.split('\n');
+        const file = graph.ir.meta.file;
+        // Lines that have a DFG definition — result is captured in a variable.
+        const linesWithDefs = new Set(graph.ir.dfg.defs.map(d => d.line));
+        const missingAwaitCalls = [];
+        for (const call of graph.ir.calls) {
+            if (!ASYNC_METHODS.has(call.method_name))
+                continue;
+            const lineNum = call.location.line;
+            const lineText = lines[lineNum - 1] ?? '';
+            // Skip if `await` is present on this line (already awaited).
+            if (/\bawait\b/.test(lineText))
+                continue;
+            // Skip if result is captured (DFG def at this line).
+            if (linesWithDefs.has(lineNum))
+                continue;
+            // Skip `return asyncOp()` — intentional Promise pass-through.
+            if (/^\s*return\b/.test(lineText))
+                continue;
+            missingAwaitCalls.push(call);
+            ctx.addFinding({
+                id: `missing-await-${file}-${lineNum}`,
+                pass: this.name,
+                category: this.category,
+                rule_id: this.name,
+                cwe: 'CWE-252',
+                severity: 'medium',
+                level: 'warning',
+                message: `Missing await: \`${call.method_name}()\` returns a Promise that is neither ` +
+                    `awaited nor captured — errors will be silently swallowed`,
+                file,
+                line: lineNum,
+                snippet: lineText.trim(),
+                fix: `Add \`await\` before \`${call.method_name}()\`, or assign the Promise and handle rejection`,
+            });
+        }
+        return { missingAwaitCalls };
+    }
+}
+//# sourceMappingURL=missing-await-pass.js.map

package/dist/analysis/passes/missing-await-pass.js.map

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

package/dist/analysis/passes/missing-public-doc-pass.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pass #35: missing-public-doc (category: maintainability)
+ *
+ * Detects public/exported methods and types that have no doc comment.
+ * A "doc comment" is a Javadoc-style `/** ... *\/` block, a TypeScript/JS
+ * JSDoc `/** ... *\/` block, a Rust `///` line comment, or a Python docstring
+ * (`"""..."""` as the first statement of the function body).
+ *
+ * What counts as "public":
+ *   - Java / Kotlin: `modifiers` contains `"public"`.
+ *   - JavaScript / TypeScript: `modifiers` does NOT contain `"private"` or
+ *     `"protected"`. (JS has no access keywords; everything is implicitly public.)
+ *   - Python: method name does not start with `_`.
+ *   - Rust / Bash / other: skipped (doc conventions differ too much).
+ *
+ * Types (classes, interfaces) are always checked — they are extracted only when
+ * they are top-level declarations and therefore always "public" in the IR sense.
+ *
+ * Test files are excluded: if the file path contains test/spec patterns, the
+ * pass emits no findings (doc comments in test helpers are low value).
+ */
+import type { MethodInfo, TypeInfo } from '../../types/index.js';
+import type { AnalysisPass, PassContext } from '../../graph/analysis-pass.js';
+export interface MissingPublicDocPassResult {
+    missingDocMethods: Array<{
+        type: TypeInfo;
+        method: MethodInfo;
+    }>;
+    missingDocTypes: TypeInfo[];
+}
+export declare class MissingPublicDocPass implements AnalysisPass<MissingPublicDocPassResult> {
+    readonly name = "missing-public-doc";
+    readonly category: "maintainability";
+    run(ctx: PassContext): MissingPublicDocPassResult;
+}

package/dist/analysis/passes/missing-public-doc-pass.js

@@ -0,0 +1,148 @@
+/**
+ * Pass #35: missing-public-doc (category: maintainability)
+ *
+ * Detects public/exported methods and types that have no doc comment.
+ * A "doc comment" is a Javadoc-style `/** ... *\/` block, a TypeScript/JS
+ * JSDoc `/** ... *\/` block, a Rust `///` line comment, or a Python docstring
+ * (`"""..."""` as the first statement of the function body).
+ *
+ * What counts as "public":
+ *   - Java / Kotlin: `modifiers` contains `"public"`.
+ *   - JavaScript / TypeScript: `modifiers` does NOT contain `"private"` or
+ *     `"protected"`. (JS has no access keywords; everything is implicitly public.)
+ *   - Python: method name does not start with `_`.
+ *   - Rust / Bash / other: skipped (doc conventions differ too much).
+ *
+ * Types (classes, interfaces) are always checked — they are extracted only when
+ * they are top-level declarations and therefore always "public" in the IR sense.
+ *
+ * Test files are excluded: if the file path contains test/spec patterns, the
+ * pass emits no findings (doc comments in test helpers are low value).
+ */
+/** Files matching these path patterns are treated as test/spec files. */
+const TEST_PATH_RE = /[/._](test|tests|spec|specs|__tests?__|__mocks?__)[/._]/i;
+/**
+ * Files in common utility/helper directories are implementation details, not
+ * public library API. Requiring JSDoc on every class in these directories
+ * produces noise when the project is a CLI tool or application.
+ */
+const UTIL_DIR_RE = /[/](utils?|helpers?|internal|private|common|shared)[/]/i;
+/** Checks whether a single character position is a doc-comment start. */
+function hasDocCommentBefore(lines, startLine) {
+    // Look back up to 10 lines (handles multi-line annotations + blank lines).
+    const limit = Math.max(0, startLine - 11);
+    for (let i = startLine - 2; i >= limit; i--) {
+        const trimmed = lines[i]?.trim() ?? '';
+        if (trimmed === '')
+            continue; // blank — keep looking
+        if (trimmed.startsWith('/**') || // Javadoc / JSDoc open
+            trimmed.startsWith('*/') || // mid-block or close
+            trimmed.startsWith('*') || // doc block body line
+            trimmed.startsWith('///') || // Rust / C# doc comment
+            trimmed.startsWith('//!')) { // Rust inner doc
+            return true;
+        }
+        // If we hit a non-blank, non-doc line that isn't an annotation or decorator,
+        // stop searching — we've gone past any preceding doc block.
+        if (!trimmed.startsWith('@') && !trimmed.startsWith('#['))
+            break;
+    }
+    return false;
+}
+/** Check whether the first statement in the method body is a Python docstring. */
+function hasPythonDocstring(lines, method) {
+    const bodyStart = method.start_line; // start_line is the `def` line (1-indexed)
+    for (let i = bodyStart; i < Math.min(bodyStart + 4, lines.length); i++) {
+        const trimmed = lines[i]?.trim() ?? '';
+        if (trimmed === '')
+            continue;
+        return trimmed.startsWith('"""') || trimmed.startsWith("'''");
+    }
+    return false;
+}
+function isPublicMethod(method, language) {
+    switch (language) {
+        case 'java':
+            return method.modifiers.includes('public');
+        case 'javascript':
+        case 'typescript':
+            return !method.modifiers.includes('private') &&
+                !method.modifiers.includes('protected');
+        case 'python':
+            return !method.name.startsWith('_');
+        default:
+            return false; // Rust, Bash, etc. — skip
+    }
+}
+export class MissingPublicDocPass {
+    name = 'missing-public-doc';
+    category = 'maintainability';
+    run(ctx) {
+        const { graph, code, language } = ctx;
+        // Skip test/spec files — doc comments in test helpers are low value.
+        if (TEST_PATH_RE.test(graph.ir.meta.file)) {
+            return { missingDocMethods: [], missingDocTypes: [] };
+        }
+        // Skip files inside utility/helper directories — these are internal
+        // implementation details, not public library API surfaces.
+        if (UTIL_DIR_RE.test(graph.ir.meta.file)) {
+            return { missingDocMethods: [], missingDocTypes: [] };
+        }
+        // Only supported languages.
+        if (!['java', 'javascript', 'typescript', 'python'].includes(language)) {
+            return { missingDocMethods: [], missingDocTypes: [] };
+        }
+        const lines = code.split('\n');
+        const file = graph.ir.meta.file;
+        const missingDocMethods = [];
+        const missingDocTypes = [];
+        for (const type of graph.ir.types) {
+            // Skip the synthetic '<module>' type used to group top-level functions.
+            // It is not a real class/interface and requiring a doc comment on it
+            // produces misleading findings for every TypeScript/JavaScript file.
+            if (type.name === '<module>')
+                continue;
+            // Check type-level doc comment.
+            if (!hasDocCommentBefore(lines, type.start_line)) {
+                missingDocTypes.push(type);
+                ctx.addFinding({
+                    id: `missing-public-doc-${file}-${type.start_line}`,
+                    pass: this.name,
+                    category: this.category,
+                    rule_id: this.name,
+                    severity: 'low',
+                    level: 'note',
+                    message: `Missing doc comment on ${type.kind} \`${type.name}\``,
+                    file,
+                    line: type.start_line,
+                    fix: `Add a /** ... */ doc comment above \`${type.kind} ${type.name}\``,
+                });
+            }
+            // Check method-level doc comments for public methods.
+            for (const method of type.methods) {
+                if (!isPublicMethod(method, language))
+                    continue;
+                const documented = language === 'python'
+                    ? hasPythonDocstring(lines, method)
+                    : hasDocCommentBefore(lines, method.start_line);
+                if (!documented) {
+                    missingDocMethods.push({ type, method });
+                    ctx.addFinding({
+                        id: `missing-public-doc-${file}-${method.start_line}`,
+                        pass: this.name,
+                        category: this.category,
+                        rule_id: this.name,
+                        severity: 'low',
+                        level: 'note',
+                        message: `Missing doc comment on public method \`${type.name}.${method.name}\``,
+                        file,
+                        line: method.start_line,
+                        fix: `Add a /** ... */ doc comment above \`${method.name}\``,
+                    });
+                }
+            }
+        }
+        return { missingDocMethods, missingDocTypes };
+    }
+}
+//# sourceMappingURL=missing-public-doc-pass.js.map

package/dist/analysis/passes/missing-public-doc-pass.js.map

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

package/dist/analysis/passes/n-plus-one-pass.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Pass #45: n-plus-one (CWE-1049, category: performance)
+ *
+ * Detects calls to database or external-API methods that occur inside a loop
+ * body, producing N+1 round-trips instead of a single batch query.
+ *
+ * Detection uses two signals:
+ *   1. The call line falls inside a loop body identified by a CFG back-edge
+ *      (`graph.loopBodies()`).
+ *   2. The method name (and optionally its receiver) matches a curated set of
+ *      DB / HTTP / ORM patterns.
+ *
+ * Precision strategy:
+ *   - High-confidence method names (e.g. `executeQuery`, `findUnique`) are
+ *     flagged regardless of receiver.
+ *   - Medium-confidence names (e.g. `find`, `save`, `get`) require a receiver
+ *     that looks like a DB/HTTP client.
+ */
+import type { CallInfo } from '../../types/index.js';
+import type { AnalysisPass, PassContext } from '../../graph/analysis-pass.js';
+export interface NPlusOnePassResult {
+    /** Calls inside loop bodies that hit a DB or external API. */
+    loopDbCalls: CallInfo[];
+}
+export declare class NPlusOnePass implements AnalysisPass<NPlusOnePassResult> {
+    readonly name = "n-plus-one";
+    readonly category: "performance";
+    run(ctx: PassContext): NPlusOnePassResult;
+}

package/dist/analysis/passes/n-plus-one-pass.js

@@ -0,0 +1,100 @@
+/**
+ * Pass #45: n-plus-one (CWE-1049, category: performance)
+ *
+ * Detects calls to database or external-API methods that occur inside a loop
+ * body, producing N+1 round-trips instead of a single batch query.
+ *
+ * Detection uses two signals:
+ *   1. The call line falls inside a loop body identified by a CFG back-edge
+ *      (`graph.loopBodies()`).
+ *   2. The method name (and optionally its receiver) matches a curated set of
+ *      DB / HTTP / ORM patterns.
+ *
+ * Precision strategy:
+ *   - High-confidence method names (e.g. `executeQuery`, `findUnique`) are
+ *     flagged regardless of receiver.
+ *   - Medium-confidence names (e.g. `find`, `save`, `get`) require a receiver
+ *     that looks like a DB/HTTP client.
+ */
+/**
+ * Methods that strongly imply a DB query or external I/O, regardless of receiver.
+ * Only names with virtually no non-DB usage at this level of confidence.
+ */
+const HIGH_CONFIDENCE_DB_METHODS = new Set([
+    // JDBC / raw SQL
+    'executeQuery', 'executeUpdate', 'prepareStatement', 'prepareCall',
+    // Spring Data / JPA
+    'findById', 'findAll', 'saveAll', 'deleteById', 'existsById',
+    // Mongoose
+    'findByIdAndUpdate', 'findByIdAndDelete',
+    'findOneAndUpdate', 'findOneAndDelete',
+    'countDocuments', 'aggregate', 'distinct',
+    // Sequelize
+    'findByPk', 'findAndCountAll', 'bulkCreate', 'bulkUpdate',
+    // Prisma
+    'findFirst', 'findUnique', 'findMany', 'createMany', 'updateMany', 'deleteMany',
+    // Network
+    'fetch',
+]);
+/**
+ * Methods that may be DB/HTTP calls — flag only when the receiver looks like
+ * a database or HTTP client.
+ */
+const MEDIUM_CONFIDENCE_DB_METHODS = new Set([
+    'query', 'execute', 'find', 'findOne',
+    'save', 'create', 'update', 'delete', 'insert', 'upsert', 'remove',
+    'get', 'post', 'put', 'patch', 'request',
+    'load', 'lookup',
+]);
+/** Receiver names that indicate a DB or HTTP client. */
+const DB_OR_HTTP_RECEIVER = /^(db|conn|connection|pool|client|repo|repository|orm|em|entityManager|sequelize|mongoose|prisma|axios|http|https|api|svc|service|dao|store|cache|gql|graphql)/i;
+function isDbOrApiCall(call) {
+    if (HIGH_CONFIDENCE_DB_METHODS.has(call.method_name))
+        return true;
+    if (MEDIUM_CONFIDENCE_DB_METHODS.has(call.method_name)) {
+        return call.receiver != null && DB_OR_HTTP_RECEIVER.test(call.receiver);
+    }
+    return false;
+}
+export class NPlusOnePass {
+    name = 'n-plus-one';
+    category = 'performance';
+    run(ctx) {
+        const { graph } = ctx;
+        const file = graph.ir.meta.file;
+        const loops = graph.loopBodies();
+        if (loops.length === 0)
+            return { loopDbCalls: [] };
+        const loopDbCalls = [];
+        for (const call of graph.ir.calls) {
+            if (!isDbOrApiCall(call))
+                continue;
+            const line = call.location.line;
+            const loop = loops.find(l => line >= l.start_line && line <= l.end_line);
+            if (!loop)
+                continue;
+            loopDbCalls.push(call);
+            ctx.addFinding({
+                id: `n-plus-one-${file}-${line}`,
+                pass: this.name,
+                category: this.category,
+                rule_id: this.name,
+                cwe: 'CWE-1049',
+                severity: 'medium',
+                level: 'warning',
+                message: `N+1 query: \`${call.method_name}()\` is called inside a loop ` +
+                    `(loop lines ${loop.start_line}–${loop.end_line}) — consider batching`,
+                file,
+                line,
+                fix: `Move \`${call.method_name}()\` outside the loop and batch the operation`,
+                evidence: {
+                    loop_start: loop.start_line,
+                    loop_end: loop.end_line,
+                    receiver: call.receiver ?? undefined,
+                },
+            });
+        }
+        return { loopDbCalls };
+    }
+}
+//# sourceMappingURL=n-plus-one-pass.js.map

package/dist/analysis/passes/n-plus-one-pass.js.map

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

package/dist/analysis/passes/null-deref-pass.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Pass #20: null-deref (CWE-476, category: reliability)
+ *
+ * Detects variables that are explicitly assigned null/None/undefined and then
+ * used as a receiver (method call or field access) without an intervening
+ * null guard.
+ *
+ * Detection strategy:
+ *   1. Find DFG defs where the expression is an explicit null literal
+ *      (null / None / undefined).
+ *   2. For each such def, find all DFG uses via graph.usesOfDef().
+ *   3. For each use that occurs after the def in the same method and is used
+ *      as a receiver, check whether any line between def and use contains a
+ *      null-check for that variable.
+ *   4. Emit a finding if no guard is found.
+ *
+ * Scope is limited to the enclosing method to avoid cross-method FPs.
+ */
+import type { AnalysisPass, PassContext } from '../../graph/analysis-pass.js';
+export interface NullDerefResult {
+    /** Potential null-dereferences detected. */
+    potentialNullDerefs: Array<{
+        defLine: number;
+        useLine: number;
+        variable: string;
+    }>;
+}
+export declare class NullDerefPass implements AnalysisPass<NullDerefResult> {
+    readonly name = "null-deref";
+    readonly category: "reliability";
+    run(ctx: PassContext): NullDerefResult;
+}