pi-lens 3.7.1 → 3.8.2

package/commands/booboo.ts

@@ -24,6 +24,10 @@ import {
 import { RunnerTracker } from "../clients/runner-tracker.js";
 import { safeSpawn } from "../clients/safe-spawn.js";
 import { getSourceFiles } from "../clients/scan-utils.js";
+import {
+	collectSourceFiles,
+	getFilterStats,
+} from "../clients/source-filter.js";
 import { calculateSimilarity } from "../clients/state-matrix.js";
 import type { TodoScanner } from "../clients/todo-scanner.js";
 import { TreeSitterClient } from "../clients/tree-sitter-client.js";
@@ -89,6 +93,35 @@ export async function handleBooboo(
 	// Detect project type once for all runners
 	const isTsProject = nodeFs.existsSync(path.join(targetPath, "tsconfig.json"));
 
+	// Collect source files once with unified artifact filtering
+	// This ensures all scanners work on the same deduplicated file set
+	const sourceFiles = collectSourceFiles(targetPath);
+	const allFiles = collectSourceFiles(targetPath, {
+		extensions: [
+			".ts",
+			".tsx",
+			".js",
+			".jsx",
+			".mjs",
+			".cjs",
+			".py",
+			".go",
+			".rs",
+			".rb",
+		],
+	});
+	const filterStats = getFilterStats(allFiles, sourceFiles);
+
+	if (filterStats.skipped > 0) {
+		const byTypeStr = Object.entries(filterStats.byType)
+			.map(([ext, count]) => `${count} ${ext}`)
+			.join(", ");
+		// biome-ignore lint/suspicious/noConsole: CLI output
+		console.log(
+			`[lens-booboo] Filtered ${filterStats.skipped} build artifacts (${byTypeStr}), scanning ${filterStats.kept} source files`,
+		);
+	}
+
 	// Get available commands for the project
 	const availableCommands = getAvailableCommands(projectMeta);
 
@@ -390,9 +423,8 @@ export async function handleBooboo(
 		const results: import("../clients/complexity-client.js").FileComplexity[] =
 			[];
 		const aiSlopIssues: string[] = [];
-		const files = getSourceFiles(targetPath, isTsProject).filter(
-			shouldIncludeFile,
-		);
+		// Use pre-collected sourceFiles (already filtered for artifacts)
+		const files = sourceFiles.filter(shouldIncludeFile);
 
 		for (const fullPath of files) {
 			if (clients.complexity.isSupportedFile(fullPath)) {
@@ -937,40 +969,20 @@ export async function handleBooboo(
 			return { findings: 0, status: "skipped" };
 		}
 
-		// Detect TypeScript project - skip .js files in TS projects (compiled artifacts)
-		const isTsProject = nodeFs.existsSync(
-			path.join(targetPath, "tsconfig.json"),
-		);
-
 		const archViolations: Array<{ file: string; message: string }> = [];
-		const archScanDir = (dir: string) => {
-			for (const entry of nodeFs.readdirSync(dir, { withFileTypes: true })) {
-				const full = path.join(dir, entry.name);
-				if (entry.isDirectory()) {
-					if (EXCLUDED_DIRS.includes(entry.name)) continue;
-					archScanDir(full);
-				} else if (/\.(ts|tsx|js|jsx|py|go|rs)$/.test(entry.name)) {
-					if (isTestFile(full)) continue;
-					// In TS projects, skip .js files (they're compiled artifacts)
-					if (
-						isTsProject &&
-						/\.(js|jsx)$/.test(entry.name) &&
-						nodeFs.existsSync(full.replace(/\.(js|jsx)$/, ".ts"))
-					)
-						continue;
-					const relPath = path.relative(targetPath, full).replace(/\\/g, "/");
-					const content = nodeFs.readFileSync(full, "utf-8");
-					const lineCount = content.split("\n").length;
-					for (const v of clients.architect.checkFile(relPath, content)) {
-						archViolations.push({ file: relPath, message: v.message });
-					}
-					const sizeV = clients.architect.checkFileSize(relPath, lineCount);
-					if (sizeV)
-						archViolations.push({ file: relPath, message: sizeV.message });
-				}
+
+		// Use pre-collected sourceFiles (already filtered for artifacts and exclusions)
+		for (const fullPath of sourceFiles) {
+			if (isTestFile(fullPath)) continue;
+			const relPath = path.relative(targetPath, fullPath).replace(/\\/g, "/");
+			const content = nodeFs.readFileSync(fullPath, "utf-8");
+			const lineCount = content.split("\n").length;
+			for (const v of clients.architect.checkFile(relPath, content)) {
+				archViolations.push({ file: relPath, message: v.message });
 			}
-		};
-		archScanDir(targetPath);
+			const sizeV = clients.architect.checkFileSize(relPath, lineCount);
+			if (sizeV) archViolations.push({ file: relPath, message: sizeV.message });
+		}
 
 		if (archViolations.length > 0) {
 			summaryItems.push({

package/default-architect.yaml

@@ -1,141 +1,130 @@
 # .pi-lens/architect.yaml
-# Architectural rules for your project
-# Copy to your project root as .pi-lens/architect.yaml and customize.
+# Architectural rules for your project.
+# Copy to your project root as .pi-lens/architect.yaml and customise.
 #
-# Structure is language-agnostic — regex patterns in must_not are language-specific.
+# Patterns use JavaScript regex syntax (multiline mode enabled).
 #
-# IMPORTANT: Patterns are JavaScript regex syntax. Use single quotes for patterns
-# containing double quotes, and escape backslashes appropriately.
+# NOTE: Rules here are intentionally non-overlapping with pi-lens built-in runners:
+#   - Empty catch blocks  -> tree-sitter + ast-grep handle these
+#   - Hardcoded secrets   -> secrets scanner handles these
+#   - as any / :any       -> ast-grep no-any-type/no-as-any handle these
 
 version: "1.2"
 
-# =============================================================================
-# FILE SIZE LIMITS (per file type)
-# =============================================================================
+rules:
+
+  # ===========================================================================
+  # FILE SIZE LIMITS
+  # ===========================================================================
 
   # Services: focused, single-purpose modules
   - pattern: "**/services/**/*.ts"
     max_lines: 500
     must_not:
-      # TUNED: Was (8+ spaces, 5 lines), now (12+ spaces, 10 lines)
       - pattern: '(?:\s{12,}.*\n){10,}'
-        message: "Extreme nesting detected (6+ levels). Refactor into smaller functions."
+        message: "Extreme nesting (6+ levels) — refactor into smaller functions."
 
-  # Clients: can be larger but still bounded
+  # Clients/commands: can be larger but still bounded
   - pattern: "**/clients/**/*.ts|**/commands/**/*.ts"
     max_lines: 1000
     must_not:
-      # TUNED: Was (8+ spaces, 5 lines), now (12+ spaces, 10 lines)
       - pattern: '(?:\s{12,}.*\n){10,}'
-        message: "Extreme nesting detected (6+ levels). Refactor into smaller functions."
+        message: "Extreme nesting (6+ levels) — refactor into smaller functions."
 
-  # General limit for other files (higher than before)
+  # General source files
   - pattern: "**/*.{ts,tsx,js,jsx,py,go,rs}"
     max_lines: 3000
     must_not:
-      # TUNED: Was (8+ spaces, 5 lines), now (12+ spaces, 10 lines) for extreme nesting only
       - pattern: '(?:\s{12,}.*\n){10,}'
-        message: "Extreme nesting detected (6+ levels). Refactor into smaller functions."
+        message: "Extreme nesting (6+ levels) — refactor into smaller functions."
 
-  # Test files: more relaxed (structure is different)
+  # Test files: more relaxed
   - pattern: "**/*.test.ts|**/*.test.js|**/*.spec.ts|**/*.spec.js"
     max_lines: 5000
 
-# =============================================================================
-# LANGUAGE-AGNOSTIC RULES (The "Universal Truths")
-# =============================================================================
+  # ===========================================================================
+  # UNIVERSAL RULES
+  # ===========================================================================
 
-rules:
-  # --- CI & Environment Safety ---
+  # CI & cross-platform safety
   - pattern: "**/*.{ts,tsx,js,jsx,py,go,rs,java,cpp}"
     must_not:
       - pattern: '[a-zA-Z]:\\(?:Users|Program Files|Windows|Temp)\\[^\\]*'
         message: "No absolute Windows paths — breaks CI and cross-platform builds."
         fix: "Use path.join(__dirname, 'relative/path') or process.cwd()"
       - pattern: '/(?:home|Users|usr|etc|var)/[a-zA-Z0-9_-]+/'
-        message: "Potential absolute Unix path detected — use relative paths or path.join()."
+        message: "Absolute Unix path — use relative paths or path.join()."
         fix: "Use path.join(process.cwd(), 'relative/path') or path.resolve()"
       - pattern: 'https?://localhost:[0-9]+'
-        message: "No hardcoded localhost URLs — use environment variables or a config service."
+        message: "No hardcoded localhost URLs — use an environment variable."
         fix: "Use process.env.API_URL || 'http://localhost:3000'"
 
-  # --- Complexity & Technical Debt ---
+  # Technical debt
   - pattern: "**/*.{ts,tsx,js,jsx,py,go,rs}"
     must_not:
       - pattern: '(?:(?://|#).*\n){10,}'
-        message: "Large block of commented-out code detected. This is dead code — delete it and rely on Git history."
-        fix: "Delete the commented code. Git history preserves it if needed later."
+        message: "Large commented-out code block — delete it and rely on Git history."
+        fix: "Delete the commented code. Git preserves it if needed."
 
-  # --- Reliability & Fragility ---
-  - pattern: "**/*.{ts,tsx,js,jsx,py,go,rs}"
-    must_not:
-      - pattern: '(?:catch|except)\s*\(?.*?\)?\s*\{\s*\}'
-        message: "No empty catch/except blocks. Swallowing errors makes debugging impossible — at least log the error."
-        fix: |
-          console.error(`[context] Operation failed:`, err);
-          // or: throw err;
-          // or: return null;
-      - pattern: '\b(?:password|secret|api_?key|token|private_?key)\b\s*[:=]\s*(?:"|'')[^''"]{8,}(?:"|'')'
-        message: "No hardcoded secrets — use environment variables or a secrets manager."
-        fix: "Use process.env.SECRET_NAME and add to .env.example (not .env!)"
-
-# =============================================================================
-# JS/TS-SPECIFIC RULES (Node.js & Frontend)
-# =============================================================================
-
-  # --- Type Safety ---
-  - pattern: "**/*.{ts,tsx}"
-    must_not:
-      - pattern: ':\s*any\b|as\s+any\b'
-        message: "No 'any' types — use 'unknown' or define a proper interface to maintain type safety."
-        fix: |
-          // Instead of: x as any
-          x as unknown as SpecificType
-          // Or define proper interface and use it
-    must:
-      - "Use strict TypeScript mode"
-
-  # --- Configuration & IO ---
-  # REMOVED: no process.env rule - extensions and CLI tools need env access
-  # If you want this rule for your project, add it to your .pi-lens/architect.yaml:
-  # - pattern: "**/services/**/*.ts|**/domain/**/*.ts"
-  #   must_not:
-  #     - pattern: 'process\.env'
-  #       message: "Domain/Service logic must not read env vars directly — inject config."
+  # ===========================================================================
+  # JS/TS-SPECIFIC RULES
+  # ===========================================================================
 
-  # --- Async Patterns ---
-  # DISABLED: .then() rule was too aggressive - flagged all promise usage
-  # Only flag in specific contexts (3+ level chains) via tree-sitter instead
-  # - pattern: "**/*.{ts,tsx,js,jsx}"
-  #   must_not:
-  #     - pattern: '\.then\('
-  #       message: "Prefer async/await over .then() chains for better readability."
-
-  # --- Grep-ability & Agent Search ---
-  # Note: 'export default' is acceptable for entry points (index.ts)
+  # Deep relative imports hurt readability and agent code search
   - pattern: "**/*.{ts,tsx}"
     must_not:
-      - pattern: "from\\s+['\"]\.\./\.\./\.\./"
-        message: "Avoid deep relative imports (3+ levels) — use absolute imports (@app/...) for agent reasoning."
+      - pattern: "from\\s+['\"](\\.\\./){3,}"
+        message: "Deep relative import (3+ levels) — use path aliases instead."
+        fix: "Configure tsconfig paths: { '@app/*': ['src/*'] }"
 
-# =============================================================================
-# PYTHON-SPECIFIC RULES
-# =============================================================================
+  # ===========================================================================
+  # PYTHON-SPECIFIC RULES
+  # ===========================================================================
 
-  # --- Clean Python ---
   - pattern: "**/*.py"
     must_not:
       - pattern: 'print\('
-        message: "No print() statements in production code — use the 'logging' module."
+        message: "No print() in production code — use the 'logging' module."
       - pattern: 'global\s+[a-zA-Z_]'
-        message: "No 'global' keyword — global state makes code untestable and unpredictable."
+        message: "No 'global' keyword — global state makes code untestable."
       - pattern: 'def\s+[a-zA-Z0-9_]+\([^)]*=\s*\[\]'
-        message: "No mutable default arguments (e.g., x=[]). Use 'x=None' and initialize inside the function."
+        message: "Mutable default argument (x=[]) — use x=None and initialise inside."
+      - pattern: 'eval\(|exec\('
+        message: "No eval()/exec() — security risk and architectural anti-pattern."
+
+  # ===========================================================================
+  # AGENT-SPECIFIC ANTI-PATTERNS
+  # Catches common failure modes where agents scaffold but forget to implement.
+  # Test files are excluded by the architect runner (skipTestFiles: true).
+  # ===========================================================================
+
+  - pattern: "**/*.{ts,tsx,js,jsx}"
+    must_not:
+      - pattern: 'throw new Error\((?:"(?:not implemented|TODO|todo|Not implemented)"|''(?:not implemented|TODO|todo|Not implemented)'')\)'
+        message: "Stub not implemented — function body was scaffolded but never completed."
+        fix: "Implement the function body or remove the stub."
 
-  # --- Python Reliability ---
   - pattern: "**/*.py"
     must_not:
-      - pattern: 'except:\s*pass|except\s+Exception:\s*pass'
-        message: "Do not use bare 'except: pass'. Explicitly catch specific exceptions and log them."
-      - pattern: 'eval\(|exec\('
-        message: "No eval() or exec() — these are security risks and architectural anti-patterns."
+      - pattern: 'raise NotImplementedError'
+        message: "NotImplementedError stub — function was scaffolded but never completed."
+        fix: "Implement the function body."
+      - pattern: '^\s*\.\.\.\s*$'
+        message: "Bare ellipsis body — function was scaffolded but never completed."
+        fix: "Implement the function body."
+
+  # ===========================================================================
+  # PROJECT-SPECIFIC TEMPLATES (uncomment and customise)
+  # ===========================================================================
+
+  # Layer boundary enforcement — adjust paths to match your project:
+  # - pattern: "**/domain/**/*.ts|**/services/**/*.ts"
+  #   must_not:
+  #     - pattern: "from\\s+['\"].*/(controllers|routes|api)/"
+  #       message: "Domain/service layer must not import from API layer."
+  #
+  # No direct env access in domain layer:
+  # - pattern: "**/domain/**/*.ts"
+  #   must_not:
+  #     - pattern: 'process\.env'
+  #       message: "Domain logic must not read env vars — inject config via constructor."

package/docs/ARCHITECTURE.md

@@ -0,0 +1,74 @@
+# Caching Architecture
+
+pi-lens uses a multi-layer caching strategy to avoid redundant work across sessions.
+
+## Cache Layers
+
+### 1. Tool Availability Cache
+
+**Location:** `clients/tool-availability.ts`
+
+```
+Map<toolName, {available, version}>
+• Persisted for session lifetime
+• Refreshed on extension restart
+```
+
+Avoids repeated `which`/`where` calls for tools like `biome`, `ruff`, `pyright`.
+
+### 2. Dispatch Baselines (Delta Mode)
+
+**Location:** `clients/dispatch/dispatcher.ts`
+
+```
+Map<filePath, Diagnostic[]>
+• Cleared at turn start
+• Updated after each runner execution
+• Filters: only NEW issues shown
+```
+
+First edit shows all issues; subsequent edits only show issues that weren't there before.
+
+### 3. Client-Level Caches
+
+| Client | Cache | TTL | Purpose |
+|--------|-------|-----|---------|
+| **Knip** | `clients/cache-manager.ts` | 5 min | Dead code analysis |
+| **jscpd** | `clients/cache-manager.ts` | 5 min | Duplicate detection |
+| **Type Coverage** | In-memory | Session | `any` type percentage |
+| **Complexity** | In-memory | File-level | MI, cognitive complexity |
+
+### 4. Session Turn State
+
+**Location:** `clients/cache-manager.ts`
+
+Tracks per-turn state:
+- Modified files this turn
+- Modified line ranges per file
+- Import changes detected
+- Turn cycle counter (max 10)
+
+Used by:
+- jscpd: Only re-scan modified files
+- Madge: Only check deps if imports changed
+- Cycle detection: Prevents infinite fix loops
+
+### 5. Tree-sitter Caches
+
+| Component | Location | Strategy | Details |
+|-----------|----------|----------|---------|
+| **TreeCache** | `clients/tree-sitter-cache.ts` | SHA-256 content hash + mtime | Parsed ASTs cached by file content; 50-file LRU; mtime check for invalidation |
+| **Query Cache** | `clients/tree-sitter-client.ts` | In-memory Map | Compiled tree-sitter queries cached per language |
+| **Navigator** | `clients/tree-sitter-navigator.ts` | Runtime scope detection | Parent/sibling traversal, test block detection, try-catch detection |
+
+**TreeCache implementation:**
+- SHA-256 hashing of file content for cache keys
+- mtime tracking for fast invalidation checks
+- LRU eviction when cache exceeds 50 files
+- `incrementalUpdate()` API ready for full incremental parsing when old content is tracked
+
+## Cache Invalidation
+
+- **Tool caches:** Refreshed on extension restart
+- **File caches:** Invalidated by mtime change
+- **Turn state:** Reset at each turn start

package/docs/AST_GREP_RULES.md

@@ -0,0 +1,266 @@
+# AST-Grep Rules Reference
+
+pi-lens uses **ast-grep** for fast structural pattern matching across multiple languages. This document describes all 112 rules (56 unique patterns × 2 languages: TypeScript and JavaScript).
+
+## Overview
+
+**What ast-grep catches:**
+- **Security vulnerabilities** — Hardcoded secrets, SQL injection, unsafe regex, JWT without verification
+- **Runtime errors** — NaN comparison, discarded errors, unchecked throwing calls, TOCTOU
+- **Code quality** — Empty catch blocks, missing returns, long methods, deep nesting
+- **Best practices** — Strict equality, proper error handling, no debugger statements
+
+**How it works:**
+1. Patterns are written in YAML with AST matchers
+2. Runs via `@ast-grep/napi` (fast Rust core) or CLI ast-grep
+3. Severity determines blocking vs warning behavior
+4. Auto-fix available for some rules (applied by Biome/Ruff/ESLint, not ast-grep directly)
+
+---
+
+## Rule Categories
+
+### 🔴 Security (Blocking Errors)
+
+Rules that detect vulnerabilities exploitable by attackers or guaranteed runtime crashes.
+
+| Rule | Languages | What it catches | Severity |
+|------|-----------|-----------------|----------|
+| **no-hardcoded-secrets** | TS, JS | API keys, passwords, tokens hardcoded in source | 🔴 error |
+| **no-sql-in-code** | TS, JS | SQL queries built with string concatenation | 🔴 error |
+| **jwt-no-verify** | TS, JS | JWT verification without secret/key (accepts any token) | 🔴 error |
+| **weak-rsa-key** | TS, JS | RSA keys < 2048 bits (cryptographically weak) | 🔴 error |
+| **no-insecure-randomness** | TS, JS | `Math.random()` for security (predictable) | 🔴 error |
+| **no-inner-html** | TS, JS | `innerHTML` assignment (XSS risk) | 🔴 error |
+| **unchecked-sync-fs** | TS, JS | `fs.statSync/readFileSync` without try/catch | 🔴 error |
+| **unchecked-throwing-call** | TS, JS | `JSON.parse`, `new URL()`, `execSync` without try/catch | 🔴 error |
+| **unchecked-throwing-call-python** | Python | `open()`, `json.loads()` without try/except | 🔴 error |
+| **unchecked-throwing-call-ruby** | Ruby | `File.read`, `JSON.parse` without begin/rescue | 🔴 error |
+| **no-nan-comparison** | TS, JS | `x === NaN` (always false, use `Number.isNaN()`) | 🔴 error |
+| **no-discarded-error** | TS, JS | `new Error()` as standalone statement (forgot throw) | 🔴 error |
+| **toctou** | TS, JS | Time-of-check-time-of-use race conditions | 🔴 error |
+| **no-throw-string** | TS, JS | `throw "string"` (loses stack trace) | 🔴 error |
+| **no-prototype-builtins** | TS, JS | Calling prototype methods directly on objects | 🔴 error |
+
+### 🔴 Structural Safety (Blocking Errors)
+
+| Rule | Languages | What it catches | Severity |
+|------|-----------|-----------------|----------|
+| **empty-catch** | TS, JS | `catch {}` silently swallowing errors | 🔴 error |
+| **no-bare-except** | Python | `except:` catching all exceptions including SystemExit | 🔴 error |
+| **no-cond-assign** | TS, JS | `if (x = y)` assignment in condition | 🔴 error |
+| **no-constant-condition** | TS, JS | `if (true)` or always-true/false conditions | 🔴 error |
+| **no-constructor-return** | TS, JS | `return` statement in constructor | 🔴 error |
+| **no-async-promise-executor** | TS, JS | `new Promise(async () => {})` (error swallowing) | 🔴 error |
+| **no-await-in-promise-all** | TS, JS | `await` inside `Promise.all()` (sequentializes parallel work) | 🔴 error |
+| **no-compare-neg-zero** | TS, JS | `x === -0` (doesn't work as expected) | 🔴 error |
+| **no-comparison-to-none** | Python | `== None` instead of `is None` | 🔴 error |
+
+### 🟡 Code Quality (Warnings)
+
+| Rule | Languages | What it catches | Severity |
+|------|-----------|-----------------|----------|
+| **no-console** | TS, JS | `console.log` in production code | 🟡 warning |
+| **no-debugger** | TS, JS | `debugger` statements left in code | 🟡 warning |
+| **no-alert** | TS, JS | `alert()`, `confirm()`, `prompt()` (poor UX) | 🟡 warning |
+| **strict-equality** | TS, JS | `==` instead of `===` | 🟡 warning |
+| **no-await-in-loop** | TS, JS | Sequential await in loops (slow) | 🟡 warning |
+| **missed-concurrency** | TS, JS | Sequential awaits that could be parallel | 🟡 warning |
+| **no-as-any** | TS, JS | `as any` type assertions (unsafe) | 🟡 warning |
+| **no-any-type** | TS | `any` type usage (loses type safety) | 🟡 warning |
+| **long-method** | TS, JS | Functions > 50 lines | 🟡 warning |
+| **long-parameter-list** | TS, JS | Functions with > 5 parameters | 🟡 warning |
+| **nested-ternary** | TS, JS | Ternary nesting > 2 levels | 🟡 warning |
+| **large-class** | TS, JS | Classes > 300 lines | 🟡 warning |
+| **array-callback-return** | TS, JS | Missing return in array callbacks | 🔴 error |
+| **getter-return** | TS, JS | Getter without return statement | 🔴 error |
+| **no-case-declarations** | TS, JS | Variables declared in switch cases | 🟡 warning |
+| **no-array-constructor** | TS, JS | `new Array()` (inconsistent behavior) | 🟡 warning |
+| **jsx-boolean-short-circuit** | TS, JS | `{condition && <Component />}` (0 renders as 0) | 🔴 error |
+| **no-unsafe-optional-chaining** | TS, JS | `a?.b.c` where `a?.b` could be undefined | 🔴 error |
+| **no-unsafe-finally** | TS, JS | `return/throw/break/continue` in finally | 🔴 error |
+
+### 🟡 Python-Specific
+
+| Rule | What it catches | Severity |
+|------|-----------------|----------|
+| **no-bare-except** | `except:` without exception type | 🔴 error |
+| **no-comparison-to-none** | `== None` instead of `is None` | 🔴 error |
+
+---
+
+## Severity Philosophy
+
+| Level | Signal | Examples |
+|-------|--------|----------|
+| **error** | 🔴 STOP | Security bugs, runtime crashes, NaN comparison, unguarded throwing calls |
+| **warning** | 🟡 | Style issues, readability, performance hints, console/debugger statements |
+
+**Why severity matters:**
+- **Errors block the agent** — Must be fixed before proceeding
+- **Warnings accumulate** — Shown in `/lens-booboo` but don't block
+- **Delta tracking** — Only NEW issues shown after first write
+
+---
+
+## Rule Details
+
+### unchecked-throwing-call (Error)
+
+**Catches:** `JSON.parse()`, `new URL()`, `execSync()`, `spawnSync()` without try/catch
+
+**Why it matters:** These calls throw on invalid input. Without try/catch, they crash the process.
+
+**Pattern:**
+```yaml
+rule:
+  any:
+    - pattern: JSON.parse($INPUT)
+    - pattern: new URL($URL)
+    - pattern: execSync($CMD)
+  not:
+    inside:
+      kind: try_statement
+      stopBy: end  # Check all ancestors, not just immediate parent
+```
+
+**Fix:** Wrap in try/catch with proper error handling.
+
+---
+
+### no-hardcoded-secrets (Error)
+
+**Catches:** Hardcoded credentials in variable assignments
+
+**Matches:** Variable names matching credential patterns:
+- `password`, `passwd`, `pwd`
+- `secret`, `token`, `apiKey`, `api_secret`
+- `accessKey`, `privateKey`, `clientSecret`
+- `credentials`, `bearer`, `auth`
+
+**Pattern:**
+```yaml
+rule:
+  any:
+    - pattern: const $VAR = "$_"
+    - pattern: const $VAR = '$_'
+constraints:
+  VAR:
+    regex: "(password|secret|token|apiKey|...)"
+```
+
+**Fix:** Use environment variables: `const apiKey = process.env.API_KEY`
+
+---
+
+### no-nan-comparison (Error)
+
+**Catches:** `x === NaN` or `x == NaN`
+
+**Why it matters:** `NaN === NaN` is always `false`. Use `Number.isNaN(x)` instead.
+
+---
+
+### no-discarded-error (Error)
+
+**Catches:** `new Error("...")` as a standalone statement
+
+**Why it matters:** Creates an Error object but doesn't throw it. Usually means `throw` was forgotten.
+
+**Fix:** Change to `throw new Error("...")`
+
+---
+
+### toctou (Error)
+
+**Catches:** Time-of-check-time-of-use race conditions in file operations
+
+**Pattern:** `fs.existsSync(path)` followed by `fs.readFileSync(path)` — file could be modified between check and use.
+
+---
+
+### empty-catch (Error)
+
+**Catches:** `catch (e) { }` with empty body
+
+**Why it matters:** Swallows errors silently. Makes debugging impossible.
+
+**Fix:** Handle the error or remove try/catch if truly don't care.
+
+---
+
+### strict-equality (Warning)
+
+**Catches:** `==` and `!=` (loose equality)
+
+**Why it matters:** `0 == "0"` is true, `0 == []` is true, `"" == false` is true. Type coercion causes bugs.
+
+**Fix:** Use `===` and `!==` always.
+
+---
+
+### no-await-in-loop (Warning)
+
+**Catches:** `await` inside `for` loops
+
+**Why it matters:** Sequentializes operations that could run in parallel. Slow.
+
+**Fix:** Use `Promise.all(array.map(async item => ...))`
+
+---
+
+### missed-concurrency (Warning)
+
+**Catches:** Sequential independent awaits
+
+**Pattern:**
+```typescript
+const a = await fetchA();  // Sequential
+const b = await fetchB();  // Doesn't need a's result
+```
+
+**Fix:** `const [a, b] = await Promise.all([fetchA(), fetchB()])`
+
+---
+
+## JavaScript Coverage
+
+Most TypeScript rules have JavaScript equivalents (`-js.yml` suffix) because:
+1. Different AST node types (TypeScript has `type_annotation`, `interface`, etc.)
+2. JavaScript projects need the same protections
+3. TS and JS run in separate passes
+
+**Total rules:** 112 (56 unique patterns × 2 languages)
+
+---
+
+## Custom Rules
+
+Add your own rules to `.pi-lens/rules/`:
+
+```yaml
+# .pi-lens/rules/no-fetch-without-timeout.yml
+id: no-fetch-without-timeout
+language: typescript
+severity: warning
+message: "fetch() without timeout can hang indefinitely"
+rule:
+  pattern: fetch($URL)
+  not:
+    inside:
+      pattern: Promise.race([fetch($URL), $TIMEOUT])
+```
+
+**Tips:**
+- Use `$VAR` for single node capture
+- Use `$$$VAR` for multi-node capture  
+- Use `not: inside:` for negative context
+- Test with `ast-grep scan --rule your-rule.yml`
+
+---
+
+## References
+
+- [ast-grep documentation](https://ast-grep.github.io/)
+- [AST patterns guide](https://ast-grep.github.io/guide/rule-syntax.html)
+- Source: `rules/ast-grep-rules/rules/*.yml`