branchproof 0.11.1 → 0.12.0

data/lib/branchproof/cli.rb

@@ -18,20 +18,28 @@ module Branchproof
     VIEWS = Report::VIEWS.to_h { |view| [view.to_s.tr("_", "-"), view] }
                          .merge("decision_tables" => :decision_tables).freeze
 
-    def initialize(stdout:, stderr:)
+    def initialize(stdout:, stderr:, env: ENV)
       @stdout = stdout
       @stderr = stderr
+      @env = env
     end
 
     def call(argv)
       argv = Array(argv)
-      return help if [["--help"], ["help"], ["analyze", "--help"]].include?(argv)
+      return help if [["--help"], ["help"], ["analyze", "--help"], ["collate", "--help"]].include?(argv)
+      return doctor_command(argv.drop(1)) if argv.first == "doctor"
+      return collate_command(argv.drop(1)) if argv.first == "collate"
       return offline(argv) if %w[report compare].include?(argv.first)
+      return usage_error("mutation testing is not supported yet; use doctor, analyze, report, compare, or collate") if argv.first == "mutate"
 
       options = parse(argv)
-      return usage_error("expected analyze, report, or compare; use branchproof --help") unless options
+      return usage_error("expected doctor, analyze, report, compare, or collate; use branchproof --help") unless options
 
       inventory = build_inventory(options)
+      changed_scope = if options[:changed_since]
+                        ChangedScope.new(root: options[:project][:root], ref: options[:changed_since])
+                                    .call(inventory: inventory)
+                      end
       evidence = empty_evidence(inventory, options)
       baseline = if run_worker?(options)
                    run_worker(options, inventory, evidence)
@@ -78,8 +86,10 @@ module Branchproof
                           analysis: analysis, minima: minima, baseline: baseline, diagnostics: diagnostics,
                           level: options[:level], missing_only: options[:missing_only], view: options[:view],
                           run_metadata: run_metadata(options, baseline), minimum: options[:minimum],
-                          focus: options[:focus], top: options[:top])
+                          focus: options[:focus], top: options[:top], changed_scope: changed_scope,
+                          minimum_changed: options[:minimum_changed])
       output_report(report, options)
+      write_step_summary(report, options)
       report.exit_code
     rescue ArgumentError => e
       usage_error(e.message)
@@ -94,34 +104,100 @@ module Branchproof
     def help
       @stdout.write(<<~HELP)
         Usage:
+          branchproof doctor [SOURCE_GLOB ...] [--test TEST_GLOB] [--project auto|ruby|rails] [--framework auto|minitest|rspec]
+            [--config PATH|--no-config] [--format terminal|json]
           branchproof analyze [SOURCE_GLOB ...] [--test TEST_GLOB] [--project auto|ruby|rails] [--framework auto|minitest|rspec]
-            [--view decisions|conditions|tests|decision-tables] [--level 1|2|3] [--missing-only] [--minimum CRITERION=THRESHOLD]
+            [--view decisions|conditions|tests|decision-tables|summary] [--level 1|2|3] [--missing-only] [--minimum CRITERION=THRESHOLD] [--minimum-changed CRITERION=THRESHOLD]
+            [--changed-since REF]
             [--focus PATH[:LINE]] [--top N]
-            [--format terminal|json] [--output PATH] [--limits PATH] [--config PATH|--no-config]
+            [--format terminal|json|github] [--output PATH] [--limits PATH] [--config PATH|--no-config]
             [--no-reachability] [-- RUNNER_ARGS]
-          branchproof report SNAPSHOT [--view decisions|conditions|tests|decision-tables]
-            [--level 1|2|3] [--missing-only] [--minimum CRITERION=THRESHOLD] [--focus PATH[:LINE]] [--top N]
-            [--format terminal|json] [--output PATH]
+          branchproof report SNAPSHOT [--view decisions|conditions|tests|decision-tables|summary]
+            [--level 1|2|3] [--missing-only] [--minimum CRITERION=THRESHOLD] [--minimum-changed CRITERION=THRESHOLD] [--focus PATH[:LINE]] [--top N]
+            [--format terminal|json|github|html] [--output PATH]
           branchproof compare BEFORE AFTER [--format terminal|json] [--output PATH] [--fail-on-regression]
+          branchproof collate REPORT... [--manifest PATH] [--format terminal|json|github|html] [--output PATH]
         mcdc accepts the same commands as a compatibility alias.
         JSON always contains full evidence; --view requires terminal output.
+        github prints Actions annotations for the summary ranking and appends Markdown to $GITHUB_STEP_SUMMARY.
+        HTML report output is self-contained and offline; it uses an integrated layout, so --view is unavailable.
         decision_tables is also accepted as an alias for the decision-tables view.
         --no-reachability keeps every generated decision-table rule as a coverage obligation.
+        --changed-since REF captures tracked changes from a commit to the current worktree; --minimum-changed requires this scope and gates its coverage separately.
       HELP
       0
     end
 
+    def doctor_command(args)
+      return help if args == ["--help"]
+
+      format = doctor_json_requested?(args) ? :json : :terminal
+      begin
+        analyze_args = doctor_analyze_args(args)
+        options = parse(analyze_args, doctor: true)
+        source_files = select_source_files(options).select { |path| File.file?(path) }
+        test_files = options[:tests].select { |path| File.file?(path) }
+        document = Doctor.new(options: options).document(source_files: source_files, test_files: test_files)
+        format = options[:format]
+      rescue ArgumentError, SystemCallError, IOError => e
+        document = Doctor.error(e.message)
+      end
+      output_doctor(document, format)
+      document[:status] == "ready" ? 0 : 2
+    end
+
+    def doctor_json_requested?(args)
+      args.each_cons(2).any? { |flag, format| flag == "--format" && format == "json" }
+    end
+
+    def doctor_analyze_args(args)
+      allowed_with_value = %w[--test --project --framework --config --format]
+      allowed_without_value = ["--no-config"]
+      analyze = ["analyze"]
+      until args.empty?
+        token = args.shift
+        if allowed_with_value.include?(token)
+          value = args.shift
+          raise ArgumentError, "#{token} requires a value" if value.to_s.empty? || value.start_with?("-")
+          if token == "--format" && !%w[terminal json].include?(value)
+            raise ArgumentError, "format must be terminal or json"
+          end
+
+          analyze.push(token, value)
+        elsif allowed_without_value.include?(token)
+          analyze << token
+        elsif token.start_with?("-")
+          raise ArgumentError, "#{token} is not supported by doctor"
+        else
+          analyze << token
+        end
+      end
+      analyze
+    end
+
+    def output_doctor(document, format)
+      if format == :json
+        @stdout.write(JSON.generate(normalize(document)))
+        @stdout.write("\n")
+      else
+        @stdout.write(Doctor.terminal(document))
+      end
+    end
+
     def parse_view(view)
       resolved = VIEWS[view.to_s]
-      raise ArgumentError, "view must be decisions, conditions, tests, or decision-tables" unless resolved
+      raise ArgumentError, "view must be decisions, conditions, tests, decision-tables, or summary" unless resolved
 
       resolved
     end
 
     def validate_view!(options)
-      return unless options[:explicit_view] && options[:format] == :json
+      return unless options[:explicit_view]
+      raise ArgumentError, "HTML uses an integrated layout; --view is unavailable" if options[:format] == :html
+      raise ArgumentError, "--view requires terminal format; JSON contains full evidence" if options[:format] == :json
+      return unless options[:format] == :github
 
-      raise ArgumentError, "--view requires terminal format; JSON contains full evidence"
+      raise ArgumentError, "--view requires terminal format; GitHub output uses the summary ranking"
     end
 
     def offline(argv)
@@ -141,27 +217,111 @@ module Branchproof
         if options[:level] > 1 && !document["analysis"]
           raise ArgumentError, "saved report has no analysis; use --level 1"
         end
-        if options[:missing_only] && (options[:format] != :terminal || options[:level] == 1)
-          raise ArgumentError, "--missing-only requires terminal format and level 2 or 3"
+        if options[:missing_only] && (!%i[terminal html].include?(options[:format]) || options[:level] == 1)
+          raise ArgumentError, "--missing-only requires terminal or HTML format and level 2 or 3"
         end
 
         report = Report.from_document(document: document, level: options[:level], view: options[:view],
                                       missing_only: options[:missing_only], minimum: options[:minimum_overrides],
+                                      minimum_changed: options[:minimum_changed_overrides],
                                       focus: options[:focus], top: options[:top])
         output_report(report, options)
+        write_step_summary(report, options)
         report.exit_code
       end
     end
 
+    def collate_command(args)
+      options, paths = parse_collate(args)
+      manifest = if options[:manifest]
+                   require_relative "collation_manifest"
+                   CollationManifest.new(path: options[:manifest], supplied_paths: paths)
+                 end
+      protected_paths = paths.map { File.expand_path(_1) }
+      if manifest
+        protected_paths.concat(manifest.declared_paths)
+        protected_paths << File.expand_path(options[:manifest])
+      end
+      reject_collation_output_collision!(protected_paths, options[:output]) if options[:output]
+
+      supplied = if manifest
+                   manifest.inputs
+                 else
+                   paths.map { |path| { id: nil, path: File.expand_path(path) } }
+                 end
+      inputs = supplied.map do |input|
+        input.merge(document: SavedReport.read(input.fetch(:path)))
+      end
+      document = Collation.new(inputs: inputs, expected_shards: manifest&.expected_ids).call
+      report = Report.from_document(document: document, level: document.dig("run_metadata", "requested_level"))
+      output_report(report, options)
+      write_step_summary(report, options)
+      report.exit_code
+    end
+
+    def parse_collate(args)
+      options = { format: :json }
+      paths = []
+      seen = {}
+      until args.empty?
+        token = args.shift
+        case token
+        when "--format"
+          argument = collate_option_value(args, seen, token)
+          raise ArgumentError, "format must be terminal, json, github, or html" unless %w[terminal json github html].include?(argument)
+
+          options[:format] = argument.to_sym
+        when "--output", "--manifest"
+          argument = collate_option_value(args, seen, token)
+          options[token == "--output" ? :output : :manifest] = argument
+        else
+          raise ArgumentError, "unknown option: #{token}" if token.start_with?("-")
+
+          paths << token
+        end
+      end
+      raise ArgumentError, "collate requires at least one saved report" if paths.empty?
+
+      [options, paths]
+    end
+
+    def collate_option_value(args, seen, token)
+      raise ArgumentError, "#{token} may be specified only once" if seen[token]
+
+      seen[token] = true
+      argument = args.shift
+      raise ArgumentError, "#{token} requires a value" if argument.to_s.empty? || argument.start_with?("-")
+
+      argument
+    end
+
+    def reject_collation_output_collision!(protected_paths, output)
+      require_relative "collation_manifest"
+      output_path = File.expand_path(output)
+      output_identity = CollationManifest.path_identity(output_path)
+      collision = protected_paths.any? do |path|
+        File.expand_path(path) == output_path ||
+          CollationManifest.path_identity(path) == output_identity ||
+          (File.exist?(path) && File.exist?(output_path) && File.identical?(path, output_path))
+      end
+      raise ArgumentError, "output must not overwrite an input, declared report, or manifest" if collision
+    end
+
     def parse_offline(command, args)
       options = { format: :terminal, view: :decisions, missing_only: false, minimum_overrides: {} }
       paths = []
       until args.empty?
         token = args.shift
         case token
+        when "--changed-since"
+          raise ArgumentError, "--changed-since is available only for analyze"
         when "--format"
           format = args.shift
-          raise ArgumentError, "format must be terminal or json" unless %w[terminal json].include?(format)
+          if command == "compare"
+            raise ArgumentError, "format must be terminal or json" unless %w[terminal json].include?(format)
+          else
+            raise ArgumentError, "format must be terminal, json, github, or html" unless %w[terminal json github html].include?(format)
+          end
 
           options[:format] = format.to_sym
         when "--output"
@@ -171,7 +331,7 @@ module Branchproof
           raise ArgumentError, "--fail-on-regression requires compare" unless command == "compare"
 
           options[:fail_on_regression] = true
-        when "--view", "--level", "--missing-only", "--minimum", "--focus", "--top"
+        when "--view", "--level", "--missing-only", "--minimum", "--minimum-changed", "--focus", "--top"
           raise ArgumentError, "#{token} requires report" unless command == "report"
 
           case token
@@ -183,6 +343,8 @@ module Branchproof
             raise ArgumentError, "level must be 1, 2, or 3" unless (1..3).cover?(options[:level])
           when "--minimum"
             add_minimum_override!(options, args.shift)
+          when "--minimum-changed"
+            add_minimum_changed_override!(options, args.shift)
           when "--focus"
             options[:focus] = args.shift
             raise ArgumentError, "--focus requires PATH or PATH:LINE" if options[:focus].nil? || options[:focus].start_with?("-")
@@ -256,7 +418,7 @@ module Branchproof
       path.to_s.empty? ? path.to_s : relative_path(path, root)
     end
 
-    def parse(argv)
+    def parse(argv, doctor: false)
       return nil if argv.empty? || argv.first != "analyze"
 
       args = argv.drop(1)
@@ -267,7 +429,7 @@ module Branchproof
                   runner_args: runner_args, project: nil, missing_only: false, view: :decisions,
                   reachability: true, project_mode: "auto", framework: "auto", explicit_tests: false,
                   explicit_project: false, explicit_framework: false, explicit_sources: false,
-                  config_path: nil, config_disabled: false, minimum_overrides: {} }
+                  config_path: nil, config_disabled: false, minimum_overrides: {}, minimum_changed_overrides: {} }
       until args.empty?
         token = args.shift
         case token
@@ -278,6 +440,13 @@ module Branchproof
           options[:missing_only] = true
         when "--minimum"
           add_minimum_override!(options, args.shift)
+        when "--minimum-changed"
+          add_minimum_changed_override!(options, args.shift)
+        when "--changed-since"
+          ref = args.shift
+          raise ArgumentError, "--changed-since requires a non-option REF" if ref.to_s.empty? || ref.start_with?("-")
+
+          options[:changed_since] = ref
         when "--focus"
           options[:focus] = args.shift
           raise ArgumentError, "--focus requires PATH or PATH:LINE" if options[:focus].nil? || options[:focus].start_with?("-")
@@ -293,7 +462,7 @@ module Branchproof
           options[:level] = level
         when "--format"
           format = args.shift.to_s
-          raise ArgumentError, "format must be terminal or json" unless %w[terminal json].include?(format)
+          raise ArgumentError, "format must be terminal, json, or github" unless %w[terminal json github].include?(format)
 
           options[:format] = format.to_sym
         when "--output"
@@ -355,10 +524,16 @@ module Branchproof
         end
         options[:exclude] = Array(configuration[:exclude]).dup
         options[:minimum] = configuration.fetch(:minimum, {}).dup.merge(options[:minimum_overrides])
+        options[:minimum_changed] = configuration.fetch(:minimum_changed, {}).dup.merge(options[:minimum_changed_overrides])
       else
         options[:exclude] = []
         options[:minimum] = options[:minimum_overrides].dup
+        options[:minimum_changed] = options[:minimum_changed_overrides].dup
+      end
+      if !doctor && !options[:minimum_changed].empty? && !options[:changed_since]
+        raise ArgumentError, "--minimum-changed requires --changed-since REF"
       end
+
       options[:project] = Project.new(root: root, mode: options[:project_mode], framework: options[:framework]).to_h
       validate_view!(options)
       validate_selection!(options)
@@ -393,6 +568,20 @@ module Branchproof
       raise ArgumentError, "minimum threshold must be a finite number from 0 to 100"
     end
 
+    def add_minimum_changed_override!(options, argument)
+      match = argument.to_s.match(/\A([a-z_]+)=([0-9]+(?:\.[0-9]+)?)\z/)
+      raise ArgumentError, "minimum-changed must be CRITERION=THRESHOLD" unless match
+
+      criterion = match[1]
+      threshold = match[2].include?(".") ? Float(match[2]) : Integer(match[2], 10)
+      normalized = CoveragePolicy.normalize(criterion => threshold)
+      criterion = normalized.keys.first
+      options[:minimum_changed_overrides] ||= {}
+      raise ArgumentError, "duplicate coverage criterion: #{criterion}" if options[:minimum_changed_overrides].key?(criterion)
+
+      options[:minimum_changed_overrides][criterion] = normalized.fetch(criterion)
+    end
+
     def validate_selection!(options)
       return unless options[:focus] || options[:top]
       raise ArgumentError, "focus and top filters are terminal-only" if options[:format] == :json
@@ -401,6 +590,12 @@ module Branchproof
     end
 
     def build_inventory(options)
+      root = options[:project][:root]
+      selected = select_source_files(options)
+      Source.new(root: root, limits: options[:limits]).inventory(paths: selected)
+    end
+
+    def select_source_files(options)
       root = options[:project][:root]
       test_paths = options[:tests].filter_map do |path|
         File.realpath(path)
@@ -426,7 +621,7 @@ module Branchproof
       end
       options[:excluded_files] = excluded
       options[:selected_source_files] = selected
-      Source.new(root: root, limits: options[:limits]).inventory(paths: selected)
+      selected
     end
 
     def empty_evidence(inventory, options)
@@ -500,6 +695,28 @@ module Branchproof
       File.unlink(temporary) if created && temporary && File.file?(temporary)
     end
 
+    # GitHub Actions reads Markdown appended to this file into the job summary.
+    def write_step_summary(report, options)
+      path = @env["GITHUB_STEP_SUMMARY"].to_s
+      return unless options[:format] == :github && !path.empty?
+
+      File.open(path, "a") { |file| file.write(report.step_summary) }
+    rescue SystemCallError, IOError => e
+      @stderr.write("branchproof: could not write GITHUB_STEP_SUMMARY: #{e.message}\n")
+    end
+
+    # Annotation paths must be relative to the repository (GITHUB_WORKSPACE),
+    # but report paths are relative to the project root (the current directory).
+    def github_path_prefix
+      workspace = @env["GITHUB_WORKSPACE"].to_s
+      return nil if workspace.empty?
+
+      relative = Pathname.new(File.realpath(Dir.pwd)).relative_path_from(Pathname.new(File.realpath(workspace))).to_s
+      relative == "." || relative.start_with?("..") ? nil : relative
+    rescue SystemCallError, ArgumentError
+      nil
+    end
+
     def run_worker?(options)
       !options[:tests].empty? || options[:project][:framework].to_s == "rspec"
     end
@@ -515,7 +732,11 @@ module Branchproof
 
     def report_string(report, format)
       buffer = StringIO.new
-      report.write(io: buffer, format: format)
+      if format == :github
+        report.write(io: buffer, format: format, path_prefix: github_path_prefix)
+      else
+        report.write(io: buffer, format: format)
+      end
       buffer.string
     end