revisable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4a689bd4a025ca4964e233c27e82610dac766a357638cd238881a8aa3df70ab9
+  data.tar.gz: e699b99e853085603d3bf24a3afb2c70fa86202adc91b5ec5457aecd28f95ebe
+SHA512:
+  metadata.gz: b99e4b430666ee6f134c2faea2954ea3470572a82142dcc51c438abf19215d8883a1eb6391948deeaa559df747d37bcadd5020fa05679ac3f46a70f98aa42305
+  data.tar.gz: 7acc9f61e70b786d074626b1911dd4925cd603f3217ae5a16d6881a057d1b01cb3e066bf9bc98c893e9193de2140331b0f520ee26c6cf6e545d44f1697eadfc6

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Brad Gessler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,309 @@
+# Revisable
+
+Git-like versioning for ActiveRecord text content. Branches, merges, diffs, tags, and publishing — in your database.
+
+## Why not PaperTrail / Audited / Logidze?
+
+Every existing Rails versioning gem gives you a **linear audit log**. That's fine for tracking "who changed what when," but it falls apart when you need real content workflows:
+
+| | PaperTrail | Audited | Logidze | **Revisable** |
+|---|---|---|---|---|
+| Branching | No | No | No | **Yes** |
+| Merging | No | No | No | **Yes** |
+| Diffing | Adjacent only | No | Between versions | **Any two refs** |
+| Tags / named versions | No | No | No | **Yes** |
+| Content deduplication | No | No | No | **SHA-based** |
+| Publish workflow | No | No | No | **Tag → publish** |
+| Storage model | Full snapshots | After-state | Incremental JSON | **Content-addressed blobs** |
+
+PaperTrail and friends answer "what happened?" Revisable answers "what's the state of this content, on this branch, and how does it differ from that branch?"
+
+### When to use Revisable
+
+You're building a CMS, docs site, legal document system, or any app where **content goes through drafts, review, and publishing**. Multiple people might edit the same article. You want to see diffs, branch off drafts, and tag releases.
+
+### When to use PaperTrail
+
+You want an audit log for compliance. You need to know that `user_42` changed `price` from `19.99` to `24.99` at 3:47pm. Linear history is fine. You don't need branches or diffs.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "revisable"
+```
+
+Generate the migration:
+
+```bash
+rails generate revisable:install
+rails db:migrate
+```
+
+## Setup
+
+```ruby
+class Post < ApplicationRecord
+  include Revisable::Model
+  revisable :title, :body
+end
+```
+
+That's it. Any text/string columns you pass to `revisable` get git-like version control.
+
+## ActiveRecord Integration
+
+### Auto-commit on save
+
+Revisable hooks into `after_create` and `after_update`. When you save a model with revisable fields, a commit is created automatically:
+
+```ruby
+post = Post.create!(title: "First Draft", body: "Hello world")
+# => auto-creates initial commit on "main"
+
+post.update!(title: "Better Title")
+# => auto-creates commit "Updated title" on "main"
+
+post.repository.log("main").map(&:message)
+# => ["Updated title", "Initial version"]
+```
+
+To disable auto-commit (for models where you want manual control):
+
+```ruby
+class LegalDocument < ApplicationRecord
+  include Revisable::Model
+  revisable :content, :summary, auto_commit: false
+end
+```
+
+### Author tracking
+
+Set the current author in your controller so auto-commits know who made the change:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Revisable::ActiveRecord::ControllerHelpers
+
+  private
+
+  def revisable_author
+    current_user
+  end
+end
+```
+
+Now every save within a request automatically records the author:
+
+```ruby
+post.update!(title: "New Title")
+post.repository.log("main").first.author  # => #<User id: 1, name: "Alice">
+```
+
+You can also set the author explicitly for background jobs or console work:
+
+```ruby
+Revisable::CurrentAuthor.with(admin_user) do
+  post.update!(body: "Bulk-edited content")
+end
+```
+
+## Usage
+
+### Manual commits
+
+For more control, use the repository directly. Pass only the fields that changed — unchanged fields carry forward automatically.
+
+```ruby
+repo = post.repository
+
+repo.commit!(
+  message: "First draft",
+  author: current_user,
+  fields: { title: "How to Deploy Rails", body: "# Step 1\n..." }
+)
+
+# Later, update just the body
+repo.commit!(
+  message: "Added step 2",
+  author: current_user,
+  fields: { body: "# Step 1\n...\n# Step 2\n..." }
+)
+```
+
+Content is stored as SHA-256 addressed blobs. If you revert a title to a previous value, no new storage is used — it points to the existing blob.
+
+### Reading
+
+```ruby
+# Read current state of any branch or tag
+snapshot = repo.at("main")
+snapshot.title  # => "How to Deploy Rails"
+snapshot.body   # => "# Step 1\n..."
+snapshot.to_h   # => { title: "...", body: "..." }
+
+# Read by tag or SHA
+repo.at("v2").title
+repo.at("abc123").title
+```
+
+### Branching
+
+```ruby
+repo.branch!("amy-draft", from: "main")
+
+repo.commit!(
+  branch: "amy-draft",
+  message: "Rewrote intro",
+  author: amy,
+  fields: { body: "# Better intro\n..." }
+)
+
+# main is untouched
+repo.at("main").body   # => original
+repo.at("amy-draft").body  # => rewritten
+```
+
+### Diffing
+
+Compare any two refs, commits, or tags. Diffs are field-level — blob SHAs are compared first, so unchanged fields skip text diffing entirely.
+
+```ruby
+diff = repo.diff("main", "amy-draft")
+
+diff.changed?           # => true
+diff.changed_fields     # => [:body]
+
+diff.field(:title).status  # => :unchanged
+diff.field(:body).status   # => :modified
+
+# Unified text diff (like `git diff`)
+puts diff.field(:body).to_text
+# --- a/body
+# +++ b/body
+# -# Step 1
+# +# Better intro
+
+# HTML diff (for web UIs)
+diff.field(:body).to_html
+# <div class="revisable-diff" data-field="body">
+#   <del># Step 1</del>
+#   <ins># Better intro</ins>
+# </div>
+
+# Combined diff across all fields
+diff.to_text
+diff.to_html
+```
+
+### Merging
+
+Three-way merge using the common ancestor. Fields that only changed on one side auto-resolve. Fields changed on both sides are conflicts.
+
+```ruby
+merge = repo.merge("amy-draft", into: "main")
+
+merge.clean?        # => false
+merge.conflicts     # => [:body]
+merge.auto_resolved # => [:title]
+
+# Inspect a conflict — each field is a MergeField object
+field = merge.field(:body)
+field.status      # => :conflicted
+field.ours        # => main's version
+field.theirs      # => amy-draft's version
+field.ancestor    # => common ancestor
+
+# Resolve it (on the field directly, or via the merge)
+field.resolve("hand-written resolution")
+field.resolve(:ours)     # pick main's version
+field.resolve(:theirs)   # pick amy's version
+
+# Or resolve all conflicts at once
+merge.each do |name, f|
+  f.resolve(:theirs) if f.conflicted?
+end
+
+# Commit the merge (creates a two-parent commit)
+merge.commit!(repository: repo, author: current_user, message: "Merged Amy's draft")
+```
+
+### Tags and publishing
+
+Tags are immutable pointers to a commit. Publishing materializes a tag's content into the model's actual columns — so your views and APIs read plain ActiveRecord attributes with zero versioning overhead.
+
+```ruby
+# Tag the current state of main
+repo.tag!("v1", ref: "main", message: "Launch version")
+
+# More editing happens on main...
+repo.commit!(message: "Post-launch tweaks", fields: { body: "..." })
+
+# Readers still see v1 until you publish
+repo.publish!("v1")
+
+# post.title and post.body now reflect v1
+# Your views just do: @post.title — no versioning API needed
+
+# Publish latest tag
+repo.publish!
+```
+
+### Log
+
+```ruby
+log = repo.log("main")              # => Log (Enumerable)
+log = repo.log("main", limit: 10)   # => last 10
+
+# Log is enumerable
+log.map(&:message)    # => ["Added step 2", "First draft"]
+log.first             # => most recent Commit
+log.to_text           # => "* a1b2c3 Added step 2\n* f4e5d6 First draft"
+
+# Commit objects
+commit = log.first
+commit.sha            # => "a1b2c3..."
+commit.message        # => "Added step 2"
+commit.author         # => #<User id: 1, name: "Alice">
+commit.committed_at   # => 2026-03-21 14:30:00 UTC
+commit.parents        # => [#<Commit ...>]
+commit.merge?         # => false
+commit.root?          # => false
+```
+
+## How it works
+
+Revisable uses the same conceptual model as git, minus the parts you don't need in a database:
+
+| Git concept | Revisable equivalent | Notes |
+|---|---|---|
+| Blob | `revisable_blobs` | SHA-256 content-addressed. Identical content = one row. |
+| Tree | — | Skipped. Fields are flat, not nested directories. |
+| Commit | `revisable_commits` | Polymorphic author, parent links, scoped to a record. |
+| Tree entries | `revisable_commit_fields` | Each commit stores a blob SHA for every revisable field. |
+| Ref | `revisable_refs` | Branches and tags. Compare-and-swap updates for concurrency. |
+| Packfile | — | Not needed. Postgres handles storage. |
+| Index / staging | — | Not needed. Every `commit!` is direct. |
+
+Each commit stores **full state** (a blob SHA for every field), not deltas. This means you can read any commit without walking history. Unchanged fields reuse the same blob SHA, so storage cost is minimal.
+
+## Schema
+
+Revisable creates 5 tables. Run `rails generate revisable:install` to get the migration:
+
+- **`revisable_blobs`** — content-addressed text storage
+- **`revisable_commits`** — commit metadata, polymorphic to any model
+- **`revisable_commit_parents`** — parent links (supports merge commits with 2+ parents)
+- **`revisable_commit_fields`** — maps each commit × field to a blob
+- **`revisable_refs`** — branches and tags per record
+
+All tables are polymorphic — one set of tables serves every model that uses `revisable`.
+
+## Concurrency
+
+Branch refs use compare-and-swap updates. If two writers commit to the same branch simultaneously, the second one gets a `Revisable::StaleRefError` and can retry. At CMS-level write volumes this is rarely hit, but it's there.
+
+## License
+
+MIT

data/lib/generators/revisable/install_generator.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Revisable
+  class InstallGenerator < Rails::Generators::Base
+    include ActiveRecord::Generators::Migration
+
+    source_root File.expand_path("templates", __dir__)
+
+    def create_migration_file
+      migration_template "create_revisable_tables.rb.erb", "db/migrate/create_revisable_tables.rb"
+    end
+  end
+end

data/lib/generators/revisable/templates/create_revisable_tables.rb.erb

@@ -0,0 +1,57 @@
+class CreateRevisableTables < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :revisable_blobs, id: :bigint do |t|
+      t.string :sha, null: false, index: { unique: true }
+      t.text :data, null: false
+      t.integer :size, null: false
+      t.timestamps
+    end
+
+    create_table :revisable_commits, id: :bigint do |t|
+      t.string :sha, null: false, index: { unique: true }
+      t.string :versionable_type, null: false
+      t.bigint :versionable_id, null: false
+      t.string :author_type
+      t.bigint :author_id
+      t.string :message, null: false
+      t.datetime :committed_at, null: false
+      t.timestamps
+    end
+
+    add_index :revisable_commits, [:versionable_type, :versionable_id]
+    add_index :revisable_commits, [:author_type, :author_id]
+
+    create_table :revisable_commit_parents, id: :bigint do |t|
+      t.string :commit_sha, null: false
+      t.string :parent_sha, null: false
+      t.integer :position, null: false, default: 0
+    end
+
+    add_index :revisable_commit_parents, :commit_sha
+    add_index :revisable_commit_parents, :parent_sha
+
+    create_table :revisable_commit_fields, id: :bigint do |t|
+      t.string :commit_sha, null: false
+      t.string :field_name, null: false
+      t.string :blob_sha, null: false
+    end
+
+    add_index :revisable_commit_fields, :commit_sha
+    add_index :revisable_commit_fields, :blob_sha
+    add_index :revisable_commit_fields, [:commit_sha, :field_name], unique: true
+
+    create_table :revisable_refs, id: :bigint do |t|
+      t.string :versionable_type, null: false
+      t.bigint :versionable_id, null: false
+      t.string :name, null: false
+      t.string :ref_type, null: false
+      t.string :commit_sha, null: false
+      t.string :message
+      t.timestamps
+    end
+
+    add_index :revisable_refs, [:versionable_type, :versionable_id, :ref_type, :name],
+              unique: true, name: "index_revisable_refs_on_versionable_and_type_and_name"
+    add_index :revisable_refs, :commit_sha
+  end
+end

data/lib/revisable/active_record/controller_helpers.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Revisable
+  module ActiveRecord
+    module ControllerHelpers
+      extend ActiveSupport::Concern
+
+      included do
+        around_action :revisable_set_author, if: :revisable_author
+      end
+
+      private
+
+      def revisable_set_author(&block)
+        Revisable::CurrentAuthor.with(revisable_author, &block)
+      end
+
+      # Override in your controller to provide the current user
+      # Example:
+      #   def revisable_author
+      #     current_user
+      #   end
+      def revisable_author
+        nil
+      end
+    end
+  end
+end

data/lib/revisable/blob.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "digest/sha2"
+
+module Revisable
+  class Blob < ActiveRecord::Base
+    self.table_name = "revisable_blobs"
+
+    validates :sha, presence: true, uniqueness: true
+    validates :data, presence: true
+    validates :size, presence: true
+
+    def self.store(content)
+      content = content.to_s
+      sha = compute_sha(content)
+
+      find_or_create_by!(sha: sha) do |blob|
+        blob.data = content
+        blob.size = content.bytesize
+      end
+    end
+
+    def self.compute_sha(content)
+      Digest::SHA256.hexdigest(content.to_s)
+    end
+  end
+end

data/lib/revisable/branch.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Revisable
+  class Branch
+    attr_reader :ref
+
+    def initialize(ref)
+      @ref = ref
+    end
+
+    def name
+      ref.name
+    end
+
+    def commit
+      ref.commit
+    end
+
+    def commit_sha
+      ref.commit_sha
+    end
+
+    def tip(fields:)
+      Snapshot.new(commit: commit, fields: fields)
+    end
+
+    def to_s
+      name
+    end
+
+    def ==(other)
+      other.is_a?(Branch) && name == other.name && commit_sha == other.commit_sha
+    end
+  end
+end

data/lib/revisable/commit.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "digest/sha2"
+
+module Revisable
+  class Commit < ActiveRecord::Base
+    self.table_name = "revisable_commits"
+
+    belongs_to :versionable, polymorphic: true
+    belongs_to :author, polymorphic: true, optional: true
+
+    has_many :commit_fields,
+      class_name: "Revisable::CommitField",
+      foreign_key: :commit_sha,
+      primary_key: :sha,
+      dependent: :destroy
+
+    has_many :parent_links,
+      class_name: "Revisable::CommitParent",
+      foreign_key: :commit_sha,
+      primary_key: :sha,
+      dependent: :destroy
+
+    validates :sha, presence: true, uniqueness: true
+    validates :message, presence: true
+
+    def parents
+      Commit.where(sha: parent_links.order(:position).pluck(:parent_sha))
+    end
+
+    def parent_shas
+      parent_links.order(:position).pluck(:parent_sha)
+    end
+
+    def root?
+      parent_links.empty?
+    end
+
+    def merge?
+      parent_links.count > 1
+    end
+
+    def snapshot(fields:)
+      Snapshot.new(commit: self, fields: fields)
+    end
+
+    def field_set
+      @field_set ||= begin
+        blobs = commit_fields.includes(:blob).each_with_object({}) do |cf, hash|
+          hash[cf.field_name.to_sym] = cf.blob
+        end
+        FieldSet.new(blobs)
+      end
+    end
+
+    def self.build_sha(parent_shas:, field_blobs:, message:, timestamp:)
+      parts = [
+        "parents:#{parent_shas.sort.join(',')}",
+        "fields:#{field_blobs.sort.map { |k, v| "#{k}:#{v}" }.join(',')}",
+        "message:#{message}",
+        "timestamp:#{timestamp.iso8601}"
+      ]
+      Digest::SHA256.hexdigest(parts.join("\n"))
+    end
+  end
+
+  class CommitParent < ActiveRecord::Base
+    self.table_name = "revisable_commit_parents"
+
+    belongs_to :commit,
+      class_name: "Revisable::Commit",
+      foreign_key: :commit_sha,
+      primary_key: :sha
+  end
+end

data/lib/revisable/commit_field.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Revisable
+  class CommitField < ActiveRecord::Base
+    self.table_name = "revisable_commit_fields"
+
+    belongs_to :commit,
+      class_name: "Revisable::Commit",
+      foreign_key: :commit_sha,
+      primary_key: :sha
+
+    belongs_to :blob,
+      class_name: "Revisable::Blob",
+      foreign_key: :blob_sha,
+      primary_key: :sha
+
+    validates :field_name, presence: true
+  end
+end

data/lib/revisable/current_author.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Revisable
+  module CurrentAuthor
+    def self.set(author)
+      Thread.current[:revisable_current_author] = author
+    end
+
+    def self.get
+      Thread.current[:revisable_current_author]
+    end
+
+    def self.clear
+      Thread.current[:revisable_current_author] = nil
+    end
+
+    def self.with(author)
+      previous = get
+      set(author)
+      yield
+    ensure
+      set(previous)
+    end
+  end
+end

data/lib/revisable/diff.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Revisable
+  class Diff
+    include Enumerable
+
+    attr_reader :commit_a, :commit_b
+
+    def initialize(commit_a:, commit_b:, versionable_fields:)
+      @commit_a = commit_a
+      @commit_b = commit_b
+      @fields_a = commit_a&.field_set || FieldSet.empty
+      @fields_b = commit_b&.field_set || FieldSet.empty
+      @versionable_fields = versionable_fields
+
+      @fields = build_field_diffs
+    end
+
+    def field(name)
+      @fields[name.to_sym]
+    end
+
+    def each(&block)
+      @fields.each(&block)
+    end
+
+    def changed?
+      @fields.values.any?(&:changed?)
+    end
+
+    def changed_fields
+      @fields.values.select(&:changed?)
+    end
+
+    def to_text
+      @fields.values
+        .select(&:changed?)
+        .map(&:to_text)
+        .join("\n\n")
+    end
+
+    def to_html
+      @fields.values
+        .select(&:changed?)
+        .map(&:to_html)
+        .join("\n")
+    end
+
+    private
+
+    def build_field_diffs
+      @versionable_fields.each_with_object({}) do |field, hash|
+        field = field.to_sym
+        hash[field] = FieldDiff.new(
+          field_name: field,
+          blob_a: @fields_a[field],
+          blob_b: @fields_b[field]
+        )
+      end
+    end
+  end
+end