reanimator 0.1.0

data/lib/reanimator/drift_report.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # What changed between two contract snapshots, and which of those changes a
+  # human has to look at (specification section 06).
+  #
+  # The distinction the specification insists on is not "big" versus "small" -
+  # it is *policy* versus *benign*. A renamed test command is benign: the
+  # obligation is unchanged, only its spelling moved. A removed security gate
+  # or a narrowed runtime matrix is a policy change: less is being proven than
+  # before, and nobody necessarily decided that on purpose. Drift detection
+  # earns its keep by never burying the second kind in a list of the first.
+  class DriftReport
+    # A single difference between two snapshots, carrying the verdict that
+    # judged it - a severity and the sentence justifying that severity - so no
+    # caller has to re-derive the judgement in order to display it. The verdict
+    # arrives whole and is kept whole: a severity can never be paired with the
+    # reasoning for a different one.
+    class Change
+      attr_reader :subject, :kind, :from, :to, :verdict
+
+      def initialize(subject:, kind:, verdict:, from: nil, to: nil)
+        @subject = subject
+        @kind = kind
+        @verdict = verdict
+        @from = from
+        @to = to
+        freeze
+      end
+
+      def severity = verdict.severity
+
+      def explanation = verdict.explanation
+
+      def policy? = severity == :policy
+
+      def benign? = severity == :benign
+
+      # A single line naming the difference.
+      def summary
+        case kind
+        when :added then "#{subject} added: #{to}"
+        when :removed then "#{subject} removed: #{from}"
+        else "#{subject}: #{from} → #{to}"
+        end
+      end
+
+      def to_h
+        {subject: subject, kind: kind, from: from, to: to, severity: severity, explanation: explanation}
+      end
+    end
+
+    attr_reader :repository, :previous, :current, :changes
+
+    def initialize(repository:, previous:, current:, changes:)
+      @repository = repository
+      @previous = previous
+      @current = current
+      @changes = changes
+      freeze
+    end
+
+    def policy_changes = changes.select(&:policy?)
+
+    def benign_changes = changes.select(&:benign?)
+
+    def drifted? = changes.any?
+
+    # Whether a human has to look. Benign drift is reported but does not
+    # demand attention; policy drift always does.
+    def requires_review? = policy_changes.any?
+
+    def since = previous.taken_at
+
+    def to_h
+      {
+        repository: repository,
+        since: since,
+        drifted: drifted?,
+        requires_review: requires_review?,
+        policy_changes: policy_changes.map(&:to_h),
+        benign_changes: benign_changes.map(&:to_h)
+      }
+    end
+  end
+end

data/lib/reanimator/effective_contract.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Reanimator
+  # The fully resolved combination of policy layers plus accepted discoveries
+  # (specification section 02): exactly what Reanimator must prove for one
+  # repository. It is what the contract-review UI shows, what the baseline
+  # runs, and what every run is versioned against. It knows how to render
+  # itself back into a minimal, round-trippable .reanimator.yml.
+  class EffectiveContract
+    attr_reader :repository, :intent, :profile, :criteria, :discovery,
+      :security_posture, :autonomy, :protected_paths, :waivers, :notes,
+      :profile_source, :intent_confirmed
+
+    def initialize(repository:, intent:, profile:, criteria:, discovery:,
+      security_posture:, autonomy:, protected_paths:, profile_source:,
+      intent_confirmed:, waivers: [], notes: [])
+      @repository = repository
+      @intent = intent
+      @profile = profile
+      @criteria = criteria
+      @discovery = discovery
+      @security_posture = security_posture
+      @autonomy = autonomy
+      @protected_paths = protected_paths
+      @waivers = waivers
+      @profile_source = profile_source
+      @intent_confirmed = intent_confirmed
+      @notes = notes
+    end
+
+    # The active waiver accepting a criterion's risk, or nil. Expired waivers
+    # never apply (fail closed).
+    def waiver_for(criterion_id, now: Time.now)
+      waivers.find { |waiver| waiver.covers?(criterion_id) && waiver.active?(now: now) }
+    end
+
+    def intent_confirmed? = @intent_confirmed
+
+    # @return [Array<AcceptanceCriterion>] criteria whose failure blocks
+    def required_criteria = criteria.select(&:required?)
+
+    # @return [Array<AcceptanceCriterion>] non-blocking criteria
+    def optional_criteria = criteria.reject(&:required?)
+
+    # Criteria that touch verifier definitions or protected contract surfaces
+    # and therefore always receive elevated review (section 09).
+    def verifier_criteria = criteria.select(&:elevated?)
+
+    # A short, stable fingerprint of the materialized contract, so each run can
+    # be attributed to the exact policy it was measured against (section 17:
+    # "version the effective contract used for each run").
+    def policy_version
+      @policy_version ||= "#{profile.id}@#{Digest::SHA256.hexdigest(canonical.to_s)[0, 12]}"
+    end
+
+    # The minimal, owner-facing declaration. This is the target for ordinary
+    # configuration (section 05): one lifecycle decision and one profile.
+    def to_minimal_hash
+      {version: ContractFile::CURRENT_VERSION, intent: intent.to_sym, profile: profile.id}
+    end
+
+    # The fuller contract hash used for advanced export. Must round-trip
+    # through {ContractFile} without semantic loss (section 07).
+    def to_contract_hash
+      to_minimal_hash.merge(
+        acceptance: {
+          checks: criteria.map { |c| c.to_h.slice(:id, :evaluator, :run, :target, :required).compact }
+        },
+        security: {posture: security_posture.to_sym},
+        autonomy: autonomy,
+        protected_paths: protected_paths
+      )
+    end
+
+    def to_h
+      {
+        repository: repository.full_name,
+        intent: intent.to_sym,
+        intent_confirmed: intent_confirmed?,
+        profile: profile.id,
+        profile_source: profile_source,
+        security_posture: security_posture.to_sym,
+        autonomy: autonomy,
+        protected_paths: protected_paths,
+        policy_version: policy_version,
+        criteria: criteria.map(&:to_h),
+        notes: notes
+      }
+    end
+
+    private
+
+    # The subset that defines the contract's identity for fingerprinting.
+    def canonical
+      {
+        intent: intent.to_sym,
+        profile: profile.id,
+        posture: security_posture.to_sym,
+        autonomy: autonomy,
+        protected: protected_paths.sort,
+        criteria: criteria.map { |c| [c.id, c.evaluator, c.run, c.required] }.sort_by(&:first),
+        waivers: waivers.map { |w| [w.target, w.expires&.iso8601] }.sort_by(&:first)
+      }
+    end
+  end
+end

data/lib/reanimator/effective_policy_resolver.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # Materializes an {EffectiveContract} from the precedence stack in section
+  # 07. For this read-only slice the layers that participate are the product
+  # safety floor (non-bypassable), the repository contract (owner declarations
+  # in .reanimator.yml), and runtime discovery (detected commands and
+  # metadata, which may never authorize weaker behavior by itself). Higher
+  # organization/portfolio/family layers plug in at the same seam later.
+  #
+  # Two rules are enforced here, not merely documented:
+  #   * an owner declaration wins over inference, but
+  #   * neither an owner declaration nor discovery may loosen the safety floor.
+  class EffectivePolicyResolver
+    # v1 autonomy defaults (section 20): observe and diagnose on; repair and
+    # submit opt-in; merge off.
+    DEFAULT_AUTONOMY = {
+      observe: :automatic,
+      diagnose: :automatic,
+      repair: :disabled,
+      submit: :disabled,
+      merge: :disabled
+    }.freeze
+
+    attr_reader :repository, :discovery
+
+    def initialize(repository, discovery: nil)
+      @repository = repository
+      @discovery = discovery || Discovery.new(repository).run
+    end
+
+    # @return [EffectiveContract]
+    def resolve
+      intent, intent_confirmed = resolve_intent
+      profile, profile_source = resolve_profile(intent)
+      autonomy, autonomy_notes = SafetyFloor.clamp_autonomy(resolve_autonomy)
+      posture = resolve_security_posture
+
+      EffectiveContract.new(
+        repository: repository,
+        intent: intent,
+        intent_confirmed: intent_confirmed,
+        profile: profile,
+        profile_source: profile_source,
+        criteria: CriteriaStack.new(
+          profile: profile, posture: posture, discovery: discovery, declared: declared
+        ).resolve,
+        discovery: discovery,
+        security_posture: posture,
+        autonomy: autonomy,
+        protected_paths: SafetyFloor.protected_paths(declared_protected_paths),
+        waivers: build_waivers,
+        notes: autonomy_notes
+      )
+    end
+
+    private
+
+    def declared = repository.declared
+
+    # Assigned intent wins, then a declared one, then a provisional suggestion
+    # from the classifier. Only the first two count as "confirmed".
+    def resolve_intent
+      if repository.intent
+        [LifecycleIntent.fetch(repository.intent), true]
+      elsif declared&.intent
+        [LifecycleIntent.fetch(declared.intent), true]
+      else
+        suggestion = Classifier.new(repository, discovery: discovery).classify
+        [LifecycleIntent.fetch(suggestion.suggested_intent), false]
+      end
+    end
+
+    # A declared profile always wins over inference (section 06). When the
+    # inferred profile is rails-app but the intent is to preserve, the
+    # historical variant is the better fit.
+    def resolve_profile(intent)
+      if declared&.profile
+        [Profiles.fetch(declared.profile), :declared]
+      else
+        id = discovery.suggested_profile
+        id = :"rails-legacy" if id == :"rails-app" && intent.to_sym == :preserve
+        [Profiles.fetch(id), :inferred]
+      end
+    end
+
+    def declared_protected_paths
+      declared&.acceptance&.dig(:protected_paths) || []
+    end
+
+    # Owner-declared waivers become accepted-risk exceptions on the contract.
+    def build_waivers
+      (declared&.waivers || []).map do |waiver|
+        Waiver.new(
+          target: waiver[:target] || waiver[:id],
+          reason: waiver[:reason].to_s,
+          owner: waiver[:owner] || "repository",
+          scope: waiver[:scope] || {},
+          expires: waiver[:expires]
+        )
+      end
+    end
+
+    def resolve_autonomy
+      declared_autonomy = declared&.autonomy || {}
+      DEFAULT_AUTONOMY.merge(declared_autonomy.transform_values(&:to_sym))
+    end
+
+    def resolve_security_posture
+      declared_posture = declared&.security&.dig(:posture)
+      return SecurityPosture[declared_posture] if declared_posture
+
+      SecurityPosture[Reanimator.configuration.security_posture]
+    end
+  end
+end

data/lib/reanimator/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # Base class for every error the library raises, so consumers can rescue the
+  # whole family with a single `rescue Reanimator::Error`.
+  class Error < StandardError; end
+
+  # Raised when a path is not a usable repository root.
+  class RepositoryError < Error; end
+
+  # Raised when a .reanimator.yml (or an inline contract) fails validation.
+  class ContractError < Error; end
+
+  # Raised when a requested profile, intent, or evaluator is not registered.
+  class UnknownError < Error; end
+
+  # Raised when a policy layer attempts to loosen a constraint it may not
+  # loosen - the precedence rules in section 07 of the specification are not
+  # advisory, they are enforced.
+  class PolicyViolation < Error; end
+end

data/lib/reanimator/evaluators/base.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Evaluators
+    # Shared plumbing for evaluators. Subclasses implement {#call} and return a
+    # {CriterionResult}. The evaluator sees the repository and discovery only
+    # through the read-only effective contract - it never receives, and cannot
+    # reach, a mutable agent workspace.
+    class Base
+      attr_reader :criterion, :contract, :execute, :timeout, :execution_root
+
+      def initialize(criterion, contract:, execute:, timeout:, execution_root: nil)
+        @criterion = criterion
+        @contract = contract
+        @execute = execute
+        @timeout = timeout
+        @execution_root = execution_root || contract.repository.path
+      end
+
+      # @return [CriterionResult]
+      def call
+        raise NotImplementedError, "#{self.class} must implement #call"
+      end
+
+      private
+
+      def repository = contract.repository
+
+      def discovery = contract.discovery
+
+      def result(status, detail: nil, evidence: nil, duration: nil)
+        CriterionResult.new(
+          criterion: criterion, status: status, detail: detail, evidence: evidence, duration: duration
+        )
+      end
+
+      # Keep only the tail of noisy command output as retained evidence.
+      def tail(text, limit: 1_500)
+        stripped = text.to_s.strip
+        return stripped if stripped.length <= limit
+
+        "...#{stripped[-limit..]}"
+      end
+    end
+
+    # Fallback for a criterion whose evaluator is not available in the
+    # read-only baseline (for example a hosted GitHub check). It is honest
+    # about the gap rather than guessing.
+    class Unsupported < Base
+      def call
+        result(:skipped, detail: "Evaluator #{criterion.evaluator.inspect} is not available in a read-only baseline.")
+      end
+    end
+  end
+end

data/lib/reanimator/evaluators/command.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Evaluators
+    # Runs a discovered or declared shell command and grades it by exit status.
+    # In the default (non-executing) mode it reports what it *would* run, so a
+    # user can see the plan before granting execution. When execution is
+    # enabled the command is bounded by a hard timeout.
+    class Command < Base
+      def call
+        return result(:missing_evidence, detail: "No command discovered for this check.") unless criterion.run
+
+        unless execute
+          return result(:planned, detail: "Would run: #{criterion.run}")
+        end
+
+        outcome = BoundedCommand.run(criterion.run, chdir: execution_root, timeout: timeout)
+        grade(outcome)
+      end
+
+      private
+
+      def grade(outcome)
+        if outcome.timed_out?
+          result(:failed, detail: "Timed out after #{timeout}s: #{criterion.run}", duration: outcome.duration)
+        elsif outcome.success?
+          result(:verified, detail: criterion.run, evidence: tail(outcome.output), duration: outcome.duration)
+        else
+          result(:failed, detail: "Nonzero exit: #{criterion.run}", evidence: tail(outcome.output), duration: outcome.duration)
+        end
+      end
+    end
+  end
+end

data/lib/reanimator/evaluators/documentation_check.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Evaluators
+    # A native evaluator that checks for the presence of documentation the
+    # criterion names (README, LICENSE, or any target prefix). Cheap, read-only,
+    # and always runnable - it backs the "reproduction-documented" and
+    # "documented/licensed" criteria without executing anything.
+    class DocumentationCheck < Base
+      KNOWN = {"README" => "README*", "LICENSE" => "LICENSE*"}.freeze
+
+      def call
+        target = criterion.target || "README"
+        pattern = KNOWN.fetch(target, "#{target}*")
+        matches = repository.glob(pattern)
+
+        if matches.any?
+          result(:verified, detail: "Found #{matches.first}.")
+        else
+          result(:missing_evidence, detail: "No #{target} found.")
+        end
+      end
+    end
+  end
+end

data/lib/reanimator/evaluators/http_smoke.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Evaluators
+    # A boot smoke test against a health endpoint. Actually booting a service
+    # requires a running environment the read-only baseline deliberately does
+    # not provision, so this evaluator records the gap honestly - the criterion
+    # is a real, valuable proof-of-life check, it is simply not yet established.
+    # This is exactly the "production boot proof not established" gap Appendix A
+    # reports as Unproven rather than green.
+    class HttpSmoke < Base
+      def call
+        result(:missing_evidence,
+          detail: "Boot smoke against #{criterion.target || "the health endpoint"} needs a running " \
+                  "service; not established in a read-only baseline.")
+      end
+    end
+  end
+end

data/lib/reanimator/evaluators/repository_integrity.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Evaluators
+    # A native evaluator for preserve/legacy repositories: attests that source
+    # remains readable with intact history. It only inspects git metadata, so
+    # it runs even in the non-executing baseline - a preserved artifact can be
+    # proven readable without running a single line of its code.
+    class RepositoryIntegrity < Base
+      def call
+        metadata = repository.metadata
+        if metadata.has_git?
+          result(:verified,
+            detail: "Git history is intact (#{metadata.commit_count || "unknown"} commits, " \
+                    "last activity #{metadata.last_activity&.strftime("%Y-%m-%d") || "unknown"}).")
+        else
+          result(:missing_evidence, detail: "No git history found; source integrity cannot be attested.")
+        end
+      end
+    end
+  end
+end

data/lib/reanimator/evaluators/security_evidence.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Evaluators
+    # A native evaluator that grades one security control from discovered
+    # evidence (specification section 12). It never asks a repository to adopt
+    # a particular tool - any of the control's accepted fingerprints counts -
+    # and a control with no evidence is reported as missing rather than
+    # quietly passed, which is the whole point of making the posture binding.
+    class SecurityEvidence < Base
+      def call
+        control = SecurityControl.fetch(criterion.target)
+        evidence = control.evidence_in(discovery)
+        return result(:missing_evidence, detail: control.remedy) unless evidence
+
+        result(:verified, detail: evidence.claim, evidence: evidence.provenance.to_s)
+      rescue UnknownError => e
+        # A contract naming a control we do not know is a misconfiguration, not
+        # a pass: say so, and let the unproven rules keep the repository honest.
+        result(:error, detail: e.message)
+      end
+    end
+  end
+end

data/lib/reanimator/evaluators/support_matrix.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Evaluators
+    # A native evaluator that compares declared runtime support against what CI
+    # actually exercises. This is the classic escalation from section 16: "the
+    # project declares Ruby 3.2 support, but CI no longer tests it." Declared
+    # support with no CI coverage is missing evidence, not a pass.
+    class SupportMatrix < Base
+      def call
+        ci = discovery[:ci_ruby_matrix]
+        declared = discovery[:supported_ruby]
+
+        if ci
+          result(:verified, detail: "CI exercises Ruby #{Array(ci.value).join(", ")}.")
+        elsif declared
+          result(:missing_evidence,
+            detail: "Ruby #{Array(declared.value).join(", ")} is declared but not exercised in CI.")
+        else
+          result(:skipped, detail: "No declared runtime support matrix to verify.")
+        end
+      end
+    end
+  end
+end

data/lib/reanimator/evaluators.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # Evaluators turn an acceptance criterion into a {CriterionResult}. They are
+  # the isolated grading half of section 09: the thing that decides pass or
+  # fail is deliberately separate from anything that could edit the repository.
+  #
+  # Two families live here. *Native* evaluators (repository integrity,
+  # documentation, support matrix, security evidence) read only inspection
+  # data and always run,
+  # even in the non-executing default - that is how a read-only baseline can
+  # still prove something. *Command* and *smoke* evaluators represent work that
+  # must actually execute, so they only run when a baseline is explicitly asked
+  # to execute.
+  module Evaluators
+    module_function
+
+    # @param criterion [AcceptanceCriterion]
+    # @param contract [EffectiveContract]
+    # @param execute [Boolean]
+    # @param timeout [Integer]
+    # @param execution_root [String] directory commands run in - a disposable
+    #   copy when executing, so the original working tree is never touched
+    # @return [Evaluators::Base]
+    def for(criterion, contract:, execute:, timeout:, execution_root: contract.repository.path)
+      klass = registry.fetch(criterion.evaluator, Unsupported)
+      klass.new(criterion, contract: contract, execute: execute, timeout: timeout, execution_root: execution_root)
+    end
+
+    def registry
+      {
+        command: Command,
+        http_smoke: HttpSmoke,
+        repository_integrity: RepositoryIntegrity,
+        documentation_check: DocumentationCheck,
+        support_matrix: SupportMatrix,
+        security_evidence: SecurityEvidence
+      }
+    end
+  end
+end

data/lib/reanimator/family/gate.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Reanimator
+  class Family
+    # A cross-repository requirement (specification section 10 family policy):
+    # when the `on` member is a candidate for change, a check in another member
+    # must pass. Family policy may *add* evidence like this, but it can never
+    # weaken a member repository's own security constraints.
+    #
+    # A gate with no explicit check falls back to the downstream member's own
+    # proof command (a smoke script, else its discovered test command), so an
+    # inferred family is useful without anyone writing YAML.
+    class Gate
+      # @return [String] the member whose change triggers this gate
+      attr_reader :on
+      # @return [String] the member that must prove itself
+      attr_reader :requires_repository
+      # @return [String, nil] the command to run, or nil to use the member's own
+      attr_reader :check
+
+      def initialize(on:, requires_repository:, check: nil)
+        @on = on
+        @requires_repository = requires_repository
+        @check = check
+        freeze
+      end
+
+      # Whether the check command must be resolved from the downstream member.
+      def inferred_check? = check.nil?
+
+      def label
+        "#{on} requires #{check || "its own proof command"} in #{requires_repository}"
+      end
+
+      def to_h
+        {on: on, require: {repository: requires_repository, check: check}.compact}
+      end
+    end
+  end
+end

data/lib/reanimator/family/gate_result.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Reanimator
+  class Family
+    # The outcome of one cross-repository gate. Section 10 is explicit that
+    # "family failures identify the exact edge that broke, not merely the
+    # repository that ran CI", so a result carries the relationship it was
+    # proving, not just a repository name.
+    class GateResult
+      STATUSES = %i[verified failed missing_evidence planned skipped].freeze
+
+      attr_reader :gate, :relationship, :status, :detail, :duration
+
+      def initialize(gate:, status:, relationship: nil, detail: nil, duration: nil)
+        @gate = gate
+        @status = status.to_sym
+        unless STATUSES.include?(@status)
+          raise UnknownError, "Unknown gate result status #{status.inspect}."
+        end
+
+        @relationship = relationship
+        @detail = detail
+        @duration = duration
+      end
+
+      def verified? = status == :verified
+
+      def failed? = status == :failed
+
+      # Not proven yet: nothing ran, or no downstream proof exists.
+      def unresolved? = %i[missing_evidence planned skipped].include?(status)
+
+      # The exact edge this result speaks for.
+      def edge
+        relationship&.label || "#{gate.on} -> #{gate.requires_repository}"
+      end
+
+      def to_h
+        {
+          edge: edge, on: gate.on, requires: gate.requires_repository,
+          status: status, detail: detail, duration: duration
+        }.compact
+      end
+    end
+  end
+end