Skip to content

DEV.md

Latest commit

 

History

History
146 lines (106 loc) · 4.8 KB

DEV.md

File metadata and controls

146 lines (106 loc) · 4.8 KB

Developer Guide — Python Coverage Visualizer

Everything you need to run, test, extend, and contribute to this extension.

Prerequisites

  • Node.js 20+
  • VS Code 1.90+
  • npm (comes with Node)

Setup

git clone https://github.com/kool7/coverage-visualizer.git
cd coverage-visualizer
npm install
npm run compile

Press F5 in VS Code to open the Extension Development Host with the extension loaded.

Architecture

The extension is split into two intentional layers:

src/parsers/coverageParser.ts — pure logic, no VS Code dependency All data transformation: parsing coverage.json / coverage.xml / .coverage SQLite, normalising into a unified CoverageReport, matching file paths, collapsing line numbers into ranges. Independently testable with Jest.

src/extension.ts — VS Code integration only Activation, command registration, decoration lifecycle, onDidChangeActiveTextEditor listener, and file watchers. Holds the current CoverageReport in module-level state so decorations reapply without re-reading from disk.

Data flow:

pytest --cov=. --cov-report=json
  → coverage.json  (or .xml or .coverage)
  → parser (coverageParser.ts)
  → CoverageReport (unified in-memory model)
  → applyToEditor() per open editor
  → CodeLens / Hover / TreeView / StatusBar / Dashboard

File watcher: activated at startup on coverage.json, coverage.xml, and .coverage. Create, change, or delete triggers an automatic re-parse and redecorate.

Project Structure

src/
  extension.ts            # Entry point — commands, decorations, watchers
  config.ts               # Typed wrapper for all extension settings
  parsers/
    coverageParser.ts     # JSON, XML, SQLite parsers + shared utilities
  providers/
    codeLensProvider.ts   # Coverage % above def/class
    hoverProvider.ts      # Hover tooltip on highlighted lines
    treeProvider.ts       # Explorer sidebar tree view
  ui/
    dashboardPanel.ts     # WebView dashboard (ring chart, file table)
    statusBar.ts          # Status bar item

tests/
  coverageParser.test.ts  # Jest tests for all three parser formats
  fixtures/
    coverage.json         # Realistic JSON fixture (3 files: partial/100%/0%)
    coverage.xml          # Cobertura XML fixture
    .coverage             # SQLite fixture (generated by scripts/)
    src/                  # Python source files for SQLite missing-line inference
  __mocks__/vscode.ts     # VS Code API mock for Jest

scripts/
  generate-test-coverage-db.mjs  # Regenerates tests/fixtures/.coverage

assets/
  demo.gif                # Marketplace demo GIF

Commands

npm run compile        # TypeScript → out/
npm run watch          # Recompile on save (dev mode)
npm test               # Run all Jest tests
npm run test:watch     # Jest in watch mode
npm run test:coverage  # Jest with coverage report (→ coverage/)
npm run lint           # ESLint on src/

Run a single test file:

npx jest tests/coverageParser.test.ts

Run a single test by name:

npx jest -t "groups consecutive lines"

Regenerating Test Fixtures

The .coverage SQLite fixture is synthetic — generated from a script so no Python installation is required:

node scripts/generate-test-coverage-db.mjs
cp demo-python-project/.coverage tests/fixtures/.coverage

Run this whenever you change which lines are executed in scripts/generate-test-coverage-db.mjs. The Python source files in tests/fixtures/src/ must match whatever the fixture expects for missing-line inference to work.

Adding a New Coverage Format

  1. Add parseXxx(input): CoverageReport in src/parsers/coverageParser.ts
  2. Add format detection in detectAndParse() in src/extension.ts
  3. Add a file watcher pattern in setupWatchers() in src/extension.ts
  4. Add a fixture file in tests/fixtures/ and tests in tests/coverageParser.test.ts

Key Constraints

  • File matching — findFileInReport uses a suffix/contains check against coverage file keys. Coverage.py stores relative paths (e.g. src/calc.py); VS Code provides absolute paths. This breaks if the workspace root doesn't contain the relative path as a suffix — a known gap.
  • module: "Node16" in tsconfig requires explicit .js extensions on relative imports in source files, even though they're .ts. Do not change to CommonJS.
  • better-sqlite3 is listed as a dependency but is unused — remove it when adding the next feature.

Pull Request Guidelines

  • One feature or fix per PR — keep it focused
  • All existing tests must pass: npm test
  • TypeScript must compile cleanly: npm run compile
  • Add tests for any new parser logic or bug fixes
  • Write a clear PR description with what changed and why
  • Branch naming: feat/, fix/, chore/ — no direct commits to main