necropsy 0.1.0 → 0.3.0

data/lib/necropsy/cli.rb

@@ -1,38 +1,51 @@
 # frozen_string_literal: true
 
 require 'date'
+require 'digest'
 require 'English'
 require 'fileutils'
 require 'json'
 require 'optparse'
+require 'rbconfig'
 require 'securerandom'
 require 'yaml'
 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
       parser = build_parser(options)
       parser.parse!(argv)
-      apply_config_defaults(options)
+      if options[:help]
+        puts parser
+        return 0
+      end
+      if options[:version]
+        puts Necropsy::VERSION
+        return 0
+      end
+      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])
-        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'
@@ -43,12 +56,16 @@ module Necropsy
         record(options, argv)
       when 'coverage'
         coverage(options, argv)
+      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, Error => e
+    rescue OptionParser::ParseError, Psych::Exception, Error, GraphSelfCheck::Failure => e
       warn e.message
       2
     end
@@ -60,18 +77,26 @@ module Necropsy
         root: '.',
         config: nil,
         format: :human,
-        min_confidence: :low,
+        min_confidence: Reporter::DEFAULT_MIN_CONFIDENCE,
         baseline: nil,
         fail_on: nil,
         diff_base: nil,
         ratchet: false,
         write: false,
         gold_standard: nil,
-        output: 'tmp/necropsy_trace_point.yml',
+        output: nil,
         sample_rate: 1.0,
         ablation: false,
+        bench_check: false,
         precision_threshold: nil,
-        recall_threshold: nil
+        recall_threshold: nil,
+        as_of: nil,
+        strict_health: false,
+        allow_degraded: [],
+        help: false,
+        version: false,
+        include_graph: false,
+        self_check: false
       }
     end
 
@@ -80,12 +105,18 @@ module Necropsy
         parser.banner = 'Usage: necropsy COMMAND [options]'
         parser.on('--root PATH', 'Project root') { |value| options[:root] = value }
         parser.on('--config PATH', 'Configuration file') { |value| options[:config] = value }
-        parser.on('--format FORMAT', 'human, json, yaml, sarif, or github') { |value| options[:format] = value.to_sym }
+        parser.on('--format FORMAT', Reporter::FORMATS.map(&:to_s), 'Output format') do |value|
+          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] = value.to_sym
+          options[:min_confidence] = confidence_level(value)
         end
         parser.on('--baseline PATH', 'Baseline path') { |value| options[:baseline] = value }
-        parser.on('--fail-on LEVEL', 'CI failure threshold') { |value| options[:fail_on] = value.to_sym }
+        parser.on('--fail-on LEVEL', 'CI failure threshold') do |value|
+          options[:fail_on] = confidence_level(value)
+        end
         parser.on('--diff-base REV', 'Restrict reported findings to files changed since REV') do |value|
           options[:diff_base] = value
         end
@@ -94,24 +125,69 @@ module Necropsy
         parser.on('--gold-standard PATH', 'Gold standard YAML for bench') { |value| options[:gold_standard] = value }
         parser.on('--output PATH', 'Output path for record') { |value| options[:output] = value }
         parser.on('--sample-rate RATE', Float, 'TracePoint sample rate for record') do |value|
+          raise OptionParser::InvalidArgument, 'sample rate must be between 0.0 and 1.0' unless value.between?(0.0, 1.0)
+
           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
-          puts parser
-          exit 0
+          options[:help] = true
         end
+        parser.on('-v', '--version', 'Show version') { options[:version] = true }
       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 or definition ID" unless node_id
+      raise Error, "Unexpected arguments for #{command}: #{argv.join(' ')}" unless argv.empty?
+
+      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
 
     def apply_config_defaults(options)
@@ -121,31 +197,115 @@ 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
 
-      if options[:ratchet] && findings.length > baseline.fingerprints.length
-        puts "Ratchet failed: #{findings.length} findings exceed baseline count #{baseline.fingerprints.length}"
+      baseline_count = baseline.count_at_least(options[:fail_on])
+      if options[:ratchet] && findings.length > baseline_count
+        puts "Ratchet failed: #{findings.length} findings exceed baseline count #{baseline_count}"
         return 1
       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))
@@ -157,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'
@@ -175,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],
@@ -188,38 +402,29 @@ 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)
-      script_argv = argv.dup
-      script_argv.shift if script_argv.first == 'ruby'
-      script = script_argv.shift
-      raise Error, 'record requires a Ruby script after --' unless script
+      command = argv.dup
+      raise Error, 'record requires a Ruby script or command after --' if command.empty?
 
-      output = File.expand_path(options[:output], options[:root])
+      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 = 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
 
-      previous_argv = ARGV.dup
-      ARGV.replace(script_argv)
-      Analyzers::Dynamic::TracePointCollector.record(
-        root: File.expand_path(options[:root]),
-        output: output,
-        sample_rate: options[:sample_rate]
-      ) do
-        load File.expand_path(script, options[:root])
-      end
-      puts "Wrote #{output}"
-      0
-    ensure
-      ARGV.replace(previous_argv) if previous_argv
+      $CHILD_STATUS&.exitstatus || 1
     end
 
     def coverage(options, argv)
       script_argv = argv.dup
       raise Error, 'coverage requires a Ruby script or command after --' if script_argv.empty?
 
-      output = File.expand_path(options[:output].sub('trace_point', 'coverage'), options[:root])
+      output = File.expand_path(options[:output] || 'tmp/necropsy_coverage.yml', options[:root])
       FileUtils.mkdir_p(File.dirname(output))
 
       return record_coverage_script(options, output, script_argv) if local_ruby_script?(options, script_argv)
@@ -241,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
@@ -272,16 +477,54 @@ module Necropsy
       }
     end
 
+    def trace_runtime_env(options, output, run_id)
+      rubyopt = [ENV.fetch('RUBYOPT', nil), '-rnecropsy/trace_point_runtime'].compact.reject(&:empty?).join(' ')
+      {
+        'NECROPSY_TRACE_ROOT' => File.expand_path(options[:root]),
+        'NECROPSY_TRACE_OUTPUT' => output,
+        'NECROPSY_TRACE_SAMPLE_RATE' => options[:sample_rate].to_s,
+        'NECROPSY_TRACE_MERGE' => '1',
+        'NECROPSY_TRACE_RUN_ID' => run_id,
+        'RUBYOPT' => rubyopt,
+        'RUBYLIB' => rubylib
+      }
+    end
+
+    def trace_command(options, command)
+      script = command.first
+      path = File.expand_path(script, options[:root])
+      return [RbConfig.ruby, path, *command.drop(1)] if script.end_with?('.rb') && File.file?(path)
+
+      command
+    end
+
     def rubylib
       paths = [File.expand_path('..', __dir__), ENV.fetch('RUBYLIB', nil)].compact.reject(&:empty?)
       paths.join(File::PATH_SEPARATOR)
     end
 
     def output_for_run?(output, run_id)
-      payload = YAML.load_file(output) || {}
+      payload = YAML.safe_load_file(output, aliases: false) || {}
       payload.dig('observation', 'run_id') == run_id
     rescue SystemCallError, Psych::Exception
       false
     end
+
+    def confidence_level(value)
+      level = value.to_sym
+      return level if CONFIDENCE_LEVELS.key?(level)
+
+      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