reanimator 0.1.0

data/lib/reanimator/family/gate_runner.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Reanimator
+  class Family
+    # Evaluates a family's gates (specification section 10). A candidate change
+    # upstream can trigger downstream checks "without opening changes in
+    # downstream repositories", so every check runs read-only, bounded, and in
+    # a disposable copy of the downstream member - never in its working tree.
+    #
+    # Execution is opt-in exactly as it is for a baseline: by default the runner
+    # reports what it *would* prove, so the graph is useful before anyone grants
+    # the right to run anything.
+    class GateRunner
+      # A downstream member proves itself with its smoke script when it has one
+      # (the section 10 example uses bin/smoke), else its discovered tests.
+      SMOKE_SCRIPTS = ["bin/smoke", "bin/doctor", "script/smoke"].freeze
+
+      attr_reader :family, :execute, :timeout
+
+      def initialize(family, execute: false, timeout: nil)
+        @family = family
+        @execute = execute
+        @timeout = timeout || Reanimator.configuration.command_timeout
+      end
+
+      # @return [Array<GateResult>]
+      def run
+        family.gates.map { |gate| evaluate(gate) }
+      end
+
+      private
+
+      def evaluate(gate)
+        member = family.member(gate.requires_repository)
+        return missing(gate, "#{gate.requires_repository} is not a member of family #{family.id}.") unless member
+        return missing(gate, "No local checkout known for #{gate.requires_repository}.") unless member.path
+
+        check = gate.check || discover_check(member)
+        return missing(gate, "No proof command found in #{gate.requires_repository}; the edge is unverifiable.") unless check
+
+        return planned(gate, check) unless execution_allowed?
+
+        run_check(gate, member, check)
+      end
+
+      def run_check(gate, member, check)
+        outcome = Isolation.copy(member.path) do |workspace|
+          BoundedCommand.run(check, chdir: workspace, timeout: timeout)
+        end
+
+        if outcome.success?
+          result(gate, :verified, detail: "#{check} passed in #{member.full_name}.", duration: outcome.duration)
+        else
+          reason = outcome.timed_out? ? "timed out after #{timeout}s" : "failed"
+          result(gate, :failed, detail: "#{check} #{reason} in #{member.full_name}.", duration: outcome.duration)
+        end
+      end
+
+      # The downstream member's own proof command: a smoke script if present,
+      # otherwise whatever discovery says it runs for tests.
+      def discover_check(member)
+        repository = Repository.at(member.path)
+        smoke = SMOKE_SCRIPTS.find { |script| repository.exist?(script) }
+        return smoke if smoke
+
+        Discovery.new(repository).run.discovered_commands[:tests]
+      rescue RepositoryError
+        nil
+      end
+
+      def execution_allowed?
+        execute && Reanimator.configuration.allow_execution
+      end
+
+      def planned(gate, check)
+        result(gate, :planned, detail: "Would run #{check} in #{gate.requires_repository}.")
+      end
+
+      def missing(gate, detail)
+        result(gate, :missing_evidence, detail: detail)
+      end
+
+      def result(gate, status, detail: nil, duration: nil)
+        GateResult.new(
+          gate: gate, status: status, detail: detail, duration: duration,
+          relationship: family.relationship_between(gate.on, gate.requires_repository)
+        )
+      end
+    end
+  end
+end

data/lib/reanimator/family.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # A graph of repositories whose health must be evaluated together
+  # (specification sections 02 and 10) - a gem and its executable examples, an
+  # application and its client, a project and its deployment samples. A family
+  # is the unit that answers "keep connected projects alive together": it knows
+  # its members and their roles, the typed edges between them, and the gates
+  # that make one member's proof a condition of another's.
+  class Family
+    # One repository inside a family. `path` is where it lives locally, when
+    # known - a gate can only run a downstream check if it can reach it.
+    Member = Struct.new(:full_name, :role, :path) do
+      def to_h = {full_name: full_name, role: role, path: path}.compact
+    end
+
+    attr_reader :id, :members, :gates, :relationships
+
+    def initialize(id:, members: [], gates: [], relationships: [])
+      @id = id.to_sym
+      @members = members
+      @gates = gates
+      @relationships = relationships
+    end
+
+    # @return [Member, nil]
+    def member(full_name)
+      members.find { |m| m.full_name == full_name }
+    end
+
+    def member?(full_name) = !member(full_name).nil?
+
+    def size = members.size
+
+    # Members holding a given role, e.g. :compatibility_suite.
+    def with_role(role)
+      members.select { |m| m.role == role.to_sym }
+    end
+
+    # The edge between two members, used to name exactly what broke.
+    def relationship_between(upstream, downstream)
+      relationships.find { |r| r.to == upstream && r.from == downstream }
+    end
+
+    # Parses the section 10 family-policy shape:
+    #
+    #   family:
+    #     id: agentic
+    #     members:
+    #       codenamev/agentic: {role: library}
+    #       codenamev/agentic-examples: {role: compatibility-suite}
+    #     gates:
+    #       - on: codenamev/agentic
+    #         require: {repository: codenamev/agentic-examples, check: bin/smoke}
+    #
+    # @param declaration [Hash]
+    # @param paths [Hash{String=>String}] optional full_name => local path
+    # @return [Family]
+    def self.from_declaration(declaration, paths: {})
+      raise ContractError, "A family declaration needs an id." unless declaration[:id]
+
+      members = (declaration[:members] || {}).map do |full_name, attributes|
+        name = full_name.to_s
+        role = (attributes || {})[:role] || :member
+        Member.new(name, role.to_s.tr("-", "_").to_sym, paths[name])
+      end
+
+      gates = (declaration[:gates] || []).map do |gate|
+        required = gate[:require] || {}
+        Gate.new(
+          on: gate[:on].to_s,
+          requires_repository: required[:repository].to_s,
+          check: required[:check]
+        )
+      end
+
+      new(id: declaration[:id], members: members, gates: gates)
+    end
+
+    def to_h
+      {
+        id: id,
+        members: members.map(&:to_h),
+        relationships: relationships.map(&:to_h),
+        gates: gates.map(&:to_h)
+      }
+    end
+  end
+end

data/lib/reanimator/family_inference.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # Infers repository families from a portfolio (specification section 10).
+  # The strongest signals are structural and cheap: a repository named
+  # `<project>-examples` is that project's compatibility suite,
+  # `<project>-example-heroku` is a deployment example, `<project>-docs` is its
+  # documentation, and `<host>-<project>` is a plugin for a project that is
+  # itself in the portfolio.
+  #
+  # Inference is deliberately conservative - it only proposes an edge it can
+  # point at concrete evidence for. An owner-declared family always wins, and
+  # weaker "these names look related" hunches are left to declaration rather
+  # than turned into obligations.
+  module FamilyInference
+    # Each rule maps a repository name to the project it depends on, and the
+    # kind of dependence that implies.
+    SUFFIX_RULES = [
+      [/\A(?<base>.+?)[-_]examples?\z/, :compatibility_suite],
+      [/\A(?<base>.+?)[-_]example[-_].+\z/, :deployment_example],
+      [/\A(?<base>.+?)[-_]docs?\z/, :documentation_for]
+    ].freeze
+
+    module_function
+
+    # @param portfolio [Portfolio]
+    # @return [Array<Family>] families with at least one edge, id-sorted
+    def call(portfolio)
+      repositories = portfolio.entries.map(&:repository)
+      declared = declared_families(repositories)
+      inferred = inferred_families(repositories, declared)
+
+      (declared.values + inferred.values).sort_by { |family| family.id.to_s }
+    end
+
+    # Families a repository explicitly joined via `family: {id:, role:}`.
+    def declared_families(repositories)
+      repositories.each_with_object({}) do |repository, families|
+        declaration = repository.declared&.family
+        next unless declaration.is_a?(Hash) && declaration[:id]
+
+        id = declaration[:id].to_sym
+        role = (declaration[:role] || :member).to_s.tr("-", "_").to_sym
+        family = families[id] ||= Family.new(id: id)
+        family.members << Family::Member.new(repository.full_name, role, repository.path)
+      end
+    end
+
+    # Families implied by naming structure, skipping any repository that has
+    # already declared its membership.
+    def inferred_families(repositories, declared)
+      claimed = declared.values.flat_map { |f| f.members.map(&:full_name) }
+      by_name = repositories.each_with_object({}) { |r, index| index[r.name] = r }
+      by_full_name = repositories.each_with_object({}) { |r, index| index[r.full_name] = r }
+
+      edges = repositories.filter_map do |repository|
+        next if claimed.include?(repository.full_name)
+
+        relationship = relate(repository, by_name)
+        # Declaration wins over inference on *both* ends: once an owner has
+        # placed a repository in a family, we do not invent a competing family
+        # around it, even as the upstream of someone else's edge.
+        next if relationship.nil? || claimed.include?(relationship.to)
+
+        relationship
+      end
+
+      build_families(edges, by_full_name)
+    end
+
+    # The edge this repository implies, or nil when nothing matches.
+    def relate(repository, by_name)
+      SUFFIX_RULES.each do |pattern, type|
+        match = repository.name.match(pattern)
+        next unless match && by_name.key?(match[:base])
+
+        return edge(repository, by_name[match[:base]], type, "name #{repository.name} implies #{match[:base]}")
+      end
+
+      plugin_edge(repository, by_name)
+    end
+
+    # `ruby_llm-ups` is a plugin for `ups` when `ups` is itself in the portfolio.
+    def plugin_edge(repository, by_name)
+      host = repository.name.split(/[-_]/).last
+      return if host.nil? || host == repository.name
+      return unless by_name.key?(host)
+
+      edge(repository, by_name[host], :plugin_for, "name #{repository.name} targets #{host}")
+    end
+
+    def edge(dependent, upstream, type, evidence)
+      return if dependent.full_name == upstream.full_name
+
+      Relationship.new(from: dependent.full_name, to: upstream.full_name, type: type, evidence: evidence)
+    end
+
+    # Groups edges by their upstream project into one family each, with a gate
+    # per edge so every dependence has something that proves it.
+    def build_families(edges, by_full_name)
+      edges.group_by(&:to).each_with_object({}) do |(upstream_name, group), families|
+        upstream = by_full_name.fetch(upstream_name)
+
+        members = [Family::Member.new(upstream_name, :library, upstream.path)] +
+          group.map { |edge| Family::Member.new(edge.from, edge.role, by_full_name[edge.from]&.path) }
+        gates = group.map { |edge| Family::Gate.new(on: upstream_name, requires_repository: edge.from) }
+
+        families[upstream.name.to_sym] =
+          Family.new(id: upstream.name, members: members, gates: gates, relationships: group)
+      end
+    end
+  end
+end

data/lib/reanimator/git.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Reanimator
+  # A deliberately tiny, read-only wrapper around the git CLI. Reanimator
+  # never mutates a repository during observation or discovery, so this helper
+  # only ever runs inspection commands and returns nil rather than raising when
+  # git is absent or the command fails - a repository without git history is a
+  # fact to record, not a crash.
+  module Git
+    module_function
+
+    # @param root [String] repository working directory
+    # @return [Boolean] whether the path is inside a git working tree
+    def repository?(root)
+      capture(root, "rev-parse", "--is-inside-work-tree") == "true"
+    end
+
+    # @return [String, nil] the origin remote URL, if any
+    def origin_url(root)
+      capture(root, "config", "--get", "remote.origin.url")
+    end
+
+    # @return [Boolean] whether an "upstream" remote is configured, a strong
+    #   local hint that the repository is a maintained fork
+    def upstream_remote?(root)
+      !capture(root, "config", "--get", "remote.upstream.url").nil?
+    end
+
+    # @return [String, nil] the current branch name
+    def current_branch(root)
+      branch = capture(root, "rev-parse", "--abbrev-ref", "HEAD")
+      branch unless branch == "HEAD"
+    end
+
+    # @return [Time, nil] author time of the most recent commit
+    def last_commit_at(root)
+      iso = capture(root, "log", "-1", "--format=%cI")
+      Time.parse(iso) if iso && !iso.empty?
+    rescue ArgumentError
+      nil
+    end
+
+    # @return [Integer, nil] number of commits, a cheap activity signal
+    def commit_count(root)
+      count = capture(root, "rev-list", "--count", "HEAD")
+      Integer(count) if count
+    rescue ArgumentError
+      nil
+    end
+
+    # @return [Array<String>] tracked files (fast, respects .gitignore); empty
+    #   when git is unavailable
+    def tracked_files(root)
+      out = capture(root, "ls-files")
+      out ? out.split("\n") : []
+    end
+
+    # Runs a read-only git command, returning trimmed stdout or nil on any
+    # failure. stderr is discarded - callers treat "no answer" as the signal.
+    def capture(root, *args)
+      require "time"
+      stdout, _stderr, status = Open3.capture3("git", "-C", root.to_s, *args)
+      return nil unless status.success?
+      value = stdout.strip
+      value.empty? ? nil : value
+    rescue Errno::ENOENT
+      nil
+    end
+  end
+end

data/lib/reanimator/isolation.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "fileutils"
+
+module Reanimator
+  # Disposable-workspace helper (specification section 12: "disposable
+  # workspaces", section 14: "all commands run in a disposable workspace"). It
+  # copies a repository into a throwaway directory so an agent can work, and so
+  # evaluation can run, without ever touching the original source. The agent's
+  # workspace and the evaluation workspace are always distinct copies - verifier
+  # isolation by construction.
+  module Isolation
+    module_function
+
+    # Copies a repository root into a fresh temp directory (excluding .git),
+    # yielding the copy to the block and removing it afterward. Without a block
+    # it returns the path and the caller owns cleanup.
+    def copy(root)
+      destination = Dir.mktmpdir("reanimator-iso")
+      Dir.children(root).each do |child|
+        next if child == ".git"
+
+        FileUtils.cp_r(File.join(root, child), File.join(destination, child))
+      end
+
+      return destination unless block_given?
+
+      begin
+        yield destination
+      ensure
+        FileUtils.remove_entry(destination, true)
+      end
+    end
+  end
+end

data/lib/reanimator/language_inference.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # A cheap primary-language guess from file extensions. This is intentionally
+  # crude - it exists to seed cohort heuristics and reports, not to replace a
+  # linguist. When git is present it counts tracked files (fast and respectful
+  # of .gitignore); otherwise it falls back to a bounded directory walk.
+  module LanguageInference
+    EXTENSIONS = {
+      ".rb" => "Ruby", ".rake" => "Ruby", ".gemspec" => "Ruby",
+      ".js" => "JavaScript", ".mjs" => "JavaScript", ".ts" => "TypeScript",
+      ".py" => "Python", ".go" => "Go", ".rs" => "Rust",
+      ".java" => "Java", ".kt" => "Kotlin", ".c" => "C", ".h" => "C",
+      ".cpp" => "C++", ".cs" => "C#", ".php" => "PHP",
+      ".ex" => "Elixir", ".exs" => "Elixir", ".erl" => "Erlang",
+      ".swift" => "Swift", ".sh" => "Shell", ".crystal" => "Crystal", ".cr" => "Crystal"
+    }.freeze
+
+    MAX_WALK_FILES = 5_000
+
+    module_function
+
+    # @param root [String]
+    # @return [String, nil] the most common recognized language, or nil
+    def call(root)
+      counts = Hash.new(0)
+      files(root).each do |rel|
+        language = EXTENSIONS[File.extname(rel)]
+        counts[language] += 1 if language
+      end
+      counts.max_by { |_lang, n| n }&.first
+    end
+
+    def files(root)
+      tracked = Git.tracked_files(root)
+      return tracked unless tracked.empty?
+
+      Dir.glob("**/*", base: root, flags: File::FNM_DOTMATCH)
+        .reject { |rel| rel.start_with?(".git/") }
+        .first(MAX_WALK_FILES)
+    end
+  end
+end

data/lib/reanimator/lifecycle_intent.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # The first and most important configuration value (specification section
+  # 05). Lifecycle intent is the owner's declaration of *why* a repository
+  # should continue to exist and what level of care it deserves. The same
+  # technical signal - say, a failing test - means different things for a
+  # maintained product, a preserved artifact, and an ignored fork, so intent
+  # is never inferred as final without confirmation.
+  class LifecycleIntent
+    # @return [Symbol] stable key used in contracts and reports
+    attr_reader :key
+    # @return [String] the promise Reanimator makes for this intent
+    attr_reader :promise
+    # @return [String] the default activity this intent authorizes
+    attr_reader :default_activity
+    # @return [Boolean] whether the intent creates any stewardship obligation
+    attr_reader :creates_obligation
+
+    def initialize(key:, promise:, default_activity:, creates_obligation: true)
+      @key = key
+      @promise = promise
+      @default_activity = default_activity
+      @creates_obligation = creates_obligation
+      freeze
+    end
+
+    # @return [Boolean] whether the intent creates any stewardship obligation
+    def creates_obligation?
+      @creates_obligation
+    end
+
+    # The canonical intents, keyed by symbol. Order is meaningful for display:
+    # most-active first, dormant last.
+    ALL = {
+      maintain: new(
+        key: :maintain,
+        promise: "Keep the repository runnable, supported, secure, and within its declared contract.",
+        default_activity: "Scheduled verification and eligible repair."
+      ),
+      monitor: new(
+        key: :monitor,
+        promise: "Detect meaningful deterioration without routine code churn.",
+        default_activity: "Periodic checks and event-triggered diagnosis."
+      ),
+      preserve: new(
+        key: :preserve,
+        promise: "Protect historical readability, provenance, and known reproduction instructions.",
+        default_activity: "Link, license, metadata, and optional reproducibility checks."
+      ),
+      incubate: new(
+        key: :incubate,
+        promise: "Surface missing foundations while the project is still becoming real.",
+        default_activity: "Report gaps; avoid unsolicited modernization."
+      ),
+      retire: new(
+        key: :retire,
+        promise: "Make end-of-life explicit and safely reduce obligations.",
+        default_activity: "Archive checklist, notices, migration path, and access cleanup."
+      ),
+      upstream: new(
+        key: :upstream,
+        promise: "Track a fork's divergence and upstream movement.",
+        default_activity: "Compare ancestry and unique commits; no generic dependency churn."
+      ),
+      ignore: new(
+        key: :ignore,
+        promise: "Create no stewardship obligation.",
+        default_activity: "No scheduled activity.",
+        creates_obligation: false
+      )
+    }.freeze
+
+    # @param key [Symbol, String]
+    # @return [LifecycleIntent]
+    # @raise [UnknownError] when the key is not a canonical intent
+    def self.fetch(key)
+      ALL.fetch(key.to_sym) do
+        raise UnknownError, "Unknown lifecycle intent #{key.inspect}. Known: #{ALL.keys.join(", ")}."
+      end
+    end
+
+    # @param key [Symbol, String]
+    # @return [Boolean]
+    def self.valid?(key)
+      ALL.key?(key.to_sym)
+    end
+
+    def to_sym = key
+
+    def to_s = key.to_s
+  end
+end

data/lib/reanimator/obligation.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # A bounded unit of drift or risk that must be verified, repaired, accepted,
+  # deferred, or waived (specification section 02 and section 17). An obligation
+  # is idempotent and deduplicated by repository, policy, target, and drift
+  # condition, so the same failing criterion does not spawn a swarm of tasks.
+  class Obligation
+    STATES = %i[open in_progress resolved deferred waived].freeze
+
+    attr_reader :repository, :policy_version, :target, :trigger, :urgency, :task_class, :state
+
+    def initialize(repository:, policy_version:, target:, trigger:, task_class:, urgency: :normal, state: :open)
+      @repository = repository
+      @policy_version = policy_version
+      @target = target
+      @trigger = trigger
+      @task_class = task_class
+      @urgency = urgency
+      @state = state
+    end
+
+    # Stable identity used for idempotent deduplication (section 17).
+    def id
+      "#{repository.full_name}::#{policy_version}::#{target.id}"
+    end
+
+    def to_h
+      {
+        id: id, repository: repository.full_name, policy_version: policy_version,
+        target: target.id, trigger: trigger, task_class: task_class, urgency: urgency, state: state
+      }
+    end
+  end
+end

data/lib/reanimator/permission_model.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # Resolves what an agent is actually permitted to do for a task, by
+  # intersecting the task class defaults (section 11) with the repository's
+  # enabled autonomy (the effective contract) and the safety floor. The contract
+  # is a *ceiling*: a task class may default to "submit as draft", but if the
+  # repository has not enabled submit, the resolved action is off. Merge is
+  # always off in v1.
+  class PermissionModel
+    # The resolved decision for one task against one contract.
+    Resolution = Struct.new(:task_class, :actions, :elevated_review, :max_action) do
+      def elevated_review? = elevated_review
+
+      def permits?(level) = actions.fetch(level.to_sym, :off) != :off
+    end
+
+    def initialize(contract)
+      @contract = contract
+    end
+
+    # @param task_class [Symbol, TaskClass]
+    # @return [Resolution]
+    def resolve(task_class)
+      klass = task_class.is_a?(TaskClass) ? task_class : TaskClass.fetch(task_class)
+      actions = AutonomyLevel.keys.each_with_object({}) do |level, resolved|
+        resolved[level] = clamp(level, klass.default_for(level))
+      end
+      actions[:merge] = :off # safety floor: no automatic merge in v1
+
+      Resolution.new(
+        task_class: klass.key,
+        actions: actions,
+        elevated_review: klass.elevated_review? || touches_verifier?,
+        max_action: highest_enabled(actions)
+      )
+    end
+
+    private
+
+    # Clamp a task-class default against what the contract enables for the rung.
+    def clamp(level, default)
+      return default if %i[observe diagnose].include?(level) # always at least observe/diagnose
+
+      ceiling = @contract.autonomy[level]
+      disabled?(ceiling) ? :off : default
+    end
+
+    def disabled?(ceiling)
+      ceiling.nil? || ceiling.to_sym == :disabled
+    end
+
+    def touches_verifier?
+      @contract.verifier_criteria.any?
+    end
+
+    def highest_enabled(actions)
+      AutonomyLevel.keys.reverse.find { |level| actions[level] != :off } || :observe
+    end
+  end
+end