awesome_annotate 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d120e2f6dba99ee06506353a609f7b68e4ad08213141762b77ca6dacacc854ce
-  data.tar.gz: 6bb8098703ec777bfc7dcc9351ca88ed4c2f9655cb122c71f25b398165aad187
+  metadata.gz: 4c4c2fe792fc935930fcc07c2a9662f7032cd590bcad80f06551e5dae567f279
+  data.tar.gz: 62db756fb9535984c36eda116f23aa2130ba18b2077c8102423d8b559e075e78
 SHA512:
-  metadata.gz: d04a22f78762b7fd4de71460b710b512b3c23e126ce136afa326a7aa1a32f7bc9be2c72ed7fa3a740da266ae2cea8883d0a156296089a1ed3dc8fa0b88ae02f7
-  data.tar.gz: d64c97ff823e7eb03e2f16a9e511343ef6dc9856c33e78b2e0003e8ccaf390ce7adc87dedb62a1299aa320b0293d9a148677fbc86b7d9e6886d8e3c210ee9a1a
+  metadata.gz: 33795981d662f1eeae3be75bb11befd25aaed09d22f50c26647d131c1916ea54eb9f2a105272a8e42e4cb6c80a5df3c474cda12c4a9c566c0e9452512d40ac33
+  data.tar.gz: ae8e56afa0844d88bbb2d1cae87e12538846ccf507394943259c8856e548d7e70e9c1e49cdc8d42ce3c7e8ada99900df46f8b251396cdb8161f976c4ad25ae2f

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # 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,

data/README.md

@@ -51,6 +51,7 @@ 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
@@ -90,6 +91,40 @@ 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`:

data/lib/awesome_annotate/annotation_block.rb

@@ -4,12 +4,12 @@ module AwesomeAnnotate
   module AnnotationBlock
     private
 
-    def replace_or_insert_annotation(file_path:, marker:, content:, before:)
+    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))
+      File.write(path, replace_annotation(file_content, marker, annotation, before, position))
     end
 
     def remove_annotation(file_path:, marker:)
@@ -36,11 +36,13 @@ module AwesomeAnnotate
       %r{^# == AwesomeAnnotate: #{escaped_marker}\n.*?^# == /AwesomeAnnotate: #{escaped_marker}\n(?:\n)*}m
     end
 
-    def replace_annotation(file_content, marker, annotation, before)
+    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

data/lib/awesome_annotate/cli.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'awesome_annotate'
+require 'awesome_annotate/configuration'
 require 'awesome_annotate/model'
 require 'awesome_annotate/route'
 require 'awesome_annotate/version'
@@ -10,23 +11,37 @@ module AwesomeAnnotate
   class Remove < Thor
     desc 'model [model_name]', 'remove annotation from a model'
     def model(model_name)
-      AwesomeAnnotate::Model.new.remove(model_name)
+      model_annotator.remove(model_name)
     end
 
     desc 'models [model_names...]', 'remove annotations from all models or specified models'
     def models(*model_names)
-      AwesomeAnnotate::Model.new.remove_all(model_names)
+      model_annotator.remove_all(model_names)
     end
 
     desc 'routes', 'remove annotation from `config/routes.rb`'
     def routes
-      AwesomeAnnotate::Route.new.remove
+      route_annotator.remove
     end
 
     desc 'all', 'remove annotations from all models and routes'
     def all
-      AwesomeAnnotate::Model.new.remove_all
-      AwesomeAnnotate::Route.new.remove
+      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
 
@@ -42,24 +57,35 @@ 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)
-      AwesomeAnnotate::Model.new.annotate_all(model_names)
+      model_annotator.annotate_all(model_names)
     end
 
     map %w[routes -r] => :routes
     desc 'routes', 'Writes application route information to `config/routes.rb`.'
     def routes
-      AwesomeAnnotate::Route.new.annotate
+      route_annotator.annotate
     end
 
     desc 'all', 'annotate all models and routes'
     def all
-      AwesomeAnnotate::Model.new.annotate_all
-      AwesomeAnnotate::Route.new.annotate
+      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'
@@ -68,5 +94,19 @@ module AwesomeAnnotate
     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/model.rb

@@ -18,6 +18,11 @@ module AwesomeAnnotate
       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'
@@ -75,9 +80,7 @@ module AwesomeAnnotate
       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 { |file_path| excluded_model_file?(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
@@ -86,7 +89,12 @@ module AwesomeAnnotate
     def excluded_model_file?(file_path)
       relative_path = Pathname.new(file_path).relative_path_from(@model_dir).to_s
 
-      relative_path == 'application_record.rb' || relative_path.start_with?('concerns/')
+      relative_path == 'application_record.rb' || relative_path.start_with?('concerns/') ||
+        excluded_by_config?(relative_path)
+    end
+
+    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)
@@ -104,12 +112,8 @@ module AwesomeAnnotate
     end
 
     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+/
-      )
+      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)
@@ -131,9 +135,8 @@ module AwesomeAnnotate
       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/route.rb

@@ -15,6 +15,8 @@ module AwesomeAnnotate
       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'
@@ -50,7 +52,7 @@ module AwesomeAnnotate
     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
@@ -59,12 +61,17 @@ 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)
       replace_or_insert_annotation(
         file_path: file_path,
         marker: 'routes',
         content: message,
-        before: "Rails.application.routes.draw do\n"
+        before: "Rails.application.routes.draw do\n",
+        position: @annotation_position
       )
     end
 

data/lib/awesome_annotate/schema_annotation.rb

@@ -5,18 +5,28 @@ module AwesomeAnnotate
     private
 
     def schema_annotation(klass)
-      columns = 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 = schema_columns(klass)
 
       [
         schema_header(klass),
-        columns.map { |column| column_annotation(klass, column, column_name_width, column_type_width) }.join,
-        index_annotations(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",
@@ -26,6 +36,13 @@ module AwesomeAnnotate
       ].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)
@@ -44,7 +61,7 @@ module AwesomeAnnotate
       details = []
       details << 'not null' if column.null == false
       details << 'primary key' if column.name == klass.primary_key
-      details << "default(#{column.default.inspect})" unless column.default.nil?
+      details << "default(#{column.default.inspect})" if include_column_defaults? && !column.default.nil?
       details
     end
 

data/lib/awesome_annotate/version.rb

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

data/lib/awesome_annotate.rb

@@ -2,4 +2,5 @@
 
 require_relative 'awesome_annotate/version'
 require_relative 'awesome_annotate/error'
+require_relative 'awesome_annotate/configuration'
 require_relative 'awesome_annotate/cli'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: awesome_annotate
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - wisdom-plus
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-10 00:00:00.000000000 Z
+date: 2026-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -63,6 +63,7 @@ files:
 - 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