simplecov-ai 0.10.2 → 0.10.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7ae5d956cdb6b5fd6529cbf793507984563b331ccaffeb710b7760f7e81a9da
-  data.tar.gz: eecad8ca18885972bd1b494f3706d1182c6fa0a3c42a1799ba4af27199e9f83f
+  metadata.gz: 21fb51a293aef52967848c9b4fcc176b83aa274c347fb29abeaf76a34f040754
+  data.tar.gz: b43d99c3b4064c5e2914be0df4251774f78f0f6fa41cc51ae85c4e4547a586e9
 SHA512:
-  metadata.gz: 7e1a9a39532116181c40dc234f98364462fefd3f30a77ba88e7eebabeb4a222550e260b3d0571539ab6b3895221c56d37f38f8391173867ecd4f06672582d7ef
-  data.tar.gz: 44a0c37ed5fe8ef1e0df5b0ecbfc88ce3315b91a6dc33767751c042cf2ad8863756d46163f5fe25741a4a7a39d7802d7b2c60926f89ab5e57d1b7ab872d90be2
+  metadata.gz: 55f0042ff2503ffc573c39a1393a407e66988e2de5f3e79d5d35eb539f70645bb1bcd6374870d84682dba430a87b7b0f9601baa446e9beb99f1e9e7aa3c45cf1
+  data.tar.gz: 2a94566df43e8bdd3c8e68ffcbe95bbda0683be0cd661313ede1af5a421d0972ad03d3b0363cf72259d631e80a490529075adc2b13df58a02d7ffa4c777ef95c

data/README.md

@@ -1 +1,89 @@
 # simplecov-ai
+
+A custom `SimpleCov::Formatter` designed explicitly for consumption by Large Language Models (LLMs) and autonomous engineering agents. 
+
+Standard coverage reporters generate massive HTML files or exhaustive JSON/console outputs detailing every line number. This overwhelms strict LLM token constraints and relies on highly volatile line numbers. `simplecov-ai` solves this by generating a concise, structurally optimized **Markdown document** containing only the exact missing semantic coverage blocks.
+
+## Why use simplecov-ai?
+
+- **Semantic Resolution:** Instead of volatile line numbers, missing coverage is resolved via Abstract Syntax Tree (AST) mapping into immutable semantic groupings (e.g., Class, Module, Instance Method).
+- **Maximum Token Conservation:** Fully covered files are completely omitted. If the report exceeds size limits, it safely truncates the output prioritizing the lowest-coverage files.
+- **Actionable Delta Directives:** Missing branches and lines are mapped directly to method names, letting the AI instantly search the code and write targeted specs.
+- **Directive Auditing:** Explicitly reports `:nocov:` bypasses, ensuring artificial metric inflation is completely transparent to the reviewing AI.
+
+## Installation
+
+Add this line to your application's `Gemfile` strictly in the `test` group:
+
+```ruby
+group :test do
+  gem 'simplecov'
+  gem 'simplecov-ai', require: false
+end
+```
+
+## Usage & Configuration
+
+Require and configure the formatter in your test helper (`spec_helper.rb` or `test_helper.rb`) after requiring `simplecov`:
+
+```ruby
+require 'simplecov'
+require 'simplecov-ai'
+
+# Optional Configuration (defaults shown below):
+SimpleCov::Formatter::AIFormatter.configure do |config|
+  config.report_path = 'coverage/ai_report.md'      # Output location
+  config.max_file_size_kb = 50                      # Maximum size (Token Ceiling)
+  config.max_snippet_lines = 5                      # AST context truncation limit
+  config.output_to_console = false                  # Echo digest to STDOUT
+  config.granularity = :fine                        # :fine (statements) or :coarse (methods)
+  config.include_bypasses = true                    # Audit `:nocov:` ignores
+end
+
+SimpleCov.start do
+  # Combine with your existing formatters
+  SimpleCov.formatters = SimpleCov::Formatter::MultiFormatter.new([
+    SimpleCov::Formatter::HTMLFormatter,
+    SimpleCov::Formatter::AIFormatter
+  ])
+end
+```
+
+## Example Output
+
+The output is written to `coverage/ai_report.md` (or your configured path), perfect for providing directly as context to an LLM:
+
+```md
+# AI Coverage Digest
+**Status:** FAILED
+**Global Line Coverage:** 92.5%
+**Global Branch Coverage:** 88.0%
+**Generated At:** 2026-04-21T23:40:44+09:00 (Local Timezone)
+**Report File Size:** 1.2 kB
+
+## Coverage Deficits
+
+### `lib/my_gem/client.rb`
+- `MyGem::Client#authenticate!`
+  - **Branch Deficit:** Missing coverage for conditional evaluation handling `ExpiredTokenError`.
+- `MyGem::Client#initialize`
+  - **Line Deficit:** Variable initialization state uncovered.
+
+### `lib/my_gem/parser/processor.rb`
+- `MyGem::Parser::Processor.parse_stream`
+  - **Branch Deficit:** Missing coverage for early-exit condition `break if stream.closed?` (Occurrence 1 of 2).
+
+## Ignored Coverage Bypasses
+
+### `lib/my_gem/legacy_handler.rb`
+- `MyGem::LegacyHandler#obsolete_action`
+  - **Bypass Present:** Contains `:nocov:` directive artificially ignoring coverage (Occurrence 1 of 1).
+```
+
+## Error Handling
+
+Adhering to fail-fast principles, if the AST parser encounters structurally unparseable Ruby code or corrupt telemetry, it will gracefully degrade or explicitly fail. It will not silently ignore failures or emit corrupted artifacts.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/simplecov-ai/ast_resolver.rb

@@ -43,6 +43,11 @@ module SimpleCov
             @end_line = end_line
             @bypasses = bypasses
           end
+
+          sig { params(bypass: String).void }
+          def add_bypass(bypass)
+            @bypasses << bypass
+          end
         end
 
         # Orchestrates the initial mapping algorithm on a target file to extract structural
@@ -54,85 +59,118 @@ module SimpleCov
         def self.resolve(file_path)
           return [] unless File.exist?(file_path)
 
-          begin
-            source = File.read(file_path)
-            ast, comments = Parser::CurrentRuby.parse_with_comments(source)
-            new.traverse(ast, comments)
-          rescue Parser::SyntaxError
-            []
-          end
+          source = File.read(file_path)
+          ast, comments = Parser::CurrentRuby.parse_with_comments(source)
+
+          resolver = new
+          nodes = resolver.traverse(ast)
+          resolver.assign_bypasses(nodes, comments)
+          nodes
         end
 
         # Recursively navigates an abstract node hierarchy, building SemanticNodes mappings
         # around modules, classes, singleton, and instance methods while aggregating parent paths.
         #
         # @param node [Parser::AST::Node] The root AST node from which traversal executes.
-        # @param comments [Array<Parser::Source::Comment>] Lexical comments corresponding to nodes.
         # @param context [String] An accumulated identifier linking namespaces to inner entities.
         # @return [Array<SemanticNode>] Accumulation of all sub-tree defined endpoints.
         sig do
-          params(node: Parser::AST::Node, comments: T::Array[Parser::Source::Comment],
+          params(node: T.nilable(Parser::AST::Node),
                  context: String).returns(T::Array[SemanticNode])
         end
-        def traverse(node, comments, context = '')
+        def traverse(node, context = '')
           return [] unless node.is_a?(Parser::AST::Node)
 
           nodes = T.let([], T::Array[SemanticNode])
-          current_context = context
+          current_context, semantic_node = extract_node_metadata(node, context)
+          nodes << semantic_node if semantic_node
+
+          node.children.grep(Parser::AST::Node).each do |child|
+            nodes.concat(traverse(child, current_context))
+          end
+
+          nodes
+        end
+
+        sig { params(nodes: T::Array[SemanticNode], comments: T::Array[Parser::Source::Comment]).void }
+        def assign_bypasses(nodes, comments)
+          comments.each do |c|
+            c_text = T.cast(c.text, String)
+            next unless c_text.include?(':nocov:')
+
+            assign_bypass(nodes, c, c_text.strip)
+          end
+        end
+
+        private
+
+        sig { params(nodes: T::Array[SemanticNode], comment: Parser::Source::Comment, text: String).void }
+        def assign_bypass(nodes, comment, text)
+          c_loc = T.cast(comment.loc, Parser::Source::Map)
+          c_line = T.cast(c_loc.line, Integer)
 
+          innermost_node = nodes.reverse.find { |n| c_line.between?(n.start_line - 1, n.end_line + 1) }
+          innermost_node&.add_bypass(text)
+        end
+
+        sig do
+          params(node: Parser::AST::Node, context: String)
+            .returns([String, T.nilable(SemanticNode)])
+        end
+        def extract_node_metadata(node, context)
           case node.type
           when :class, :module
-            const_node = T.cast(node.children[0], Parser::AST::Node)
-            const_node_loc = T.cast(const_node.loc, Parser::Source::Map::Constant)
-            const_node_name = T.cast(const_node_loc.name, Parser::Source::Range)
-            name = T.cast(const_node_name.source, String)
-            current_context = context.empty? ? name : "#{context}::#{name}"
-            nodes << build_node(node, comments, current_context, node.type.to_s.capitalize)
+            extract_class_metadata(node, context)
           when :def
-            name = T.cast(node.children.first, Symbol).to_s
-            current_context = context.empty? ? "##{name}" : "#{context}##{name}"
-            nodes << build_node(node, comments, current_context, 'Instance Method')
+            extract_instance_method_metadata(node, context)
           when :defs
-            name = T.cast(node.children[1], Symbol).to_s
-            current_context = context.empty? ? ".#{name}" : "#{context}.#{name}"
-            nodes << build_node(node, comments, current_context, 'Singleton Method')
+            extract_singleton_method_metadata(node, context)
+          else
+            [context, nil]
           end
+        end
 
-          node.children.each do |child|
-            case child
-            when Parser::AST::Node
-              nodes.concat(traverse(child, comments, current_context))
-            end
-          end
+        sig do
+          params(node: Parser::AST::Node, context: String)
+            .returns([String, T.nilable(SemanticNode)])
+        end
+        def extract_class_metadata(node, context)
+          const_node = T.cast(node.children[0], Parser::AST::Node)
+          const_node_name = T.cast(T.cast(const_node.loc, Parser::Source::Map::Constant).name, Parser::Source::Range)
+          name = T.cast(const_node_name.source, String)
+          ctx = context.empty? ? name : "#{context}::#{name}"
+          [ctx, build_node(node, ctx, node.type.to_s.capitalize)]
+        end
 
-          nodes
+        sig do
+          params(node: Parser::AST::Node, context: String)
+            .returns([String, T.nilable(SemanticNode)])
+        end
+        def extract_instance_method_metadata(node, context)
+          name = T.cast(node.children.first, Symbol).to_s
+          ctx = context.empty? ? "##{name}" : "#{context}##{name}"
+          [ctx, build_node(node, ctx, 'Instance Method')]
         end
 
-        private
+        sig do
+          params(node: Parser::AST::Node, context: String)
+            .returns([String, T.nilable(SemanticNode)])
+        end
+        def extract_singleton_method_metadata(node, context)
+          name = T.cast(node.children[1], Symbol).to_s
+          ctx = context.empty? ? ".#{name}" : "#{context}.#{name}"
+          [ctx, build_node(node, ctx, 'Singleton Method')]
+        end
 
         sig do
-          params(node: Parser::AST::Node, comments: T::Array[Parser::Source::Comment], name: String,
+          params(node: Parser::AST::Node, name: String,
                  type: String).returns(SemanticNode)
         end
-        def build_node(node, comments, name, type)
-          node_loc = T.cast(node.loc, Parser::Source::Map)
-          node_line = T.cast(node_loc.line, Integer)
-          node_last_line = T.cast(node_loc.last_line, Integer)
-
-          bypasses = comments.select do |c|
-            c_loc = T.cast(c.loc, Parser::Source::Map)
-            c_line = T.cast(c_loc.line, Integer)
-            c_text = T.cast(c.text, String)
-            c_line >= node_line - 1 && c_line <= node_last_line + 1 && c_text.include?(':nocov:')
-          end.map { |c| T.cast(c.text, String).strip }
-
-          SemanticNode.new(
-            name: name,
-            type: type,
-            start_line: node_line,
-            end_line: node_last_line,
-            bypasses: bypasses
-          )
+        def build_node(node, name, type)
+          loc = T.cast(node.loc, Parser::Source::Map)
+          start_ln = T.cast(loc.line, Integer)
+          end_ln = T.cast(loc.last_line, Integer)
+          SemanticNode.new(name: name, type: type, start_line: start_ln, end_line: end_ln, bypasses: [])
         end
       end
     end

data/lib/simplecov-ai/markdown_builder/bypass_compiler.rb

@@ -0,0 +1,67 @@
+# typed: strict
+# frozen_string_literal: true
+
+module SimpleCov
+  module Formatter
+    class AIFormatter
+      class MarkdownBuilder
+        # Scans resolved AST blocks to report explicitly defined coverage ignores (e.g., :nocov:).
+        class BypassCompiler
+          extend T::Sig
+
+          sig { params(result: SimpleCov::Result, builder: MarkdownBuilder).void }
+          def initialize(result, builder)
+            @result = result
+            @builder = builder
+          end
+
+          sig { params(buffer: StringIO).void }
+          def write_bypasses(buffer)
+            bypass_buffer = T.let(StringIO.new, StringIO)
+            has_bypasses = compile_all_bypasses(bypass_buffer)
+
+            return unless has_bypasses
+
+            buffer.puts "## Ignored Coverage Bypasses\n\n"
+            buffer.puts bypass_buffer.string
+          end
+
+          private
+
+          sig { params(buffer: StringIO).returns(T::Boolean) }
+          def compile_all_bypasses(buffer)
+            has_bypasses = T.let(false, T::Boolean)
+            T.let(@result.files.to_a, T::Array[SimpleCov::SourceFile]).each do |file|
+              bypassed = fetch_bypassed_nodes(file.filename)
+              next if bypassed.empty?
+
+              has_bypasses = true
+              write_file_bypasses(buffer, file, bypassed)
+            end
+            has_bypasses
+          end
+
+          sig { params(filename: String).returns(T::Array[ASTResolver::SemanticNode]) }
+          def fetch_bypassed_nodes(filename)
+            nodes = @builder.try_resolve_ast(filename)
+            nodes ? nodes.select { |n| n.bypasses.any? } : []
+          end
+
+          sig do
+            params(buffer: StringIO, file: SimpleCov::SourceFile, bypasses: T::Array[ASTResolver::SemanticNode]).void
+          end
+          def write_file_bypasses(buffer, file, bypasses)
+            buffer.puts "### `#{file.project_filename}`"
+            total = bypasses.size
+            bypasses.each_with_index do |node, idx|
+              buffer.puts "- `#{node.name}`\n  " \
+                          '- **Bypass Present:** Contains `:nocov:` directive artificially ' \
+                          "ignoring coverage (Occurrence #{idx + 1} of #{total})."
+            end
+            buffer.puts ''
+          end
+        end
+      end
+    end
+  end
+end

data/lib/simplecov-ai/markdown_builder/deficit_compiler.rb

@@ -0,0 +1,129 @@
+# typed: strict
+# frozen_string_literal: true
+
+module SimpleCov
+  module Formatter
+    class AIFormatter
+      class MarkdownBuilder
+        # Iterates through files with coverage deficits and coordinates their AST parsing and snippet generation.
+        class DeficitCompiler
+          extend T::Sig
+          include SnippetFormatter
+
+          sig { params(result: SimpleCov::Result, config: Configuration, builder: MarkdownBuilder).void }
+          def initialize(result, config, builder)
+            @result = result
+            @config = config
+            @builder = builder
+          end
+
+          sig { params(buffer: StringIO).void }
+          def write_deficits(buffer)
+            files = T.let(
+              @result.files.reject { |f| f.covered_percent >= 100.0 }.sort_by { |f| [f.covered_percent, f.filename] },
+              T::Array[SimpleCov::SourceFile]
+            )
+            return if files.empty?
+
+            buffer.puts "## Coverage Deficits\n\n"
+            files.each do |file|
+              break if @builder.truncate_if_needed?
+
+              process_file(buffer, file)
+            end
+          end
+
+          private
+
+          sig { params(buffer: StringIO, file: SimpleCov::SourceFile).void }
+          def process_file(buffer, file)
+            buffer.puts "### `#{file.project_filename}`"
+            nodes = @builder.try_resolve_ast(file.filename)
+            nodes ? process_deficits(buffer, file, nodes) : format_raw_deficits(buffer, file)
+          end
+
+          sig { params(buffer: StringIO, file: SimpleCov::SourceFile).void }
+          def format_raw_deficits(buffer, file)
+            buffer.puts "  - **ERROR:** AST Parsing Failed. Showing raw line numbers instead.\n"
+            group = MarkdownBuilder::DeficitGroup.new(
+              lines: file.missed_lines,
+              branches: file.missed_branches
+            )
+            format_deficit_group(buffer, group, fetch_source_lines(file.filename))
+            buffer.puts ''
+          end
+
+          sig do
+            params(buffer: StringIO, file: SimpleCov::SourceFile, nodes: T::Array[ASTResolver::SemanticNode]).void
+          end
+          def process_deficits(buffer, file, nodes)
+            node_deficits = DeficitGrouper.build(file, nodes)
+            source_lines = T.let(nil, T.nilable(T::Array[String]))
+
+            node_deficits.each do |node_name, group|
+              break if @builder.truncate_if_needed?
+
+              source_lines ||= fetch_source_lines(file.filename)
+              format_node_deficit(buffer, node_name, group, source_lines)
+            end
+
+            buffer.puts ''
+          end
+
+          sig { params(buffer: StringIO, node_name: String, group: DeficitGroup, source_lines: T::Array[String]).void }
+          def format_node_deficit(buffer, node_name, group, source_lines)
+            buffer.puts "- `#{node_name}`"
+
+            if @config.granularity == :coarse
+              buffer.puts '  - **Deficit:** Contains unexecuted lines or branches.'
+            else
+              format_deficit_group(buffer, group, source_lines)
+            end
+          end
+
+          sig { params(filename: String).returns(T::Array[String]) }
+          def fetch_source_lines(filename)
+            File.readlines(filename)
+          rescue StandardError
+            []
+          end
+
+          sig { params(buffer: StringIO, group: DeficitGroup, source_lines: T::Array[String]).void }
+          def format_deficit_group(buffer, group, source_lines)
+            group.lines.each do |line|
+              write_line_snippet(buffer, line, source_lines, group.semantic_node)
+            end
+
+            group.branches.each do |branch|
+              write_branch_snippet(buffer, branch, source_lines, group.semantic_node)
+            end
+          end
+
+          sig do
+            params(buffer: StringIO, line: SimpleCov::SourceFile::Line, source_lines: T::Array[String],
+                   node: T.nilable(ASTResolver::SemanticNode)).void
+          end
+          def write_line_snippet(buffer, line, source_lines, node)
+            line_num = line.line_number
+            text = truncate_snippet(fetch_snippet_text([line_num], source_lines), @config.max_snippet_lines)
+            occurrence_str = calculate_occurrence(line_num, source_lines, node)
+            buffer.puts "  - **Line Deficit:** `#{text}` #{occurrence_str}".rstrip
+          end
+
+          sig do
+            params(buffer: StringIO, branch: SimpleCov::SourceFile::Branch, source_lines: T::Array[String],
+                   node: T.nilable(ASTResolver::SemanticNode)).void
+          end
+          def write_branch_snippet(buffer, branch, source_lines, node)
+            start_line = branch.start_line
+            end_line = branch.end_line
+            lines_range = T.cast((start_line..end_line).to_a, T::Array[Integer])
+            text = truncate_snippet(fetch_snippet_text(lines_range, source_lines), @config.max_snippet_lines)
+            occurrence_str = calculate_occurrence(start_line, source_lines, node)
+            buffer.puts "  - **Branch Deficit:** Missing coverage for conditional `#{text}` #{occurrence_str}".rstrip
+          end
+        end
+      end
+    end
+  end
+end

data/lib/simplecov-ai/markdown_builder/deficit_grouper.rb

@@ -0,0 +1,84 @@
+# typed: strict
+# frozen_string_literal: true
+
+module SimpleCov
+  module Formatter
+    class AIFormatter
+      class MarkdownBuilder
+        # Groups missed lines and branches into DeficitGroup objects based on AST semantic boundaries.
+        class DeficitGrouper
+          extend T::Sig
+
+          sig { returns(T::Hash[String, DeficitGroup]) }
+          attr_reader :node_deficits
+
+          sig { params(nodes: T::Array[ASTResolver::SemanticNode]).void }
+          def initialize(nodes)
+            @nodes = nodes
+            @node_deficits = T.let({}, T::Hash[String, DeficitGroup])
+          end
+
+          sig do
+            params(file: SimpleCov::SourceFile, nodes: T::Array[ASTResolver::SemanticNode])
+              .returns(T::Hash[String, DeficitGroup])
+          end
+          def self.build(file, nodes)
+            grouper = new(nodes)
+            grouper.group_missed_lines(file)
+            grouper.group_missed_branches(file)
+            grouper.sort_deficits
+          end
+
+          sig { returns(T::Hash[String, DeficitGroup]) }
+          def sort_deficits
+            T.let(
+              @node_deficits.sort_by do |name, group|
+                if (node = group.semantic_node)
+                  node.start_line
+                else
+                  name.match(/\d+/)&.to_s&.to_i || Float::INFINITY
+                end
+              end.to_h,
+              T::Hash[String, DeficitGroup]
+            )
+          end
+
+          sig { params(file: SimpleCov::SourceFile).void }
+          def group_missed_lines(file)
+            file.missed_lines.each do |line|
+              add_missed_line(line)
+            end
+          end
+
+          sig { params(line: SimpleCov::SourceFile::Line).void }
+          def add_missed_line(line)
+            line_num = line.line_number
+            node = @nodes.reverse.find { |n| line_num.between?(n.start_line, n.end_line) }
+            node_name = node ? node.name : "Line #{line_num}"
+            @node_deficits[node_name] ||= DeficitGroup.new(semantic_node: node)
+            T.must(@node_deficits[node_name]).lines << line
+          end
+
+          sig { params(file: SimpleCov::SourceFile).void }
+          def group_missed_branches(file)
+            return unless file.respond_to?(:branches) && file.branches.any?
+
+            file.missed_branches.each do |branch|
+              add_missed_branch(branch)
+            end
+          end
+
+          sig { params(branch: SimpleCov::SourceFile::Branch).void }
+          def add_missed_branch(branch)
+            start_line = branch.start_line
+            end_line = branch.end_line
+            node = @nodes.reverse.find { |n| start_line >= n.start_line && end_line <= n.end_line }
+            node_name = node ? node.name : "Lines #{start_line}-#{end_line}"
+            @node_deficits[node_name] ||= DeficitGroup.new(semantic_node: node)
+            T.must(@node_deficits[node_name]).branches << branch
+          end
+        end
+      end
+    end
+  end
+end

data/lib/simplecov-ai/markdown_builder/snippet_formatter.rb

@@ -0,0 +1,76 @@
+# typed: strict
+# frozen_string_literal: true
+
+module SimpleCov
+  module Formatter
+    class AIFormatter
+      class MarkdownBuilder
+        # Handles extraction and formatting of source code snippets for the markdown digest.
+        module SnippetFormatter
+          extend T::Sig
+
+          # Extracts and normalizes exact string literals from the source file arrays.
+          #
+          # @param line_nums [Array<Integer>] Target line coordinates.
+          # @param source_lines [Array<String>] The raw text lines of the file.
+          # @return [String] Joined snippet text.
+          sig { params(line_nums: T::Array[Integer], source_lines: T::Array[String]).returns(String) }
+          def fetch_snippet_text(line_nums, source_lines)
+            line_nums.filter_map { |ln| source_lines[ln - 1]&.strip }.reject(&:empty?).join(' ')
+          end
+
+          # Safely limits the character length of a code snippet according to global configurations.
+          #
+          # @param text [String] The snippet to potentially truncate.
+          # @param max_snippet_lines [Integer] The configured max lines.
+          # @return [String] Truncated string with trailing ellipses if limit exceeded.
+          sig { params(text: String, max_snippet_lines: Integer).returns(String) }
+          def truncate_snippet(text, max_snippet_lines)
+            max_chars = max_snippet_lines * 80
+            text.length > max_chars ? "#{text[0...max_chars]}..." : text
+          end
+
+          # Disambiguates identical code snippets within the same semantic block (e.g., "(Occurrence 2 of 3)").
+          #
+          # @param line_num [Integer] The target coordinate of the deficit.
+          # @param source_lines [Array<String>] Raw file contents.
+          # @param node [ASTResolver::SemanticNode, nil] The semantic node boundary to search within.
+          # @return [String] Occurrence label or empty string if unique.
+          sig do
+            params(line_num: Integer, source_lines: T::Array[String],
+                   node: T.nilable(ASTResolver::SemanticNode)).returns(String)
+          end
+          def calculate_occurrence(line_num, source_lines, node)
+            return '' if node.nil?
+
+            first_line_of_snippet = source_lines[line_num - 1]&.strip
+            return '' if first_line_of_snippet.nil? || first_line_of_snippet.empty?
+
+            occurrences, current = count_snippet_occurrences(first_line_of_snippet, line_num, source_lines, node)
+
+            occurrences > 1 ? "(Occurrence #{current} of #{occurrences})." : ''
+          end
+
+          sig do
+            params(snippet: String, target_ln: Integer, source_lines: T::Array[String],
+                   node: ASTResolver::SemanticNode).returns([Integer, Integer])
+          end
+          def count_snippet_occurrences(snippet, target_ln, source_lines, node)
+            occurrences = 0
+            current_occurrence = 1
+
+            (node.start_line..node.end_line).each do |ln|
+              line_content = source_lines[ln - 1]&.strip
+              next unless line_content == snippet
+
+              occurrences += 1
+              current_occurrence = occurrences if ln == target_ln
+            end
+
+            [occurrences, current_occurrence]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/simplecov-ai/markdown_builder.rb

@@ -1,6 +1,13 @@
 # typed: strict
 # frozen_string_literal: true
 
+require_relative 'ast_resolver'
+require 'time'
+require_relative 'markdown_builder/snippet_formatter'
+require_relative 'markdown_builder/bypass_compiler'
+require_relative 'markdown_builder/deficit_grouper'
+require_relative 'markdown_builder/deficit_compiler'
+
 module SimpleCov
   module Formatter
     class AIFormatter
@@ -9,6 +16,17 @@ module SimpleCov
       # Serves as the primary mutation boundary to format AI consumption targets.
       class MarkdownBuilder
         extend T::Sig
+        include SnippetFormatter
+
+        # Groups unexecuted lines and branches under their common semantic node.
+        class DeficitGroup < T::Struct
+          # @return [ASTResolver::SemanticNode, nil] The corresponding structural boundary
+          prop :semantic_node, T.nilable(ASTResolver::SemanticNode), default: nil
+          # @return [Array<SimpleCov::SourceFile::Line>] The missed source lines
+          prop :lines, T::Array[SimpleCov::SourceFile::Line], default: []
+          # @return [Array<SimpleCov::SourceFile::Branch>] The missed conditional branches
+          prop :branches, T::Array[SimpleCov::SourceFile::Branch], default: []
+        end
 
         # Initializes the Markdown sequence compilation.
         #
@@ -21,6 +39,7 @@ module SimpleCov
           @buffer = T.let(StringIO.new, StringIO)
           @file_count = T.let(0, Integer)
           @truncated = T.let(false, T::Boolean)
+          @ast_cache = T.let({}, T::Hash[String, T::Array[ASTResolver::SemanticNode]])
         end
 
         # Executes the primary buffer composition logic yielding a monolithic compiled output.
@@ -30,142 +49,62 @@ module SimpleCov
         sig { returns(String) }
         def build
           write_header
-          write_deficits
-          write_bypasses if @config.include_bypasses
+          DeficitCompiler.new(@result, @config, self).write_deficits(@buffer)
+          BypassCompiler.new(@result, self).write_bypasses(@buffer) if @config.include_bypasses
           write_truncation_warning if @truncated
           @buffer.string
         end
 
-        private
-
-        sig { void }
-        def write_header
-          status = T.cast(@result.covered_percent, Float) >= 100.0 ? 'PASSED' : 'FAILED'
-          time_str = Time.now.to_s # UI timezone requirement
-
-          @buffer.puts '# AI Coverage Digest'
-          @buffer.puts "**Status:** #{status}"
-          @buffer.puts "**Global Line Coverage:** #{T.cast(@result.covered_percent, Float).round(1)}%"
-
-          branch_pct = begin
-            T.cast(@result.covered_branches, Float) / T.cast(@result.total_branches, Numeric) * 100
-          rescue StandardError
-            0.0
-          end
-          @buffer.puts "**Global Branch Coverage:** #{T.cast(branch_pct, Float).round(1)}%"
-          @buffer.puts "**Generated At:** #{time_str}"
-          @buffer.puts ''
+        sig { params(filename: String).returns(T.nilable(T::Array[ASTResolver::SemanticNode])) }
+        def try_resolve_ast(filename)
+          @ast_cache[filename] ||= ASTResolver.resolve(filename)
+        rescue StandardError
+          nil
         end
 
-        sig { void }
-        def write_deficits
-          files_enum = T.cast(@result.files, T::Enumerable[T.untyped])
-          files_array = T.let(files_enum.to_a, T::Array[SimpleCov::SourceFile])
-          # SCMD-REQ-014: Sort by coverage percent ASC, then by filename
-          files = T.let(
-            files_array.reject { |f| T.cast(f.covered_percent, Float) >= 100.0 }
-             .sort_by { |f| [T.cast(f.covered_percent, Float), T.cast(f.filename, String)] },
-            T::Array[SimpleCov::SourceFile]
-          )
-
-          return if files.empty?
-
-          @buffer.puts "## Coverage Deficits\n\n"
+        sig { returns(T::Boolean) }
+        def truncate_if_needed?
+          return false unless @buffer.size / 1024.0 > @config.max_file_size_kb
 
-          files.each do |file|
-            # Check size limits SCMD-REQ-012
-            if @buffer.size / 1024.0 > @config.max_file_size_kb
-              @truncated = true
-              break
-            end
-
-            @buffer.puts "### `#{T.cast(file.project_filename, String)}`"
-
-            begin
-              nodes = ASTResolver.resolve(T.cast(file.filename, String))
-            rescue StandardError => e
-              @buffer.puts "- **ERROR:** AST Parsing Failed (`#{e.class}`)"
-              next
-            end
-
-            process_deficits(file, nodes)
-          end
+          @truncated = true
+          true
         end
 
-        sig { params(file: SimpleCov::SourceFile, nodes: T::Array[ASTResolver::SemanticNode]).void }
-        def process_deficits(file, nodes)
-          T.cast(file.missed_lines, T::Array[SimpleCov::SourceFile::Line]).each do |line|
-            line_num = T.cast(line.line_number, Integer)
-            node = nodes.find { |n| line_num >= n.start_line && line_num <= n.end_line }
-            node_name = node ? node.name : "Line #{line_num}"
-            @buffer.puts "- `#{node_name}`\n  - **Line Deficit:** Unexecuted code."
-          end
-
-          process_branch_deficits(file, nodes) if file.respond_to?(:branches)
-
-          @buffer.puts ''
-        end
-
-        sig { params(file: SimpleCov::SourceFile, nodes: T::Array[ASTResolver::SemanticNode]).void }
-        def process_branch_deficits(file, nodes)
-          branches = file.branches
-          case branches
-          when Array
-            return unless branches.any?
-
-            T.cast(file.missed_branches, T::Array[SimpleCov::SourceFile::Branch]).each do |branch|
-              start_line = T.cast(branch.start_line, Integer)
-              end_line = T.cast(branch.end_line, Integer)
-              node = nodes.find { |n| start_line >= n.start_line && end_line <= n.end_line }
-              node_name = node ? node.name : "Lines #{start_line}-#{end_line}"
-              @buffer.puts "- `#{node_name}`\n  - **Branch Deficit:** Missing coverage for conditional."
-            end
-          end
+        private
 
+        # Writes the summary header containing global coverage percentages and generation metadata.
+        sig { void }
+        def write_header
+          status = @result.covered_percent >= 100.0 ? 'PASSED' : 'FAILED'
+          @buffer.puts '# AI Coverage Digest'
+          @buffer.puts "**Status:** #{status}"
+          @buffer.puts "**Global Line Coverage:** #{@result.covered_percent.round(1)}%"
+          @buffer.puts "**Global Branch Coverage:** #{calculate_branch_pct.round(1)}%"
+          @buffer.puts "**Generated At:** #{Time.now.iso8601} (Local Timezone)"
           @buffer.puts ''
         end
 
-        sig { void }
-        def write_bypasses
-          has_bypasses = T.let(false, T::Boolean)
-          bypass_buffer = T.let(StringIO.new, StringIO)
-
-          files_enum = T.cast(@result.files, T::Enumerable[T.untyped])
-          files_array = T.let(files_enum.to_a, T::Array[SimpleCov::SourceFile])
-
-          files_array.each do |file|
-            begin
-              nodes = ASTResolver.resolve(T.cast(file.filename, String))
-            rescue StandardError
-              next
-            end
+        sig { returns(Float) }
+        def calculate_branch_pct
+          return 0.0 unless @result.respond_to?(:covered_branches) && @result.respond_to?(:total_branches)
 
-            nodes_with_bypasses = nodes.select { |n| n.bypasses.any? }
-            next if nodes_with_bypasses.empty?
-
-            has_bypasses = true
-            write_file_bypasses(bypass_buffer, file, nodes_with_bypasses)
-          end
-
-          return unless has_bypasses
-
-          @buffer.puts "## Ignored Coverage Bypasses\n\n"
-          @buffer.puts bypass_buffer.string
-        end
+          total = @result.total_branches
+          return 0.0 if total.to_i.zero?
 
-        sig { params(buffer: StringIO, file: SimpleCov::SourceFile, bypasses: T::Array[ASTResolver::SemanticNode]).void }
-        def write_file_bypasses(buffer, file, bypasses)
-          buffer.puts "### `#{file.project_filename}`"
-          bypasses.each do |node|
-            buffer.puts "- `#{node.name}`\n  - **Bypass Present:** Contains `# :nocov:` directive artificially ignoring coverage."
-          end
-          buffer.puts ''
+          covered = @result.covered_branches
+          covered.to_f / total * 100.0
         end
 
+        # Appends a critical alert if the output hit the token-ceiling constraint and was forcibly terminated.
         sig { void }
         def write_truncation_warning
           @buffer.puts '> **[WARNING] TRUNCATION NOTIFICATION:**'
-          @buffer.puts "> The total coverage deficit report exceeded the maximum token constraint (#{@config.max_file_size_kb} kB). The report was truncated. The deficits detailed above represent the lowest-coverage (most critical) files. Please resolve these deficits to reveal the remaining uncovered files in subsequent test runs."
+          msg = '> The total coverage deficit report exceeded the maximum token ' \
+                "constraint (#{@config.max_file_size_kb} kB). " \
+                'The report was truncated. The deficits detailed above represent ' \
+                'the lowest-coverage (most critical) files. ' \
+                'Please resolve these deficits to reveal the remaining uncovered files in subsequent test runs.'
+          @buffer.puts msg
         end
       end
     end

data/lib/simplecov-ai/version.rb

@@ -8,7 +8,7 @@ module SimpleCov
     class AIFormatter
       # The semantic version identifier for the gem, used for dependency resolution
       # and enforcing compatibility across upgrades.
-      VERSION = T.let('0.10.2', String)
+      VERSION = T.let('0.10.4', String)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: simplecov-ai
 version: !ruby/object:Gem::Version
-  version: 0.10.2
+  version: 0.10.4
 platform: ruby
 authors:
 - Vitalii Lazebnyi
@@ -151,44 +151,58 @@ dependencies:
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.28'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.28'
 - !ruby/object:Gem::Dependency
   name: rubocop-performance
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.14'
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.11'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.11'
+- !ruby/object:Gem::Dependency
+  name: rubocop-sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rubocop-thread_safety
   requirement: !ruby/object:Gem::Requirement
@@ -218,7 +232,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.5'
 - !ruby/object:Gem::Dependency
-  name: tsort
+  name: standard-sorbet
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -232,7 +246,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: yard
+  name: tapioca
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -246,7 +260,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: yard-sorbet
+  name: tsort
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -260,19 +274,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: simplecov-ai
+  name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard-sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Generates highly concise, deterministic Markdown coverage digests tailored
   for LLMs and autonomous agents by matching coverage deficits to their AST semantic
   boundaries rather than line numbers.
@@ -289,6 +317,10 @@ files:
 - lib/simplecov-ai/ast_resolver.rb
 - lib/simplecov-ai/configuration.rb
 - lib/simplecov-ai/markdown_builder.rb
+- lib/simplecov-ai/markdown_builder/bypass_compiler.rb
+- lib/simplecov-ai/markdown_builder/deficit_compiler.rb
+- lib/simplecov-ai/markdown_builder/deficit_grouper.rb
+- lib/simplecov-ai/markdown_builder/snippet_formatter.rb
 - lib/simplecov-ai/version.rb
 homepage: https://github.com/VitaliiLazebnyi/simplecov-ai
 licenses:
@@ -304,7 +336,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="