necropsy 0.2.0 → 0.3.0

data/lib/necropsy/cli.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'date'
+require 'digest'
 require 'English'
 require 'fileutils'
 require 'json'
@@ -12,10 +13,17 @@ require 'necropsy'
 
 module Necropsy
   class CLI
+    HEALTH_FAILURE_STATUS = 3
+
     def self.run(argv)
       new.run(argv)
     end
 
+    def initialize(run_id_generator: nil, environment: ENV)
+      @run_id_generator = run_id_generator
+      @environment = environment
+    end
+
     def run(argv)
       command = argv.first&.start_with?('-') ? 'analyze' : argv.shift || 'analyze'
       options = default_options
@@ -29,23 +37,15 @@ module Necropsy
         puts Necropsy::VERSION
         return 0
       end
-      apply_config_defaults(options)
+      apply_config_defaults(options) unless command == 'semantics'
 
       case command
       when 'analyze'
         report = analyze(options)
-        puts Reporter.new(report).render(
-          format: options[:format],
-          min_confidence: options[:min_confidence],
-          include_graph: options[:include_graph]
-        )
-        0
+        emit_report(report, options, min_confidence: options[:min_confidence])
+        health_acceptable?(report, options, strict: false) ? 0 : HEALTH_FAILURE_STATUS
       when 'baseline'
-        report = analyze(options)
-        path = File.expand_path(options[:baseline], options[:root])
-        Guardrail::Baseline.write(report, path: path)
-        puts "Wrote #{path}"
-        0
+        baseline(options, argv)
       when 'check'
         check(options)
       when 'quarantine'
@@ -56,14 +56,16 @@ module Necropsy
         record(options, argv)
       when 'coverage'
         coverage(options, argv)
-      when 'why', 'explain'
+      when 'semantics'
+        semantics(options, argv)
+      when 'why', 'why-not', 'explain'
         diagnose(command, options, argv)
       else
         warn "Unknown command: #{command}"
         warn parser
         2
       end
-    rescue OptionParser::ParseError, Psych::Exception, Error => e
+    rescue OptionParser::ParseError, Psych::Exception, Error, GraphSelfCheck::Failure => e
       warn e.message
       2
     end
@@ -85,11 +87,16 @@ module Necropsy
         output: nil,
         sample_rate: 1.0,
         ablation: false,
+        bench_check: false,
         precision_threshold: nil,
         recall_threshold: nil,
+        as_of: nil,
+        strict_health: false,
+        allow_degraded: [],
         help: false,
         version: false,
-        include_graph: false
+        include_graph: false,
+        self_check: false
       }
     end
 
@@ -102,6 +109,7 @@ module Necropsy
           options[:format] = value.to_sym
         end
         parser.on('--include-graph', 'Include nodes and edges in JSON/YAML output') { options[:include_graph] = true }
+        parser.on('--self-check', 'Validate graph invariants after analysis') { options[:self_check] = true }
         parser.on('--min-confidence LEVEL', 'low, medium, high, or certain') do |value|
           options[:min_confidence] = confidence_level(value)
         end
@@ -122,12 +130,30 @@ module Necropsy
           options[:sample_rate] = value
         end
         parser.on('--ablation', 'Run bench across analyzer combinations') { options[:ablation] = true }
+        parser.on('--check', 'Fail bench when release criteria do not pass') { options[:bench_check] = true }
         parser.on('--precision-threshold N', Float, 'Bench release precision threshold') do |value|
           options[:precision_threshold] = value
         end
         parser.on('--recall-threshold N', Float, 'Bench release recall threshold') do |value|
           options[:recall_threshold] = value
         end
+        parser.on('--as-of DATE', 'Use a reproducible UTC date for time-dependent analysis') do |value|
+          options[:as_of] = Date.iso8601(value)
+        rescue Date::Error
+          raise OptionParser::InvalidArgument, 'as-of must be an ISO 8601 date'
+        end
+        parser.on('--strict-health', 'Return status 3 unless analysis health is complete') do
+          options[:strict_health] = true
+        end
+        parser.on('--allow-degraded=REASONS', 'Comma-separated degraded reason codes to allow explicitly') do |value|
+          reasons = value.split(',').map(&:strip).reject(&:empty?)
+          raise OptionParser::InvalidArgument, 'allow-degraded requires at least one reason code' if reasons.empty?
+          unless reasons.all? { |reason| reason.match?(/\A[a-z][a-z0-9_]*\z/) }
+            raise OptionParser::InvalidArgument, 'allow-degraded reason codes must use lowercase letters, numbers, and _'
+          end
+
+          options[:allow_degraded] |= reasons
+        end
         parser.on('-h', '--help', 'Show help') do
           options[:help] = true
         end
@@ -135,17 +161,31 @@ module Necropsy
       end
     end
 
-    def analyze(options)
-      Necropsy.analyze(root: options[:root], config_path: options[:config])
+    def analyze(options, ignored_reference_paths: [])
+      report = Necropsy.analyze(
+        root: options[:root],
+        config_path: options[:config],
+        ignored_reference_paths: ignored_reference_paths,
+        as_of: options[:as_of]
+      )
+      GraphSelfCheck.new(report).validate! if options[:self_check]
+      report
     end
 
     def diagnose(command, options, argv)
       node_id = argv.shift
-      raise Error, "#{command} requires a symbol ID" unless node_id
+      raise Error, "#{command} requires a symbol or definition ID" unless node_id
       raise Error, "Unexpected arguments for #{command}: #{argv.join(' ')}" unless argv.empty?
 
-      diagnostics = Diagnostics.new(analyze(options))
-      payload = command == 'why' ? diagnostics.why(node_id) : diagnostics.explain(node_id)
+      report = analyze(options)
+      return health_failure(report, options) unless health_acceptable?(report, options, strict: false)
+
+      diagnostics = Diagnostics.new(report)
+      payload = case command
+                when 'why' then diagnostics.why(node_id)
+                when 'why-not' then diagnostics.why_not(node_id)
+                else diagnostics.explain(node_id)
+                end
       puts diagnostics.render(payload, format: options[:format])
       0
     end
@@ -157,11 +197,20 @@ module Necropsy
     end
 
     def check(options)
-      report = analyze(options)
+      report = analyze(options, ignored_reference_paths: [options[:baseline]])
+      return health_failure(report, options) unless health_acceptable?(report, options, strict: true)
+
+      report_invalid_quarantine_dates(report)
+      expiry_failure = apply_quarantine_expiry_policy(report, report_config(options))
       findings = filtered_findings(report, options)
       baseline_path = File.expand_path(options[:baseline], options[:root])
       baseline = Guardrail::Baseline.load(baseline_path)
-      failures = findings.reject { |finding| baseline.include?(finding) }
+      comparison = baseline.compare(report.actionable_candidates(min_confidence: :low))
+      if comparison.review_required?
+        puts Reporter.render_baseline_review(comparison.review_report)
+        return 1
+      end
+      failures = findings - comparison.matched_findings
 
       baseline_count = baseline.count_at_least(options[:fail_on])
       if options[:ratchet] && findings.length > baseline_count
@@ -170,19 +219,93 @@ module Necropsy
       end
 
       if failures.any?
-        puts Reporter.new(Report.new(root: report.root, graph: report.graph, findings: failures)).render(
-          format: :human,
-          min_confidence: options[:fail_on]
-        )
+        emit_report(report_with_findings(report, failures), options, min_confidence: options[:fail_on])
         return 1
       end
 
+      return 1 if expiry_failure
+
       puts 'Necropsy check passed'
       0
     end
 
+    def report_with_findings(report, findings)
+      Report.new(
+        root: report.root,
+        graph: report.graph,
+        findings: findings,
+        reachability: report.reachability,
+        project: report.project,
+        source_snapshot: report.source_snapshot,
+        performance_profile: report.performance_profile,
+        analysis_health: report.analysis_health
+      )
+    end
+
+    def emit_report(report, options, min_confidence:)
+      reporter = Reporter.new(report)
+      if options[:format] == :ndjson
+        reporter.each_ndjson { |line| puts line }
+      else
+        puts reporter.render(
+          format: options[:format],
+          min_confidence: min_confidence,
+          include_graph: options[:include_graph]
+        )
+      end
+    end
+
+    def semantics(options, argv)
+      raise Error, "Unexpected semantics arguments: #{argv.join(' ')}" unless argv.empty?
+
+      puts SemanticsMatrix.new.render(format: options[:format])
+      0
+    end
+
+    def apply_quarantine_expiry_policy(report, config)
+      policy = config.quarantine_expiry
+      return false if policy == :ignore
+
+      findings = findings_with_quarantine_components(
+        report,
+        %w[quarantine_review_required quarantine_fingerprint_required quarantine_stale_fingerprint]
+      )
+      return false if findings.empty?
+
+      noun = findings.length == 1 ? 'annotation requires' : 'annotations require'
+      lines = findings.map { |finding| "  #{finding.node.file}:#{finding.node.line} #{finding.node.id}" }
+      message = "Quarantine expiry #{policy == :fail ? 'failed' : 'warning'}: " \
+                "#{findings.length} #{noun} review\n#{lines.join("\n")}"
+      if policy == :warn
+        warn message
+        return false
+      end
+
+      puts message
+      true
+    end
+
+    def report_invalid_quarantine_dates(report)
+      findings = findings_with_quarantine_component(report, 'quarantine_invalid_date')
+      return if findings.empty?
+
+      noun = findings.length == 1 ? 'annotation has' : 'annotations have'
+      lines = findings.map { |finding| "  #{finding.node.file}:#{finding.node.line} #{finding.node.id}" }
+      warn "Invalid quarantine date warning: #{findings.length} #{noun} an invalid since date\n#{lines.join("\n")}"
+    end
+
+    def findings_with_quarantine_component(report, name)
+      findings_with_quarantine_components(report, [name])
+    end
+
+    def findings_with_quarantine_components(report, names)
+      report.dead_methods(min_confidence: :low).select do |finding|
+        finding.score_components.any? { |component| names.include?(component.name) }
+      end
+    end
+
     def filtered_findings(report, options)
-      findings = report.dead_methods(min_confidence: options[:fail_on])
+      findings = report.actionable_candidates(min_confidence: options[:fail_on])
       return findings unless options[:diff_base]
 
       project = Project.new(root: File.expand_path(options[:root]), config: report_config(options))
@@ -194,9 +317,60 @@ module Necropsy
       Configuration.load(root: File.expand_path(options[:root]), path: options[:config])
     end
 
+    def health_failure(report, options)
+      if options[:format] == :human
+        puts Reporter.render_analysis_health(report.analysis_health)
+      else
+        emit_report(report, options, min_confidence: options[:fail_on] || options[:min_confidence])
+      end
+      HEALTH_FAILURE_STATUS
+    end
+
+    def health_acceptable?(report, options, strict:)
+      health = report.analysis_health
+      return true if health.complete?
+
+      allowed = Array(options[:allow_degraded])
+      degraded_codes = health.reasons.filter_map do |reason|
+        reason['code'].to_s if reason['severity'].to_s == 'degraded'
+      end.uniq
+      explicitly_allowed = health.status == :degraded && degraded_codes.any? &&
+                           (degraded_codes - allowed).empty?
+      return true if explicitly_allowed
+
+      !(strict || options[:strict_health])
+    end
+
+    def baseline(options, argv)
+      migration = argv.first == 'migrate'
+      argv.shift if migration
+      raise Error, "Unexpected baseline arguments: #{argv.join(' ')}" unless argv.empty?
+
+      report = analyze(options, ignored_reference_paths: [options[:baseline]])
+      return health_failure(report, options) unless health_acceptable?(report, options, strict: true)
+
+      path = File.expand_path(options[:baseline], options[:root])
+      if migration
+        comparison = Guardrail::Baseline.load(path).migrate(report.actionable_candidates(min_confidence: :low))
+        if comparison.review_required?
+          puts Reporter.render_baseline_review(comparison.review_report)
+          return 1
+        end
+      end
+      Guardrail::Baseline.write(report, path: path, clock: Clock.new(as_of: options[:as_of]))
+      puts "#{migration ? 'Migrated' : 'Wrote'} #{path}"
+      0
+    end
+
     def quarantine(options)
       report = analyze(options)
-      quarantine = Guardrail::Quarantine.new(report: report, root: File.expand_path(options[:root]))
+      return health_failure(report, options) unless health_acceptable?(report, options, strict: options[:write])
+
+      quarantine = Guardrail::Quarantine.new(
+        report: report,
+        root: File.expand_path(options[:root]),
+        clock: Clock.new(as_of: options[:as_of])
+      )
       if options[:write]
         quarantine.write(min_confidence: options[:min_confidence])
         puts 'Wrote quarantine annotations'
@@ -212,11 +386,14 @@ module Necropsy
     def bench(options)
       raise Error, '--gold-standard is required for bench' unless options[:gold_standard]
 
-      report = analyze(options)
+      gold_standard_path = File.expand_path(options[:gold_standard])
+      report = analyze(options, ignored_reference_paths: [gold_standard_path])
+      return health_failure(report, options) unless health_acceptable?(report, options, strict: true)
+
       config = report_config(options)
       result = Bench::Evaluator.new(
         report: report,
-        gold_standard_path: options[:gold_standard],
+        gold_standard_path: gold_standard_path,
         min_confidence: options[:min_confidence],
         root: options[:root],
         config_path: options[:config],
@@ -225,7 +402,7 @@ module Necropsy
         recall_threshold: options[:recall_threshold] || config.bench_recall_threshold
       ).call
       puts JSON.pretty_generate(result)
-      0
+      options[:bench_check] && !result.dig('release_criteria', 'passed') ? 1 : 0
     end
 
     def record(options, argv)
@@ -235,7 +412,7 @@ module Necropsy
       output = File.expand_path(options[:output] || 'tmp/necropsy_trace_point.yml', options[:root])
       FileUtils.mkdir_p(File.dirname(output))
       command = trace_command(options, command)
-      run_id = SecureRandom.hex(16)
+      run_id = artifact_run_id(options, output, 'trace_point')
       status = system(trace_runtime_env(options, output, run_id), *command)
       puts "Wrote #{output}" if output_for_run?(output, run_id)
       return 0 if status
@@ -269,7 +446,7 @@ module Necropsy
     end
 
     def run_coverage_command(options, output, script_argv)
-      run_id = SecureRandom.hex(16)
+      run_id = artifact_run_id(options, output, 'coverage')
       status = system(coverage_runtime_env(options, output, run_id), *script_argv)
       puts "Wrote #{output}" if output_for_run?(output, run_id)
       return 0 if status
@@ -339,5 +516,15 @@ module Necropsy
 
       raise OptionParser::InvalidArgument, "unknown confidence level: #{value}"
     end
+
+    def artifact_run_id(options, output, kind)
+      return @run_id_generator.call if @run_id_generator
+
+      epoch = @environment.fetch(Clock::SOURCE_DATE_EPOCH, nil)
+      reproducible = options[:as_of]&.iso8601 || epoch
+      return SecureRandom.hex(16) unless reproducible
+
+      Digest::SHA256.hexdigest([kind, File.expand_path(options[:root]), output, reproducible].join("\0"))[0, 32]
+    end
   end
 end

data/lib/necropsy/clock.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module Necropsy
+  class Clock
+    SOURCE_DATE_EPOCH = 'SOURCE_DATE_EPOCH'
+
+    attr_reader :time
+
+    def initialize(as_of: nil, environment: ENV, now: nil)
+      @time = resolve_time(as_of, environment, now).utc.freeze
+    rescue ArgumentError, TypeError, RangeError
+      raise Error, 'as-of time and SOURCE_DATE_EPOCH must identify a valid date'
+    end
+
+    def date
+      time.to_date
+    end
+
+    private
+
+    def resolve_time(as_of, environment, now)
+      return time_for_as_of(as_of) unless as_of.nil?
+
+      epoch = environment[SOURCE_DATE_EPOCH]
+      return Time.at(Integer(epoch), in: '+00:00') unless epoch.nil? || epoch.empty?
+
+      value = now.respond_to?(:call) ? now.call : now
+      value || Time.now.utc
+    end
+
+    def time_for_as_of(value)
+      return value if value.is_a?(Time)
+
+      date = value.is_a?(Date) ? value : Date.iso8601(value.to_s)
+      Time.utc(date.year, date.month, date.day)
+    end
+  end
+end