rail_verdict 1.0.0

data/lib/rail_verdict/cli.rb

@@ -0,0 +1,471 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+
+module RailVerdict
+  class CLI
+    EXIT_OK = 0
+    EXIT_POLICY_FAIL = 1
+    EXIT_NO_GATE = 2
+    EXIT_INTERRUPTED = 130
+
+    FORMATS = %w[console json sarif].freeze
+    DEFAULT_CONFIG_PATH = ".railverdict.yml"
+
+    USAGE = <<~USAGE
+      Usage: railverdict <command> [options]
+
+      Commands:
+        init             Write the default .railverdict.yml configuration
+        doctor           Report configuration and analyzer observations
+        check            Run verification and print the gate result
+        baseline create  Deferred boundary; Phase 3 owns baseline writes
+        findings         Print normalized findings from the evidence run
+        explain          Explain a finding with optional AI
+        investigate      Investigate top findings with optional AI
+        repair           Build a deterministic repair packet for a finding
+        mcp              MCP adapter (serve)
+
+      Global options:
+        --help           Show this usage
+        --version        Show the railverdict version
+    USAGE
+
+    def initialize(stdout: $stdout, stderr: $stderr, working_directory: Dir.pwd)
+      @stdout = stdout
+      @stderr = stderr
+      @working_directory = working_directory
+    end
+
+    def run(argv)
+      command = argv.first
+      case command
+      when nil, "-h", "--help", "help"
+        @stdout.puts USAGE
+        EXIT_OK
+      when "--version", "-V"
+        @stdout.puts "railverdict #{RailVerdict::VERSION}"
+        EXIT_OK
+      when "init"
+        command_init(argv.drop(1))
+      when "doctor"
+        command_doctor(argv.drop(1))
+      when "check"
+        command_check(argv.drop(1))
+      when "baseline"
+        command_baseline(argv.drop(1))
+      when "findings"
+        command_findings(argv.drop(1))
+      when "explain"
+        command_explain(argv.drop(1))
+      when "investigate"
+        command_investigate(argv.drop(1))
+      when "repair"
+        command_repair(argv.drop(1))
+      when "mcp"
+        command_mcp(argv.drop(1))
+      else
+        @stderr.puts "railverdict: unknown command: #{command}"
+        @stderr.puts USAGE
+        EXIT_NO_GATE
+      end
+    rescue RailVerdict::UsageError => error
+      @stderr.puts "railverdict: #{error.message}"
+      @stderr.puts USAGE
+      EXIT_NO_GATE
+    end
+
+    private
+
+    def command_init(argv)
+      options = { config: DEFAULT_CONFIG_PATH, force: false }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict init [--config PATH] [--force]"
+        opts.on("--config PATH", String) { |value| options[:config] = value }
+        opts.on("--force") { options[:force] = true }
+      end
+      parse!(parser, argv)
+      exit_code, message = Init.write(
+        root: @working_directory,
+        config_path: options[:config],
+        force: options[:force]
+      )
+      if exit_code.zero?
+        @stdout.puts message
+      else
+        @stderr.puts "railverdict init: #{message}"
+      end
+      exit_code
+    end
+
+    def command_doctor(argv)
+      options = { config: DEFAULT_CONFIG_PATH, format: "console" }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict doctor [--config PATH] [--format console|json]"
+        opts.on("--config PATH", String) { |value| options[:config] = value }
+        opts.on("--format FORMAT", String) { |value| options[:format] = value }
+      end
+      parse!(parser, argv)
+      validate_format!(options[:format])
+      outcome = Doctor.execute(
+        repository_root: @working_directory,
+        config_path: options[:config]
+      )
+      if options[:format] == "json"
+        @stdout.write(JSON.generate(outcome.report))
+        @stdout.write("\n")
+      else
+        @stdout.write(render_doctor_console(outcome.report))
+      end
+      outcome.exit_code
+    end
+
+    def command_check(argv)
+      options = { config: DEFAULT_CONFIG_PATH, format: "console", changed: false, base: nil, baseline: nil, waiver: nil }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict check [--config PATH] [--format console|json|sarif] [--changed] [--base REV] [--baseline PATH] [--waiver PATH]"
+        opts.on("--config PATH", String) { |value| options[:config] = value }
+        opts.on("--format FORMAT", String) { |value| options[:format] = value }
+        opts.on("--changed") { options[:changed] = true }
+        opts.on("--base REV", String) { |value| options[:base] = value }
+        opts.on("--baseline PATH", String) { |value| options[:baseline] = value }
+        opts.on("--waiver PATH", String) { |value| options[:waiver] = value }
+      end
+      parse!(parser, argv)
+      validate_format!(options[:format])
+      if options[:base] && !options[:changed]
+        raise RailVerdict::UsageError, "--base requires --changed"
+      end
+
+      outcome, interrupted = execute_check(options)
+      return EXIT_NO_GATE unless render_result(outcome.result, options[:format])
+
+      exit_code_for(outcome.result, interrupted: interrupted)
+    end
+
+    def command_baseline(argv)
+      subcommand = argv.first
+      raise RailVerdict::UsageError, "unknown baseline subcommand: #{subcommand.inspect}; only `baseline create` exists" unless subcommand == "create"
+
+      options = { config: DEFAULT_CONFIG_PATH, output: nil, format: "console", force: false }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict baseline create [--config PATH] [--output PATH] [--format console|json] [--force]"
+        opts.on("--config PATH", String) { |value| options[:config] = value }
+        opts.on("--output PATH", String) { |value| options[:output] = value }
+        opts.on("--format FORMAT", String) { |value| options[:format] = value }
+        opts.on("--force") { options[:force] = true }
+      end
+      parse!(parser, argv.drop(1))
+      validate_format!(options[:format])
+
+      outcome, interrupted = execute_check({ config: options[:config], format: options[:format] })
+      return EXIT_INTERRUPTED if interrupted || outcome.result.completion_status == "interrupted"
+      baseline_required_only = outcome.result.completion_status == "incomplete" &&
+        outcome.result.decision_reasons.any? { |r| r["code"] == "baseline_required" } &&
+        outcome.result.operational_failures.all? { |f| f["message"]&.include?("baseline required") }
+      unless outcome.result.completion_status == "complete" || baseline_required_only
+        @stderr.puts "railverdict baseline create: refusing to create baseline from incomplete run (#{outcome.result.operational_failures.map { |failure| failure.fetch('code') }.join(', ')})"
+        return EXIT_NO_GATE
+      end
+      if outcome.context.nil? || outcome.configuration.nil?
+        @stderr.puts "railverdict baseline create: refusing to create baseline without a complete context"
+        return EXIT_NO_GATE
+      end
+
+      path = Baseline.resolve_path(repository_root: @working_directory, configuration: outcome.configuration, output_override: options[:output])
+      baseline = Baseline.create(
+        findings: outcome.findings,
+        configuration: outcome.configuration,
+        analyzer_versions: outcome.context.analyzer_versions,
+        clock: Time.now.utc
+      )
+      Baseline.write(path: path, baseline: baseline, force: options[:force])
+
+      if options[:format] == "json"
+        @stdout.write(JSON.generate({ "baseline" => baseline.to_h }) + "\n")
+      else
+        @stdout.puts "Baseline created at #{path} (#{baseline.entries.length} entries)"
+      end
+      EXIT_OK
+    rescue RailVerdict::UsageError => error
+      @stderr.puts "railverdict baseline create: #{error.message}"
+      EXIT_NO_GATE
+    rescue RailVerdict::Baseline::IncompatibleError, RailVerdict::Error => error
+      @stderr.puts "railverdict baseline create: #{error.message}"
+      EXIT_NO_GATE
+    end
+
+    def command_findings(argv)
+      options = { config: DEFAULT_CONFIG_PATH, format: "console" }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict findings [--config PATH] [--format console|json]"
+        opts.on("--config PATH", String) { |value| options[:config] = value }
+        opts.on("--format FORMAT", String) { |value| options[:format] = value }
+      end
+      parse!(parser, argv)
+      validate_format!(options[:format])
+      outcome, interrupted = execute_check(options)
+      if options[:format] == "json"
+        @stdout.write(JSON.generate(FindingsCommand.document(outcome)))
+        @stdout.write("\n")
+      else
+        @stdout.write(FindingsCommand.console(outcome))
+      end
+      @stderr.puts "railverdict findings: required evidence is incomplete" if outcome.result.incomplete?
+      return EXIT_INTERRUPTED if interrupted || outcome.result.completion_status == "interrupted"
+      return EXIT_NO_GATE if outcome.result.incomplete?
+
+      EXIT_OK
+    end
+
+    def parse!(parser, argv)
+      rest = parser.parse(argv.dup)
+      return if rest.empty?
+
+      raise RailVerdict::UsageError, "unexpected arguments: #{rest.join(' ')}"
+    rescue OptionParser::ParseError => error
+      raise RailVerdict::UsageError, error.message
+    end
+
+    def validate_format!(format)
+      return if FORMATS.include?(format)
+
+      raise RailVerdict::UsageError, "invalid --format #{format.inspect}; expected console, json or sarif"
+    end
+
+    def execute_check(options)
+      interrupted = false
+      previous = Signal.trap("INT") do
+        interrupted = true
+        RailVerdict::ProcessRunner.registry.terminate_all
+      end
+      execute_options = {
+        repository_root: @working_directory,
+        config_path: options[:config],
+        interrupted: -> { interrupted }
+      }
+      execute_options[:baseline_path_override] = options[:baseline] if options.key?(:baseline) && options[:baseline]
+      execute_options[:waiver_path_override] = options[:waiver] if options.key?(:waiver) && options[:waiver]
+      execute_options[:baseline_path_override] = options[:output] if options.key?(:output) && options[:output]
+      execute_options[:changed] = options[:changed] if options.key?(:changed)
+      execute_options[:base] = options[:base] if options.key?(:base)
+      outcome = Check.execute(**execute_options)
+      [outcome, interrupted]
+    ensure
+      Signal.trap("INT", previous) if previous
+    end
+
+    def render_result(result, format)
+      rendered = if format == "json"
+        Reporters::JsonReporter.render(result)
+      elsif format == "sarif"
+        Reporters::Sarif.render_json(result)
+      else
+        Reporters::Console.render(result)
+      end
+      @stdout.write(rendered)
+      true
+    rescue RailVerdict::Error => error
+      @stderr.puts "railverdict: #{error.message}"
+      false
+    end
+
+    def exit_code_for(result, interrupted: false)
+      return EXIT_INTERRUPTED if interrupted || result.completion_status == "interrupted"
+      return EXIT_NO_GATE if result.completion_status != "complete"
+      return EXIT_POLICY_FAIL if result.gate == "FAIL"
+
+      EXIT_OK
+    end
+
+    def render_doctor_console(report)
+      lines = ["RailVerdict doctor", "", "Ruby: #{report['ruby_version'] || 'unknown'}"]
+      lines << "Target Ruby: #{report['target_ruby_version']}" if report.key?("target_ruby_version")
+      lines << "Rails: #{report['rails_version']}" if report.key?("rails_version")
+      configuration = report.fetch("configuration")
+      lines << "Configuration: #{configuration['valid'] ? 'valid' : 'invalid'}"
+      report.fetch("analyzers", {}).each do |name, details|
+        lines << "#{name}: #{details['status']}#{details['version'] ? " (#{details['version']})" : ''}"
+      end
+      lines.join("\n") + "\n"
+    end
+
+    def command_explain(argv)
+      finding_ref = argv.first
+      raise RailVerdict::UsageError, "explain requires a finding id or fingerprint" unless finding_ref && !finding_ref.start_with?("-")
+
+      options = { config: DEFAULT_CONFIG_PATH, format: "console", preview: false }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict explain <finding-id|fingerprint> [--config PATH] [--format console|json] [--preview-context]"
+        opts.on("--config PATH", String) { |v| options[:config] = v }
+        opts.on("--format FORMAT", String) { |v| options[:format] = v }
+        opts.on("--preview-context") { options[:preview] = true }
+      end
+      parse!(parser, argv.drop(1))
+      validate_format!(options[:format])
+
+      outcome, interrupted = execute_check({ config: options[:config], format: options[:format] })
+      return EXIT_INTERRUPTED if interrupted
+
+      if options[:preview]
+        return explain_preview(outcome, finding_ref, options[:format])
+      end
+
+      result = Intelligence::Orchestrator.explain(
+        outcome: outcome,
+        finding_ref: finding_ref,
+        configuration: outcome.configuration
+      )
+      render_intelligence(result, options[:format])
+      EXIT_OK
+    rescue RailVerdict::UsageError => e
+      @stderr.puts "railverdict explain: #{e.message}"
+      EXIT_NO_GATE
+    rescue StandardError => e
+      @stderr.puts "railverdict explain: #{e.message}"
+      EXIT_NO_GATE
+    end
+
+    def command_investigate(argv)
+      options = { config: DEFAULT_CONFIG_PATH, format: "console", preview: false, limit: 3 }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict investigate [--config PATH] [--format console|json] [--preview-context] [--limit N]"
+        opts.on("--config PATH", String) { |v| options[:config] = v }
+        opts.on("--format FORMAT", String) { |v| options[:format] = v }
+        opts.on("--preview-context") { options[:preview] = true }
+        opts.on("--limit N", Integer) { |v| options[:limit] = v }
+      end
+      parse!(parser, argv)
+      validate_format!(options[:format])
+
+      outcome, interrupted = execute_check({ config: options[:config], format: options[:format] })
+      return EXIT_INTERRUPTED if interrupted
+
+      if options[:preview]
+        findings = Intelligence::Budget.select_findings(outcome.findings || [], limit: [options[:limit], 3].min)
+        manifests = findings.map do |f|
+          Intelligence::ContextBuilder.build(outcome: outcome, finding_ref: f.id).to_json_hash rescue {}
+        end
+        if options[:format] == "json"
+          @stdout.write(JSON.generate({ "manifests" => manifests }) + "\n")
+        else
+          @stdout.puts "Preview: #{manifests.length} findings selected"
+          manifests.each { |m| @stdout.puts "  #{m['finding_id']} #{m['fingerprint']}" }
+        end
+        return EXIT_OK
+      end
+
+      results = Intelligence::Orchestrator.investigate(
+        outcome: outcome,
+        configuration: outcome.configuration,
+        limit: options[:limit]
+      )
+      results.each { |r| render_intelligence(r, options[:format]) }
+      EXIT_OK
+    rescue RailVerdict::UsageError => e
+      @stderr.puts "railverdict investigate: #{e.message}"
+      EXIT_NO_GATE
+    rescue StandardError => e
+      @stderr.puts "railverdict investigate: #{e.message}"
+      EXIT_NO_GATE
+    end
+
+    def explain_preview(outcome, finding_ref, format)
+      manifest = Intelligence::ContextBuilder.build(outcome: outcome, finding_ref: finding_ref)
+      if format == "json"
+        @stdout.write(JSON.generate(manifest.to_json_hash) + "\n")
+      else
+        @stdout.puts "Finding: #{manifest.finding_id}"
+        @stdout.puts "Fingerprint: #{manifest.fingerprint}"
+        @stdout.puts "Snippets: #{manifest.snippets.length}"
+        manifest.snippets.each { |s| @stdout.puts "  #{s['path']}" }
+      end
+      EXIT_OK
+    rescue ArgumentError => e
+      @stderr.puts "railverdict explain: #{e.message}"
+      EXIT_NO_GATE
+    end
+
+    def render_intelligence(result, format)
+      if result[:failure]
+        if format == "json"
+          @stdout.write(JSON.generate({ "failure" => result[:failure].to_h }) + "\n")
+        else
+          @stdout.puts "Intelligence: #{result[:failure].code}: #{result[:failure].message}"
+        end
+      elsif result[:analysis]
+        if format == "json"
+          @stdout.write(JSON.generate(result[:analysis].to_h) + "\n")
+        else
+          @stdout.puts "Analysis: #{result[:analysis].summary} (confidence: #{result[:analysis].confidence})"
+        end
+      end
+    end
+
+    def command_repair(argv)
+      finding_ref = argv.first
+      raise RailVerdict::UsageError, "repair requires a finding id or fingerprint" unless finding_ref && !finding_ref.start_with?("-")
+
+      options = { config: DEFAULT_CONFIG_PATH, format: "console", output: nil, changed: false, base: nil, baseline: nil, waiver: nil }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict repair <finding-id|fingerprint> [--config PATH] [--format console|json] [--output PATH] [--changed] [--base REV] [--baseline PATH] [--waiver PATH]"
+        opts.on("--config PATH", String) { |v| options[:config] = v }
+        opts.on("--format FORMAT", String) { |v| options[:format] = v }
+        opts.on("--output PATH", String) { |v| options[:output] = v }
+        opts.on("--changed") { options[:changed] = true }
+        opts.on("--base REV", String) { |v| options[:base] = v }
+        opts.on("--baseline PATH", String) { |v| options[:baseline] = v }
+        opts.on("--waiver PATH", String) { |v| options[:waiver] = v }
+      end
+      parse!(parser, argv.drop(1))
+      validate_format!(options[:format])
+      raise RailVerdict::UsageError, "--base requires --changed" if options[:base] && !options[:changed]
+
+      code, _packet = RailVerdict::Repair::Command.execute(
+        repository_root: @working_directory,
+        config_path: options[:config],
+        finding_ref: finding_ref,
+        format: options[:format],
+        output_path: options[:output],
+        changed: options[:changed],
+        base: options[:base],
+        baseline_override: options[:baseline],
+        waiver_override: options[:waiver],
+        stdout: @stdout,
+        stderr: @stderr
+      )
+      code
+    rescue RailVerdict::UsageError => e
+      @stderr.puts "railverdict repair: #{e.message}"
+      EXIT_NO_GATE
+    end
+
+    def command_mcp(argv)
+      sub = argv.first
+      raise RailVerdict::UsageError, "mcp requires subcommand: serve" unless sub == "serve"
+
+      options = { repository_root: @working_directory }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict mcp serve [--repository-root PATH]"
+        opts.on("--repository-root PATH", String) { |v| options[:repository_root] = v }
+      end
+      parse!(parser, argv.drop(1))
+      require_relative "mcp"
+      server = RailVerdict::MCP::Server.new(repository_root: options[:repository_root])
+      server.serve
+      EXIT_OK
+    rescue RailVerdict::UsageError => e
+      @stderr.puts "railverdict mcp: #{e.message}"
+      EXIT_NO_GATE
+    rescue StandardError => e
+      @stderr.puts "railverdict mcp: #{e.message}"
+      EXIT_NO_GATE
+    end
+
+    def not_implemented(command)
+      @stderr.puts "railverdict #{command}: not yet implemented in this build step."
+      EXIT_NO_GATE
+    end
+  end
+end

data/lib/rail_verdict/comparison.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "set"
+
+module RailVerdict
+  class Comparison
+    Result = Struct.new(:existing, :introduced, :resolved, :changed, :moved, :counts, :classified_findings, :orphaned_waivers, keyword_init: true)
+
+    def self.classify(findings:, baseline:, waivers: [], clock: Time.now.utc, rename_map: nil)
+      findings = findings.sort_by(&:sort_key)
+      if baseline.nil?
+        introduced = findings.map { |finding| restate(finding, "introduced") }
+        resolved = []
+        existing = []
+        changed = []
+        moved = []
+        if waivers.any?
+          waived, orphaned = apply_waivers(nil, findings, baseline, waivers, clock)
+          if waived.any?
+            current_by_fp = findings.to_h { |finding| [finding.fingerprint, finding] }
+            introduced = introduced.reject { |finding| waived.include?(finding.fingerprint) }
+            waived_findings = waived.map { |fingerprint| current_by_fp[fingerprint] }.compact.map { |finding| restate(finding, "waived") }.sort_by(&:sort_key)
+            classified = (introduced + waived_findings).sort_by(&:sort_key)
+            return build_result(existing: existing, introduced: introduced, resolved: resolved, changed: changed, moved: moved, classified_findings: classified, waived: waived_findings, orphaned_waivers: orphaned, baseline: baseline)
+          end
+          return build_result(existing: existing, introduced: introduced, resolved: resolved, changed: changed, moved: moved, classified_findings: introduced, waived: [], orphaned_waivers: orphaned, baseline: baseline)
+        end
+        return build_result(existing: existing, introduced: introduced, resolved: resolved, changed: changed, moved: moved, findings: findings, baseline: baseline, waivers: waivers, clock: clock)
+      end
+
+      baseline_fps = Set.new(baseline.entries.map { |entry| entry.fetch("fingerprint") })
+      baseline_by_fp = baseline.entries.to_h { |entry| [entry.fetch("fingerprint"), entry] }
+      current_by_fp = findings.to_h { |finding| [finding.fingerprint, finding] }
+      current_fps = Set.new(current_by_fp.keys)
+
+      existing_fps = baseline_fps & current_fps
+      resolved_fps = baseline_fps - current_fps
+      introduced_fps = current_fps - baseline_fps
+
+      existing = existing_fps.map { |fingerprint| restate(current_by_fp.fetch(fingerprint), "existing") }.sort_by(&:sort_key)
+      resolved_entries = resolved_fps.map { |fingerprint| baseline_by_fp.fetch(fingerprint) }.sort_by { |entry| entry.fetch("fingerprint") }
+      introduced_candidates = introduced_fps.map { |fingerprint| current_by_fp.fetch(fingerprint) }.sort_by(&:sort_key)
+
+      resolved_by_key = build_resolved_index(resolved_entries)
+      changed, moved, introduced = partition_introduced(introduced_candidates, resolved_by_key, resolved_entries, rename_map: rename_map)
+      resolved = resolved_entries.map { |entry| { "fingerprint" => entry.fetch("fingerprint"), "analyzer" => entry.fetch("analyzer"), "rule_id" => entry.fetch("rule_id"), "path" => entry.fetch("path"), "message" => entry.fetch("message"), "state" => "resolved" } }
+      if changed.any? || moved.any?
+        consumed_fps = Set.new((changed + moved).flat_map { |pair| [pair[:resolved].fetch("fingerprint")] })
+        resolved = resolved.reject { |entry| consumed_fps.include?(entry.fetch("fingerprint")) }
+      end
+
+      waived = Set.new
+      orphaned = []
+      if waivers.any?
+        waived, orphaned = apply_waivers(nil, findings, baseline, waivers, clock)
+      end
+      waived_findings = []
+      if waived.any?
+        existing = existing.reject { |finding| waived.include?(finding.fingerprint) }
+        introduced = introduced.reject { |finding| waived.include?(finding.fingerprint) }
+        changed_pairs = changed
+        moved_pairs = moved
+        changed_findings_tmp = changed_pairs.map { |pair| pair[:finding] }.reject { |finding| waived.include?(finding.fingerprint) }
+        moved_findings_tmp = moved_pairs.map { |pair| pair[:finding] }.reject { |finding| waived.include?(finding.fingerprint) }
+        changed = changed_pairs.select { |pair| changed_findings_tmp.include?(pair[:finding]) }
+        moved = moved_pairs.select { |pair| moved_findings_tmp.include?(pair[:finding]) }
+        waived_findings = waived.map { |fingerprint| current_by_fp[fingerprint] }.compact.map { |finding| restate(finding, "waived") }.sort_by(&:sort_key)
+        classified_extra = waived_findings
+        changed_findings = changed.map { |pair| pair[:finding] }
+        moved_findings = moved.map { |pair| pair[:finding] }
+        classified = (existing + introduced + changed_findings + moved_findings + classified_extra).sort_by(&:sort_key)
+        return build_result(existing: existing, introduced: introduced, resolved: resolved, changed: changed_findings, moved: moved_findings, classified_findings: classified, waived: classified_extra, orphaned_waivers: orphaned, baseline: baseline)
+      end
+      changed_findings = changed.map { |pair| pair[:finding] }
+      moved_findings = moved.map { |pair| pair[:finding] }
+      classified = (existing + introduced + changed_findings + moved_findings).sort_by(&:sort_key)
+      build_result(existing: existing, introduced: introduced, resolved: resolved, changed: changed_findings, moved: moved_findings, classified_findings: classified, waived: [], orphaned_waivers: orphaned, baseline: baseline)
+    end
+
+    def self.build_result(existing:, introduced:, resolved:, changed:, moved:, classified_findings: nil, waived: [], orphaned_waivers: [], baseline: nil, findings: nil, waivers: nil, clock: nil)
+      classified_findings ||= (existing + introduced + changed + moved + waived).sort_by { |finding| finding.is_a?(Hash) ? finding.fetch("fingerprint") : finding.sort_key }
+      counts = {
+        "introduced" => introduced.length,
+        "existing" => existing.length,
+        "resolved" => resolved.length,
+        "changed" => changed.length,
+        "moved" => moved.length,
+        "waived" => waived.length
+      }
+      Result.new(existing: existing.freeze, introduced: introduced.freeze, resolved: resolved.freeze, changed: changed.freeze, moved: moved.freeze, counts: counts.freeze, classified_findings: classified_findings.freeze, orphaned_waivers: orphaned_waivers.freeze)
+    end
+    private_class_method :build_result
+
+    def self.restate(finding, state)
+      Finding.new(
+        fingerprint: finding.fingerprint,
+        origin: finding.origin,
+        analyzer: finding.analyzer,
+        rule_id: finding.rule_id,
+        category: finding.category,
+        severity: finding.severity,
+        confidence: finding.confidence,
+        state: state,
+        evidence_ref: finding.evidence_ref,
+        location: finding.location,
+        message: finding.message
+      )
+    end
+    private_class_method :restate
+
+    def self.build_resolved_index(resolved_entries)
+      index = Hash.new { |hash, key| hash[key] = [] }
+      resolved_entries.each do |entry|
+        key = [entry.fetch("analyzer"), entry.fetch("rule_id"), entry.fetch("message")]
+        index[key] << entry
+      end
+      index
+    end
+    private_class_method :build_resolved_index
+
+    def self.partition_introduced(candidates, resolved_by_key, resolved_entries, rename_map: nil)
+      changed = []
+      moved = []
+      introduced = []
+      consumed_resolved = Set.new
+      candidates.each do |finding|
+        key_exact = [finding.analyzer, finding.rule_id, finding.message]
+        exact_matches = resolved_by_key[key_exact].reject { |entry| consumed_resolved.include?(entry.fetch("fingerprint")) }
+        if exact_matches.length == 1
+          resolved_entry = exact_matches.first
+          if resolved_entry.fetch("path") != finding.location.fetch("path")
+            if rename_map
+              new_path = finding.location.fetch("path")
+              expected_old = rename_map[new_path]
+              if expected_old && resolved_entry.fetch("path") == expected_old
+                moved << { finding: restate(finding, "moved"), resolved: resolved_entry }
+                consumed_resolved.add(resolved_entry.fetch("fingerprint"))
+                next
+              elsif expected_old && resolved_entry.fetch("path") != expected_old
+                introduced << restate(finding, "introduced")
+                next
+              end
+            end
+            moved << { finding: restate(finding, "moved"), resolved: resolved_entry }
+            consumed_resolved.add(resolved_entry.fetch("fingerprint"))
+            next
+          end
+        elsif rename_map && exact_matches.length > 1
+          new_path = finding.location.fetch("path")
+          expected_old = rename_map[new_path]
+          if expected_old
+            filtered = exact_matches.select { |entry| entry.fetch("path") == expected_old }
+            if filtered.length == 1
+              resolved_entry = filtered.first
+              moved << { finding: restate(finding, "moved"), resolved: resolved_entry }
+              consumed_resolved.add(resolved_entry.fetch("fingerprint"))
+              next
+            end
+          end
+          introduced << restate(finding, "introduced")
+          next
+        end
+        same_path_key = resolved_entries.select { |entry| entry.fetch("path") == finding.location.fetch("path") && entry.fetch("analyzer") == finding.analyzer && entry.fetch("rule_id") == finding.rule_id }
+        same_path_unconsumed = same_path_key.reject { |entry| consumed_resolved.include?(entry.fetch("fingerprint")) }
+        if same_path_unconsumed.length == 1 && same_path_unconsumed.first.fetch("message") != finding.message
+          resolved_entry = same_path_unconsumed.first
+          changed << { finding: restate(finding, "changed"), resolved: resolved_entry }
+          consumed_resolved.add(resolved_entry.fetch("fingerprint"))
+          next
+        end
+        introduced << restate(finding, "introduced")
+      end
+      [changed, moved, introduced]
+    end
+    private_class_method :partition_introduced
+
+    def self.apply_waivers(grouped, findings, baseline, waivers, clock)
+      current_fps = Set.new(findings.map(&:fingerprint))
+      baseline_fps = baseline ? Set.new(baseline.entries.map { |entry| entry.fetch("fingerprint") }) : Set.new
+      all_fps = current_fps | baseline_fps
+      active = Set.new
+      orphaned = []
+      waivers.each do |waiver|
+        hash = waiver.is_a?(Hash) ? waiver : waiver.to_h
+        fingerprint = hash["fingerprint"] || hash[:fingerprint]
+        next unless fingerprint
+
+        if !all_fps.include?(fingerprint)
+          orphaned << hash
+          next
+        end
+        active.add(fingerprint) if waiver_active?(hash, clock)
+      end
+      [active, orphaned]
+    end
+    private_class_method :apply_waivers
+
+    def self.waiver_active?(waiver, clock)
+      created_at = parse_time(waiver["created_at"] || waiver[:created_at])
+      expires_at = parse_time(waiver["expires_at"] || waiver[:expires_at])
+      return false unless created_at && expires_at
+
+      clock >= created_at && clock < expires_at
+    end
+    private_class_method :waiver_active?
+
+    def self.parse_time(value)
+      return nil if value.nil?
+
+      Time.iso8601(value.to_s).utc
+    rescue ArgumentError
+      nil
+    end
+    private_class_method :parse_time
+  end
+end