rails-ai-context 5.19.0 → 5.19.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46645f9291dee2458c1a03529fcf888bfd4d11be1d742310f224ae439baed82f
-  data.tar.gz: 6c1a79f00117f9617970e5c0f1380337fdc17578fe350515d1a8d301a0fef3fd
+  metadata.gz: 175ccbf5bac4703a8f9699708a02435a9b80546c09129deae79ffb5f182e14e6
+  data.tar.gz: 0adbdf439e6ac853606fc786d6f92041a70aec4e2379ebfe98132eb14352b219
 SHA512:
-  metadata.gz: 6ffd81a61373550ad0df085b3c01dc647de386bd79773b148711d8f040969f8a7f71fffb4e059539deef7285fc1fa21480761bd9f04cbaabd7aaaebab0e84e9d
-  data.tar.gz: c83fe3ae8dfa8bb663bba3b09dd6cd8b3b29939e2ae7ce6cf379cb9df0f739a2b21e86976a6741bee103240324f6e6118ba1fdf85b70d36927a702521e48a159
+  metadata.gz: 9bb08e8b5d06124360be6870c7f667f008a666d07bea55a33b89662049ea1ee00b3ab88b5c5060ee70c47b8d1b77c422cfd8434f3327094427e2ac321c8a9201
+  data.tar.gz: 160c8b647c1a6be4bec7290be0308a98318edd92c2525235410bd1fed94459ddd107538f5ced4c8fced29745a9de00aa8dfc37f0bdc9274afa358c0aa2f82e3f

data/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.19.1] - 2026-08-10
+
+### Fixed
+
+- **Static-tier routes no longer inherit a closed `namespace` block.**
+  `SourceIntrospector` registered its listeners for every Prism event except
+  `:on_call_node_leave`, so the two listeners that pop a scope stack never
+  received it. With `--no-boot`, every route declared after a
+  `namespace :admin do ... end` block was reported under that namespace, so an
+  app with `/comments` and `/health` served `/admin/comments` and
+  `/admin/health` tagged `[VERIFIED]`. The same cause put a gem declared after
+  a `group :development do ... end` block into that group in
+  `rails_get_gems`' group listing. Booted mode was never affected.
+- **`rails_get_i18n` coverage is measured against the default locale's keys.**
+  It compared raw key counts, so a locale defining five keys against a
+  one-key default reported `500.0%`. Coverage is now the share of the default
+  locale's keys the other locale also defines, and each locale reports how
+  many keys are missing and how many it adds beyond the default.
+- **`rails_get_autoload` reports each path once.** Rails lists a path once per
+  railtie that contributed it, so an app using `config.autoload_lib` showed
+  `lib` twice under a count of two.
+- **Counts of one read as singular.** Tools, generated context files, `doctor`,
+  `facts`, the rake tasks and the standalone CLI wrote `1 keys`,
+  `1 associations`, `1 pending migration(s)` and the like. A locale file with
+  one key now reads `1 key`, a model with one association reads
+  `1 association`, and `facts` reads `1 index, 1 FK`. Counts render through
+  one shared helper, replacing the four spellings that had grown up across the
+  render code: raw interpolation, a `== 1 ?` ternary, an `#{"s" unless n == 1}`
+  suffix, and the `(s)` hedge. A handful of sites keep raw interpolation on
+  purpose: ratios (`1/1 files passed`), diff stats, and byte or row counts
+  whose branch only runs past a limit.
+- **A locale file with a symbol root key counts toward coverage.** Both `en:`
+  and `:en:` load as valid YAML, but only the string form had its root
+  stripped, so a symbol-rooted locale compared its `es.`-prefixed paths
+  against nothing and scored 0%.
+
 ## [5.19.0] - 2026-08-09
 
 ### Added - 6 new tools surfacing previously unserved introspection (45 tools total)

data/exe/rails-ai-context

@@ -222,7 +222,7 @@ class RailsAiContextCLI < Thor
 
       failed = result[:checks].count { |c| c.status == :fail }
       if options[:strict] && failed > 0
-        $stderr.puts "#{failed} check#{'s' unless failed == 1} failed (--strict)"
+        $stderr.puts "#{RailsAiContext::CountPhrase.call(failed, "check")} failed (--strict)"
         exit 1
       end
     end
@@ -552,7 +552,7 @@ class RailsAiContextCLI < Thor
       $stderr.puts ""
       $stderr.puts "Commands:"
       $stderr.puts "  rails-ai-context context    # Regenerate context files"
-      $stderr.puts "  rails-ai-context tool NAME  # Run any of the #{tool_count_str} tools"
+      $stderr.puts "  rails-ai-context tool NAME  # Run any of the #{RailsAiContext::CountPhrase.call(builtin_tool_count, "tool")}"
       if tool_mode == :mcp
         $stderr.puts "  rails-ai-context serve      # Start MCP server"
       end
@@ -571,12 +571,10 @@ class RailsAiContextCLI < Thor
       $stderr.puts ""
     end
 
-    def tool_count_str
-      if defined?(::RailsAiContext::Server)
-        ::RailsAiContext::Server.builtin_tools.size.to_s
-      else
-        "45"
-      end
+    def builtin_tool_count
+      return ::RailsAiContext::Server.builtin_tools.size if defined?(::RailsAiContext::Server)
+
+      45
     end
 
     def print_context_result(result)

data/lib/generators/rails_ai_context/install/install_generator.rb

@@ -215,8 +215,8 @@ module RailsAiContext
         "Introspection" => <<~SECTION,
             # ── Introspection ─────────────────────────────────────────────────
             # Introspector preset:
-            #   :full     - all #{RailsAiContext::Configuration::PRESETS[:full].size} introspectors (default)
-            #   :standard - #{RailsAiContext::Configuration::PRESETS[:standard].size} core introspectors (schema, models, routes, jobs, gems,
+            #   :full     - all #{CountPhrase.call(RailsAiContext::Configuration::PRESETS[:full].size, 'introspector')} (default)
+            #   :standard - #{CountPhrase.call(RailsAiContext::Configuration::PRESETS[:standard].size, 'core introspector')} (schema, models, routes, jobs, gems,
             #               conventions, controllers, tests, migrations, stimulus,
             #               view_templates, config, components)
             # config.preset = :full
@@ -283,7 +283,7 @@ module RailsAiContext
         SECTION
         "Extensibility" => <<~SECTION,
             # ── Extensibility ─────────────────────────────────────────────────
-            # Register additional MCP tool classes alongside the #{RailsAiContext::Server.builtin_tools.size} built-in tools
+            # Register additional MCP tool classes alongside the #{CountPhrase.call(RailsAiContext::Server.builtin_tools.size, 'built-in tool')}
             # config.custom_tools = ["MyApp::CustomTool"]  # class name as string - resolved after boot
 
             # Exclude specific built-in tools by name
@@ -406,7 +406,7 @@ module RailsAiContext
         content, = ensure_initializer_guard(content)
 
         create_file path, content
-        say "Created #{path} with all #{CONFIG_SECTIONS.size} config sections", :green
+        say "Created #{path} with all #{CountPhrase.call(CONFIG_SECTIONS.size, "config section")}", :green
       end
 
       def update_existing_initializer(full_path)
@@ -693,9 +693,9 @@ module RailsAiContext
         say "Commands:", :yellow
         say "  rails ai:context         # Regenerate context files"
         tool_count = RailsAiContext::Server.builtin_tools.size
-        say "  rails 'ai:tool[schema]'    # Run any of the #{tool_count} tools from CLI"
+        say "  rails 'ai:tool[schema]'    # Run any of the #{CountPhrase.call(tool_count, "tool")} from CLI"
         if @tool_mode == :mcp
-          say "  rails ai:serve           # Start MCP server (#{tool_count} live tools)"
+          say "  rails ai:serve           # Start MCP server (#{CountPhrase.call(tool_count, "live tool")})"
         end
         say "  rails ai:facts           # Print concise schema facts summary"
         say "  rails 'ai:preset[arch]'   # Run multi-tool presets (architecture, debugging, migration)"

data/lib/rails_ai_context/count_phrase.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+
+module RailsAiContext
+  # Renders a count with its noun. Raw interpolation reads wrong at one
+  # ("1 models"), and every tool and serializer that reports a count needs
+  # the same fix, so they share this rather than each spelling it out.
+  module CountPhrase
+    # Pass `plural` where the inflector's answer is wrong for the domain:
+    # database docs say indexes, not the inflector's indices.
+    def self.call(count, noun, plural: nil)
+      "#{count} #{count == 1 ? noun : plural || noun.pluralize}"
+    end
+
+    private
+
+    # Mixed in for the classes; rake tasks and generators, which have no class
+    # to mix into, call CountPhrase.call directly.
+    def count_phrase(count, noun, plural: nil)
+      CountPhrase.call(count, noun, plural: plural)
+    end
+  end
+end

data/lib/rails_ai_context/doctor.rb

@@ -4,6 +4,8 @@ module RailsAiContext
   # Diagnostic checker that validates the environment and reports
   # AI readiness with pass/warn/fail checks and a readiness score.
   class Doctor
+    include CountPhrase
+
     Check = Data.define(:name, :status, :message, :fix)
 
     CHECKS = %i[
@@ -67,7 +69,7 @@ module RailsAiContext
       structure_path = File.join(app.root, "db/structure.sql")
       if File.exist?(schema_path)
         lines = File.readlines(schema_path).size
-        Check.new(name: "Schema", status: :pass, message: "db/schema.rb found (#{lines} lines)", fix: nil)
+        Check.new(name: "Schema", status: :pass, message: "db/schema.rb found (#{count_phrase(lines, "line")})", fix: nil)
       elsif File.exist?(structure_path)
         size = (File.size(structure_path) / 1024.0).round(1)
         Check.new(name: "Schema", status: :pass, message: "db/structure.sql found (#{size}KB)", fix: nil)
@@ -86,7 +88,7 @@ module RailsAiContext
         Check.new(name: "Pending migrations", status: :pass, message: "No pending migrations", fix: nil)
       else
         Check.new(name: "Pending migrations", status: :fail,
-          message: "#{pending.size} pending migration(s) - schema data will be stale",
+          message: "#{count_phrase(pending.size, "pending migration")} - schema data will be stale",
           fix: "Run `rails db:migrate`")
       end
     end
@@ -95,7 +97,7 @@ module RailsAiContext
       models_dir = File.join(app.root, "app/models")
       if Dir.exist?(models_dir) && Dir.glob(File.join(models_dir, "**/*.rb")).any?
         count = Dir.glob(File.join(models_dir, "**/*.rb")).size
-        Check.new(name: "Models", status: :pass, message: "#{count} model files found", fix: nil)
+        Check.new(name: "Models", status: :pass, message: "#{count_phrase(count, "model file")} found", fix: nil)
       else
         Check.new(name: "Models", status: :warn, message: "No model files in app/models/", fix: "Generate models with `rails generate model`")
       end
@@ -123,7 +125,7 @@ module RailsAiContext
       dir = File.join(app.root, "app/controllers")
       if Dir.exist?(dir) && Dir.glob(File.join(dir, "**/*.rb")).any?
         count = Dir.glob(File.join(dir, "**/*.rb")).size
-        Check.new(name: "Controllers", status: :pass, message: "#{count} controller files found", fix: nil)
+        Check.new(name: "Controllers", status: :pass, message: "#{count_phrase(count, "controller file")} found", fix: nil)
       else
         Check.new(name: "Controllers", status: :warn, message: "No controller files", fix: nil)
       end
@@ -133,7 +135,7 @@ module RailsAiContext
       dir = File.join(app.root, "app/views")
       if Dir.exist?(dir)
         count = Dir.glob(File.join(dir, "**/*")).reject { |f| File.directory?(f) }.size
-        Check.new(name: "Views", status: :pass, message: "#{count} view files found", fix: nil)
+        Check.new(name: "Views", status: :pass, message: "#{count_phrase(count, "view file")} found", fix: nil)
       else
         Check.new(name: "Views", status: :warn, message: "No view files", fix: nil)
       end
@@ -153,7 +155,7 @@ module RailsAiContext
       migrate_dir = File.join(app.root, "db/migrate")
       if Dir.exist?(migrate_dir) && Dir.glob(File.join(migrate_dir, "*.rb")).any?
         count = Dir.glob(File.join(migrate_dir, "*.rb")).size
-        Check.new(name: "Migrations", status: :pass, message: "#{count} migration #{count == 1 ? 'file' : 'files'}", fix: nil)
+        Check.new(name: "Migrations", status: :pass, message: count_phrase(count, "migration file"), fix: nil)
       else
         Check.new(name: "Migrations", status: :warn, message: "No migrations", fix: nil)
       end
@@ -289,13 +291,13 @@ module RailsAiContext
 
       if failures.empty?
         Check.new(name: "MCP configs", status: :pass,
-          message: "#{checks.size} of #{checks.size} MCP config(s) valid",
+          message: "#{checks.size} of #{count_phrase(checks.size, "MCP config")} valid",
           fix: nil)
       else
         labels = failures.map { |c| c.name }
         worst_status = failures.any? { |c| c.status == :fail } ? :fail : :warn
         Check.new(name: "MCP configs", status: worst_status,
-          message: "#{failures.size} of #{checks.size} MCP config(s) need attention: #{labels.join(', ')}",
+          message: "#{failures.size} of #{count_phrase(checks.size, "MCP config")} #{failures.size == 1 ? "needs" : "need"} attention: #{labels.join(', ')}",
           fix: "Run `rails generate rails_ai_context:install` to fix")
       end
     end
@@ -401,12 +403,12 @@ module RailsAiContext
 
       if errors.empty?
         Check.new(name: "Introspector health", status: :pass,
-          message: "All #{config.introspectors.size} introspectors return data " \
-            "(these feed the #{Server.builtin_tools.size} MCP tools)",
+          message: "All #{count_phrase(config.introspectors.size, "introspector")} return data " \
+            "(these feed the #{count_phrase(Server.builtin_tools.size, "MCP tool")})",
           fix: nil)
       else
         Check.new(name: "Introspector health", status: :warn,
-          message: "#{errors.size} introspector(s) returned errors: #{errors.join(', ')}",
+          message: "#{count_phrase(errors.size, "introspector")} returned errors: #{errors.join(', ')}",
           fix: "Check if the app has the required features (e.g., stimulus needs app/javascript/controllers/)")
       end
     rescue => e
@@ -420,7 +422,8 @@ module RailsAiContext
 
       stimulus_dir = File.join(app.root, "app/javascript/controllers")
       if Dir.exist?(stimulus_dir) && Dir.glob(File.join(stimulus_dir, "**/*_controller.{js,ts}")).any? && !config.introspectors.include?(:stimulus)
-        suggestions << "stimulus (#{Dir.glob(File.join(stimulus_dir, '**/*_controller.{js,ts}')).size} controllers found)"
+        stimulus_count = Dir.glob(File.join(stimulus_dir, "**/*_controller.{js,ts}")).size
+        suggestions << "stimulus (#{count_phrase(stimulus_count, "controller")} found)"
       end
 
       views_dir = File.join(app.root, "app/views")
@@ -429,8 +432,9 @@ module RailsAiContext
       end
 
       i18n_dir = File.join(app.root, "config/locales")
-      if Dir.exist?(i18n_dir) && Dir.glob(File.join(i18n_dir, "**/*.{yml,yaml}")).size > 1 && !config.introspectors.include?(:i18n)
-        suggestions << "i18n (#{Dir.glob(File.join(i18n_dir, '**/*.{yml,yaml}')).size} locale files)"
+      locale_file_count = Dir.exist?(i18n_dir) ? Dir.glob(File.join(i18n_dir, "**/*.{yml,yaml}")).size : 0
+      if locale_file_count > 1 && !config.introspectors.include?(:i18n)
+        suggestions << "i18n (#{count_phrase(locale_file_count, "locale file")})"
       end
 
       graphql_dir = File.join(app.root, "app/graphql")
@@ -440,7 +444,7 @@ module RailsAiContext
 
       if suggestions.empty?
         Check.new(name: "Preset coverage", status: :pass,
-          message: "#{config.introspectors.size} introspectors cover detected features",
+          message: "#{count_phrase(config.introspectors.size, "introspector")} cover detected features",
           fix: nil)
       else
         Check.new(name: "Preset coverage", status: :warn,
@@ -647,11 +651,11 @@ module RailsAiContext
 
       if pct >= 80
         Check.new(name: "View aggregation size", status: :warn,
-          message: "#{count} view files totaling #{(total_size / 1_000_000.0).round(1)}MB (#{pct}% of #{(limit / 1_000_000.0).round}MB limit for UI pattern extraction)",
+          message: "#{count_phrase(count, "view file")} totaling #{(total_size / 1_000_000.0).round(1)}MB (#{pct}% of #{(limit / 1_000_000.0).round}MB limit for UI pattern extraction)",
           fix: "Increase `config.max_view_total_size` or `config.max_view_file_size`")
       else
         Check.new(name: "View aggregation size", status: :pass,
-          message: "#{count} view files (#{(total_size / 1024.0).round}KB total, within limits)",
+          message: "#{count_phrase(count, "view file")} (#{(total_size / 1024.0).round}KB total, within limits)",
           fix: nil)
       end
     end

data/lib/rails_ai_context/facts_formatter.rb

@@ -5,6 +5,8 @@ module RailsAiContext
   # the standalone CLI (rails-ai-context facts) so both outputs stay in sync.
   class FactsFormatter
     class << self
+      include CountPhrase
+
       def render(context, inspect_hint: "rails ai:inspect")
         lines = []
         lines << "# #{app_name(context)} - Schema Facts"
@@ -41,9 +43,9 @@ module RailsAiContext
           cols = meta[:columns]&.size || 0
           indexes = meta[:indexes]&.size || 0
           fks = meta[:foreign_keys]&.size || 0
-          lines << "- #{name} (#{cols} #{cols == 1 ? 'col' : 'cols'}, " \
-            "#{indexes} #{indexes == 1 ? 'index' : 'indexes'}, " \
-            "#{fks} #{fks == 1 ? 'FK' : 'FKs'})"
+          lines << "- #{name} (#{count_phrase(cols, "col")}, " \
+            "#{count_phrase(indexes, "index", plural: "indexes")}, " \
+            "#{count_phrase(fks, "FK", plural: "FKs")})"
         end
         lines << ""
         lines

data/lib/rails_ai_context/introspectors/autoload_introspector.rb

@@ -133,11 +133,12 @@ module RailsAiContext
         "#{hit[:method]}: #{values.first}"
       end
 
+      # Rails lists a path once per railtie that contributed it.
       def relativize(paths)
-        Array(paths).map do |p|
+        Array(paths).map { |p|
           s = p.to_s
           s.start_with?(root) ? s.sub("#{root}/", "") : s
-        end
+        }.uniq
       end
     end
   end

data/lib/rails_ai_context/introspectors/i18n_introspector.rb

@@ -61,9 +61,8 @@ module RailsAiContext
         Dir.glob(File.join(dir, "**/*.{yml,yaml,rb}")).size
       end
 
-      def count_keys(hash, depth: 0)
-        return 0 unless hash.is_a?(Hash)
-        hash.sum { |_, v| v.is_a?(Hash) ? count_keys(v, depth: depth + 1) : 1 }
+      def count_keys(hash)
+        nested_key_paths(hash).size
       end
 
       def detect_fallback_config
@@ -79,12 +78,21 @@ module RailsAiContext
         locales = I18n.available_locales
         return {} if locales.size < 2
 
-        # Compare key counts between default and other locales
+        # Coverage is the share of the default locale's keys that the other
+        # locale also defines. Comparing raw counts instead reports over 100%
+        # for a locale that translates few default keys but adds many of its
+        # own - the one number a translator must not be told is fine.
         coverage = {}
-        default_count = count_keys_for_locale(I18n.default_locale)
+        default_keys = key_paths_for_locale(I18n.default_locale)
         locales.reject { |l| l == I18n.default_locale }.each do |locale|
-          locale_count = count_keys_for_locale(locale)
-          coverage[locale.to_s] = { keys: locale_count, coverage_pct: default_count > 0 ? ((locale_count.to_f / default_count) * 100).round(1) : 0 }
+          locale_keys = key_paths_for_locale(locale)
+          translated = (default_keys & locale_keys).size
+          coverage[locale.to_s] = {
+            keys: locale_keys.size,
+            missing: (default_keys - locale_keys).size,
+            extra: (locale_keys - default_keys).size,
+            coverage_pct: default_keys.any? ? ((translated.to_f / default_keys.size) * 100).round(1) : 0
+          }
         end
         coverage
       rescue => e
@@ -92,20 +100,26 @@ module RailsAiContext
         {}
       end
 
-      def count_keys_for_locale(locale)
-        paths = find_locale_paths(locale)
-        return 0 if paths.empty?
-        paths.sum do |path|
+      # Dotted key paths a locale defines, with the locale root stripped so
+      # `en.posts.title` and `es.posts.title` compare as the same key.
+      def key_paths_for_locale(locale)
+        loc = locale.to_s
+        find_locale_paths(locale).flat_map do |path|
           content = RailsAiContext::SafeFile.read(path)
-          next 0 unless content
+          next [] unless content
           data = YAML.safe_load(content, permitted_classes: [ Symbol ])
-          count_nested_keys(data)
+          next [] unless data.is_a?(Hash)
+
+          # A locale root may be written `en:` or `:en:` - both load, and both
+          # have to be stripped or this locale's paths compare against nothing.
+          root = data.key?(loc) ? data[loc] : data.fetch(locale.to_sym, data)
+          nested_key_paths(root)
         rescue StandardError
-          0
-        end
+          []
+        end.uniq
       rescue => e
-        $stderr.puts "[rails-ai-context] count_keys_for_locale failed: #{e.message}" if ENV["DEBUG"]
-        0
+        $stderr.puts "[rails-ai-context] key_paths_for_locale failed: #{e.message}" if ENV["DEBUG"]
+        []
       end
 
       # Finds all YAML files contributing translations for the given locale:
@@ -124,10 +138,13 @@ module RailsAiContext
         end
       end
 
-      def count_nested_keys(hash, count = 0)
-        return count unless hash.is_a?(Hash)
-        hash.each_value { |v| count = v.is_a?(Hash) ? count_nested_keys(v, count) : count + 1 }
-        count
+      def nested_key_paths(hash, prefix = nil, paths = [])
+        return paths unless hash.is_a?(Hash)
+        hash.each do |key, value|
+          path = prefix ? "#{prefix}.#{key}" : key.to_s
+          value.is_a?(Hash) ? nested_key_paths(value, path, paths) : paths << path
+        end
+        paths
       end
     end
   end

data/lib/rails_ai_context/introspectors/schema_introspector.rb

@@ -645,7 +645,7 @@ module RailsAiContext
           adapter: "static_parse",
           tables: tables,
           total_tables: tables.size,
-          note: "Reconstructed from #{migration_files.size} migration files (no DB connection, no schema.rb)"
+          note: "Reconstructed from #{CountPhrase.call(migration_files.size, "migration file")} (no DB connection, no schema.rb)"
         }
       end
 

data/lib/rails_ai_context/introspectors/source_introspector.rb

@@ -66,6 +66,7 @@ module RailsAiContext
       def self.register_listener(dispatcher, listener)
         events = []
         events << :on_call_node_enter  if listener.respond_to?(:on_call_node_enter)
+        events << :on_call_node_leave  if listener.respond_to?(:on_call_node_leave)
         events << :on_def_node_enter   if listener.respond_to?(:on_def_node_enter)
         events << :on_singleton_class_node_enter if listener.respond_to?(:on_singleton_class_node_enter)
         events << :on_singleton_class_node_leave if listener.respond_to?(:on_singleton_class_node_leave)

data/lib/rails_ai_context/live_reload.rb

@@ -5,6 +5,8 @@ module RailsAiContext
   # sending notifications to connected AI clients so they re-query fresh data.
   # Runs a background thread alongside the MCP server (stdio or HTTP).
   class LiveReload
+    include CountPhrase
+
     WATCH_DIRS = (Watcher::WATCH_PATTERNS | Fingerprinter::WATCHED_DIRS).freeze
 
     attr_reader :app, :mcp_server
@@ -83,12 +85,12 @@ module RailsAiContext
         when %r{app/views}           then "view"
         when %r{app/jobs}            then "job"
         when %r{app/mailers}         then "mailer"
-        when %r{app/javascript}      then "javascript"
+        when %r{app/javascript}      then "JavaScript file"
         when %r{config/routes}       then "route"
         when %r{config/}             then "config"
         when %r{db/migrate}          then "migration"
         when %r{db/}                 then "database"
-        when %r{lib/tasks}           then "rake_task"
+        when %r{lib/tasks}           then "rake task"
         else                              "file"
         end
 
@@ -98,9 +100,9 @@ module RailsAiContext
       categories
     end
 
-    # Build a readable summary like "Files changed: 2 model(s), 1 controller(s)."
+    # Build a readable summary like "Files changed: 2 models, 1 controller."
     def format_change_message(categories)
-      parts = categories.map { |cat, count| "#{count} #{cat}(s)" }
+      parts = categories.map { |cat, count| count_phrase(count, cat) }
       "Files changed: #{parts.join(", ")}."
     end
   end

data/lib/rails_ai_context/serializers/claude_rules_serializer.rb

@@ -43,7 +43,7 @@ module RailsAiContext
         # Compact counts - gems and architecture are already in the root file (CLAUDE.md/AGENTS.md)
         schema = context[:schema]
         if SectionGuard.usable?(schema)
-          lines << "- Database: #{schema[:adapter]} - #{schema[:total_tables]} tables"
+          lines << "- Database: #{schema[:adapter]} - #{count_phrase(schema[:total_tables], "table")}"
         end
 
         models = context[:models]
@@ -133,7 +133,7 @@ module RailsAiContext
             .map { |i| i[:unique] ? "#{Array(i[:columns]).join('+')}(unique)" : Array(i[:columns]).join("+") }
           idx_str = idxs.any? ? " | Idx: #{idxs.join(', ')}" : ""
 
-          lines << "- **#{name}** (#{col_count} cols)#{col_str}#{fk_str}#{idx_str}"
+          lines << "- **#{name}** (#{count_phrase(col_count, 'col')})#{col_str}#{fk_str}#{idx_str}"
 
           # Include enum values if model has them
           model_name = name.classify
@@ -146,7 +146,7 @@ module RailsAiContext
         end
 
         if tables.size > 30
-          lines << "- ...#{tables.size - 30} more tables (use `rails_get_schema` MCP tool)"
+          lines << "- ...#{count_phrase(tables.size - 30, "more table")} (use `rails_get_schema` MCP tool)"
         end
 
         lines.join("\n")
@@ -191,7 +191,7 @@ module RailsAiContext
           table = data[:table_name]
           line = "- #{name}"
           line += " (table: #{table})" if table
-          line += " - #{assocs} assocs, #{vals} validations"
+          line += " - #{count_phrase(assocs, "assoc")}, #{count_phrase(vals, "validation")}"
           lines << line
 
           # Include app-specific concerns (filter out Rails/gem internals)

data/lib/rails_ai_context/serializers/compact_serializer_helper.rb

@@ -6,6 +6,8 @@ module RailsAiContext
     # Include in any serializer that has a `context` reader and includes
     # StackOverviewHelper, ToolGuideHelper, and TestCommandDetection.
     module CompactSerializerHelper
+      include CountPhrase
+
       private
 
       def render_header
@@ -24,7 +26,7 @@ module RailsAiContext
         schema = context[:schema]
         if SectionGuard.usable?(schema)
           tables = schema[:total_tables]
-          lines << "- Database: #{schema[:adapter]} - #{tables} #{tables == 1 ? 'table' : 'tables'}"
+          lines << "- Database: #{schema[:adapter]} - #{count_phrase(tables, "table")}"
         end
 
         models = context[:models]
@@ -41,8 +43,8 @@ module RailsAiContext
           # routes across app controllers, with the grand total (framework
           # routes included) alongside for scale.
           app_routes = app_ctrls.sum { |k| Array(by_controller[k]).size }
-          lines << "- Routes: #{app_routes} app #{app_routes == 1 ? 'route' : 'routes'} across " \
-                   "#{app_ctrls.size} #{app_ctrls.size == 1 ? 'controller' : 'controllers'} " \
+          lines << "- Routes: #{count_phrase(app_routes, "app route")} across " \
+                   "#{count_phrase(app_ctrls.size, "controller")} " \
                    "(#{routes[:total_routes]} total incl. framework)"
         end
 
@@ -52,9 +54,9 @@ module RailsAiContext
           mailer_count = jobs[:mailers]&.size || 0
           channel_count = jobs[:channels]&.size || 0
           parts = []
-          parts << "#{job_count} jobs" if job_count > 0
-          parts << "#{mailer_count} mailers" if mailer_count > 0
-          parts << "#{channel_count} channels" if channel_count > 0
+          parts << count_phrase(job_count, "job") if job_count > 0
+          parts << count_phrase(mailer_count, "mailer") if mailer_count > 0
+          parts << count_phrase(channel_count, "channel") if channel_count > 0
           lines << "- Async: #{parts.join(', ')}" if parts.any?
         end
 

data/lib/rails_ai_context/serializers/copilot_instructions_serializer.rb

@@ -45,7 +45,7 @@ module RailsAiContext
 
         schema = context[:schema]
         if SectionGuard.usable?(schema)
-          lines << "- Database: #{schema[:adapter]} - #{schema[:total_tables]} tables"
+          lines << "- Database: #{schema[:adapter]} - #{count_phrase(schema[:total_tables], "table")}"
         end
 
         models = context[:models]
@@ -108,7 +108,7 @@ module RailsAiContext
         models.keys.sort.first(30).each do |name|
           data = models[name]
           assocs = (data[:associations] || []).size
-          lines << "- #{name} (#{assocs} associations)"
+          lines << "- #{name} (#{count_phrase(assocs, "association")})"
           extras = model_extras_line(data)
           lines << extras if extras
         end
@@ -146,7 +146,7 @@ module RailsAiContext
           "---",
           "applyTo: \"**/*\"",
           "name: \"Rails MCP Tools\"",
-          "description: \"#{tool_count} introspection tools - schema, models, routes, controllers, search, testing, validation\"",
+          "description: \"#{count_phrase(tool_count, "introspection tool")} - schema, models, routes, controllers, search, testing, validation\"",
           "excludeAgent: \"code-review\"",
           "---",
           ""

data/lib/rails_ai_context/serializers/copilot_serializer.rb

@@ -29,7 +29,7 @@ module RailsAiContext
         schema = context[:schema]
         if SectionGuard.usable?(schema)
           tables = schema[:total_tables]
-          lines << "- Database: #{schema[:adapter]} - #{tables} #{tables == 1 ? 'table' : 'tables'}"
+          lines << "- Database: #{schema[:adapter]} - #{count_phrase(tables, "table")}"
         end
 
         models = context[:models]
@@ -43,8 +43,8 @@ module RailsAiContext
           by_controller = routes[:by_controller] || {}
           app_ctrls = by_controller.keys.reject { |k| internal.any? { |p| k.downcase.start_with?(p) } }
           app_routes = app_ctrls.sum { |k| Array(by_controller[k]).size }
-          lines << "- Routes: #{app_routes} app #{app_routes == 1 ? 'route' : 'routes'} across " \
-                   "#{app_ctrls.size} #{app_ctrls.size == 1 ? 'controller' : 'controllers'} " \
+          lines << "- Routes: #{count_phrase(app_routes, "app route")} across " \
+                   "#{count_phrase(app_ctrls.size, "controller")} " \
                    "(#{routes[:total_routes]} total incl. framework)"
         end
 

data/lib/rails_ai_context/serializers/cursor_rules_serializer.rb

@@ -74,7 +74,7 @@ module RailsAiContext
 
         schema = context[:schema]
         if SectionGuard.usable?(schema)
-          lines << "- Database: #{schema[:adapter]} - #{schema[:total_tables]} tables"
+          lines << "- Database: #{schema[:adapter]} - #{count_phrase(schema[:total_tables], "table")}"
         end
 
         models = context[:models]
@@ -143,7 +143,7 @@ module RailsAiContext
         models.keys.sort.first(30).each do |name|
           data = models[name]
           assocs = (data[:associations] || []).size
-          lines << "- #{name} (#{assocs} associations, table: #{data[:table_name] || '?'})"
+          lines << "- #{name} (#{count_phrase(assocs, "association")}, table: #{data[:table_name] || '?'})"
           extras = model_extras_line(data)
           lines << extras if extras
         end
@@ -185,7 +185,7 @@ module RailsAiContext
       def render_mcp_tools_rule
         lines = [
           "---",
-          "description: \"Rails MCP tools reference - #{tool_count} tools for schema, models, routes, controllers, search, testing, and more\"",
+          "description: \"Rails MCP tools reference - #{count_phrase(tool_count, "tool")} for schema, models, routes, controllers, search, testing, and more\"",
           "alwaysApply: false",
           "---",
           ""