reanimator 0.1.0

data/lib/reanimator/baseline.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # A timestamped, read-only measurement of a repository's current obligations
+  # and pre-existing failures (specification sections 02 and 14). A baseline is
+  # the organism measured before any operation: it separates verified claims,
+  # failed claims, missing evidence, and skipped boundaries, and it carries the
+  # policy version it was measured against so later runs can detect genuine
+  # improvement or regression rather than noise.
+  class Baseline
+    attr_reader :contract, :results, :state, :generated_at, :executed
+
+    def initialize(contract:, results:, state:, generated_at:, executed:)
+      @contract = contract
+      @results = results
+      @state = state
+      @generated_at = generated_at
+      @executed = executed
+    end
+
+    # @return [Boolean] whether checks actually executed, versus were planned
+    def executed? = @executed
+
+    def repository = contract.repository
+
+    def policy_version = contract.policy_version
+
+    # Counts of each result status, e.g. {verified: 3, missing_evidence: 1}.
+    # @return [Hash{Symbol=>Integer}]
+    def tally
+      results.each_with_object(Hash.new(0)) { |r, h| h[r.status] += 1 }
+    end
+
+    def results_with_status(status)
+      results.select { |r| r.status == status.to_sym }
+    end
+
+    # Required criteria that failed - the actionable, blocking ones.
+    def failing_required
+      results.select { |r| r.required? && r.failed? }
+    end
+
+    # Required criteria that are neither verified nor accepted risk - the ones
+    # that genuinely still need attention (failed, missing, planned, skipped).
+    def unresolved_required
+      results.select { |r| r.required? && !r.verified? && !r.accepted_risk? }
+    end
+
+    # Required criteria whose failure has been explicitly waived - accepted
+    # risk, kept separate from verified vitality (section 15).
+    def accepted_risks
+      results.select(&:accepted_risk?)
+    end
+
+    # The first required criterion that failed, or nil - the natural repair
+    # target. Callers ask the baseline rather than digging through #results.
+    def first_failing_required_criterion
+      failing_required.first&.criterion
+    end
+
+    # The result for a criterion id, or nil.
+    def result_for(criterion_id)
+      results.find { |r| r.criterion.id == criterion_id }
+    end
+
+    # Ids of required criteria that are verified - the set a later run must not
+    # regress from.
+    def verified_required_ids
+      results.select { |r| r.required? && r.verified? }.map { |r| r.criterion.id }
+    end
+
+    # The required criteria the Verified Vitality Rate is measured over.
+    # Accepted risk is deliberately excluded so it is reported separately
+    # rather than counted as a failure (section 15).
+    def rated_required
+      results.select { |r| r.required? && !r.accepted_risk? }
+    end
+
+    # Verified Vitality Rate for active (required) obligations - the headline
+    # dashboard metric from section 15, kept separate from accepted risk.
+    # @return [Float] 0.0..1.0
+    def verified_vitality_rate
+      rated = rated_required
+      return 1.0 if rated.empty?
+
+      rated.count(&:verified?).to_f / rated.size
+    end
+
+    # A repository is proven when it is Alive with no failed or unproven
+    # required criteria.
+    def proven? = state.alive?
+
+    def to_h
+      {
+        repository: repository.full_name,
+        state: state.to_sym,
+        executed: executed?,
+        generated_at: generated_at.iso8601,
+        policy_version: policy_version,
+        verified_vitality_rate: verified_vitality_rate.round(3),
+        tally: tally,
+        results: results.map(&:to_h)
+      }
+    end
+  end
+end

data/lib/reanimator/baseline_runner.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Reanimator
+  # Executes a baseline for one repository against its effective contract
+  # (specification section 14). Every criterion is graded by an isolated
+  # evaluator; the runner itself never edits the repository. Execution is
+  # opt-in and doubly gated - by the per-run `execute` flag and by the global
+  # `allow_execution` configuration - so the default really is read-only, and
+  # even when executing, native (inspection-only) evaluators still run.
+  #
+  # When commands do execute, they run in a *disposable copy* of the repository,
+  # never the original working tree (section 14: "all commands run in a
+  # disposable workspace" and "the baseline is read-only with respect to
+  # repository source"). Inspection-only evaluators still read the original.
+  class BaselineRunner
+    attr_reader :contract, :execute, :timeout
+
+    def initialize(contract, execute: false, timeout: nil, now: nil)
+      @contract = contract
+      @execute = execute
+      @timeout = timeout || Reanimator.configuration.command_timeout
+      @now = now
+    end
+
+    # @return [Baseline]
+    def run
+      if execution_allowed?
+        # Commands run inside a throwaway copy so builds/tests cannot mutate the
+        # real checkout (no stray .gem, coverage/, or tmp/ artifacts).
+        Isolation.copy(contract.repository.path) { |workspace| measure(workspace) }
+      else
+        measure(contract.repository.path)
+      end
+    end
+
+    private
+
+    def measure(execution_root)
+      results = contract.criteria.map do |criterion|
+        Evaluators.for(
+          criterion, contract: contract, execute: execution_allowed?,
+          timeout: timeout, execution_root: execution_root
+        ).call
+      end
+      results = apply_waivers(results)
+
+      Baseline.new(
+        contract: contract,
+        results: results,
+        state: ProofOfLife.assess(contract, results),
+        generated_at: now,
+        executed: execution_allowed?
+      )
+    end
+
+    # Re-tags an unresolved required criterion as accepted risk when an active
+    # waiver covers it (section 09). The waiver does not make it verified - it
+    # records the failure as explicitly accepted, so it stops blocking the
+    # repository state while staying visible.
+    def apply_waivers(results)
+      results.map do |result|
+        next result unless result.waivable?
+
+        waiver = contract.waiver_for(result.criterion.id)
+        waiver ? result.accepted_via(waiver) : result
+      end
+    end
+
+    # Execution requires both the per-run request and the global allowance.
+    # Native evaluators ignore this flag and always inspect.
+    def execution_allowed?
+      execute && Reanimator.configuration.allow_execution
+    end
+
+    def now
+      @now || Time.now
+    end
+  end
+end

data/lib/reanimator/bounded_command.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "open3"
+require "timeout"
+
+module Reanimator
+  # Runs a single shell command under a hard wall-clock bound and captures its
+  # combined output (specification section 12: bounded attempts, time, and
+  # paths). Baselines are bounded by construction - a check that hangs is a
+  # failed check, never an unbounded wait. The command runs through `sh -c` so
+  # discovered commands with globs (for example `gem build *.gemspec`) behave as
+  # they do in CI.
+  #
+  # The child is started as its own process-group leader and, on timeout, the
+  # *entire group* is signalled - not just the `sh` parent - so a spawned
+  # grandchild (the actual test or build process) cannot outlive the bound.
+  module BoundedCommand
+    # Cap on captured output so a runaway producer cannot exhaust memory before
+    # the time bound fires. The pipe is still drained past the cap so the child
+    # never blocks on a full pipe; only accumulation stops.
+    MAX_OUTPUT_BYTES = 1 << 20 # 1 MiB
+    READ_CHUNK = 16_384
+
+    Result = Struct.new(:success, :output, :duration, :timed_out) do
+      def success? = success
+      def timed_out? = timed_out
+    end
+
+    module_function
+
+    # @param command [String]
+    # @param chdir [String]
+    # @param timeout [Integer] seconds
+    # @return [Result]
+    def run(command, chdir:, timeout:)
+      started = clock
+      stdin, out_and_err, wait_thread = Open3.popen2e("sh", "-c", command, chdir: chdir, pgroup: true)
+      stdin.close
+      out_and_err.binmode
+
+      output = +"".b
+      truncated = false
+      timed_out = false
+      begin
+        Timeout.timeout(timeout) do
+          while (chunk = out_and_err.read(READ_CHUNK))
+            if output.bytesize < MAX_OUTPUT_BYTES
+              output << chunk
+            else
+              truncated = true # keep draining, stop accumulating
+            end
+          end
+        end
+        wait_thread.join
+      rescue Timeout::Error
+        timed_out = true
+        kill_group(wait_thread.pid)
+        wait_thread.join # reap the terminated leader
+      ensure
+        out_and_err.close
+      end
+
+      output << "\n...[output truncated]" if truncated
+
+      Result.new(
+        success: !timed_out && wait_thread.value&.success?,
+        # Command output is untrusted bytes; present it as scrubbed UTF-8 so
+        # callers' string operations never raise.
+        output: output.force_encoding("UTF-8").scrub,
+        duration: (clock - started).round(2),
+        timed_out: timed_out
+      )
+    end
+
+    # Signals the whole process group led by pid (the negative-pid form), so
+    # every process the command spawned is terminated together.
+    def kill_group(pid)
+      Process.kill("TERM", -pid)
+      Process.kill("KILL", -pid)
+    rescue Errno::ESRCH, Errno::EPERM
+      # Already gone; nothing to clean up.
+    end
+
+    # Monotonic clock so a system time change cannot skew a duration.
+    def clock = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end

data/lib/reanimator/classifier.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # Assigns a repository to a triage cohort and a provisional lifecycle intent
+  # from read-only evidence (specification sections 04 and 05). The classifier
+  # is deliberately conservative: it flags ambiguity rather than assuming
+  # maintenance, and it never treats its own suggestion as final - intent must
+  # be confirmed before activation.
+  class Classifier
+    # Gems that imply a hardware- or credential-constrained environment.
+    HARDWARE_MARKERS = %w[rpi_gpio pi_piper serialport dino artoo denko wiringpi].freeze
+    RECENT_DAYS = 120
+    STALE_DAYS = 365
+    EXPERIMENT_COMMITS = 15
+
+    # The result of classification: the cohort, the intent it suggests, how
+    # confident that suggestion is, and why.
+    Classification = Struct.new(:cohort, :suggested_intent, :confidence, :reason) do
+      def recommended_for_onboarding? = cohort.recommended_for_onboarding?
+    end
+
+    attr_reader :repository, :discovery
+
+    def initialize(repository, discovery: nil)
+      @repository = repository
+      @discovery = discovery
+    end
+
+    # @return [Classification]
+    def classify
+      cohort_key, confidence, reason = decide
+      cohort = Cohort.fetch(cohort_key)
+      Classification.new(
+        cohort: cohort,
+        suggested_intent: cohort.default_intent,
+        confidence: Confidence[confidence],
+        reason: reason
+      )
+    end
+
+    private
+
+    def decide
+      metadata = repository.metadata
+
+      if repository.fork? || discovery&.fact?(:fork_of)
+        [:fork_observation, :high, "The repository is a fork; defaulting to upstream observation."]
+      elsif hardware?
+        [:constrained, :medium, "Hardware/credential-dependent gems detected; a constrained profile is safer."]
+      elsif metadata.archived?
+        [:archived, :high, "The repository is archived."]
+      elsif readme_only?
+        [:readme_only, :medium, "No recognized source language; looks like a concept or presentation."]
+      elsif stale?
+        [:old_unarchived, :medium, "No activity for over a year; intent is ambiguous rather than clearly maintained."]
+      elsif experiment?
+        [:recent_experiment, :medium, "Recent, low-commit repository; likely still an experiment."]
+      else
+        [:active_original, :high, "Active original repository with recognizable structure."]
+      end
+    end
+
+    def hardware?
+      body = repository.read("Gemfile").to_s + repository.read("Gemfile.lock").to_s
+      HARDWARE_MARKERS.any? { |marker| body.include?(marker) } ||
+        HARDWARE_MARKERS.any? { |marker| repository.name.include?(marker) }
+    end
+
+    def readme_only?
+      repository.metadata.primary_language.nil? &&
+        !repository.any?("*.gemspec") &&
+        !repository.exist?("package.json") &&
+        repository.any?("README*")
+    end
+
+    def stale?
+      days = repository.metadata.days_since_activity
+      days && days > STALE_DAYS
+    end
+
+    def experiment?
+      days = repository.metadata.days_since_activity
+      count = repository.metadata.commit_count
+      return false unless days && count
+
+      days <= RECENT_DAYS && count < EXPERIMENT_COMMITS
+    end
+  end
+end

data/lib/reanimator/cli.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+require "thor"
+require "json"
+
+module Reanimator
+  # The interactive surface. Every command here is read-only by default and
+  # maps to one onboarding stage from section 03: inventory (classify),
+  # discover, contract (review), and baseline (measure). Nothing in this CLI
+  # writes to a repository or connects an agent - it exists to make the
+  # repository's definition of life visible, executable, and trustworthy.
+  class CLI < Thor
+    def self.exit_on_failure? = true
+
+    desc "version", "Print the Reanimator version"
+    def version
+      puts Reanimator::VERSION
+    end
+    map %w[--version -v] => :version
+
+    desc "inventory [PATH...]", "Classify repositories into lifecycle cohorts (read-only)"
+    long_desc <<~DESC
+      Stage 1 of onboarding: classify before acting. Groups each repository into
+      a suggested cohort and lifecycle intent, and recommends a small,
+      high-confidence set for onboarding - never all of them.
+    DESC
+    def inventory(*paths)
+      guard do
+        paths = [Dir.pwd] if paths.empty?
+        puts Reports::Inventory.new(Reanimator.inventory(paths)).render
+      end
+    end
+
+    desc "discover [PATH]", "Show discovered facts and their provenance (read-only)"
+    def discover(path = Dir.pwd)
+      guard { puts Reports::Discovery.new(Reanimator.discover(path)).render }
+    end
+
+    desc "contract [PATH]", "Show or export the effective vitality contract"
+    option :intent, desc: "Override the inferred lifecycle intent (e.g. maintain, preserve)"
+    option :export, type: :boolean, default: false, desc: "Print a minimal .reanimator.yml instead of the review"
+    def contract(path = Dir.pwd)
+      guard do
+        contract = Reanimator.contract(path, intent: options[:intent]&.to_sym)
+        if options[:export]
+          puts ContractFile.dump(contract.to_minimal_hash)
+        else
+          puts Reports::Contract.new(contract).render
+        end
+      end
+    end
+
+    desc "baseline [PATH]", "Measure a read-only proof-of-life baseline"
+    long_desc <<~DESC
+      Runs the effective contract's acceptance criteria and reports a
+      proof-of-life state. Native checks (integrity, documentation, support
+      matrix) always run; command and boot checks only plan unless --execute is
+      given, and even then execution is bounded and never edits source.
+    DESC
+    option :execute, type: :boolean, default: false, desc: "Actually run discovered checks (bounded, read-only)"
+    option :intent, desc: "Override the inferred lifecycle intent"
+    option :format, default: "text", enum: %w[text check json], desc: "Output format"
+    def baseline(path = Dir.pwd)
+      guard do
+        baseline = Reanimator.baseline(path, execute: options[:execute], intent: options[:intent]&.to_sym)
+        puts render_baseline(baseline, options[:format])
+      end
+    end
+
+    desc "portfolio [PATH...]", "Baseline several repositories into one report (Appendix A)"
+    option :execute, type: :boolean, default: false, desc: "Actually run discovered checks (bounded, read-only)"
+    option :name, default: "portfolio", desc: "Portfolio name shown in the report header"
+    def portfolio(*paths)
+      guard do
+        paths = [Dir.pwd] if paths.empty?
+        baselines = paths.filter_map do |path|
+          Reanimator.baseline(path, execute: options[:execute])
+        rescue RepositoryError => e
+          warn "skipping #{path}: #{e.message}"
+          nil
+        end
+        puts Reports::PortfolioBaseline.new(baselines, name: options[:name]).render
+      end
+    end
+
+    desc "agents", "List coding-agent providers and whether each is available"
+    def agents
+      guard { puts Reports::Agents.new(Reanimator.adapters).render }
+    end
+
+    desc "commission", "Prove a coding agent is ready via a synthetic repair (no repository writes)"
+    long_desc <<~DESC
+      Stage 5 of onboarding. Runs the commissioning test from section 08: a
+      synthetic repair against a disposable fixture, graded independently by
+      Reanimator's own evaluators. The default local agent always runs; hosted
+      providers report themselves unavailable until connected.
+    DESC
+    option :provider, default: "local", desc: "Provider to commission (local, codex, claude, amp)"
+    def commission
+      guard do
+        report = Reanimator.commission(provider: options[:provider].to_sym)
+        puts Reports::Commissioning.new(report).render
+        exit 1 unless report.ready? || report.readiness == :unavailable
+      end
+    end
+
+    desc "repair [PATH]", "Attempt a bounded repair and propose a draft PR (no repository writes)"
+    long_desc <<~DESC
+      Stage toward bounded stewardship (section 11 repair rung). Finds the first
+      failing required criterion, checks the permission model, routes to a ready
+      agent, and lets it propose a patch in an isolated workspace. The patch is
+      applied only to a separate clean copy and re-verified independently; on
+      success a draft PR is materialized but NOT submitted. Nothing is written to
+      the repository.
+    DESC
+    option :provider, default: "local", desc: "Provider to use (local, codex, claude, amp)"
+    option :task_class, default: "patch_dependency", desc: "Task class governing autonomy"
+    def repair(path = Dir.pwd)
+      guard do
+        run = Reanimator.repair(path, provider: options[:provider].to_sym, task_class: options[:task_class].to_sym)
+        puts Reports::Run.new(run).render
+      end
+    end
+
+    desc "drift [PATH...]", "Record contract snapshots, or detect drift against them"
+    long_desc <<~DESC
+      Section 06. Configuration drift is the difference between the contract a
+      repository resolved to when it was last recorded and the one its evidence
+      resolves to now. Differences are separated into policy changes - less is
+      being proven than before, so a human should look - and benign ones, such
+      as a renamed test command. The exit status is non-zero only for a policy
+      change, so CI can gate on it.
+
+      A repository's snapshot normally lives in the repository, committed as
+      .reanimator-snapshot.json, so a policy change arrives as a diff in a
+      pull request rather than as state hidden in a tool; --record writes it
+      there. For repositories you cannot commit a file into, --snapshots DIR
+      keeps them side by side, keyed by repository. Pass several paths for a
+      portfolio triage list. With nothing recorded yet, shows what the
+      repository is currently required to prove. The only files Reanimator
+      ever writes are those snapshots, and only when asked.
+    DESC
+    option :since, desc: "Path to a recorded snapshot to compare against (one repository)"
+    option :save, desc: "Path to write the current snapshot to (one repository)"
+    option :snapshots, desc: "Directory of recorded snapshots, keyed by repository"
+    option :record, type: :boolean, default: false, desc: "Record each current snapshot where it belongs"
+    option :intent, desc: "Override the inferred lifecycle intent"
+    option :format, default: "text", enum: %w[text json], desc: "Output format"
+    def drift(*paths)
+      guard do
+        paths = [Dir.pwd] if paths.empty?
+        (paths.size > 1) ? portfolio_drift(paths) : single_drift(paths.first)
+      end
+    end
+
+    desc "permissions [PATH]", "Show resolved autonomy per task class for a repository"
+    option :intent, desc: "Override the inferred lifecycle intent"
+    def permissions(path = Dir.pwd)
+      guard do
+        contract = Reanimator.contract(path, intent: options[:intent]&.to_sym)
+        puts Reports::Permissions.new(contract).render
+      end
+    end
+
+    desc "families [PATH...]", "Show the compatibility graph: repositories that must stay alive together"
+    long_desc <<~DESC
+      Section 10. Groups related repositories into families from their structure -
+      a project and its examples, deployment samples, docs, or plugins - and shows
+      the typed edge between each pair plus the gate that proves it.
+    DESC
+    def families(*paths)
+      guard do
+        paths = [Dir.pwd] if paths.empty?
+        puts Reports::Families.new(Reanimator.families(paths)).render
+      end
+    end
+
+    desc "gates [PATH...]", "Evaluate cross-repository family gates (read-only)"
+    long_desc <<~DESC
+      Proves each family edge by running the downstream member's own check. A
+      candidate change upstream can trigger these downstream checks without
+      opening anything downstream: with --execute each check runs bounded, in a
+      disposable copy, never in the downstream working tree. A failure names the
+      exact edge that broke.
+    DESC
+    option :family, desc: "Limit to one family id"
+    option :execute, type: :boolean, default: false, desc: "Actually run downstream checks (bounded, read-only)"
+    def gates(*paths)
+      guard do
+        paths = [Dir.pwd] if paths.empty?
+        evaluated = Reanimator.family_gates(paths, family: options[:family], execute: options[:execute])
+        if evaluated.empty?
+          puts "No repository families detected."
+        else
+          puts evaluated.map { |family, results| Reports::FamilyGates.new(family, results).render }.join("\n\n")
+        end
+      end
+    end
+
+    private
+
+    # Several paths: a triage list across the portfolio, not one verdict.
+    def portfolio_drift(paths)
+      %w[since save].each do |single|
+        next unless options[single]
+
+        raise ContractError,
+          "--#{single} names one file, so it cannot be used with several repositories; use --snapshots DIR."
+      end
+
+      drift = Reanimator.portfolio_drift(
+        paths, snapshots: options[:snapshots], record: options[:record], intent: options[:intent]&.to_sym
+      )
+      puts((options[:format] == "json") ? JSON.pretty_generate(drift.to_h) : Reports::PortfolioDrift.new(drift).render)
+      exit 1 if drift.requires_review?
+    end
+
+    def single_drift(path)
+      store = SnapshotStore.new(directory: options[:snapshots])
+      repository = Repository.at(path)
+      snapshot = Reanimator.snapshot(path, intent: options[:intent]&.to_sym)
+      previous = options[:since] ? ContractSnapshot.load(options[:since]) : store.load(repository)
+      report = previous && DriftDetector.between(previous, snapshot)
+
+      recorded_to = record_snapshot(snapshot, repository, store)
+      puts render_drift(report, snapshot, recorded_to, store)
+      exit 1 if report&.requires_review?
+    end
+
+    # A snapshot is written only where the maintainer asked for it: --save names
+    # an exact file, --record puts it where the store says it belongs. Nothing
+    # is written without one of them - detecting drift is not licence to start
+    # writing files.
+    def record_snapshot(snapshot, repository, store)
+      return unless options[:save] || options[:record]
+
+      written = options[:save] ? save_snapshot(snapshot, options[:save]) : store.save(snapshot, repository)
+      warn "Recorded contract snapshot for #{snapshot.repository} → #{written}"
+      written
+    end
+
+    def render_drift(report, snapshot, recorded_to, store)
+      return JSON.pretty_generate(report ? report.to_h : snapshot.to_h) if options[:format] == "json"
+      return Reports::Drift.new(report, record_with: store.record_command(options[:since])).render if report
+
+      Reports::Snapshot.new(snapshot, saved_to: recorded_to, record_with: store.record_command).render
+    end
+
+    def save_snapshot(snapshot, destination)
+      File.write(destination, snapshot.to_json)
+      destination
+    rescue SystemCallError => e
+      raise ContractError, "Could not write the contract snapshot to #{destination}: #{e.message}"
+    end
+
+    def render_baseline(baseline, format)
+      case format
+      when "check" then Reports::GitHubCheck.new(baseline).render
+      when "json" then JSON.pretty_generate(baseline.to_h)
+      else Reports::Baseline.new(baseline).render
+      end
+    end
+
+    # Turns library errors into a clean, single-line CLI failure instead of a
+    # backtrace - the tool is for maintainers, not for reading stack traces.
+    def guard
+      yield
+    rescue Reanimator::Error => e
+      warn "reanimator: #{e.message}"
+      exit 1
+    end
+  end
+end