simcov-ai-formatter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9ad0a4b51fd6e7a743e2cb7238b7797d2bad733a23bac120261028ac7ed5e8b9
+  data.tar.gz: a39467b1e1fdcf351922ceeb8718ddfbb77ecd54f689285c04fe170467998667
+SHA512:
+  metadata.gz: 4964b080d74c7d4f8e8e3f76bff4d4f668916d9adcd219e3c952295c9c27316d9a4599b43c83f52bca46b0e6c0b211397fbeef382573b3fab5b5e623b5527d16
+  data.tar.gz: 5ac52c9e2307aaee72ced97754a8daaed9a6bc0d5219466ca8c36f5059effab24c5bedce924964aea0407aa925e5dbbbd3da65a789619d63beef570a5136a672

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [0.1.0] - 2026-05-03
+
+### Added
+- Initial release.
+- Converts SimpleCov's `.resultset.json` into AI-friendly JSON.
+- Per-file and project-wide summaries (line counts, coverage percentage).
+- `uncovered_ranges` (consecutive uncovered lines collapsed into ranges) and flat `uncovered_lines`.
+- `with_source: true, context: N` embeds source lines around uncovered ranges.
+- Multiple suites are merged via `max(hit)`, or a single suite can be selected with `suite: "NAME"`.
+- Public Ruby API: `SimcovAiFormatter.format(path, **opts)` returns a Hash.
+- SimpleCov formatter plugin (`SimcovAiFormatter::SimpleCovFormatter`) — emit the AI-friendly JSON automatically during a SimpleCov run. Configure via class-level attributes (`with_source`, `context`, `pretty`, `output_path`).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuhi Sato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,165 @@
+# simcov-ai-formatter
+
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Yuhi-Sato/simcov-ai-formatter)
+
+A SimpleCov formatter that emits a JSON format optimized for AI / LLM consumption — per-file summaries, uncovered ranges, and optional source snippets.
+
+## Why this exists
+
+SimpleCov's `.resultset.json` records coverage as position-dependent arrays:
+
+```json
+{ "RSpec": { "coverage": { "/abs/path/foo.rb": { "lines": [null, 1, 0, 0, null, 5] } } } }
+```
+
+`lines` is a 1-indexed hit-count array (`null` = irrelevant, `0` = uncovered, `Integer >= 1` = hit count).
+For an LLM to figure out "which file has which uncovered lines" from this shape, it has to scan arrays, compute summaries, and normalize paths every single time.
+
+This gem does that preprocessing **once, deterministically, and in a token-efficient way**.
+
+## Installation
+
+```sh
+gem install simcov-ai-formatter
+```
+
+Or in `Gemfile`:
+
+```ruby
+group :development, :test do
+  gem "simcov-ai-formatter"
+end
+```
+
+## Output schema
+
+### Default
+
+```json
+{
+  "schema_version": 1,
+  "suite": "RSpec",
+  "root": "/Users/me/proj",
+  "summary": {
+    "total_files": 42,
+    "relevant_lines": 1830,
+    "covered_lines": 1644,
+    "missed_lines": 186,
+    "coverage_percentage": 89.84
+  },
+  "files": {
+    "lib/foo.rb": {
+      "relevant_lines": 50,
+      "covered_lines": 45,
+      "missed_lines": 5,
+      "coverage_percentage": 90.0,
+      "uncovered_ranges": [
+        { "start": 12, "end": 14 },
+        { "start": 88, "end": 88 }
+      ],
+      "uncovered_lines": [12, 13, 14, 88]
+    }
+  }
+}
+```
+
+When multiple suites are merged, a top-level `"suites_merged": ["RSpec", "Cucumber"]` is emitted.
+
+### With `with_source: true, context: 2`
+
+Each `uncovered_ranges` entry gains a `source` array:
+
+```json
+{
+  "start": 12, "end": 14,
+  "source": [
+    { "line": 10, "text": "def parse(input)",        "covered": true },
+    { "line": 11, "text": "  return nil if input.nil?", "covered": true },
+    { "line": 12, "text": "  raise ArgumentError",     "covered": false },
+    { "line": 13, "text": "  log_error(input)",        "covered": false },
+    { "line": 14, "text": "  nil",                     "covered": false },
+    { "line": 15, "text": "end",                       "covered": true }
+  ]
+}
+```
+
+If the source file is missing, the range gets `"source": null, "source_error": "missing"` and a warning summary is emitted to stderr (processing continues).
+
+### Branch coverage
+
+If `branches` exists in the resultset, each file gets a `branches_raw` field containing the resultset's original key shape **unchanged**.
+Structured form (`{ type: "if", line: ..., then_hits: ..., else_hits: ... }`) is planned for v0.2.0.
+
+### Schema details
+
+- `relevant_lines` excludes `null` entries (matches SimpleCov convention).
+- Files with all `null` lines (comments / blanks only) report `relevant_lines: 0, coverage_percentage: 100.0` and are excluded from the project-level denominator.
+- `coverage_percentage` is rounded to 2 decimal places.
+- Files outside `root` (e.g. third-party gems) are kept under keys of the form `!abs:/abs/path`.
+- The output contains no timestamp — the JSON is deterministic.
+
+## As a SimpleCov formatter
+
+Plug `simcov-ai-formatter` into SimpleCov's formatter pipeline to emit the AI-friendly JSON automatically as part of your test run.
+
+```ruby
+# spec/spec_helper.rb (or .simplecov)
+require "simplecov"
+require "simcov_ai_formatter/simple_cov_formatter"
+
+SimpleCov.start do
+  # ... your usual SimpleCov config
+end
+
+# Replace the default formatter
+SimpleCov.formatter = SimcovAiFormatter::SimpleCovFormatter
+
+# Or run alongside the HTML formatter
+SimpleCov.formatters = SimpleCov::Formatter::MultiFormatter.create([
+  SimpleCov::Formatter::HTMLFormatter,
+  SimcovAiFormatter::SimpleCovFormatter
+])
+```
+
+After tests finish, the AI-friendly JSON is written to `coverage/.resultset.ai.json` (or wherever `SimpleCov.coverage_path` points).
+
+### Configuration
+
+Set class-level attributes before `SimpleCov.start`:
+
+```ruby
+SimcovAiFormatter::SimpleCovFormatter.with_source = true
+SimcovAiFormatter::SimpleCovFormatter.context     = 3
+SimcovAiFormatter::SimpleCovFormatter.pretty      = false
+SimcovAiFormatter::SimpleCovFormatter.output_path = "tmp/coverage.ai.json"  # nil = coverage/.resultset.ai.json
+```
+
+## Programmatic use
+
+The same logic is callable from Ruby:
+
+```ruby
+require "simcov_ai_formatter"
+
+result = SimcovAiFormatter.format(
+  "coverage/.resultset.json",
+  root: Dir.pwd,
+  with_source: true,
+  context: 2
+)
+
+# result is a Hash
+puts result["summary"]["coverage_percentage"]
+```
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test                   # run all tests
+UPDATE_GOLDEN=1 bundle exec rake test   # regenerate golden files
+```
+
+## License
+
+MIT

data/lib/simcov_ai_formatter/errors.rb

@@ -0,0 +1,6 @@
+module SimcovAiFormatter
+  class Error < StandardError; end
+  class ResultsetNotFound < Error; end
+  class InvalidResultset < Error; end
+  class SuiteNotFound < Error; end
+end

data/lib/simcov_ai_formatter/formatter.rb

@@ -0,0 +1,155 @@
+require "pathname"
+
+module SimcovAiFormatter
+  # Transforms SimpleCov's coverage hash into the AI-friendly Hash shape.
+  #
+  # Input:  { "<abs_path>" => { "lines" => [null|0|N, ...], "branches" => {...}? } }
+  # Output: see README for the full schema.
+  class Formatter
+    def initialize(coverage:, suite:, root:, suites_merged: nil, with_source: false, context: 2, source_reader: nil)
+      @coverage = coverage
+      @suite = suite
+      @suites_merged = suites_merged
+      @root = Pathname.new(root).expand_path
+      @with_source = with_source
+      @context = context
+      @source_reader = source_reader
+    end
+
+    def call
+      files = build_files
+      project_summary = aggregate_summary(files)
+
+      result = {
+        "schema_version" => 1,
+        "suite" => @suite,
+        "root" => @root.to_s,
+        "summary" => project_summary,
+        "files" => files
+      }
+      if @suites_merged && @suites_merged.size > 1
+        result["suites_merged"] = @suites_merged
+      end
+      result
+    end
+
+    private
+
+    def build_files
+      sorted = @coverage.keys.sort
+      sorted.each_with_object({}) do |abs_path, acc|
+        entry = @coverage[abs_path]
+        rel = relativize(abs_path)
+        acc[rel] = build_file_entry(abs_path, entry)
+      end
+    end
+
+    def build_file_entry(abs_path, entry)
+      lines = entry["lines"] || []
+      relevant = lines.count { |v| !v.nil? }
+      covered = lines.count { |v| v.is_a?(Integer) && v.positive? }
+      uncovered_lines = find_uncovered_lines(lines)
+      uncovered_ranges = collapse_ranges(uncovered_lines)
+
+      file_entry = {
+        "relevant_lines" => relevant,
+        "covered_lines" => covered,
+        "missed_lines" => relevant - covered,
+        "coverage_percentage" => percentage(covered, relevant),
+        "uncovered_ranges" => uncovered_ranges,
+        "uncovered_lines" => uncovered_lines
+      }
+
+      with_source_attached = @with_source && @source_reader && !uncovered_ranges.empty?
+      if with_source_attached
+        file_entry["uncovered_ranges"] = uncovered_ranges.map do |range|
+          attach_source(abs_path, range, lines)
+        end
+      end
+
+      attach_branches(file_entry, entry)
+      file_entry
+    end
+
+    def find_uncovered_lines(lines)
+      lines.each_with_index.filter_map { |v, i| i + 1 if v.is_a?(Integer) && v.zero? }
+    end
+
+    def attach_branches(file_entry, entry)
+      branches = entry["branches"]
+      file_entry["branches_raw"] = branches if branches.is_a?(Hash) && !branches.empty?
+    end
+
+    def attach_source(abs_path, range, lines)
+      start_line = [range["start"] - @context, 1].max
+      end_line = range["end"] + @context
+      snippet = @source_reader.read(abs_path, start_line, end_line)
+
+      if snippet.nil?
+        range.merge("source" => nil, "source_error" => "missing")
+      else
+        source_array = snippet.map do |line_no, text|
+          {
+            "line" => line_no,
+            "text" => text,
+            "covered" => covered_for(lines[line_no - 1])
+          }
+        end
+        range.merge("source" => source_array)
+      end
+    end
+
+    def covered_for(value)
+      return nil if value.nil?
+      return false if value.is_a?(Integer) && value.zero?
+      true
+    end
+
+    def collapse_ranges(line_numbers)
+      ranges = []
+      line_numbers.each do |n|
+        if !ranges.empty? && ranges.last["end"] == n - 1
+          ranges.last["end"] = n
+        else
+          ranges << { "start" => n, "end" => n }
+        end
+      end
+      ranges
+    end
+
+    def aggregate_summary(files)
+      values = files.values
+      total_relevant = values.sum { |f| f["relevant_lines"] }
+      total_covered = values.sum { |f| f["covered_lines"] }
+      total_missed = values.sum { |f| f["missed_lines"] }
+      {
+        "total_files" => files.size,
+        "relevant_lines" => total_relevant,
+        "covered_lines" => total_covered,
+        "missed_lines" => total_missed,
+        "coverage_percentage" => percentage(total_covered, total_relevant)
+      }
+    end
+
+    def percentage(covered, relevant)
+      return 100.0 if relevant.zero?
+      (covered.to_f / relevant * 100).round(2)
+    end
+
+    def relativize(abs_path)
+      pathname = Pathname.new(abs_path)
+      return "!abs:#{abs_path}" unless pathname.absolute?
+
+      begin
+        relative = pathname.relative_path_from(@root).to_s
+        if relative.start_with?("..")
+          "!abs:#{abs_path}"
+        else
+          relative
+        end
+      rescue ArgumentError
+        "!abs:#{abs_path}"
+      end
+    end
+  end
+end

data/lib/simcov_ai_formatter/renderer.rb

@@ -0,0 +1,13 @@
+require "json"
+
+module SimcovAiFormatter
+  class Renderer
+    def initialize(pretty: false)
+      @pretty = pretty
+    end
+
+    def render(hash)
+      @pretty ? JSON.pretty_generate(hash) : JSON.generate(hash)
+    end
+  end
+end

data/lib/simcov_ai_formatter/resultset_loader.rb

@@ -0,0 +1,59 @@
+require "json"
+
+module SimcovAiFormatter
+  # Loads SimpleCov's .resultset.json, validates its shape, and returns the parsed Hash.
+  #
+  # Expected shape:
+  #   {
+  #     "<suite_name>" => {
+  #       "coverage" => { "<abs_path>" => { "lines" => [...], "branches" => {...} } },
+  #       "timestamp" => Integer
+  #     },
+  #     ...
+  #   }
+  class ResultsetLoader
+    def initialize(path)
+      @path = path
+    end
+
+    def load
+      raw = read_json
+      validate!(raw)
+      raw
+    end
+
+    private
+
+    def read_json
+      unless File.exist?(@path)
+        raise ResultsetNotFound, "resultset.json not found: #{@path}"
+      end
+
+      JSON.parse(File.read(@path))
+    rescue JSON::ParserError => e
+      raise InvalidResultset, "invalid JSON at #{@path}: #{e.message}"
+    end
+
+    def validate!(raw)
+      unless raw.is_a?(Hash) && !raw.empty?
+        raise InvalidResultset, "expected non-empty top-level hash at #{@path}"
+      end
+
+      raw.each { |suite, body| validate_suite!(suite, body) }
+    end
+
+    def validate_suite!(suite, body)
+      unless body.is_a?(Hash) && body["coverage"].is_a?(Hash)
+        raise InvalidResultset, "suite #{suite.inspect} missing 'coverage' hash"
+      end
+
+      body["coverage"].each { |file, entry| validate_file!(suite, file, entry) }
+    end
+
+    def validate_file!(suite, file, entry)
+      unless entry.is_a?(Hash) && entry["lines"].is_a?(Array)
+        raise InvalidResultset, "file #{file.inspect} in suite #{suite.inspect} missing 'lines' array"
+      end
+    end
+  end
+end

data/lib/simcov_ai_formatter/simple_cov_formatter.rb

@@ -0,0 +1,77 @@
+require_relative "../simcov_ai_formatter"
+
+module SimcovAiFormatter
+  # SimpleCov plugin formatter — emits the AI-friendly JSON during a SimpleCov
+  # run, without requiring a separate `simcov-ai-formatter` invocation.
+  #
+  # Usage:
+  #   require "simcov_ai_formatter/simple_cov_formatter"
+  #
+  #   SimpleCov.formatter = SimcovAiFormatter::SimpleCovFormatter
+  #
+  #   # or alongside other formatters:
+  #   SimpleCov.formatters = SimpleCov::Formatter::MultiFormatter.create([
+  #     SimpleCov::Formatter::HTMLFormatter,
+  #     SimcovAiFormatter::SimpleCovFormatter
+  #   ])
+  #
+  # Configure (before SimpleCov.start):
+  #   SimcovAiFormatter::SimpleCovFormatter.with_source = true
+  #   SimcovAiFormatter::SimpleCovFormatter.context     = 3
+  #   SimcovAiFormatter::SimpleCovFormatter.pretty      = true
+  #   SimcovAiFormatter::SimpleCovFormatter.output_path = "tmp/coverage.ai.json"
+  class SimpleCovFormatter
+    DEFAULT_OUTPUT_FILENAME = ".resultset.ai.json".freeze
+
+    class << self
+      attr_accessor :with_source, :context, :pretty, :output_path
+    end
+    self.with_source = false
+    self.context = 2
+    self.pretty = false
+    self.output_path = nil
+
+    # SimpleCov calls this with a SimpleCov::Result instance.
+    def format(result)
+      with_source = self.class.with_source
+      context = self.class.context
+      pretty = self.class.pretty
+
+      raw = result.to_hash
+      selected_suite, coverage = SuiteMerger.new(raw).select
+
+      source_reader = with_source ? SourceReader.new(warnings: $stderr) : nil
+      formatted = Formatter.new(
+        coverage: coverage,
+        suite: selected_suite,
+        suites_merged: nil,
+        root: simplecov_root,
+        with_source: with_source,
+        context: context,
+        source_reader: source_reader
+      ).call
+
+      json = Renderer.new(pretty: pretty).render(formatted)
+      target = resolve_output_path
+      File.write(target, json + "\n")
+      source_reader&.report_missing
+
+      puts "Coverage AI report generated to #{target}"
+      target
+    end
+
+    private
+
+    def resolve_output_path
+      self.class.output_path || File.join(simplecov_coverage_path, DEFAULT_OUTPUT_FILENAME)
+    end
+
+    def simplecov_coverage_path
+      defined?(::SimpleCov) ? ::SimpleCov.coverage_path : "coverage"
+    end
+
+    def simplecov_root
+      defined?(::SimpleCov) ? ::SimpleCov.root : Dir.pwd
+    end
+  end
+end

data/lib/simcov_ai_formatter/source_reader.rb

@@ -0,0 +1,49 @@
+module SimcovAiFormatter
+  # Reads source files by 1-indexed line numbers with random access.
+  # Files are cached as line arrays after the first read.
+  # Missing files and unknown encodings never crash the caller.
+  class SourceReader
+    def initialize(warnings: nil)
+      @cache = {}
+      @missing = []
+      @warnings = warnings
+    end
+
+    # @return [Array<[Integer, String]>, nil] line-number/text pairs, or nil if the file is missing
+    def read(path, start_line, end_line)
+      lines = lines_for(path)
+      return nil if lines.nil?
+
+      from = [start_line, 1].max
+      to = [end_line, lines.size].min
+      (from..to).map { |n| [n, lines[n - 1]] }
+    end
+
+    def report_missing
+      return if @warnings.nil? || @missing.empty?
+      @warnings.puts("simcov-ai-formatter: warning: #{@missing.size} source file(s) not found:")
+      @missing.first(5).each { |p| @warnings.puts("  - #{p}") }
+      @warnings.puts("  ...") if @missing.size > 5
+    end
+
+    private
+
+    def lines_for(path)
+      return @cache[path] if @cache.key?(path)
+
+      unless File.exist?(path)
+        @missing << path
+        return (@cache[path] = nil)
+      end
+
+      @cache[path] = read_lines_safely(path)
+    end
+
+    def read_lines_safely(path)
+      raw = File.read(path, mode: "rb")
+      text = raw.force_encoding("UTF-8")
+      text = text.scrub("?") unless text.valid_encoding?
+      text.split(/\r\n|\r|\n/, -1).tap { |arr| arr.pop if arr.last == "" }
+    end
+  end
+end

data/lib/simcov_ai_formatter/suite_merger.rb

@@ -0,0 +1,100 @@
+module SimcovAiFormatter
+  # Merges multiple suites in a resultset into a single coverage Hash,
+  # or selects one when --suite NAME is given.
+  #
+  # Line merge rules per (file, index):
+  #   - one nil and one Integer → take the Integer
+  #   - both Integer            → take max(hit)
+  #   - both nil                → nil
+  # Branches: hit counts are summed for matching keys; missing keys are added.
+  class SuiteMerger
+    def initialize(resultset, suite: nil)
+      @resultset = resultset
+      @suite = suite
+    end
+
+    # @return [Array(String, Hash)] the selected suite label and the merged coverage hash
+    def select
+      return select_specified_suite if @suite
+      return select_sole_suite if @resultset.size == 1
+      select_merged_suites
+    end
+
+    private
+
+    def select_specified_suite
+      body = @resultset[@suite]
+      unless body
+        available = @resultset.keys.join(", ")
+        raise SuiteNotFound, "suite #{@suite.inspect} not in resultset (available: #{available})"
+      end
+      [@suite, body["coverage"]]
+    end
+
+    def select_sole_suite
+      suite, body = @resultset.first
+      [suite, body["coverage"]]
+    end
+
+    def select_merged_suites
+      ["merged", merge_all]
+    end
+
+    def merge_all
+      merged = {}
+      @resultset.each_value do |body|
+        body["coverage"].each do |file, entry|
+          if merged.key?(file)
+            merged[file] = merge_entries(merged[file], entry)
+          else
+            merged[file] = deep_dup(entry)
+          end
+        end
+      end
+      merged
+    end
+
+    def merge_entries(a, b)
+      lines_a = a["lines"]
+      lines_b = b["lines"]
+      length = [lines_a.size, lines_b.size].max
+      merged_lines = Array.new(length) do |i|
+        merge_hit(lines_a[i], lines_b[i])
+      end
+
+      result = { "lines" => merged_lines }
+      branches_a = a["branches"]
+      branches_b = b["branches"]
+      if branches_a || branches_b
+        result["branches"] = merge_branches(branches_a, branches_b)
+      end
+      result
+    end
+
+    def merge_hit(x, y)
+      return y if x.nil?
+      return x if y.nil?
+      [x, y].max
+    end
+
+    def merge_branches(a, b)
+      a ||= {}
+      b ||= {}
+      keys = (a.keys | b.keys)
+      keys.each_with_object({}) do |outer_key, acc|
+        acc[outer_key] = sum_branch_hits(a[outer_key] || {}, b[outer_key] || {})
+      end
+    end
+
+    def sum_branch_hits(inner_a, inner_b)
+      inner_keys = (inner_a.keys | inner_b.keys)
+      inner_keys.each_with_object({}) do |k, sub|
+        sub[k] = (inner_a[k] || 0) + (inner_b[k] || 0)
+      end
+    end
+
+    def deep_dup(entry)
+      JSON.parse(JSON.generate(entry))
+    end
+  end
+end

data/lib/simcov_ai_formatter/version.rb

@@ -0,0 +1,3 @@
+module SimcovAiFormatter
+  VERSION = "0.1.0"
+end

data/lib/simcov_ai_formatter.rb

@@ -0,0 +1,35 @@
+require_relative "simcov_ai_formatter/version"
+require_relative "simcov_ai_formatter/errors"
+require_relative "simcov_ai_formatter/resultset_loader"
+require_relative "simcov_ai_formatter/suite_merger"
+require_relative "simcov_ai_formatter/formatter"
+require_relative "simcov_ai_formatter/source_reader"
+require_relative "simcov_ai_formatter/renderer"
+
+module SimcovAiFormatter
+  DEFAULT_RESULTSET_PATH = "coverage/.resultset.json".freeze
+
+  # Public API: convert resultset.json into an AI-friendly Hash.
+  #
+  # @param path [String] path to resultset.json
+  # @param root [String] base directory for relative paths (default: Dir.pwd)
+  # @param suite [String, nil] pick a single suite; if nil, merge all suites via max(hit)
+  # @param with_source [Boolean] embed source lines around uncovered ranges
+  # @param context [Integer] lines of context when with_source is true
+  # @param source_warnings [IO, nil] destination for source-missing warnings
+  # @return [Hash]
+  def self.format(path, root: Dir.pwd, suite: nil, with_source: false, context: 2, source_warnings: nil)
+    raw = ResultsetLoader.new(path).load
+    selected_suite, coverage = SuiteMerger.new(raw, suite: suite).select
+    source_reader = with_source ? SourceReader.new(warnings: source_warnings) : nil
+    Formatter.new(
+      coverage: coverage,
+      suite: selected_suite,
+      suites_merged: suite.nil? ? raw.keys : nil,
+      root: root,
+      with_source: with_source,
+      context: context,
+      source_reader: source_reader
+    ).call
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: simcov-ai-formatter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yuhi Sato
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Converts SimpleCov coverage data into a JSON format optimized for LLM/AI
+  consumption — per-file summaries, uncovered ranges, optional source snippets. Works
+  as a SimpleCov formatter plugin (auto-emit during test runs) or via a programmatic
+  Ruby API.
+email:
+- yuhi120101@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/simcov_ai_formatter.rb
+- lib/simcov_ai_formatter/errors.rb
+- lib/simcov_ai_formatter/formatter.rb
+- lib/simcov_ai_formatter/renderer.rb
+- lib/simcov_ai_formatter/resultset_loader.rb
+- lib/simcov_ai_formatter/simple_cov_formatter.rb
+- lib/simcov_ai_formatter/source_reader.rb
+- lib/simcov_ai_formatter/suite_merger.rb
+- lib/simcov_ai_formatter/version.rb
+homepage: https://github.com/y-sato/simcov-ai-formatter
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/y-sato/simcov-ai-formatter
+  source_code_uri: https://github.com/y-sato/simcov-ai-formatter
+  changelog_uri: https://github.com/y-sato/simcov-ai-formatter/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Format SimpleCov coverage data into AI-friendly JSON
+test_files: []