reanimator 0.1.0

data/lib/reanimator.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "logger"
+require "zeitwerk"
+
+# Zeitwerk is the single code loader for the gem: every constant under
+# Reanimator:: is autoloaded on first reference, including the CLI, so a
+# library consumer (or a future GitHub App host) never pays for Thor or the
+# tty-* UI stack at require time. Files must not require_relative their
+# siblings - reference the constant and let the loader resolve it.
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect(
+  "cli" => "CLI",
+  "github_actions" => "GitHubActions",
+  "github_check" => "GitHubCheck"
+)
+# errors.rb intentionally defines the whole error family in one file, so it is
+# required directly rather than autoloaded one-constant-per-file.
+loader.ignore("#{__dir__}/reanimator/errors.rb")
+# The interactive surface is loaded on demand (exe/reanimator), never eager.
+loader.do_not_eager_load("#{__dir__}/reanimator/cli.rb")
+loader.setup
+
+require_relative "reanimator/errors"
+
+# Reanimator turns repository intent into a verified, low-friction
+# stewardship contract. The public promise, echoed throughout this library, is
+# that the first successful run proves something useful *without changing a
+# single line of code*: it observes, discovers, resolves an effective
+# contract, and measures a read-only baseline before any coding agent or write
+# permission is involved.
+#
+# The module methods below are the "80% path" - a maintainer can go from a
+# path on disk to a proof-of-life report in one call.
+module Reanimator
+  class << self
+    attr_writer :configuration
+    attr_accessor :logger
+  end
+
+  # Quiet by default. The CLI raises verbosity for interactive use; library
+  # consumers opt in via Reanimator.logger.level=.
+  self.logger ||= Logger.new($stdout, level: Logger::WARN)
+
+  # @return [Configuration] the process-wide configuration
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # @yieldparam config [Configuration]
+  # @return [Configuration]
+  def self.configure
+    yield(configuration) if block_given?
+    configuration
+  end
+
+  # Classify a set of repository paths into lifecycle cohorts.
+  #
+  # @param paths [Array<String>] repository roots on disk
+  # @return [Portfolio] the classified portfolio
+  def self.inventory(paths)
+    Portfolio.scan(Array(paths))
+  end
+
+  # Run every detector over a repository and return its discovered facts.
+  #
+  # @param path [String] repository root on disk
+  # @return [DiscoveryResult]
+  def self.discover(path)
+    Discovery.new(Repository.at(path)).run
+  end
+
+  # Resolve the effective vitality contract for a repository: discovery plus
+  # the inferred (or declared) profile plus any .reanimator.yml overrides,
+  # all clamped by the non-bypassable safety floor.
+  #
+  # @param path [String] repository root on disk
+  # @param intent [Symbol, nil] override the inferred lifecycle intent
+  # @return [EffectiveContract]
+  def self.contract(path, intent: nil)
+    repository = Repository.at(path)
+    repository.intent = intent if intent
+    EffectivePolicyResolver.new(repository).resolve
+  end
+
+  # Measure a read-only proof-of-life baseline for a repository.
+  #
+  # @param path [String] repository root on disk
+  # @param execute [Boolean] actually run discovered checks (bounded,
+  #   read-only) rather than only planning them
+  # @param intent [Symbol, nil] override the inferred lifecycle intent
+  # @return [Baseline]
+  def self.baseline(path, execute: false, intent: nil)
+    BaselineRunner.new(contract(path, intent: intent), execute: execute).run
+  end
+
+  # Capture the contract a repository resolves to right now, in a form that can
+  # be recorded and compared later.
+  #
+  # @param path [String] repository root on disk
+  # @param intent [Symbol, nil] override the inferred lifecycle intent
+  # @return [ContractSnapshot]
+  def self.snapshot(path, intent: nil)
+    ContractSnapshot.of(contract(path, intent: intent))
+  end
+
+  # Detect configuration drift (section 06): compare the contract a repository
+  # resolves to now against a previously recorded snapshot, classifying each
+  # difference as a policy change (a human should look) or a benign one.
+  #
+  # @param path [String] repository root on disk
+  # @param since [String, ContractSnapshot] a recorded snapshot, or a path to one
+  # @param intent [Symbol, nil] override the inferred lifecycle intent
+  # @return [DriftReport]
+  def self.drift(path, since:, intent: nil)
+    previous = since.is_a?(ContractSnapshot) ? since : ContractSnapshot.load(since.to_s)
+    DriftDetector.between(previous, snapshot(path, intent: intent))
+  end
+
+  # Detect configuration drift across several repositories at once. Each
+  # repository is compared against its own recorded snapshot - its committed
+  # `.reanimator-snapshot.json`, or a file in `snapshots` keyed by
+  # repository - and the result is a triage list rather than one verdict.
+  #
+  # @param paths [Array<String>] repository roots on disk
+  # @param snapshots [String, nil] a directory of recorded snapshots, for
+  #   repositories you cannot commit a file into
+  # @param record [Boolean] also write each repository's current snapshot
+  # @param intent [Symbol, nil] override the inferred lifecycle intent
+  # @param name [String] portfolio name for the report header
+  # @return [PortfolioDrift]
+  def self.portfolio_drift(paths, snapshots: nil, record: false, intent: nil, name: "portfolio")
+    PortfolioDrift.scan(
+      paths, store: SnapshotStore.new(directory: snapshots),
+      record: record, intent: intent, name: name
+    )
+  end
+
+  # Default environment-variable names where each hosted provider's credentials
+  # would live. Credentials are never read from a repository (section 08).
+  CREDENTIAL_REFS = {
+    codex: "OPENAI_ACCESS_TOKEN",
+    claude: "ANTHROPIC_API_KEY",
+    amp: "AMP_API_KEY"
+  }.freeze
+
+  # Commission a coding agent: prove it can plan and patch a synthetic repair on
+  # a disposable fixture, graded independently, without any repository write.
+  #
+  # @param provider [Symbol] :local (default), :codex, :claude, or :amp
+  # @return [Commissioning::Report]
+  def self.commission(provider: :local, **connection_options)
+    connection =
+      if provider.to_sym == :local
+        AgentConnection.local(**connection_options)
+      else
+        AgentConnection.new(
+          provider: provider, credentials_ref: CREDENTIAL_REFS[provider.to_sym], **connection_options
+        )
+      end
+    Commissioning::Test.new(Agents.for(connection)).run
+  end
+
+  # Attempt one bounded repair for a repository's first failing required
+  # criterion. Read-only with respect to the repository: the result is a
+  # recorded {Run} whose most eventful outcome is a *proposed* draft PR, never a
+  # write or submission.
+  #
+  # @param path [String] repository root on disk
+  # @param provider [Symbol] agent provider (:local by default)
+  # @param task_class [Symbol] the task class governing autonomy (section 11)
+  # @return [Run]
+  def self.repair(path, provider: :local, task_class: :patch_dependency)
+    RepairRun.new(contract(path), provider: provider, task_class: task_class).run
+  end
+
+  # Infer the compatibility graph for a set of repository paths: which
+  # repositories must stay alive together, and what proves each edge.
+  #
+  # @param paths [Array<String>]
+  # @return [Array<Family>]
+  def self.families(paths)
+    FamilyInference.call(inventory(paths))
+  end
+
+  # Evaluate cross-repository gates for the inferred families. Read-only by
+  # default: each downstream check only runs when execution is requested, and
+  # then in a disposable copy of the downstream repository.
+  #
+  # @param paths [Array<String>]
+  # @param family [Symbol, String, nil] limit to one family id
+  # @param execute [Boolean]
+  # @return [Array<Array(Family, Array<Family::GateResult>)>]
+  def self.family_gates(paths, family: nil, execute: false)
+    found = families(paths)
+    found = found.select { |f| f.id == family.to_sym } if family
+    found.map { |f| [f, Family::GateRunner.new(f, execute: execute).run] }
+  end
+
+  # Adapters for every built-in provider, with default connections - the roster
+  # the CLI lists with availability.
+  # @return [Array<Agents::Adapter>]
+  def self.adapters
+    Agents.providers.map do |provider|
+      connection =
+        if provider == :local
+          AgentConnection.local
+        else
+          AgentConnection.new(provider: provider, credentials_ref: CREDENTIAL_REFS[provider])
+        end
+      Agents.for(connection)
+    end
+  end
+end

metadata

@@ -0,0 +1,262 @@
+--- !ruby/object:Gem::Specification
+name: reanimator
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Valentino Stoll
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-10-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: pastel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: tty-table
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: tty-box
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: psych
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Reanimator reads a repository, infers what "healthy" means for it, and
+  proves that health without changing a single line of code. It classifies lifecycle
+  intent, discovers a vitality contract from evidence, resolves an effective policy,
+  and produces a read-only proof-of-life baseline - before any coding agent or write
+  permission is ever involved.
+email:
+- v@codenamev.com
+executables:
+- reanimator
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- SECURITY.md
+- exe/reanimator
+- lib/reanimator.rb
+- lib/reanimator/acceptance_criterion.rb
+- lib/reanimator/agent_connection.rb
+- lib/reanimator/agent_profile.rb
+- lib/reanimator/agents.rb
+- lib/reanimator/agents/adapter.rb
+- lib/reanimator/agents/capability.rb
+- lib/reanimator/agents/constraints.rb
+- lib/reanimator/agents/hosted.rb
+- lib/reanimator/agents/local.rb
+- lib/reanimator/agents/patch.rb
+- lib/reanimator/agents/repair_task.rb
+- lib/reanimator/agents/result.rb
+- lib/reanimator/agents/strategies/arithmetic_fix.rb
+- lib/reanimator/agents/strategies/base.rb
+- lib/reanimator/autonomy_level.rb
+- lib/reanimator/baseline.rb
+- lib/reanimator/baseline_runner.rb
+- lib/reanimator/bounded_command.rb
+- lib/reanimator/classifier.rb
+- lib/reanimator/cli.rb
+- lib/reanimator/cohort.rb
+- lib/reanimator/commissioning/fixture.rb
+- lib/reanimator/commissioning/report.rb
+- lib/reanimator/commissioning/test.rb
+- lib/reanimator/confidence.rb
+- lib/reanimator/configuration.rb
+- lib/reanimator/contract_file.rb
+- lib/reanimator/contract_snapshot.rb
+- lib/reanimator/criteria_stack.rb
+- lib/reanimator/criterion_result.rb
+- lib/reanimator/detectors/base.rb
+- lib/reanimator/detectors/bundler.rb
+- lib/reanimator/detectors/commands.rb
+- lib/reanimator/detectors/fork.rb
+- lib/reanimator/detectors/github_actions.rb
+- lib/reanimator/detectors/operational_proof.rb
+- lib/reanimator/detectors/rails_app.rb
+- lib/reanimator/detectors/relationships.rb
+- lib/reanimator/detectors/ruby_gem.rb
+- lib/reanimator/detectors/security_controls.rb
+- lib/reanimator/discovered_fact.rb
+- lib/reanimator/discovery.rb
+- lib/reanimator/discovery_result.rb
+- lib/reanimator/drift_detector.rb
+- lib/reanimator/drift_report.rb
+- lib/reanimator/effective_contract.rb
+- lib/reanimator/effective_policy_resolver.rb
+- lib/reanimator/errors.rb
+- lib/reanimator/evaluators.rb
+- lib/reanimator/evaluators/base.rb
+- lib/reanimator/evaluators/command.rb
+- lib/reanimator/evaluators/documentation_check.rb
+- lib/reanimator/evaluators/http_smoke.rb
+- lib/reanimator/evaluators/repository_integrity.rb
+- lib/reanimator/evaluators/security_evidence.rb
+- lib/reanimator/evaluators/support_matrix.rb
+- lib/reanimator/family.rb
+- lib/reanimator/family/gate.rb
+- lib/reanimator/family/gate_result.rb
+- lib/reanimator/family/gate_runner.rb
+- lib/reanimator/family_inference.rb
+- lib/reanimator/git.rb
+- lib/reanimator/isolation.rb
+- lib/reanimator/language_inference.rb
+- lib/reanimator/lifecycle_intent.rb
+- lib/reanimator/obligation.rb
+- lib/reanimator/permission_model.rb
+- lib/reanimator/portfolio.rb
+- lib/reanimator/portfolio_drift.rb
+- lib/reanimator/profile_inference.rb
+- lib/reanimator/profiles.rb
+- lib/reanimator/proof_of_life.rb
+- lib/reanimator/proposed_change.rb
+- lib/reanimator/provenance.rb
+- lib/reanimator/relationship.rb
+- lib/reanimator/repair_run.rb
+- lib/reanimator/reports.rb
+- lib/reanimator/reports/agents.rb
+- lib/reanimator/reports/baseline.rb
+- lib/reanimator/reports/commissioning.rb
+- lib/reanimator/reports/contract.rb
+- lib/reanimator/reports/discovery.rb
+- lib/reanimator/reports/drift.rb
+- lib/reanimator/reports/families.rb
+- lib/reanimator/reports/family_gates.rb
+- lib/reanimator/reports/github_check.rb
+- lib/reanimator/reports/inventory.rb
+- lib/reanimator/reports/permissions.rb
+- lib/reanimator/reports/portfolio_baseline.rb
+- lib/reanimator/reports/portfolio_drift.rb
+- lib/reanimator/reports/run.rb
+- lib/reanimator/reports/snapshot.rb
+- lib/reanimator/repository.rb
+- lib/reanimator/repository_metadata.rb
+- lib/reanimator/repository_state.rb
+- lib/reanimator/routing/decision.rb
+- lib/reanimator/routing/router.rb
+- lib/reanimator/run.rb
+- lib/reanimator/safety_floor.rb
+- lib/reanimator/security_control.rb
+- lib/reanimator/security_posture.rb
+- lib/reanimator/snapshot_store.rb
+- lib/reanimator/task_class.rb
+- lib/reanimator/version.rb
+- lib/reanimator/vitality_profile.rb
+- lib/reanimator/waiver.rb
+homepage: https://github.com/Autogenetica/reanimator
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Autogenetica/reanimator
+  changelog_uri: https://github.com/Autogenetica/reanimator/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Autogenetica/reanimator/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Turn repository intent into a verified, low-friction stewardship contract.
+test_files: []