reanimator 0.1.0

data/lib/reanimator/contract_snapshot.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Reanimator
+  # A comparable, serializable picture of what a repository was required to
+  # prove at a point in time. Configuration drift (specification section 06) is
+  # a comparison between two of these: the contract as it was last recorded,
+  # and the contract the current evidence resolves to.
+  #
+  # It deliberately captures more than the contract alone. "A removed security
+  # gate" and "a narrowed runtime matrix" are the section 06 examples of a
+  # policy change, and both live in discovered evidence rather than in the
+  # declared file, so the snapshot carries them too.
+  class ContractSnapshot
+    # `taken_at` is normalized to an ISO-8601 string on the way in: a snapshot
+    # exists to be written down and read back, so the moment it records reads
+    # the same whether it was just taken or loaded from a file.
+    attr_reader :repository, :origin, :intent, :profile, :security_posture, :autonomy,
+      :protected_paths, :criteria, :waivers, :support_matrix, :security_controls, :taken_at
+
+    def initialize(repository:, intent:, profile:, security_posture:, autonomy: {},
+      protected_paths: [], criteria: [], waivers: [], support_matrix: [],
+      security_controls: [], origin: nil, taken_at: nil)
+      @repository = immutable(repository)
+      @origin = immutable(origin)
+      @intent = intent
+      @profile = profile
+      @security_posture = security_posture
+      @autonomy = immutable(autonomy)
+      @protected_paths = immutable(protected_paths)
+      @criteria = immutable(criteria)
+      @waivers = immutable(waivers)
+      @support_matrix = immutable(support_matrix)
+      @security_controls = immutable(security_controls)
+      @taken_at = taken_at.is_a?(Time) ? taken_at.iso8601 : taken_at
+      freeze
+    end
+
+    # A snapshot records what was true at a moment, so it must not be editable
+    # afterwards - and `freeze` alone does not achieve that, because it leaves
+    # the recorded arrays and hashes writable. Copies are frozen rather than
+    # the caller's own collections, so recording a contract never freezes the
+    # live contract.
+    def immutable(value)
+      case value
+      when Hash then value.transform_values { |entry| immutable(entry) }.freeze
+      when Array then value.map { |entry| immutable(entry) }.freeze
+      when String then value.frozen? ? value : value.dup.freeze
+      else value
+      end
+    end
+    private :immutable
+
+    # @param contract [EffectiveContract]
+    # @return [ContractSnapshot]
+    def self.of(contract, taken_at: Time.now)
+      discovery = contract.discovery
+
+      new(
+        repository: contract.repository.full_name,
+        origin: Git.origin_url(contract.repository.path),
+        intent: contract.intent.to_sym,
+        profile: contract.profile.id,
+        security_posture: contract.security_posture.to_sym,
+        autonomy: contract.autonomy,
+        protected_paths: contract.protected_paths,
+        criteria: contract.criteria.map { |criterion| record_criterion(criterion) },
+        waivers: contract.waivers.map { |waiver| record_waiver(waiver) },
+        support_matrix: discovered_matrix(discovery),
+        security_controls: discovered_controls(discovery),
+        taken_at: taken_at
+      )
+    end
+
+    def self.record_criterion(criterion)
+      {id: criterion.id, evaluator: criterion.evaluator, run: criterion.run, required: criterion.required?}
+    end
+    private_class_method :record_criterion
+
+    def self.record_waiver(waiver)
+      {target: waiver.target, expires: waiver.expires&.iso8601}
+    end
+    private_class_method :record_waiver
+
+    # What CI actually exercises, falling back to what the project declares.
+    def self.discovered_matrix(discovery)
+      return [] unless discovery
+
+      Array(discovery.value(:ci_ruby_matrix) || discovery.value(:supported_ruby)).map(&:to_s)
+    end
+    private_class_method :discovered_matrix
+
+    def self.discovered_controls(discovery)
+      return [] unless discovery
+
+      discovery.in_category(:security_controls).map(&:key).sort
+    end
+    private_class_method :discovered_controls
+
+    # Rebuilds a snapshot from its serialized form, tolerating the string keys
+    # a JSON round-trip produces.
+    def self.from_h(hash)
+      data = symbolize(hash)
+      unless data.is_a?(Hash) && data.key?(:repository)
+        raise ContractError,
+          "That is not a contract snapshot; expected the JSON object written by `reanimator drift --save`."
+      end
+
+      new(
+        repository: data[:repository],
+        origin: data[:origin],
+        intent: data[:intent]&.to_sym,
+        profile: data[:profile]&.to_sym,
+        security_posture: data[:security_posture]&.to_sym,
+        autonomy: (data[:autonomy] || {}).transform_values(&:to_sym),
+        protected_paths: Array(data[:protected_paths]).map(&:to_s),
+        criteria: Array(data[:criteria]).map { |criterion| restore_criterion(criterion) },
+        waivers: Array(data[:waivers]).map { |waiver| restore_waiver(waiver) },
+        support_matrix: Array(data[:support_matrix]).map(&:to_s),
+        security_controls: Array(data[:security_controls]).map(&:to_sym),
+        taken_at: data[:taken_at]
+      )
+    end
+
+    def self.restore_criterion(criterion)
+      {
+        id: criterion[:id]&.to_sym, evaluator: criterion[:evaluator]&.to_sym,
+        run: criterion[:run], required: criterion[:required]
+      }
+    end
+    private_class_method :restore_criterion
+
+    def self.restore_waiver(waiver)
+      {target: waiver[:target]&.to_sym, expires: waiver[:expires]}
+    end
+    private_class_method :restore_waiver
+
+    def self.load(path)
+      from_h(JSON.parse(File.read(path, encoding: "UTF-8")))
+    rescue JSON::ParserError => e
+      raise ContractError, "#{path} is not a valid contract snapshot: #{e.message}"
+    rescue Errno::ENOENT
+      raise ContractError, "No contract snapshot at #{path}."
+    rescue SystemCallError => e
+      raise ContractError, "Could not read the contract snapshot at #{path}: #{e.message}"
+    end
+
+    def self.symbolize(value)
+      case value
+      when Hash then value.each_with_object({}) { |(k, v), h| h[k.to_sym] = symbolize(v) }
+      when Array then value.map { |v| symbolize(v) }
+      else value
+      end
+    end
+    private_class_method :symbolize
+
+    # The criterion recorded under an id, or nil.
+    def criterion(id)
+      criteria.find { |c| c[:id] == id }
+    end
+
+    def criterion_ids = criteria.map { |c| c[:id] }
+
+    # Whether a recorded criterion was blocking. Asked rather than dug out of
+    # the criterion hash, so callers never have to know its shape.
+    def requires?(id) = criterion(id)&.fetch(:required, false) == true
+
+    def waiver_targets = waivers.map { |w| w[:target] }
+
+    # When accepted risk for a target runs out, or nil for open-ended.
+    def waiver_expiry(target)
+      waivers.find { |waiver| waiver[:target] == target }&.[](:expires)
+    end
+
+    def to_h
+      {
+        repository: repository, origin: origin,
+        taken_at: taken_at,
+        intent: intent, profile: profile, security_posture: security_posture,
+        autonomy: autonomy, protected_paths: protected_paths, criteria: criteria,
+        waivers: waivers, support_matrix: support_matrix, security_controls: security_controls
+      }
+    end
+
+    def to_json(*args) = JSON.pretty_generate(to_h, *args)
+  end
+end

data/lib/reanimator/criteria_stack.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # Assembles the acceptance criteria for one repository out of the layers
+  # allowed to contribute them (specification section 07). Three layers speak:
+  # the vitality profile's defaults, the security posture's obligations, and
+  # the owner's declared checks. They are *merged*, not concatenated, so a
+  # layer naming an existing criterion id replaces it rather than arguing with
+  # it twice in the same report - and the owner's declaration wins.
+  #
+  # This is deliberately not part of {EffectivePolicyResolver}: resolving the
+  # precedence stack and assembling the list of things to prove change for
+  # different reasons, and adding a fourth layer should not mean reopening the
+  # resolver.
+  class CriteriaStack
+    def initialize(profile:, posture:, discovery:, declared:)
+      @profile = profile
+      @posture = posture
+      @discovery = discovery
+      @declared = declared
+    end
+
+    # @return [Array<AcceptanceCriterion>]
+    def resolve
+      merge(profile_criteria, security_criteria, declared_criteria)
+    end
+
+    private
+
+    attr_reader :profile, :posture, :discovery, :declared
+
+    # Keeps each criterion in the position it first appeared, so reports stay
+    # stable, while the last layer to claim an id supplies the criterion.
+    def merge(*layers)
+      layers.flatten.each_with_object({}) { |criterion, merged| merged[criterion.id] = criterion }.values
+    end
+
+    # Profile criteria, with discovered commands substituted in for the
+    # matching defaults (section 00: reuse detected checks; surface missing
+    # proof).
+    def profile_criteria
+      commands = discovery.discovered_commands
+      profile.resolved_criteria.map do |criterion|
+        run = commands[criterion.id]
+        run ? with_run(criterion, run) : criterion
+      end
+    end
+
+    def with_run(criterion, run)
+      AcceptanceCriterion.new(
+        id: criterion.id, claim: criterion.claim, evaluator: criterion.evaluator,
+        run: run, target: criterion.target, required: criterion.required,
+        scope: criterion.scope, freshness: criterion.freshness, owner: criterion.owner,
+        risk_class: criterion.risk_class,
+        provenance: discovery.command_fact(criterion.id)&.provenance
+      )
+    end
+
+    # The security evidence the posture makes binding (section 12). These are
+    # policy-owned rather than profile-owned: how much security proof a
+    # repository must show is a posture decision, not a question of what shape
+    # the project happens to be.
+    def security_criteria
+      posture.obligations.map do |control_id, required|
+        control = SecurityControl.fetch(control_id)
+        AcceptanceCriterion.new(
+          id: control.criterion_id, claim: control.claim,
+          evaluator: :security_evidence, target: control.to_s,
+          required: required, owner: "policy"
+        )
+      end
+    end
+
+    # Owner-declared acceptance checks become criteria owned by the repository.
+    # A criterion that edits CI/verifier surfaces is elevated by policy.
+    def declared_criteria
+      checks = declared&.acceptance&.dig(:checks) || []
+      checks.map do |check|
+        AcceptanceCriterion.new(
+          id: check[:id] || "declared-#{check.object_id}",
+          claim: check[:claim] || "Owner-declared check #{check[:id]}.",
+          evaluator: check[:evaluator] || :command,
+          run: check[:run], target: check[:target],
+          required: check.fetch(:required, true),
+          owner: "repository",
+          risk_class: check[:risk_class] || :normal
+        )
+      end
+    end
+  end
+end

data/lib/reanimator/criterion_result.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # The outcome of evaluating one acceptance criterion during a baseline. Its
+  # status is drawn from the vocabulary section 14 requires a baseline to
+  # separate: verified claims, failed claims, missing evidence, skipped
+  # boundaries, and accepted risks - plus "planned" for the read-only,
+  # non-executing default.
+  class CriterionResult
+    STATUSES = %i[verified failed missing_evidence skipped accepted_risk planned error].freeze
+
+    attr_reader :criterion, :status, :detail, :evidence, :duration
+
+    def initialize(criterion:, status:, detail: nil, evidence: nil, duration: nil)
+      @criterion = criterion
+      @status = status.to_sym
+      unless STATUSES.include?(@status)
+        raise UnknownError, "Unknown criterion result status #{status.inspect}."
+      end
+      @detail = detail
+      @evidence = evidence
+      @duration = duration
+    end
+
+    def verified? = status == :verified
+
+    def failed? = status == :failed
+
+    # A required criterion whose failure has been explicitly accepted via a
+    # waiver: not verified, but not blocking either.
+    def accepted_risk? = status == :accepted_risk
+
+    # Whether this result contributes proof (a verified required criterion).
+    def proven? = verified?
+
+    # Whether the criterion is still unproven: no evidence either way yet.
+    # An evaluator that errored belongs here too - "we could not tell" is not
+    # proof, and leaving it out would let a broken check read as green.
+    def unproven? = %i[missing_evidence planned skipped error].include?(status)
+
+    def required? = criterion.required?
+
+    # Whether this result is eligible to be waived: a required obligation that
+    # is not proven and has not already been accepted.
+    def waivable? = required? && !verified? && !accepted_risk?
+
+    # A copy of this result recorded as accepted risk under the given waiver.
+    # The criterion is still not verified - its failure is explicitly accepted.
+    #
+    # @param waiver [Waiver]
+    # @return [CriterionResult]
+    def accepted_via(waiver)
+      CriterionResult.new(
+        criterion: criterion, status: :accepted_risk,
+        detail: waiver.acceptance_of(self), evidence: evidence, duration: duration
+      )
+    end
+
+    def to_h
+      {
+        id: criterion.id,
+        claim: criterion.claim,
+        required: criterion.required?,
+        status: status,
+        detail: detail,
+        duration: duration
+      }.compact
+    end
+  end
+end

data/lib/reanimator/detectors/base.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Detectors
+    # Base class for every detector. A detector reads a repository through the
+    # read-only helpers on {Repository} and returns an array of
+    # {DiscoveredFact}s, each carrying its own provenance and confidence. It
+    # never decides policy - it only proposes facts for a human to confirm.
+    class Base
+      # @return [Repository]
+      attr_reader :repository
+
+      def initialize(repository)
+        @repository = repository
+      end
+
+      # @return [Array<DiscoveredFact>]
+      def call
+        detect
+      end
+
+      # @return [Array<DiscoveredFact>]
+      def detect
+        raise NotImplementedError, "#{self.class} must implement #detect"
+      end
+
+      private
+
+      # Builds a discovered fact with a provenance record in one call - the
+      # shape every detector uses.
+      def fact(key, category:, claim:, source:, method:, value: true, confidence: :medium, detail: nil)
+        DiscoveredFact.new(
+          key: key,
+          category: category,
+          claim: claim,
+          value: value,
+          confidence: confidence,
+          provenance: Provenance.new(source: source, method: method, detail: detail)
+        )
+      end
+
+      # Convenience: the first repository-relative path matching any of the
+      # given globs, or nil.
+      def first_path(*patterns)
+        patterns.flat_map { |pattern| repository.glob(pattern) }.first
+      end
+    end
+  end
+end

data/lib/reanimator/detectors/bundler.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Detectors
+    # Detects the Ruby/Bundler ecosystem and the supported-runtime matrix
+    # (specification section 06: Ecosystem and Support matrix). Evidence is the
+    # presence of a Gemfile, a lockfile, and any runtime pin - .ruby-version,
+    # a gemspec `required_ruby_version`, or a Gemfile `ruby` directive.
+    class Bundler < Base
+      RUBY_VERSION_PIN = /required_ruby_version\s*=?\s*['"]?([^'"]+)['"]?/
+      GEMFILE_RUBY = /^\s*ruby\s+['"]([^'"]+)['"]/
+
+      # A single declared runtime version paired with the file it came from.
+      Pin = Struct.new(:version, :source)
+
+      def detect
+        return [] unless repository.exist?("Gemfile") || repository.any?("*.gemspec")
+
+        facts = [
+          fact(:bundler, category: :ecosystem,
+            claim: "Managed with Bundler.",
+            confidence: :high, source: gemfile_or_gemspec, method: :file_present)
+        ]
+
+        if repository.exist?("Gemfile.lock")
+          facts << fact(:locked_dependencies, category: :ecosystem,
+            claim: "Dependencies are locked (Gemfile.lock present).",
+            confidence: :high, source: "Gemfile.lock", method: :file_present)
+        end
+
+        pins = runtime_pins
+        unless pins.empty?
+          versions = pins.map(&:version)
+          facts << fact(:supported_ruby, category: :support_matrix,
+            claim: "Declared Ruby support: #{versions.join(", ")}.",
+            value: versions, confidence: :medium,
+            source: pins.first.source, method: :version_pin, detail: versions.join(", "))
+        end
+
+        facts
+      end
+
+      private
+
+      def gemfile_or_gemspec
+        repository.exist?("Gemfile") ? "Gemfile" : first_path("*.gemspec")
+      end
+
+      # @return [Array<Pin>] de-duplicated runtime pins, strongest source first
+      def runtime_pins
+        pins = []
+
+        if (rv = repository.read(".ruby-version"))
+          pins << Pin.new(rv.strip, ".ruby-version")
+        end
+        if (gemspec = first_path("*.gemspec")) && (body = repository.read(gemspec)) &&
+            (m = body.match(RUBY_VERSION_PIN))
+          pins << Pin.new(m[1].strip, gemspec)
+        end
+        if (gemfile = repository.read("Gemfile")) && (m = gemfile.match(GEMFILE_RUBY))
+          pins << Pin.new(m[1].strip, "Gemfile")
+        end
+
+        pins.uniq(&:version)
+      end
+    end
+  end
+end

data/lib/reanimator/detectors/commands.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Detectors
+    # Discovers the commands a repository already uses to prove itself
+    # (specification section 06: Commands). The point is that users should
+    # "confirm facts rather than transcribe their own CI" - so this detector
+    # reads Rakefiles, lint configuration, gemspecs, and package.json scripts
+    # and reports the install/test/lint/build commands it finds. Each command
+    # fact later overrides the matching profile default (section 00: reuse
+    # detected checks; surface missing proof).
+    class Commands < Base
+      def detect
+        [
+          dependencies_command,
+          test_command,
+          lint_command,
+          build_command,
+          assets_command
+        ].compact
+      end
+
+      private
+
+      def dependencies_command
+        return unless repository.exist?("Gemfile")
+
+        command(:dependencies_command, "bundle check",
+          claim: "Dependency resolution is verified with `bundle check`.",
+          source: "Gemfile")
+      end
+
+      def test_command
+        if rspec?
+          command(:test_command, "bundle exec rspec",
+            claim: "Tests run with RSpec.", source: rspec_source, confidence: :high)
+        elsif repository.exist?("test") || repository.any?("test/**/*_test.rb")
+          command(:test_command, "bundle exec rake test",
+            claim: "Tests run with the default rake test task.", source: "test/")
+        elsif (script = package_script("test"))
+          command(:test_command, script,
+            claim: "Tests run via the package.json test script.", source: "package.json")
+        end
+      end
+
+      def lint_command
+        if repository.exist?(".standard.yml") || gemfile_mentions?("standard")
+          command(:lint_command, "bundle exec standardrb",
+            claim: "Lint runs with Standard.", source: standard_source, confidence: :high)
+        elsif repository.exist?(".rubocop.yml")
+          command(:lint_command, "bundle exec rubocop",
+            claim: "Lint runs with RuboCop.", source: ".rubocop.yml", confidence: :high)
+        end
+      end
+
+      def build_command
+        gemspec = first_path("*.gemspec")
+        return unless gemspec
+
+        command(:build_command, "gem build #{gemspec}",
+          claim: "Gem builds with `gem build`.", source: gemspec, confidence: :high)
+      end
+
+      def assets_command
+        script = package_script("build")
+        return unless script
+
+        command(:assets_command, script,
+          claim: "Assets build via the package.json build script.", source: "package.json")
+      end
+
+      # --- helpers -------------------------------------------------------------
+
+      def command(key, value, claim:, source:, confidence: :medium)
+        fact(key, category: :commands, claim: claim, value: value,
+          confidence: confidence, source: source, method: :command_inference, detail: value)
+      end
+
+      def rspec?
+        repository.exist?(".rspec") || repository.exist?("spec") || repository.any?("spec/**/*_spec.rb")
+      end
+
+      def rspec_source
+        repository.exist?(".rspec") ? ".rspec" : "spec/"
+      end
+
+      def standard_source
+        repository.exist?(".standard.yml") ? ".standard.yml" : "Gemfile"
+      end
+
+      def gemfile_mentions?(gem)
+        body = repository.read("Gemfile").to_s + repository.read("Gemfile.lock").to_s
+        body.include?(gem)
+      end
+
+      def package_script(name)
+        body = repository.read("package.json")
+        return unless body
+
+        require "json"
+        scripts = JSON.parse(body).fetch("scripts", {})
+        script = scripts[name]
+        return unless script
+
+        # Prefer the yarn/npm indirection so the discovered command is portable.
+        repository.exist?("yarn.lock") ? "yarn #{name}" : "npm run #{name}"
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/reanimator/detectors/fork.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Detectors
+    # Detects that a repository is a fork and, when possible, its upstream
+    # (specification section 04 cohorts and section 10 relationships). A fork
+    # is classified differently from an active original - it may be upstream
+    # observation, divergence monitoring, or a candidate to retire - so knowing
+    # the fork relationship early shapes the entire onboarding default.
+    class Fork < Base
+      def detect
+        upstream = Git.capture(repository.path, "config", "--get", "remote.upstream.url")
+        return [] unless repository.fork? || upstream
+
+        upstream_name = RepositoryMetadata.full_name_from_url(upstream)
+        claim = upstream_name ? "A fork of #{upstream_name}." : "A fork with a configured upstream remote."
+
+        [fact(:fork_of, category: :relationships,
+          claim: claim, value: upstream_name, confidence: :high,
+          source: upstream ? "remote.upstream" : "git metadata", method: :git_metadata,
+          detail: upstream_name)]
+      end
+    end
+  end
+end

data/lib/reanimator/detectors/github_actions.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Detectors
+    # Reads .github/workflows/*.yml for the evidence CI already provides
+    # (specification section 06: Commands, Support matrix, Security controls,
+    # Operational proof). Reanimator's job is to surface what a maintainer
+    # has already proven, so a project with a Ruby matrix and a
+    # dependency-review action should never be asked to re-declare either.
+    class GitHubActions < Base
+      # Action fingerprints -> the security control they demonstrate.
+      SECURITY_ACTIONS = {
+        "actions/dependency-review-action" => "Dependency review",
+        "github/codeql-action" => "CodeQL SAST",
+        "gitleaks" => "Secret scanning (gitleaks)",
+        "trufflehog" => "Secret scanning (trufflehog)",
+        "brakeman" => "Brakeman SAST",
+        "bundler-audit" => "Bundler dependency audit",
+        "bundle audit" => "Bundler dependency audit"
+      }.freeze
+
+      RUBY_MATRIX = /ruby(?:-version)?\s*:\s*\[([^\]]+)\]/
+
+      def detect
+        workflows = repository.glob(".github/workflows/*.yml") + repository.glob(".github/workflows/*.yaml")
+        return [] if workflows.empty?
+
+        facts = [
+          fact(:ci_github_actions, category: :operational_proof,
+            claim: "Continuous integration runs on GitHub Actions.",
+            value: workflows, confidence: :high, source: workflows.first, method: :file_present)
+        ]
+
+        facts.concat(ruby_matrix_facts(workflows))
+        facts.concat(security_facts(workflows))
+        facts
+      end
+
+      private
+
+      def ruby_matrix_facts(workflows)
+        workflows.filter_map do |path|
+          body = repository.read(path)
+          next unless body && (m = body.match(RUBY_MATRIX))
+
+          versions = m[1].split(",").map { |v| v.strip.delete("\"'") }.reject(&:empty?)
+          next if versions.empty?
+
+          fact(:ci_ruby_matrix, category: :support_matrix,
+            claim: "CI exercises Ruby: #{versions.join(", ")}.",
+            value: versions, confidence: :high, source: path, method: :yaml_matrix, detail: versions.join(", "))
+        end
+      end
+
+      def security_facts(workflows)
+        text = workflows.map { |path| repository.read(path).to_s }.join("\n")
+        SECURITY_ACTIONS.filter_map do |marker, description|
+          next unless text.include?(marker)
+
+          key = description.downcase.gsub(/[^a-z]+/, "_").gsub(/\A_|_\z/, "")
+          fact(:"security_#{key}", category: :security_controls,
+            claim: "Security control present: #{description}.",
+            confidence: :high, source: ".github/workflows", method: :action_fingerprint, detail: marker)
+        end
+      end
+    end
+  end
+end