awesome_annotate 0.1.5 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: add6a26de84b0dab25e21c0c60213a8d0c6aef0109a552faf635fdfb745e5bcb
-  data.tar.gz: 6a9494f2aeafe2e163c59f1544f181da0d39aef6736851412580c1b59231631a
+  metadata.gz: 4c4c2fe792fc935930fcc07c2a9662f7032cd590bcad80f06551e5dae567f279
+  data.tar.gz: 62db756fb9535984c36eda116f23aa2130ba18b2077c8102423d8b559e075e78
 SHA512:
-  metadata.gz: 9654317d619c0d5e4706b1a5fb1f6899a123a3f8b6acb79c29d744d65ed5c6d1a895e9cbd835653e1d33de80055c75a24e0f38fd365d2e58112738cf2e70b763
-  data.tar.gz: 807524f834b4087643d8fc2e2477ebd271f6eac9a989d947b9ac3dd693259baf7890187e3201293d4e809f6dfef9f7abe05542f3a287e17af0a527d54d955acc
+  metadata.gz: 33795981d662f1eeae3be75bb11befd25aaed09d22f50c26647d131c1916ea54eb9f2a105272a8e42e4cb6c80a5df3c474cda12c4a9c566c0e9452512d40ac33
+  data.tar.gz: ae8e56afa0844d88bbb2d1cae87e12538846ccf507394943259c8856e548d7e70e9c1e49cdc8d42ce3c7e8ada99900df46f8b251396cdb8161f976c4ad25ae2f

data/.rubocop.yml

@@ -1,18 +1,50 @@
-inherit_from:
-  - .rubocop_todo.yml
-
 require:
   - rubocop-rake
   - rubocop-rspec
 
 AllCops:
+  TargetRubyVersion: 3.0
   Exclude:
     - 'vendor/**/*'
     - 'spec/fixtures/**/*'
     - 'tmp/**/*'
-    - 'spec/integration/**/*'
   NewCops: enable
 
+Style/Documentation:
+  Enabled: false
+
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*.rb'
+
+Metrics/AbcSize:
+  Exclude:
+    - 'spec/support/**/*'
+
+RSpec/VerifiedDoubles:
+  Exclude:
+    - 'spec/support/**/*'
+
+RSpec/MultipleExpectations:
+  Exclude:
+    - 'spec/**/*'
+
+RSpec/NestedGroups:
+  Exclude:
+    - 'spec/**/*'
+
+RSpec/HooksBeforeExamples:
+  Exclude:
+    - 'spec/**/*'
+
+RSpec/ExampleLength:
+  Exclude:
+    - 'spec/**/*'
+
+RSpec/DescribeClass:
+  Exclude:
+    - 'spec/integration/**/*'
+
+Lint/EmptyClass:
+  Exclude:
+    - 'spec/support/rails.rb'

data/.ruby-version

@@ -0,0 +1 @@
+3.2.2

data/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## [0.3.1] - 2026-05-31
+
+- Fixed a bug
+
+## [0.1.0] - 2024-04-29
+
+- Initial release
+
+## [0.3.0] - 2026-05-31
+
+- Added `awesome_annotate init` to create
+  `config/initializers/awesome_annotate.yml`.
+- Added configuration loading for annotation and remove commands.
+- Added path configuration:
+  - `env_file_path`
+  - `model_dir`
+  - `route_file_path`
+- Added `annotation_position` to choose whether new annotation blocks are
+  inserted at the top or bottom of files.
+- Added model annotation filters and output controls:
+  - `exclude_model_files`
+  - `include_indexes`
+  - `exclude_columns`
+  - `include_column_defaults`
+- Added `exclude_routes` to omit matching route lines from route annotations.
+- Added validation for supported configuration value types.
+
+## [0.2.0] - 2026-05-10
+
+- Added model schema annotations with column type, nullability, primary key,
+  default value, and basic index information.
+- Added duplicate-safe annotation blocks with AwesomeAnnotate start and end
+  markers.
+- Added route annotations for `config/routes.rb`.
+- Added model commands:
+  - `awesome_annotate model MODEL`
+  - `awesome_annotate models`
+  - `awesome_annotate models MODEL...`
+- Added `awesome_annotate all` to annotate all models and routes.
+- Added remove commands:
+  - `awesome_annotate remove model MODEL`
+  - `awesome_annotate remove models`
+  - `awesome_annotate remove routes`
+  - `awesome_annotate remove all`
+- Added Rails-like integration specs and GitHub Actions CI for RSpec and
+  RuboCop.
+- Documented supported Ruby and Active Record versions.
+
 ## [0.1.3] - 2024-05-05
 
 - Add a new feature

data/README.md

@@ -1,35 +1,245 @@
 # AwesomeAnnotate
 
-TODO: Delete this and the text below, and describe your gem
+AwesomeAnnotate adds generated schema and route comments to Rails applications.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/awesome_annotate`. To experiment with that code, run `bin/console` for an interactive prompt.
+This gem is intended as a small replacement-style tool for the basic features of
+the original `annotate` gem:
+
+- annotate model files with Active Record schema information
+- annotate `config/routes.rb` with the application's route table
+- replace previous AwesomeAnnotate blocks instead of appending duplicates
+- remove generated AwesomeAnnotate blocks
+
+## Requirements
+
+- Ruby 3.0 or later, below 4.0
+- Active Record 6.1 or later, below 8.0
+- Rails application layout with `config/environment.rb`
+
+Development currently uses the Ruby version in `.ruby-version`.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add this line to your Rails application's Gemfile:
+
+```ruby
+gem 'awesome_annotate'
+```
 
-Install the gem and add to the application's Gemfile by executing:
+Then run:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```sh
+bundle install
+```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+If you are using this repository directly before publishing the gem, use a Git
+source instead:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+gem 'awesome_annotate', git: 'https://github.com/wisdom-plus/awesome_annotate'
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+Run commands from the root directory of a Rails application.
+
+Available commands:
+
+```sh
+bundle exec awesome_annotate model user
+bundle exec awesome_annotate models
+bundle exec awesome_annotate models user article admin/user
+bundle exec awesome_annotate routes
+bundle exec awesome_annotate all
+bundle exec awesome_annotate init
+bundle exec awesome_annotate remove model user
+bundle exec awesome_annotate remove models
+bundle exec awesome_annotate remove routes
+bundle exec awesome_annotate remove all
+```
+
+Annotate a model:
+
+```sh
+bundle exec awesome_annotate model user
+```
+
+Annotate all models:
+
+```sh
+bundle exec awesome_annotate models
+```
+
+Annotate specific models:
+
+```sh
+bundle exec awesome_annotate models user article admin/user
+```
+
+Annotate all models and routes:
+
+```sh
+bundle exec awesome_annotate all
+```
+
+Remove generated annotations:
+
+```sh
+bundle exec awesome_annotate remove model user
+bundle exec awesome_annotate remove models
+bundle exec awesome_annotate remove routes
+bundle exec awesome_annotate remove all
+```
+
+Create a configuration file:
+
+```sh
+bundle exec awesome_annotate init
+```
+
+This creates `config/initializers/awesome_annotate.yml`:
+
+```yaml
+# AwesomeAnnotate configuration
+#
+# Change these paths when your Rails app uses non-standard locations.
+env_file_path: config/environment.rb
+model_dir: app/models
+route_file_path: config/routes.rb
+annotation_position: top
+exclude_model_files: []
+include_indexes: true
+exclude_columns: []
+include_column_defaults: true
+exclude_routes: []
+```
+
+When this file exists, annotation and removal commands use these values. This
+allows applications with non-standard model, route, or environment file paths to
+change command behavior without passing Ruby options directly. Set
+`annotation_position` to `top` or `bottom` to choose where new annotation blocks
+are inserted. Set `exclude_model_files` to relative file paths or glob patterns
+under `model_dir` to skip them during model discovery. Set `include_indexes` to
+`false` to omit the Indexes section from model schema annotations. Set
+`exclude_columns` to column names to omit them from model schema annotations. Set
+`include_column_defaults` to `false` to omit `default(...)` details. Set
+`exclude_routes` to route line patterns to omit them from route annotations.
+
+This loads `config/environment.rb`, resolves `User`, reads its Active Record
+columns, and writes a schema block before the class definition in
+`app/models/user.rb`:
+
+```ruby
+# == AwesomeAnnotate: columns
+# == Schema Information
+#
+# Table name: users
+#
+#  id         :integer  not null, primary key
+#  name       :string
+#  email      :string   not null, default("")
+#  created_at :datetime not null
+#  updated_at :datetime not null
+#
+# Indexes
+#
+#  (email)       UNIQUE, index_users_on_email
+#  (name,email)  index_users_on_name_and_email
+#
+# == /AwesomeAnnotate: columns
+class User < ApplicationRecord
+end
+```
+
+Annotate routes:
+
+```sh
+bundle exec awesome_annotate routes
+```
+
+This writes a generated route block before `Rails.application.routes.draw do` in
+`config/routes.rb`:
+
+```ruby
+# == AwesomeAnnotate: routes
+# Prefix Verb URI Pattern Controller#Action
+# users GET /users(.:format) users#index
+# == /AwesomeAnnotate: routes
+Rails.application.routes.draw do
+end
+```
+
+Print the gem version:
+
+```sh
+bundle exec awesome_annotate --version
+```
+
+Short aliases are also available:
+
+```sh
+bundle exec awesome_annotate -m user
+bundle exec awesome_annotate -r
+bundle exec awesome_annotate -v
+```
+
+## Generated Blocks
+
+AwesomeAnnotate wraps generated comments with start and end markers:
+
+```ruby
+# == AwesomeAnnotate: columns
+# ...
+# == /AwesomeAnnotate: columns
+```
+
+When the command is run again, the existing block with the same marker is
+replaced. This prevents duplicate annotations from being appended on repeated
+runs.
+
+## Current Limitations
+
+- Only model schema blocks and routes are supported.
+- Model annotations include column type, nullability, primary key, and default
+  values, plus basic index information.
+- Model annotation currently targets files under `app/models`.
+- Model class detection expects a simple class declaration such as
+  `class User < ApplicationRecord`.
+- Existing comments generated by other annotate tools are not migrated or
+  removed automatically.
+- Ruby 4 is not currently supported.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Install dependencies:
+
+```sh
+bundle install
+```
+
+Run the test suite:
+
+```sh
+bundle exec rspec
+```
+
+Run RuboCop:
+
+```sh
+bundle exec rubocop
+```
+
+Build the gem locally:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```sh
+bundle exec rake build
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/awesome_annotate.
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/wisdom-plus/awesome_annotate.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the MIT License.

data/Rakefile

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-require "rubocop/rake_task"
+require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 

data/exe/awesome_annotate

@@ -1,8 +1,7 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-unless File.exist?('./Rakefile') || File.exist?('./Gemfile')
-  abort 'Please run annotate from the root of the project.'
-end
+abort 'Please run annotate from the root of the project.' unless File.exist?('./Rakefile') || File.exist?('./Gemfile')
 require 'awesome_annotate'
 
 AwesomeAnnotate::CLI.start ARGV

data/lib/awesome_annotate/annotation_block.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module AwesomeAnnotate
+  module AnnotationBlock
+    private
+
+    def replace_or_insert_annotation(file_path:, marker:, content:, before:, position: 'top')
+      path = file_path.to_s
+      file_content = File.read(path)
+      annotation = annotation_block(marker, content)
+
+      File.write(path, replace_annotation(file_content, marker, annotation, before, position))
+    end
+
+    def remove_annotation(file_path:, marker:)
+      path = file_path.to_s
+      file_content = File.read(path)
+      pattern = annotation_block_pattern(marker)
+
+      return false unless file_content.match?(pattern)
+
+      File.write(path, file_content.gsub(pattern, ''))
+      true
+    end
+
+    def annotation_block(marker, content)
+      body = content.end_with?("\n") ? content : "#{content}\n"
+
+      "# == AwesomeAnnotate: #{marker}\n" \
+        "#{body}" \
+        "# == /AwesomeAnnotate: #{marker}\n\n"
+    end
+
+    def annotation_block_pattern(marker)
+      escaped_marker = Regexp.escape(marker)
+      %r{^# == AwesomeAnnotate: #{escaped_marker}\n.*?^# == /AwesomeAnnotate: #{escaped_marker}\n(?:\n)*}m
+    end
+
+    def replace_annotation(file_content, marker, annotation, before, position)
+      pattern = annotation_block_pattern(marker)
+
+      return file_content.sub(pattern, annotation) if file_content.match?(pattern)
+
+      return "#{file_content.chomp}\n#{annotation}" if position.to_s == 'bottom'
+
+      file_content.sub(before, "#{annotation}\\0")
+    end
+  end
+end

data/lib/awesome_annotate/cli.rb

@@ -1,15 +1,55 @@
+# frozen_string_literal: true
+
 require 'awesome_annotate'
+require 'awesome_annotate/configuration'
 require 'awesome_annotate/model'
 require 'awesome_annotate/route'
 require 'awesome_annotate/version'
 require 'thor'
 
 module AwesomeAnnotate
+  class Remove < Thor
+    desc 'model [model_name]', 'remove annotation from a model'
+    def model(model_name)
+      model_annotator.remove(model_name)
+    end
+
+    desc 'models [model_names...]', 'remove annotations from all models or specified models'
+    def models(*model_names)
+      model_annotator.remove_all(model_names)
+    end
+
+    desc 'routes', 'remove annotation from `config/routes.rb`'
+    def routes
+      route_annotator.remove
+    end
+
+    desc 'all', 'remove annotations from all models and routes'
+    def all
+      model_annotator.remove_all
+      route_annotator.remove
+    end
+
+    private
+
+    def model_annotator
+      AwesomeAnnotate::Model.new(configuration.options)
+    end
+
+    def route_annotator
+      AwesomeAnnotate::Route.new(configuration.options)
+    end
+
+    def configuration
+      AwesomeAnnotate::Configuration.load
+    end
+  end
+
   class CLI < Thor
     include Thor::Actions
 
     map %w[--version -v] => :print_version
-    desc "--version, -v", "print the version"
+    desc '--version, -v', 'print the version'
     def print_version
       say AwesomeAnnotate::VERSION
     end
@@ -17,19 +57,56 @@ module AwesomeAnnotate
     map %w[model -m] => :model
     desc 'model [model_name]', 'annotate your model'
     def model(model_name)
-      AwesomeAnnotate::Model.new.annotate(model_name)
+      model_annotator.annotate(model_name)
+    end
+
+    desc 'models [model_names...]', 'annotate all models or specified models'
+    def models(*model_names)
+      model_annotator.annotate_all(model_names)
     end
 
     map %w[routes -r] => :routes
-    desc 'routes', "Writes application route information to `config/routes.rb`."
+    desc 'routes', 'Writes application route information to `config/routes.rb`.'
     def routes
-      AwesomeAnnotate::Route.new.annotate
+      route_annotator.annotate
     end
 
-    private
+    desc 'all', 'annotate all models and routes'
+    def all
+      model_annotator.annotate_all
+      route_annotator.annotate
+    end
+
+    desc 'init', "create #{AwesomeAnnotate::Configuration::DEFAULT_PATH}"
+    def init
+      path = AwesomeAnnotate::Configuration::DEFAULT_PATH
+      if File.exist?(path)
+        say "Config file already exists: #{path}"
+      else
+        AwesomeAnnotate::Configuration.create(path)
+        say "create #{path}"
+      end
+    end
+
+    desc 'remove SUBCOMMAND', 'remove generated annotations'
+    subcommand 'remove', Remove
 
     def self.exit_on_failure?
       true
     end
+
+    private
+
+    def model_annotator
+      AwesomeAnnotate::Model.new(configuration.options)
+    end
+
+    def route_annotator
+      AwesomeAnnotate::Route.new(configuration.options)
+    end
+
+    def configuration
+      AwesomeAnnotate::Configuration.load
+    end
   end
 end

data/lib/awesome_annotate/configuration.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'yaml'
+
+module AwesomeAnnotate
+  class Configuration
+    DEFAULT_PATH = 'config/initializers/awesome_annotate.yml'
+    DEFAULT_OPTIONS = {
+      env_file_path: 'config/environment.rb',
+      model_dir: 'app/models',
+      route_file_path: 'config/routes.rb',
+      annotation_position: 'top',
+      exclude_model_files: [],
+      include_indexes: true,
+      exclude_columns: [],
+      include_column_defaults: true,
+      exclude_routes: []
+    }.freeze
+    ANNOTATION_POSITIONS = %w[top bottom].freeze
+
+    TEMPLATE = <<~YAML
+      # AwesomeAnnotate configuration
+      #
+      # Change these paths when your Rails app uses non-standard locations.
+      env_file_path: config/environment.rb
+      model_dir: app/models
+      route_file_path: config/routes.rb
+      annotation_position: top
+      exclude_model_files: []
+      include_indexes: true
+      exclude_columns: []
+      include_column_defaults: true
+      exclude_routes: []
+    YAML
+
+    class << self
+      def load(path = DEFAULT_PATH)
+        return new unless File.exist?(path)
+
+        loaded = YAML.safe_load_file(path, aliases: false) || {}
+        raise ArgumentError, "Configuration file must contain a YAML mapping: #{path}" unless loaded.is_a?(Hash)
+
+        new(symbolize_options(loaded))
+      end
+
+      def create(path = DEFAULT_PATH)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, TEMPLATE)
+      end
+
+      private
+
+      def symbolize_options(options)
+        options.each_with_object({}) do |(key, value), result|
+          symbol_key = key.to_sym
+          result[symbol_key] = value if DEFAULT_OPTIONS.key?(symbol_key)
+        end
+      end
+    end
+
+    attr_reader :options
+
+    def initialize(options = {})
+      @options = DEFAULT_OPTIONS.merge(options)
+      validate_annotation_position
+      validate_exclude_model_files
+      validate_include_indexes
+      validate_exclude_columns
+      validate_include_column_defaults
+      validate_exclude_routes
+    end
+
+    private
+
+    def validate_annotation_position
+      return if ANNOTATION_POSITIONS.include?(@options[:annotation_position])
+
+      raise ArgumentError, "annotation_position must be one of: #{ANNOTATION_POSITIONS.join(', ')}"
+    end
+
+    def validate_exclude_model_files
+      return if @options[:exclude_model_files].is_a?(Array)
+
+      raise ArgumentError, 'exclude_model_files must be an array'
+    end
+
+    def validate_include_indexes
+      return if [true, false].include?(@options[:include_indexes])
+
+      raise ArgumentError, 'include_indexes must be true or false'
+    end
+
+    def validate_exclude_columns
+      return if @options[:exclude_columns].is_a?(Array)
+
+      raise ArgumentError, 'exclude_columns must be an array'
+    end
+
+    def validate_include_column_defaults
+      return if [true, false].include?(@options[:include_column_defaults])
+
+      raise ArgumentError, 'include_column_defaults must be true or false'
+    end
+
+    def validate_exclude_routes
+      return if @options[:exclude_routes].is_a?(Array)
+
+      raise ArgumentError, 'exclude_routes must be an array'
+    end
+  end
+end

data/lib/awesome_annotate/error.rb

@@ -1,2 +1,6 @@
+# frozen_string_literal: true
 
-class NotFoundError < StandardError; end
+module AwesomeAnnotate
+  class Error < StandardError; end
+  class NotFoundError < Error; end
+end

data/lib/awesome_annotate/model.rb

@@ -1,73 +1,142 @@
+# frozen_string_literal: true
+
 require 'active_record'
 require 'thor'
+require_relative 'annotation_block'
 require_relative 'error'
+require_relative 'rails_environment'
+require_relative 'schema_annotation'
 
 module AwesomeAnnotate
   class Model < Thor
+    include AnnotationBlock
     include Thor::Actions
+    include RailsEnvironment
+    include SchemaAnnotation
 
     def initialize(params = {})
       super()
       @env_file_path = Pathname.new(params[:env_file_path] || 'config/environment.rb')
       @model_dir = Pathname.new(params[:model_dir] || 'app/models')
+      @annotation_position = params[:annotation_position] || 'top'
+      @exclude_model_files = params[:exclude_model_files] || []
+      @include_indexes = params.fetch(:include_indexes, true)
+      @exclude_columns = params[:exclude_columns] || []
+      @include_column_defaults = params.fetch(:include_column_defaults, true)
     end
 
     desc 'model [model name]', 'annotate your model'
     def annotate(model_name)
-      raise "Rails application path is required" unless @env_file_path.exist?
+      raise 'Rails application path is required' unless @env_file_path.exist?
+
+      load_rails_environment
+      annotate_loaded_model(model_name)
+    end
+
+    desc 'models [model names]', 'annotate all models or specified models'
+    def annotate_all(model_names = [])
+      raise 'Rails application path is required' unless @env_file_path.exist?
 
-      apply @env_file_path.to_s
+      load_rails_environment
 
-      klass = klass_name(model_name)
+      if model_names.empty?
+        discover_model_names.each { |model_name| annotate_discovered_model(model_name) }
+      else
+        model_names.each { |model_name| annotate_loaded_model(model_name) }
+      end
+    end
+
+    desc 'remove [model name]', 'remove annotation from your model'
+    def remove(model_name)
+      file_path = model_file_path(model_name)
+
+      remove_model_annotation(file_path)
+    end
+
+    desc 'remove_all [model names]', 'remove annotations from all models or specified models'
+    def remove_all(model_names = [])
+      if model_names.empty?
+        discovered_model_file_paths.each { |file_path| remove_model_annotation(file_path, report_missing: false) }
+      else
+        model_names.each { |model_name| remove(model_name) }
+      end
+    end
+
+    private
+
+    def annotate_loaded_model(model_name, report_missing: true)
+      klass = klass_name(model_name, report_missing: report_missing)
 
       return say 'This model does not inherit activerecord' unless klass < ActiveRecord::Base
 
-      column_names = column_names(klass)
       file_path = model_file_path(model_name)
 
-      insert_file_before_class(file_path, klass, "# Columns: #{column_names.join(', ')}\n")
+      insert_file_before_class(file_path, schema_annotation(klass))
 
       say "annotate #{model_name.pluralize} table columns in #{file_path}"
     end
 
-    private
+    def discover_model_names
+      discovered_model_file_paths.map { |file_path| model_name_from_file_path(file_path) }
+    end
+
+    def discovered_model_file_paths = Dir.glob(@model_dir.join('**/*.rb')).reject { |path| excluded_model_file?(path) }
+
+    def model_name_from_file_path(file_path)
+      Pathname.new(file_path).relative_path_from(@model_dir).sub_ext('').to_s
+    end
+
+    def excluded_model_file?(file_path)
+      relative_path = Pathname.new(file_path).relative_path_from(@model_dir).to_s
 
-    def model_dir
-      Pathname.new('app/models')
+      relative_path == 'application_record.rb' || relative_path.start_with?('concerns/') ||
+        excluded_by_config?(relative_path)
     end
 
-    def insert_file_before_class(file_path, klass, message)
-      insert_into_file file_path, :before => /^class\s+\w+\s+<\s+\w+/ do
-        message
+    def excluded_by_config?(relative_path)
+      @exclude_model_files.any? { |pattern| File.fnmatch?(pattern, relative_path, File::FNM_PATHNAME) }
+    end
+
+    def annotate_discovered_model(model_name)
+      annotate_loaded_model(model_name, report_missing: false)
+    rescue AwesomeAnnotate::NotFoundError
+      nil
+    end
+
+    def remove_model_annotation(file_path, report_missing: true)
+      if remove_annotation(file_path: file_path, marker: 'columns')
+        say "remove model annotation in #{file_path}"
+      elsif report_missing
+        say "no model annotation in #{file_path}"
       end
     end
 
-    def column_names(klass)
-      klass.column_names
+    def insert_file_before_class(file_path, message)
+      replace_or_insert_annotation(file_path: file_path, marker: 'columns', content: message,
+                                   before: /^class\s+\w+\s+<\s+\w+/, position: @annotation_position)
     end
 
     def model_file_path(model_name)
       file_path = "#{@model_dir}/#{model_name}.rb"
 
       unless File.exist?(file_path)
-        say "Model file not found"
-        raise NotFoundError
+        say 'Model file not found'
+        raise AwesomeAnnotate::NotFoundError
       end
 
-      return file_path
+      file_path
     end
 
-    def klass_name(model_name)
+    def klass_name(model_name, report_missing: true)
       name = model_name.singularize.camelize
-      return Object.const_get(name)
-
+      Object.const_get(name)
     rescue NameError
-      say "Model not found"
-      raise NotFoundError
+      say 'Model not found' if report_missing
+      raise AwesomeAnnotate::NotFoundError
     end
 
-    def self.source_root
-      Dir.pwd
-    end
+    def self.source_root = Dir.pwd
+
+    private_class_method :source_root
   end
 end

data/lib/awesome_annotate/rails_environment.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module AwesomeAnnotate
+  module RailsEnvironment
+    private
+
+    def load_rails_environment
+      require @env_file_path.expand_path.to_s
+    end
+  end
+end

data/lib/awesome_annotate/route.rb

@@ -1,21 +1,29 @@
+# frozen_string_literal: true
+
 require 'active_record'
 require 'thor'
+require_relative 'annotation_block'
+require_relative 'rails_environment'
 
 module AwesomeAnnotate
   class Route < Thor
+    include AnnotationBlock
     include Thor::Actions
+    include RailsEnvironment
 
     def initialize(params = {})
       super()
       @env_file_path = Pathname.new(params[:env_file_path] || 'config/environment.rb')
       @route_file_path = Pathname.new(params[:route_file_path] || 'config/routes.rb')
+      @annotation_position = params[:annotation_position] || 'top'
+      @exclude_routes = params[:exclude_routes] || []
     end
 
     desc 'annotate all routes', 'annotate your routes'
     def annotate
-      raise "Rails application path is required" unless @env_file_path.exist?
+      raise 'Rails application path is required' unless @env_file_path.exist?
 
-      apply @env_file_path.to_s
+      load_rails_environment
 
       inspector = ActionDispatch::Routing::RoutesInspector.new(Rails.application.routes.routes)
       formatter = ActionDispatch::Routing::ConsoleFormatter::Sheet.new
@@ -23,17 +31,28 @@ module AwesomeAnnotate
       routes = inspector.format(formatter, {})
       route_message = parse_routes(routes)
 
-      raise "Route file not found" unless @route_file_path.exist?
+      raise 'Route file not found' unless @route_file_path.exist?
 
       insert_file_before_class(@route_file_path, route_message)
 
       say "annotate routes in #{@route_file_path}"
     end
 
+    desc 'remove', 'remove route annotation'
+    def remove
+      raise 'Route file not found' unless @route_file_path.exist?
+
+      if remove_annotation(file_path: @route_file_path, marker: 'routes')
+        say "remove route annotation in #{@route_file_path}"
+      else
+        say "no route annotation in #{@route_file_path}"
+      end
+    end
+
     private
 
     def parse_routes(routes)
-      split_routes = routes.split(/\r\n|\r|\n/)
+      split_routes = routes.split(/\r\n|\r|\n/).reject { |route| excluded_route?(route) }
       parse_routes = split_routes.map do |route|
         "# #{route}\n"
       end
@@ -42,14 +61,23 @@ module AwesomeAnnotate
       parse_routes.join
     end
 
+    def excluded_route?(route)
+      @exclude_routes.any? { |pattern| File.fnmatch?(pattern, route.strip) }
+    end
+
     def insert_file_before_class(file_path, message)
-      insert_into_file file_path, :before => "Rails.application.routes.draw do\n" do
-        message
-      end
+      replace_or_insert_annotation(
+        file_path: file_path,
+        marker: 'routes',
+        content: message,
+        before: "Rails.application.routes.draw do\n",
+        position: @annotation_position
+      )
     end
 
     def self.source_root
       Dir.pwd
     end
+    private_class_method :source_root
   end
 end

data/lib/awesome_annotate/schema_annotation.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module AwesomeAnnotate
+  module SchemaAnnotation
+    private
+
+    def schema_annotation(klass)
+      columns = schema_columns(klass)
+
+      [
+        schema_header(klass),
+        column_annotations(klass, columns),
+        include_indexes? ? index_annotations(klass) : '',
+        "#\n"
+      ].join
+    end
+
+    def include_indexes?
+      @include_indexes != false
+    end
+
+    def include_column_defaults?
+      @include_column_defaults != false
+    end
+
+    def schema_columns(klass)
+      klass.columns.reject { |column| @exclude_columns.include?(column.name) }
+    end
+
+    def schema_header(klass)
+      [
+        "# == Schema Information\n",
+        "#\n",
+        "# Table name: #{klass.table_name}\n",
+        "#\n"
+      ].join
+    end
+
+    def column_annotations(klass, columns)
+      column_name_width = columns.map { |column| column.name.length }.max || 0
+      column_type_width = columns.map { |column| column_type(column).length }.max || 0
+
+      columns.map { |column| column_annotation(klass, column, column_name_width, column_type_width) }.join
+    end
+
+    def column_annotation(klass, column, column_name_width, column_type_width)
+      column_name = column.name.ljust(column_name_width)
+      type = column_type(column).ljust(column_type_width)
+      details = column_details(klass, column)
+      line = "#  #{column_name} :#{type}"
+
+      line = "#{line} #{details.join(', ')}" if details.any?
+      "#{line}\n"
+    end
+
+    def column_type(column)
+      column.type.to_s
+    end
+
+    def column_details(klass, column)
+      details = []
+      details << 'not null' if column.null == false
+      details << 'primary key' if column.name == klass.primary_key
+      details << "default(#{column.default.inspect})" if include_column_defaults? && !column.default.nil?
+      details
+    end
+
+    def index_annotations(klass)
+      indexes = klass.connection.indexes(klass.table_name)
+      return '' if indexes.empty?
+
+      index_column_width = indexes.map { |index| index_columns(index).length }.max || 0
+
+      [
+        "#\n",
+        "# Indexes\n",
+        "#\n",
+        indexes.map { |index| index_annotation(index, index_column_width) }.join
+      ].join
+    end
+
+    def index_annotation(index, index_column_width)
+      columns = index_columns(index).ljust(index_column_width)
+      details = index_details(index)
+
+      "#  #{columns}  #{details.join(', ')}\n"
+    end
+
+    def index_columns(index)
+      "(#{index.columns.join(',')})"
+    end
+
+    def index_details(index)
+      details = []
+      details << 'UNIQUE' if index.unique
+      details << index.name
+      details
+    end
+  end
+end

data/lib/awesome_annotate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AwesomeAnnotate
-  VERSION = "0.1.5"
+  VERSION = '0.3.1'
 end

data/lib/awesome_annotate.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "awesome_annotate/version"
-require_relative "awesome_annotate/cli"
-
-module AwesomeAnnotate
-  class Error < StandardError; end
-end
+require_relative 'awesome_annotate/version'
+require_relative 'awesome_annotate/error'
+require_relative 'awesome_annotate/configuration'
+require_relative 'awesome_annotate/cli'

metadata

@@ -1,65 +1,74 @@
 --- !ruby/object:Gem::Specification
 name: awesome_annotate
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.3.1
 platform: ruby
 authors:
 - wisdom-plus
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-03 00:00:00.000000000 Z
+date: 2026-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: thor
+  name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
 - !ruby/object:Gem::Dependency
-  name: activerecord
+  name: thor
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 6.1.0
+        version: '1.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 6.1.0
+        version: '1.3'
 description: annotate your code with comments (e.g. model schema, routes, etc.)
 email:
-- wisdom.plus.264.dev@gmail.com
+- wisdom-plus@users.noreply.github.com
 executables:
 - awesome_annotate
 extensions: []
 extra_rdoc_files: []
 files:
 - ".rspec"
-- ".rspec_status"
 - ".rubocop.yml"
+- ".ruby-version"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
-- awesome_annotate.gemspec
 - exe/awesome_annotate
 - lib/awesome_annotate.rb
+- lib/awesome_annotate/annotation_block.rb
 - lib/awesome_annotate/cli.rb
+- lib/awesome_annotate/configuration.rb
 - lib/awesome_annotate/error.rb
 - lib/awesome_annotate/model.rb
+- lib/awesome_annotate/rails_environment.rb
 - lib/awesome_annotate/route.rb
+- lib/awesome_annotate/schema_annotation.rb
 - lib/awesome_annotate/version.rb
 - sig/awesome_annotate.rbs
 homepage: https://github.com/wisdom-plus/awesome_annotate
@@ -70,6 +79,7 @@ metadata:
   homepage_uri: https://github.com/wisdom-plus/awesome_annotate
   source_code_uri: https://github.com/wisdom-plus/awesome_annotate
   changelog_uri: https://github.com/wisdom-plus/awesome_annotate/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -78,14 +88,17 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: '3.0'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '4.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: annotate your code with comments

data/.rspec_status

@@ -1,11 +0,0 @@
-example_id                                           | status | run_time        |
----------------------------------------------------- | ------ | --------------- |
-./spec/awesome_annotate_spec.rb[1:1]                 | passed | 0.00031 seconds |
-./spec/lib/awesome_annotate/cli_spec.rb[1:3:1]       | passed | 0.00185 seconds |
-./spec/lib/awesome_annotate/model_spec.rb[1:1:1:1:1] | passed | 0.19755 seconds |
-./spec/lib/awesome_annotate/model_spec.rb[1:1:1:2:1] | passed | 0.00078 seconds |
-./spec/lib/awesome_annotate/model_spec.rb[1:1:1:3:1] | passed | 0.00018 seconds |
-./spec/lib/awesome_annotate/model_spec.rb[1:1:2:1]   | passed | 0.00008 seconds |
-./spec/lib/awesome_annotate/route_spec.rb[1:1:1:1:1] | passed | 0.00303 seconds |
-./spec/lib/awesome_annotate/route_spec.rb[1:1:1:2:1] | passed | 0.0005 seconds  |
-./spec/lib/awesome_annotate/route_spec.rb[1:1:2:1]   | passed | 0.00009 seconds |

data/awesome_annotate.gemspec

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/awesome_annotate/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "awesome_annotate"
-  spec.version = AwesomeAnnotate::VERSION
-  spec.authors = ["wisdom-plus"]
-  spec.email = ["wisdom.plus.264.dev@gmail.com"]
-
-  spec.summary = "annotate your code with comments"
-  spec.description = "annotate your code with comments (e.g. model schema, routes, etc.)"
-  spec.homepage = "https://github.com/wisdom-plus/awesome_annotate"
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.0.0"
-
-  spec.metadata["allowed_push_host"] = "https://rubygems.org"
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = spec.homepage
-  spec.metadata["changelog_uri"] = spec.homepage + "/blob/main/CHANGELOG.md"
-
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) ||
-        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
-    end
-  end
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-  spec.add_dependency "thor"
-  spec.add_dependency "activerecord", ">= 6.1.0"
-end