getdoorman 1.0.0

package/src/rules/scope-rules.js

@@ -0,0 +1,815 @@
+/**
+ * Scope-Aware Rules (SCOPE-*)
+ *
+ * These rules leverage the lightweight scope analyzer to make context-sensitive
+ * decisions: detecting patterns that only matter inside certain blocks,
+ * suppressing false positives in test files / comments / strings, and
+ * evaluating structural quality metrics (function length, nesting depth, etc.).
+ */
+
+import { analyzeScope, languageFromPath } from '../scope-analyzer.js';
+
+const JS_EXT = ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'];
+const isJS = (f) => JS_EXT.some(ext => f.endsWith(ext));
+
+const COMMENT_LINE = /^\s*(\/\/|#|\/\*|\*)/;
+
+// Cache scope analysis per file to avoid re-parsing
+function getScope(cache, filePath, content) {
+  if (!cache.has(filePath)) {
+    cache.set(filePath, analyzeScope(content, languageFromPath(filePath)));
+  }
+  return cache.get(filePath);
+}
+
+// Security middleware names
+const SECURITY_MIDDLEWARE = ['helmet', 'cors', 'csurf', 'express-rate-limit', 'rate-limiter-flexible'];
+const INPUT_VALIDATION_LIBS = ['joi', 'zod', 'yup', 'ajv', 'express-validator', 'class-validator'];
+const SECURITY_LIBS = [...SECURITY_MIDDLEWARE, ...INPUT_VALIDATION_LIBS, 'bcrypt', 'bcryptjs', 'argon2'];
+
+// Database call patterns
+const DB_CALL_PATTERN = /\b(?:\.query|\.execute|\.find|\.findOne|\.findMany|\.findAll|\.select|\.insert|\.update|\.delete|\.aggregate|\.raw|\.fetch|Model\.\w+|db\.\w+|collection\.\w+|cursor\.\w+)\s*\(/;
+
+// Sync fs operations
+const SYNC_FS_PATTERN = /\b(?:readFileSync|writeFileSync|appendFileSync|readdirSync|statSync|mkdirSync|existsSync|unlinkSync|renameSync|copyFileSync)\s*\(/;
+
+const rules = [
+
+  // ---------------------------------------------------------------
+  // SCOPE-AUTH-001: Route handler without auth middleware
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-AUTH-001',
+    category: 'security',
+    severity: 'high',
+    confidence: 'suggestion',
+    title: 'Route Handler Without Auth Middleware',
+    description: 'Express route handler detected with (req, res) parameters but no authentication middleware appears in the same router file.',
+    fix: { suggestion: 'Add authentication middleware (e.g., passport, express-jwt) to protect this route.' },
+    check({ files }) {
+      const findings = [];
+      const scopeCache = new Map();
+      for (const [path, content] of files) {
+        if (!isJS(path)) continue;
+        const scope = getScope(scopeCache, path, content);
+        if (scope.isTestFile) continue;
+
+        // Check if file has any auth-related imports or middleware references
+        const hasAuth = /\b(auth|authenticate|passport|jwt|verify[Tt]oken|isAuthenticated|requireAuth|ensureAuth)\b/.test(content);
+
+        for (const handler of scope.routeHandlers) {
+          if (handler.method === 'use') continue; // middleware registration
+          if (!hasAuth) {
+            findings.push({
+              ruleId: this.id, category: this.category, severity: this.severity,
+              title: this.title, description: this.description, confidence: this.confidence,
+              file: path, line: handler.startLine, fix: this.fix,
+            });
+          }
+        }
+      }
+      return findings;
+    },
+  },
+
+  // ---------------------------------------------------------------
+  // SCOPE-AUTH-002: Route handler without rate limiting
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-AUTH-002',
+    category: 'security',
+    severity: 'medium',
+    confidence: 'suggestion',
+    title: 'Route Handler Without Rate Limiting',
+    description: 'Express route handler without rate limiting middleware imported in the same file.',
+    fix: { suggestion: 'Add rate limiting middleware (e.g., express-rate-limit) to prevent abuse.' },
+    check({ files }) {
+      const findings = [];
+      const scopeCache = new Map();
+      for (const [path, content] of files) {
+        if (!isJS(path)) continue;
+        const scope = getScope(scopeCache, path, content);
+        if (scope.isTestFile) continue;
+
+        const hasRateLimit = scope.hasAnyImport(['express-rate-limit', 'rate-limiter-flexible']) ||
+                             /\brateLimit|rateLimiter|limiter\b/.test(content);
+
+        for (const handler of scope.routeHandlers) {
+          if (handler.method === 'use') continue;
+          if (!hasRateLimit) {
+            findings.push({
+              ruleId: this.id, category: this.category, severity: this.severity,
+              title: this.title, description: this.description, confidence: this.confidence,
+              file: path, line: handler.startLine, fix: this.fix,
+            });
+          }
+        }
+      }
+      return findings;
+    },
+  },
+
+  // ---------------------------------------------------------------
+  // SCOPE-ERR-001: Async function without try/catch
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-ERR-001',
+    category: 'reliability',
+    severity: 'medium',
+    confidence: 'suggestion',
+    title: 'Async Function Without try/catch',
+    description: 'Async function does not contain a try/catch block. Unhandled rejections may crash the process.',
+    fix: { suggestion: 'Wrap the function body in a try/catch block or use an error-handling middleware.' },
+    check({ files }) {
+      const findings = [];
+      const scopeCache = new Map();
+      for (const [path, content] of files) {
+        if (!isJS(path)) continue;
+        const scope = getScope(scopeCache, path, content);
+        if (scope.isTestFile) continue;
+
+        for (const fn of scope.functions) {
+          if (!fn.isAsync) continue;
+          if (fn.endLine - fn.startLine < 3) continue; // trivial one-liners
+
+          // Check if any try/catch exists inside the function
+          const hasTryCatch = scope.tryCatches.some(
+            tc => tc.tryStart >= fn.startLine && tc.tryStart <= fn.endLine
+          );
+          if (!hasTryCatch) {
+            findings.push({
+              ruleId: this.id, category: this.category, severity: this.severity,
+              title: this.title, description: this.description, confidence: this.confidence,
+              file: path, line: fn.startLine, fix: this.fix,
+            });
+          }
+        }
+      }
+      return findings;
+    },
+  },
+
+  // ---------------------------------------------------------------
+  // SCOPE-ERR-002: Promise chain without .catch()
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-ERR-002',
+    category: 'reliability',
+    severity: 'medium',
+    confidence: 'suggestion',
+    title: 'Promise Chain Without .catch()',
+    description: 'Promise chain using .then() without a corresponding .catch() handler.',
+    fix: { suggestion: 'Add a .catch() handler or use async/await with try/catch.' },
+    check({ files }) {
+      const findings = [];
+      const scopeCache = new Map();
+      for (const [path, content] of files) {
+        if (!isJS(path)) continue;
+        const scope = getScope(scopeCache, path, content);
+        if (scope.isTestFile) continue;
+
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+          const lineNum = i + 1;
+          if (scope.isInsideComment(lineNum) || scope.isInsideString(lineNum)) continue;
+          const line = lines[i];
+          if (/\.then\s*\(/.test(line)) {
+            // Look ahead up to 5 lines for .catch
+            let hasCatch = false;
+            for (let j = i; j < Math.min(i + 6, lines.length); j++) {
+              if (/\.catch\s*\(/.test(lines[j])) {
+                hasCatch = true;
+                break;
+              }
+            }
+            if (!hasCatch) {
+              findings.push({
+                ruleId: this.id, category: this.category, severity: this.severity,
+                title: this.title, description: this.description, confidence: this.confidence,
+                file: path, line: lineNum, fix: this.fix,
+              });
+            }
+          }
+        }
+      }
+      return findings;
+    },
+  },
+
+  // ---------------------------------------------------------------
+  // SCOPE-ERR-003: Empty catch block
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-ERR-003',
+    category: 'reliability',
+    severity: 'medium',
+    confidence: 'likely',
+    title: 'Empty catch Block',
+    description: 'Catch block is empty or contains only a comment. Errors are silently swallowed.',
+    fix: { suggestion: 'Log the error or re-throw it. Silent swallowing hides bugs.' },
+    check({ files }) {
+      const findings = [];
+      const scopeCache = new Map();
+      for (const [path, content] of files) {
+        if (!isJS(path)) continue;
+        const scope = getScope(scopeCache, path, content);
+        if (scope.isTestFile) continue;
+
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+          const lineNum = i + 1;
+          const trimmed = lines[i].trim();
+          // Match } catch (e) { } or catch(e) { }
+          if (/catch\s*\([^)]*\)\s*\{\s*\}/.test(trimmed)) {
+            findings.push({
+              ruleId: this.id, category: this.category, severity: this.severity,
+              title: this.title, description: this.description, confidence: this.confidence,
+              file: path, line: lineNum, fix: this.fix,
+            });
+            continue;
+          }
+          // Multi-line empty catch: catch(...) { \n }
+          if (/catch\s*\([^)]*\)\s*\{\s*$/.test(trimmed)) {
+            // Look at the next non-blank line
+            let nextContentLine = '';
+            for (let j = i + 1; j < Math.min(i + 3, lines.length); j++) {
+              const t = lines[j].trim();
+              if (t === '') continue;
+              nextContentLine = t;
+              break;
+            }
+            if (nextContentLine === '}' || nextContentLine.startsWith('//') && i + 2 < lines.length) {
+              // Check if the line after comment is }
+              if (nextContentLine === '}') {
+                findings.push({
+                  ruleId: this.id, category: this.category, severity: this.severity,
+                  title: this.title, description: this.description, confidence: this.confidence,
+                  file: path, line: lineNum, fix: this.fix,
+                });
+              }
+            }
+          }
+        }
+      }
+      return findings;
+    },
+  },
+
+  // ---------------------------------------------------------------
+  // SCOPE-TEST-001: Security-sensitive code in test file (suppress)
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-TEST-001',
+    category: 'security',
+    severity: 'info',
+    confidence: 'likely',
+    title: 'Security-Sensitive Pattern in Test File',
+    description: 'eval, exec, or raw SQL usage detected in a test file. This is expected for testing and should not be flagged as a vulnerability.',
+    check({ files }) {
+      // This rule returns nothing — it exists to document the suppression.
+      // Other scope rules already skip test files.
+      return [];
+    },
+  },
+
+  // ---------------------------------------------------------------
+  // SCOPE-TEST-002: Hardcoded credentials NOT in test file
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-TEST-002',
+    category: 'security',
+    severity: 'high',
+    confidence: 'likely',
+    title: 'Hardcoded Credentials Outside Test Code',
+    description: 'Hardcoded password, secret, or API key found in production code (not in a test file).',
+    fix: { suggestion: 'Use environment variables or a secrets manager instead of hardcoded credentials.' },
+    check({ files }) {
+      const findings = [];
+      const scopeCache = new Map();
+      const credPattern = /(?:password|passwd|secret|api[_-]?key|auth[_-]?token|access[_-]?token|private[_-]?key)\s*[:=]\s*['"][^'"]{4,}['"]/i;
+
+      for (const [path, content] of files) {
+        if (!isJS(path)) continue;
+        const scope = getScope(scopeCache, path, content);
+        if (scope.isTestFile) continue;
+
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+          const lineNum = i + 1;
+          if (scope.isInsideComment(lineNum) || scope.isInsideString(lineNum)) continue;
+          if (credPattern.test(lines[i])) {
+            findings.push({
+              ruleId: this.id, category: this.category, severity: this.severity,
+              title: this.title, description: this.description, confidence: this.confidence,
+              file: path, line: lineNum, fix: this.fix,
+            });
+          }
+        }
+      }
+      return findings;
+    },
+  },
+
+  // ---------------------------------------------------------------
+  // SCOPE-QUAL-001: Function exceeds 50 lines
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-QUAL-001',
+    category: 'quality',
+    severity: 'low',
+    confidence: 'definite',
+    title: 'Function Exceeds 50 Lines',
+    description: 'Long functions are harder to understand, test, and maintain.',
+    fix: { suggestion: 'Extract sub-operations into smaller helper functions.' },
+    check({ files }) {
+      const findings = [];
+      const scopeCache = new Map();
+      for (const [path, content] of files) {
+        if (!isJS(path)) continue;
+        const scope = getScope(scopeCache, path, content);
+        if (scope.isTestFile) continue;
+
+        for (const fn of scope.functions) {
+          const lineCount = fn.endLine - fn.startLine + 1;
+          if (lineCount > 50) {
+            findings.push({
+              ruleId: this.id, category: this.category, severity: this.severity,
+              title: this.title,
+              description: `Function "${fn.name}" is ${lineCount} lines long (limit: 50).`,
+              confidence: this.confidence,
+              file: path, line: fn.startLine, fix: this.fix,
+            });
+          }
+        }
+      }
+      return findings;
+    },
+  },
+
+  // ---------------------------------------------------------------
+  // SCOPE-QUAL-002: Function has more than 5 parameters
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-QUAL-002',
+    category: 'quality',
+    severity: 'low',
+    confidence: 'definite',
+    title: 'Function Has More Than 5 Parameters',
+    description: 'Functions with many parameters are hard to call correctly and suggest the need for an options object.',
+    fix: { suggestion: 'Use an options/config object parameter instead of many positional parameters.' },
+    check({ files }) {
+      const findings = [];
+      const scopeCache = new Map();
+      for (const [path, content] of files) {
+        if (!isJS(path)) continue;
+        const scope = getScope(scopeCache, path, content);
+        if (scope.isTestFile) continue;
+
+        for (const fn of scope.functions) {
+          if (fn.paramCount > 5) {
+            findings.push({
+              ruleId: this.id, category: this.category, severity: this.severity,
+              title: this.title,
+              description: `Function "${fn.name}" has ${fn.paramCount} parameters (limit: 5).`,
+              confidence: this.confidence,
+              file: path, line: fn.startLine, fix: this.fix,
+            });
+          }
+        }
+      }
+      return findings;
+    },
+  },
+
+  // ---------------------------------------------------------------
+  // SCOPE-QUAL-003: Nesting depth exceeds 4 levels
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-QUAL-003',
+    category: 'quality',
+    severity: 'low',
+    confidence: 'likely',
+    title: 'Excessive Nesting Depth',
+    description: 'Code nesting exceeds 4 levels, making it hard to follow.',
+    fix: { suggestion: 'Use early returns, extract helper functions, or use guard clauses to reduce nesting.' },
+    check({ files }) {
+      const findings = [];
+      const scopeCache = new Map();
+      const reported = new Set();
+
+      for (const [path, content] of files) {
+        if (!isJS(path)) continue;
+        const scope = getScope(scopeCache, path, content);
+        if (scope.isTestFile) continue;
+
+        for (let i = 0; i < scope.lineCount; i++) {
+          const lineNum = i + 1;
+          if (scope.isInsideComment(lineNum) || scope.isInsideString(lineNum)) continue;
+          if (scope.lineDepth[i] > 4) {
+            const fn = scope.getFunctionAt(lineNum);
+            const key = `${path}:${fn ? fn.name : 'global'}`;
+            if (!reported.has(key)) {
+              reported.add(key);
+              findings.push({
+                ruleId: this.id, category: this.category, severity: this.severity,
+                title: this.title,
+                description: `Nesting depth of ${scope.lineDepth[i]} at line ${lineNum}${fn ? ` in function "${fn.name}"` : ''}.`,
+                confidence: this.confidence,
+                file: path, line: lineNum, fix: this.fix,
+              });
+            }
+          }
+        }
+      }
+      return findings;
+    },
+  },
+
+  // ---------------------------------------------------------------
+  // SCOPE-QUAL-004: Class exceeds 300 lines
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-QUAL-004',
+    category: 'quality',
+    severity: 'low',
+    confidence: 'definite',
+    title: 'Class Exceeds 300 Lines',
+    description: 'Large classes often violate the Single Responsibility Principle.',
+    fix: { suggestion: 'Split the class into smaller, focused classes or use composition.' },
+    check({ files }) {
+      const findings = [];
+      const scopeCache = new Map();
+      for (const [path, content] of files) {
+        if (!isJS(path)) continue;
+        const scope = getScope(scopeCache, path, content);
+        if (scope.isTestFile) continue;
+
+        for (const cls of scope.classes) {
+          const lineCount = cls.endLine - cls.startLine + 1;
+          if (lineCount > 300) {
+            findings.push({
+              ruleId: this.id, category: this.category, severity: this.severity,
+              title: this.title,
+              description: `Class "${cls.name}" is ${lineCount} lines long (limit: 300).`,
+              confidence: this.confidence,
+              file: path, line: cls.startLine, fix: this.fix,
+            });
+          }
+        }
+      }
+      return findings;
+    },
+  },
+
+  // ---------------------------------------------------------------
+  // SCOPE-PERF-001: Database call inside a loop (N+1 query)
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-PERF-001',
+    category: 'performance',
+    severity: 'high',
+    confidence: 'likely',
+    title: 'Database Call Inside Loop (N+1 Query)',
+    description: 'A database query is executed inside a loop, causing N+1 query performance problems.',
+    fix: { suggestion: 'Batch the queries using WHERE IN, Promise.all, or eager loading.' },
+    check({ files }) {
+      const findings = [];
+      const scopeCache = new Map();
+      for (const [path, content] of files) {
+        if (!isJS(path)) continue;
+        const scope = getScope(scopeCache, path, content);
+        if (scope.isTestFile) continue;
+
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+          const lineNum = i + 1;
+          if (scope.isInsideComment(lineNum) || scope.isInsideString(lineNum)) continue;
+          if (scope.isInsideLoop(lineNum) && DB_CALL_PATTERN.test(lines[i])) {
+            findings.push({
+              ruleId: this.id, category: this.category, severity: this.severity,
+              title: this.title, description: this.description, confidence: this.confidence,
+              file: path, line: lineNum, fix: this.fix,
+            });
+          }
+        }
+      }
+      return findings;
+    },
+  },
+
+  // ---------------------------------------------------------------
+  // SCOPE-PERF-002: await inside a loop
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-PERF-002',
+    category: 'performance',
+    severity: 'medium',
+    confidence: 'likely',
+    title: 'await Inside Loop',
+    description: 'Using await inside a loop serializes async operations. Consider using Promise.all for parallel execution.',
+    fix: { suggestion: 'Collect promises and use Promise.all() instead of awaiting each one sequentially.' },
+    check({ files }) {
+      const findings = [];
+      const scopeCache = new Map();
+      for (const [path, content] of files) {
+        if (!isJS(path)) continue;
+        const scope = getScope(scopeCache, path, content);
+        if (scope.isTestFile) continue;
+
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+          const lineNum = i + 1;
+          if (scope.isInsideComment(lineNum) || scope.isInsideString(lineNum)) continue;
+          if (scope.isInsideLoop(lineNum) && /\bawait\s/.test(lines[i])) {
+            findings.push({
+              ruleId: this.id, category: this.category, severity: this.severity,
+              title: this.title, description: this.description, confidence: this.confidence,
+              file: path, line: lineNum, fix: this.fix,
+            });
+          }
+        }
+      }
+      return findings;
+    },
+  },
+
+  // ---------------------------------------------------------------
+  // SCOPE-PERF-003: Synchronous fs operation inside async function
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-PERF-003',
+    category: 'performance',
+    severity: 'medium',
+    confidence: 'likely',
+    title: 'Synchronous fs Operation in Async Function',
+    description: 'Synchronous file system calls block the event loop. Use async alternatives inside async functions.',
+    fix: { suggestion: 'Use fs.promises (readFile, writeFile, etc.) instead of synchronous variants.' },
+    check({ files }) {
+      const findings = [];
+      const scopeCache = new Map();
+      for (const [path, content] of files) {
+        if (!isJS(path)) continue;
+        const scope = getScope(scopeCache, path, content);
+        if (scope.isTestFile) continue;
+
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+          const lineNum = i + 1;
+          if (scope.isInsideComment(lineNum) || scope.isInsideString(lineNum)) continue;
+
+          const fn = scope.getFunctionAt(lineNum);
+          if (fn && fn.isAsync && SYNC_FS_PATTERN.test(lines[i])) {
+            findings.push({
+              ruleId: this.id, category: this.category, severity: this.severity,
+              title: this.title, description: this.description, confidence: this.confidence,
+              file: path, line: lineNum, fix: this.fix,
+            });
+          }
+        }
+      }
+      return findings;
+    },
+  },
+
+  // ---------------------------------------------------------------
+  // SCOPE-SEC-001: eval/exec not inside sandboxed context
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-SEC-001',
+    category: 'security',
+    severity: 'critical',
+    confidence: 'likely',
+    title: 'eval/exec Outside Sandboxed Context',
+    description: 'eval() or exec() used outside of a sandboxing function (vm.runInNewContext, sandbox, etc.).',
+    fix: { suggestion: 'Use a sandboxed execution environment (vm2, isolated-vm) instead of eval/exec.' },
+    check({ files }) {
+      const findings = [];
+      const scopeCache = new Map();
+      for (const [path, content] of files) {
+        if (!isJS(path)) continue;
+        const scope = getScope(scopeCache, path, content);
+        if (scope.isTestFile) continue;
+
+        const hasSandbox = /\b(vm\.runInNewContext|vm\.createContext|isolated-vm|vm2|sandbox)\b/.test(content);
+
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+          const lineNum = i + 1;
+          if (scope.isInsideComment(lineNum) || scope.isInsideString(lineNum)) continue;
+          if (/\b(eval|Function)\s*\(/.test(lines[i]) || /\bexec\s*\(/.test(lines[i])) {
+            if (!hasSandbox) {
+              findings.push({
+                ruleId: this.id, category: this.category, severity: this.severity,
+                title: this.title, description: this.description, confidence: this.confidence,
+                file: path, line: lineNum, fix: this.fix,
+              });
+            }
+          }
+        }
+      }
+      return findings;
+    },
+  },
+
+  // ---------------------------------------------------------------
+  // SCOPE-SEC-002: crypto.createHash outside hashing utility
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-SEC-002',
+    category: 'security',
+    severity: 'low',
+    confidence: 'suggestion',
+    title: 'crypto.createHash Outside Hashing Utility',
+    description: 'Direct use of crypto.createHash should be centralized in a utility function for consistency and to ease algorithm migration.',
+    fix: { suggestion: 'Wrap hashing in a dedicated utility function (e.g., hashPassword, computeHash).' },
+    check({ files }) {
+      const findings = [];
+      const scopeCache = new Map();
+      for (const [path, content] of files) {
+        if (!isJS(path)) continue;
+        const scope = getScope(scopeCache, path, content);
+        if (scope.isTestFile) continue;
+
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+          const lineNum = i + 1;
+          if (scope.isInsideComment(lineNum) || scope.isInsideString(lineNum)) continue;
+          if (/crypto\.createHash\s*\(/.test(lines[i])) {
+            const fn = scope.getFunctionAt(lineNum);
+            const isInHashUtil = fn && /hash/i.test(fn.name);
+            if (!isInHashUtil) {
+              findings.push({
+                ruleId: this.id, category: this.category, severity: this.severity,
+                title: this.title, description: this.description, confidence: this.confidence,
+                file: path, line: lineNum, fix: this.fix,
+              });
+            }
+          }
+        }
+      }
+      return findings;
+    },
+  },
+
+  // ---------------------------------------------------------------
+  // SCOPE-IMPORT-001: Security middleware imported but not used
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-IMPORT-001',
+    category: 'security',
+    severity: 'medium',
+    confidence: 'likely',
+    title: 'Security Middleware Imported But Not Used',
+    description: 'A security middleware package (helmet, cors, csurf) is imported but never called in the file.',
+    fix: { suggestion: 'Call the imported middleware with app.use() to activate it.' },
+    check({ files }) {
+      const findings = [];
+      const scopeCache = new Map();
+      for (const [path, content] of files) {
+        if (!isJS(path)) continue;
+        const scope = getScope(scopeCache, path, content);
+        if (scope.isTestFile) continue;
+
+        for (const mw of SECURITY_MIDDLEWARE) {
+          if (scope.hasImport(mw)) {
+            // Check if actually used (called) beyond the import line
+            const importLine = scope.imports.find(imp => imp.module === mw)?.line || 0;
+            const name = mw.replace(/-([a-z])/g, (_, c) => c.toUpperCase()); // camelCase
+            const usagePattern = new RegExp(`\\b(?:${name}|${mw.replace(/-/g, '')})\\s*\\(`);
+            let used = false;
+            const lines = content.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+              if (i + 1 === importLine) continue; // skip the import line itself
+              if (usagePattern.test(lines[i])) { used = true; break; }
+            }
+            // Also check for app.use(name) pattern
+            if (!used) {
+              const usePattern = new RegExp(`app\\.use\\s*\\(.*${name}|app\\.use\\s*\\(.*${mw.replace(/-/g, '')}`);
+              used = usePattern.test(content);
+            }
+            if (!used) {
+              findings.push({
+                ruleId: this.id, category: this.category, severity: this.severity,
+                title: this.title,
+                description: `"${mw}" is imported but never activated. Call it with app.use().`,
+                confidence: this.confidence,
+                file: path, line: importLine, fix: this.fix,
+              });
+            }
+          }
+        }
+      }
+      return findings;
+    },
+  },
+
+  // ---------------------------------------------------------------
+  // SCOPE-IMPORT-002: No input validation library in Express app
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-IMPORT-002',
+    category: 'security',
+    severity: 'medium',
+    confidence: 'suggestion',
+    title: 'No Input Validation Library in Express App',
+    description: 'Express route file without any input validation library (joi, zod, yup, express-validator).',
+    fix: { suggestion: 'Add input validation using joi, zod, yup, or express-validator to validate request data.' },
+    check({ files }) {
+      const findings = [];
+      const scopeCache = new Map();
+      for (const [path, content] of files) {
+        if (!isJS(path)) continue;
+        const scope = getScope(scopeCache, path, content);
+        if (scope.isTestFile) continue;
+        if (scope.routeHandlers.length === 0) continue;
+
+        const hasValidation = scope.hasAnyImport(INPUT_VALIDATION_LIBS);
+        if (!hasValidation) {
+          findings.push({
+            ruleId: this.id, category: this.category, severity: this.severity,
+            title: this.title, description: this.description, confidence: this.confidence,
+            file: path, line: 1, fix: this.fix,
+          });
+        }
+      }
+      return findings;
+    },
+  },
+
+  // ---------------------------------------------------------------
+  // SCOPE-COMMENT-001: TODO/FIXME/HACK in exported function
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-COMMENT-001',
+    category: 'quality',
+    severity: 'low',
+    confidence: 'likely',
+    title: 'TODO/FIXME/HACK in Exported Function',
+    description: 'Production debt: TODO, FIXME, or HACK comment found inside an exported function.',
+    fix: { suggestion: 'Resolve the TODO/FIXME before shipping or create a tracked issue.' },
+    check({ files }) {
+      const findings = [];
+      const scopeCache = new Map();
+      const todoPattern = /\b(TODO|FIXME|HACK|XXX)\b/;
+
+      for (const [path, content] of files) {
+        if (!isJS(path)) continue;
+        const scope = getScope(scopeCache, path, content);
+        if (scope.isTestFile) continue;
+
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+          const lineNum = i + 1;
+          if (!todoPattern.test(lines[i])) continue;
+          if (scope.isExported(lineNum)) {
+            findings.push({
+              ruleId: this.id, category: this.category, severity: this.severity,
+              title: this.title, description: this.description, confidence: this.confidence,
+              file: path, line: lineNum, fix: this.fix,
+            });
+          }
+        }
+      }
+      return findings;
+    },
+  },
+
+  // ---------------------------------------------------------------
+  // SCOPE-COMMENT-002: Security-related TODO comment
+  // ---------------------------------------------------------------
+  {
+    id: 'SCOPE-COMMENT-002',
+    category: 'security',
+    severity: 'high',
+    confidence: 'likely',
+    title: 'Security-Related TODO Comment',
+    description: 'A comment explicitly mentions missing security measures (auth, validation, encryption, sanitization).',
+    fix: { suggestion: 'Implement the security measure described in the TODO comment before deploying.' },
+    check({ files }) {
+      const findings = [];
+      const scopeCache = new Map();
+      const secTodoPattern = /(?:TODO|FIXME|HACK|XXX)\s*:?\s*.*\b(auth|authenticat|authoriz|validat|sanitiz|encrypt|secur|csrf|xss|inject|permission|access.control|rate.limit)/i;
+
+      for (const [path, content] of files) {
+        if (!isJS(path)) continue;
+        const scope = getScope(scopeCache, path, content);
+        if (scope.isTestFile) continue;
+
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+          const lineNum = i + 1;
+          if (secTodoPattern.test(lines[i])) {
+            findings.push({
+              ruleId: this.id, category: this.category, severity: this.severity,
+              title: this.title, description: this.description, confidence: this.confidence,
+              file: path, line: lineNum, fix: this.fix,
+            });
+          }
+        }
+      }
+      return findings;
+    },
+  },
+];
+
+export default rules;