octocode-cli 1.2.8 → 1.2.10

package/skills/octocode-research/.octocode/scan/2026-03-22T10-40-10-469Z/summary.md

@@ -0,0 +1,265 @@
+# Code Quality Scan Report
+
+**Generated**: 2026-03-22T10:40:13.784Z  
+**Root**: `/Users/guybary/Documents/octocode-mcp/skills/octocode-research`
+
+## Scan Scope
+
+| Metric | Count |
+|--------|-------|
+| Files analyzed | 36 |
+| Functions | 286 |
+| Flow nodes | 357 |
+| Dependency files | 53 |
+| Packages | 1 |
+
+## Findings Overview
+
+| Severity | Count |
+|----------|-------|
+| Critical | 7 |
+| High | 126 |
+| Medium | 90 |
+| Low | 84 |
+| **Total** | **307** |
+
+> **Scoped scan**: Only showing findings for: `src`
+
+> **Semantic analysis**: TypeChecker + LanguageService enabled (14 additional categories)
+
+## Health Scores
+
+| Pillar | Score | Grade |
+|--------|-------|-------|
+| **Overall** | **17/100** | **F** |
+| Architecture | 38/100 | D |
+| Code Quality | 68/100 | B |
+| Dead Code & Hygiene | 29/100 | D |
+| Security | 73/100 | B |
+| Test Quality | 100/100 | A |
+
+## Top Concern Tags
+
+Searchable tags across all findings — use to filter `findings.json` with `jq`.
+
+- `dead-code`: 195 findings
+- `semantic`: 135 findings
+- `refactoring`: 77 findings
+- `module-surface`: 73 findings
+- `architecture`: 70 findings
+- `cleanup`: 59 findings
+- `api-surface`: 58 findings
+- `dependency`: 26 findings
+- `security`: 22 findings
+- `performance`: 20 findings
+- `change-risk`: 17 findings
+- `injection`: 15 findings
+
+## Analysis Signals
+
+- **Graph Signal**: src/utils/responseBuilder.ts concentrates dependency pressure (articulation point, 1 bridge edge(s), on critical path, high complexity risk (109)).
+- **AST Signal**: src/server-init.ts performs import-time work that matches the reported side-effect risk.
+- **Combined Interpretation**: Structural chokepoint and Hidden initialization logic both appear in this scan, so use a hybrid investigation instead of a single-lens conclusion.
+- **Confidence**: medium
+- **Recommended Validation**: navigate to the awaited call to check if parallelization is safe (tools: localSearchCode -> lspGotoDefinition)
+
+**Investigation Prompts**
+- Inspect src/utils/responseBuilder.ts first and validate the graph claim with localSearchCode plus LSP navigation.
+- Use file-inventory.json for src/server-init.ts to explain why the code shape matches the finding.
+- Use a hybrid investigation before proposing a refactor because the signals do not fully align yet.
+- Cross-check the top hotspot src/utils/logger.ts with the strongest architecture finding before editing code.
+
+## Architecture Health
+
+> 67 findings (score: 38/100) — see [`architecture.json`](./architecture.json)
+
+| Metric | Value |
+|--------|-------|
+| Modules | 53 |
+| Import edges | 93 |
+| Cycles | 0 |
+| Critical paths | 12 |
+| Root modules | 21 |
+| Leaf modules | 22 |
+| Test-only modules | 4 |
+| Unresolved imports | 0 |
+
+- `dependency-cycle`: 0
+- `dependency-critical-path`: 7
+- `dependency-test-only`: 4
+- `architecture-sdp-violation`: 1
+- `high-coupling`: 0
+- `god-module-coupling`: 0
+- `orphan-module`: 3
+- `unreachable-module`: 12
+- `layer-violation`: 0
+- `low-cohesion`: 2
+- `mega-folder`: 0
+- `distance-from-main-sequence`: 7
+- `feature-envy`: 3
+- `untested-critical-code`: 10
+- `over-abstraction`: 14
+- `concrete-dependency`: 0
+- `circular-type-dependency`: 0
+- `shotgun-surgery`: 0
+- `import-side-effect-risk`: 2
+- `cycle-cluster`: 0
+- `broker-module`: 0
+- `bridge-module`: 0
+- `package-boundary-chatter`: 0
+- `startup-risk-hub`: 0
+- `namespace-import`: 0
+- `commonjs-in-esm`: 0
+- `export-star-leak`: 2
+- `mixed-module-format`: 0
+
+## Change Risk Hotspots
+
+Files most dangerous to change — high fan-in, complexity, or cycle membership.
+
+| File | Risk | Fan-In | Fan-Out | Complexity | Exports | Cycle | Critical Path |
+|------|------|--------|---------|------------|---------|-------|---------------|
+| `src/utils/logger.ts` | 97 | 4 | 2 | 112 | 12 | - | Y |
+| `src/utils/responseBuilder.ts` | 87 | 6 | 0 | 109 | 3 | - | Y |
+| `src/validation/schemas.ts` | 84 | 2 | 1 | 37 | 39 | - | - |
+| `src/utils/circuitBreaker.ts` | 75 | 4 | 3 | 70 | 11 | - | Y |
+| `src/routes/tools.ts` | 58 | 1 | 8 | 79 | 1 | - | Y |
+| `src/types/guards.ts` | 55 | 6 | 0 | 40 | 11 | - | - |
+| `src/server.ts` | 54 | 0 | 11 | 71 | 2 | - | Y |
+| `src/routes/lsp.ts` | 51 | 1 | 7 | 65 | 1 | - | Y |
+| `src/utils/retry.ts` | 50 | 2 | 1 | 66 | 7 | - | - |
+| `src/routes/github.ts` | 45 | 1 | 7 | 54 | 1 | - | Y |
+| `src/types/errorGuards.ts` | 45 | 1 | 0 | 47 | 12 | - | - |
+| `src/utils/resilience.ts` | 45 | 5 | 3 | 21 | 5 | - | Y |
+| `src/utils/responseFactory.ts` | 44 | 4 | 2 | 38 | 8 | - | - |
+| `src/routes/local.ts` | 41 | 1 | 7 | 46 | 1 | - | Y |
+| `src/utils/responseParser.ts` | 41 | 3 | 0 | 43 | 7 | - | - |
+
+## Code Quality
+
+> 41 findings (score: 68/100) — see [`code-quality.json`](./code-quality.json)
+
+- `duplicate-function-body`: 0
+- `duplicate-flow-structure`: 0
+- `function-optimization`: 0
+- `cognitive-complexity`: 4
+- `god-module`: 1
+- `god-function`: 0
+- `halstead-effort`: 0
+- `low-maintainability`: 0
+- `excessive-parameters`: 2
+- `unsafe-any`: 0
+- `empty-catch`: 3
+- `switch-no-default`: 0
+- `unused-parameter`: 0
+- `deep-override-chain`: 0
+- `interface-compliance`: 0
+- `type-assertion-escape`: 2
+- `promise-misuse`: 2
+- `narrowable-type`: 4
+- `missing-error-boundary`: 3
+- `await-in-loop`: 4
+- `sync-io`: 4
+- `uncleared-timer`: 2
+- `listener-leak-risk`: 6
+- `unbounded-collection`: 0
+- `similar-function-body`: 4
+- `message-chain`: 0
+
+## Dead Code & Hygiene
+
+> 177 findings (score: 29/100) — see [`dead-code.json`](./dead-code.json)
+
+- `dead-export`: 55
+- `dead-re-export`: 1
+- `re-export-duplication`: 1
+- `re-export-shadowed`: 0
+- `unused-npm-dependency`: 0
+- `package-boundary-violation`: 0
+- `barrel-explosion`: 0
+- `unused-import`: 0
+- `orphan-implementation`: 0
+- `move-to-caller`: 73
+- `semantic-dead-export`: 44
+- `dead-file`: 3
+
+## Security
+
+> 22 findings (score: 73/100) — see [`security.json`](./security.json)
+
+- `hardcoded-secret`: 1
+- `eval-usage`: 0
+- `unsafe-html`: 0
+- `sql-injection-risk`: 2
+- `unsafe-regex`: 0
+- `prototype-pollution-risk`: 6
+- `unvalidated-input-sink`: 7
+- `input-passthrough-risk`: 6
+- `path-traversal-risk`: 0
+- `command-injection-risk`: 0
+- `debug-log-leakage`: 0
+- `sensitive-data-logging`: 0
+
+## Test Quality
+
+> 0 findings (score: 100/100) — no `test-quality.json` written for this scan
+
+- `low-assertion-density`: 0
+- `test-no-assertion`: 0
+- `excessive-mocking`: 0
+- `shared-mutable-state`: 0
+- `missing-test-cleanup`: 0
+- `focused-test`: 0
+- `fake-timer-no-restore`: 0
+- `missing-mock-restoration`: 0
+
+> **Note**: Test Quality reflects analyzed test files only. 10 modules flagged as `untested-critical-code` (architecture pillar) have no test coverage — use `--include-tests` for test-quality analysis.
+
+## Top Recommendations
+
+- **[CRITICAL]** `src/server.ts` — Critical dependency chain risk: 6 files (2 entry points) *(dependency-critical-path)* 
+- **[CRITICAL]** `src/__tests__/integration/routes.test.ts` — Critical dependency chain risk: 6 files (2 entry points) *(dependency-critical-path)* 
+- **[HIGH]** `src/server-init.ts` — await inside loop — sequential async execution *(await-in-loop)* 
+- **[HIGH]** `src/server-init.ts` — await inside loop — sequential async execution *(await-in-loop)* 
+- **[HIGH]** `src/utils/responseParser.ts` — High cognitive complexity: parseToolResponse (29) *(cognitive-complexity)* 
+- **[HIGH]** `src/utils/responseParser.ts` — High cognitive complexity: parseToolResponseBulk (30) *(cognitive-complexity)* 
+- **[HIGH]** `src/types/errorGuards.ts` — Unused export: hasMessage *(dead-export)* 
+- **[HIGH]** `src/types/errorGuards.ts` — Unused export: hasHeaders *(dead-export)* 
+- **[HIGH]** `src/mcpCache.ts` — Distance from Main Sequence: src/mcpCache.ts (D=1.00) *(distance-from-main-sequence)* 
+- **[HIGH]** `src/types/guards.ts` — Distance from Main Sequence: src/types/guards.ts (D=1.00) *(distance-from-main-sequence)* 
+
+## AST Trees (`ast-trees.txt`)
+
+Compact indented text format — each node is `Kind[startLine:endLine]`, nesting = indentation.
+
+Run these commands from the skill directory. Current scan: `.octocode/scan/2026-03-22T10-40-10-469Z`.
+
+```
+SourceFile[1:152]
+  ImportDeclaration[1]
+  FunctionDeclaration[3:20]
+    Block[4:19]
+      IfStatement[5:12] ...
+```
+
+**Smart navigation:**
+
+- Find functions: `node scripts/ast/tree-search.js -i "/Users/guybary/Documents/octocode-mcp/skills/octocode-research/.octocode/scan/2026-03-22T10-40-10-469Z/ast-trees.txt" -k function_declaration --limit 25`
+- Find classes: `node scripts/ast/tree-search.js -i "/Users/guybary/Documents/octocode-mcp/skills/octocode-research/.octocode/scan/2026-03-22T10-40-10-469Z/ast-trees.txt" -k class_declaration --limit 25`
+- Find control flow: `node scripts/ast/tree-search.js -i "/Users/guybary/Documents/octocode-mcp/skills/octocode-research/.octocode/scan/2026-03-22T10-40-10-469Z/ast-trees.txt" -p 'IfStatement|SwitchStatement|ForStatement|WhileStatement' --limit 25`
+- Narrow to one file: `node scripts/ast/tree-search.js -i "/Users/guybary/Documents/octocode-mcp/skills/octocode-research/.octocode/scan/2026-03-22T10-40-10-469Z/ast-trees.txt" --file "/Users/guybary/Documents/octocode-mcp/skills/octocode-research/src" -k function_declaration --limit 10`
+- Raw text fallback: `rg 'FunctionDeclaration|IfStatement' "/Users/guybary/Documents/octocode-mcp/skills/octocode-research/.octocode/scan/2026-03-22T10-40-10-469Z/ast-trees.txt"`
+
+## Output Files
+
+| File | Size | Description |
+|------|------|-------------|
+| [`summary.json`](./summary.json) | 29.0 KB | Scan metadata, agent output, parse errors |
+| [`architecture.json`](./architecture.json) | 134.4 KB | Dependency graph, cycles, critical paths, architecture findings |
+| [`code-quality.json`](./code-quality.json) | 56.5 KB | Duplicate detection, complexity, god modules/functions |
+| [`dead-code.json`](./dead-code.json) | 247.2 KB | Dead files/exports/re-exports, unused deps, boundary violations |
+| [`file-inventory.json`](./file-inventory.json) | 400.4 KB | Per-file function/flow/dependency details |
+| [`findings.json`](./findings.json) | 437.8 KB | All findings across all categories (master list) |
+| [`security.json`](./security.json) | 42.6 KB | security |
+| [`graph.md`](./graph.md) | 9.7 KB | Mermaid dependency graph |
+| [`ast-trees.txt`](./ast-trees.txt) | 141.0 KB | AST tree snapshots (compact indented text — grep/regex friendly) |

package/skills/octocode-research/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Octocode Research — Changelog
+
+## Detached Daemon Architecture
+
+`server-init.ts` no longer keeps the server as a child process. The server is now spawned **detached** (`detached: true`, `child.unref()`) so no client owns it. Every `server-init` invocation exits after confirming health — whether it spawned the server or found it already running. The server self-manages its lifecycle via the existing 30-minute idle timeout and SIGTERM handling.
+
+- **PID file**: `server.ts` writes `~/.octocode/research-server-{PORT}.pid` on startup, removes on shutdown
+- **Multi-client safe**: multiple agents/IDEs share one server instance without ownership conflicts
+- **`/health` endpoint**: now includes `pid` field and `processManager: 'self (detached daemon)'`
+- **Tests**: lifecycle tests updated to verify detached behavior (init exits, server survives, PID file lifecycle)
+
+---
+
+**36 files changed** | +1,456 −2,391 | Net: **−935 lines**
+
+---
+
+## Dead Code Removal
+
+Deleted `src/types/toolTypes.ts`, `src/utils/logEmoji.ts`. Removed unused exports from 15 files (`errorGuards`, `guards`, `responses`, `mcp`, `circuitBreaker`, `logger`, `responseFactory`, `responseParser`, `retry`, `resilience`, `routeFactory`, `schemas`, `toolCallSchema`, `httpPreprocess`, `index`). Removed unused `queryParser` middleware.
+
+## Bug Fixes
+
+- **Port fallback**: `server.ts` now reads `OCTOCODE_PORT` like `server-init.ts`
+- **Version mismatch**: routes hardcoded `2.0.0` while package.json said `2.2.0` — fixed via build-time `__PACKAGE_VERSION__` injection
+- **Missing routes**: added `GET /tools/info` and `GET /tools/metadata` to 404 handler + startup log
+- **PM2 cleanup**: replaced `processManager: 'pm2'`, removed `process.send('ready')`
+- **Empty JSON Schemas**: `zod-to-json-schema` produced empty `{}` for Zod v4 schemas — replaced with `z.toJSONSchema()` (native Zod v4), removed `zod-to-json-schema` dependency. All 13 tool schemas now return full properties, types, and constraints.
+
+## `bin` → Init Lifecycle
+
+`"bin"` now points to `server-init.js` (was `server.js`). `npx octocode-research` gets health polling, parent-child lifecycle, and graceful shutdown. All PM2 scripts removed.
+
+## Version — Single Source of Truth
+
+`tsdown.config.ts` reads `package.json` at build time, injects `__PACKAGE_VERSION__`. Version bump = edit `package.json` only.
+
+## `server-init.ts` Rewrite (288 → 55 lines)
+
+PM2-based init replaced with standalone lifecycle: health-check → spawn child → exponential backoff poll → stay alive → signal forwarding.
+
+## Route Refactors
+
+Extracted helpers in `lsp.ts` and `package.ts` to reduce cognitive complexity.
+
+## Documentation
+
+- **SKILL.md** (→ 380 lines): all 11 routes, 503 warm-up note, env var table, parallel/session sections extracted to `references/`
+- **README.md** (→ 209 lines): "Why a Server?" section, corrected examples with required `id` field, accurate per-circuit resilience table
+- **package.json**: renamed `octocode-skill` → `octocode-research`, removed PM2 scripts, removed `zod-to-json-schema`
+
+## New Files
+
+- `references/SESSION_MANAGEMENT.md` — checkpoint/resume protocol
+- `src/__tests__/integration/serverLifecycle.test.ts` — init/shutdown tests
+- `src/__tests__/unit/schemas.test.ts` — Zod schema validation tests (509 lines)
+
+## Verification
+
+Build OK | Lint 0 errors | Tests 215/215