reeve 0.0.1 → 0.1.0

data/lib/reeve/testing/ledger.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    # The checks' read-only window onto the audit ledger.
+    #
+    # It exists so that `require "reeve/testing"` stays loadable with no ActiveRecord in
+    # the process (FR-020, SC-008): nothing here mentions +Reeve::Audit::Entry+ until a
+    # check actually asks a question, and every question has an answer for the case where
+    # the ledger is absent.
+    #
+    # A host with its own non-ActiveRecord recorder can pass any object with these six
+    # methods as `ledger:` to any ledger-reading check.
+    class Ledger
+      def self.default
+        new
+      end
+
+      def available?
+        return false if entry_class.nil?
+
+        entry_class.table_exists?
+      rescue StandardError
+        false
+      end
+
+      # Why not, in the words a developer can act on.
+      def unavailable_reason
+        return nil if available?
+        if entry_class.nil?
+          return "the audit ledger is not loaded — add `require \"reeve/audit\"` to your " \
+                 "test helper, or pass a `ledger:` of your own"
+        end
+
+        "the #{entry_class.table_name} table does not exist — run `rails g reeve:install` " \
+          "and migrate"
+      end
+
+      # A position in the ledger, taken before an invocation so the entries that
+      # invocation wrote can be told apart from everything already there.
+      def marker
+        return nil unless available?
+
+        entry_class.maximum(:id)
+      end
+
+      def entries_after(marker)
+        return [] unless available?
+
+        scope = entry_class.order(:id)
+        marker.nil? ? scope.to_a : scope.where("id > ?", marker).to_a
+      end
+
+      def count
+        available? ? entry_class.count : 0
+      end
+
+      def contract_version
+        return nil unless entry_class.respond_to?(:contract_version)
+
+        entry_class.contract_version
+      end
+
+      def columns
+        return [] unless available?
+
+        entry_class.column_names.map(&:to_s)
+      end
+
+      private
+
+      def entry_class
+        return @entry_class if defined?(@entry_class)
+
+        @entry_class =
+          if Reeve.const_defined?(:Audit, false) && Reeve::Audit.const_defined?(:Entry, false)
+            Reeve::Audit::Entry
+          end
+      end
+    end
+  end
+end

data/lib/reeve/testing/matchers/audit_every_call.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    module Matchers
+      # FR-017, from RSpec:
+      #
+      #   it { is_expected.to audit_every_call }
+      #   it { is_expected.to audit_every_call.for_principal(alice).with(query: "AC") }
+      #
+      # Point it at the host's own call site to prove that *that* goes through the
+      # envelope, which is where an audit bypass actually lives:
+      #
+      #   it { is_expected.to audit_every_call.invoked_by(MyServer.method(:dispatch)) }
+      class AuditEveryCall < Base
+        def self.check
+          Checks::AuditCoverage
+        end
+
+        def for_principal(principal)
+          @principal = principal
+          self
+        end
+
+        def description
+          "audit every call"
+        end
+
+        private
+
+        def check_for(tool)
+          Checks::AuditCoverage.new(
+            tool: tool, principal: @principal || default_principal, **options
+          )
+        end
+      end
+    end
+  end
+end

data/lib/reeve/testing/matchers/base.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    module Matchers
+      # What every reeve matcher is: a check, and nothing else.
+      #
+      # +failure_message+ returns the check's own +message+ verbatim. No matcher composes
+      # a sentence, reformats one, or adds context (FR-019) — that is the whole reason the
+      # same violation reads identically here, in Minitest, and in a rake task.
+      #
+      # Written against RSpec's matcher protocol by duck-typing rather than by including
+      # +RSpec::Matchers::DSL+, so nothing under lib/reeve/testing needs RSpec loaded in
+      # order to be *parsed*; only a suite that uses these needs it present.
+      class Base
+        attr_reader :result
+
+        def initialize
+          @arguments = {}
+          @invoke = nil
+          @ledger = nil
+        end
+
+        # The arguments the tool is called with.
+        def with(**arguments)
+          @arguments = arguments
+          self
+        end
+
+        # How the tool is called. Point this at a host's own invoker to prove that *it*
+        # goes through the envelope.
+        def invoked_by(callable)
+          @invoke = callable
+          self
+        end
+
+        def reading(ledger)
+          @ledger = ledger
+          self
+        end
+
+        def matches?(subject)
+          @result = check_for(subject).call
+          @result.passed?
+        end
+
+        # No `does_not_match?`: RSpec negates `matches?` for us, and a check that had a
+        # separate negative path could drift from its positive one.
+        def failure_message
+          result.message
+        end
+
+        def failure_message_when_negated
+          "expected #{result.check} to fail, but it passed: #{result.message}"
+        end
+
+        def description
+          self.class.check.check_name
+        end
+
+        def supports_block_expectations?
+          false
+        end
+
+        private
+
+        attr_reader :arguments, :invoke, :ledger
+
+        def check_for(_subject)
+          raise NotImplementedError, "#{self.class} must build its check"
+        end
+
+        def options
+          { arguments: arguments, invoke: invoke, ledger: ledger }
+        end
+
+        # The principal a matcher falls back to when the example did not name one.
+        def default_principal
+          Testing.compliance_principals.first
+        end
+      end
+    end
+  end
+end

data/lib/reeve/testing/matchers/deny_access_for.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    module Matchers
+      # FR-016, from RSpec:
+      #
+      #   it { is_expected.to deny_access_for(stranger).with(query: "AC") }
+      #
+      # Backed by CrossPrincipalLeak in its :nothing expectation — this principal may
+      # receive no record at all. A denial satisfies it; so does an allowed call that
+      # returns an empty scope, because from the agent's side those are the same thing,
+      # and FR-006 requires that they stay the same thing.
+      class DenyAccessFor < Base
+        def self.check
+          Checks::CrossPrincipalLeak
+        end
+
+        def initialize(principal)
+          super()
+          @principal = principal
+        end
+
+        def description
+          "deny access for #{@principal.inspect}"
+        end
+
+        private
+
+        def check_for(tool)
+          Checks::CrossPrincipalLeak.new(
+            tool: tool, principals: [@principal], expect: :nothing, **options
+          )
+        end
+      end
+    end
+  end
+end

data/lib/reeve/testing/matchers/pass_reeve_check.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    module Matchers
+      # The escape hatch that keeps SC-009 honest: every one of the seven checks is
+      # assertable from RSpec, not only the two with names of their own.
+      #
+      #   expect(Reeve::Checks::RedactionHolds.new(tool: T, principal: alice))
+      #     .to pass_reeve_check
+      class PassReeveCheck < Base
+        def self.check
+          Checks::Base
+        end
+
+        def description
+          "pass its reeve check"
+        end
+
+        def failure_message_when_negated
+          "expected #{result.check} to fail, but it passed: #{result.message}"
+        end
+
+        private
+
+        def check_for(check)
+          check
+        end
+      end
+    end
+  end
+end

data/lib/reeve/testing/matchers.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "matchers/base"
+require_relative "matchers/deny_access_for"
+require_relative "matchers/audit_every_call"
+require_relative "matchers/pass_reeve_check"
+
+module Reeve
+  module Testing
+    # The RSpec front-end.
+    #
+    #   require "reeve/rspec"
+    #   RSpec.configure { |c| c.include Reeve::Testing::Matchers }
+    #
+    #   RSpec.describe InvoiceSearchTool do
+    #     it { is_expected.to deny_access_for(stranger).with(query: "AC") }
+    #     it { is_expected.to audit_every_call }
+    #   end
+    module Matchers
+      def deny_access_for(principal)
+        DenyAccessFor.new(principal)
+      end
+
+      def audit_every_call
+        AuditEveryCall.new
+      end
+
+      def pass_reeve_check
+        PassReeveCheck.new
+      end
+    end
+  end
+end

data/lib/reeve/testing/report.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    # The aggregate of one compliance run (FR-018).
+    #
+    # +to_s+ is written to be the whole output of a failing CI step: a one-line verdict
+    # followed by every failure in full. A report that has to be cross-referenced with
+    # something else is a report nobody reads at 3am.
+    class Report
+      attr_reader :results
+
+      def initialize(results)
+        @results = results.freeze
+        freeze
+      end
+
+      def passed?
+        failures.empty?
+      end
+
+      def failed?
+        !passed?
+      end
+
+      def failures
+        results.reject(&:passed?)
+      end
+
+      def passes
+        results.select(&:passed?)
+      end
+
+      def size
+        results.size
+      end
+
+      def to_s
+        [summary, *failures.map { |result| detail(result) }].join("\n")
+      end
+
+      def inspect
+        "#<Reeve::Testing::Report #{summary}>"
+      end
+
+      private
+
+      def summary
+        "reeve compliance: #{size} #{size == 1 ? 'check' : 'checks'}, " \
+          "#{passes.size} passed, #{failures.size} failed"
+      end
+
+      def detail(result)
+        "\nFAIL #{result.check}\n  #{result.message}"
+      end
+    end
+  end
+end

data/lib/reeve/testing/result.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Testing
+    # What a check hands back: whether the guarantee held, the sentence explaining it, and
+    # the structured facts behind the sentence.
+    #
+    # The message is built here and nowhere else. A front-end — an RSpec matcher, a
+    # Minitest assertion, a rake task — reads +message+ and prints it; none of them
+    # composes their own (FR-019). That is what makes the same violation read identically
+    # from all three.
+    class Result
+      attr_reader :check, :message, :details
+
+      def self.passed(check:, message:, details: {})
+        new(check: check, passed: true, message: message, details: details)
+      end
+
+      def self.failed(check:, message:, details: {})
+        new(check: check, passed: false, message: message, details: details)
+      end
+
+      def initialize(check:, passed:, message:, details: {})
+        @check   = check.to_s
+        @passed  = passed ? true : false
+        @message = message.to_s
+        @details = details.freeze
+        freeze
+      end
+
+      def passed?
+        @passed
+      end
+
+      def failed?
+        !@passed
+      end
+
+      def to_s
+        message
+      end
+
+      def inspect
+        "#<Reeve::Testing::Result #{check} #{passed? ? 'passed' : 'failed'} " \
+          "#{message.inspect}>"
+      end
+    end
+  end
+end

data/lib/reeve/testing.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "../reeve"
+require_relative "testing/result"
+require_relative "testing/report"
+require_relative "testing/ledger"
+require_relative "testing/checks"
+
+module Reeve
+  # The testing kit: framework-neutral checks, and thin front-ends over them.
+  #
+  #   require "reeve/testing"    # the checks, and nothing else
+  #   require "reeve/rspec"      # + matchers and the shared example group
+  #   require "reeve/minitest"   # + assertions and the compliance test case
+  #
+  # This file loads no test framework and no ActiveRecord, so the checks are runnable from
+  # a rake task, a CI script or a boot-time assertion in staging (FR-020, FR-026):
+  #
+  #   require "reeve/testing"
+  #   report = Reeve::Checks.run_all(principals: [alice, bob])
+  #   abort report.to_s unless report.passed?
+  module Testing
+    class << self
+      # The two fixture principals the compliance suite runs every tool against. Set once,
+      # in the host's test helper, and both front-ends' compliance suites pick it up:
+      #
+      #   Reeve::Testing.compliance_principals = -> { [users(:alice), users(:bob)] }
+      #
+      # A callable rather than a value, because in a Rails test suite the fixtures do not
+      # exist yet at the moment the helper is loaded.
+      attr_writer :compliance_principals
+
+      def compliance_principals
+        source = @compliance_principals || Reeve.config.compliance_principals
+        raise ConfigurationError, missing_principals_message if source.nil?
+
+        principals = Array(source.respond_to?(:call) ? source.call : source)
+        raise ConfigurationError, missing_principals_message if principals.size < 2
+
+        principals
+      end
+
+      def compliance_principals?
+        !(@compliance_principals || Reeve.config.compliance_principals).nil?
+      end
+
+      def reset!
+        @compliance_principals = nil
+      end
+
+      private
+
+      def missing_principals_message
+        "the reeve compliance suite needs two fixture principals with disjoint records. " \
+          "Set them in your test helper:\n\n  " \
+          "Reeve::Testing.compliance_principals = -> { [users(:alice), users(:bob)] }"
+      end
+    end
+  end
+end

data/lib/reeve/version.rb

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

data/lib/reeve.rb

@@ -1,12 +1,18 @@
 # frozen_string_literal: true
 
 require_relative "reeve/version"
+require_relative "reeve/errors"
+require_relative "reeve/decision"
+require_relative "reeve/configuration"
+require_relative "reeve/context"
+require_relative "reeve/scope_result"
+require_relative "reeve/invocation"
+require_relative "reeve/authorization"
 
 # Reeve — per-record authorization and an append-only audit ledger for the MCP tools
 # a Rails application exposes to AI agents.
 #
-# 0.0.1 is a placeholder release reserving the gem name. It has no functionality yet.
-# See https://github.com/vicmaster/reeve for progress.
+# The published 0.0.1 is a placeholder release reserving the gem name; the kernel below
+# is unreleased work in progress. See https://github.com/vicmaster/reeve.
 module Reeve
-  class Error < StandardError; end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: reeve
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Victor Velazquez
@@ -27,7 +27,57 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- lib/generators/reeve/install/install_generator.rb
+- lib/generators/reeve/install/templates/create_audit_entries.rb.tt
+- lib/generators/reeve/install/templates/initializer.rb.tt
 - lib/reeve.rb
+- lib/reeve/audit.rb
+- lib/reeve/audit/entry.rb
+- lib/reeve/audit/query.rb
+- lib/reeve/audit/recorder.rb
+- lib/reeve/audit/redactor.rb
+- lib/reeve/authorization.rb
+- lib/reeve/authorization/adapter.rb
+- lib/reeve/authorization/adapters/plain.rb
+- lib/reeve/authorization/adapters/pundit.rb
+- lib/reeve/authorization/authorizer.rb
+- lib/reeve/authorization/current.rb
+- lib/reeve/authorization/declaration.rb
+- lib/reeve/authorization/guard.rb
+- lib/reeve/authorization/registry.rb
+- lib/reeve/authorization/scoper.rb
+- lib/reeve/configuration.rb
+- lib/reeve/context.rb
+- lib/reeve/decision.rb
+- lib/reeve/errors.rb
+- lib/reeve/fast_mcp.rb
+- lib/reeve/integrations/fast_mcp/context_builder.rb
+- lib/reeve/integrations/fast_mcp/tool_extension.rb
+- lib/reeve/invocation.rb
+- lib/reeve/minitest.rb
+- lib/reeve/rspec.rb
+- lib/reeve/scope_result.rb
+- lib/reeve/testing.rb
+- lib/reeve/testing/assertions.rb
+- lib/reeve/testing/checks.rb
+- lib/reeve/testing/checks/audit_coverage.rb
+- lib/reeve/testing/checks/base.rb
+- lib/reeve/testing/checks/contract_version.rb
+- lib/reeve/testing/checks/cross_principal_leak.rb
+- lib/reeve/testing/checks/guard_declared.rb
+- lib/reeve/testing/checks/principal_required.rb
+- lib/reeve/testing/checks/redaction_holds.rb
+- lib/reeve/testing/checks/rule_present.rb
+- lib/reeve/testing/compliance_assertions.rb
+- lib/reeve/testing/compliance_suite.rb
+- lib/reeve/testing/ledger.rb
+- lib/reeve/testing/matchers.rb
+- lib/reeve/testing/matchers/audit_every_call.rb
+- lib/reeve/testing/matchers/base.rb
+- lib/reeve/testing/matchers/deny_access_for.rb
+- lib/reeve/testing/matchers/pass_reeve_check.rb
+- lib/reeve/testing/report.rb
+- lib/reeve/testing/result.rb
 - lib/reeve/version.rb
 homepage: https://github.com/vicmaster/reeve
 licenses:
@@ -37,6 +87,7 @@ metadata:
   source_code_uri: https://github.com/vicmaster/reeve
   changelog_uri: https://github.com/vicmaster/reeve/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/vicmaster/reeve/issues
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths: