fusion/coverage-report/README.md

Code Coverage Report

Generated: 2026-04-01 | Task: FN-689

This directory contains the results of a comprehensive code coverage analysis across all packages in the kb monorepo.

How to Run Coverage

All Packages

pnpm test:coverage

⚠️ Engine package will OOM when running with coverage. See Known Issues.

Individual Packages

pnpm test:coverage:core
pnpm test:coverage:engine    # Will likely OOM — see workaround below
pnpm test:coverage:cli
pnpm test:coverage:dashboard

Engine Workaround

Run a subset of engine tests with coverage:

cd packages/engine
npx vitest run --coverage --coverage.reportOnFailure --maxWorkers=1 \
  src/concurrency.test.ts \
  src/worktree-names.test.ts \
  src/notifier.test.ts \
  src/logger.test.ts \
  src/agent-heartbeat.test.ts

Generate Report with Test Failures

By default, vitest skips coverage output when tests fail. Use --coverage.reportOnFailure to generate reports even with failures:

cd packages/core
npx vitest run --coverage --coverage.reportOnFailure

Coverage Output

Each package generates reports in its coverage/ directory:

• coverage/index.html — Interactive HTML report (open in browser)
• coverage/coverage-final.json — Machine-readable JSON data
• Terminal output includes a text summary table

Note: coverage/ directories are in .gitignore and should not be committed.

How to Read the Reports

This Directory

File	Description
gaps.md	Detailed analysis of all coverage gaps — untested files, low-coverage areas, and pre-existing test failures
summary.json	Machine-readable JSON with per-package metrics, untested file lists, and low-coverage file lists
README.md	This file — instructions and overview

HTML Reports

After running coverage, open packages/<name>/coverage/index.html in your browser for an interactive report showing:

• Per-file line/function/branch coverage
• Highlighted uncovered lines
• Sortable columns

summary.json Structure

{
  "generatedAt": "ISO timestamp",
  "packages": {
    "core": { "lineCoverage": 80.63, "functionCoverage": 91.26, ... },
    "engine": { "lineCoverage": 6.04, "note": "Partial — OOM" },
    "cli": { "lineCoverage": 36.17, ... },
    "dashboard": { "lineCoverage": 70.21, ... }
  },
  "overall": { "lineCoverage": X, ... },
  "untestedFiles": [ ... ],
  "lowCoverageFiles": [ ... ]
}

Top 10 Files Needing Attention

#	Package	File	Coverage	Issue
1	dashboard	src/mission-routes.ts	37% lines	1,137-line API surface — mission endpoints
2	cli	commands/task.ts	17% lines	Primary CLI interface (1,486 lines)
3	core	agent-store.ts	0%	597 lines with zero test coverage
4	dashboard	src/terminal.ts	37% lines	Terminal service — 8/9 functions untested
5	dashboard	src/server.ts	29% lines	Server initialization
6	engine	ipc/ipc-host.ts	0%	IPC host — no tests exist
7	engine	ipc/ipc-worker.ts	0%	IPC worker — no tests exist
8	cli	project-resolver.ts	28% lines	Multi-project resolution (915 lines)
9	dashboard	src/subtask-breakdown.ts	51% lines	AI subtask feature
10	dashboard	NewTaskModal.tsx	47% / 13% funcs	Complex modal, many untested paths

Recommendations

Immediate Actions (High Impact)

1. Add tests for core/agent-store.ts — This is a 597-line business logic module with zero tests. It manages agent state and is used across the engine.

2. Improve CLI commands/task.ts coverage — At 17% line coverage, the most-used CLI commands lack test assertions. Focus on create, list, show, move, and archive subcommands.

3. Add tests for dashboard/src/mission-routes.ts — The entire missions API (1,137 lines) has only 37% coverage. Route handlers need request/response testing.

4. Fix engine OOM for coverage — The engine package can't run coverage at all due to heap exhaustion. Investigate memory leaks in test setup/teardown (likely in executor or scheduler tests).

Medium-Term

5. Add IPC host/worker tests — The multi-project IPC layer (ipc-host.ts, ipc-worker.ts) has no tests at all, which is risky for a communication protocol.

6. Test CLI backup/settings commands — commands/backup.ts, commands/settings-export.ts, commands/settings-import.ts have zero tests.

7. Improve dashboard server coverage — server.ts (29%), terminal.ts (37%), planning.ts (42%) all need more tests.

Long-Term

8. Fix pre-existing test failures — 4 failures in core (db-migrate, store), 111 failures in CLI (many related to project resolution mocking).

9. Dashboard component test coverage — Several components (NewTaskModal, SettingsModal, SetupWizardModal) have tests but with significant gaps in function coverage.

10. Set coverage thresholds — Once coverage improves, enable vitest coverage thresholds to prevent regression:

    coverage: {
      thresholds: {
        lines: 60,
        functions: 60,
        branches: 50,
      }
    }
    

Known Issues

Engine OOM

Engine tests consistently crash with FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory when run with coverage, even with:

• --max-old-space-size=8192
• --maxWorkers=1
• --fileParallelism=false

This appears to be a pre-existing issue (OOM occurs even without coverage enabled). The v8 coverage provider's instrumentation adds significant memory overhead on top of an already memory-intensive test suite.

Workaround: Run small subsets of engine tests with coverage (5-7 files at a time).

Pre-existing Test Failures

Some test failures exist in the codebase independent of coverage changes:

• Core: 4 failures in db-migrate.test.ts and store.test.ts
• CLI: Multiple failures related to project resolution
• See gaps.md for full details

Coverage Configuration

Coverage is configured in each package's vitest.config.ts. By default, enabled: false to avoid slowing CI. Use --coverage flag or pnpm test:coverage to enable.

// packages/*/vitest.config.ts
coverage: {
  enabled: false,  // Enable via CLI flag
  reporter: ["text", "html", "json"],
  reportsDirectory: "./coverage",
  include: ["src/**/*.ts"],
  exclude: ["**/*.test.ts", "**/*.d.ts", "dist/**"],
}