branchproof 0.2.0 → 0.4.0

data/doc/README.md

@@ -6,8 +6,8 @@ modifier, and ordinary ternary (`?:`) decisions, records observed vectors,
 and reports independence evidence, missing counterpart constraints, and
 smaller supporting test sets.
 
-The gem is named `branchproof`; its command and compatibility namespace are
-`mcdc` and `MCDC`.
+The gem and primary command are named `branchproof`. The `mcdc` command and
+`MCDC` namespace remain compatibility aliases with the same behavior.
 
 ## Installation
 
@@ -30,12 +30,12 @@ instead of being counted as coverage.
 
 ## Analyze a test run
 
-Run `mcdc analyze` with the source files or globs to inspect, followed by
+Run `branchproof analyze` with the source files or globs to inspect, followed by
 options. A second `--` separates Branchproof options from arguments passed to
 Minitest unchanged:
 
 ```sh
-mcdc analyze 'lib/**/*.rb' --test 'test/**/*_test.rb' \
+branchproof analyze 'lib/**/*.rb' --test 'test/**/*_test.rb' \
   --level 3 \
   --format terminal \
   --output tmp/branchproof.txt \
@@ -47,14 +47,14 @@ For a plain Ruby application, select the project policy explicitly when
 running from the application root:
 
 ```sh
-bundle exec mcdc analyze 'lib/**/*.rb' --project ruby --test 'test/**/*_test.rb'
+bundle exec branchproof analyze 'lib/**/*.rb' --project ruby --test 'test/**/*_test.rb'
 ```
 
 For a Rails application, run the same command from the application root so
 the application's bundle and Rails version remain in effect:
 
 ```sh
-bundle exec mcdc analyze 'app/**/*.rb' --project rails --test 'test/**/*_test.rb'
+bundle exec branchproof analyze 'app/**/*.rb' --project rails --test 'test/**/*_test.rb'
 ```
 
 For a project rooted at the current directory, `--project auto` is the
@@ -97,7 +97,7 @@ For example, running the contents of the small `decision.rb` /
 with the terminal format produces a summary like this:
 
 ```text
-Branchproof 0.2.0
+Branchproof 0.4.0
 Tests: PASSED (3 tests, 0 failed, 0 skipped)
 MC/DC: 100.0% (2/2 conditions proven)
 Analysis: COMPLETE
@@ -126,6 +126,53 @@ Additional tests outside this MC/DC evidence set may improve coverage.
 The test execution still runs once for the selected level. Use `--format
 json` when a consumer needs the complete identifiers and versioned schema.
 
+### Find missing cases
+
+Use `--missing-only` to focus the terminal report on conditions that still
+lack independence evidence:
+
+```sh
+bundle exec branchproof analyze 'lib/**/*.rb' --missing-only
+```
+
+This keeps the overall summary and diagnostics, hides proven conditions and
+supporting-set lists, and shows missing scenarios using the source expressions.
+It works with levels 2 and 3 (the default). JSON remains the complete report;
+`--missing-only` cannot be combined with `--format json` or `--level 1`.
+
+For example, given this decision:
+
+```ruby
+content && Instruction.installed?(content)
+```
+
+Observing `[TT]` and `[F-]` proves the effect of `content`, but does not prove
+the effect of `Instruction.installed?(content)`. The missing case is `[TF]`:
+`content` must be truthy and `Instruction.installed?(content)` must be falsey,
+making the decision false. The missing condition is presented as:
+
+```text
+  Condition 1: Instruction.installed?(content)
+    NOT_PROVEN — missing observation
+      Need an observation where:
+        content is truthy
+        Instruction.installed?(content) is falsey
+        Expected decision: false [TF]
+```
+
+An existing file without the instruction block
+may produce this case; the test must reach the reported line. The report
+describes required truth values, not application inputs or guaranteed
+reachable paths. In Ruby, only `false` and `nil` are falsey; an empty string
+is truthy.
+
+`NOT_PROVEN` means analysis ran but did not find the required pair of
+observations. `NOT CALCULATED` means analysis was not available or was not
+requested; check the test status and diagnostics before adding tests.
+`Analysis: COMPLETE` means the analysis finished, not that every condition
+was proven. Missing conditions may require new tests or changes to existing
+test inputs; they do not by themselves prove a bug in the application.
+
 The levels select how much of the one-run result is displayed:
 
 * Level 1 reports observed vectors grouped by their raw decision outcomes.
@@ -138,6 +185,95 @@ test suite. A failed, unsupported, or incomplete run is reported with its
 status and diagnostics and cannot become a successful coverage result by
 changing the display level.
 
+### Focused condition and test views
+
+Use `--view conditions` to group the report by condition. Each condition shows
+its expression, decision, and project-relative source location with the
+condition's own 1-based start line. The view separates tests that evaluated
+the condition true or false from tests where it was short-circuited. Level 3
+also shows the canonical witness observations selected by the analyzer and
+their owning tests.
+
+```sh
+bundle exec branchproof analyze 'lib/**/*.rb' --view conditions
+bundle exec branchproof analyze 'lib/**/*.rb' --view conditions --missing-only
+```
+
+Use `--view tests` to group the same evidence by test. Rows include each
+exercised condition, its relative source location, observed values, and the
+recorded `setup`, `body`, or `teardown` phases. Tests with no completed
+condition observation remain visible, as do unattributed and unexecuted
+conditions. A test that evaluates both Boolean values is evidence of execution;
+it is a proof contributor only when the analyzer's independent witness pair
+uses its observations.
+
+`--view` changes terminal grouping and does not change instrumentation or test
+execution. JSON output always contains the complete evidence document, so an
+explicit view cannot be combined with `--format json`. The `mcdc` executable
+accepts the same arguments for existing scripts.
+
+### Saved reports and offline comparison
+
+Reports are saved only when requested. Create a local artifact directory and
+write a complete JSON baseline with the existing atomic `--output` option:
+
+```sh
+mkdir -p .branchproof
+bundle exec branchproof analyze 'lib/**/*.rb' --format json \
+  --output .branchproof/baseline.json
+bundle exec branchproof report .branchproof/baseline.json --view conditions
+bundle exec branchproof report .branchproof/baseline.json --view tests
+```
+
+The output's parent directory must already exist. Replacing a baseline is an
+explicit `analyze --format json --output` operation; keep CI snapshots as
+artifacts when you need to retain multiple runs.
+
+The `report` command reads the saved document without loading the application
+or running tests. It uses locations and metadata captured in the report, so
+rendering remains useful after the original checkout has moved or been
+removed. Level 1 reports observations; levels 2 and 3 require corresponding
+analysis in the saved report. The repository ignores `.branchproof/`; choose a
+different path and CI artifact policy when a project needs to retain reports.
+Saved JSON includes existing raw metadata such as test names and expressions;
+relative terminal labels do not mean every legacy JSON field is sanitized.
+
+To compare two explicitly saved runs:
+
+```sh
+bundle exec branchproof analyze 'lib/**/*.rb' --format json \
+  --output .branchproof/current.json
+bundle exec branchproof compare .branchproof/baseline.json \
+  .branchproof/current.json
+bundle exec branchproof compare .branchproof/baseline.json \
+  .branchproof/current.json --fail-on-regression
+```
+
+Comparison matches exact condition identities from unchanged source files.
+Changed source files, changed selection or runtime context, incomplete runs,
+and legacy reports missing comparison metadata are reported as partial or
+incomplete context rather than guessed regressions. The output distinguishes
+gained proof, lost proof, changed sources, newly selected files, and files no
+longer present in a report. Previous witness values and owner names are shown
+for lost proof; an absent owner is described as `not observed in current run`,
+not as a deleted test. A different test population under unchanged discovery
+patterns is valid comparison context, and seed differences are disclosed.
+
+`compare` exits 0 for a complete comparison, including one with coverage
+changes; `--fail-on-regression` exits 1 when a complete comparable run loses
+proof. Invalid input or an incomplete comparison exits 2, which takes
+precedence. Reports are explicit snapshots: comparison never creates history,
+promotes a baseline, or overwrites either input.
+
+MC/DC has two related questions. Evaluation asks whether a condition was
+observed with a value, including short-circuiting. Independent proof asks
+whether the analyzer found a pair of observations where that condition changes
+the decision outcome under the masking criterion. Other conditions may be
+short-circuited or masked rather than fixed to the same observed values. For example,
+`left && right` observed as `[TT]` and `[F-]` evaluates `right` once and
+short-circuits it once, but does not prove `right`; `[TF]` is also required.
+The condition and test views preserve that distinction.
+
 ### Supported conditional forms
 
 Ordinary Ruby ternaries use the same predicate instrumentation and `&&`/`||`
@@ -183,7 +319,7 @@ Everything after the argument separator is passed as individual arguments to
 the serial Minitest runner. This is useful for seeds and name filters:
 
 ```sh
-mcdc analyze 'lib/**/*.rb' --level 1 -- --seed 9001 -n /checkout/
+branchproof analyze 'lib/**/*.rb' --level 1 -- --seed 9001 -n /checkout/
 ```
 
 The 0.2 release supports serial Minitest execution in plain Ruby projects and

data/exe/branchproof

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "branchproof"
+exit Branchproof::CLI.new(stdout: $stdout, stderr: $stderr).call(ARGV)

data/lib/branchproof/analyzer.rb

@@ -181,7 +181,7 @@ module Branchproof
       end
 
       effective_mask(vector, id(decision, :id), decision[:tree])
-      vector
+      decision_source.nil? ? vector : vector.merge(source_id: decision_source)
     rescue ArgumentError
       @analysis_invalid = true
       add_diagnostic("invalid_vector", "error", id(vector, :id))

data/lib/branchproof/cli.rb

@@ -10,6 +10,7 @@ require "rbconfig"
 require "stringio"
 require "fileutils"
 require "securerandom"
+require "time"
 
 module Branchproof
   # Coordinates source inventory, isolated test execution, and report output.
@@ -20,8 +21,12 @@ module Branchproof
     end
 
     def call(argv)
+      argv = Array(argv)
+      return help if [["--help"], ["help"], ["analyze", "--help"]].include?(argv)
+      return offline(argv) if %w[report compare].include?(argv.first)
+
       options = parse(Array(argv))
-      return usage_error("analyze is the only supported command") unless options
+      return usage_error("expected analyze, report, or compare; use branchproof --help") unless options
 
       inventory = build_inventory(options)
       evidence = empty_evidence(inventory, options)
@@ -69,17 +74,145 @@ module Branchproof
       minima = options[:level] == 1 ? [] : Array(value(baseline, :minima))
       report = Report.new(inventory: inventory, evidence: value(baseline, :evidence) || evidence.snapshot,
                           analysis: analysis, minima: minima, baseline: baseline, diagnostics: diagnostics,
-                          level: options[:level])
+                          level: options[:level], missing_only: options[:missing_only], view: options[:view],
+                          run_metadata: run_metadata(options, baseline))
       output_report(report, options)
       report.exit_code
     rescue ArgumentError => e
       usage_error(e.message)
     rescue JSON::ParserError => e
       usage_error("invalid JSON limits: #{e.message}")
+    rescue SystemCallError, IOError => e
+      usage_error("report IO failed: #{e.message}")
     end
 
     private
 
+    def help
+      @stdout.write(<<~HELP)
+        Usage:
+          branchproof analyze [SOURCE_GLOB ...] [--test TEST_GLOB] [--project auto|ruby|rails]
+            [--view decisions|conditions|tests] [--level 1|2|3] [--missing-only]
+            [--format terminal|json] [--output PATH] [--limits PATH] [-- RUNNER_ARGS]
+          branchproof report SNAPSHOT [--view decisions|conditions|tests] [--level 1|2|3]
+            [--missing-only] [--format terminal|json] [--output PATH]
+          branchproof compare BEFORE AFTER [--format terminal|json] [--output PATH] [--fail-on-regression]
+        mcdc accepts the same commands as a compatibility alias.
+        JSON always contains full evidence; --view requires terminal output.
+      HELP
+      0
+    end
+
+    def parse_view(view)
+      raise ArgumentError, "view must be decisions, conditions, or tests" unless %w[decisions conditions tests].include?(view)
+
+      view.to_sym
+    end
+
+    def validate_view!(options)
+      return unless options[:explicit_view] && options[:format] == :json
+
+      raise ArgumentError, "--view requires terminal format; JSON contains full evidence"
+    end
+
+    def offline(argv)
+      command = argv.first
+      return help if argv.drop(1) == ["--help"]
+
+      options, paths = parse_offline(command, argv.drop(1))
+      reject_input_output_collision!(paths, options[:output]) if options[:output]
+      documents = paths.map { |path| SavedReport.read(path) }
+      if command == "compare"
+        report = ComparisonReport.new(document: Comparison.new(before: documents[0], after: documents[1]).call)
+        output_report(report, options)
+        report.exit_code(fail_on_regression: options[:fail_on_regression])
+      else
+        document = documents.first
+        options[:level] ||= document["analysis"] ? 3 : 1
+        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"
+        end
+
+        report = Report.from_document(document: document, level: options[:level], view: options[:view],
+                                      missing_only: options[:missing_only])
+        output_report(report, options)
+        report.exit_code
+      end
+    end
+
+    def parse_offline(command, args)
+      options = { format: :terminal, view: :decisions, missing_only: false }
+      paths = []
+      until args.empty?
+        token = args.shift
+        case token
+        when "--format"
+          format = args.shift
+          raise ArgumentError, "format must be terminal or json" unless %w[terminal json].include?(format)
+
+          options[:format] = format.to_sym
+        when "--output"
+          options[:output] = args.shift
+          raise ArgumentError, "--output requires a path" if options[:output].to_s.empty?
+        when "--fail-on-regression"
+          raise ArgumentError, "--fail-on-regression requires compare" unless command == "compare"
+
+          options[:fail_on_regression] = true
+        when "--view", "--level", "--missing-only"
+          raise ArgumentError, "#{token} requires report" unless command == "report"
+
+          case token
+          when "--view"
+            options[:view] = parse_view(args.shift)
+            options[:explicit_view] = true
+          when "--level"
+            options[:level] = Integer(args.shift.to_s, 10)
+            raise ArgumentError, "level must be 1, 2, or 3" unless (1..3).cover?(options[:level])
+          else options[:missing_only] = true
+          end
+        else
+          raise ArgumentError, "unknown option: #{token}" if token.start_with?("-")
+
+          paths << token
+        end
+      end
+      expected = command == "compare" ? 2 : 1
+      raise ArgumentError, "#{command} requires #{expected} saved report #{expected == 1 ? "path" : "paths"}" unless paths.length == expected
+
+      validate_view!(options)
+      [options, paths]
+    end
+
+    def reject_input_output_collision!(paths, output)
+      collision = paths.any? do |input|
+        File.expand_path(input) == File.expand_path(output) ||
+          (File.exist?(input) && File.exist?(output) && File.identical?(input, output))
+      end
+      raise ArgumentError, "output must not overwrite an input report" if collision
+    end
+
+    def run_metadata(options, baseline)
+      root = options[:project][:root]
+      locations = Array(value(baseline, :tests)).to_h do |test|
+        source = value(test, :source) || {}
+        [value(test, :id), { relative_path: relative_path(value(source, :path), root), line: value(source, :line) }]
+      end
+      { captured_at: Time.now.utc.iso8601, requested_level: options[:level], project_kind: options[:project][:kind],
+        project_root: root, source_patterns: options[:source_patterns].map { |path| relative_path(path, root) },
+        test_patterns: options[:test_patterns].map { |path| relative_path(path, root) },
+        test_files: options[:tests].map { |path| relative_path(path, root) }, runner_args: options[:runner_args],
+        seed: value(baseline, :seed), limits: options[:limits], test_locations: locations }
+    end
+
+    def relative_path(path, root)
+      return nil if path.to_s.empty?
+
+      Pathname.new(File.expand_path(path, root)).relative_path_from(Pathname.new(root)).to_s
+    end
+
     def parse(argv)
       return nil if argv.empty? || argv.first != "analyze"
 
@@ -88,10 +221,15 @@ module Branchproof
       runner_args = delimiter ? args[(delimiter + 1)..] : []
       args = args[0...delimiter] if delimiter
       options = { level: 3, format: :terminal, output: nil, tests: [], source_paths: [], limits: Limits.default,
-                  runner_args: runner_args, project: nil }
+                  runner_args: runner_args, project: nil, missing_only: false, view: :decisions }
       until args.empty?
         token = args.shift
         case token
+        when "--view"
+          options[:view] = parse_view(args.shift)
+          options[:explicit_view] = true
+        when "--missing-only"
+          options[:missing_only] = true
         when "--level"
           level = Integer(args.shift.to_s, 10)
           raise ArgumentError, "level must be 1, 2, or 3" unless (1..3).cover?(level)
@@ -126,9 +264,16 @@ module Branchproof
           options[:source_paths] << token
         end
       end
+      validate_view!(options)
+      if options[:missing_only] && (options[:format] != :terminal || options[:level] == 1)
+        raise ArgumentError, "--missing-only requires terminal format and level 2 or 3"
+      end
+
       options[:project] ||= Project.new(root: Dir.pwd, mode: "auto").to_h
       options[:source_paths] = default_sources if options[:source_paths].empty?
       options[:tests] = default_tests if options[:tests].empty?
+      options[:source_patterns] = options[:source_paths].dup
+      options[:test_patterns] = argv.include?("--test") ? options[:tests].dup : %w[test/**/*_test.rb test/**/test_*.rb]
       options[:tests] = expand_paths(options[:tests], root: options[:project][:root])
       options
     end
@@ -193,13 +338,19 @@ module Branchproof
     end
 
     def output_report(report, options)
+      created = false
       if options[:output]
-        temporary = "#{options[:output]}.tmp-#{Process.pid}"
-        File.binwrite(temporary, report_string(report, options[:format]))
+        temporary = "#{options[:output]}.tmp-#{SecureRandom.hex(12)}"
+        File.open(temporary, "wx") do |file|
+          created = true
+          file.write(report_string(report, options[:format]))
+        end
         File.rename(temporary, options[:output])
       else
         @stdout.write(report_string(report, options[:format]))
       end
+    ensure
+      File.unlink(temporary) if created && temporary && File.file?(temporary)
     end
 
     def report_string(report, format)
@@ -209,7 +360,7 @@ module Branchproof
     end
 
     def usage_error(message)
-      @stderr.write("mcdc: #{message}\n")
+      @stderr.write("branchproof: #{message}\n")
       2
     end
 
@@ -239,7 +390,7 @@ module Branchproof
     def value(hash, key)
       return nil unless hash.respond_to?(:key?)
 
-      hash[key] || hash[key.to_s]
+      hash.key?(key) ? hash[key] : hash[key.to_s]
     end
 
     def normalize(value)