rails-ai-context 5.32.2 → 5.34.0

data/lib/rails_ai_context/serializers/opencode_rules_serializer.rb

@@ -9,8 +9,12 @@ module RailsAiContext
     # Generated files:
     #   app/models/AGENTS.md      - model listing, loaded when editing models
     #   app/controllers/AGENTS.md - controller listing, loaded when editing controllers
+    #
+    # Teams write these by hand too, so one the gem did not generate keeps
+    # its text and gets the gem's listing as a marked block.
     class OpencodeRulesSerializer < Base
       include StackOverviewHelper
+      include ToolGuideHelper
 
       RULE_FILES = {
         "app/models/AGENTS.md" => { renderer: :render_models_reference, reason: "no models" },
@@ -29,15 +33,23 @@ module RailsAiContext
           if Dir.exist?(File.dirname(filepath))
             RuleFile.new(filepath, send(rule[:renderer]), rule[:reason])
           else
-            RuleFile.new(filepath, nil, "#{File.dirname(relative)} not present")
+            RuleFile.new(filepath, nil, missing_directory_reason(File.dirname(relative), output_dir))
           end
         end
 
-        write_rule_files(entries)
+        write_rule_files(entries, shared: true)
       end
 
       private
 
+      # OpenCode reads these beside the code, so they go only into a
+      # directory that exists. Under an output_dir that is not the app, the
+      # app's own directory is there; it is the output_dir that lacks one.
+      def missing_directory_reason(dir, output_dir)
+        elsewhere = File.expand_path(output_dir) != File.expand_path(project_root)
+        elsewhere && Dir.exist?(File.join(project_root, dir)) ? "no #{dir} under output_dir" : "#{dir} not present"
+      end
+
       def render_models_reference
         models = Payload.models(context)
         return nil unless models.any?
@@ -46,7 +58,7 @@ module RailsAiContext
           "# ActiveRecord Models (#{models.size})",
           "",
           "> #{Install::Cleanup::GENERATED_NOTE}",
-          "> Check here first for scopes, constants, associations. Read model files for business logic/methods.",
+          "> #{MODELS_READING}",
           ""
         ]
         if (notice = SectionFacts.static_notice(context))
@@ -62,8 +74,9 @@ module RailsAiContext
 
           assocs = SectionFacts.associations_list(data).join(", ")
           vals = (data[:validations] || []).size
+          note = SectionFacts.table_note(Payload.section(context, :schema), data)
           line = "- **#{name}**"
-          line += " (table: #{data[:table_name]})" if data[:table_name]
+          line += note ? " (table #{note})" : (" (table: #{data[:table_name]})" if data[:table_name]).to_s
           line += " - #{assocs}" unless assocs.empty?
           line += " [#{vals}v]" if vals > 0
           lines << line
@@ -72,14 +85,23 @@ module RailsAiContext
         end
 
         lines << "- _...#{models.size - 30} more_" if models.size > 30
-        lines << ""
-        lines << "Use `rails_get_model_details(model:\"Name\")` for associations, validations, scopes, enums."
-        lines << "Use `rails_get_view(controller:\"name\")` for view templates."
-        lines << "Use `rails_get_test_info(model:\"Name\")` for existing model tests."
+        lines.concat(tool_pointers(
+          [ "rails_get_model_details", 'model:"Name"', "model=Name", "for associations, validations, scopes, enums." ],
+          [ "rails_get_view", 'controller:"name"', "controller=name", "for view templates." ],
+          [ "rails_get_test_info", 'model:"Name"', "model=Name", "for existing model tests." ]
+        ))
 
         lines.join("\n")
       end
 
+      # "Use <tool> for ..." lines under a blank one, for the tools the server serves.
+      def tool_pointers(*pointers)
+        served = pointers.select { |name, *| served?(name) }
+        return [] if served.empty?
+
+        [ "", *served.map { |name, mcp_params, cli_params, purpose| "Use #{tool_ref(name, mcp_params, cli_params)} #{purpose}" } ]
+      end
+
       def render_controllers_reference
         app_controllers = Payload.app_controllers(context)
         return nil if app_controllers.empty?
@@ -88,7 +110,7 @@ module RailsAiContext
           "# Controllers (#{app_controllers.size})",
           "",
           "> #{Install::Cleanup::GENERATED_NOTE}",
-          "> Read controller files directly when editing. Use MCP tools for reference only.",
+          "> Read controller files directly when editing. Use #{tools_noun} for reference only.",
           ""
         ]
         if (notice = SectionFacts.static_notice(context))
@@ -109,12 +131,13 @@ module RailsAiContext
         jobs = job_names
         lines << "**Jobs:** #{jobs.join(', ')}" if jobs.any?
 
-        lines << ""
-        lines << "Use `rails_get_controllers(controller:\"Name\", action:\"index\")` for one action's source code."
-        lines << "Use `rails_get_edit_context(file:\"path\", near:\"keyword\")` for surgical edit context."
-        lines << "Use `rails_get_view(controller:\"name\")` for view templates."
-        lines << "Use `rails_get_test_info(controller:\"Name\")` for existing controller tests."
-        lines << "Use `rails_validate(files:[...])` to check syntax after editing - do NOT re-read files to verify."
+        lines.concat(tool_pointers(
+          [ "rails_get_controllers", 'controller:"Name", action:"index"', "controller=Name action=index", "for one action's source code." ],
+          [ "rails_get_edit_context", 'file:"path", near:"keyword"', "file=path near=keyword", "for surgical edit context." ],
+          [ "rails_get_view", 'controller:"name"', "controller=name", "for view templates." ],
+          [ "rails_get_test_info", 'controller:"Name"', "controller=Name", "for existing controller tests." ],
+          [ "rails_validate", "files:[...]", "files=...", "to check syntax after editing - do NOT re-read files to verify." ]
+        ))
 
         lines.join("\n")
       end

data/lib/rails_ai_context/serializers/section_facts.rb

@@ -33,11 +33,45 @@ module RailsAiContext
         models.any? ? "- Models: #{models.size}" : nil
       end
 
+      # The primary first, then each other database by its database.yml name:
+      # a count that leaves one out undercounts the app.
       def database_line(ctx)
         schema = Payload.section(ctx, :schema)
         return nil unless schema
 
-        "- Database: #{SchemaAdapter.label(ctx)} - #{CountPhrase.call(schema[:total_tables].to_i, "table")}"
+        parts = [ "#{SchemaAdapter.label(ctx)} - #{CountPhrase.call(schema[:total_tables].to_i, "table")}" ]
+        Payload.secondary_databases(schema).each do |name, db|
+          tables = CountPhrase.call(db[:total_tables].to_i, "table")
+          adapter = SchemaAdapter.secondary_label(ctx, name, db)
+          parts << (framework_database_text(name, db) || "#{name}: #{adapter ? "#{adapter} - #{tables}" : tables}")
+        end
+        "- Database: #{parts.join('; ')}"
+      end
+
+      # A database a Rails framework keeps to itself, as every file names it:
+      # "queue: Solid Queue (13 tables)". Its tables are the framework's, so
+      # no file lists them. nil for a database of the app's own.
+      def framework_database_text(name, db)
+        framework = Payload.database_framework(db) or return nil
+
+        "#{name}: #{framework} (#{CountPhrase.call(db[:total_tables].to_i, "table")})"
+      end
+
+      # The same databases, the ones with migrations of their own.
+      def migrations_line(ctx)
+        migrations = Payload.section(ctx, :migrations)
+        return nil unless migrations
+
+        pending = Payload.pending_migrations(ctx) if migrations.key?(:pending)
+        parts = [ migration_counts(migrations[:total], pending) ]
+        secondary = migrations[:secondary_databases].is_a?(Hash) ? migrations[:secondary_databases] : {}
+        secondary.each { |name, db| parts << "#{name}: #{migration_counts(db[:total], db[:pending])}" }
+        "- Migrations: #{parts.join('; ')}"
+      end
+
+      # No pending count when nothing says what has been applied: zero would read as up to date.
+      def migration_counts(total, pending)
+        pending ? "#{total.to_i} total, #{pending.size} pending" : "#{total.to_i} total"
       end
 
       def auth_line(ctx)
@@ -78,6 +112,15 @@ module RailsAiContext
         buckets
       end
 
+      # The table a model reads when it is not plainly named: missing from a live listing, or set by
+      # a parent the static tier did not read. Nil otherwise.
+      def table_note(schema, model_data)
+        return "`#{model_data[:table_name]}` not found" if Payload.missing_table?(schema, model_data)
+        return nil if model_data[:table_name] || !model_data[:table_set_by]
+
+        "set by `#{model_data[:table_set_by]}`, which the static tier did not read"
+      end
+
       def associations_list(model_data)
         (model_data[:associations] || [])
           .select { |a| a.is_a?(Hash) }

data/lib/rails_ai_context/serializers/section_marker_writer.rb

@@ -6,7 +6,8 @@ module RailsAiContext
     # markers so user-added content OUTSIDE the markers survives regeneration.
     #
     # Used by ContextFileSerializer (for CLAUDE.md, AGENTS.md, .github/copilot-
-    # instructions.md) and CursorRulesSerializer (for .cursorrules). Same
+    # instructions.md), CursorRulesSerializer (for .cursorrules) and, for a
+    # per-directory AGENTS.md the user wrote, OpencodeRulesSerializer. Same
     # marker contract everywhere - a user can hand-write content above or below
     # the gem-managed block and it'll persist across `rails ai:context` runs.
     module SectionMarkerWriter
@@ -20,29 +21,78 @@ module RailsAiContext
       # nothing new still put a diff in a repo that commits its context files.
       GENERATED_LINE = /^> Generated: .*\n/
 
+      BLOCK = /#{Regexp.escape(BEGIN_MARKER)}.*?#{Regexp.escape(END_MARKER)}(?:\r?\n)?/m
+
+      # Why a run left a file alone: with a marker lost, or a second block
+      # pasted in, nothing says where the gem's block ends.
+      UNPAIRED = "unpaired rails-ai-context marker, left as it is"
+
+      # Inside a file somebody else wrote, the note claims the block rather
+      # than the whole file, as Install::Cleanup::GENERATED_NOTE does.
+      BLOCK_NOTE = "This block is generated by rails-ai-context and rewritten on every run. " \
+        "Edit outside its BEGIN/END markers."
+
       module_function
 
+      # A file under a name users write by hand too (OpenCode's
+      # app/models/AGENTS.md), rendered whole with the generated note. One
+      # that is missing, or that this gem generated whole - the note and no
+      # marker - is written whole. Any other is somebody's own, and gets the
+      # content as a block the way a root file does, so their text stays and
+      # Install::Cleanup takes out only the block.
+      def write_whole_or_block(filepath, content)
+        existing = File.exist?(filepath) ? RailsAiContext::SafeFile.read_text(filepath) : nil
+        return write_whole(filepath, content) if existing.nil? || generated_whole?(existing)
+
+        write_with_markers(filepath, content.sub(Install::Cleanup::GENERATED_LINE, "> #{BLOCK_NOTE}"))
+      end
+
+      def generated_whole?(text)
+        markers(text) == :none && text.match?(Install::Cleanup::GENERATED_LINE)
+      end
+
+      # A file the gem owns whole, rewritten only when it says something else.
+      # It ends with a newline, as a text file does: without one, editors and
+      # end-of-file fixers rewrote every rule file and git flagged each.
+      def write_whole(filepath, content)
+        content = "#{content}\n" unless content.end_with?("\n")
+        if File.exist?(filepath)
+          existing = RailsAiContext::SafeFile.read_text(filepath)
+          content = in_line_endings_of(existing, content)
+          return :skipped if existing == content
+        end
+
+        atomic_write(filepath, content)
+        :written
+      end
+
       # Write `content` to `filepath` wrapped in markers. If the file already
       # exists with markers, replace only the marker block (preserving user
       # content outside). If the file exists WITHOUT markers, prepend the
       # marker block so AI tools read our context first while keeping the
-      # user's prior content intact below.
+      # user's prior content intact below. A file whose markers do not pair
+      # up is not written: replacing a guess at the block could take the
+      # user's text, and prepending a new one duplicated the old for good.
       #
       # Returns :written if the file changed (created or block updated),
-      # :skipped if the file already had the exact same marker block.
+      # :skipped if the file already had the exact same marker block,
+      # :unpaired if its markers do not pair up.
       def write_with_markers(filepath, content)
         marked_content = "#{BEGIN_MARKER}\n#{content}\n#{END_MARKER}\n"
 
         if File.exist?(filepath)
-          existing = File.read(filepath)
-
-          new_content = if existing.include?(BEGIN_MARKER) && existing.include?(END_MARKER)
-            existing.sub(
-              /#{Regexp.escape(BEGIN_MARKER)}.*?#{Regexp.escape(END_MARKER)}\n?/m,
-              marked_content
-            )
-          else
-            "#{marked_content}\n#{existing}"
+          # Read as UTF-8 whatever the locale: a C locale tagged it US-ASCII,
+          # and the first non-ASCII character stopped the rewrite. A file that
+          # is no UTF-8 keeps its bytes, and the block joins them as bytes.
+          existing = RailsAiContext::SafeFile.read_text(filepath)
+          marked_content = in_line_endings_of(existing, marked_content)
+          marked_content = marked_content.b if existing.encoding == Encoding::BINARY
+
+          new_content = case markers(existing)
+          # A block, so a backslash in the content is not read as a backreference.
+          when :pair then existing.sub(BLOCK) { marked_content }
+          when :none then "#{marked_content}#{crlf?(existing) ? "\r\n" : "\n"}#{existing}"
+          else return :unpaired
           end
 
           return :skipped if same_but_for_timestamp?(existing, new_content)
@@ -55,6 +105,38 @@ module RailsAiContext
         end
       end
 
+      # :pair for one BEGIN marker before one END marker, :none for neither,
+      # :unpaired for anything else: a lone marker, two blocks, END first.
+      def markers(text)
+        begins = text.scan(BEGIN_MARKER).size
+        ends = text.scan(END_MARKER).size
+        return :none if begins.zero? && ends.zero?
+        return :pair if begins == 1 && ends == 1 && text.index(BEGIN_MARKER) < text.index(END_MARKER)
+
+        :unpaired
+      end
+
+      # Files a write's outcome under the bucket a context run reports it in.
+      def report(outcome, filepath, result)
+        case outcome
+        when :written then result[:written] << filepath
+        when :skipped then result[:skipped] << filepath
+        when :unpaired then result[:not_applicable][filepath] = UNPAIRED
+        end
+        result
+      end
+
+      # Text in the line endings of the file it goes into. A file checked out
+      # on Windows ends its lines in CRLF, and a block in LF beside them
+      # mixed the two and left a blank line under END on every run.
+      def in_line_endings_of(existing, text)
+        crlf?(existing) ? text.gsub(/\r?\n/, "\r\n") : text
+      end
+
+      def crlf?(text)
+        text.include?("\r\n")
+      end
+
       def same_but_for_timestamp?(existing, candidate)
         existing == candidate ||
           existing.gsub(GENERATED_LINE, "") == candidate.gsub(GENERATED_LINE, "")

data/lib/rails_ai_context/serializers/stack_overview_helper.rb

@@ -13,6 +13,12 @@ module RailsAiContext
       RuleFile = Struct.new(:path, :content, :reason)
 
       IN_REPO_ENGINES_SHOWN = 5
+      DATABASES_SHOWN = 3
+
+      # The models listings' line on reading, in the tools guide's terms: the
+      # tools are the reference, and a file is read to edit it. "Read model
+      # files for business logic" sat beside "NEVER read ... model files".
+      MODELS_READING = "Check here first for scopes, constants, associations. Read a model file only when you edit it."
 
       # Returns an array of summary lines for full-preset introspectors.
       # Each line is only added if the introspector returned meaningful data.
@@ -78,7 +84,10 @@ module RailsAiContext
         db_list = raw_databases.is_a?(Hash) ? raw_databases.keys : Array(raw_databases)
         if db_list.size > 1
           db_names = db_list.map { |d| d.is_a?(Hash) ? d[:name] : d }
-          lines << "- Databases: #{db_list.size} (#{db_names.first(3).join(', ')})"
+          # The names it leaves out are counted, as the mounted apps' are.
+          shown = db_names.first(DATABASES_SHOWN)
+          shown << "...#{db_names.size - DATABASES_SHOWN} more" if db_names.size > DATABASES_SHOWN
+          lines << "- Databases: #{db_list.size} (#{shown.join(', ')})"
         end
 
         components = Payload.section(ctx, :components)
@@ -116,7 +125,7 @@ module RailsAiContext
         lines << SectionFacts.models_line(context)
 
         if (routes = Payload.section(context, :routes))
-          lines << "- Routes: #{routes[:total_routes]}#{RouteCoverage.suffix(routes)}"
+          lines << "- Routes: #{RouteCoverage.summary(routes)}"
         end
 
         if gems
@@ -214,28 +223,31 @@ module RailsAiContext
       # A nil render means the app has nothing to put in that file. It is
       # reported rather than dropped, so a deliberate omission never looks
       # like a failed generation.
+      #
+      # A rules directory's names are the gem's own. `shared:` is for names
+      # users write by hand too (OpenCode's app/models/AGENTS.md): a file
+      # there the gem did not generate whole keeps its text and gets the
+      # gem's block, as a root file does.
       # @param entries [Array<RuleFile>]
       # @return [Hash] { written: [paths], skipped: [paths], not_applicable: { path => reason } }
-      def write_rule_files(entries)
-        written = []
-        skipped = []
-        not_applicable = {}
+      def write_rule_files(entries, shared: false)
+        result = { written: [], skipped: [], not_applicable: {} }
 
         entries.each do |entry|
           if entry.content.nil?
-            not_applicable[entry.path] = entry.reason || "nothing to document"
+            result[:not_applicable][entry.path] = entry.reason || "nothing to document"
             next
           end
 
-          if File.exist?(entry.path) && File.read(entry.path) == entry.content
-            skipped << entry.path
+          outcome = if shared
+            SectionMarkerWriter.write_whole_or_block(entry.path, entry.content)
           else
-            SafeFile.atomic_write(entry.path, entry.content)
-            written << entry.path
+            SectionMarkerWriter.write_whole(entry.path, entry.content)
           end
+          SectionMarkerWriter.report(outcome, entry.path, result)
         end
 
-        { written: written, skipped: skipped, not_applicable: not_applicable }
+        result
       end
 
       def project_root