sidenotes 0.1.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8ae9eac3b04b22f97ed8449628befa33a88bfa94ac1e3533a62290ffffb1a32
-  data.tar.gz: 81616ba19442a2b9dbae04a494d092cd93f998aaf5fb2a105f75a0fbfb059b16
+  metadata.gz: 49cfca99965003c2f6fbff02ac2d9a930671bec5bb36f0cafecbb03e8c2e47f1
+  data.tar.gz: 505db15a10c3df2c3af8d3d3425d1cb3ea4580faf22a24fe0ba10a48dd0c432d
 SHA512:
-  metadata.gz: 668ef3a9a5bbdb367fce80df121953c503f8ac4f948ba246eb1cf297ad620adba89e8e9e97a9a4bf8bb8d518f052fd4a6cbb79090099a1e8541f2ab19cce6a14
-  data.tar.gz: 5bad7f9f8f5f6673938f93e85711d7782b0abe180c49e4f7ba3d14047f729bd868b7e095ee1263c663d83ff728d6eed0f936b933cefd1ea03145c1bcf58f6ebb
+  metadata.gz: 042f58ab4161438219e6980cd8637bb07395e91bd4240e1c7bc729362c3a27d99b0d67cd2ff91c17103a58deb2fd6fa830de42749bdc1bceadc44fd7c7fb6334
+  data.tar.gz: 6e621545a5d90913fa388317bec1fc84bd75c7f0e2407be88f701eeff6d4d957a5f1b949379475b4ae4668edecf6af72dfd42db3adebb19b1b58fdde5f7ff808

data/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-05-01
+
+### Added
+
+- `sidenotes:verify` now detects pending migrations and reports them as drift (exits 1). This catches the case where a migration file exists but hasn't been applied, where the sidecars and DB happen to match but the test suite would later fail with `ActiveRecord::PendingMigrationError`.
+- Verifier API: `Sidenotes::Verifier#pending_migrations`, `#pending_migrations?`
+
+### Changed
+
+- `Verifier#drift?` and `#issue_count` now include pending migrations.
+- Migration context lookup supports both pre-7.2 (`connection.migration_context`) and 7.2+ (`connection_pool.migration_context`) APIs.
+
+## [0.2.0] - 2026-04-29
+
+### Added
+
+- `sidenotes:verify` rake task that compares sidecar files against the database schema, reports drift, and exits non-zero on mismatch (suitable for CI)
+- `Sidenotes::Verifier` class for programmatic drift detection
+- `auto_generate_after_migrate` configuration option that hooks into `db:migrate`, `db:migrate:up`, `db:migrate:down`, and `db:rollback` to regenerate annotations automatically
+- `SIDENOTES_AUTO_GENERATE` env var as a zero-config alternative to the configuration flag
+
 ## [0.1.0] - 2026-04-08
 
 ### Added

data/README.md

@@ -73,6 +73,37 @@ rake sidenotes:model MODEL=User
 rake sidenotes:clean
 ```
 
+### Verify annotations match the database
+
+```bash
+rake sidenotes:verify
+```
+
+Compares each `.annotations/` sidecar file against the live database schema and reports drift (missing/extra columns, indexes, associations, foreign keys, or models without sidecars). It also surfaces **pending migrations** — if a migration file exists but hasn't been applied, sidenotes flags it before doing the schema comparison, since the test suite would fail later anyway. Exits with status `1` if any drift or pending migrations are detected, making it suitable for CI:
+
+```yaml
+# .github/workflows/ci.yml
+- run: bundle exec rake sidenotes:verify
+```
+
+### Auto-regenerate after migrations
+
+Sidenotes can hook into `db:migrate`, `db:migrate:up`, `db:migrate:down`, and `db:rollback` so annotations stay in sync with your schema automatically. Enable it in your initializer:
+
+```ruby
+Sidenotes.configure do |config|
+  config.auto_generate_after_migrate = true
+end
+```
+
+Or via environment variable, no initializer required:
+
+```bash
+SIDENOTES_AUTO_GENERATE=true bin/rails db:migrate
+```
+
+When enabled, every successful migration triggers `sidenotes:generate` automatically. Keep this opt-in so it doesn't run in CI or production environments unintentionally.
+
 ### Example output
 
 Running `rake sidenotes:generate` creates `.annotations/user.yml`:

data/lib/generators/sidenotes/templates/initializer.rb

@@ -18,4 +18,8 @@ Sidenotes.configure do |config|
 
   # Patterns to exclude models (strings or regexps)
   # config.exclude_patterns = ["ApplicationRecord", /^HABTM_/]
+
+  # Auto-regenerate annotations after db:migrate, db:rollback, etc.
+  # Can also be enabled via the SIDENOTES_AUTO_GENERATE=true env var.
+  # config.auto_generate_after_migrate = true
 end

data/lib/sidenotes/configuration.rb

@@ -7,7 +7,7 @@ module Sidenotes
     DEFAULT_SECTIONS = %i[columns indexes associations foreign_keys metadata].freeze
 
     attr_reader :output_directory, :format, :sections
-    attr_accessor :model_paths, :exclude_patterns
+    attr_accessor :model_paths, :exclude_patterns, :auto_generate_after_migrate
 
     def initialize
       @output_directory = '.annotations'
@@ -15,6 +15,11 @@ module Sidenotes
       @sections = DEFAULT_SECTIONS.dup
       @model_paths = ['app/models']
       @exclude_patterns = []
+      @auto_generate_after_migrate = false
+    end
+
+    def auto_generate_after_migrate?
+      auto_generate_after_migrate || ENV['SIDENOTES_AUTO_GENERATE'] == 'true'
     end
 
     def format=(value)

data/lib/sidenotes/railtie.rb

@@ -2,6 +2,8 @@
 
 module Sidenotes
   class Railtie < Rails::Railtie
+    MIGRATE_TASKS = %w[db:migrate db:migrate:up db:migrate:down db:rollback].freeze
+
     rake_tasks do
       namespace :sidenotes do
         desc 'Generate annotation files for all models'
@@ -19,7 +21,14 @@ module Sidenotes
         task model: :environment do
           Sidenotes::Railtie.run_model
         end
+
+        desc 'Verify annotation files match the database schema (exits 1 on drift)'
+        task verify: :environment do
+          Sidenotes::Railtie.run_verify
+        end
       end
+
+      Sidenotes::Railtie.install_migrate_hooks if Sidenotes.configuration.auto_generate_after_migrate?
     end
 
     def self.run_generate
@@ -48,5 +57,61 @@ module Sidenotes
         puts "Sidenotes: Could not generate annotation for #{model_name}"
       end
     end
+
+    def self.run_verify
+      verifier = Sidenotes::Verifier.new.verify_all
+      print_verify_report(verifier)
+      exit(1) if verifier.drift?
+    end
+
+    def self.print_verify_report(verifier)
+      puts "Checking #{verifier.checked_count} model annotations against database..."
+      puts
+
+      print_pending_migrations(verifier) if verifier.pending_migrations?
+      print_drifts(verifier)
+      print_missing_sidecars(verifier)
+      print_summary(verifier)
+    end
+
+    def self.print_pending_migrations(verifier)
+      puts '  PENDING MIGRATIONS detected (run `rails db:migrate` first):'
+      verifier.pending_migrations.each do |m|
+        puts "    - #{m['version']} #{m['name']}"
+      end
+      puts
+    end
+
+    def self.print_drifts(verifier)
+      verifier.drifts.each do |drift|
+        puts "  #{File.basename(drift.sidecar_path)} - DRIFT:"
+        drift.issues.each { |issue| puts "    #{issue}" }
+        puts
+      end
+    end
+
+    def self.print_missing_sidecars(verifier)
+      verifier.missing_sidecars.each do |name|
+        puts "  #{name} - MISSING (model exists, no sidecar file)"
+      end
+    end
+
+    def self.print_summary(verifier)
+      if verifier.drift?
+        puts "#{verifier.issue_count} issue(s) found. Run `rake db:migrate && rake sidenotes:generate` to update."
+      else
+        puts 'All annotations are up to date.'
+      end
+    end
+
+    def self.install_migrate_hooks
+      MIGRATE_TASKS.each do |task_name|
+        next unless Rake::Task.task_defined?(task_name)
+
+        Rake::Task[task_name].enhance do
+          Rake::Task['sidenotes:generate'].invoke if Rake::Task.task_defined?('sidenotes:generate')
+        end
+      end
+    end
   end
 end

data/lib/sidenotes/verifier.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'json'
+
+module Sidenotes
+  class Verifier
+    Drift = Struct.new(:model_name, :sidecar_path, :issues, keyword_init: true)
+
+    attr_reader :drifts, :missing_sidecars, :checked_count, :pending_migrations
+
+    def initialize
+      @drifts = []
+      @missing_sidecars = []
+      @checked_count = 0
+      @pending_migrations = []
+    end
+
+    def verify_all
+      check_pending_migrations
+      generator = Generator.new
+      generator.discover_models.each { |model| verify_model(model) }
+      self
+    end
+
+    def check_pending_migrations
+      context = migration_context
+      return unless context.respond_to?(:pending_migrations)
+
+      @pending_migrations = context.pending_migrations.map do |m|
+        { 'version' => m.version, 'name' => m.name }
+      end
+    rescue StandardError => e
+      warn "Sidenotes: could not check pending migrations: #{e.message}"
+    end
+
+    def pending_migrations?
+      pending_migrations.any?
+    end
+
+    def verify_model(model)
+      inspector = ModelInspector.new(model)
+      return unless inspector.inspectable?
+
+      @checked_count += 1
+      sidecar = sidecar_path_for(model)
+
+      unless File.exist?(sidecar)
+        @missing_sidecars << model.name
+        return
+      end
+
+      stored = parse_sidecar(sidecar, model.name)
+      current = inspector.inspect_model
+      issues = compare(stored, current)
+
+      return if issues.empty?
+
+      @drifts << Drift.new(model_name: model.name, sidecar_path: sidecar, issues: issues)
+    end
+
+    def drift?
+      drifts.any? || missing_sidecars.any? || pending_migrations?
+    end
+
+    def issue_count
+      drifts.sum { |d| d.issues.size } + missing_sidecars.size + pending_migrations.size
+    end
+
+    private
+
+    def migration_context
+      return nil unless defined?(ActiveRecord::Base)
+
+      pool = ActiveRecord::Base.connection_pool
+      return pool.migration_context if pool.respond_to?(:migration_context)
+
+      conn = ActiveRecord::Base.connection
+      return conn.migration_context if conn.respond_to?(:migration_context)
+
+      nil
+    rescue StandardError
+      nil
+    end
+
+    def sidecar_path_for(model)
+      config = Sidenotes.configuration
+      File.join(config.output_directory, "#{model.name.underscore}.#{config.file_extension}")
+    end
+
+    def parse_sidecar(path, model_name)
+      content = File.read(path)
+      parsed = case Sidenotes.configuration.format
+               when :yaml then YAML.safe_load(strip_yaml_header(content), permitted_classes: [Symbol])
+               when :json then JSON.parse(content)
+               end
+      parsed[model_name] || {}
+    end
+
+    def strip_yaml_header(content)
+      content.lines.reject { |l| l.start_with?('#') }.join
+    end
+
+    def compare(stored, current)
+      issues = []
+      issues.concat(diff_columns(stored['columns'], current['columns'])) if current.key?('columns')
+      issues.concat(diff_indexes(stored['indexes'], current['indexes'])) if current.key?('indexes')
+      if current.key?('foreign_keys')
+        issues.concat(diff_named_list(stored['foreign_keys'], current['foreign_keys'], 'foreign_key',
+                                      'name'))
+      end
+      issues.concat(diff_associations(stored['associations'], current['associations'])) if current.key?('associations')
+      issues
+    end
+
+    def diff_columns(stored, current)
+      stored_by_name = (stored || []).to_h { |c| [c['name'], c] }
+      current_by_name = current.to_h { |c| [c['name'], c] }
+
+      added = (current_by_name.keys - stored_by_name.keys).map do |name|
+        "+ missing column: #{name} (#{current_by_name[name]['type']})"
+      end
+      removed = (stored_by_name.keys - current_by_name.keys).map do |name|
+        "- extra column: #{name} (no longer in schema)"
+      end
+      changed = column_type_changes(stored_by_name, current_by_name)
+
+      added + removed + changed
+    end
+
+    def column_type_changes(stored_by_name, current_by_name)
+      (stored_by_name.keys & current_by_name.keys).filter_map do |name|
+        s = stored_by_name[name]
+        c = current_by_name[name]
+        "~ column changed: #{name} (#{s['type']} -> #{c['type']})" if s['type'] != c['type']
+      end
+    end
+
+    def diff_indexes(stored, current)
+      stored ||= []
+      stored_names = stored.map { |i| i['name'] }
+      current_names = current.map { |i| i['name'] }
+
+      issues = (current_names - stored_names).map { |n| "+ missing index: #{n}" }
+      (stored_names - current_names).each { |n| issues << "- extra index: #{n} (no longer in schema)" }
+      issues
+    end
+
+    def diff_associations(stored, current)
+      stored ||= []
+      stored_keys = stored.map { |a| "#{a['type']}:#{a['name']}" }
+      current_keys = current.map { |a| "#{a['type']}:#{a['name']}" }
+
+      issues = (current_keys - stored_keys).map { |k| "+ missing association: #{k}" }
+      (stored_keys - current_keys).each { |k| issues << "- extra association: #{k} (no longer defined)" }
+      issues
+    end
+
+    def diff_named_list(stored, current, label, key)
+      stored ||= []
+      stored_names = stored.map { |i| i[key] }.compact
+      current_names = current.map { |i| i[key] }.compact
+
+      issues = (current_names - stored_names).map { |n| "+ missing #{label}: #{n}" }
+      (stored_names - current_names).each { |n| issues << "- extra #{label}: #{n} (no longer in schema)" }
+      issues
+    end
+  end
+end

data/lib/sidenotes/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sidenotes
-  VERSION = '0.1.2'
+  VERSION = '0.2.1'
 end

data/lib/sidenotes.rb

@@ -5,6 +5,7 @@ require_relative 'sidenotes/configuration'
 require_relative 'sidenotes/model_inspector'
 require_relative 'sidenotes/formatter'
 require_relative 'sidenotes/generator'
+require_relative 'sidenotes/verifier'
 
 module Sidenotes
   class Error < StandardError; end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sidenotes
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.1
 platform: ruby
 authors:
 - Wes Mason
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-09 00:00:00.000000000 Z
+date: 2026-05-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -74,6 +74,7 @@ files:
 - lib/sidenotes/generator.rb
 - lib/sidenotes/model_inspector.rb
 - lib/sidenotes/railtie.rb
+- lib/sidenotes/verifier.rb
 - lib/sidenotes/version.rb
 homepage: https://github.com/1stvamp/sidenotes-ruby
 licenses: