CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

coverage-visualizer is a VS Code extension (TypeScript) that visualizes Python test coverage inline in the editor. It reads Python's .coverage SQLite file (generated by coverage.py), exports it to JSON via the coverage json CLI, then applies green/red line decorations to open editors.

Commands

npm run compile          # compile TypeScript → out/
npm run watch            # compile in watch mode during development
npm test                 # run Jest unit tests
npm run test:watch       # Jest in watch mode
npm run test:coverage    # Jest with coverage report (outputs to coverage/)
npm run lint             # ESLint on src/
vsce package             # build .vsix for distribution
vsce publish             # publish to VS Code Marketplace

Run a single test file:

npx jest tests/coverageParser.test.ts

Run a single test by name:

npx jest -t "groups consecutive lines"

To launch the extension in a dev host window, open this project in VS Code and press F5 (or use Run and Debug panel → "Run Extension"). This compiles first via the default build task, then opens a second VS Code window with the extension loaded.

Architecture

The extension is split into two layers intentionally:

src/coverageParser.ts — pure logic, no VS Code dependency All data transformation lives here: parsing the raw coverage json output (RawCoverageJson), normalising it into CoverageReport, matching file paths, and collapsing line numbers into contiguous ranges (toLineRanges). This module is independently testable with Jest.

src/extension.ts — VS Code integration only Handles activation, command registration, decoration lifecycle, and the onDidChangeActiveTextEditor listener that re-applies decorations when the user switches files. The current CoverageReport is held in module-level state (currentReport) so decorations can be reapplied without re-reading the file.

Data flow:

pytest --cov=. --cov-report=json
  → coverage.json  (plain JSON in workspace root)
  → parseCoverageJson()
  → CoverageReport
  → applyToEditor() per visible editor

The extension reads coverage.json directly — it has no Python runtime dependency. Users generate coverage.json once with pytest-cov; the extension watches it for changes and auto-reloads.

File watcher: extension.ts sets up a vscode.FileSystemWatcher on coverage.json at activation. When the file is created, changed, or deleted, decorations update automatically without running any command.

Testing

Unit tests are in tests/ and cover only coverageParser.ts. The vscode module is mocked at tests/__mocks__/vscode.ts — Jest resolves it via moduleNameMapper in jest.config.ts.

tests/fixtures/coverage.json is the realistic dummy fixture used in tests — it has three files: one partially covered, one 100%, one 0%. When adding new parser behaviour, extend the fixture rather than creating separate files.

extension.ts is not unit tested directly — it requires a real VS Code host. Test it manually via F5.

Key constraints

• The file matching in findFileInReport uses a suffix/contains check against the keys in coverage.json. Coverage.py stores relative paths (e.g. src/calculator.py) as keys. Absolute paths from VS Code are matched against these. This is imprecise and will break if the workspace root does not 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 the source is .ts). Do not change to CommonJS — the VS Code extension host expects ES module-compatible output.
• better-sqlite3 is listed as a dependency but is not used — remove it when adding the next feature rather than carrying dead weight.