octocode-cli 1.2.6 → 1.2.8

package/skills/octocode-code-engineer/references/ast-tree-search.md

@@ -0,0 +1,151 @@
+# AST Tree Search
+
+Use `ast/tree-search.js` to inspect the generated `ast-trees.txt` artifact from one specific scan.
+
+This is the canonical way to read AST snapshot output for agents because it keeps the search pinned to the current scan and bounds noisy output by default.
+
+## When to Use It
+
+- use it after reading `summary.md` when you want fast structure-first triage
+- use it before `ast/search.js` when you are still deciding which file deserves deeper source-level inspection
+- use it to narrow by node kind, file, or section without accidentally reading a different scan
+
+Do not use it as proof of live-code behavior. After artifact triage, validate important claims with Octocode local and LSP tools, or with `ast/search.js` for structural confirmation.
+
+## What `ast-trees.txt` Looks Like
+
+Each file gets a `## package — path` header. Nodes are `Kind[startLine:endLine]`, nesting = indentation. Truncated subtrees end with `...`.
+
+```
+## my-package — src/services/storage.ts
+SourceFile[1:152]
+  ImportDeclaration[1:3]
+  FunctionDeclaration[10:45]
+    Block[11:44]
+      IfStatement[12:20] ...
+      ReturnStatement[43]
+  ExportDeclaration[50:52]
+```
+
+This tells you: `storage.ts` has a function spanning lines 10-45 with a conditional inside it. Use this to decide which files and functions deserve source-level inspection.
+
+## Usage
+
+```bash
+node <SKILL_DIR>/scripts/ast/tree-search.js [options]
+```
+
+Core options:
+
+- `--input, -i <path>`: `ast-trees.txt`, a timestamped scan directory, or the scan root
+- `--kind, -k <kind>`: match node kinds such as `function_declaration` or `ClassDeclaration`
+- `--pattern, -p <regex>`: regex against AST tree lines
+- `--file <regex>`: filter to section file paths that match the regex
+- `--section <regex>`: filter to section headers that match the regex
+- `--limit <n>`: default `50`; use `0` for all matches
+- `--context, -C <n>`: include surrounding lines
+- `--json`: machine-readable output
+- `--ignore-case`: case-insensitive matching
+
+## Input Resolution
+
+The `-i` flag accepts three kinds of input, resolved automatically:
+
+| Input | What happens | Selection mode |
+|-------|-------------|----------------|
+| Path to `ast-trees.txt` file | Uses that file directly | `direct-file` |
+| Path to a scan directory (e.g., `.octocode/scan/2026-03-19T00-01-19-468Z`) | Looks for `ast-trees.txt` inside it | `scan-dir` |
+| Path to scan root (e.g., `.octocode/scan`) | Finds the latest timestamped directory with an `ast-trees.txt` | `latest-scan` |
+
+Default when `-i` is omitted: `.octocode/scan` (resolves to latest scan automatically).
+
+## Recommended Flow
+
+1. Start from `<CURRENT_SCAN>/ast-trees.txt` or just pass `-i .octocode/scan` for the latest.
+2. Run a bounded query with `--limit 25` or smaller.
+3. Narrow with `--file` or `--section` once you know the suspicious area.
+4. Switch to `ast/search.js` when you need source-level structural matching.
+5. Validate final claims with Octocode local and LSP tools.
+
+## Examples
+
+```bash
+# Find all function declarations (latest scan)
+node <SKILL_DIR>/scripts/ast/tree-search.js -i .octocode/scan -k function_declaration --limit 25
+
+# Find classes in a specific file
+node <SKILL_DIR>/scripts/ast/tree-search.js -i <CURRENT_SCAN>/ast-trees.txt --file 'src/report' -k class_declaration --limit 10
+
+# Find control flow nodes
+node <SKILL_DIR>/scripts/ast/tree-search.js -i <CURRENT_SCAN>/ast-trees.txt -p 'IfStatement|SwitchStatement|ForStatement|WhileStatement' --limit 25
+
+# JSON output for programmatic use
+node <SKILL_DIR>/scripts/ast/tree-search.js -i <CURRENT_SCAN>/ast-trees.txt --section 'src/services' -k function_declaration --json
+
+# With context lines to see surrounding tree structure
+node <SKILL_DIR>/scripts/ast/tree-search.js -i .octocode/scan -k function_declaration -C 2 --limit 10
+```
+
+## Output
+
+### Text (default)
+
+```
+AST tree search: kind=function_declaration
+Requested input: /path/to/.octocode/scan
+Selected AST file: /path/to/.octocode/scan/2026-03-19T00-01-19-468Z/ast-trees.txt (latest-scan)
+Matches: 42 total, showing 10 (limit 10)
+Matched files: 5
+
+-- my-package — src/services/storage.ts --
+  L14 (src/services/storage.ts)    FunctionDeclaration[10:45]
+  L68 (src/services/storage.ts)    FunctionDeclaration[50:80]
+```
+
+### Text with `--context 2`
+
+```
+-- my-package — src/services/storage.ts --
+       12 |   ImportDeclaration[1:3]
+       13 |   ExportDeclaration[5:8]
+ >     14 |   FunctionDeclaration[10:45]
+       15 |     ExportKeyword[10]
+       16 |     Identifier[10]
+```
+
+### JSON (`--json`)
+
+```json
+{
+  "requestedInput": "/path/to/.octocode/scan",
+  "inputFile": "/path/to/.octocode/scan/2026-03-19T.../ast-trees.txt",
+  "selectionMode": "latest-scan",
+  "query": "kind=function_declaration",
+  "limit": 25,
+  "totalMatches": 42,
+  "returnedMatches": 25,
+  "truncated": true,
+  "uniqueFiles": 5,
+  "matches": [{
+    "section": "my-package — src/services/storage.ts",
+    "file": "src/services/storage.ts",
+    "lineNumber": 14,
+    "line": "  FunctionDeclaration[10:45]",
+    "context": [{ "lineNumber": 14, "line": "  FunctionDeclaration[10:45]" }]
+  }]
+}
+```
+
+Use `totalMatches` vs `returnedMatches` to know if results are truncated. Use `selectionMode` to confirm which scan was selected.
+
+## Difference from `ast/search.js`
+
+| | `ast/tree-search.js` | `ast/search.js` |
+|---|---|---|
+| **Searches** | Generated `ast-trees.txt` artifact | Actual source files on disk |
+| **Powered by** | Regex / kind matching on text | `@ast-grep/napi` structural matching |
+| **Input** | `-i <scan-path>` | `--root <source-dir>` |
+| **Best for** | Quick triage — find where to look | Proof — confirm a code pattern exists |
+| **Proves behavior** | No — artifact only | Partial — structural shape, not runtime |
+
+Use `ast/tree-search.js` to decide where to look. Use `ast/search.js` to prove a source-level structural pattern exists.

package/skills/octocode-code-engineer/references/cli-reference.md

@@ -0,0 +1,167 @@
+# CLI Reference
+
+```bash
+node <SKILL_DIR>/scripts/index.js [flags]
+```
+
+Output goes to `.octocode/scan/<timestamp>/` by default. Results are cached — subsequent runs skip unchanged files (~4x faster).
+
+---
+
+## CLI Presets
+
+| Situation | Flags |
+|---|---|
+| Default scan | _(none)_ |
+| Analyze different repo | `--root /path/to/other/repo` |
+| Legacy single-file output | `--out path/to/report.json` |
+| Scope to one package | `--scope=packages/my-package` |
+| Scope to a directory | `--scope=packages/my-package/src/tools` |
+| Scope to a single file | `--scope=packages/my-package/src/session.ts` |
+| Scope to a function | `--scope=packages/my-package/src/session.ts:initSession` |
+| Scope to multiple areas | `--scope=packages/foo/src/tools,packages/bar/src/ui` |
+| Architecture only | `--features=architecture` |
+| Code quality only | `--features=code-quality` |
+| Dead code only | `--features=dead-code` |
+| Security only | `--features=security` |
+| Test quality only | `--features=test-quality --include-tests` |
+| Single category | `--features=cognitive-complexity` |
+| Mix pillars + categories | `--features=dead-code,dependency-cycle` |
+| Everything except X | `--exclude=architecture` |
+| Exclude specific categories | `--exclude=dead-export,magic-number` |
+| Cap findings (diverse) | `--findings-limit 500` |
+| Cap findings (pure severity) | `--findings-limit 500 --no-diversify` |
+| Include tests | `--include-tests` |
+| Architecture graph | `--graph` |
+| Advanced graph overlays | `--graph --graph-advanced` |
+| Flow enrichment | `--flow` |
+| Suppress AST tree output | `--no-tree` |
+| Strict complexity | `--critical-complexity-threshold 20 --cognitive-complexity-threshold 10` |
+| Strict type safety | `--any-threshold 0` |
+| Strict maintainability | `--maintainability-index-threshold 30 --halstead-effort-threshold 200000` |
+| Layer enforcement | `--layer-order ui,service,repository` |
+| Sensitive flow dups | `--flow-dup-threshold 2 --min-flow-statements 4` |
+| Diverse top recs | `--max-recs-per-category 1` |
+| Enable semantic analysis | `--semantic` |
+| Semantic + scope combo | `--semantic --scope=packages/my-package` |
+| Only semantic categories | `--semantic --features=unused-parameter,shotgun-surgery` |
+| Deep hierarchy threshold | `--semantic --type-hierarchy-threshold 6` |
+| Detect near-clones | `--similarity-threshold 0.8` |
+| Strict security | `--secret-entropy-threshold 4.0 --secret-min-length 16` |
+| Strict test quality | `--mock-threshold 5 --include-tests --features=test-quality` |
+| Force full re-parse | `--no-cache` |
+| Clear cache | `--clear-cache` |
+| JSON to stdout | `--json` |
+
+---
+
+## Flag Details
+
+`--scope` focuses on specific paths (comma-separated, relative to root). Use `file:symbol` syntax to drill into a specific function or exported variable — only findings whose line range overlaps with that symbol are returned. The full dependency graph is still built so architecture findings involving scoped files are reported. Combinable with `--features`/`--exclude`.
+
+`--features` and `--exclude` are mutually exclusive. Both accept pillar names (`architecture`, `code-quality`, `dead-code`, `security`, `test-quality`) and individual category names, comma-separated.
+
+`--semantic` enables TypeChecker + LanguageService analysis (additional categories). Off by default since it adds ~3-5s. Semantic categories require `--semantic` to appear in results.
+
+`--out` changes the output destination. If the path ends with `.json`, writes a single monolithic file (legacy mode). Otherwise, writes to the given directory instead of the default timestamped directory.
+
+`--parser` selects the parse engine: `auto` (default — uses tree-sitter with TS fallback), `typescript` (TS compiler only), or `tree-sitter` (tree-sitter only).
+
+---
+
+## All Flags Reference
+
+### Core
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--root <path>` | cwd | Analyze a different repo root |
+| `--out <path>` | `.octocode/scan/<ts>/` | Output path. Ends in `.json` → single-file legacy mode |
+| `--json` | off | Print report JSON to stdout |
+| `--include-tests` | off | Include `*.test.*` and `*.spec.*` files |
+| `--scope=X,Y,Z` | _(all files)_ | Limit to specific paths/files/functions (comma-separated) |
+| `--features=X,Y,Z` | _(all)_ | Run only selected pillars/categories |
+| `--exclude=X,Y,Z` | _(none)_ | Exclude specific pillars/categories (mutually exclusive with `--features`) |
+| `--findings-limit N` | no limit | Cap total findings in report |
+| `--graph` | off | Emit Mermaid dependency graph (`graph.md`) |
+| `--graph-advanced` | off | Enable SCC clusters, chokepoints, package graph hotspots, and advanced architecture findings |
+| `--flow` | off | Enable lightweight flow enrichment such as `cfgFlags`, `flowTrace`, and richer evidence metadata |
+| `--emit-tree` | **on** | Force include AST tree blocks in output |
+| `--no-tree` | — | Suppress AST tree output (`ast-trees.txt`) |
+| `--parser <engine>` | `auto` | Parse engine: `auto`, `typescript`, `tree-sitter` |
+| `--semantic` | off | Enable semantic analysis (TypeChecker + LanguageService) |
+| `--no-diversify` | off | Disable category-aware diversification when truncating. By default `--findings-limit` interleaves categories so the capped list is diverse. Use this for pure severity ordering. |
+| `--no-cache` | off | Disable incremental cache; re-parse all files |
+| `--clear-cache` | — | Delete the analysis cache and exit (no scan) |
+| `--all` | off | Enable all features: `--include-tests --semantic` |
+| `--help`, `-h` | — | Show help message |
+
+### Thresholds — Architecture
+
+| Flag | Default | Controls |
+|------|---------|----------|
+| `--coupling-threshold N` | 15 | Ca+Ce threshold for `high-coupling` |
+| `--fan-in-threshold N` | 20 | Fan-in threshold for `god-module-coupling` |
+| `--fan-out-threshold N` | 15 | Fan-out threshold for `god-module-coupling` |
+| `--layer-order <layers>` | _(none)_ | Comma-separated layer names for violation detection |
+| `--deep-link-topn N` | 12 | Max critical dependency paths to report |
+
+### Thresholds — Code Quality
+
+| Flag | Default | Controls |
+|------|---------|----------|
+| `--critical-complexity-threshold N` | 30 | Complexity for HIGH findings + critical path weighting |
+| `--cognitive-complexity-threshold N` | 15 | Cognitive complexity threshold |
+| `--cyclomatic-density-threshold N` | 0.5 | CC/LOC ratio threshold |
+| `--halstead-effort-threshold N` | 500000 | Halstead effort threshold |
+| `--maintainability-index-threshold N` | 20 | MI below this triggers a finding (0-100 scale) |
+| `--parameter-threshold N` | 5 | Max function parameters before flagging |
+| `--any-threshold N` | 5 | Max `any` type usages per file |
+| `--magic-number-threshold N` | 3 | Max magic number occurrences per file |
+| `--god-module-statements N` | 500 | Statement threshold for `god-module` |
+| `--god-module-exports N` | 20 | Export threshold for `god-module` |
+| `--god-function-statements N` | 100 | Statement threshold for `god-function` |
+| `--min-function-statements N` | 6 | Min function body statements for duplicate matching |
+| `--min-flow-statements N` | 6 | Min control-flow statements for duplicate matching |
+| `--flow-dup-threshold N` | 3 | Min occurrences for a repeated flow to become a finding |
+| `--similarity-threshold N` | 0.85 | Jaccard similarity threshold for near-clone detection |
+| `--max-recs-per-category N` | 2 | Max findings per category in top recommendations |
+
+### Thresholds — Semantic (require `--semantic`)
+
+| Flag | Default | Controls |
+|------|---------|----------|
+| `--type-hierarchy-threshold N` | 4 | Max inheritance depth before flagging |
+| `--override-chain-threshold N` | 3 | Max method override depth before flagging |
+
+### Thresholds — Security
+
+| Flag | Default | Controls |
+|------|---------|----------|
+| `--secret-entropy-threshold N` | 4.5 | Shannon entropy threshold for high-entropy string detection |
+| `--secret-min-length N` | 20 | Min string length for entropy-based secret detection |
+
+### Thresholds — Test Quality
+
+| Flag | Default | Controls |
+|------|---------|----------|
+| `--mock-threshold N` | 10 | Max mock/spy calls per test file before flagging |
+
+### Output Tuning
+
+| Flag | Default | Controls |
+|------|---------|----------|
+| `--tree-depth N` | 4 | AST tree depth when tree snapshots are emitted |
+| `--barrel-symbol-threshold N` | 30 | Re-export count threshold for `barrel-explosion` |
+
+---
+
+## Drill-Down Workflow
+
+```
+1. Full scan                     → identify hotspots from summary.md
+2. --scope=critical/area         → deep-dive into the worst package/directory
+3. --scope=file.ts               → investigate a single file's findings
+4. --scope=file.ts:functionName  → drill into a specific function or variable
+5. Fix → re-scan with scope      → verify finding count drops
+```

package/skills/octocode-code-engineer/references/concepts.md

@@ -0,0 +1,107 @@
+# Concepts — Metric Definitions
+
+## Instability (SDP)
+
+**Formula**: `I = Ce / (Ca + Ce)` where Ca = inbound (afferent) coupling, Ce = outbound (efferent) coupling.
+
+**Range**: 0 (maximally stable) to 1 (maximally unstable).
+
+**Threshold**: An SDP violation fires when a stable module (I < 0.5) depends on a more unstable module with delta > 0.15. Delta > 0.3 = high severity.
+
+**Interpretation**: I=0 means everything depends on this module and it depends on nothing — changing it breaks many consumers. I=1 means it depends on many modules but nothing depends on it — safe to change. Violations mean a hard-to-change module depends on an easy-to-change one, creating fragility.
+
+**Example**: Module A (I=0.2, 8 importers, 2 imports) depends on module B (I=0.8, 1 importer, 4 imports). Delta=0.6. Fix: extract an interface in A that B implements.
+
+## Cognitive Complexity
+
+**Formula**: Each `if`/`for`/`while`/`switch`/`catch`/`&&`/`||` adds +1. Each nesting level adds +1 more per construct inside it.
+
+**Default threshold**: 15. Above 15 = flagged.
+
+**Interpretation**: Unlike cyclomatic complexity, cognitive complexity penalizes deeply nested code much more heavily. A flat chain of 10 `if` statements scores 10, but 5 nested `if` blocks score 5+4+3+2+1=15.
+
+**Example**: A function with cognitive complexity 42 has deeply nested branches. Target: refactor to <15 by extracting guard clauses, breaking into helper functions, or using early returns.
+
+## Halstead Metrics
+
+**Formula**: Volume = Length × log₂(Vocabulary). Effort = Volume × Difficulty. Difficulty = (distinctOperators/2) × (totalOperands/distinctOperands).
+
+**Default threshold**: Effort > 500,000 triggers a finding.
+
+**Interpretation**: Effort estimates the mental effort to understand or recreate the code. Volume measures information content. EstimatedBugs = Volume / 3000 gives a rough bug prediction.
+
+**Example**: A 200-line function with effort 1,200,000 is ~2.4× the threshold — it likely needs decomposition into 3-4 smaller functions each under 500K effort.
+
+## Maintainability Index
+
+**Formula**: `MI = 171 - 5.2×ln(Volume) - 0.23×CC - 16.2×ln(LOC)`, rescaled to 0-100.
+
+**Default threshold**: MI < 20 triggers a finding.
+
+**Interpretation**: >65 = highly maintainable. 40-65 = moderate. 20-40 = difficult. <20 = very difficult to maintain. The index combines volume, complexity, and size into one number.
+
+**Example**: MI=12 on a 300-line function means it's in the danger zone. Splitting it into 4 focused helpers of ~75 lines each would likely push each above MI=40.
+
+## Abstractness (A)
+
+**Formula**: `A = abstractExports / totalExports` — share of exports that are types/interfaces.
+
+**Range**: 0 (fully concrete) to 1 (fully abstract).
+
+**Interpretation**: Combined with Instability to compute Distance from Main Sequence.
+
+**Example**: A module with 10 exports, 3 of which are types → A = 0.3.
+
+## Distance from Main Sequence (D)
+
+**Formula**: `D = |A + I - 1|` where A = Abstractness, I = Instability.
+
+**Default thresholds**: D > 0.7 (and module has minimum coupling) triggers a finding. Severity high if D > 0.8.
+
+**Interpretation**: D = 0 means the module sits on the "main sequence" (balanced abstraction vs. stability). High D means the module is either in the **Zone of Pain** (concrete + stable = hard to change) or **Zone of Uselessness** (abstract + unstable = unused abstractions).
+
+**Example**: Module with I=0.1, A=0.1 → D = |0.1 + 0.1 - 1| = 0.8 (Zone of Pain). Fix: add abstractions or reduce inbound coupling.
+
+## Hot-File Risk Score
+
+**Formula**: `risk = fanIn * 3 + complexity + fanOut + (onCriticalPath ? 100 : 0) + (inCycle ? 50 : 0)`
+
+**Interpretation**: Ranks files by danger-to-change. High fan-in means many consumers break. High complexity means the file itself is fragile. Critical path and cycle membership amplify risk.
+
+**Example**: `types/index.ts` with fanIn=54, complexity=1 → risk = 54*3 + 1 + 2 + 100 = 265. The highest risk files are the most important to keep stable and well-tested.
+
+## Low Cohesion (LCOM)
+
+**Method**: For each file, compare the set of imports used by each export. If exports share few common dependencies, the file has low cohesion — its exports serve unrelated purposes.
+
+**Default thresholds**: minExports ≥ 3, internal dependencies from 3+ distinct groups.
+
+**Interpretation**: A file with low cohesion is doing multiple jobs and should be split. LCOM > 1 suggests the module boundary is wrong.
+
+**Example**: `utils.ts` exports `parseDate()`, `formatCurrency()`, and `validateEmail()` — each uses different imports and serves a different domain. Split into `date-utils.ts`, `currency-utils.ts`, `validation-utils.ts`.
+
+## Cyclomatic Density
+
+**Formula**: `CC / LOC` (cyclomatic complexity divided by lines of code).
+
+**Note**: Not used as a standalone finding category. Cyclomatic complexity is folded into the `function-optimization` detector and the Maintainability Index calculation.
+
+**Interpretation**: Density > 0.5 means on average every other line is a branch point. The code is almost entirely control flow with minimal straight-line logic.
+
+**Example**: A function with CC=30 and LOC=45 has density 0.67 — nearly pure branching logic. Consider extracting branch groups into named helpers or using lookup tables.
+
+## Reachability
+
+**Method**: BFS from entrypoints (`index`, `main`, `app`, `server`, `cli`, `public`, `*.config.*`). Files not reached are flagged as `unreachable-module`.
+
+**Interpretation**: Stricter than orphan-module detection (which only checks for zero inbound imports). A file may have importers but still be unreachable from any entrypoint if its entire import subtree is disconnected.
+
+**Example**: `utils/legacy-helper.ts` has 2 importers, but both importers are also unreachable from any entrypoint — the entire cluster is dead code.
+
+## Package Boundaries
+
+**Rule**: `packages/A/` should import from `packages/B/src/index.ts` (public API), never `packages/B/src/internal/bar.ts`.
+
+**Interpretation**: Crossing into another package's internal modules creates tight coupling that bypasses the package's public contract. Changes to internals can break consumers silently.
+
+**Example**: `packages/cli/src/run.ts` imports `packages/core/src/internal/parser.ts` instead of using the public `packages/core/src/index.ts` re-export. Fix: add the needed symbol to core's public API or restructure the dependency.

package/skills/octocode-code-engineer/references/finding-categories.md

@@ -0,0 +1,128 @@
+# Finding Categories
+
+All categories detected by the scan, grouped by pillar. Categories marked `--semantic` require the `--semantic` flag.
+
+---
+
+## Architecture Risk
+
+| Category | Severity | Detects | Requires |
+|----------|----------|---------|----------|
+| `dependency-cycle` | high | Circular import chains | — |
+| `dependency-critical-path` | high — critical | High-weight transitive dependency chains | — |
+| `dependency-test-only` | medium | Production modules imported only from tests | — |
+| `architecture-sdp-violation` | medium — high | Stable module depends on unstable module (I = Ce/(Ca+Ce)) | — |
+| `high-coupling` | medium — high | Excessive Ca + Ce connections | — |
+| `god-module-coupling` | medium — high | High fan-in (bottleneck) or fan-out (sprawl) | — |
+| `mega-folder` | medium | Directory with excessive file count | — |
+| `orphan-module` | medium | Zero inbound AND zero outbound dependencies | — |
+| `unreachable-module` | high | Not reachable from any entrypoint via BFS | — |
+| `layer-violation` | high | Import backwards in configured layer order | — |
+| `low-cohesion` | medium — high | Exports serve unrelated purposes (LCOM > 1) | — |
+| `distance-from-main-sequence` | medium — high | Module far from A + I = 1 (Zone of Pain / Uselessness) | — |
+| `feature-envy` | medium — high | Module imports 60%+ symbols from single external module | — |
+| `untested-critical-code` | high — critical | Hot/critical-path file with zero test imports | — |
+| `cycle-cluster` | medium — high | Strongly connected file cluster large enough to behave like one tangled subsystem | — |
+| `broker-module` | medium — high | Module concentrates graph pressure across fan-in, fan-out, articulation, or critical-path signals | — |
+| `bridge-module` | medium — high | Structural articulation point or bridge between subsystems | — |
+| `package-boundary-chatter` | medium — high | Excessive cross-package dependency edges between two package groups | — |
+| `startup-risk-hub` | medium — high | Import-time side effects on a high fan-in structural hub | — |
+| `over-abstraction` | medium | Interface/abstract class with exactly 1 implementor | `--semantic` |
+| `concrete-dependency` | medium | Import resolves to concrete class (DIP violation) | `--semantic` |
+| `circular-type-dependency` | high | Type A references Type B, B references A (type-level cycle) | `--semantic` |
+| `shotgun-surgery` | medium — high | Export referenced from 8+ unique files (change amplification risk) | `--semantic` |
+| `import-side-effect-risk` | low — critical | Module executes risky work at import time (sync I/O, exec, eval, timers, listeners); scored by AST evidence + architecture context (fan-in, critical path, cycle, entry role) | — |
+| `namespace-import` | medium | Namespace import (`import * as X`) pulling in entire module surface | — |
+| `commonjs-in-esm` | medium | CommonJS `require()` in an ESM-style codebase | — |
+| `export-star-leak` | medium — high | `export * from` re-exports leaking internal symbols | — |
+| `mixed-module-format` | medium | File mixes CommonJS and ESM syntax | — |
+
+---
+
+## Code Quality
+
+| Category | Severity | Detects | Requires |
+|----------|----------|---------|----------|
+| `duplicate-function-body` | low — high | Identical function implementations across files | — |
+| `duplicate-flow-structure` | medium — high | Repeated control-flow patterns | — |
+| `similar-function-body` | medium — high | Near-clone functions (Type-2: renamed vars, different literals) | — |
+| `function-optimization` | medium — high | High complexity, deep nesting, oversized functions | — |
+| `cognitive-complexity` | medium — high | Nesting-aware complexity score | — |
+| `god-module` | high | Files with excessive statements or exports | — |
+| `god-function` | high | Functions with excessive statements | — |
+| `halstead-effort` | medium — high | Halstead effort > threshold or estimated bugs > 2.0 | — |
+| `low-maintainability` | high — critical | Maintainability Index below threshold | — |
+| `excessive-parameters` | medium — high | Function exceeds parameter threshold | — |
+| `unsafe-any` | medium — high | Excessive `any` types | — |
+| `empty-catch` | medium | Empty catch block | — |
+| `switch-no-default` | low | Switch missing default case | — |
+| `type-assertion-escape` | medium — high | `as any`, `as unknown as T`, non-null `!` assertions | — |
+| `missing-error-boundary` | low — high | Async function with await(s) but no try-catch or `.catch()` handler; severity tiers: 1 await = low, 2-3 = medium, 4+ = high | — |
+| `promise-misuse` | medium | `async` function that never uses `await` | — |
+| `await-in-loop` | high | await inside loop body — sequential async (N+1 latency) | — |
+| `sync-io` | medium | Synchronous I/O calls (readFileSync, execSync, etc.) | — |
+| `uncleared-timer` | medium | setInterval without clearInterval in scope | — |
+| `listener-leak-risk` | medium | Event listeners added without corresponding removal | — |
+| `unbounded-collection` | low | Collection growth inside nested loops without size guard | — |
+| `unused-parameter` | medium | Function parameter never referenced in body (semantic) | `--semantic` |
+| `deep-override-chain` | medium — high | Method overridden beyond depth threshold in class hierarchy | `--semantic` |
+| `interface-compliance` | medium — high | Class `implements I` with missing or any-cast members | `--semantic` |
+| `narrowable-type` | low | Parameter declared broad but all callers pass narrow type | `--semantic` |
+| `message-chain` | medium — high | Property-access chains of depth ≥ 4 (`a.b.c.d`) violating the Law of Demeter. Medium at depth 4–5; high at depth ≥ 6. Deep chains tightly couple the caller to intermediate object structure | — |
+
+---
+
+## Dead Code & Hygiene
+
+| Category | Severity | Detects | Requires |
+|----------|----------|---------|----------|
+| `dead-export` | medium — high | Exported symbol with no usage (import matching) | — |
+| `dead-re-export` | medium | Barrel re-export with no consumers | — |
+| `re-export-duplication` | medium | Same symbol re-exported from multiple paths | — |
+| `re-export-shadowed` | high | Local export and re-export name collision | — |
+| `unused-npm-dependency` | low — medium | package.json dep not imported anywhere | — |
+| `package-boundary-violation` | medium — high | Cross-package import bypassing public API | — |
+| `barrel-explosion` | medium — high | Barrel with excessive re-exports or chain depth | — |
+| `redundant-re-export` | low — medium | *(planned)* Barrel re-export with 0 consumers through the barrel path; includes `export *` where <50% of symbols are consumed | — |
+| `redundant-comment` | low | *(planned)* Comment that restates what the code already says (narrating patterns: `// Import`, `// Define`, `// Return`, `// Set`, `// Get`, `// Handle`, `// Create`, etc.) | — |
+| `unused-import` | low | Imported symbol never semantically used (TypeChecker confirmed) | `--semantic` |
+| `orphan-implementation` | medium | Exported class with no external references and no interface | `--semantic` |
+| `move-to-caller` | low | Exported symbol consumed by exactly 1 file (candidate for inlining) | `--semantic` |
+| `semantic-dead-export` | high | Exported symbol with zero semantic references (TypeChecker confirmed, stricter than `dead-export`) | `--semantic` |
+| `dead-file` | medium | File with no inbound or outbound dependencies — likely stale | — |
+
+---
+
+## Security
+
+| Category | Severity | Detects | Requires |
+|----------|----------|---------|----------|
+| `hardcoded-secret` | high | String literals matching secret patterns (password, API key, token) or high-entropy strings | — |
+| `eval-usage` | critical | `eval()`, `new Function()`, string-based `setTimeout`/`setInterval` | — |
+| `unsafe-html` | high | `innerHTML`, `outerHTML`, `dangerouslySetInnerHTML`, `document.write` | — |
+| `sql-injection-risk` | high | Template literal with SQL keywords and interpolated expressions | — |
+| `unsafe-regex` | medium | Regex with nested quantifiers (catastrophic backtracking / ReDoS) | — |
+| `prototype-pollution-risk` | medium — high | `Object.assign()` without `__proto__` guard, deep merge/extend utilities, computed-property bracket writes (`obj[key] = val`) | — |
+| `unvalidated-input-sink` | high | Function receives external input (param name heuristic) and uses a dangerous sink (eval, innerHTML, SQL, exec, fs write) without validation evidence | — |
+| `input-passthrough-risk` | low — medium | Function receives external input and passes it to other functions without validation; severity by param confidence (high-confidence params like `req`, `body` = medium; medium-confidence like `input`, `event` = low; low-confidence like `data`, `args` = filtered out). Trace downstream with `lspCallHierarchy` | — |
+| `path-traversal-risk` | medium — high | Function receives external input that flows into `fs.readFile`, `path.resolve`, or `path.join` without validation (normalize → prefix check → realpath). High severity when no validation; medium when partial validation detected | — |
+| `command-injection-risk` | high — critical | Function receives external input that flows into `exec`/`execSync` (critical) or `spawn` with potential `shell:true` (high). exec with string interpolation enables arbitrary OS command execution | — |
+| `debug-log-leakage` | medium — high | `debugger` statements (high) or `console.debug`/`console.trace` calls (medium) in non-test production files. Information disclosure risk — exposes internal state and execution paths | — |
+| `sensitive-data-logging` | high | `console.*` calls whose argument text matches a sensitive-data pattern: password, token, secret, credential, API key, session, SSN, credit card. Logs write secrets to stdout, log aggregators, and persistent storage | — |
+
+---
+
+## Test Quality
+
+Requires `--include-tests` (or auto-enabled when `--features=test-quality`).
+
+| Category | Severity | Detects | Requires |
+|----------|----------|---------|----------|
+| `low-assertion-density` | medium | Average < 1 assertion per test block | `--include-tests` |
+| `test-no-assertion` | high | `it()`/`test()` block with zero assertions | `--include-tests` |
+| `excessive-mocking` | medium | Mock/spy calls exceeding threshold per test file | `--include-tests` |
+| `shared-mutable-state` | medium | `let`/`var` at describe scope — mutation across tests | `--include-tests` |
+| `missing-test-cleanup` | medium | `beforeAll`/`beforeEach` without corresponding `afterAll`/`afterEach` | `--include-tests` |
+| `focused-test` | medium | `.only`, `.skip`, or `.todo` committed in a test file | `--include-tests` |
+| `fake-timer-no-restore` | medium | Fake timers enabled without restoring real timers | `--include-tests` |
+| `missing-mock-restoration` | medium | Spies/stubs created without restore or restoreAll cleanup | `--include-tests` |