simplecov-mcp 0.3.0 → 1.0.0

data/docs/ARCHITECTURE.md

@@ -0,0 +1,79 @@
+# Architecture
+
+simplecov-mcp is organized around a single coverage data model that feeds three delivery channels: a command-line interface, an MCP server for LLM agents, and a light-weight Ruby API. The codebase is intentionally modular—shared logic for loading, normalizing, and validating SimpleCov data lives in `lib/simplecov_mcp/`, while adapters wrap that core for each runtime mode.
+
+## Runtime Entry Points
+
+- **Executable** – `exe/simplecov-mcp` bootstraps the gem, enforces Ruby >= 3.2, and delegates to `SimpleCovMcp.run(ARGV)`.
+- **Mode Negotiation** – `SimpleCovMcp.run` inspects environment defaults from `SIMPLECOV_MCP_OPTS`, checks for CLI subcommands, and defaults to CLI mode when STDIN is a TTY. Otherwise it instantiates `SimpleCovMcp::MCPServer` for MCP protocol communication over STDIO.
+- **Embedded Usage** – Applications embed the gem by instantiating `SimpleCovMcp::CoverageModel` directly, optionally wrapping work in `SimpleCovMcp.with_context` to install a library-oriented error handler.
+
+## Coverage Data Pipeline
+
+1. **Resultset discovery** – The tool locates the `.resultset.json` file by checking a series of default paths or by using a path specified by the user. For a detailed explanation of the configuration options, see the [Configuring the Resultset](../README.md#configuring-the-resultset) section in the main README.
+2. **Parsing and normalization** – `CoverageModel` loads the chosen resultset once, selects the first suite that exposes `coverage`, and maps all file keys to absolute paths anchored at the configured project root. Timestamps are cached for staleness checks.
+3. **Path relativizing** – `PathRelativizer` produces relative paths for user-facing payloads without mutating the canonical data. Tool responses pass through `CoverageModel#relativize` before leaving the process.
+4. **Derived metrics** – `CovUtil.summary`, `CovUtil.uncovered`, and `CovUtil.detailed` compute coverage stats from the raw `lines` arrays. `CoverageModel` exposes `summary_for`, `uncovered_for`, `detailed_for`, and `raw_for` helpers that wrap these utilities.
+5. **Staleness detection** – `StalenessChecker` compares source mtimes/line counts to coverage metadata. CLI flags and MCP arguments can promote warnings to hard failures (`--stale error`) or simply mark rows as stale for display.
+
+## Interfaces
+
+### CLI (`SimpleCovMcp::CoverageCLI`)
+
+- Builds on Ruby’s `OptionParser`, with global options such as `--resultset`, `--stale`, `--json`, and `--source` modes.
+- Subcommands (`list`, `summary`, `raw`, `uncovered`, `detailed`, `version`) translate to calls on `CoverageModel`.
+- Uses `ErrorHandlerFactory.for_cli` to convert unexpected exceptions into friendly user messages while honoring `--error-mode`.
+- Formatting logic (tables, JSON) lives in the model to keep presentation consistent with MCP responses.
+
+### MCP Server (`SimpleCovMcp::MCPServer`)
+
+- Assembles a list of tool classes and mounts them in `MCP::Server` using STDIO transport.
+- Relies on the same core model; each tool instance recreates `CoverageModel` with the arguments provided by the MCP client, keeping the server stateless between requests.
+- Error handling delegates to `BaseTool.handle_mcp_error`, which swaps in the MCP-specific handler and emits `MCP::Tool::Response` objects.
+
+### Library API
+
+- Consuming code instantiates `CoverageModel` directly for fine-grained control over coverage queries.
+- Use `SimpleCovMcp::ErrorHandlerFactory.for_library` together with `SimpleCovMcp.with_context` when an embedded caller wants to suppress CLI-friendly error logging.
+
+## MCP Tool Stack
+
+- `SimpleCovMcp::BaseTool` centralizes JSON schema definitions, error conversion, and response serialization for the MCP protocol.
+- Individual tools reside in `lib/simplecov_mcp/tools/` and follow a consistent shape: define an input schema, call into `CoverageModel`, then serialize via `respond_json`. Examples include `AllFilesCoverageTool`, `CoverageSummaryTool`, and `UncoveredLinesTool`.
+- Tools are registered in `SimpleCovMcp::MCPServer#run`. Adding a new tool only requires creating a subclass and appending it to that list.
+
+## Error Handling & Logging
+
+- Custom exceptions under `lib/simplecov_mcp/errors.rb` capture context for configuration issues, missing files, stale coverage, and general runtime errors. Each implements `#user_friendly_message` for consistent UX.
+- `SimpleCovMcp::ErrorHandler` encapsulates logging and severity decisions. Modes (`:off`, `:on`, `:trace`) control whether errors are recorded and whether stack traces are included.
+- Runtime configuration (error handlers, log destinations) flows through `SimpleCovMcp::AppContext`. Entry points push a context with `SimpleCovMcp.with_context`, which stores the active configuration in a thread-local slot (`SimpleCovMcp.context`). Nested calls automatically restore the previous context when the block exits, ensuring isolation even when multiple callers share a process or thread.
+- Two helper accessors clarify intent:
+  - `SimpleCovMcp.default_log_file` / `default_log_file=` adjust the baseline log sink that future contexts inherit.
+  - `SimpleCovMcp.active_log_file` / `active_log_file=` mutate only the current context (or create one on demand) so the change applies immediately without touching the default.
+- `ErrorHandlerFactory` wires the appropriate handler per runtime: CLI, MCP server, or embedded library, each of which installs its handler inside a fresh `AppContext` before executing user work.
+- Diagnostics are written via `CovUtil.log` to `simplecov_mcp.log` in the current directory by default; override with CLI `--log-file`, set `SimpleCovMcp.default_log_file` for future contexts, or temporarily tweak `SimpleCovMcp.active_log_file` when a caller needs a different destination mid-run.
+
+## Configuration Surface
+
+- **Environment defaults** – `SIMPLECOV_MCP_OPTS` applies baseline CLI flags before parsing the actual command line.
+- **Resultset overrides** – The location of the `.resultset.json` file can be specified via CLI options or in the MCP configuration. See [Configuring the Resultset](../README.md#configuring-the-resultset) for details.
+- **Tracked globs** – For project staleness checks, `tracked_globs` ensures new files raise alerts when absent from coverage.
+- **Colorized source** – CLI-only flags (`--source`, `--source-context`, `--color`) enhance human-readable reports when working locally.
+
+## Repository Layout Highlights
+
+- `lib/simplecov_mcp/` – Core runtime (model, utilities, error handling, CLI, MCP server, tools).
+- `lib/simplecov_mcp.rb` – Primary public entry point required by gem consumers.
+- `docs/` – User-facing guides (usage, installation, troubleshooting, architecture).
+- `spec/` – RSpec suite with fixtures under `spec/fixtures/` for deterministic coverage data.
+- `scripts/` – Helper scripts (e.g., `scripts/setup_codex_cloud.sh`).
+
+## Extending the System
+
+1. Add or update data processing inside `CoverageModel` or `CovUtil` when a new metric is needed.
+2. Surface that metric through the desired interface: CLI option/subcommand, new MCP tool, or library helper.
+3. Register the new tool in `MCPServer`, or update CLI option parsing in `CoverageCLI`.
+4. Provide tests under `spec/` mirroring the lib path (`spec/lib/simplecov_mcp/..._spec.rb`).
+5. Update documentation to reflect the new capability.
+
+By funnelling every interface through the shared `CoverageModel`, simplecov-mcp guarantees that CLI users, MCP clients, and embedding libraries all observe identical coverage semantics and staleness rules, while still allowing each adapter to tailor presentation and error handling to its audience.

data/docs/BRANCH_ONLY_COVERAGE.md

@@ -0,0 +1,81 @@
+# Branch-Only Coverage Handling
+
+SimpleCov can collect *line* coverage, *branch* coverage, or both. Projects that
+enable the `:branch` mode without `:line` produce a `.resultset.json` where the
+per-file entries contain a `branches` hash while the legacy `lines` array is
+`null`. This document explains that format and why SimpleCov MCP synthesizes a
+line array on the fly so downstream consumers continue to work.
+
+## SimpleCov branch payloads
+
+Each resultset groups coverage by absolute (or project-relative) path. A branch
+only entry looks like:
+
+```json
+{
+  "lib/example.rb": {
+    "lines": null,
+    "branches": {
+      "[:if, 0, 12, 4, 20, 29]": {
+        "[:then, 1, 13, 6, 13, 18]": 4,
+        "[:else, 2, 15, 6, 15, 16]": 0
+      }
+    }
+  }
+}
+```
+
+Key observations:
+
+- The outer hash key is either a stringified Ruby array or the raw array itself:
+  `[:if, branch_id, line, column, end_line, end_column]`. Array structure:
+  - index 0: branch type (`:if`, `:case`, `:unless`, etc.)
+  - index 1: internal branch identifier
+  - **index 2: line where the branch starts** (the field we care about for coverage)
+  - index 3: column where the branch starts
+  - index 4: line where the branch expression ends
+  - index 5: column where the branch expression ends
+- SimpleCov reuses a single branch tuple for all recorded runs.
+- The nested hash contains targets (`[:then, …]`, `[:else, …]`, `[:when, …]`, etc.)
+  Each target tuple mirrors the same shape—branch type at index 0, an internal
+  identifier at 1, then the start/end positions for that branch leg.
+  The integer value is the execution count for that branch leg. SimpleCov MCP
+  sums these counts per line when synthesizing fallback line data.
+
+## Synthesizing line coverage
+
+SimpleCov MCP exposes APIs and CLI tooling built around line-oriented coverage.
+To support branch-only projects, we reconstruct a minimal line array by summing
+branch hits per line. The resolver:
+
+1. Normalizes branch tuples, whether they arrive as arrays or strings.
+2. Extracts the line token (element `2`) and converts it to an integer.
+3. Aggregates hit counts across all branch targets for that line.
+4. Builds a dense array up to the highest line seen. Each populated slot stores
+   the total branch hits recorded for that line. Slots remain `nil` when a line
+   never appeared in the branch data.
+
+This produces the familiar SimpleCov shape (array index → line number - 1), so
+utilities like `summary`, `uncovered`, and staleness checks keep working.
+
+## Code map
+
+Relevant implementation points:
+
+- `lib/simplecov_mcp/resolvers/coverage_line_resolver.rb` — entry point that
+  synthesizes the array when `lines` is missing.
+- Specs covering branch-only behaviour live in
+  `spec/resolvers/coverage_line_resolver_spec.rb` and
+  `spec/simplecov_mcp_model_spec.rb`.
+- Fixture data resides at
+  `spec/fixtures/branch_only_project/coverage/.resultset.json`.
+
+Implementation notes:
+
+- The resolver must return `nil` when a path fails to match. `CovUtil.lookup_lines`
+  tries alternate keys (absolute, project-relative, cwd-stripped). Returning
+  `nil` allows those attempts to continue, ultimately raising the expected
+  `FileError` only after every variant is exhausted.
+- SimpleCov may evolve the branch tuple format. When that happens, extend
+  `extract_line_number` to recognize the new shape and refresh this document so
+  future maintainers understand which forms are supported.