sidenotes 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8ae9eac3b04b22f97ed8449628befa33a88bfa94ac1e3533a62290ffffb1a32
-  data.tar.gz: 81616ba19442a2b9dbae04a494d092cd93f998aaf5fb2a105f75a0fbfb059b16
+  metadata.gz: 24381f7028cc342a69f1b713f2604ae0a0bdc829d675f8f866241550e13b4440
+  data.tar.gz: 384a71a3b65bf767fd3634a84e03125329cb72fb5638dd29a9160a3f157e9bca
 SHA512:
-  metadata.gz: 668ef3a9a5bbdb367fce80df121953c503f8ac4f948ba246eb1cf297ad620adba89e8e9e97a9a4bf8bb8d518f052fd4a6cbb79090099a1e8541f2ab19cce6a14
-  data.tar.gz: 5bad7f9f8f5f6673938f93e85711d7782b0abe180c49e4f7ba3d14047f729bd868b7e095ee1263c663d83ff728d6eed0f936b933cefd1ea03145c1bcf58f6ebb
+  metadata.gz: 23c955f99d8e8c4f46c221cc96332907ba20dd6492271eb176ce2ca07a40842a460720b17f8294acdc929980e59b014706acf4ac8363c405708df4864d07c368
+  data.tar.gz: 8a37de79dc70a7e941845485b2435bbabf9580fc07caaa6db9c86a4f55204fd3d84cbc01c23be1196c87715a83c52b6daae899e6c41061bd953ac6a8e6063ecb

data/CHANGELOG.md

@@ -5,6 +5,15 @@ 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.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). Exits with status `1` if any drift is 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,42 @@ 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
+
+      verifier.drifts.each do |drift|
+        puts "  #{File.basename(drift.sidecar_path)} - DRIFT:"
+        drift.issues.each { |issue| puts "    #{issue}" }
+        puts
+      end
+
+      verifier.missing_sidecars.each do |name|
+        puts "  #{name} - MISSING (model exists, no sidecar file)"
+      end
+
+      if verifier.drift?
+        puts "#{verifier.issue_count} issue(s) found. Run `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,138 @@
+# 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
+
+    def initialize
+      @drifts = []
+      @missing_sidecars = []
+      @checked_count = 0
+    end
+
+    def verify_all
+      generator = Generator.new
+      generator.discover_models.each { |model| verify_model(model) }
+      self
+    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?
+    end
+
+    def issue_count
+      drifts.sum { |d| d.issues.size } + missing_sidecars.size
+    end
+
+    private
+
+    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.0'
 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.0
 platform: ruby
 authors:
 - Wes Mason
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-09 00:00:00.000000000 Z
+date: 2026-04-29 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: