cov-loupe 3.0.0

data/lib/cov_loupe/cli.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'app_config'
+require_relative 'option_parser_builder'
+require_relative 'commands/command_factory'
+require_relative 'option_parsers/error_helper'
+require_relative 'option_parsers/env_options_parser'
+require_relative 'constants'
+require_relative 'presenters/project_coverage_presenter'
+
+module CovLoupe
+  class CoverageCLI
+    SUBCOMMANDS = %w[list summary raw uncovered detailed totals validate version].freeze
+    HORIZONTAL_RULE = '-' * 79
+
+    # Reference shared constant to avoid duplication with ModeDetector
+    OPTIONS_EXPECTING_ARGUMENT = Constants::OPTIONS_EXPECTING_ARGUMENT
+
+    attr_reader :config
+
+    # Initialize CLI for pure CLI usage only.
+    # Always runs as CLI, no mode detection needed.
+    def initialize(error_handler: nil)
+      @config = AppConfig.new
+      @cmd = nil
+      @cmd_args = []
+      @custom_error_handler = error_handler # Store custom handler if provided
+      @error_handler = nil # Will be created after parsing options
+    end
+
+    def run(argv)
+      context = nil
+      # argv should already include environment options (merged by caller)
+      # Pre-scan for error-mode to ensure early errors are logged with correct verbosity
+      pre_scan_error_mode(argv)
+      parse_options!(argv)
+      enforce_version_subcommand_if_requested
+
+      context = CovLoupe.create_context(
+        error_handler: error_handler, # construct after options to respect --error-mode
+        log_target: config.log_file.nil? ? CovLoupe.context.log_target : config.log_file,
+        mode: :cli
+      )
+
+      CovLoupe.with_context(context) do
+        if @cmd
+          run_subcommand(@cmd, @cmd_args)
+        else
+          show_default_report(sort_order: config.sort_order)
+        end
+      end
+    rescue OptionParser::ParseError => e
+      # Handle any option parsing errors (invalid option/argument) without relying on
+      # @error_handler, which is not guaranteed to be initialized yet.
+      with_context_if_available(context) { handle_option_parser_error(e, argv: argv) }
+    rescue CovLoupe::Error => e
+      with_context_if_available(context) { handle_user_facing_error(e) }
+    end
+
+    def show_default_report(sort_order: :descending, output: $stdout)
+      model = CoverageModel.new(**config.model_options)
+      presenter = Presenters::ProjectCoveragePresenter.new(
+        model: model,
+        sort_order: sort_order,
+        check_stale: (config.staleness == :error),
+        tracked_globs: config.tracked_globs
+      )
+
+      if config.format != :table
+        require_relative 'formatters'
+        output.puts Formatters.format(presenter.relativized_payload, config.format)
+        return
+      end
+
+      file_summaries = presenter.relative_files
+      output.puts model.format_table(
+        file_summaries,
+        sort_order: sort_order,
+        check_stale: (config.staleness == :error),
+        tracked_globs: nil
+      )
+    end
+
+    private def parse_options!(argv)
+      require 'optparse'
+      parser = build_option_parser
+
+      # order! parses global options (updating config) and removes them from argv.
+      # It stops cleanly at the first subcommand (e.g., 'list', 'summary') or unknown option.
+      # If it stops at an unknown option, it raises OptionParser::InvalidOption.
+      parser.order!(argv)
+
+      # The first remaining argument is the subcommand
+      @cmd = argv.shift
+
+      # Verify it's a valid subcommand if present
+      if @cmd && !SUBCOMMANDS.include?(@cmd)
+        raise UsageError, "Unknown subcommand: '#{@cmd}'. Valid subcommands: #{SUBCOMMANDS.join(', ')}"
+      end
+
+      # Any remaining arguments belong to the subcommand
+      @cmd_args = argv
+    end
+
+    private def error_handler
+      @error_handler ||= @custom_error_handler ||
+                         ErrorHandlerFactory.for_cli(error_mode: config.error_mode)
+    end
+
+    private def pre_scan_error_mode(argv)
+      env_parser = OptionParsers::EnvOptionsParser.new
+      config.error_mode = env_parser.pre_scan_error_mode(argv) || :log
+    end
+
+    private def build_option_parser
+      builder = OptionParserBuilder.new(config)
+      builder.build_option_parser
+    end
+
+    # Converts the -v/--version flags into the version subcommand.
+    # When the user passes -v or --version, config.show_version is set to true during option parsing.
+    # This method intercepts that flag and redirects execution to the 'version' subcommand,
+    # ensuring consistent version display regardless of whether the user runs
+    # `cov-loupe -v`, `cov-loupe --version`, or `cov-loupe version`.
+    private def enforce_version_subcommand_if_requested
+      @cmd = 'version' if config.show_version
+    end
+
+    private def with_context_if_available(ctx, &block)
+      if ctx
+        CovLoupe.with_context(ctx, &block)
+      else
+        block.call
+      end
+    end
+
+    private def run_subcommand(cmd, args)
+      # Check if user mistakenly placed global options after the subcommand
+      check_for_misplaced_global_options(cmd, args)
+
+      command = Commands::CommandFactory.create(cmd, self)
+      command.execute(args)
+    rescue CovLoupe::Error => e
+      handle_user_facing_error(e)
+    rescue => e
+      error_handler.handle_error(e, context: "subcommand '#{cmd}'")
+    end
+
+    private def handle_option_parser_error(error, argv: [])
+      @error_helper ||= OptionParsers::ErrorHelper.new(SUBCOMMANDS)
+      @error_helper.handle_option_parser_error(error, argv: argv)
+    end
+
+    private def check_for_misplaced_global_options(cmd, args)
+      # Global options that users commonly place after subcommands by mistake
+      global_options = %w[-r --resultset -R --root -f --format -o --sort-order -s --source
+                          -c --context-lines -S --staleness -g --tracked-globs
+                          -l --log-file --error-mode --color --no-color]
+
+      misplaced = args.select { |arg| global_options.include?(arg) }
+      return if misplaced.empty?
+
+      option_list = misplaced.join(', ')
+      raise UsageError, "Global option(s) must come BEFORE the subcommand.\n" \
+        "You used: #{cmd} #{option_list}\n" \
+        "Correct: #{option_list} #{cmd}\n\n" \
+        "Example: cov-loupe --format json #{cmd}"
+    end
+
+    private def handle_user_facing_error(error)
+      error_handler.handle_error(error, context: 'CLI', reraise: false)
+      warn error.user_friendly_message
+      warn error.backtrace.first(5).join("\n") if config.error_mode == :debug && error.backtrace
+      exit 1
+    end
+  end
+end

data/lib/cov_loupe/commands/base_command.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../formatters'
+require_relative '../formatters/source_formatter'
+require_relative '../model'
+require_relative '../errors'
+
+module CovLoupe
+  module Commands
+    class BaseCommand
+      def initialize(cli_context)
+        @cli = cli_context
+        @config = cli_context.config
+        @source_formatter = Formatters::SourceFormatter.new(
+          **config.formatter_options
+        )
+      end
+
+      attr_reader :cli, :config, :source_formatter
+
+      protected def model
+        @model ||= CoverageModel.new(**config.model_options)
+      end
+
+      protected def handle_with_path(args, name)
+        path = args.shift or raise UsageError.for_subcommand("#{name} <path>")
+        yield(path)
+      rescue Errno::ENOENT
+        raise FileNotFoundError, "File not found: #{path}"
+      rescue Errno::EACCES
+        raise FilePermissionError, "Permission denied: #{path}"
+      end
+
+      protected def maybe_output_structured_format?(obj, model)
+        return false if config.format == :table
+
+        puts CovLoupe::Formatters.format(model.relativize(obj), config.format)
+        true
+      end
+
+      protected def emit_structured_format_with_optional_source?(data, model, path)
+        return false if config.format == :table
+
+        relativized = model.relativize(data)
+        if config.source_mode
+          payload = relativized.merge('source' => build_source_payload(model, path))
+          puts CovLoupe::Formatters.format(payload, config.format)
+        else
+          puts CovLoupe::Formatters.format(relativized, config.format)
+        end
+        true
+      end
+
+      protected def build_source_payload(model, path)
+        source_formatter.build_source_payload(model, path, mode: config.source_mode,
+          context: config.source_context)
+      end
+
+      protected def print_source_for(model, path)
+        formatted = source_formatter.format_source_for(model, path, mode: config.source_mode,
+          context: config.source_context)
+        puts formatted
+      end
+    end
+  end
+end

data/lib/cov_loupe/commands/command_factory.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+require_relative 'list_command'
+require_relative 'version_command'
+require_relative 'summary_command'
+require_relative 'raw_command'
+require_relative 'uncovered_command'
+require_relative 'detailed_command'
+require_relative 'totals_command'
+require_relative 'validate_command'
+
+module CovLoupe
+  module Commands
+    class CommandFactory
+      COMMAND_MAP = {
+        'list' => ListCommand,
+        'version' => VersionCommand,
+        'summary' => SummaryCommand,
+        'raw' => RawCommand,
+        'uncovered' => UncoveredCommand,
+        'detailed' => DetailedCommand,
+        'totals' => TotalsCommand,
+        'total' => TotalsCommand, # Alias for backward compatibility
+        'validate' => ValidateCommand
+      }.freeze
+
+      def self.create(command_name, cli_context)
+        command_class = COMMAND_MAP[command_name]
+        unless command_class
+          raise UsageError.for_subcommand(
+            'list | summary <path> | raw <path> | uncovered <path> | detailed <path> ' \
+              '| totals | validate <file> | validate -i <code> | version'
+          )
+        end
+
+        command_class.new(cli_context)
+      end
+
+      def self.available_commands
+        COMMAND_MAP.keys
+      end
+    end
+  end
+end

data/lib/cov_loupe/commands/detailed_command.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+require_relative '../formatters/source_formatter'
+require_relative '../presenters/coverage_detailed_presenter'
+require_relative '../table_formatter'
+
+module CovLoupe
+  module Commands
+    class DetailedCommand < BaseCommand
+      def execute(args)
+        handle_with_path(args, 'detailed') do |path|
+          presenter = Presenters::CoverageDetailedPresenter.new(model: model, path: path)
+          data = presenter.absolute_payload
+          break if emit_structured_format_with_optional_source?(data, model, path)
+
+          relative_path = presenter.relative_path
+          puts "File: #{relative_path}"
+          puts
+
+          # Table format with box-drawing
+          headers = ['Line', 'Hits', 'Covered']
+          rows = data['lines'].map do |r|
+            [r['line'].to_s, r['hits'].to_s, r['covered'] ? 'yes' : 'no']
+          end
+
+          puts TableFormatter.format(
+            headers: headers,
+            rows: rows,
+            alignments: [:right, :right, :center]
+          )
+
+          print_source_for(model, path) if config.source_mode
+        end
+      end
+    end
+  end
+end

data/lib/cov_loupe/commands/list_command.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+
+module CovLoupe
+  module Commands
+    class ListCommand < BaseCommand
+      def execute(_args)
+        cli.send(:show_default_report, sort_order: config.sort_order)
+      end
+    end
+  end
+end

data/lib/cov_loupe/commands/raw_command.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+require_relative '../presenters/coverage_raw_presenter'
+require_relative '../table_formatter'
+
+module CovLoupe
+  module Commands
+    class RawCommand < BaseCommand
+      def execute(args)
+        handle_with_path(args, 'raw') do |path|
+          presenter = Presenters::CoverageRawPresenter.new(model: model, path: path)
+          data = presenter.absolute_payload
+          break if maybe_output_structured_format?(data, model)
+
+          relative_path = presenter.relative_path
+          puts "File: #{relative_path}"
+          puts
+
+          # Table format for raw coverage data
+          headers = ['Line', 'Coverage']
+          rows = data['lines'].each_with_index.map do |coverage, index|
+            [
+              (index + 1).to_s,
+              coverage.nil? ? 'nil' : coverage.to_s
+            ]
+          end
+
+          puts TableFormatter.format(
+            headers: headers,
+            rows: rows,
+            alignments: [:right, :right]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/cov_loupe/commands/summary_command.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+require_relative '../presenters/coverage_summary_presenter'
+require_relative '../table_formatter'
+
+module CovLoupe
+  module Commands
+    class SummaryCommand < BaseCommand
+      def execute(args)
+        handle_with_path(args, 'summary') do |path|
+          presenter = Presenters::CoverageSummaryPresenter.new(model: model, path: path)
+          data = presenter.absolute_payload
+          break if emit_structured_format_with_optional_source?(data, model, path)
+
+          relative_path = presenter.relative_path
+          summary = data['summary']
+
+          # Table format with box-drawing
+          headers = ['File', '%', 'Covered', 'Total', 'Stale']
+          stale_marker = data['stale'] ? 'Yes' : ''
+          rows = [[
+            relative_path,
+            format('%.2f%%', summary['percentage']),
+            summary['covered'].to_s,
+            summary['total'].to_s,
+            stale_marker
+          ]]
+
+          puts TableFormatter.format(
+            headers: headers,
+            rows: rows,
+            alignments: [:left, :right, :right, :right, :center]
+          )
+          puts
+          print_source_for(model, path) if config.source_mode
+        end
+      end
+    end
+  end
+end

data/lib/cov_loupe/commands/totals_command.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+require_relative '../presenters/project_totals_presenter'
+require_relative '../table_formatter'
+
+module CovLoupe
+  module Commands
+    class TotalsCommand < BaseCommand
+      def execute(args)
+        unless args.empty?
+          raise UsageError.for_subcommand('totals')
+        end
+
+        presenter = Presenters::ProjectTotalsPresenter.new(
+          model: model,
+          check_stale: (config.staleness == :error),
+          tracked_globs: config.tracked_globs
+        )
+        payload = presenter.absolute_payload
+        return if maybe_output_structured_format?(payload, model)
+
+        lines = payload['lines']
+        files = payload['files']
+
+        # Table format
+        headers = ['Metric', 'Total', 'Covered', 'Uncovered', '%']
+        rows = [
+          [
+            'Lines',
+            lines['total'].to_s,
+            lines['covered'].to_s,
+            lines['uncovered'].to_s,
+            format('%.2f%%', payload['percentage'])
+          ],
+          [
+            'Files',
+            files['total'].to_s,
+            files['ok'].to_s,
+            files['stale'].to_s,
+            ''
+          ]
+        ]
+
+        puts TableFormatter.format(
+          headers: headers,
+          rows: rows,
+          alignments: [:left, :right, :right, :right, :right]
+        )
+      end
+    end
+  end
+end

data/lib/cov_loupe/commands/uncovered_command.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+require_relative '../presenters/coverage_uncovered_presenter'
+require_relative '../table_formatter'
+
+module CovLoupe
+  module Commands
+    class UncoveredCommand < BaseCommand
+      def execute(args)
+        handle_with_path(args, 'uncovered') do |path|
+          presenter = Presenters::CoverageUncoveredPresenter.new(model: model, path: path)
+          data = presenter.absolute_payload
+          break if emit_structured_format_with_optional_source?(data, model, path)
+
+          relative_path = presenter.relative_path
+          summary = data['summary']
+
+          puts "File: #{relative_path}"
+          puts "Coverage: #{format('%.2f%%', summary['percentage'])} " \
+               "(#{summary['covered']}/#{summary['total']} lines)"
+          puts
+
+          # Table format for uncovered lines
+          uncovered_lines = data['uncovered']
+          if uncovered_lines.empty?
+            puts 'All lines covered!'
+          else
+            headers = ['Line']
+            rows = uncovered_lines.map { |line| [line.to_s] }
+
+            puts TableFormatter.format(
+              headers: headers,
+              rows: rows,
+              alignments: [:right]
+            )
+          end
+
+          puts
+          print_source_for(model, path) if config.source_mode
+        end
+      end
+    end
+  end
+end

data/lib/cov_loupe/commands/validate_command.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+require_relative '../predicate_evaluator'
+
+module CovLoupe
+  module Commands
+    # Validates coverage data against a predicate.
+    # Exits with code 0 (pass), 1 (fail), or 2 (error).
+    #
+    # Usage:
+    #   cov-loupe validate policy.rb                # File mode
+    #   cov-loupe validate -i '->(m) { ... }'       # Inline mode
+    class ValidateCommand < BaseCommand
+      def execute(args)
+        # Parse command-specific options
+        inline_mode = false
+        code = nil
+
+        # Simple option parsing for -i/--inline flag
+        while args.first&.start_with?('-')
+          case args.first
+          when '-i', '--inline'
+            inline_mode = true
+            args.shift
+            code = args.shift or raise UsageError.for_subcommand('validate -i <code>')
+          else
+            raise UsageError, "Unknown option for validate: #{args.first}"
+          end
+        end
+
+        # If not inline mode, expect a file path as positional argument
+        unless inline_mode
+          file_path = args.shift or raise UsageError.for_subcommand('validate <file> | -i <code>')
+          code = file_path
+        end
+
+        # Evaluate the predicate
+        result = if inline_mode
+          PredicateEvaluator.evaluate_code(code, model)
+        else
+          PredicateEvaluator.evaluate_file(code, model)
+        end
+
+        exit(result ? 0 : 1)
+      rescue UsageError
+        # Usage errors should exit with code 1, not 2
+        raise
+      rescue => e
+        handle_predicate_error(e)
+      end
+
+      private def handle_predicate_error(error)
+        warn "Predicate error: #{error.message}"
+        warn error.backtrace.first(5).join("\n") if config.error_mode == :debug
+        exit 2
+      end
+    end
+  end
+end

data/lib/cov_loupe/commands/version_command.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'base_command'
+require_relative '../table_formatter'
+
+module CovLoupe
+  module Commands
+    class VersionCommand < BaseCommand
+      def execute(_args)
+        @gem_root = File.expand_path('../../..', __dir__)
+
+        if config.format == :table
+          data = {
+            'Version' => CovLoupe::VERSION,
+            'Gem Root' => @gem_root,
+            'Documentation' => 'README.md and docs/user/**/*.md in gem root'
+          }
+          puts TableFormatter.format_vertical(data)
+        else
+          puts CovLoupe::Formatters.format(version_info, config.format)
+        end
+      end
+
+      private def version_info
+        {
+          version: CovLoupe::VERSION,
+          gem_root: @gem_root
+        }
+      end
+    end
+  end
+end

data/lib/cov_loupe/config_parser.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'app_config'
+require_relative 'option_parser_builder'
+
+module CovLoupe
+  # Centralized configuration parser for both CLI and MCP modes
+  # Parses argv (which should already include environment options merged by caller)
+  class ConfigParser
+    attr_reader :config, :argv
+
+    def initialize(argv)
+      @argv = argv
+      @config = AppConfig.new
+    end
+
+    # Parse argv (with env opts already merged) and return config
+    # @param argv [Array<String>] command-line arguments (should include env opts if needed)
+    # @return [AppConfig] populated configuration object
+    def self.parse(argv)
+      new(argv).parse
+    end
+
+    def parse
+      # Build and execute the option parser
+      parser = OptionParserBuilder.new(config).build_option_parser
+      parser.parse!(argv)
+
+      config
+    end
+  end
+end

data/lib/cov_loupe/constants.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module CovLoupe
+  # Shared constants used across multiple components to avoid duplication.
+  # This ensures consistency between CLI option parsing and mode detection.
+  module Constants
+    # CLI options that expect an argument value following them.
+    # Used by both CoverageCLI and ModeDetector to correctly parse command-line arguments.
+    OPTIONS_EXPECTING_ARGUMENT = %w[
+      -r --resultset
+      -R --root
+      -f --format
+      -o --sort-order
+      -s --source
+      -c --context-lines
+      -S --staleness
+      -g --tracked-globs
+      -l --log-file
+      --error-mode
+    ].freeze
+  end
+end