annotato 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11a779fb4ddeec8b6cf9f7858f821104466a9a769e58e137245636b9d62d459f
-  data.tar.gz: 2addea232a4a29643a66dd29396bf3d56614f2ff7923d516aba48e7b6b3f2379
+  metadata.gz: a87fe0063a6a76448199f86495ad0dad9dbc1680681fc001e98a93736f54ac20
+  data.tar.gz: 65ad0aa21cba0c583e31f1de2246ca63889e59a5a6ec178e885bec58f0715dc2
 SHA512:
-  metadata.gz: 7a04edef5bb90afad0d50ebb18c4590dc73e6ee8902f73d9a592291855d8f78c591c2174799d31d904d0fc1347df25baeedbe0383e57af156c9e59c16a2661c4
-  data.tar.gz: 8bf3fee198f5c60ed40b85b6d89ce6eecd3723171a51874338a8702a3b7436e1894db2a92dc8f62a08be534d782e35040d2fe74a36042836e13a5d9d597743bb
+  metadata.gz: 24cd3aff9a33a461070e8dda327c3fc3c54467ee832b9f131cc20fb5646465729fd9b173f684e222f8c295d2d61fb3ac1e573e7c0b3574e9635a6655b33f41bc
+  data.tar.gz: 22b6d1dc87290ed155f142b6ce5a051e0df00c546885460c5e1afb1e5ee9bdde0094e030f77b9ef88b7c45b488821abab141bf081fcd5dc27121597d06a6869e

data/.gitignore

@@ -9,3 +9,4 @@
 
 # rspec failure tracking
 .rspec_status
+gemfiles/*.lock

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-14
+
+### Fixed
+
+- Replacing a legacy `annotate` block above a `module`-wrapped class no longer deletes the rest of the file
+- Never write into model files outside the application (engines, gems, `vendor/`); skip anonymous classes and HABTM join models
+- MySQL, Trilogy and SQLite no longer crash on PostgreSQL-only enum queries; SQLite triggers are now listed
+- Check constraints are skipped on adapters/Rails versions that don't support them
+- Models on a secondary database are annotated from their own connection
+- `rake "annotato:models[User,Post]"` annotates every listed model; unknown names are skipped with a warning
+- Columns whose only unique index is partial are marked `unique (partial)` instead of `unique`
+- JSON defaults are rendered as valid JSON (numbers, nested values, `null`, escaped quotes)
+- Tables without columns no longer crash; SQL is never wrapped inside a quoted literal
+
+### Added
+
+- `rake annotato:check` for CI: fails when annotations are missing or outdated
+- Database function defaults (`default(now())`), generated columns (`generated(...)`), table comments, index method / order / `INCLUDE` / `NULLS NOT DISTINCT`
+- `MODEL` environment variable for `annotato:models`
+- `ANNOTATO_SKIP=1` to disable automatic annotation after migrations
+
+### Changed
+
+- Automatic annotation after migrations now runs only in development, and also after `db:rollback` and per-database migrate tasks
+- Model files are written atomically
+- Depends on `activerecord` and `railties` (>= 6.1) instead of the whole `rails` gem
+
 ## [0.1.0] - 2025-05-16
 
 - Initial release

data/Gemfile

@@ -13,4 +13,5 @@ gem "rspec", "~> 3.0"
 group :development, :test do
   gem "simplecov", require: false
   gem "pry", require: false
+  gem "sqlite3", ">= 2.1"
 end

data/Gemfile.lock

@@ -1,32 +1,13 @@
 PATH
   remote: .
   specs:
-    annotato (0.2.5)
-      rails (>= 6.0)
+    annotato (0.3.0)
+      activerecord (>= 6.1)
+      railties (>= 6.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actioncable (8.0.2)
-      actionpack (= 8.0.2)
-      activesupport (= 8.0.2)
-      nio4r (~> 2.0)
-      websocket-driver (>= 0.6.1)
-      zeitwerk (~> 2.6)
-    actionmailbox (8.0.2)
-      actionpack (= 8.0.2)
-      activejob (= 8.0.2)
-      activerecord (= 8.0.2)
-      activestorage (= 8.0.2)
-      activesupport (= 8.0.2)
-      mail (>= 2.8.0)
-    actionmailer (8.0.2)
-      actionpack (= 8.0.2)
-      actionview (= 8.0.2)
-      activejob (= 8.0.2)
-      activesupport (= 8.0.2)
-      mail (>= 2.8.0)
-      rails-dom-testing (~> 2.2)
     actionpack (8.0.2)
       actionview (= 8.0.2)
       activesupport (= 8.0.2)
@@ -37,34 +18,18 @@ GEM
       rails-dom-testing (~> 2.2)
       rails-html-sanitizer (~> 1.6)
       useragent (~> 0.16)
-    actiontext (8.0.2)
-      actionpack (= 8.0.2)
-      activerecord (= 8.0.2)
-      activestorage (= 8.0.2)
-      activesupport (= 8.0.2)
-      globalid (>= 0.6.0)
-      nokogiri (>= 1.8.5)
     actionview (8.0.2)
       activesupport (= 8.0.2)
       builder (~> 3.1)
       erubi (~> 1.11)
       rails-dom-testing (~> 2.2)
       rails-html-sanitizer (~> 1.6)
-    activejob (8.0.2)
-      activesupport (= 8.0.2)
-      globalid (>= 0.3.6)
     activemodel (8.0.2)
       activesupport (= 8.0.2)
     activerecord (8.0.2)
       activemodel (= 8.0.2)
       activesupport (= 8.0.2)
       timeout (>= 0.4.0)
-    activestorage (8.0.2)
-      actionpack (= 8.0.2)
-      activejob (= 8.0.2)
-      activerecord (= 8.0.2)
-      activesupport (= 8.0.2)
-      marcel (~> 1.0)
     activesupport (8.0.2)
       base64
       benchmark (>= 0.3)
@@ -91,8 +56,6 @@ GEM
     docile (1.4.1)
     drb (2.2.1)
     erubi (1.13.1)
-    globalid (1.2.1)
-      activesupport (>= 6.1)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
     io-console (0.8.0)
@@ -104,25 +67,14 @@ GEM
     loofah (2.24.0)
       crass (~> 1.0.2)
       nokogiri (>= 1.12.0)
-    mail (2.8.1)
-      mini_mime (>= 0.1.1)
-      net-imap
-      net-pop
-      net-smtp
-    marcel (1.0.4)
     method_source (1.1.0)
-    mini_mime (1.1.5)
-    minitest (5.25.5)
-    net-imap (0.5.8)
-      date
-      net-protocol
-    net-pop (0.1.2)
-      net-protocol
-    net-protocol (0.2.2)
-      timeout
-    net-smtp (0.5.1)
-      net-protocol
-    nio4r (2.7.4)
+    mini_portile2 (2.8.9)
+    minitest (6.0.6)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    nokogiri (1.18.8)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
     nokogiri (1.18.8-arm64-darwin)
       racc (~> 1.4)
     nokogiri (1.18.8-x86_64-linux-gnu)
@@ -130,6 +82,7 @@ GEM
     pp (0.6.2)
       prettyprint
     prettyprint (0.2.0)
+    prism (1.9.0)
     pry (0.15.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
@@ -145,20 +98,6 @@ GEM
       rack (>= 1.3)
     rackup (2.2.1)
       rack (>= 3)
-    rails (8.0.2)
-      actioncable (= 8.0.2)
-      actionmailbox (= 8.0.2)
-      actionmailer (= 8.0.2)
-      actionpack (= 8.0.2)
-      actiontext (= 8.0.2)
-      actionview (= 8.0.2)
-      activejob (= 8.0.2)
-      activemodel (= 8.0.2)
-      activerecord (= 8.0.2)
-      activestorage (= 8.0.2)
-      activesupport (= 8.0.2)
-      bundler (>= 1.15.0)
-      railties (= 8.0.2)
     rails-dom-testing (2.2.0)
       activesupport (>= 5.0.0)
       minitest
@@ -199,6 +138,8 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.1)
     simplecov_json_formatter (0.1.4)
+    sqlite3 (2.9.6-arm64-darwin)
+    sqlite3 (2.9.6-x86_64-linux-gnu)
     stringio (3.1.7)
     thor (1.3.2)
     timeout (0.4.3)
@@ -206,10 +147,6 @@ GEM
       concurrent-ruby (~> 1.0)
     uri (1.0.3)
     useragent (0.16.11)
-    websocket-driver (0.7.7)
-      base64
-      websocket-extensions (>= 0.1.0)
-    websocket-extensions (0.1.5)
     zeitwerk (2.7.2)
 
 PLATFORMS
@@ -224,6 +161,7 @@ DEPENDENCIES
   rake (~> 13.0)
   rspec (~> 3.0)
   simplecov
+  sqlite3 (>= 2.1)
 
 BUNDLED WITH
    2.6.9

data/README.md

@@ -12,30 +12,42 @@
 * Annotates Rails models with:
 
   * Columns and types
-  * Default values and constraints
-  * Enums with values
-  * Indexes (only if present)
+  * Default values (including database functions like `now()`) and constraints
+  * Table and column comments
+  * PostgreSQL native enums with their values
+  * Indexes with method, order, `INCLUDE` and `WHERE` clauses (only if present)
   * Triggers (only if present)
   * Check Constraints (only if present)
-* Skips unchanged annotations
+* Works with PostgreSQL, MySQL/Trilogy and SQLite (enums are PostgreSQL-only)
+* Supports multiple databases (each model uses its own connection)
+* Skips unchanged annotations and replaces legacy `annotate` gem blocks
+* Only writes files inside your application (never engine or gem models)
 * Smart formatting with aligned columns
 
-Example:
+Example (the annotation is appended to the end of the model file):
 
 ```ruby
+class User < ApplicationRecord
+end
+
 # == Annotato Schema Info
 # Table: users
+# Comment: People who can log in
 #
 # Columns:
-#  id         :bigint           not null, primary key
-#  email      :string           not null, unique
-#  role       :string           default("user"), not null
+#  id         :bigint not null, primary key
+#  email      :character varying not null, unique
+#  role       :user_role default("member"), not null, enum
+#  created_at :timestamp(6) without time zone default(now()), not null
 #
 # Enums:
-#  role: { user, admin }
-
-class User < ApplicationRecord
-end
+#  role (user_role): [
+#    member,
+#    admin
+#  ]
+#
+# Indexes:
+#  index_users_on_email (email) unique
 ```
 
 ---
@@ -68,27 +80,51 @@ bundle exec rake annotato:models
 
 ### Annotate Specific Models
 
-You can now pass one or multiple model names to the task.
+You can pass one or multiple model names to the task, as task arguments or via `MODEL`.
 
 ```bash
 # Annotate only the User model
 rake annotato:models[User]
 
 # Annotate multiple models (User and Admin::Account)
-rake annotato:models["User,Admin::Account"]
+rake "annotato:models[User,Admin::Account]"
+MODEL=User,Admin::Account rake annotato:models
+```
+
+Unknown names are reported and skipped.
+
+### Check Annotations in CI
+
+`annotato:check` writes nothing and exits with a non-zero status if any annotation is missing or outdated:
+
+```bash
+bundle exec rake annotato:check
+```
+
+### Automatic Annotation After Migrations
+
+In the `development` environment, models are re-annotated automatically after
+`db:migrate`, `db:rollback` and their variants (`db:migrate:primary`, `db:migrate:up`, ...).
+Other environments (production, CI) never rewrite model files.
+
+To turn it off locally:
+
+```bash
+ANNOTATO_SKIP=1 rake db:migrate
 ```
 
 ---
 
-## Rake Task
+## Rake Tasks
 
 ```bash
 rake annotato:models[MODEL]
+rake annotato:check[MODEL]
 ```
 
 * Automatically loads all models via `Rails.application.eager_load!`
-* Modifies model files in place
-* Replace existing Annotato and legacy annotate blocks
+* Modifies model files in place (atomically, via a temp file)
+* Replaces existing Annotato and legacy annotate blocks
 * **Pass `MODEL` argument (single or comma-separated) to target specific models**
 
 ---

data/annotato.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
 
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject do |f|
-      f.match(%r{^(test|spec|features)/}) || f.start_with?(".github")
+      f.match(%r{^(test|spec|features|gemfiles)/}) || f.start_with?(".github")
     end
   end
 
@@ -30,5 +30,6 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "rails", ">= 6.0"
+  spec.add_dependency "activerecord", ">= 6.1"
+  spec.add_dependency "railties", ">= 6.1"
 end

data/lib/annotato/adapter.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Annotato
+  # Normalizes ActiveRecord adapter names ("PostgreSQL", "PostGIS", "Mysql2",
+  # "Trilogy", "SQLite", ...) into a small set of symbols.
+  module Adapter
+    def self.kind(conn)
+      case conn.adapter_name.downcase
+      when /postg/                    then :postgresql
+      when /mysql|trilogy/            then :mysql
+      when /sqlite/                   then :sqlite
+      end
+    end
+
+    def self.postgresql?(conn)
+      kind(conn) == :postgresql
+    end
+  end
+end

data/lib/annotato/annotation_builder.rb

@@ -11,18 +11,31 @@ require_relative "check_constraint_formatter"
 module Annotato
   class AnnotationBuilder
     def self.build(model)
-      conn = ActiveRecord::Base.connection
+      with_connection(model) { |conn| build_with(model, conn) }
+    end
+
+    # Uses the model's own connection (multi-database apps), and with_connection on
+    # Rails 7.2+ where holding a permanent connection is deprecated.
+    def self.with_connection(model, &block)
+      model.respond_to?(:with_connection) ? model.with_connection(&block) : yield(model.connection)
+    end
+    private_class_method :with_connection
+
+    def self.build_with(model, conn)
       table_name = model.table_name
+      pg_enums = EnumFormatter.pg_enums(conn)
 
       lines = []
       lines << "== Annotato Schema Info"
       lines << "Table: #{table_name}"
+      comment = conn.respond_to?(:table_comment) && conn.table_comment(table_name)
+      lines << "Comment: #{comment}" if comment && !comment.empty?
       lines << ""
 
       lines << "Columns:"
-      lines += ColumnFormatter.format(model, conn)
+      lines += ColumnFormatter.format(model, conn, pg_enums: pg_enums)
 
-      enums = EnumFormatter.format(conn, conn.columns(table_name))
+      enums = EnumFormatter.format(conn, conn.columns(table_name), pg_enums: pg_enums)
       unless enums.empty?
         lines << ""
         lines << "Enums:"
@@ -52,5 +65,6 @@ module Annotato
 
       LineFormatter.format(lines)
     end
+    private_class_method :build_with
   end
 end

data/lib/annotato/auto_annotate.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Annotato
+  # Decides when annotations are refreshed automatically after migrations.
+  module AutoAnnotate
+    # db:migrate, db:rollback and their per-database / up / down / redo variants.
+    TASK_PATTERN = /\Adb:(?:migrate|rollback)(?::(?!status\z)\w+)?\z/
+
+    # Only in development, so deploys and CI never rewrite model files.
+    # ANNOTATO_SKIP=1 turns it off locally too.
+    def self.enabled?(rails_env, env = ENV)
+      return false if %w[1 true yes].include?(env["ANNOTATO_SKIP"].to_s.downcase)
+
+      rails_env.to_s == "development"
+    end
+
+    def self.task_names(all_names)
+      all_names.grep(TASK_PATTERN)
+    end
+  end
+end

data/lib/annotato/check_constraint_formatter.rb

@@ -1,10 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "wrap_helper"
+
 module Annotato
   class CheckConstraintFormatter
     extend WrapHelper
 
     def self.format(conn, table_name)
+      # check_constraints exists since Rails 6.1 and not every adapter supports it.
+      return [] unless conn.respond_to?(:check_constraints) && conn.supports_check_constraints?
+
       conn.check_constraints(table_name).sort_by(&:name).map do |chk|
         expr_clause = ""
         if chk.expression

data/lib/annotato/column_formatter.rb

@@ -2,20 +2,19 @@
 
 require "json"
 require_relative "wrap_helper"
+require_relative "enum_formatter"
 
 module Annotato
   class ColumnFormatter
     extend WrapHelper
 
     # Main entry: returns an array of comment lines per column, flattened.
-    def self.format(model, connection)
+    def self.format(model, connection, pg_enums: EnumFormatter.pg_enums(connection))
       table_name     = model.table_name
       primary_key    = model.primary_key
       unique_indexes = connection.indexes(table_name).select(&:unique)
       columns        = connection.columns(table_name)
-
-      # Collect native PG enum type names once up front (avoids N+1 queries).
-      pg_enum_types = pg_enum_type_names(connection)
+      return [] if columns.empty?
 
       # Compute max widths for name and sql_type so that the table lines up.
       name_width = columns.map(&:name).map(&:length).max
@@ -40,22 +39,27 @@ module Annotato
           opts << "__MULTILINE__"  # placeholder
         elsif !col.default.nil?
           opts << "default(#{col.default.inspect})"
+        elsif generated?(col)
+          opts << "generated(#{col.default_function})"
+        elsif show_default_function?(col)
+          opts << "default(#{col.default_function})"
         end
         opts << "not null"       unless col.null
         opts << "primary key"    if name == primary_key
         opts << "is an Array"    if type.end_with?("[]")
-        opts << "unique"         if unique_indexes.any? { |idx| idx.columns == [name] }
-        opts << "enum"           if pg_enum_types.include?(type.delete_suffix("[]"))
+        unique_flag = unique_option(unique_indexes, name)
+        opts << unique_flag      if unique_flag
+        opts << "enum"           if pg_enums.key?(type.delete_suffix("[]"))
         opts << "comment: #{col.comment.inspect}" if col.respond_to?(:comment) && col.comment && !col.comment.empty?
 
         # Emit either a multiline block or a single line.
         if default_block
           # 1) opening line
-          lines = ["#{left} default(#{col.default[0]}"]
+          lines = ["#{left} default(#{default_block[:open]}"]
           # 2) each interior line, prefixed by "# " + indent_str
-          lines += default_block.map { |l| "# #{indent_str}#{l}" }
+          lines += default_block[:lines].map { |l| "# #{indent_str}#{l}" }
           # 3) closing line with trailing options
-          closing = "# #{closing_indent_str}#{col.default[-1]})"
+          closing = "# #{closing_indent_str}#{default_block[:close]})"
           trailing = opts.reject { |o| o == "__MULTILINE__" }
           closing += ", #{trailing.join(', ')}" unless trailing.empty?
           lines << closing
@@ -65,7 +69,10 @@ module Annotato
           opts_str = opts.join(", ")
           line = opts_str.empty? ? left : "#{left} #{opts_str}"
           if line.length > WrapHelper::MAX_LINE && !opts_str.empty?
-            [left, "#    #{opts_str}"]
+            # Align the continuation under the type column so it reads as part of this column;
+            # fall back to a short indent if that still doesn't fit.
+            aligned = "##{' ' * (left.index(':') - 1)}#{opts_str}"
+            [left, aligned.length <= WrapHelper::MAX_LINE ? aligned : "#    #{opts_str}"]
           else
             [line]
           end
@@ -73,8 +80,34 @@ module Annotato
       end
     end
 
-    # Returns nil for non-JSON/empty values, or an Array of un-indented inner lines
-    # for multiline formatting: e.g. ["\"A\",", "\"B\""] for a JSON array.
+    # "unique" for a full single-column unique index; "unique (partial)" when every such
+    # index has a WHERE clause (uniqueness holds only for some rows, see Indexes section).
+    def self.unique_option(unique_indexes, name)
+      indexes = unique_indexes.select { |idx| idx.columns == [name] }
+      return if indexes.empty?
+
+      indexes.any? { |idx| idx.where.to_s.empty? } ? "unique" : "unique (partial)"
+    end
+    private_class_method :unique_option
+
+    # Generated columns (GENERATED ALWAYS AS ... ): Rails stores the expression in default_function.
+    def self.generated?(col)
+      col.respond_to?(:virtual?) && col.virtual? && !col.default_function.nil?
+    end
+    private_class_method :generated?
+
+    # Function defaults like now() are shown; sequence defaults of serial columns
+    # (nextval('users_id_seq'::regclass)) are implied by the type and only add noise.
+    def self.show_default_function?(col)
+      return false unless col.respond_to?(:default_function) && col.default_function
+
+      !col.default_function.start_with?("nextval(")
+    end
+    private_class_method :show_default_function?
+
+    # Returns nil for non-JSON/empty values, or { open:, close:, lines: } for multiline
+    # formatting, where lines are the un-indented inner lines of the pretty-printed JSON:
+    # e.g. { open: "[", close: "]", lines: ["\"A\",", "\"B\""] } for a JSON array.
     def self.build_default_block(value)
       return nil if value.nil? || !value.is_a?(String)
       s = value.strip
@@ -82,35 +115,14 @@ module Annotato
 
       parsed = JSON.parse(s) rescue nil
       return nil unless parsed.is_a?(Array) || parsed.is_a?(Hash)
+      return nil if parsed.empty?
 
-      if parsed.is_a?(Array)
-        return nil if parsed.empty?
-
-        # JSON array of strings
-        parsed.map.with_index do |e, i|
-          comma = i == parsed.size - 1 ? "" : ","
-          %Q{"#{e}"#{comma}}
-        end
-      else
-        return nil if parsed.empty?
-
-        # JSON hash → key/value pairs
-        parsed.map.with_index do |(k, v), i|
-          comma = i == parsed.size - 1 ? "" : ","
-          %Q{"#{k}": #{v.inspect}#{comma}}
-        end
-      end
-    end
-
-    # Fetches all native PostgreSQL enum type names in one query.
-    # Returns a Set for O(1) membership checks.
-    def self.pg_enum_type_names(connection)
-      rows = connection.exec_query(
-        "SELECT typname FROM pg_type WHERE typtype = 'e'",
-        "SQL"
-      )
-      rows.map { |r| r["typname"] }.to_set
+      pretty = JSON.pretty_generate(parsed).lines.map(&:rstrip)
+      {
+        open:  pretty.first,
+        close: pretty.last,
+        lines: pretty[1..-2].map { |l| l.delete_prefix("  ") }
+      }
     end
-    private_class_method :pg_enum_type_names
   end
 end

data/lib/annotato/enum_formatter.rb

@@ -1,18 +1,18 @@
 # frozen_string_literal: true
 
+require_relative "adapter"
+
 module Annotato
   # Formats PostgreSQL native enum type definitions for columns whose sql_type
   # refers to a custom DB enum (e.g. `access_link_category`). Queries pg_enum
   # directly so the output reflects the actual database definition, not the
   # ActiveRecord-level enum mapping already visible in the model source.
   class EnumFormatter
-    def self.format(conn, columns)
-      # Collect columns backed by a native PG enum type.
-      enum_columns = columns.select { |col| pg_enum_type?(conn, col.sql_type) }
-      return [] if enum_columns.empty?
+    def self.format(conn, columns, pg_enums: pg_enums(conn))
+      columns.flat_map do |col|
+        labels = pg_enums[col.sql_type.delete_suffix("[]")]
+        next [] unless labels
 
-      enum_columns.flat_map do |col|
-        labels = pg_enum_labels(conn, col.sql_type)
         lines = ["#  #{col.name} (#{col.sql_type}): ["]
         labels.each_with_index do |label, i|
           comma = i == labels.size - 1 ? "" : ","
@@ -23,27 +23,22 @@ module Annotato
       end
     end
 
-    private_class_method def self.pg_enum_type?(conn, sql_type)
-      # Strip array suffix (e.g. "my_enum[]") before checking.
-      type_name = sql_type.delete_suffix("[]")
-      result = conn.exec_query(
-        "SELECT 1 FROM pg_type WHERE typname = $1 AND typtype = 'e' LIMIT 1",
-        "SQL",
-        [type_name]
-      )
-      result.any?
-    end
+    # Returns { type_name => [labels in sort order] } for every native PG enum, in one query.
+    # Keys come from format_type(), the same function PostgreSQL uses for a column's sql_type,
+    # so types outside the search_path are schema-qualified exactly as in the column.
+    # Returns {} for non-PostgreSQL adapters.
+    def self.pg_enums(conn)
+      return {} unless Adapter.postgresql?(conn)
 
-    private_class_method def self.pg_enum_labels(conn, sql_type)
-      type_name = sql_type.delete_suffix("[]")
-      conn.exec_query(
-        "SELECT e.enumlabel FROM pg_enum e " \
-        "JOIN pg_type t ON e.enumtypid = t.oid " \
-        "WHERE t.typname = $1 AND t.typtype = 'e' " \
-        "ORDER BY e.enumsortorder",
-        "SQL",
-        [type_name]
-      ).map { |r| r["enumlabel"] }
+      rows = conn.exec_query(
+        "SELECT format_type(t.oid, NULL) AS type_name, e.enumlabel AS label " \
+        "FROM pg_type t JOIN pg_enum e ON e.enumtypid = t.oid " \
+        "ORDER BY t.oid, e.enumsortorder",
+        "SQL"
+      )
+      rows.each_with_object({}) do |r, acc|
+        (acc[r["type_name"]] ||= []) << r["label"]
+      end
     end
   end
 end

data/lib/annotato/index_formatter.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
+require_relative "wrap_helper"
+
 module Annotato
   class IndexFormatter
     extend WrapHelper
 
     def self.format(conn, table_name)
       conn.indexes(table_name).sort_by(&:name).map do |idx|
-        cols_list = Array(idx.columns).join(',')
+        cols_list = Array(idx.columns).map { |col| with_order(idx, col) }.join(',')
         unique_clause = idx.unique ? " unique" : ""
 
         where_clause = ""
@@ -14,8 +16,29 @@ module Annotato
           where_clause = "\n" + wrap_sql(idx.where, first_prefix: "#    where (", cont_prefix: "#          ")
         end
 
-        "#  #{idx.name} (#{cols_list})#{unique_clause}#{where_clause}"
+        "#  #{idx.name} (#{cols_list})#{unique_clause}#{extras(idx)}#{where_clause}"
       end
     end
+
+    # Index method (other than the default btree), INCLUDE columns and NULLS NOT DISTINCT.
+    # Guarded with respond_to? because these attributes vary across Rails versions.
+    def self.extras(idx)
+      parts = []
+      using = idx.respond_to?(:using) && idx.using
+      parts << "using #{using}" if using && using.to_s != "btree"
+      include_cols = idx.respond_to?(:include) && idx.include
+      parts << "include (#{Array(include_cols).join(',')})" if include_cols && !Array(include_cols).empty?
+      parts << "nulls not distinct" if idx.respond_to?(:nulls_not_distinct) && idx.nulls_not_distinct
+      parts.empty? ? "" : " #{parts.join(' ')}"
+    end
+    private_class_method :extras
+
+    def self.with_order(idx, col)
+      return col unless idx.respond_to?(:orders)
+
+      order = idx.orders.is_a?(Hash) ? idx.orders[col.to_s] || idx.orders[col.to_sym] : idx.orders
+      order ? "#{col} #{order.to_s.upcase}" : col
+    end
+    private_class_method :with_order
   end
 end

data/lib/annotato/model_annotator.rb

@@ -6,8 +6,20 @@ require_relative "annotation_builder"
 
 module Annotato
   class ModelAnnotator
-    def initialize(output: $stdout)
-      @output = output
+    # A block is its header line plus every directly following comment line.
+    # Matching stops at the first non-comment line (blank lines right after the block are
+    # consumed too), so code after the block is never touched.
+    ANNOTATO_BLOCK = /^# == Annotato Schema Info\n(?:#.*(?:\n|\z))*\n*/
+    LEGACY_BLOCK   = /^# == Schema Information\n(?:#.*(?:\n|\z))*\n*/
+
+    # Names of models whose annotation is missing or outdated (filled in check mode).
+    attr_reader :outdated
+
+    # check: true reports outdated annotations without writing any file.
+    def initialize(output: $stdout, check: false)
+      @output   = output
+      @check    = check
+      @outdated = []
     end
 
     def run(one_model = nil)
@@ -21,24 +33,45 @@ module Annotato
       end
     end
 
+    # Annotates models given by name (e.g. ["User", "Admin::Account"]).
+    # Unknown names are reported and skipped instead of aborting the whole run.
+    def run_named(names)
+      names.each do |name|
+        klass = name.safe_constantize
+        unless klass.is_a?(Class) && klass < ActiveRecord::Base
+          @output.puts "⚠️  Skipped #{name} — not an ActiveRecord model"
+          next
+        end
+
+        run(klass)
+      end
+    end
+
     private
 
       def models
         Rails.application.eager_load!
-        # All AR models, but skip STI subclasses (only keep base classes)
+        # All AR models, but skip STI subclasses (only keep base classes),
+        # anonymous classes and generated HABTM join models.
         ActiveRecord::Base.descendants
           .reject(&:abstract_class?)
           .select { |m| m.base_class == m }
+          .reject { |m| m.name.nil? || m.name.demodulize.start_with?("HABTM_") }
       end
 
+      # Only files inside the application are ever written; models defined
+      # in gems or engines (e.g. ActiveStorage::Blob) are skipped.
       def model_file(model)
-        file = model.instance_method(:initialize).source_location&.first
+        return if model.name.nil?
 
-        if file.nil? || file.include?("/gems/")
-          Object.const_source_location(model.name)&.first
-        else
-          file
-        end
+        file = Object.const_source_location(model.name)&.first
+        file if file && app_file?(file)
+      end
+
+      def app_file?(file)
+        root = "#{File.expand_path(Rails.root.to_s)}/"
+        path = File.expand_path(file)
+        path.start_with?(root) && !path.start_with?("#{root}vendor/")
       end
 
       def write_annotation(model, annotation)
@@ -53,25 +86,39 @@ module Annotato
           return
         end
 
-        # Extract the old Annotato annotation block if it exists
-        old_annotation = content[/^# == Annotato Schema Info.*?(?=^class|\z)/m]
+        # Skip writing if the annotation hasn't changed and there is no legacy block to clean up
+        old_annotation = content[ANNOTATO_BLOCK]
+        if old_annotation && old_annotation.strip == annotation.strip && !content.match?(LEGACY_BLOCK)
+          return
+        end
 
-        # Skip writing if the annotation hasn't changed
-        if old_annotation && old_annotation.strip == annotation.strip
-          @output.puts "ℹ️  Skipped #{model.name} — annotation unchanged"
+        if @check
+          @outdated << model.name
+          @output.puts "❌ Outdated annotation: #{model.name}"
           return
         end
 
         # Remove old Annotato blocks and legacy annotate-gem blocks
-        content.gsub!(/^# == Annotato Schema Info.*?(?=^class|\z)/m, "")
-        content.gsub!(/^# == Schema Information.*?(?=^class|\z)/m, "")
+        content.gsub!(ANNOTATO_BLOCK, "")
+        content.gsub!(LEGACY_BLOCK, "")
         content.rstrip!
 
         # Append the new annotation at the end of the file
-        content += "\n\n#{annotation}\n"
-        File.write(file, content)
+        content += "\n\n#{annotation.rstrip}\n"
+        write_file(file, content)
 
         @output.puts "✍️  Annotated #{model.name}"
       end
+
+      # Writes via a temp file + rename so an interrupted run never leaves a truncated model file.
+      def write_file(file, content)
+        target = File.realpath(file)
+        tmp    = "#{target}.annotato-#{Process.pid}.tmp"
+        File.write(tmp, content)
+        File.chmod(File.stat(target).mode, tmp)
+        File.rename(tmp, target)
+      ensure
+        File.delete(tmp) if tmp && File.exist?(tmp)
+      end
   end
 end

data/lib/annotato/railtie.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "rails/railtie"
+require_relative "auto_annotate"
 
 module Annotato
   class Railtie < ::Rails::Railtie
@@ -8,10 +9,14 @@ module Annotato
       # Load all annotato rake tasks as before
       Dir[File.expand_path("../tasks/**/*.rake", __dir__)].each { |f| load f }
 
-      # After db:migrate finishes, run annotato:models automatically
-      Rake::Task["db:migrate"].enhance do
-        Rake::Task["annotato:models"].reenable
-        Rake::Task["annotato:models"].invoke
+      # After migrating or rolling back, run annotato:models automatically (development only)
+      AutoAnnotate.task_names(Rake::Task.tasks.map(&:name)).each do |name|
+        Rake::Task[name].enhance do
+          next unless AutoAnnotate.enabled?(Rails.env)
+
+          Rake::Task["annotato:models"].reenable
+          Rake::Task["annotato:models"].invoke
+        end
       end
     end
   end

data/lib/annotato/trigger_formatter.rb

@@ -1,21 +1,24 @@
 # frozen_string_literal: true
 
+require_relative "adapter"
+
 module Annotato
   class TriggerFormatter
     def self.format(conn, table_name)
-      rows = case conn.adapter_name.downcase
-             when "postgresql"
+      rows = case Adapter.kind(conn)
+             when :postgresql
                conn.exec_query(
                  "SELECT tgname AS name FROM pg_trigger WHERE tgrelid = $1::regclass AND NOT tgisinternal",
                  "SQL", [table_name]
                )
-             when "mysql2", "mysql", "trilogy"
+             when :mysql
+               # Quoted instead of bound: the Trilogy adapter does not support bind params.
                conn.exec_query(
                  "SELECT TRIGGER_NAME AS name FROM information_schema.TRIGGERS " \
-                 "WHERE EVENT_OBJECT_SCHEMA = DATABASE() AND EVENT_OBJECT_TABLE = ?",
-                 "SQL", [table_name]
+                 "WHERE EVENT_OBJECT_SCHEMA = DATABASE() AND EVENT_OBJECT_TABLE = #{conn.quote(table_name)}",
+                 "SQL"
                )
-             when "sqlite3"
+             when :sqlite
                conn.exec_query(
                  "SELECT name FROM sqlite_master WHERE type = 'trigger' AND tbl_name = ?",
                  "SQL", [table_name]

data/lib/annotato/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Annotato
-  VERSION = "0.2.5"
+  VERSION = "0.3.0"
 end

data/lib/annotato/wrap_helper.rb

@@ -3,6 +3,8 @@
 module Annotato
   module WrapHelper
     MAX_LINE = 120
+    # Preferred break points, best first; the token stays at the end of the line.
+    BREAK_TOKENS = [" AND ", " OR ", ", ", ") ", " "].freeze
 
     # Produces one or more lines, each already prefixed with "#    "
     # First line: "#    where (..."
@@ -29,30 +31,8 @@ module Annotato
           break
         end
 
-        # Prefer breaking on logical operators within the window
-        window = remaining[0, available]
-        cut =
-          window.rindex(" AND ") ||
-          window.rindex(" OR ")  ||
-          window.rindex(", ")    ||
-          window.rindex(") ")    ||
-          window.rindex(" ")     # last resort: whitespace
-
-        # If we found a breakpoint, include it in the line (so operators stay visible)
-        if cut
-          # If we’re cutting on AND/OR/comma, keep that token at the end of the line when possible
-          if window[cut, 5] == " AND " || window[cut, 4] == " OR "
-            cut += (window[cut, 5] == " AND " ? 5 : 4)
-          elsif window[cut, 2] == ", "
-            cut += 2
-          elsif window[cut, 2] == ") "
-            cut += 2
-          else
-            cut += 1
-          end
-        else
-          cut = available
-        end
+        # Prefer breaking on logical operators within the window; hard cut if none.
+        cut = find_break(remaining[0, available]) || available
 
         lines << "#{current_prefix}#{remaining[0, cut].rstrip}"
         remaining = remaining[cut..].to_s.lstrip
@@ -64,5 +44,25 @@ module Annotato
 
       lines.join("\n")
     end
+
+    private
+
+    # Position right after the best break token in window, or nil.
+    # Never breaks at position 0 (would emit an empty line) or inside a quoted SQL literal.
+    def find_break(window)
+      BREAK_TOKENS.each do |token|
+        pos = window.rindex(token)
+        while pos && pos.positive?
+          return pos + token.length unless inside_quotes?(window, pos)
+
+          pos = window.rindex(token, pos - 1)
+        end
+      end
+      nil
+    end
+
+    def inside_quotes?(text, pos)
+      text[0, pos].count("'").odd?
+    end
   end
 end

data/lib/annotato.rb

@@ -1,2 +1,11 @@
+# frozen_string_literal: true
+
 require "annotato/version"
+
+module Annotato
+  autoload :AnnotationBuilder, "annotato/annotation_builder"
+  autoload :AutoAnnotate,      "annotato/auto_annotate"
+  autoload :ModelAnnotator,    "annotato/model_annotator"
+end
+
 require "annotato/railtie" if defined?(Rails::Railtie)

data/lib/tasks/annotato.rake

@@ -3,18 +3,24 @@
 require "annotato/model_annotator"
 
 namespace :annotato do
-  desc "Annotate models with schema info. Pass MODEL=name or comma-separated list"
-  task :models, [:MODEL] => :environment do |t, args|
-    # Parse MODEL argument into an array of model names, if given
-    model_list = args[:MODEL]&.split(",")&.map(&:strip)
+  # Model names come from the task args and/or ENV["MODEL"]. Rake splits task args
+  # on commas, so annotato:models[User,Admin::Account] arrives as MODEL + extras.
+  model_names = lambda do |args|
+    [args[:MODEL], *args.extras, ENV["MODEL"]]
+      .compact
+      .flat_map { |names| names.split(",") }
+      .map(&:strip)
+      .reject(&:empty?)
+      .uniq
+  end
 
+  desc "Annotate models with schema info. Pass MODEL=name or comma-separated list"
+  task :models, [:MODEL] => :environment do |_t, args|
+    names = model_names.call(args)
     annotator = Annotato::ModelAnnotator.new
 
-    if model_list && model_list.any?
-      # Constantize each name and annotate only those classes
-      model_list.map(&:constantize).each do |klass|
-        annotator.run(klass)
-      end
+    if names.any?
+      annotator.run_named(names)
     else
       # No MODEL passed → annotate all models
       annotator.run
@@ -22,4 +28,17 @@ namespace :annotato do
 
     puts "✅ Annotato completed"
   end
+
+  desc "Check that model annotations are up to date (no files are written); fails if any are outdated"
+  task :check, [:MODEL] => :environment do |_t, args|
+    names = model_names.call(args)
+    annotator = Annotato::ModelAnnotator.new(check: true)
+    names.any? ? annotator.run_named(names) : annotator.run
+
+    if annotator.outdated.any?
+      abort "❌ #{annotator.outdated.size} outdated annotation(s). Run `rake annotato:models` to update."
+    end
+
+    puts "✅ Annotations are up to date"
+  end
 end

data/sig/annotato.rbs

@@ -1,4 +1,27 @@
 module Annotato
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  class ModelAnnotator
+    attr_reader outdated: Array[String]
+
+    def initialize: (?output: IO, ?check: bool) -> void
+    def run: (?untyped one_model) -> void
+    def run_named: (Array[String] names) -> void
+  end
+
+  class AnnotationBuilder
+    def self.build: (untyped model) -> String
+  end
+
+  module AutoAnnotate
+    TASK_PATTERN: Regexp
+
+    def self.enabled?: (_ToS rails_env, ?Hash[String, String?] env) -> bool
+    def self.task_names: (Array[String] all_names) -> Array[String]
+  end
+
+  module Adapter
+    def self.kind: (untyped conn) -> (:postgresql | :mysql | :sqlite | nil)
+    def self.postgresql?: (untyped conn) -> bool
+  end
 end

metadata

@@ -1,28 +1,42 @@
 --- !ruby/object:Gem::Specification
 name: annotato
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.3.0
 platform: ruby
 authors:
 - Serhii Bodnaruk
 bindir: exe
 cert_chain: []
-date: 2026-07-24 00:00:00.000000000 Z
+date: 2026-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '6.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
 description: Annotato automatically adds or updates comments at the end of your Rails
   models to show schema details like columns, indexes, and PostgreSQL triggers.
 email:
@@ -44,7 +58,9 @@ files:
 - bin/console
 - bin/setup
 - lib/annotato.rb
+- lib/annotato/adapter.rb
 - lib/annotato/annotation_builder.rb
+- lib/annotato/auto_annotate.rb
 - lib/annotato/check_constraint_formatter.rb
 - lib/annotato/column_formatter.rb
 - lib/annotato/enum_formatter.rb