octocode-cli 1.2.8 → 1.2.10

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

@@ -1,210 +0,0 @@
-# AST Search Reference
-
-Structural code search powered by [`@ast-grep/napi`](https://ast-grep.github.io/). Finds code by AST shape, not text — `console.log(x)` matches regardless of whitespace or formatting.
-
-```bash
-node <SKILL_DIR>/scripts/ast/search.js [options]
-```
-
----
-
-## Search Modes
-
-Pick one per invocation.
-
-### Pattern (`-p`, `--pattern`)
-
-Write the code shape. Replace variable parts with `$X` (one node) or `$$$X` (zero or more).
-
-```bash
--p 'console.log($$$ARGS)'                    # all console.log
--p 'console.$METHOD($$$ARGS)'                # any console method
--p 'if ($COND) { return $VAL }'              # early returns
--p 'import { $$$NAMES } from $MOD'           # named imports (any module)
--p 'export const $NAME = $VAL'               # exported constants
--p 'process.env.$VAR'                        # env access
--p 'throw new Error($$$MSG)'                 # error throws
--p 'function $NAME($$$P) { $$$B }'           # function declarations
--p 'const $NAME = ($$$P) => $BODY'           # arrow assignments
-```
-
-Meta-variables captured in JSON output under `metaVariables`:
-
-```json
-{ "$METHOD": "log", "$$$ARGS": "\"hello\", 42" }
-```
-
-> **Quote sensitivity**: `'fs'` won't match `"fs"`. Use `$MOD` wildcard to match any quote style.
-
-### Kind (`-k`, `--kind`)
-
-Match all nodes of an AST kind.
-
-```bash
--k function_declaration    -k arrow_function         -k class_declaration
--k interface_declaration   -k type_alias_declaration  -k import_statement
--k try_statement           -k switch_statement        -k for_in_statement
--k await_expression        -k template_string         -k object_pattern
-```
-
-> TS-only kinds (`predefined_type`, `interface_declaration`) are silently skipped on `.js` files.
-
-### Preset (`--preset`)
-
-16 built-in rules for common patterns. List with `--list-presets`.
-
-| Preset | Finds |
-|--------|-------|
-| `empty-catch` | `catch (e) {}` — silently swallowed errors |
-| `console-log` | `console.log(...)` left in production |
-| `console-any` | Any `console.*()` call |
-| `debugger` | `debugger;` statements |
-| `todo-fixme` | TODO/FIXME/HACK/XXX/BUG comments |
-| `any-type` | `: any` annotations (TS only) |
-| `type-assertion` | `x as Type` assertions |
-| `non-null-assertion` | `x!` non-null assertions |
-| `fat-arrow-body` | `() => { return x }` — could be expression |
-| `nested-ternary` | `a ? (b ? 1 : 2) : 3` |
-| `throw-string` | `throw "oops"` — should be Error |
-| `switch-no-default` | `switch` without `default` |
-| `class-declaration` | All class declarations |
-| `async-function` | `async function` declarations |
-| `export-default` | `export default` statements |
-| `import-star` | `import * as X` namespace imports |
-
-### Rule (`--rule`)
-
-Raw ast-grep rule JSON. Use for negation, regex, or nested structural queries.
-
-```bash
-# Negation: if without else
---rule '{"rule":{"kind":"if_statement","not":{"has":{"kind":"else_clause"}}}}'
-
-# Regex on text: secrets in strings
---rule '{"rule":{"kind":"string","regex":"password|secret|token|api.?key"}}'
-
-# Nested: try with finally
---rule '{"rule":{"kind":"try_statement","has":{"kind":"finally_clause","stopBy":"end"}}}'
-
-# Long param lists
---rule '{"rule":{"kind":"formal_parameters","regex":"(,.*){5,}"}}'
-```
-
-**Rule operators:**
-
-| Operator | Purpose | Example |
-|----------|---------|---------|
-| `kind` | Match node kind | `{"kind":"catch_clause"}` |
-| `pattern` | Match code shape | `{"pattern":"console.log($$$A)"}` |
-| `regex` | Match node text | `{"regex":"TODO\|FIXME"}` |
-| `has` | Child matches rule | `{"has":{"kind":"finally_clause"}}` |
-| `not` | Negate | `{"not":{"has":{"kind":"else_clause"}}}` |
-| `all` | AND | `{"all":[{"kind":"X"},{"regex":"Y"}]}` |
-| `any` | OR | `{"any":[{"kind":"X"},{"kind":"Y"}]}` |
-| `stopBy: "end"` | Search descendants (not just direct children) | `{"has":{"kind":"X","stopBy":"end"}}` |
-| `field` | Match by grammar field | `{"has":{"field":"default"}}` |
-
----
-
-## CLI Reference
-
-```
-node scripts/ast/search.js [options]
-
-Search (pick one):
-  -p, --pattern <code>     Code shape with $X/$$$X wildcards
-  -k, --kind <name>        AST node kind
-  --preset <name>          Built-in rule (see --list-presets)
-  --rule <json>            Raw ast-grep rule JSON
-
-Options:
-  --root <path>            Search directory (default: cwd)
-  --json                   JSON output (use for programmatic consumption)
-  --limit N                Max matches (default: 500)
-  --include-tests          Include *.test.*, *.spec.*, __tests__/
-  -C, --context N          Context lines around matches (text mode only)
-  --list-presets           List presets and exit
-  -h, --help               Show help
-```
-
-| Flag | Default | Notes |
-|------|---------|-------|
-| `--root` | cwd | Relative or absolute |
-| `--json` | off | Outputs `AstSearchResult` — always use for agent consumption |
-| `--limit` | 500 | Global cap across all files |
-| `--include-tests` | off | Test files excluded by default |
-| `--context` | 0 | Shows source lines around matches with `>` marker |
-
-**Scanned**: `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs` (excludes `.d.ts`)
-
-**Skipped dirs**: `.git`, `.next`, `.yarn`, `.cache`, `.octocode`, `node_modules`, `dist`, `coverage`, `out`
-
----
-
-## Output
-
-### Text (default)
-
-```
-🔍 preset:empty-catch — Empty catch blocks that silently swallow errors
-   3 matches across 2 files
-
-── packages/core/src/parser.ts ──
-  L42:4  [catch_clause]  catch (e) { }
-```
-
-### Text with `--context 2`
-
-```
-── src/index.ts ──
-     896 |   for (const [key, file] of Object.entries(outputFiles)) {
-     897 |     let size = '—';
-  >  898 |     try { size = formatFileSize(fs.statSync(path.join(dir, file)).size); } catch {}
-     899 |     lines.push(...);
-     900 |   }
-```
-
-### JSON (`--json`)
-
-```json
-{
-  "query": "preset:empty-catch — ...",
-  "queryType": "preset",
-  "totalMatches": 3,
-  "totalFiles": 2,
-  "matches": [{
-    "file": "packages/core/src/parser.ts",
-    "kind": "catch_clause",
-    "text": "catch (e) { }",
-    "lineStart": 42, "lineEnd": 42,
-    "columnStart": 4, "columnEnd": 18,
-    "metaVariables": {}
-  }]
-}
-```
-
----
-
-## Agent Guide
-
-### Decision Tree
-
-```
-"Find all X() calls"        → -p 'X($$$ARGS)'
-"Find all X nodes"          → -k X_kind_name
-"Known code smell"          → --preset name
-"Negation / regex / nesting" → --rule '{...}'
-```
-
-### Rules for Agents
-
-1. **Always `--json`** for programmatic use. Parse `totalMatches`, iterate `matches[]`.
-2. **Start narrow**: `--limit 10 --root <specific-dir>` before broad search.
-3. **Chain with scan**: `index.js` flags `unsafe-any` → `--preset any-type --root <pkg>`.
-4. **Use `$MOD`** for imports — avoids quote mismatch.
-5. **`--rule` for negation** — patterns can't express "X without Y".
-6. **`stopBy: "end"`** required for recursive `has` (descendant search, not just children).
-7. **Grammar-safe**: TS-only kinds silently skipped on JS files.
-8. **`--include-tests`** for `describe`, `it`, `expect` patterns.
-9. **Meta-variables** appear in JSON — extract captured `$NAME`, `$MOD`, `$$$ARGS`.
-10. **`-C N`** for context — shows N lines before/after matches in text mode.

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

@@ -1,151 +0,0 @@
-# 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/concepts.md

@@ -1,107 +0,0 @@
-# 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

@@ -1,128 +0,0 @@
-# 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` |