octocode-cli 1.2.7 → 1.2.9

package/skills/octocode-code-engineer/references/improvement-roadmap.md

@@ -1,304 +0,0 @@
-# Improvement Roadmap
-
-Research-backed upgrade plan for the weakest parts of the skill: security analysis, test-quality analysis, semantic analysis, output/reporting, and test-suite quality.
-
-For validation policy, see the Principles section in [SKILL.md](../SKILL.md) and [validate & investigate](./validate-investigate.md).
-
-**Status legend**: Done, Partial, Planned
-
----
-
-## 1. Security Analysis
-
-### Current weakness
-
-The current security layer is strong on breadth but still depends heavily on single-file heuristics. That creates false positives for patterns that look dangerous but are not proven dangerous in context.
-
-### Target architecture
-
-Move from isolated pattern detection to a lightweight taint model:
-
-`sources -> propagators -> sanitizers -> sinks -> evidence trace`
-
-Keep cheap AST rules for obvious cases:
-- `eval`
-- `new Function`
-- direct `innerHTML`
-- hardcoded secrets
-
-Upgrade the noisier rules to dataflow-backed analysis:
-- `prototype-pollution-risk`
-- `sql-injection-risk`
-- `unsafe-html`
-- `unvalidated-input-sink`
-- `input-passthrough-risk`
-
-### Concrete upgrades
-
-- Add sink-specific rule models for SQL, HTML, command execution, file writes, path joins, and object merge/write sites.
-- Add sanitizer catalogs for common validation and encoding patterns.
-- Add confidence scoring per rule: `high`, `medium`, `low`.
-- Add finding evidence: source parameter, propagation steps, sink call, sanitizer status.
-- Suppress structural false positives where the dynamic key is synthesized locally and never user-controlled.
-
-### P0 work
-
-- Split current security detectors into `pattern` rules and `flow` rules. *(Partial — detectors use evidence/confidence/ruleId)*
-- Add fixture tests for true positive and false positive pairs. *(Partial — test file exists)*
-- Add `confidence` and `evidence` fields to security findings. *(Done — `toSecurityFinding` in security.ts)*
-
-### P1 work
-
-- Build intra-procedural taint tracking inside a function body. *(Planned)*
-- Add reusable source/sink/sanitizer definitions. *(Planned)*
-- Add validation playbooks for each security category using Octocode local tools. *(Partial — playbooks.md covers some)*
-
----
-
-## 2. Test-Quality Analysis
-
-### Current weakness
-
-The current test-quality pass mostly counts assertions, mocks, and setup hooks. That is helpful, but still shallow for real flakiness and false-confidence detection.
-
-### Target architecture
-
-Extend test analysis from simple counters to behavior-aware checks:
-
-- assertion presence
-- assertion reachability on all paths
-- cleanup and restore behavior
-- deterministic execution
-- framework misuse
-
-### Concrete upgrades
-
-- Detect async tests that neither `await` nor return a promise.
-- Detect `test.only`, `describe.only`, `skip`, and `todo`.
-- Detect fake timers without restore and mock/spy state not reset or restored.
-- Detect time, randomness, environment, and global-state coupling.
-- Detect snapshot-only tests and interaction-only tests with no outcome assertions.
-- Detect cleanup that exists on one path but not all paths.
-
-### P0 work
-
-- Add dedicated detector tests for test-quality rules. *(Done — test-quality.test.ts)*
-- Add rules for focused tests, fake timers without restore, and missing mock restoration. *(Done — all 8 categories implemented)*
-- Add a richer `testProfile` summary for timers, mocks, async patterns, and cleanup hooks. *(Done — TestProfile in interfaces.ts)*
-
-### P1 work
-
-- Add code-path-aware assertion and cleanup checks. *(Planned)*
-- Add framework-specific adapters for Vitest/Jest style APIs. *(Planned)*
-- Add flaky-test tags and recommended remediation steps. *(Planned)*
-
----
-
-## 3. Semantic Analysis
-
-### Current weakness
-
-Semantic analysis is valuable, but it currently rebuilds a fresh TypeScript language service and uses a constant script version. That limits scale and wastes work on repeated scans.
-
-### Target architecture
-
-Adopt a persistent project-backed semantic engine:
-
-- cache by `tsconfig`
-- track file versions
-- reuse TypeScript project state across scans
-- support project references cleanly
-
-### Concrete upgrades
-
-- Replace ad hoc `LanguageService` creation with a project-service wrapper.
-- Separate semantic fact collection from detector execution.
-- Cache export references, inheritance chains, implementation maps, and symbol relationships.
-- Expose semantic facts to detectors through a stable query surface instead of repeated tree walks.
-
-### P0 work
-
-- Introduce a semantic cache keyed by root + tsconfig + file versions. *(Planned)*
-- Stop hardcoding script version `"1"`. *(Planned)*
-- Benchmark semantic scan cost before and after caching. *(Planned)*
-
-### P1 work
-
-- Move to a Project Service style lifecycle. *(Planned)*
-- Support project references and monorepo workspaces. *(Planned)*
-- Share semantic state between multiple detectors in a single run. *(Partial — `runSemanticDetectors` shares ctx)*
-
----
-
-## 4. Output & Reporting
-
-### Current weakness
-
-The output is rich, but report generation is currently brittle and the output contract is not explicit enough to protect downstream tooling.
-
-### Target architecture
-
-Treat findings and reports as a versioned API:
-
-- one normalized internal result model
-- multiple emitters from that model
-- stable schema version
-- stable rule IDs
-- optional SARIF output
-
-### Concrete upgrades
-
-- Normalize `summary.json`, `findings.json`, and Markdown generation around one canonical result object.
-- Add `schemaVersion`, `confidence`, `evidence`, and `ruleId`.
-- Add SARIF emission with stable fingerprints.
-- Add diff/baseline mode so teams can adopt the tool incrementally.
-- Add contract tests for output shapes and golden tests for Markdown rendering.
-
-### P0 work
-
-- Fix the report regression first. *(Done)*
-- Add dedicated golden tests for `summary.md`, `summary.json`, and `findings.json`. *(Done — output-contract.test.ts)*
-- Add contract assertions around required keys and nullable fields. *(Done — schemaVersion, REPORT_SCHEMA_VERSION)*
-
-### P1 work
-
-- Add SARIF emitter. *(Planned)*
-- Add baseline and diff output modes. *(Planned)*
-- Add category-level and confidence-level summary slices. *(Planned)*
-
----
-
-## 5. Test-Suite Quality
-
-### Current weakness
-
-The suite is large, but the failing report tests show that critical output paths can still regress together. Some important detector modules do not have focused test files.
-
-### Target architecture
-
-Use layered testing:
-
-- focused detector unit tests
-- integration tests for orchestration
-- golden tests for reports
-- property-based tests for AST invariants
-- mutation testing for critical rules
-
-### Concrete upgrades
-
-- Add dedicated tests for `security-detectors`, `test-quality-detectors`, and `tree-sitter-analyzer`.
-- Add property-based tests for AST search and report invariants.
-- Add mutation testing for high-risk detectors and output generation.
-- Add smoke tests that run the scanner against its own source and assert key categories.
-
-### P0 work
-
-- Restore a green Vitest run. *(Done)*
-- Add missing focused test files. *(Partial — 34 test files, some detector modules still untested)*
-- Lock down report and findings schema expectations. *(Done — output-contract.test.ts)*
-
-### P1 work
-
-- Add property-based tests with `fast-check`. *(Planned)*
-- Add mutation testing with Stryker for critical modules. *(Planned)*
-- Add self-scan fixture snapshots for detector stability. *(Planned)*
-
----
-
-## 6. Architecture Analysis Depth
-
-### Current weakness
-
-The current architecture layer is strongest at file-level import analysis and architecture heuristics, but it still underuses graph science and AST/dataflow techniques that would make boundary and coupling defects more explainable.
-
-### Target architecture
-
-Treat architecture analysis as a hybrid of graph evidence and structural evidence:
-
-- graph evidence for dependency shape, chokepoints, layering, and subsystem boundaries
-- AST/semantic evidence for code roles, boundary leaks, side effects, and repeated orchestration
-
-### Graph technique upgrades
-
-- Add SCC condensation graphs so large file-level cycles collapse into interpretable cycle clusters.
-- Add folder/package graphs to surface subsystem-level cycles and cross-boundary chatter.
-- Add articulation-point and bridge-edge detection to identify brittle chokepoints.
-- Add broker or betweenness-centrality scoring to find modules that mediate too many paths.
-- Add change-coupling overlays from git history to catch architecture defects the import graph misses.
-
-### AST and semantic technique upgrades
-
-- Add relational or composite AST rules for architecture motifs, not just single-node patterns.
-- Add symbol-level usage graphs so cohesion and feature-envy checks work below the file level.
-- Add CFG/dataflow checks for boundary leaks, initialization order, and validation-before-sink behavior.
-- Add import-time effect tracing to classify module-scope I/O, registration, and global mutation.
-- Add boundary-role detection so controllers, services, domain modules, and infrastructure code can be checked semantically instead of only by path names.
-
-### P0 work
-
-- Expand the docs and playbooks so agents interpret architecture findings through graph and AST lenses together. *(Done — tool-workflows.md, playbooks.md)*
-- Surface existing hub-node and hotspot signals more explicitly in result reading guidance. *(Done — hotFiles in summary.md)*
-- Add fixture-based tests for graph-hotspot interpretation and architecture-summary rendering. *(Partial)*
-
-### P1 work
-
-- Implement SCC condensation and package-level dependency views. *(Partial — SCC clusters implemented in graph-analytics.ts)*
-- Add broker centrality and articulation-point scoring to hotspot analysis. *(Done — broker-module, bridge-module in graph-analytics.ts)*
-- Add relational AST rules for boundary leaks, split-brain modules, and import-time orchestration. *(Partial — import-side-effect-risk implemented)*
-
-### P2 work
-
-- Add lightweight local dataflow for architecture rules.
-- Combine graph scores with AST evidence into a single architecture-confidence model.
-- Add change-coupling overlays and folder/community clustering for subsystem discovery.
-
----
-
-## Delivery Phases
-
-### Phase 0: Stabilize
-
-- Fix output/reporting regressions.
-- Make Vitest green.
-- Add missing focused tests.
-- Enforce Octocode local-tool validation in the skill docs and playbooks.
-- Tighten architecture reading guidance around graph and AST signals.
-
-### Phase 1: Improve Precision
-
-- Add security taint modeling inside a function body.
-- Add richer test-quality rules for cleanup, timers, mocks, and async behavior.
-- Add confidence and evidence fields to findings.
-
-### Phase 2: Improve Scale
-
-- Add persistent semantic state and project-backed analysis.
-- Add semantic fact caching.
-- Add baseline/diff mode and SARIF output.
-
-### Phase 3: Deepen Coverage
-
-- Add optional interprocedural summaries.
-- Add property-based and mutation testing.
-- Externalize more AST-only rules into rule packs.
-- Add deeper graph and subsystem analysis for architecture defects.
-
----
-
-## Research Basis
-
-- TypeScript Compiler API wiki: https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API
-- typescript-eslint Project Service docs: https://typescript-eslint.io/packages/project-service/generated/
-- typescript-eslint Project Service blog: https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/website/blog/2025-05-29-project-service.mdx
-- Semgrep taint analysis overview: https://github.com/semgrep/semgrep-docs/blob/main/docs/writing-rules/data-flow/taint-mode/overview.md
-- ast-grep relational rules: https://github.com/ast-grep/ast-grep.github.io/blob/main/website/guide/rule-config/relational-rule.md
-- ESLint code path analysis: https://eslint.org/docs/latest/extend/code-path-analysis
-- Tree-sitter predicates and directives: https://tree-sitter.github.io/tree-sitter/using-parsers/queries/3-predicates-and-directives.html
-- dependency-cruiser rules reference: https://github.com/sverweij/dependency-cruiser/blob/main/doc/rules-reference.md
-- CodeQL data flow analysis: https://github.com/github/codeql/blob/main/docs/codeql/writing-codeql-queries/about-data-flow-analysis.rst
-- CodeQL JS/TS data flow guide: https://github.com/github/codeql/blob/main/docs/codeql/codeql-language-guides/analyzing-data-flow-in-javascript-and-typescript.rst
-- Vitest coverage reporters: https://github.com/vitest-dev/vitest/blob/main/docs/config/coverage.md
-- Vitest timers guide: https://vitest.dev/guide/mocking/timers
-- Stryker JS usage: https://github.com/stryker-mutator/stryker-js/blob/master/docs/usage.md
-- fast-check getting started: https://fast-check.dev/docs/introduction/getting-started/
-- GitHub SARIF fingerprints: https://docs.github.com/en/code-security/reference/code-scanning/sarif-files/sarif-support-for-code-scanning

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

@@ -1,204 +0,0 @@
-# Playbooks — Validate & Fix by Category
-
-Per-category guidance: which tools can help, what to check, and how to fix.
-
-For tool descriptions and LSP rules, see the **Tools** section in [SKILL.md](../SKILL.md).
-For investigation methodology, tool selection guide, taint tracing, and false positive dismissal, see [validate & investigate](./validate-investigate.md).
-
-Use `--graph-advanced` for SCC clusters, chokepoints, bridge modules, and package chatter. Use `--flow` for `cfgFlags`, `flowTrace`, and richer evidence.
-
-The tables below show CLI and Octocode MCP approaches per category. **These are suggestions, not rigid sequences** — pick the tools that answer the question fastest.
-
----
-
-## Architecture Playbooks
-
-| Finding | CLI Validate | Octocode MCP Validate | Fix |
-|---------|-------------|----------------------|-----|
-| `dependency-cycle` | `--features=dependency-cycle` → read `architecture.json` cycle paths | `localSearchCode(import.*from)` on cycle files → `lspGotoDefinition` on import | Break with shared contracts or dependency inversion |
-| `dependency-critical-path` | `--graph` → inspect Mermaid for long chains | `localSearchCode(export)` on hub → `lspCallHierarchy(incoming)` | Split hub, enforce boundaries |
-| `architecture-sdp-violation` | Read finding `reason` for I values | `lspCallHierarchy(incoming)` on stable; `(outgoing)` on unstable | Invert via interface or move to stable utility |
-| `high-coupling` | `--json \| jq` filter for `high-coupling` → check Ca/Ce | `lspFindReferences` on key exports → count consumers | Extract focused sub-modules by consumer group |
-| `god-module-coupling` | Check `hotFiles[]` in `architecture.json` for fan-in/fan-out | Fan-in: `lspFindReferences`; Fan-out: `lspCallHierarchy(outgoing)` | Split by responsibility, introduce facade |
-| `orphan-module` | `ast-search -p 'import $$$N from "modulePath"'` — 0 hits = orphan | `localSearchCode(fileName, filesOnly=true)` — check runtime config | Delete if disconnected |
-| `unreachable-module` | Same as orphan + check dynamic imports with `ast-search -p 'import($$$A)'` | `localSearchCode(moduleName)` — check dynamic imports | Delete subgraph if confirmed |
-| `layer-violation` | `--features=layer-violation --layer-order ui,service,repo` | `lspGotoDefinition` on violating import | Extract shared contracts to lower layer |
-| `low-cohesion` | Read finding `reason` for LCOM count + groups | `lspFindReferences` per export → map consumer clusters | Split into N focused modules |
-| `distance-from-main-sequence` | Read finding `reason` for A/I/D values + zone | Check `reason` for A/I/D values + zone | Add interfaces (Zone of Pain) or implementations (Zone of Uselessness) |
-| `feature-envy` | Check finding → compare import ratio | `lspCallHierarchy(outgoing)` on envious module → see which functions use target | Move logic to target module or extract shared module |
-| `cycle-cluster` | `--graph-advanced` → inspect `sccClusters[]` in `architecture.json` | `localSearchCode(import)` on hub files → `lspGotoDefinition` on cluster edges | Break SCC at a hub file or shared contract |
-| `broker-module` | `--graph-advanced` → inspect `chokepoints[]` and `criticalHubCandidates[]` | `lspFindReferences` for fan-in + `lspCallHierarchy(outgoing)` for fan-out | Split orchestration seams and narrow consumers |
-| `bridge-module` | `--graph-advanced` → inspect articulation-heavy `chokepoints[]` | `localSearchCode(fileName)` → trace the bridge edges with LSP | Remove the single structural bridge by adding lower-level contracts |
-| `package-boundary-chatter` | `--graph-advanced` → inspect `packageGraphSummary.hotspots[]` | `localSearchCode("from \\\"pkg\\\"")` on both sides → confirm symbol traffic | Reduce package API surface and stop internal-detail imports |
-| `startup-risk-hub` | `--graph-advanced` + `--features=startup-risk-hub` → inspect `topLevelEffects` + `chokepoints[]` | `lspFindReferences` on the module + `lspCallHierarchy` on effectful calls | Move import-time work behind explicit init or lazy paths |
-| `untested-critical-code` | `ast-search -p 'import $$$N from "modulePath"' --include-tests` — 0 test imports | `localFindFiles(name=*.test.*)` for sibling test → `lspCallHierarchy(incoming)` | Create test file covering public API + complex functions |
-| `import-side-effect-risk` | `--features=import-side-effect-risk` → check `topLevelEffects` in `file-inventory.json` | `lspFindReferences` on file → confirm fan-in; `lspCallHierarchy` on side-effect call → trace callers | Move side effects into explicit init(), wrap in lazy pattern, or guard with feature flags |
-| `namespace-import` | `ast-search -p 'import * as $NAME from $MOD'` | `localSearchCode("import * as")` → check which members are used | Convert to named imports for tree-shaking |
-| `commonjs-in-esm` | `ast-search -p 'require($$$A)'` | `localSearchCode("require(")` → check if ESM alternative exists | Convert to `import` syntax |
-| `export-star-leak` | `ast-search -p 'export * from $MOD'` | `localSearchCode("export * from")` → `lspFindReferences` on re-exported symbols | Replace with explicit named re-exports |
-| `mixed-module-format` | Check finding for mixed CJS/ESM evidence | `localGetFileContent` → confirm mixed `require()` and `import` | Standardize on ESM |
-
----
-
-## Code Quality Playbooks
-
-| Finding | CLI Validate | Octocode MCP Validate | Fix |
-|---------|-------------|----------------------|-----|
-| `duplicate-function-body` | `ast-search -p 'function $NAME($$$P) { $$$B }'` → compare matches | `localSearchCode` → `lspFindReferences` + `lspCallHierarchy(incoming)` | Extract shared helper |
-| `duplicate-flow-structure` | Read finding `reason` + line ranges → compare code | `localGetFileContent(startLine, endLine)` | Extract reusable flow helper |
-| `similar-function-body` | Read both file:line locations from finding | `localGetFileContent` on both locations → compare side-by-side | Parameterize differences into shared helper |
-| `function-optimization` | `--scope=file.ts:functionName` → check complexity breakdown | `lspCallHierarchy(incoming)` + `(outgoing)` | Split along responsibilities |
-| `cognitive-complexity` | `--scope=file.ts:functionName --features=cognitive-complexity` | `localGetFileContent(startLine, endLine)` + `lspCallHierarchy` | Early returns, extract nested blocks |
-| `god-module` | `--scope=file.ts` → check statement + export count | `localGetFileContent` → identify groups; `lspFindReferences` on exports → find consumer clusters | Extract each into dedicated module |
-| `god-function` | `--scope=file.ts:functionName` → check statement count | `localGetFileContent(startLine, endLine)` + `lspCallHierarchy` → map callees | Extract steps into named helpers |
-| `halstead-effort` | Read finding `reason` for effort/bugs/volume breakdown | `localGetFileContent` + `lspCallHierarchy(outgoing)` | Split into smaller functions |
-| `low-maintainability` | Read finding `reason` for MI components | Check `reason` for MI components | Reduce LOC, simplify expressions |
-| `excessive-parameters` | `ast-search -p 'function $NAME($A, $B, $C, $D, $E, $F)'` | `lspCallHierarchy(incoming)` → check caller diversity | Group into options object |
-| `unsafe-any` | `ast-search --preset any-type --root <package>` | `localSearchCode(": any\|as any")` | `unknown` + type guards, generics |
-| `empty-catch` | `ast-search --preset empty-catch --root <package>` | `localGetFileContent(startLine, endLine)` | Add logging or re-throw |
-| `switch-no-default` | `ast-search --preset switch-no-default` | `localGetFileContent(startLine, endLine)` | Add `default` with unreachable error |
-| `type-assertion-escape` | `ast-search --preset type-assertion` + `ast-search --preset non-null-assertion` | `localSearchCode("as any")` → review each occurrence | Replace with `unknown` + type guards, proper generics |
-| `missing-error-boundary` | `--features=missing-error-boundary` → check await counts (1=low, 2-3=med, 4+=high) | `localGetFileContent(startLine, endLine)` → check await calls; `lspCallHierarchy(incoming)` → check if callers wrap in try-catch | Wrap in try-catch, add `.catch()`, or document caller handling |
-| `promise-misuse` | `--features=promise-misuse` → list async-without-await | `localGetFileContent(startLine, endLine)` → check if await forgotten | Remove `async` keyword or add the missing `await` |
-| `message-chain` | `--features=message-chain` → read finding for depth and chain text | `localGetFileContent(startLine, endLine)` → read chain; `lspGotoDefinition` on root object → identify intermediate types | Add a delegating method on the root object (Tell, Don't Ask); replace chain with single call on immediate friend |
-
----
-
-## Performance & Resource Playbooks
-
-> These categories appear under the **Code Quality** pillar in scan output.
-
-| Finding | CLI Validate | Octocode MCP Validate | Fix |
-|---------|-------------|----------------------|-----|
-| `await-in-loop` | `ast-search -p 'await $EXPR' --root <dir>` + check if inside loop | `localGetFileContent(startLine, endLine)` → confirm loop+await pattern; `lspGotoDefinition` on awaited call | Collect promises, use `Promise.all()` or batch utility |
-| `sync-io` | `ast-search -p 'readFileSync($$$A)'` (or `writeFileSync`, etc.) | `localSearchCode("readFileSync\|writeFileSync")` → `lspCallHierarchy(incoming)` → check if in hot path | Replace with `fs.promises.*` async equivalents |
-| `uncleared-timer` | `ast-search -p 'setInterval($$$A)'` + search for `clearInterval` in same file | `localSearchCode("setInterval")` → check for `clearInterval` in same scope/cleanup | Store timer ID, call `clearInterval` in cleanup |
-| `listener-leak-risk` | `ast-search -p '.addEventListener($$$A)'` + `ast-search -p '.removeEventListener($$$A)'` — compare counts | `localSearchCode("addEventListener\|.on(")` → check for matching removal | Add `removeEventListener`/`.off()` in cleanup, or use `AbortController` |
-| `unbounded-collection` | `--scope=file.ts:functionName` → structural signal (loops × calls × depth) | **Read body**: `localGetFileContent(matchString=fnName)` → look for `.push/.add/.set` inside loops. **Trace**: `lspCallHierarchy(incoming)` → hot path? **Use `lspHints[]`** if present. **Dismiss** if no mutation in body or bounded by guard/limit | Add size limits, use pagination or streaming |
-
----
-
-## Dead Code & Hygiene Playbooks
-
-| Finding | CLI Validate | Octocode MCP Validate | Fix |
-|---------|-------------|----------------------|-----|
-| `dead-export` | `ast-search -p 'import { symbolName } from $MOD'` — 0 hits | `localSearchCode(export symbolName)` → `lspFindReferences(includeDeclaration=false)` — 0 refs | Remove export or delete symbol |
-| `dead-re-export` | `ast-search -p 'import { symbolName } from "barrelPath"'` — 0 hits | `localSearchCode(export.*from)` on barrel → `lspFindReferences` | Remove stale re-export |
-| `redundant-re-export` | Read barrel → `ast-search -p 'export { $SYM } from $MOD'` → check each for consumers | `lspFindReferences` on each re-exported symbol (from barrel, not source) → 0 consumer refs = redundant | Remove the re-export line. If source module also has 0 refs, flag for deletion. For `export *` with <50% consumed symbols, replace with explicit named exports |
-| `re-export-duplication` / `re-export-shadowed` | Read barrel file → check duplicate export names | `localSearchCode(export {)` in barrel | Keep one source-of-truth per name |
-| `unused-npm-dependency` | `ast-search -p 'import $$$N from "packageName"'` — 0 hits; also check `require("packageName")` | `localSearchCode(packageName)` — check build scripts | Remove the dependency via the project's package manager, verify build |
-| `package-boundary-violation` | Read finding → check if import goes through public API (index file) | `lspGotoDefinition` on cross-package import | Re-export from target index |
-| `barrel-explosion` | Count re-exports in barrel file; `--features=barrel-explosion` | `localGetFileContent(barrel file)` | Group into sub-barrels |
-| `redundant-comment` | `ast-search --rule '{"rule":{"kind":"comment"}}'` → filter for narrating patterns | `localSearchCode("// Import\|// Define\|// Return\|// Set \|// Get \|// Handle\|// Create\|// Initialize\|// Check \|// Update")` → review each hit | Delete comments that restate code. Keep comments explaining *why*, trade-offs, constraints, or non-obvious intent. Rule: if removing the comment loses zero information, remove it |
-
----
-
-## Security Playbooks
-
-| Finding | CLI Validate | Octocode MCP Validate | Fix |
-|---------|-------------|----------------------|-----|
-| `hardcoded-secret` | `ast-search --rule '{"rule":{"kind":"string","regex":"password\|secret\|token"}}'` → check if test/mock data | `localSearchCode("password\|api_key\|token")` → `lspFindReferences` on variable → scope remediation | Move to environment variable or secrets manager |
-| `eval-usage` | `ast-search -p 'eval($$$A)'` + `ast-search -p 'new Function($$$A)'` | `localGetFileContent(startLine, endLine)` → `lspCallHierarchy(incoming)` → trace how user input reaches eval | Replace with `JSON.parse`, lookup table, or function reference |
-| `unsafe-html` | `ast-search -p '$OBJ.innerHTML = $VAL'` + `ast-search -p 'dangerouslySetInnerHTML'` | `localSearchCode("innerHTML\|dangerouslySetInnerHTML")` → check if input is sanitized | Use `textContent`, DOMPurify, or JSX instead |
-| `sql-injection-risk` | Read finding → check template literal for user-controlled interpolation | `localGetFileContent(startLine, endLine)` → check if interpolated values are user input | Use parameterized queries or query builder |
-| `unsafe-regex` | Read finding regex pattern → check for nested quantifiers | `localGetFileContent(startLine, endLine)` → `lspFindReferences` → check if user input reaches regex | Simplify nested quantifiers, use `safe-regex` linter |
-| `prototype-pollution-risk` | `ast-search -p 'Object.assign($$$A)'` + `ast-search -p '$OBJ[$KEY] = $VAL'` | `localGetFileContent(startLine, endLine)` → `lspCallHierarchy(incoming)` → trace if user data reaches merge/assign site | Validate keys (reject `__proto__`, `constructor`), use `Object.create(null)`, use `structuredClone()` |
-| `unvalidated-input-sink` | `--features=unvalidated-input-sink` → read finding for param names + sink kinds | `lspCallHierarchy(outgoing)` on function → trace where input params flow; `lspFindReferences` on param → check all usages | Add schema validation (zod, joi) before sink; use parameterized queries for SQL/exec |
-| `input-passthrough-risk` | `--features=input-passthrough-risk` → read finding for param confidence + callees | `lspCallHierarchy(outgoing)` → verify downstream callees validate input; `lspFindReferences` on param → check all usage points | Add validation at entry point; search for middleware/guard patterns upstream |
-| `path-traversal-risk` | `--features=path-traversal-risk` → read finding for source params + sink kinds | `lspCallHierarchy(incoming)` on fs.readFile/path.resolve call → trace if path param comes from user input → check for `path.resolve` + `startsWith` + `realpathSync` guards | Add multi-layer validation: normalize → prefix check → realpath → re-validate |
-| `command-injection-risk` | `--features=command-injection-risk` → read finding for exec vs spawn distinction | `lspCallHierarchy(incoming)` on exec/spawn call → check if args come from user input → verify spawn uses array args (safe) vs exec with string interpolation (dangerous) | Replace exec with spawn + array args; use command allowlist; never interpolate user input into command strings |
-| `debug-log-leakage` | `ast-search --preset debugger` + `ast-search --preset console-any` → filter debug/trace calls | `localGetFileContent(startLine, endLine)` → confirm call exists and is not inside a test file or LOG_LEVEL guard | Remove `debugger` statements; replace `console.debug/trace` with structured logger gated by log-level config |
-| `sensitive-data-logging` | `ast-search --preset console-any --root <dir>` → filter for sensitive argument patterns | `localGetFileContent(startLine, endLine)` → read full log call and its arguments; `lspCallHierarchy(incoming)` → trace where the sensitive value originates | Remove raw sensitive values from log args; use `{ ...obj, password: "[REDACTED]" }` pattern; configure pino/winston redact option at the logger level |
-
-For taint tracing methodology, false positive dismissal criteria, and agentic security paths, see [validate & investigate](./validate-investigate.md).
-
----
-
-## Test Quality Playbooks
-
-| Finding | CLI Validate | Octocode MCP Validate | Fix |
-|---------|-------------|----------------------|-----|
-| `low-assertion-density` | `ast-search -p 'expect($$$A)' --include-tests --root <test-file>` → count per `it()` block | `localSearchCode("expect\|assert")` in file → count assertions per test | Add meaningful assertions to each test case |
-| `test-no-assertion` | Read finding → check specific `it()`/`test()` block at line range | `localGetFileContent(startLine, endLine)` → confirm no expect/assert inside test block | Add at least one assertion verifying behavior |
-| `excessive-mocking` | `ast-search -p 'vi.mock($$$A)' --include-tests` + `ast-search -p 'jest.mock($$$A)' --include-tests` — count | `localSearchCode("jest.mock\|vi.mock\|sinon")` → count mock calls | Reduce mocks by testing through public interfaces; use DI |
-| `shared-mutable-state` | Read finding → check `let`/`var` at describe scope | `localGetFileContent(startLine, endLine)` → confirm let/var at describe scope | Move to `beforeEach` or use `const` |
-| `missing-test-cleanup` | `ast-search -p 'beforeAll($$$A)' --include-tests` + check for `afterAll` in same file | `localSearchCode("beforeAll\|beforeEach\|afterAll\|afterEach")` → check pairing | Add corresponding `afterAll`/`afterEach` to clean up resources |
-| `focused-test` | `ast-search -p 'it.only($$$A)' --include-tests` + `ast-search -p 'describe.only($$$A)'` | `localSearchCode("\.only\|\.skip\|\.todo")` in test files → confirm committed focused/skipped tests | Remove `.only`/`.skip`/`.todo` before committing — use a pre-commit hook or lint rule to prevent regression |
-| `fake-timer-no-restore` | `ast-search -p 'vi.useFakeTimers($$$A)' --include-tests` + `ast-search -p 'jest.useFakeTimers($$$A)'` → check for matching restore | `localSearchCode("useFakeTimers\|useRealTimers")` → confirm each useFakeTimers has a corresponding useRealTimers | Add `afterEach(() => vi.useRealTimers())` or `jest.useRealTimers()` after each fake-timer setup |
-| `missing-mock-restoration` | `ast-search -p 'vi.spyOn($$$A)' --include-tests` + `ast-search -p 'jest.spyOn($$$A)'` → check for `.mockRestore()` | `localSearchCode("spyOn\|mockRestore\|restoreAllMocks")` → confirm each spy is restored | Add `mockRestore()` on each spy in `afterEach`, or use `vi.restoreAllMocks()`/`jest.restoreAllMocks()` in `afterEach` |
-
----
-
-## Semantic Analysis Playbooks (`--semantic`)
-
-| Finding | CLI Validate | Octocode MCP Validate (use `lspHints`) | Fix |
-|---------|-------------|----------------------------------------|-----|
-| `semantic-dead-export` | `--features=semantic-dead-export --semantic` → read findings | `lspFindReferences(symbolName, lineHint)` → 0 refs confirms dead | Remove export or delete symbol (stricter than `dead-export`) |
-| `over-abstraction` | `ast-search -p 'implements $IFACE'` → count implementations | `lspFindReferences` on interface → exactly 1 implementor | Inline interface into concrete class, or keep if mocking needed |
-| `concrete-dependency` | Read finding → check import target is class not interface | `lspGotoDefinition` on import → resolves to class (not interface) | Extract interface, depend on abstraction (DIP) |
-| `circular-type-dependency` | `--features=circular-type-dependency` → read cycle paths | `lspFindReferences` on each type in cycle → see cross-refs | Extract shared types to common file |
-| `unused-parameter` | `ast-search -p 'function $NAME($$$BEFORE, paramName, $$$AFTER)'` → check body references | `lspFindReferences` on param → 0 non-declaration refs | Remove param or prefix with `_` |
-| `deep-override-chain` | Read finding for override chain depth | `lspGotoDefinition` → trace override chain | Use template method or strategy pattern |
-| `interface-compliance` | Read finding for missing/any-cast members | `lspGotoDefinition` on interface → compare members | Implement missing members; replace `any` with proper types |
-| `unused-import` | `--features=unused-import --semantic` | `lspFindReferences` on import → 0 usages | Remove unused import statement |
-| `orphan-implementation` | `ast-search -p 'import { className } from $MOD'` — 0 hits | `lspFindReferences` on class → 0 external refs | Wire into DI/module graph, or delete if truly dead |
-| `shotgun-surgery` | Read finding for reference count across files | `lspFindReferences(symbolName, lineHint)` → count unique files | Introduce facade/adapter or event-based decoupling |
-| `move-to-caller` | Read finding → confirm 1 consumer | `lspFindReferences(symbolName, lineHint)` → exactly 1 consumer file | Move symbol to consumer file or inline it |
-| `narrowable-type` | Read finding for broad vs narrow type info | `lspCallHierarchy(incoming)` → check argument types at all call sites | Narrow param type to match actual usage |
-
----
-
-## Change Risk Hotspots
-
-`architecture.json` → `hotFiles[]`: riskScore = fan-in + complexity + exports + cycle/critical-path membership.
-
-**CLI check**: `jq '.hotFiles[:5]' .octocode/scan/<ts>/architecture.json`
-
-**Octocode check**: `lspFindReferences` on top hotfile exports → map consumer blast radius.
-
-Prioritize for refactoring.
-
-## Mega-Folder Restructuring
-
-When the scan reports a mega-folder finding (flat directory with many loosely related files):
-
-1. **Map the import graph.** Use `localSearchCode` or `rg` to extract `from './...'` imports. Group files into clusters. Use LSP to confirm boundaries when ambiguous.
-2. **Design target structure.** Name directories after their role (e.g., types → parsing → analysis → detection → reporting).
-3. **Write a migration script.** Disposable Node.js/shell script that moves files and rewrites all relative import paths atomically. Path resolution: same dir → `./name.js`, root→subdir → `./subdir/name.js`, subdir→root → `../name.js`, across subdirs → `../other/name.js`.
-4. **Validate.** Run the project's lint, build, and test scripts after migration (see Project Environment in SKILL.md).
-5. **Delete the migration script.** One-shot tool, not part of the codebase.
-
-Prefer this over manual file-by-file moves when a directory has 15+ files in clearly separable domains.
-
----
-
-## Fix Validation Playbook
-
-After every fix batch, run the project's toolchain to catch regressions:
-
-| Step | Command | On Failure |
-|------|---------|------------|
-| 1. Lint (auto-fix) | `<pm> run lint --fix` (if supported) or `<pm> run lint` | Fix lint errors in changed code. Pre-existing errors: note but don't block |
-| 2. Tests | `<pm> run test` (scoped to package in monorepos) | Investigate immediately. If your fix broke it, revert or correct. Pre-existing: note and continue |
-| 3. Build | `<pm> run build` (scoped to package in monorepos) | Likely missing export or type error from your change — fix before continuing |
-
-**Detect lint auto-fix support**: check if the `lint` script wraps eslint (`--fix`), biome (`--write`), or oxlint (`--fix`). If uncertain, run without `--fix` first.
-
-**Monorepo scoping**: prefer `<pm> workspace <pkg> test` or `cd packages/<pkg> && <pm> run test` over root-level runs — faster feedback loop.
-
----
-
-## TDD Fix Playbook
-
-For behavioral fixes (logic changes, bug fixes, refactors that change observable behavior):
-
-| Step | Action | Tool |
-|------|--------|------|
-| 1. Understand behavior | Read the code and its callers | `localGetFileContent`, `lspCallHierarchy(incoming)` |
-| 2. Write failing test | Add a test that describes the expected post-fix behavior | Manual edit in test file |
-| 3. Run test | Confirm it fails for the right reason | `<pm> run test -- <test-file>` |
-| 4. Apply fix | Make the minimal change | Edit source file |
-| 5. Run test | Confirm it passes | `<pm> run test -- <test-file>` |
-| 6. Run full suite | Confirm no regressions | `<pm> run test` |
-
-**Skip TDD for**: comment removal, dead re-export deletion, import path rewrites, formatting, any change where the test would just assert "file doesn't contain X" — those are validated by lint + build instead.

package/skills/octocode-code-engineer/references/present-results.md

@@ -1,136 +0,0 @@
-# Present Results
-
-Read `summary.md` first — it has everything needed for a top-level presentation. Only drill into feature JSONs for investigation.
-
-For confidence tiers and how to label findings, see the **Confidence Tiers** table in [SKILL.md](../SKILL.md).
-
----
-
-## Summary Sections
-
-Fixed order — read top-down, stop when enough:
-
-1. **Scan Scope** — files, functions, flows, dependency files, packages
-2. **Findings Overview** — severity table + truncation notice + features-filter / scope / semantic notices
-3. **Health Scores** — 0-100 per pillar (Overall, Architecture, Code Quality, Dead Code, and conditionally Security, Test Quality) with letter grades (A-F)
-4. **Top Concern Tags** — searchable tags ranked by frequency, top 12 (filter `findings.json` with `jq '.optimizationFindings[] | select(.tags | contains(["coupling"]))'`)
-5. **Analysis Signals** — strongest graph signal, strongest AST signal, combined interpretation, confidence, recommended validation
-6. **Architecture Health** — dep graph metrics (modules, edges, cycles, critical paths, roots, leaves, test-only, unresolved) + all architecture categories with counts (0 = clean, `skipped` = filtered)
-7. **Change Risk Hotspots** — top 15 riskiest files (riskScore, fanIn, fanOut, complexity, exports, cycle/critical-path flags)
-8. **Code Quality** — all code-quality categories with counts
-9. **Dead Code & Hygiene** — all dead-code categories with counts
-10. **Security** *(conditional — only when security findings exist)* — all security categories with counts
-11. **Test Quality** *(conditional — only when test quality findings exist)* — all test-quality categories with counts
-12. **Top Recommendations** — 10 highest-severity findings (diverse by `--max-recs-per-category`)
-13. **AST Trees** *(conditional — only when tree output enabled)* — format guide + grep commands for navigation
-14. **Output Files** — table with file names, sizes, descriptions
-15. **Parse Errors** *(conditional — only when files failed to parse)* — up to 10 parse failures with file + message
-
----
-
-## Decision Heuristics
-
-The summary is not just a list of findings. Use it to choose the right investigation path.
-
-When the summary is ambiguous:
-
-- rerun with `--graph --graph-advanced` if the question is about cycles, chokepoints, package chatter, or startup risk
-- rerun with `--flow` if the question is about validation paths, cleanup behavior, or path-sensitive evidence
-- if graph and AST signals conflict, present that conflict and recommend a hybrid investigation instead of forcing one explanation
-
-### Graph-first signals
-
-Use graph-first language when the summary shows:
-
-- non-trivial `dependency-cycle` counts
-- multiple `criticalPaths`
-- high-risk entries in **Change Risk Hotspots**
-- `layer-violation`, `inferred-layer-violation`, or `distance-from-main-sequence`
-- `import-side-effect-risk` on high fan-in modules
-
-Good phrases:
-
-- "The architecture risk is concentrated around a small set of chokepoint modules."
-- "The dependency graph suggests a boundary leak between layers."
-- "The import graph shows startup risk because a high fan-in module performs work at import time."
-
-### AST-first signals
-
-Use AST-first language when the summary shows:
-
-- `low-cohesion` paired with `feature-envy`
-- duplicate flow or similar-function findings
-- large top-level side effects in `file-inventory.json`
-- structurally repeated orchestration or control-flow complexity
-
-Good phrases:
-
-- "The code shape suggests this module is doing multiple unrelated jobs."
-- "The repeated control-flow structure suggests orchestration duplication rather than an isolated bug."
-- "The AST evidence points to hidden initialization logic at module scope."
-
-### Combined signals
-
-Escalate when graph and AST signals align:
-
-- `critical-path` + `low-maintainability`
-- `feature-envy` + `layer-violation`
-- `import-side-effect-risk` + high `fanIn`
-- `low-cohesion` + many exports + disjoint consumers
-
-When they align, say so explicitly. That helps the user prioritize architectural work over local cleanup.
-
----
-
-## Presentation Template
-
-```markdown
-## Scan Summary
-- **Scope**: <n> files, <n> functions, <n> flows, <n> dependency edges
-- **Health**: Overall <n>/100 (grade) | Architecture <n>/100 | Quality <n>/100 | Hygiene <n>/100
-- **Findings**: <n> total — <n> critical, <n> high, <n> medium, <n> low
-- **Top Tags**: `coupling` (<n>), `dead-code` (<n>), `complexity` (<n>)
-- **Graph Signal**: <highest-signal graph interpretation backed by summary/architecture.json>
-- **AST Signal**: <highest-signal structural interpretation backed by findings/file-inventory>
-- **Combined Interpretation**: <how the graph and AST signals align or conflict>
-- **Confidence**: <high|medium|low>
-- **Recommended Validation**: <next Octocode local-tool step>
-
-## Top Findings (by severity)
-### Critical
-- `<file>:<line>` — <title> — <reason>
-### High
-- `<file>:<line>` — <title> — <reason>
-
-## Next Step
-Which findings should I investigate first?
-```
-
-Severity order: `critical` > `high` > `medium` > `low` > `info`.
-
----
-
-## Example Output
-
-A condensed real scan result for reference:
-
-```markdown
-## Scan Summary
-- **Scope**: 47 files, 312 functions, 89 flows, 186 dependency edges across 1 package
-- **Health**: Overall 61/100 (D) | Architecture 54/100 | Quality 72/100 | Hygiene 58/100
-- **Findings**: 83 total — 2 critical, 14 high, 41 medium, 26 low (capped to 50 by --findings-limit)
-- **Top Tags**: `coupling` (12), `dead-code` (9), `complexity` (8), `change-risk` (6), `duplication` (5)
-
-## Top Findings (by severity)
-### Critical
-- `src/tools/toolsManager.ts:45` — Critical dependency chain risk: 27 files — Break chain at `src/providers/factory.ts` (fan-out: 12, fan-in: 8) *(dependency-critical-path)*
-- `src/server.ts:12` — Dependency cycle detected (4 node cycle) — src/server.ts -> src/session.ts -> src/config.ts -> src/server.ts *(dependency-cycle)*
-
-### High
-- `src/utils/helpers.ts:1` — 6 unused exports — Exported symbols have no observed import usage *(dead-export)*
-- `src/providers/github.ts:89` — Potential function refactor: fetchWithRetries — Cyclomatic-like complexity is high (>=30). Branch depth is very deep. *(function-optimization)*
-- `src/tools/localSearch.ts:142` — Input passthrough without validation — Parameter `query` flows to child_process.spawn without sanitization *(input-passthrough-risk)*
-
-## Next Step
-Which findings should I investigate first?
-```