simplecov-ai 0.10.4 → 0.10.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21fb51a293aef52967848c9b4fcc176b83aa274c347fb29abeaf76a34f040754
-  data.tar.gz: b43d99c3b4064c5e2914be0df4251774f78f0f6fa41cc51ae85c4e4547a586e9
+  metadata.gz: 72c1e34acc5609236e3551bf3759099948f9dd98ae12b04ee249ea0e03682e79
+  data.tar.gz: 84d74a91bc0ac99d9841242aa095a5876316f8493e8a1d9ac8be1aca1146003c
 SHA512:
-  metadata.gz: 55f0042ff2503ffc573c39a1393a407e66988e2de5f3e79d5d35eb539f70645bb1bcd6374870d84682dba430a87b7b0f9601baa446e9beb99f1e9e7aa3c45cf1
-  data.tar.gz: 2a94566df43e8bdd3c8e68ffcbe95bbda0683be0cd661313ede1af5a421d0972ad03d3b0363cf72259d631e80a490529075adc2b13df58a02d7ffa4c777ef95c
+  metadata.gz: b4339ac621867c733eebbc80bcb6b8453839e210f3ce6e9017a276d4342b48c1aa2e9e068f7068b3780e33934edffdcda5afec4ffb670b9a2dee214ea68f5ebd
+  data.tar.gz: 1cc89347ca1d591d0f207d81dde82864062743b8cc8b981b71c5f7f2529ae0f06898d4949c9a1f7ed5916b943cb510a4a4528235acb15135d1f8fd116bb25ae8

data/lib/simplecov-ai/ast_resolver/semantic_node.rb

@@ -0,0 +1,47 @@
+# typed: strict
+# frozen_string_literal: true
+
+module SimpleCov
+  module Formatter
+    class AIFormatter
+      class ASTResolver
+        # An immutable struct housing bounds, identification metrics, and static bypassing
+        # definitions derived from traversing the AST nodes.
+        class SemanticNode
+          extend T::Sig
+
+          sig { returns(String) }
+          attr_reader :name, :type
+
+          sig { returns(Integer) }
+          attr_reader :start_line, :end_line
+
+          sig { returns(T::Array[String]) }
+          attr_reader :bypass_reasons
+
+          sig do
+            params(
+              name: String,
+              type: String,
+              start_line: Integer,
+              end_line: Integer,
+              bypass_reasons: T::Array[String]
+            ).void
+          end
+          def initialize(name:, type:, start_line:, end_line:, bypass_reasons: [])
+            @name = name
+            @type = type
+            @start_line = start_line
+            @end_line = end_line
+            @bypass_reasons = bypass_reasons
+          end
+
+          sig { params(bypass_reason: String).void }
+          def add_bypass(bypass_reason)
+            @bypass_reasons << bypass_reason
+          end
+        end
+      end
+    end
+  end
+end

data/lib/simplecov-ai/ast_resolver.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require 'parser/current'
+require_relative 'ast_resolver/semantic_node'
 
 module SimpleCov
   module Formatter
@@ -13,42 +14,16 @@ module SimpleCov
       class ASTResolver
         extend T::Sig
 
-        # An immutable struct housing bounds, identification metrics, and static bypassing
-        # definitions derived from traversing the AST nodes.
-        class SemanticNode
-          extend T::Sig
-
-          sig { returns(String) }
-          attr_reader :name, :type
-
-          sig { returns(Integer) }
-          attr_reader :start_line, :end_line
-
-          sig { returns(T::Array[String]) }
-          attr_reader :bypasses
-
-          sig do
-            params(
-              name: String,
-              type: String,
-              start_line: Integer,
-              end_line: Integer,
-              bypasses: T::Array[String]
-            ).void
-          end
-          def initialize(name:, type:, start_line:, end_line:, bypasses: [])
-            @name = name
-            @type = type
-            @start_line = start_line
-            @end_line = end_line
-            @bypasses = bypasses
-          end
-
-          sig { params(bypass: String).void }
-          def add_bypass(bypass)
-            @bypasses << bypass
-          end
-        end
+        # Separator used to denote namespace nesting (e.g., Module::Class)
+        NAMESPACE_SEPARATOR = T.let('::', String)
+        # Separator used to denote instance methods (e.g., Class#method)
+        INSTANCE_SEPARATOR = T.let('#', String)
+        # Separator used to denote singleton/class methods (e.g., Class.method)
+        SINGLETON_SEPARATOR = T.let('.', String)
+        # Label applied to nodes representing instance methods
+        TYPE_INSTANCE_METHOD = T.let('Instance Method', String)
+        # Label applied to nodes representing singleton methods
+        TYPE_SINGLETON_METHOD = T.let('Singleton Method', String)
 
         # Orchestrates the initial mapping algorithm on a target file to extract structural
         # metadata, circumventing potential syntax violations explicitly.
@@ -94,23 +69,21 @@ module SimpleCov
 
         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)
+          comments.each do |comment|
+            comment_text = T.cast(comment.text, String)
+            assign_bypass(nodes, comment, comment_text.strip) if comment_text.include?(Constants::NOCOV_DIRECTIVE)
           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)
+        sig { params(nodes: T::Array[SemanticNode], comment: Parser::Source::Comment, bypass_reason: String).void }
+        def assign_bypass(nodes, comment, bypass_reason)
+          comment_loc = T.cast(comment.loc, Parser::Source::Map)
+          comment_line = T.cast(comment_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)
+          innermost_node = nodes.reverse.find { |node| comment_line.between?(node.start_line - 1, node.end_line + 1) }
+          innermost_node&.add_bypass(bypass_reason)
         end
 
         sig do
@@ -138,8 +111,8 @@ module SimpleCov
           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)]
+          new_context = context.empty? ? name : "#{context}#{NAMESPACE_SEPARATOR}#{name}"
+          [new_context, build_node(node, new_context, node.type.to_s.capitalize)]
         end
 
         sig do
@@ -148,8 +121,8 @@ module SimpleCov
         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')]
+          new_context = context.empty? ? "#{INSTANCE_SEPARATOR}#{name}" : "#{context}#{INSTANCE_SEPARATOR}#{name}"
+          [new_context, build_node(node, new_context, TYPE_INSTANCE_METHOD)]
         end
 
         sig do
@@ -158,8 +131,8 @@ module SimpleCov
         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')]
+          new_context = context.empty? ? "#{SINGLETON_SEPARATOR}#{name}" : "#{context}#{SINGLETON_SEPARATOR}#{name}"
+          [new_context, build_node(node, new_context, TYPE_SINGLETON_METHOD)]
         end
 
         sig do
@@ -168,9 +141,9 @@ module SimpleCov
         end
         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: [])
+          start_line = T.cast(loc.line, Integer)
+          end_line = T.cast(loc.last_line, Integer)
+          SemanticNode.new(name: name, type: type, start_line: start_line, end_line: end_line, bypass_reasons: [])
         end
       end
     end

data/lib/simplecov-ai/configuration.rb

@@ -10,6 +10,19 @@ module SimpleCov
       class Configuration
         extend T::Sig
 
+        # Default output path for the generated markdown report
+        DEFAULT_REPORT_PATH = T.let('coverage/ai_report.md', String)
+        # Default maximum size of the output file in kilobytes
+        DEFAULT_MAX_FILE_SIZE_KB = T.let(50, Integer)
+        # Default maximum number of lines for a single snippet
+        DEFAULT_MAX_SNIPPET_LINES = T.let(5, Integer)
+        # Default flag for outputting to console
+        DEFAULT_OUTPUT_TO_CONSOLE = T.let(false, T::Boolean)
+        # Default granularity level of the report
+        DEFAULT_GRANULARITY = T.let(:fine, Symbol)
+        # Default flag for including bypassed regions in the report
+        DEFAULT_INCLUDE_BYPASSES = T.let(true, T::Boolean)
+
         # The absolute or relative system path where the final token-efficient markdown
         # document acts as an artifact.
         # @return [String]
@@ -44,12 +57,12 @@ module SimpleCov
 
         sig { void }
         def initialize
-          @report_path = T.let('coverage/ai_report.md', String)
-          @max_file_size_kb = T.let(50, Integer)
-          @max_snippet_lines = T.let(5, Integer)
-          @output_to_console = T.let(false, T::Boolean)
-          @granularity = T.let(:fine, Symbol)
-          @include_bypasses = T.let(true, T::Boolean)
+          @report_path = T.let(DEFAULT_REPORT_PATH, String)
+          @max_file_size_kb = T.let(DEFAULT_MAX_FILE_SIZE_KB, Integer)
+          @max_snippet_lines = T.let(DEFAULT_MAX_SNIPPET_LINES, Integer)
+          @output_to_console = T.let(DEFAULT_OUTPUT_TO_CONSOLE, T::Boolean)
+          @granularity = T.let(DEFAULT_GRANULARITY, Symbol)
+          @include_bypasses = T.let(DEFAULT_INCLUDE_BYPASSES, T::Boolean)
         end
       end
     end

data/lib/simplecov-ai/constants.rb

@@ -0,0 +1,20 @@
+# typed: strict
+# frozen_string_literal: true
+
+module SimpleCov
+  module Formatter
+    class AIFormatter
+      # Houses globally shared constant values utilized across the AI formatter suite
+      # to prevent magic string duplication and establish a single source of truth.
+      module Constants
+        extend T::Sig
+
+        # The explicit value used to designate a file or coverage block as perfectly covered.
+        PERFECT_COVERAGE_PERCENT = T.let(100.0, Float)
+
+        # The directive typically employed within comments to force coverage engines to bypass execution tracking.
+        NOCOV_DIRECTIVE = T.let(':nocov:', String)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# typed: strict
+# frozen_string_literal: true
+
+module SimpleCov
+  module Formatter
+    class AIFormatter
+      class MarkdownBuilder
+        # Enriches SimpleCov branch data with column information from raw coverage data.
+        class BranchEnricher
+          extend T::Sig
+
+          sig { params(file: SimpleCov::SourceFile).void }
+          def self.enrich(file)
+            return unless file.respond_to?(:coverage_data)
+
+            case (cov = file.coverage_data)
+            when Hash
+              case (branches = cov['branches'])
+              when Hash
+                process_branches(file, branches)
+              end
+            end
+          rescue StandardError
+            nil
+          end
+
+          class << self
+            extend T::Sig
+
+            private
+
+            sig { params(file: SimpleCov::SourceFile, branches: T::Hash[BasicObject, BasicObject]).void }
+            def process_branches(file, branches)
+              raw = extract_raw_branches(file, branches)
+              apply_column_data(file.branches, raw)
+            end
+
+            sig { params(file: SimpleCov::SourceFile, branches: T::Hash[BasicObject, BasicObject]).returns(T::Array[BasicObject]) }
+            def extract_raw_branches(file, branches)
+              branches.flat_map do |_condition, branch_hash|
+                case branch_hash
+                when Hash
+                  branch_hash.map do |branch_data, _hit_count|
+                    T.cast(file.send(:restore_ruby_data_structure, branch_data), BasicObject)
+                  end
+                else
+                  []
+                end
+              end
+            end
+
+            sig { params(branches: T::Array[SimpleCov::SourceFile::Branch], raw_branches: T::Array[BasicObject]).void }
+            def apply_column_data(branches, raw_branches)
+              branches.zip(raw_branches).each do |branch, raw|
+                case raw
+                when Array
+                  next unless raw.size >= 6
+
+                  branch.instance_variable_set(:@start_col, T.cast(raw[3], Integer))
+                  branch.instance_variable_set(:@end_col, T.cast(raw[5], Integer))
+                  branch.class.send(:attr_reader, :start_col, :end_col) unless branch.respond_to?(:start_col)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -9,9 +9,21 @@ module SimpleCov
         class BypassCompiler
           extend T::Sig
 
-          sig { params(result: SimpleCov::Result, builder: MarkdownBuilder).void }
-          def initialize(result, builder)
-            @result = result
+          # Section heading for bypassed coverage
+          HEADING = T.let("## Ignored Coverage Bypasses\n\n", String)
+          # Template for formatting file headers in the bypass section
+          FILE_HEADING_TEMPLATE = T.let('### `%s`', String)
+          # Template for detailing an individual bypass directive
+          BYPASS_TEMPLATE = T.let(
+            "- `%s`\n  " \
+            '- **Bypass Present:** Contains `%s` directive artificially ' \
+            'ignoring coverage (Occurrence %d of %d).',
+            String
+          )
+
+          sig { params(coverage_metrics: SimpleCov::Result, builder: MarkdownBuilder).void }
+          def initialize(coverage_metrics, builder)
+            @coverage_metrics = coverage_metrics
             @builder = builder
           end
 
@@ -22,7 +34,7 @@ module SimpleCov
 
             return unless has_bypasses
 
-            buffer.puts "## Ignored Coverage Bypasses\n\n"
+            buffer.puts HEADING
             buffer.puts bypass_buffer.string
           end
 
@@ -31,12 +43,12 @@ module SimpleCov
           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?
+            T.let(@coverage_metrics.files.to_a, T::Array[SimpleCov::SourceFile]).each do |file|
+              bypassed_nodes = fetch_bypassed_nodes(file.filename)
+              next if bypassed_nodes.empty?
 
               has_bypasses = true
-              write_file_bypasses(buffer, file, bypassed)
+              write_file_bypasses(buffer, file, bypassed_nodes)
             end
             has_bypasses
           end
@@ -44,19 +56,17 @@ module SimpleCov
           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? } : []
+            nodes ? nodes.select { |node| node.bypass_reasons.any? } : []
           end
 
           sig do
-            params(buffer: StringIO, file: SimpleCov::SourceFile, bypasses: T::Array[ASTResolver::SemanticNode]).void
+            params(buffer: StringIO, file: SimpleCov::SourceFile, bypassed_nodes: 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})."
+          def write_file_bypasses(buffer, file, bypassed_nodes)
+            buffer.puts format(FILE_HEADING_TEMPLATE, file.project_filename)
+            total = bypassed_nodes.size
+            bypassed_nodes.each_with_index do |node, idx|
+              buffer.puts format(BYPASS_TEMPLATE, node.name, Constants::NOCOV_DIRECTIVE, idx + 1, total)
             end
             buffer.puts ''
           end

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

@@ -10,22 +10,35 @@ module SimpleCov
           extend T::Sig
           include SnippetFormatter
 
-          sig { params(result: SimpleCov::Result, config: Configuration, builder: MarkdownBuilder).void }
-          def initialize(result, config, builder)
-            @result = result
+          # Header for the coverage deficits section
+          HEADING = T.let("## Coverage Deficits\n\n", String)
+          # Template for file-level deficit headings
+          FILE_HEADING_TEMPLATE = T.let('### `%s`', String)
+          # Error message for AST parsing failures
+          ERROR_AST_FAILED = T.let("  - **ERROR:** AST Parsing Failed. Showing raw line numbers instead.\n", String)
+          # Template for node-level deficit headings
+          NODE_HEADING_TEMPLATE = T.let('- `%s`', String)
+          # Coarse-grained deficit summary message
+          DEFICIT_COARSE = T.let('  - **Deficit:** Contains unexecuted lines or branches.', String)
+          # Template for a specific line deficit
+          LINE_DEFICIT_TEMPLATE = T.let('  - **Line Deficit:** [L%d] `%s` %s', String)
+          # Template for a specific branch deficit
+          BRANCH_DEFICIT_TEMPLATE = T.let('  - **Branch Deficit:** [L%s] Missing coverage for `%s` branch: `%s` %s',
+                                          String)
+
+          sig { params(coverage_metrics: SimpleCov::Result, config: Configuration, builder: MarkdownBuilder).void }
+          def initialize(coverage_metrics, config, builder)
+            @coverage_metrics = coverage_metrics
             @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]
-            )
+            files = find_deficit_files
             return if files.empty?
 
-            buffer.puts "## Coverage Deficits\n\n"
+            buffer.puts HEADING
             files.each do |file|
               break if @builder.truncate_if_needed?
 
@@ -35,93 +48,59 @@ module SimpleCov
 
           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)
+          sig { returns(T::Array[SimpleCov::SourceFile]) }
+          def find_deficit_files
+            files_with_deficits = @coverage_metrics.files.reject do |f|
+              line_perfect?(f) && branch_perfect?(f)
+            end
+            T.let(files_with_deficits.sort_by { |file| [file.covered_percent, file.filename] }, T::Array[SimpleCov::SourceFile])
           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 ''
+          sig { params(file: SimpleCov::SourceFile).returns(T::Boolean) }
+          def line_perfect?(file)
+            file.covered_percent >= Constants::PERFECT_COVERAGE_PERCENT
           end
 
-          sig do
-            params(buffer: StringIO, file: SimpleCov::SourceFile, nodes: T::Array[ASTResolver::SemanticNode]).void
+          sig { params(file: SimpleCov::SourceFile).returns(T::Boolean) }
+          def branch_perfect?(file)
+            cov = file.respond_to?(:branches_coverage_percent) ? file.branches_coverage_percent : nil
+            branch_coverage_perfect?(cov)
           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)
+          sig { params(coverage: T.nilable(BasicObject)).returns(T::Boolean) }
+          def branch_coverage_perfect?(coverage)
+            case coverage
+            when Float, Integer
+              coverage >= Constants::PERFECT_COVERAGE_PERCENT
+            else
+              case coverage
+              when nil then true
+              else false
+              end
             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}`"
+          sig { params(buffer: StringIO, file: SimpleCov::SourceFile).void }
+          def process_file(buffer, file)
+            BranchEnricher.enrich(file)
+            buffer.puts format(FILE_HEADING_TEMPLATE, file.project_filename)
+
+            formatter = DeficitFormatter.new(buffer, @config)
+            nodes = @builder.try_resolve_ast(file.filename)
 
-            if @config.granularity == :coarse
-              buffer.puts '  - **Deficit:** Contains unexecuted lines or branches.'
+            if nodes
+              formatter.process_deficits(file, nodes, -> { safe_readlines(file.filename) })
             else
-              format_deficit_group(buffer, group, source_lines)
+              formatter.format_raw_deficits(file, safe_readlines(file.filename))
             end
           end
 
           sig { params(filename: String).returns(T::Array[String]) }
-          def fetch_source_lines(filename)
+          def safe_readlines(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

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

@@ -0,0 +1,142 @@
+# typed: strict
+# frozen_string_literal: true
+
+module SimpleCov
+  module Formatter
+    class AIFormatter
+      class MarkdownBuilder
+        # Handles the formatting of line and branch deficits into markdown.
+        class DeficitFormatter
+          extend T::Sig
+          include SnippetFormatter
+
+          # Error message for AST parsing failures
+          ERROR_AST_FAILED = T.let("  - **ERROR:** AST Parsing Failed. Showing raw line numbers instead.\n", String)
+          # Template for node-level deficit headings
+          NODE_HEADING_TEMPLATE = T.let('- `%s`', String)
+          # Coarse-grained deficit summary message
+          DEFICIT_COARSE = T.let('  - **Deficit:** Contains unexecuted lines or branches.', String)
+          # Template for a specific line deficit
+          LINE_DEFICIT_TMPL = T.let('  - **Line Deficit:** [L%d] `%s` %s', String)
+          # Template for a specific branch deficit
+          BRANCH_DEFICIT_TMPL = T.let('  - **Branch Deficit:** [L%s] Missing coverage for `%s` branch: `%s` %s', String)
+
+          sig { params(buffer: StringIO, config: Configuration).void }
+          def initialize(buffer, config)
+            @buffer = buffer
+            @config = config
+          end
+
+          sig { params(file: SimpleCov::SourceFile, source_lines: T::Array[String]).void }
+          def format_raw_deficits(file, source_lines)
+            @buffer.puts ERROR_AST_FAILED
+            deficit_group = MarkdownBuilder::DeficitGroup.new(lines: file.missed_lines, branches: file.missed_branches)
+            format_deficit_group(deficit_group, source_lines)
+            @buffer.puts ''
+          end
+
+          sig do
+            params(file: SimpleCov::SourceFile, nodes: T::Array[ASTResolver::SemanticNode],
+                   safe_readlines_proc: T.proc.returns(T::Array[String])).void
+          end
+          def process_deficits(file, nodes, safe_readlines_proc)
+            node_deficits = DeficitGrouper.build(file, nodes)
+            source_lines = T.let(nil, T.nilable(T::Array[String]))
+
+            node_deficits.each do |node_name, deficit_group|
+              source_lines ||= safe_readlines_proc.call
+              format_node_deficit(node_name, deficit_group, source_lines)
+            end
+
+            @buffer.puts ''
+          end
+
+          private
+
+          sig { params(node_name: String, deficit_group: DeficitGroup, source_lines: T::Array[String]).void }
+          def format_node_deficit(node_name, deficit_group, source_lines)
+            @buffer.puts format(NODE_HEADING_TEMPLATE, node_name)
+
+            if @config.granularity == :coarse
+              @buffer.puts DEFICIT_COARSE
+            else
+              format_deficit_group(deficit_group, source_lines)
+            end
+          end
+
+          sig { params(deficit_group: DeficitGroup, source_lines: T::Array[String]).void }
+          def format_deficit_group(deficit_group, source_lines)
+            deficit_group.lines.each do |line|
+              write_line_snippet(line, source_lines, deficit_group.semantic_node)
+            end
+
+            deficit_group.branches.each do |branch|
+              write_branch_snippet(branch, source_lines, deficit_group.semantic_node)
+            end
+          end
+
+          sig do
+            params(line: SimpleCov::SourceFile::Line, source_lines: T::Array[String],
+                   node: T.nilable(ASTResolver::SemanticNode)).void
+          end
+          def write_line_snippet(line, source_lines, node)
+            text = truncate_snippet(fetch_snippet_text([line.line_number], source_lines), @config.max_snippet_lines)
+            occurrence_str = calculate_occurrence(line.line_number, source_lines, node)
+            @buffer.puts format(LINE_DEFICIT_TMPL, line.line_number, text, occurrence_str).rstrip
+          end
+
+          sig do
+            params(branch: SimpleCov::SourceFile::Branch, source_lines: T::Array[String],
+                   node: T.nilable(ASTResolver::SemanticNode)).void
+          end
+          def write_branch_snippet(branch, source_lines, node)
+            text = truncate_snippet(extract_branch_text(branch, source_lines), @config.max_snippet_lines)
+            occurrence = calculate_occurrence(branch.start_line, source_lines, node)
+            label = format_branch_label(branch)
+
+            type_val = branch.respond_to?(:type) ? branch.type : nil
+
+            type_label = type_val ? type_val.to_s : 'conditional'
+            @buffer.puts format(BRANCH_DEFICIT_TMPL, label, type_label, text, occurrence).rstrip
+          end
+
+          sig { params(branch: SimpleCov::SourceFile::Branch).returns(String) }
+          def format_branch_label(branch)
+            branch.start_line == branch.end_line ? branch.start_line.to_s : "#{branch.start_line}-#{branch.end_line}"
+          end
+
+          sig { params(branch: SimpleCov::SourceFile::Branch, source_lines: T::Array[String]).returns(String) }
+          def extract_branch_text(branch, source_lines)
+            start_col = fetch_column(branch, :start_col)
+            end_col = fetch_column(branch, :end_col)
+
+            inline_text = extract_inline_branch(branch, start_col, end_col, source_lines)
+            return inline_text if inline_text
+
+            lines_range = T.cast((branch.start_line..branch.end_line).to_a, T::Array[Integer])
+            fetch_snippet_text(lines_range, source_lines)
+          end
+
+          sig { params(branch: SimpleCov::SourceFile::Branch, col: Symbol).returns(T.nilable(Integer)) }
+          def fetch_column(branch, col)
+            val = branch.respond_to?(col) ? branch.public_send(col) : branch.instance_variable_get(:"@#{col}")
+            T.cast(val, T.nilable(Integer))
+          end
+
+          sig do
+            params(branch: SimpleCov::SourceFile::Branch, start_col: T.nilable(Integer),
+                   end_col: T.nilable(Integer), source_lines: T::Array[String]).returns(T.nilable(String))
+          end
+          def extract_inline_branch(branch, start_col, end_col, source_lines)
+            return nil unless branch.start_line == branch.end_line && start_col && end_col
+
+            line_text = source_lines[branch.start_line - 1]
+            return nil unless line_text && line_text.length >= end_col
+
+            line_text[start_col...end_col].to_s.strip
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -9,6 +9,11 @@ module SimpleCov
         class DeficitGrouper
           extend T::Sig
 
+          # Fallback identifier format for unassociated lines
+          FALLBACK_LINE_NAME = T.let('Line %d', String)
+          # Fallback identifier format for unassociated branches
+          FALLBACK_BRANCH_NAME = T.let('Lines %d-%d', String)
+
           sig { returns(T::Hash[String, DeficitGroup]) }
           attr_reader :node_deficits
 
@@ -32,11 +37,11 @@ module SimpleCov
           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
+              @node_deficits.sort_by do |node_name, deficit_group|
+                if (semantic_node = deficit_group.semantic_node)
+                  semantic_node.start_line
                 else
-                  name.match(/\d+/)&.to_s&.to_i || Float::INFINITY
+                  node_name.match(/\d+/)&.to_s&.to_i || Float::INFINITY
                 end
               end.to_h,
               T::Hash[String, DeficitGroup]
@@ -53,9 +58,9 @@ module SimpleCov
           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)
+            matched_node = @nodes.reverse.find { |node| line_num.between?(node.start_line, node.end_line) }
+            node_name = matched_node ? matched_node.name : format(FALLBACK_LINE_NAME, line_num)
+            @node_deficits[node_name] ||= DeficitGroup.new(semantic_node: matched_node)
             T.must(@node_deficits[node_name]).lines << line
           end
 
@@ -72,9 +77,11 @@ module SimpleCov
           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)
+            matched_node = @nodes.reverse.find do |node|
+              start_line >= node.start_line && end_line <= node.end_line
+            end
+            node_name = matched_node ? matched_node.name : format(FALLBACK_BRANCH_NAME, start_line, end_line)
+            @node_deficits[node_name] ||= DeficitGroup.new(semantic_node: matched_node)
             T.must(@node_deficits[node_name]).branches << branch
           end
         end

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

@@ -9,6 +9,13 @@ module SimpleCov
         module SnippetFormatter
           extend T::Sig
 
+          # Approximate maximum characters per line for truncation calculation
+          ESTIMATED_CHARS_PER_LINE = T.let(80, Integer)
+          # Suffix added to truncated snippets
+          TRUNCATION_ELLIPSIS = T.let('...', String)
+          # Template for identical snippet occurrences indicator
+          OCCURRENCE_TEMPLATE = T.let('(Occurrence %d of %d).', String)
+
           # Extracts and normalizes exact string literals from the source file arrays.
           #
           # @param line_nums [Array<Integer>] Target line coordinates.
@@ -16,18 +23,22 @@ module SimpleCov
           # @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(' ')
+            line_nums.filter_map { |line_number| source_lines[line_number - 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 snippet_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
+          sig { params(snippet_text: String, max_snippet_lines: Integer).returns(String) }
+          def truncate_snippet(snippet_text, max_snippet_lines)
+            max_chars = max_snippet_lines * ESTIMATED_CHARS_PER_LINE
+            if snippet_text.length > max_chars
+              "#{snippet_text[0...max_chars]}#{TRUNCATION_ELLIPSIS}"
+            else
+              snippet_text
+            end
           end
 
           # Disambiguates identical code snippets within the same semantic block (e.g., "(Occurrence 2 of 3)").
@@ -48,23 +59,23 @@ module SimpleCov
 
             occurrences, current = count_snippet_occurrences(first_line_of_snippet, line_num, source_lines, node)
 
-            occurrences > 1 ? "(Occurrence #{current} of #{occurrences})." : ''
+            occurrences > 1 ? Kernel.format(OCCURRENCE_TEMPLATE, current, occurrences) : ''
           end
 
           sig do
-            params(snippet: String, target_ln: Integer, source_lines: T::Array[String],
+            params(snippet: String, target_line_number: Integer, source_lines: T::Array[String],
                    node: ASTResolver::SemanticNode).returns([Integer, Integer])
           end
-          def count_snippet_occurrences(snippet, target_ln, source_lines, node)
+          def count_snippet_occurrences(snippet, target_line_number, source_lines, node)
             occurrences = 0
             current_occurrence = 1
 
-            (node.start_line..node.end_line).each do |ln|
-              line_content = source_lines[ln - 1]&.strip
+            (node.start_line..node.end_line).each do |line_number|
+              line_content = source_lines[line_number - 1]&.strip
               next unless line_content == snippet
 
               occurrences += 1
-              current_occurrence = occurrences if ln == target_ln
+              current_occurrence = occurrences if line_number == target_line_number
             end
 
             [occurrences, current_occurrence]

data/lib/simplecov-ai/markdown_builder.rb

@@ -3,9 +3,12 @@
 
 require_relative 'ast_resolver'
 require 'time'
+require 'stringio'
 require_relative 'markdown_builder/snippet_formatter'
 require_relative 'markdown_builder/bypass_compiler'
 require_relative 'markdown_builder/deficit_grouper'
+require_relative 'markdown_builder/branch_enricher'
+require_relative 'markdown_builder/deficit_formatter'
 require_relative 'markdown_builder/deficit_compiler'
 
 module SimpleCov
@@ -18,6 +21,35 @@ module SimpleCov
         extend T::Sig
         include SnippetFormatter
 
+        # The number of bytes in a kilobyte
+        BYTES_PER_KB = T.let(1024.0, Float)
+        # Text representation for a passed coverage check
+        STATUS_PASSED = T.let('PASSED', String)
+        # Text representation for a failed coverage check
+        STATUS_FAILED = T.let('FAILED', String)
+
+        # Template for the report header
+        HEADER_TEMPLATE = T.let(
+          "# AI Coverage Digest\n" \
+          "**Status:** %<status>s\n" \
+          "**Global Line Coverage:** %<line_pct>s%%\n" \
+          "**Global Branch Coverage:** %<branch_pct>s%%\n" \
+          "**Generated At:** %<time>s (Local Timezone)\n",
+          String
+        )
+
+        # Alert heading for truncated reports
+        TRUNCATION_ALERT_HEADING = T.let('> **[WARNING] TRUNCATION NOTIFICATION:**', String)
+        # Alert body for truncated reports
+        TRUNCATION_ALERT_BODY = T.let(
+          '> The total coverage deficit report exceeded the maximum token ' \
+          'constraint (%<limit>d 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.',
+          String
+        )
+
         # Groups unexecuted lines and branches under their common semantic node.
         class DeficitGroup < T::Struct
           # @return [ASTResolver::SemanticNode, nil] The corresponding structural boundary
@@ -30,11 +62,11 @@ module SimpleCov
 
         # Initializes the Markdown sequence compilation.
         #
-        # @param result [SimpleCov::Result] Application-wide coverage aggregation metrics
+        # @param coverage_metrics [SimpleCov::Result] Application-wide coverage aggregation metrics
         # @param config [Configuration] Pre-registered runtime toggles
-        sig { params(result: SimpleCov::Result, config: Configuration).void }
-        def initialize(result, config)
-          @result = T.let(result, SimpleCov::Result)
+        sig { params(coverage_metrics: SimpleCov::Result, config: Configuration).void }
+        def initialize(coverage_metrics, config)
+          @coverage_metrics = T.let(coverage_metrics, SimpleCov::Result)
           @config = T.let(config, Configuration)
           @buffer = T.let(StringIO.new, StringIO)
           @file_count = T.let(0, Integer)
@@ -49,8 +81,8 @@ module SimpleCov
         sig { returns(String) }
         def build
           write_header
-          DeficitCompiler.new(@result, @config, self).write_deficits(@buffer)
-          BypassCompiler.new(@result, self).write_bypasses(@buffer) if @config.include_bypasses
+          DeficitCompiler.new(@coverage_metrics, @config, self).write_deficits(@buffer)
+          BypassCompiler.new(@coverage_metrics, self).write_bypasses(@buffer) if @config.include_bypasses
           write_truncation_warning if @truncated
           @buffer.string
         end
@@ -64,7 +96,7 @@ module SimpleCov
 
         sig { returns(T::Boolean) }
         def truncate_if_needed?
-          return false unless @buffer.size / 1024.0 > @config.max_file_size_kb
+          return false unless @buffer.size / BYTES_PER_KB > @config.max_file_size_kb
 
           @truncated = true
           true
@@ -75,36 +107,36 @@ module SimpleCov
         # 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 ''
+          covered_pct = @coverage_metrics.covered_percent
+          status = covered_pct >= Constants::PERFECT_COVERAGE_PERCENT ? STATUS_PASSED : STATUS_FAILED
+          @buffer.puts format(
+            HEADER_TEMPLATE,
+            status: status,
+            line_pct: covered_pct.round(1),
+            branch_pct: calculate_branch_pct.round(1),
+            time: Time.now.iso8601
+          )
         end
 
         sig { returns(Float) }
         def calculate_branch_pct
-          return 0.0 unless @result.respond_to?(:covered_branches) && @result.respond_to?(:total_branches)
+          unless @coverage_metrics.respond_to?(:covered_branches) &&
+                 @coverage_metrics.respond_to?(:total_branches)
+            return 0.0
+          end
 
-          total = @result.total_branches
+          total = @coverage_metrics.total_branches
           return 0.0 if total.to_i.zero?
 
-          covered = @result.covered_branches
-          covered.to_f / total * 100.0
+          covered = @coverage_metrics.covered_branches
+          covered.to_f / total * Constants::PERFECT_COVERAGE_PERCENT
         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:**'
-          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
+          @buffer.puts TRUNCATION_ALERT_HEADING
+          @buffer.puts format(TRUNCATION_ALERT_BODY, limit: @config.max_file_size_kb)
         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.4', String)
+      VERSION = T.let('0.10.5', String)
     end
   end
 end

data/lib/simplecov-ai.rb

@@ -5,6 +5,7 @@ require 'sorbet-runtime'
 require 'simplecov'
 require 'parser/current'
 
+require_relative 'simplecov-ai/constants'
 require_relative 'simplecov-ai/version'
 require_relative 'simplecov-ai/configuration'
 require_relative 'simplecov-ai/ast_resolver'
@@ -21,6 +22,9 @@ module SimpleCov
     class AIFormatter
       extend T::Sig
 
+      # The standard output prefix used when reporting generation success.
+      SUCCESS_LOG_PREFIX = T.let("\n[SimpleCov AI Formatter] Digest written to ", String)
+
       # Retrieves the global configuration for the AI formatter.
       # The instantiation pattern ensures that defaults are securely lazily loaded
       # before any coverage processing begins.
@@ -46,18 +50,18 @@ module SimpleCov
       # directory structures, and securely persists the result to disk to guarantee
       # an idempotent and strictly defined output location.
       #
-      # @param result [SimpleCov::Result] The test coverage outcome generated by SimpleCov.
+      # @param coverage_metrics [SimpleCov::Result] The test coverage outcome generated by SimpleCov.
       # @return [void]
-      sig { params(result: SimpleCov::Result).void }
-      def format(result)
+      sig { params(coverage_metrics: SimpleCov::Result).void }
+      def format(coverage_metrics)
         config = self.class.configuration
-        builder = MarkdownBuilder.new(result, config)
+        builder = MarkdownBuilder.new(coverage_metrics, config)
         digest = builder.build
 
         FileUtils.mkdir_p(File.dirname(config.report_path))
         File.write(config.report_path, digest)
 
-        puts "\n[SimpleCov AI Formatter] Digest written to #{config.report_path}" if config.output_to_console
+        puts "#{SUCCESS_LOG_PREFIX}#{config.report_path}" if config.output_to_console
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: simplecov-ai
 version: !ruby/object:Gem::Version
-  version: 0.10.4
+  version: 0.10.5
 platform: ruby
 authors:
 - Vitalii Lazebnyi
@@ -315,10 +315,14 @@ files:
 - certs/simplecov-ai-public_cert.pem
 - lib/simplecov-ai.rb
 - lib/simplecov-ai/ast_resolver.rb
+- lib/simplecov-ai/ast_resolver/semantic_node.rb
 - lib/simplecov-ai/configuration.rb
+- lib/simplecov-ai/constants.rb
 - lib/simplecov-ai/markdown_builder.rb
+- lib/simplecov-ai/markdown_builder/branch_enricher.rb
 - lib/simplecov-ai/markdown_builder/bypass_compiler.rb
 - lib/simplecov-ai/markdown_builder/deficit_compiler.rb
+- lib/simplecov-ai/markdown_builder/deficit_formatter.rb
 - lib/simplecov-ai/markdown_builder/deficit_grouper.rb
 - lib/simplecov-ai/markdown_builder/snippet_formatter.rb
 - lib/simplecov-ai/version.rb
@@ -343,7 +347,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: An AI-optimized Markdown formatter for SimpleCov utilizing AST mapping.
 test_files: []