reanimator 0.1.0

data/lib/reanimator/safety_floor.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # The product safety floor (specification section 07): the non-bypassable
+  # bottom of the precedence stack. No layer above it - organization,
+  # portfolio, family, repository, or task - may loosen these. The floor is
+  # what makes the anti-gaming rule enforceable: "a task that modifies the
+  # rules of proof cannot use those modified rules to approve itself."
+  module SafetyFloor
+    # Paths that always receive elevated scrutiny because editing them can
+    # weaken a check, change who is trusted, or alter what "proof" means. A
+    # repository contract may *add* to this set but never remove from it.
+    PROTECTED_PATHS = [
+      ".reanimator.yml",
+      ".github/workflows/**",
+      ".github/dependabot.yml",
+      "CODEOWNERS",
+      ".github/CODEOWNERS"
+    ].freeze
+
+    # Merge is off in v1 regardless of what any layer requests (section 18:
+    # automatic merge is explicitly later).
+    MERGE_IN_V1 = :disabled
+
+    module_function
+
+    # The union of the floor's protected paths and any the contract declares.
+    # @param declared [Array<String>]
+    # @return [Array<String>]
+    def protected_paths(declared = [])
+      (PROTECTED_PATHS + Array(declared)).uniq
+    end
+
+    # Matches a repository-relative path against a glob, treating a trailing
+    # `**` as "this directory and everything under it, at any depth". Plain
+    # `File.fnmatch?` with FNM_PATHNAME does not let `**` cross `/`, which would
+    # leave `.github/workflows/nested/deploy.yml` unprotected - so the recursive
+    # form is expanded and tried as well.
+    #
+    # @param glob [String]
+    # @param path [String]
+    # @return [Boolean]
+    def matches?(glob, path)
+      flags = File::FNM_PATHNAME | File::FNM_EXTGLOB
+      return true if File.fnmatch?(glob, path, flags)
+
+      recursive = glob.sub(%r{/\*\*\z}, "/**/*")
+      recursive != glob && File.fnmatch?(recursive, path, flags)
+    end
+
+    # Whether any of the given globs protects the path.
+    def protects?(path, globs)
+      globs.any? { |glob| matches?(glob, path) }
+    end
+
+    # Clamps an autonomy map so it can never exceed the floor. Returns the
+    # clamped map plus a list of human-readable notes describing what was
+    # tightened, so the resolver can surface the clamp rather than hide it.
+    #
+    # @param autonomy [Hash]
+    # @return [Array(Hash, Array<String>)]
+    def clamp_autonomy(autonomy)
+      clamped = autonomy.dup
+      notes = []
+
+      if clamped[:merge] && clamped[:merge].to_sym != MERGE_IN_V1
+        notes << "Merge autonomy was requested but is disabled by the v1 safety floor."
+        clamped[:merge] = MERGE_IN_V1
+      end
+      clamped[:merge] ||= MERGE_IN_V1
+
+      [clamped, notes]
+    end
+
+    # Verifier isolation is always on: evaluation runs separately from any
+    # agent workspace, and an acting agent can never alter the effective
+    # contract, hidden tests, or baseline evidence during an ordinary repair
+    # (section 09). This is a constant, not a setting.
+    def verifier_isolation? = true
+  end
+end

data/lib/reanimator/security_control.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # A family of security evidence a posture can require (specification section
+  # 12). Controls are named by *obligation* rather than by tool: "dependency
+  # risk is reviewed" is satisfied by Dependabot, bundler-audit, or the
+  # dependency-review action alike, so a repository that already solved the
+  # problem its own way is credited rather than asked to adopt ours.
+  class SecurityControl
+    REGISTRY = {
+      dependency_review: {
+        claim: "Dependency risk is reviewed automatically.",
+        satisfied_by: %i[dependabot security_dependency_review security_bundler_dependency_audit].freeze,
+        remedy: "No dependency review found. Add .github/dependabot.yml, bundler-audit, or actions/dependency-review-action."
+      },
+      secret_scanning: {
+        claim: "Committed secrets are scanned for.",
+        satisfied_by: %i[security_secret_scanning_gitleaks security_secret_scanning_trufflehog].freeze,
+        remedy: "No secret scanning found. Add gitleaks or trufflehog to CI."
+      },
+      static_analysis: {
+        claim: "Source is scanned for known vulnerability patterns.",
+        satisfied_by: %i[security_codeql_sast security_brakeman_sast].freeze,
+        remedy: "No static analysis found. Add CodeQL or Brakeman to CI."
+      },
+      security_policy: {
+        claim: "A security policy says how to report a vulnerability.",
+        satisfied_by: %i[security_policy].freeze,
+        remedy: "No security policy found. Add SECURITY.md."
+      },
+      ownership: {
+        claim: "Ownership of protected paths is declared.",
+        satisfied_by: %i[codeowners].freeze,
+        remedy: "No ownership declaration found. Add CODEOWNERS."
+      }
+    }.freeze
+
+    attr_reader :id, :claim, :satisfied_by, :remedy
+
+    def initialize(id)
+      @id = id.to_sym
+      spec = REGISTRY.fetch(@id) do
+        raise UnknownError, "Unknown security control #{id.inspect}. Known: #{REGISTRY.keys.join(", ")}."
+      end
+      @claim = spec[:claim]
+      @satisfied_by = spec[:satisfied_by]
+      @remedy = spec[:remedy]
+      freeze
+    end
+
+    def self.fetch(id) = new(id)
+
+    def self.ids = REGISTRY.keys
+
+    def self.all = ids.map { |id| new(id) }
+
+    # How a set of controls reads in a report: their plain names, or "none" -
+    # so a posture that asks for nothing says so instead of trailing off.
+    def self.labels(ids)
+      return "none" if ids.empty?
+
+      ids.map { |id| fetch(id).label }.join(", ")
+    end
+
+    # The criterion id this control is graded under. The control owns its own
+    # naming so reports, waivers, and history cannot drift apart. Ids are
+    # already namespaced under "security-", so a control named for security
+    # drops the prefix rather than stuttering as security-security-policy.
+    def criterion_id = :"security-#{id.to_s.delete_prefix("security_").tr("_", "-")}"
+
+    # The first discovered fact that satisfies this control, or nil. Any one of
+    # several fingerprints counts: the obligation is what matters, not the tool.
+    #
+    # @param discovery [DiscoveryResult]
+    # @return [DiscoveredFact, nil]
+    def evidence_in(discovery)
+      satisfied_by.filter_map { |key| discovery[key] }.first
+    end
+
+    # Human-readable name for reports, e.g. "dependency review".
+    def label = id.to_s.tr("_", " ")
+
+    def to_sym = id
+
+    def to_s = id.to_s
+  end
+end

data/lib/reanimator/security_posture.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # The security posture presets from specification section 12. Security is
+  # part of onboarding, not a hidden settings page, so the posture is a
+  # first-class, named value with plain-language behavior - never a bundle of
+  # silent relaxations.
+  class SecurityPosture
+    PRESETS = {
+      strict: "Approved providers only, deny-by-default network and secrets, " \
+              "protected workflows, no auto-merge, enhanced review for verifier changes.",
+      balanced: "Approved package-registry network, hosted agents allowed, " \
+                "patch submission permitted, no major automatic repair.",
+      local: "Code and execution remain on user-controlled runners; external providers excluded.",
+      custom: "Explicit controls with no hidden relaxation from a preset."
+    }.freeze
+
+    # What each posture makes mandatory (section 12). The posture - not the
+    # project's shape - decides how much security proof a repository must show,
+    # so the same gem is advisory under :balanced and blocking under :strict.
+    # A control absent from a posture's map is not asked for at all.
+    #
+    # :local requires secret scanning because committed secrets are the one
+    # risk that does not care whether the runner is yours. :custom implies
+    # nothing: "no hidden relaxation from a preset" cuts both ways, so the
+    # owner declares the controls they want and Reanimator adds none.
+    OBLIGATIONS = {
+      strict: {
+        security_policy: true, dependency_review: true, secret_scanning: true,
+        static_analysis: false, ownership: false
+      },
+      balanced: {dependency_review: false, secret_scanning: false, security_policy: false},
+      local: {secret_scanning: true, dependency_review: false},
+      custom: {}
+    }.freeze
+
+    attr_reader :name
+
+    def initialize(name)
+      @name = name.to_sym
+      unless PRESETS.key?(@name)
+        raise UnknownError, "Unknown security posture #{name.inspect}. Known: #{PRESETS.keys.join(", ")}."
+      end
+      freeze
+    end
+
+    def self.[](name) = new(name)
+
+    # Section 20 v1 default: balanced for public repositories, strict for
+    # private repositories unless changed.
+    def self.default_for(visibility)
+      (visibility.to_s == "private") ? new(:strict) : new(:balanced)
+    end
+
+    def description = PRESETS.fetch(name)
+
+    # Network egress the posture permits by default.
+    def network
+      case name
+      when :strict, :local then :deny
+      when :balanced then :package_registries
+      else :custom
+      end
+    end
+
+    # @return [Hash{Symbol=>Boolean}] security control id => whether a missing
+    #   control blocks advancement under this posture
+    def obligations = OBLIGATIONS.fetch(name)
+
+    # @return [Array<Symbol>] controls whose absence blocks
+    def required_controls = obligations.select { |_, required| required }.keys
+
+    # @return [Array<Symbol>] controls reported but not blocking
+    def advisory_controls = obligations.reject { |_, required| required }.keys
+
+    def to_sym = name
+
+    def to_s = name.to_s
+  end
+end

data/lib/reanimator/snapshot_store.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Reanimator
+  # Where a repository's recorded contract snapshot lives - and the only place
+  # Reanimator ever writes one (specification section 06).
+  #
+  # There are two conventions, because drift has two shapes. A repository you
+  # own records its snapshot *inside itself*, as a committed file beside
+  # `.reanimator.yml`: the contract and the record of what it last required
+  # are the same kind of thing, and keeping both under review means a policy
+  # change arrives as a diff a human reads rather than as state hidden in a
+  # tool. A portfolio of repositories you cannot write into records them side
+  # by side in one directory instead, keyed by repository.
+  class SnapshotStore
+    DEFAULT_FILENAME = ".reanimator-snapshot.json"
+
+    # @return [String, nil] the portfolio-side directory, or nil when each
+    #   repository keeps its own committed snapshot
+    attr_reader :directory
+
+    def initialize(directory: nil)
+      @directory = directory
+    end
+
+    # @param repository [Repository]
+    # @return [String] where this repository's snapshot is read from and written to
+    def path_for(repository)
+      return File.join(repository.path, DEFAULT_FILENAME) unless directory
+
+      File.join(directory, "#{key_for(repository)}.json")
+    end
+
+    def recorded?(repository) = File.file?(path_for(repository))
+
+    # @param repository [Repository]
+    # @return [ContractSnapshot, nil] nil when nothing has been recorded yet
+    def load(repository)
+      recorded?(repository) ? ContractSnapshot.load(path_for(repository)) : nil
+    end
+
+    # @param snapshot [ContractSnapshot]
+    # @param repository [Repository]
+    # @return [String] the path written
+    def save(snapshot, repository)
+      destination = path_for(repository)
+      FileUtils.mkdir_p(directory) if directory
+      File.write(destination, snapshot.to_json)
+      destination
+    rescue SystemCallError => e
+      raise ContractError, "Could not write the contract snapshot to #{destination}: #{e.message}"
+    end
+
+    # The exact command a maintainer runs to re-record a snapshot, for a report
+    # to quote. The store is the one place that knows where snapshots live, so
+    # it is also the one place that knows how to say "put it back".
+    #
+    # @param file [String, nil] an explicitly named snapshot file, if the
+    #   maintainer bypassed the store with one
+    def record_command(file = nil)
+      return "reanimator drift --save #{file}" if file
+      return "reanimator drift --record --snapshots #{directory}" if directory
+
+      "reanimator drift --record"
+    end
+
+    private
+
+    # A repository's identity flattened into one filename. A collision is not a
+    # correctness risk: {DriftDetector} refuses to compare snapshots from two
+    # different repositories, so a mis-keyed file fails closed instead of
+    # reporting the most dangerous possible answer - "no drift".
+    def key_for(repository)
+      repository.full_name.to_s.gsub(/[^A-Za-z0-9._-]+/, "-")
+    end
+  end
+end

data/lib/reanimator/task_class.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # A category of maintenance work with a default autonomy posture per rung
+  # (specification section 11, "Default autonomy by task class"). The table is
+  # deliberately conservative: security remediation may repair and submit, but
+  # major upgrades only plan, verifier changes demand elevated review, and
+  # nothing merges automatically.
+  class TaskClass
+    # Per-rung default policy tokens used in the section 11 table.
+    #   :auto        run automatically
+    #   :allowed     permitted when the rung is enabled
+    #   :draft       permitted, but only as a draft PR
+    #   :draft_elevated  draft PR plus elevated review
+    #   :plan_only   may only produce a plan
+    #   :issue       may only open an issue
+    #   :optional    permitted but not default
+    #   :by_exception only when explicitly excepted
+    #   :off         not permitted
+    attr_reader :key, :title, :defaults, :elevated_review
+
+    def initialize(key:, title:, defaults:, elevated_review: false)
+      @key = key
+      @title = title
+      @defaults = defaults
+      @elevated_review = elevated_review
+      freeze
+    end
+
+    def elevated_review? = @elevated_review
+
+    def default_for(level) = defaults.fetch(level.to_sym, :off)
+
+    def self.fetch(key)
+      ALL.fetch(key.to_sym) { raise UnknownError, "Unknown task class #{key.inspect}. Known: #{ALL.keys.join(", ")}." }
+    end
+
+    def self.keys = ALL.keys
+
+    def self.build(key, title, observe:, diagnose:, repair:, submit:, merge:, elevated_review: false)
+      new(key: key, title: title, elevated_review: elevated_review,
+        defaults: {observe: observe, diagnose: diagnose, repair: repair, submit: submit, merge: merge})
+    end
+
+    ALL = {
+      critical_security: build(:critical_security, "Critical security remediation",
+        observe: :auto, diagnose: :auto, repair: :allowed, submit: :allowed, merge: :off),
+      patch_dependency: build(:patch_dependency, "Patch dependency update",
+        observe: :auto, diagnose: :auto, repair: :allowed, submit: :allowed, merge: :off),
+      minor_dependency: build(:minor_dependency, "Minor dependency update",
+        observe: :auto, diagnose: :auto, repair: :allowed, submit: :draft, merge: :off),
+      major_upgrade: build(:major_upgrade, "Major dependency or runtime update",
+        observe: :auto, diagnose: :auto, repair: :plan_only, submit: :issue, merge: :off),
+      mechanical_formatting: build(:mechanical_formatting, "Mechanical formatting",
+        observe: :auto, diagnose: :auto, repair: :optional, submit: :draft, merge: :off),
+      behavioral_refactor: build(:behavioral_refactor, "Behavioral refactor",
+        observe: :auto, diagnose: :auto, repair: :by_exception, submit: :draft, merge: :off),
+      verifier_modification: build(:verifier_modification, "CI or verifier modification",
+        observe: :auto, diagnose: :auto, repair: :by_exception, submit: :draft_elevated, merge: :off,
+        elevated_review: true)
+    }.freeze
+  end
+end

data/lib/reanimator/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Reanimator
+  VERSION = "0.1.0"
+end

data/lib/reanimator/vitality_profile.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # A reusable bundle of inferred or declared obligations for a common project
+  # shape - ruby-gem, rails-app, ruby-cli (specification section 02). A
+  # profile says what "healthy" *usually* looks like; it removes repetitive
+  # configuration without hiding the resulting contract. Profiles compose:
+  # rails-app inherits from web-application, and both resolve against the
+  # detected evidence of a specific repository.
+  class VitalityProfile
+    # @return [Symbol] stable profile id, e.g. :"ruby-gem"
+    attr_reader :id
+    # @return [String] one-line description
+    attr_reader :summary
+    # @return [Array<Symbol>] profiles this one inherits obligations from
+    attr_reader :inherits
+    # @return [Array<AcceptanceCriterion>] criteria contributed by this profile
+    attr_reader :criteria
+
+    def initialize(id:, summary:, inherits: [], criteria: [])
+      @id = id.to_sym
+      @summary = summary
+      @inherits = Array(inherits).map(&:to_sym)
+      @criteria = criteria
+      freeze
+    end
+
+    # The fully-resolved criteria for this profile, including inherited ones,
+    # de-duplicated by id with the most specific (this profile) winning.
+    #
+    # @param registry [#fetch] profile lookup, defaults to {Profiles}
+    # @return [Array<AcceptanceCriterion>]
+    def resolved_criteria(registry: Profiles)
+      inherited = inherits.flat_map { |parent| registry.fetch(parent).resolved_criteria(registry: registry) }
+      by_id = {}
+      (inherited + criteria).each { |c| by_id[c.id] = c }
+      by_id.values
+    end
+
+    def to_h
+      {id: id, summary: summary, inherits: inherits}
+    end
+  end
+end

data/lib/reanimator/waiver.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module Reanimator
+  # An explicit, scoped, attributable exception to an obligation (specification
+  # section 09). A waiver does not make a failing criterion pass - "a waived
+  # obligation is not counted as verified; it is counted as accepted risk". It
+  # is time-bounded when appropriate: past its expiry it stops applying and the
+  # obligation is blocking again (fail closed). A waiver always carries a
+  # rationale, so accepted risk is never anonymous.
+  class Waiver
+    # @return [Symbol] the acceptance-criterion id this waiver accepts
+    attr_reader :target
+    # @return [String] why the risk is accepted (required)
+    attr_reader :reason
+    # @return [String] who accepted it
+    attr_reader :owner
+    # @return [Hash] optional scope (environments, paths, family members)
+    attr_reader :scope
+    # @return [Time, nil] when the waiver stops applying, or nil for open-ended
+    attr_reader :expires
+
+    def initialize(target:, reason:, owner: "repository", scope: {}, expires: nil)
+      @target = target.to_sym
+      @reason = reason.to_s
+      @owner = owner
+      @scope = scope || {}
+      @expires = coerce_time(expires)
+      if @reason.strip.empty?
+        raise ContractError, "Waiver for #{target.inspect} needs a reason; accepted risk must be attributable."
+      end
+    end
+
+    # @param criterion_id [Symbol, String]
+    def covers?(criterion_id) = target == criterion_id.to_sym
+
+    # How this waiver reads on a result it accepts. The waiver owns its reason
+    # and bound, so it phrases its own acceptance rather than leaving callers
+    # to assemble the sentence.
+    #
+    # @param result [CriterionResult] the result being accepted
+    # @return [String]
+    def acceptance_of(result)
+      bound = expires ? " until #{expires.strftime("%Y-%m-%d")}" : ""
+      "Accepted risk#{bound}: #{reason} (was #{result.status})"
+    end
+
+    # Whether the waiver still applies at the given time.
+    def active?(now: Time.now) = expires.nil? || now < expires
+
+    def expired?(now: Time.now) = !active?(now: now)
+
+    def to_h
+      {target: target, reason: reason, owner: owner, expires: expires&.iso8601}.compact
+    end
+
+    private
+
+    # Accepts a Date or Time (from YAML) or a parseable string; nil means
+    # open-ended.
+    def coerce_time(value)
+      case value
+      when nil then nil
+      when Time then value
+      when Date then value.to_time
+      else Time.parse(value.to_s)
+      end
+    rescue ArgumentError
+      raise ContractError, "Waiver for #{target.inspect} has an invalid expires: #{value.inspect}."
+    end
+  end
+end