rail_verdict 1.0.0

data/lib/rail_verdict/configuration.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module RailVerdict
+  class Configuration
+    DEFAULT_FILENAME = ".railverdict.yml"
+    CONFIGURATION_VERSION = 1.4
+    SUPPORTED_VERSIONS = [1, 1.1, 1.2, 1.3, 1.4].freeze
+    UTF8_BOM = "\xEF\xBB\xBF".b
+
+    attr_reader :version, :mode, :analyzers, :source_path, :digest
+
+    def self.load(path)
+      source_path = path.to_s
+      unless File.file?(source_path)
+        raise ConfigurationError.new(
+          "configuration file not found: #{source_path}",
+          source_path: source_path
+        )
+      end
+
+      bytes = File.binread(source_path)
+      text = decode_utf8(bytes, source_path)
+      data = load_strict_yaml(text, source_path)
+      validate_schema(data, source_path)
+      new(data, source_path, bytes)
+    end
+
+    def self.decode_utf8(bytes, source_path)
+      if bytes.start_with?(UTF8_BOM)
+        raise ConfigurationError.new(
+          "#{source_path}: configuration must be UTF-8 without a byte order mark",
+          source_path: source_path
+        )
+      end
+
+      text = bytes.dup.force_encoding(Encoding::UTF_8)
+      unless text.valid_encoding?
+        raise ConfigurationError.new(
+          "#{source_path}: configuration must be valid UTF-8",
+          source_path: source_path
+        )
+      end
+
+      text
+    end
+
+    def self.load_strict_yaml(text, source_path)
+      StrictYaml.parse(text, source_path)
+    rescue StrictYaml::Error => error
+      raise ConfigurationError.new(
+        "#{error.message}",
+        source_path: source_path,
+        property_path: error.property_path
+      )
+    end
+
+    def self.validate_schema(data, source_path)
+      unless data.is_a?(Hash)
+        raise ConfigurationError.new(
+          "#{source_path}: $: configuration must be a mapping",
+          source_path: source_path,
+          property_path: "$"
+        )
+      end
+
+      errors = SchemaValidator.validate_configuration(data)
+      return if errors.empty?
+
+      raise ConfigurationError.new(
+        "invalid configuration #{source_path}: #{errors.join('; ')}",
+        source_path: source_path,
+        property_path: errors.first.to_s.split(":").first
+      )
+    end
+
+    def initialize(data, source_path, bytes)
+      @version = data.fetch("version")
+      @mode = data.fetch("mode").freeze
+      @analyzers = deep_freeze(data.fetch("analyzers"))
+      @raw_data = deep_freeze(data.dup)
+      @source_path = source_path.dup.freeze
+      @digest = Digest::SHA256.hexdigest(bytes).freeze
+      freeze
+    end
+
+    def analyzer_selection(name)
+      @analyzers.fetch(name)
+    end
+
+    def analyzer_enabled?(name)
+      selection = @analyzers[name]
+      return false if selection.nil?
+
+      selection.fetch("enabled")
+    end
+
+    def analyzer_required?(name)
+      @analyzers.fetch(name).fetch("required")
+    end
+
+    def analyzer_present?(name)
+      @analyzers.key?(name)
+    end
+
+    def baseline_path
+      @raw_data&.dig("baseline", "path")
+    end
+
+    def waivers_path
+      @raw_data&.dig("waivers", "path")
+    end
+
+    def git_base
+      @raw_data&.dig("git", "base")
+    end
+
+    def ai_config
+      @raw_data&.dig("ai")
+    end
+
+    def ai_enabled?
+      ai_config&.fetch("enabled", false) == true
+    end
+
+    def ai_mode
+      ai_config&.fetch("mode", "off")
+    end
+
+    def ai_remote_enabled?
+      ai_enabled? && ai_config&.dig("remote", "enabled") == true
+    end
+
+    def ai_remote_trust
+      ai_config&.dig("remote", "trust") || "redacted"
+    end
+
+    def ai_budgets
+      ai_config&.fetch("budgets", {}) || {}
+    end
+
+    def ai_cache_enabled?
+      ai_config&.dig("cache", "enabled") == true
+    end
+
+    private
+
+    def deep_freeze(value)
+      case value
+      when Hash
+        value.each { |key, child| deep_freeze(child); key.freeze }
+        value.freeze
+      when Array
+        value.each { |child| deep_freeze(child) }
+        value.freeze
+      when String
+        value.freeze
+      else
+        value
+      end
+      value
+    end
+  end
+end

data/lib/rail_verdict/contracts/analyzer_result.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  class AnalyzerResult
+    EXECUTION_STATUSES = %w[
+      succeeded unavailable unsupported timed_out signaled
+      failed parse_failed truncated malformed
+    ].freeze
+    FAILURE_CODES = (EXECUTION_STATUSES - ["succeeded"]).freeze
+    EVIDENCE_STATUSES = %w[complete incomplete].freeze
+
+    attr_reader :analyzer, :invocation, :tool_version, :execution_status,
+                :evidence_status, :finding_ids, :failure, :evidence_summary
+
+    def initialize(analyzer:, invocation:, execution_status:, finding_ids:, tool_version: nil, failure: nil, evidence_summary: nil)
+      @analyzer = require_nonempty_string(analyzer, "analyzer", 256).freeze
+      @invocation = validate_invocation(invocation)
+      @execution_status = validate_execution_status(execution_status)
+      @evidence_status = execution_status == "succeeded" ? "complete" : "incomplete"
+      @tool_version = tool_version && require_nonempty_string(tool_version, "tool_version", 128).freeze
+      @finding_ids = validate_finding_ids(finding_ids)
+      @failure = validate_failure(failure)
+      @evidence_summary = validate_evidence_summary(evidence_summary)
+      enforce_coupling
+      freeze
+    end
+
+    def complete?
+      evidence_status == "complete"
+    end
+
+    def to_schema_h
+      result = {}
+      result["analyzer"] = analyzer
+      result["tool_version"] = tool_version if tool_version
+      result["invocation"] = invocation
+      result["execution_status"] = execution_status
+      result["evidence_status"] = evidence_status
+      result["finding_ids"] = finding_ids
+      result["failure"] = failure if failure
+      result["evidence_summary"] = evidence_summary if evidence_summary
+      result
+    end
+
+    private
+
+    def enforce_coupling
+      if execution_status == "succeeded"
+        raise ArgumentError, "succeeded results cannot carry failure metadata" unless failure.nil?
+      else
+        raise ArgumentError, "non-succeeded results require failure metadata" if failure.nil?
+        unless failure["code"] == execution_status
+          raise ArgumentError, "failure code must match execution status"
+        end
+      end
+    end
+
+    def validate_invocation(invocation)
+      raise ArgumentError, "invocation must be a Hash" unless invocation.is_a?(Hash)
+
+      executable = invocation["executable"]
+      argv = invocation["argv"]
+      unless executable.is_a?(String) && !executable.empty? && executable.bytesize <= 1024
+        raise ArgumentError, "invocation.executable must be a non-empty string"
+      end
+      unless argv.is_a?(Array) && argv.all? { |element| element.is_a?(String) && element.bytesize <= 4096 }
+        raise ArgumentError, "invocation.argv must be an array of strings"
+      end
+
+      { "executable" => executable.dup.freeze, "argv" => argv.map(&:dup).map(&:freeze).freeze }.freeze
+    end
+
+    def validate_execution_status(value)
+      unless EXECUTION_STATUSES.include?(value)
+        raise ArgumentError, "execution_status must be one of #{EXECUTION_STATUSES.join(', ')}"
+      end
+
+      value
+    end
+
+    def validate_finding_ids(finding_ids)
+      unless finding_ids.is_a?(Array) &&
+             finding_ids.all? { |id| id.is_a?(String) && !id.empty? && id.bytesize <= 256 }
+        raise ArgumentError, "finding_ids must be an array of non-empty strings"
+      end
+
+      finding_ids.map { |id| id.dup.freeze }.freeze
+    end
+
+    def validate_failure(failure)
+      return nil if failure.nil?
+
+      raise ArgumentError, "failure must be a Hash" unless failure.is_a?(Hash)
+
+      code = failure["code"]
+      message = failure["message"]
+      unless FAILURE_CODES.include?(code)
+        raise ArgumentError, "failure.code must be one of #{FAILURE_CODES.join(', ')}"
+      end
+      unless message.is_a?(String) && !message.empty? && message.bytesize <= 4096
+        raise ArgumentError, "failure.message must be a non-empty string"
+      end
+
+      { "code" => code.freeze, "message" => message.dup.freeze }.freeze
+    end
+
+    def validate_evidence_summary(value)
+      return nil if value.nil?
+
+      raise ArgumentError, "evidence_summary must be a Hash" unless value.is_a?(Hash)
+      raise ArgumentError, "evidence_summary is too large" if value.keys.length > 30
+
+      value.each do |key, entry|
+        raise ArgumentError, "evidence_summary keys must be non-empty strings" unless key.is_a?(String) && !key.empty? && key.bytesize <= 128
+        if entry.is_a?(Hash) || entry.is_a?(Array)
+          raise ArgumentError, "evidence_summary values must be primitives" unless key.start_with?("changed_") || key == "files"
+        else
+          unless entry.is_a?(Integer) || entry.is_a?(Float) || entry.is_a?(String) || entry.nil? || entry == true || entry == false
+            raise ArgumentError, "evidence_summary values must be primitives"
+          end
+          if entry.is_a?(String) && entry.bytesize > 4096
+            raise ArgumentError, "evidence_summary string values too large"
+          end
+        end
+      end
+
+      value.dup.freeze
+    end
+
+    def require_nonempty_string(value, name, max_length)
+      unless value.is_a?(String) && !value.empty? && value.bytesize <= max_length
+        raise ArgumentError, "#{name} must be a non-empty string of at most #{max_length} bytes"
+      end
+
+      value
+    end
+  end
+end

data/lib/rail_verdict/contracts/finding.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module RailVerdict
+  class Finding
+    SCHEMA_VERSION = "1.0"
+    FINGERPRINT_PAYLOAD_SCHEMA = "https://railverdict.dev/fingerprint-payload/v1"
+    LEGACY_FINGERPRINT_PAYLOAD_SCHEMA = "https://railverdict.dev/fingerprint-payload/v0.1"
+    FINGERPRINT_PATTERN = /\Asha256:[0-9a-f]{64}\z/
+    LOCATION_PATH_PATTERN = %r{
+      \A
+      (?!/)
+      (?!.*\\)
+      (?!.*//)
+      (?!(?:\.{1,2})(?:/|\z))
+      (?!.* / (?:\.{1,2}) (?:/|\z))
+      [^\u0000-\u001f/]+
+      (?:/[^\u0000-\u001f/]+)*
+      \z
+    }x
+
+    ORIGINS = %w[deterministic runtime ai custom].freeze
+    SEVERITIES = %w[info low medium high critical].freeze
+    CONFIDENCES = %w[low medium high].freeze
+    STATES = %w[observed introduced existing resolved changed moved suppressed waived].freeze
+
+    attr_reader :id, :fingerprint, :origin, :analyzer, :rule_id, :category, :severity,
+                :confidence, :state, :evidence_ref, :location, :message
+
+    def self.fingerprint_for(analyzer:, rule_id:, path:, message:)
+      Fingerprint.hexdigest(analyzer: analyzer, rule_id: rule_id, path: path, message: message)
+    end
+
+    def self.id_for(fingerprint)
+      hex = fingerprint.delete_prefix("sha256:")
+      "rv:#{hex.slice(0, 20)}"
+    end
+
+    def initialize(fingerprint:, origin:, analyzer:, rule_id:, category:, severity:, confidence:,
+                   state:, evidence_ref:, location:, message:)
+      @fingerprint = require_match(fingerprint, FINGERPRINT_PATTERN, "fingerprint")
+      @origin = require_member(origin, ORIGINS, "origin")
+      @analyzer = require_nonempty(analyzer, "analyzer", 256)
+      @rule_id = require_nonempty(rule_id, "rule_id", 256)
+      @category = require_nonempty(category, "category", 256)
+      @severity = require_member(severity, SEVERITIES, "severity")
+      @confidence = require_member(confidence, CONFIDENCES, "confidence")
+      @state = require_member(state, STATES, "state")
+      @evidence_ref = require_nonempty(evidence_ref, "evidence_ref", 512)
+      @location = validate_location(location)
+      @message = require_nonempty(message, "message", 4096)
+      @id = Finding.id_for(@fingerprint).freeze
+      @location.freeze
+      @analyzer.freeze
+      @rule_id.freeze
+      @category.freeze
+      @evidence_ref.freeze
+      @message.freeze
+      freeze
+    end
+
+    def schema_version
+      SCHEMA_VERSION
+    end
+
+    def sort_key
+      [
+        location.fetch("path").to_s,
+        location["start_line"] || -1,
+        location["end_line"] || -1,
+        analyzer,
+        rule_id,
+        fingerprint,
+        id
+      ]
+    end
+
+    def to_schema_h
+      {
+        "schema_version" => SCHEMA_VERSION,
+        "id" => id,
+        "fingerprint" => fingerprint,
+        "origin" => origin,
+        "analyzer" => analyzer,
+        "rule_id" => rule_id,
+        "category" => category,
+        "severity" => severity,
+        "confidence" => confidence,
+        "state" => state,
+        "evidence_ref" => evidence_ref,
+        "location" => location,
+        "message" => message
+      }
+    end
+
+    private
+
+    def require_match(value, pattern, name)
+      raise ArgumentError, "#{name} is invalid" unless value.is_a?(String) && value.match?(pattern)
+
+      value.frozen? ? value : value.dup.freeze
+    end
+
+    def require_member(value, allowed, name)
+      raise ArgumentError, "#{name} must be one of #{allowed.join(', ')}" unless allowed.include?(value)
+
+      value
+    end
+
+    def require_nonempty(value, name, max_length)
+      unless value.is_a?(String) && value.valid_encoding? && !value.empty? && value.bytesize <= max_length
+        raise ArgumentError, "#{name} must be a non-empty string of at most #{max_length} bytes"
+      end
+
+      value
+    end
+
+    def validate_location(location)
+      raise ArgumentError, "location must be a Hash" unless location.is_a?(Hash)
+
+      unknown = location.keys - %w[path start_line end_line]
+      raise ArgumentError, "location contains unknown fields: #{unknown.join(', ')}" unless unknown.empty?
+
+      path = location.fetch("path") do
+        raise ArgumentError, "location requires a path"
+      end
+      unless path.is_a?(String) && path.valid_encoding? && path.match?(LOCATION_PATH_PATTERN)
+        raise ArgumentError, "location.path must be a clean repository-relative path"
+      end
+
+      result = { "path" => path.dup.freeze }
+      start_line = location["start_line"]
+      end_line = location["end_line"]
+      result["start_line"] = validate_line(start_line, "start_line") unless start_line.nil?
+      result["end_line"] = validate_line(end_line, "end_line") unless end_line.nil?
+
+      if !start_line.nil? && !end_line.nil? && end_line < start_line
+        raise ArgumentError, "location end_line cannot precede start_line"
+      end
+
+      result
+    end
+
+    def validate_line(value, name)
+      unless value.is_a?(Integer) && value >= 1
+        raise ArgumentError, "location #{name} must be an integer >= 1"
+      end
+
+      value
+    end
+  end
+end

data/lib/rail_verdict/contracts/gate_result.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  class GateResult
+    SCHEMA_VERSION = "1.0"
+    COMPLETION_STATUSES = %w[complete incomplete interrupted].freeze
+    GATES = %w[PASS WARN FAIL INCOMPLETE].freeze
+    POLICY_STATUSES = %w[pass warn fail not_evaluated].freeze
+    FAILURE_CODES = %w[
+      unavailable unsupported timed_out signaled failed parse_failed truncated
+      malformed configuration interrupted incomplete_evidence
+    ].freeze
+
+    attr_reader :completion_status, :gate, :policy_status, :findings,
+                :analyzer_results, :operational_failures, :decision_reasons
+
+    def initialize(completion_status:, gate:, policy_status:, findings:, analyzer_results:,
+                    operational_failures:, decision_reasons:, baseline: nil, comparison: nil, git: nil, rails_context: nil)
+      @completion_status = require_member(completion_status, COMPLETION_STATUSES, "completion_status")
+      @gate = require_member(gate, GATES, "gate")
+      @policy_status = require_member(policy_status, POLICY_STATUSES, "policy_status")
+      @findings = validate_findings(findings)
+      @analyzer_results = validate_analyzer_results(analyzer_results)
+      @operational_failures = validate_operational_failures(operational_failures)
+      @decision_reasons = validate_decision_reasons(decision_reasons)
+      @baseline = baseline ? baseline.dup.freeze : nil
+      @comparison = comparison ? comparison.dup.freeze : nil
+      @git = git ? deep_freeze_git(git) : nil
+      @rails_context = rails_context ? deep_freeze_git(rails_context) : nil
+      enforce_state_coupling
+      freeze
+    end
+
+    def baseline
+      @baseline
+    end
+
+    def comparison
+      @comparison
+    end
+
+    def git
+      @git
+    end
+
+    def rails_context
+      @rails_context
+    end
+
+    def complete?
+      completion_status == "complete"
+    end
+
+    def incomplete?
+      completion_status != "complete"
+    end
+
+    def to_schema_h
+      result = {
+        "schema_version" => SCHEMA_VERSION,
+        "completion_status" => completion_status,
+        "gate" => gate,
+        "policy_status" => policy_status,
+        "findings" => findings,
+        "analyzer_results" => analyzer_results.map(&:to_schema_h),
+        "operational_failures" => operational_failures,
+        "decision_reasons" => decision_reasons
+      }
+      result["baseline"] = @baseline if @baseline
+      result["comparison"] = @comparison if @comparison
+      result["git"] = @git if @git
+      result["rails_context"] = @rails_context if @rails_context
+      result
+    end
+
+    def deep_freeze_git(value)
+      case value
+      when Hash
+        value.each do |key, child|
+          key.freeze if key.is_a?(String)
+          deep_freeze_git(child)
+        end
+        value.freeze
+      when Array
+        value.each { |child| deep_freeze_git(child) }
+        value.freeze
+      when String
+        value.freeze
+      else
+        value
+      end
+      value
+    end
+    private :deep_freeze_git
+
+    private
+
+    def require_member(value, allowed, name)
+      raise ArgumentError, "#{name} must be one of #{allowed.join(', ')}" unless allowed.include?(value)
+
+      value
+    end
+
+    def enforce_state_coupling
+      if completion_status == "complete"
+        unless %w[PASS WARN FAIL].include?(gate) && %w[pass warn fail].include?(policy_status)
+          raise ArgumentError, "complete result must contain a completed gate and policy status"
+        end
+      elsif gate != "INCOMPLETE" || policy_status != "not_evaluated" || operational_failures.empty?
+        raise ArgumentError, "incomplete result must be INCOMPLETE, not_evaluated, and explain a failure"
+      end
+    end
+
+    def validate_findings(findings)
+      unless findings.is_a?(Array)
+        raise ArgumentError, "findings must be an array"
+      end
+
+      findings.map do |finding|
+        raise ArgumentError, "finding summary must be a Hash" unless finding.is_a?(Hash)
+
+        expected = %w[id fingerprint severity state blocking]
+        raise ArgumentError, "finding summary contains unknown fields" unless finding.keys == expected
+        raise ArgumentError, "finding summary id is invalid" unless finding["id"].is_a?(String) && !finding["id"].empty?
+        raise ArgumentError, "finding summary fingerprint is invalid" unless finding["fingerprint"].match?(/\Asha256:[0-9a-f]{64}\z/)
+        raise ArgumentError, "finding summary severity is invalid" unless Finding::SEVERITIES.include?(finding["severity"])
+        raise ArgumentError, "finding summary state is invalid" unless Finding::STATES.include?(finding["state"])
+        raise ArgumentError, "finding summary blocking must be boolean" unless [true, false].include?(finding["blocking"])
+
+        finding.dup.freeze
+      end.freeze
+    end
+
+    def validate_analyzer_results(results)
+      raise ArgumentError, "analyzer_results must be an array" unless results.is_a?(Array)
+      raise ArgumentError, "analyzer_results must contain AnalyzerResult values" unless results.all? { |result| result.is_a?(AnalyzerResult) }
+
+      results.sort_by(&:analyzer).freeze
+    end
+
+    def validate_operational_failures(failures)
+      raise ArgumentError, "operational_failures must be an array" unless failures.is_a?(Array)
+
+      failures.map do |failure|
+        raise ArgumentError, "operational failure must be a Hash" unless failure.is_a?(Hash)
+        allowed = %w[code analyzer message]
+        raise ArgumentError, "operational failure contains unknown fields" unless (failure.keys - allowed).empty?
+        raise ArgumentError, "operational failure has invalid code" unless FAILURE_CODES.include?(failure["code"])
+        raise ArgumentError, "operational failure requires a message" unless failure["message"].is_a?(String) && !failure["message"].empty?
+        if failure.key?("analyzer") && !failure["analyzer"].is_a?(String)
+          raise ArgumentError, "operational failure analyzer must be a string"
+        end
+
+        failure.dup.freeze
+      end.freeze
+    end
+
+    def validate_decision_reasons(reasons)
+      raise ArgumentError, "decision_reasons must be an array" unless reasons.is_a?(Array)
+
+      reasons.map do |reason|
+        raise ArgumentError, "decision reason must be a Hash" unless reason.is_a?(Hash)
+        raise ArgumentError, "decision reason fields are invalid" unless reason.keys == %w[code message]
+        raise ArgumentError, "decision reason code is invalid" unless reason["code"].is_a?(String) && !reason["code"].empty?
+        raise ArgumentError, "decision reason message is invalid" unless reason["message"].is_a?(String) && !reason["message"].empty?
+
+        reason.dup.freeze
+      end.freeze
+    end
+  end
+end

data/lib/rail_verdict/coverage/changed_line_evaluator.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  module Coverage
+    module ChangedLineEvaluator
+      module_function
+
+      def evaluate(coverage_document:, line_set:)
+        raise ArgumentError, "coverage_document must be a Hash" unless coverage_document.is_a?(Hash)
+        raise ArgumentError, "line_set must be a Hash" unless line_set.is_a?(Hash)
+
+        files = coverage_document["files"]
+        raise ArgumentError, "coverage document has no files array" unless files.is_a?(Array)
+
+        coverage_map = {}
+        files.each do |file|
+          filename = file["filename"]
+          coverage = file.dig("coverage", "lines")
+          next unless filename.is_a?(String) && coverage.is_a?(Array)
+
+          coverage_map[filename] = coverage
+        end
+
+        executable = 0
+        covered = 0
+        missing = []
+
+        line_set.each do |path, lines|
+          raise ArgumentError, "line_set path must be a string" unless path.is_a?(String)
+          raise ArgumentError, "line_set lines must be an array" unless lines.is_a?(Array)
+
+          coverage = coverage_map[path]
+          lines.each do |line_number|
+            raise ArgumentError, "line number must be an integer >= 1" unless line_number.is_a?(Integer) && line_number >= 1
+
+            if coverage.nil? || line_number > coverage.length
+              executable += 1
+              missing << [path, line_number]
+              next
+            end
+
+            hit = coverage[line_number - 1]
+            if hit.nil?
+              next
+            end
+
+            executable += 1
+            if hit.to_i > 0
+              covered += 1
+            else
+              missing << [path, line_number]
+            end
+          end
+        end
+
+        missing = missing.sort
+
+        percent = executable == 0 ? 100.0 : ((covered.to_f / executable) * 100).round(2)
+
+        {
+          "covered_lines" => covered,
+          "executable_lines" => executable,
+          "missing_lines" => missing,
+          "percent" => percent,
+          "paths" => line_set.keys.sort
+        }.freeze
+      end
+    end
+  end
+end