rails-ai-context 5.32.0 → 5.32.2

data/lib/rails_ai_context/install/ai_tool.rb

@@ -13,8 +13,11 @@ module RailsAiContext
     #
     # context_paths lists the root file first, then the split-rule targets. The writers,
     # doctor and cleanup all read this table, so a moved path changes every surface at once.
-    AiTool = Struct.new(:number, :key, :name, :files, :context_paths, :rules_dir, :mcp_config, :legacy_paths,
-                        :owned_dir, keyword_init: true)
+    #
+    # rule_files names what the gem writes inside rules_dir. The directory is shared with
+    # rules the user writes by hand, so cleanup removes these names and nothing else.
+    AiTool = Struct.new(:number, :key, :name, :files, :context_paths, :rules_dir, :rule_files, :mcp_config,
+                        :legacy_paths, :owned_dir, keyword_init: true)
 
     class AiTool
       ALL = [
@@ -23,6 +26,7 @@ module RailsAiContext
           files: "CLAUDE.md + .claude/rules/",
           context_paths: %w[CLAUDE.md .claude/rules],
           rules_dir: ".claude/rules",
+          rule_files: %w[rails-context.md rails-schema.md rails-models.md rails-mcp-tools.md rails-components.md],
           mcp_config: { path: ".mcp.json", root_key: "mcpServers", format: :mcp_json },
           legacy_paths: [ ".claude/rules/rails-ui-patterns.md", ".claude/rules/rails-accessibility.md" ],
           owned_dir: ".claude"
@@ -32,6 +36,7 @@ module RailsAiContext
           files: ".cursor/rules/ + .cursorrules (legacy fallback)",
           context_paths: %w[.cursor/rules .cursorrules],
           rules_dir: ".cursor/rules",
+          rule_files: %w[rails-project.mdc rails-models.mdc rails-controllers.mdc rails-mcp-tools.mdc],
           mcp_config: { path: ".cursor/mcp.json", root_key: "mcpServers", format: :mcp_json },
           legacy_paths: [ ".cursor/rules/rails-ui-patterns.mdc" ],
           owned_dir: ".cursor"
@@ -41,6 +46,10 @@ module RailsAiContext
           files: ".github/copilot-instructions.md + .github/instructions/",
           context_paths: %w[.github/copilot-instructions.md .github/instructions],
           rules_dir: ".github/instructions",
+          rule_files: %w[
+            rails-context.instructions.md rails-models.instructions.md
+            rails-controllers.instructions.md rails-mcp-tools.instructions.md
+          ],
           mcp_config: { path: ".vscode/mcp.json", root_key: "servers", format: :vscode_json },
           legacy_paths: [ ".github/instructions/rails-ui-patterns.instructions.md" ]
         ),

data/lib/rails_ai_context/install/cleanup.rb

@@ -11,49 +11,95 @@ module RailsAiContext
     module Cleanup
       module_function
 
+      # The block SectionMarkerWriter manages inside a root context file.
+      BEGIN_MARKER = "<!-- BEGIN rails-ai-context -->"
+      MANAGED_BLOCK = /#{BEGIN_MARKER}.*?<!-- END rails-ai-context -->(?:\r?\n)?/m
+
+      # The line a split rules file generated whole carries.
+      GENERATED_NOTE = "Auto-generated by rails-ai-context. Do not edit manually."
+      GENERATED_LINE = /^> #{Regexp.escape(GENERATED_NOTE)}\r?$/
+
+      # Removes what this gem generated and nothing the user wrote: the named
+      # rule files inside a rules directory, the managed block inside a root
+      # file, and a file generated whole.
+      #
       # @param tools [Array<Symbol>] the AI tools being dropped
       # @param keeping [Array<Symbol>] the tools still selected, whose files
       #   must survive even when a dropped tool names the same path
       # @param root [String, Pathname] project root
-      # @return [Hash] { removed: [paths], failed: [paths] }, directories
-      #   marked with a trailing slash so callers can print them the way they
-      #   always have. Both rm calls swallow their errors, so a path is only
+      # @return [Hash] { removed: [paths], trimmed: [paths], kept: [paths], failed: [paths] }.
+      #   A directory carries a trailing slash. `trimmed` files lost their
+      #   managed block and kept the user's lines; `kept` files hold nothing
+      #   this gem generated. rm swallows its errors, so a path is only
       #   reported removed once it is gone.
       def remove(tools:, keeping:, root:)
         kept = Array(keeping).flat_map { |key| AiTool.find(key)&.context_paths || [] }.to_set
-        removed = []
-        failed = []
+        outcome = { removed: [], trimmed: [], kept: [], failed: [] }
 
         Array(tools).each do |key|
-          paths = AiTool.find(key)&.context_paths || []
-          paths.each do |relative|
+          tool = AiTool.find(key) or next
+          tool.context_paths.each do |relative|
             next if kept.include?(relative)
 
-            label, gone = remove_path(relative, root)
-            next unless label
-
-            (gone ? removed : failed) << label
+            if File.directory?(File.join(root.to_s, relative))
+              remove_rule_files(tool, relative, root, outcome)
+            else
+              remove_generated(relative, root, outcome)
+            end
           end
         end
 
-        { removed: removed, failed: failed }
+        outcome
       end
 
-      # @return [Array(String, Boolean), nil] the path's label and whether it
-      #   is gone, or nil when there was nothing there to remove. A directory
-      #   whose children went but which itself survives counts as not gone.
-      def remove_path(relative, root)
+      # A symlink is somebody's own arrangement, and writing through one edits
+      # a file this run was not asked about.
+      def remove_rule_files(tool, dir, root, outcome)
+        full = File.join(root.to_s, dir)
+        return if File.symlink?(full)
+
+        names = Array(tool.rule_files) + tool.legacy_paths.select { |path| File.dirname(path) == dir }.map { |path| File.basename(path) }
+        names.each { |name| delete(File.join(dir, name), root, outcome) }
+        return unless Dir.empty?(full)
+
+        Dir.rmdir(full)
+        outcome[:removed] << "#{dir}/"
+      rescue SystemCallError
+        outcome[:failed] << "#{dir}/"
+      end
+      private_class_method :remove_rule_files
+
+      # Bytes in, bytes out: the markers are ASCII, and the user's lines may not be valid UTF-8.
+      def remove_generated(relative, root, outcome)
         full = File.join(root.to_s, relative)
+        return unless File.file?(full) || File.symlink?(full)
+        return outcome[:kept] << relative if File.symlink?(full)
 
-        if File.directory?(full)
-          FileUtils.rm_rf(full)
-          [ "#{relative}/", !File.exist?(full) ]
-        elsif File.exist?(full)
-          FileUtils.rm_f(full)
-          [ relative, !File.exist?(full) ]
+        content = File.binread(full)
+        rest = content.gsub(MANAGED_BLOCK, "")
+        # The writer puts one blank line under a block it prepends to a file that was already there.
+        rest = rest.sub(/\A\r?\n/, "") if content.start_with?(BEGIN_MARKER)
+        if rest == content
+          content.match?(GENERATED_LINE) ? delete(relative, root, outcome) : outcome[:kept] << relative
+        elsif rest.strip.empty?
+          delete(relative, root, outcome)
+        else
+          File.binwrite(full, rest)
+          outcome[:trimmed] << relative
         end
+      rescue SystemCallError
+        outcome[:failed] << relative
+      end
+      private_class_method :remove_generated
+
+      def delete(relative, root, outcome)
+        full = File.join(root.to_s, relative)
+        return unless File.file?(full) && !File.symlink?(full)
+
+        FileUtils.rm_f(full)
+        (File.exist?(full) ? outcome[:failed] : outcome[:removed]) << relative
       end
-      private_class_method :remove_path
+      private_class_method :delete
     end
   end
 end

data/lib/rails_ai_context/install/program.rb

@@ -113,13 +113,16 @@ module RailsAiContext
 
           outcome = Cleanup.remove(tools: [ key ], keeping: selected.map(&:to_sym), root: root)
           outcome[:removed].each { |path| surface.say "  Removed #{path}", :ok }
+          outcome[:trimmed].each { |path| surface.say "  Removed the generated section from #{path}", :ok }
+          outcome[:kept].each { |path| surface.say "  Kept #{path} (nothing in it was generated by rails-ai-context)", :muted }
           outcome[:failed].each { |path| surface.say "Could not remove #{path} - check its permissions", :warn }
 
           # Merge-safe MCP config cleanup - removes only the rails-ai-context entry
           cleaned = RailsAiContext::McpConfigGenerator.remove(tools: [ key ], output_dir: root.to_s)
           cleaned.each { |f| surface.say "  Removed MCP entry from #{relative_to(f, root)}", :ok }
 
-          surface.say "  #{tool.name} files removed", :ok if tool && outcome[:failed].empty?
+          gone = outcome[:removed].any? || outcome[:trimmed].any? || cleaned.any?
+          surface.say "  #{tool.name} files removed", :ok if tool && gone && outcome[:failed].empty?
         end
       end
 

data/lib/rails_ai_context/install/selection_record.rb

@@ -74,7 +74,7 @@ module RailsAiContext
         recorded.nil? ? nil : !!recorded
       end
 
-      # @return [Symbol] :updated, :inserted, :unchanged or :absent
+      # @return [Symbol] :updated, :inserted, :unchanged, :conflict or :absent
       def write_context_files(value, root:)
         write_config_line(root, "  config.context_files = #{value ? 'true' : 'false'}",
                           CONTEXT_FILES_LINE, /^[ \t]*config\.context_files\s*=.*$/)
@@ -83,7 +83,7 @@ module RailsAiContext
       # Only an uncommented line is rewritten - the generated initializer ships
       # a commented-out default that must stay a comment.
       #
-      # @return [Symbol] :updated, :inserted, :unchanged or :absent
+      # @return [Symbol] :updated, :inserted, :unchanged, :conflict or :absent
       def write_tool_mode(mode, root:)
         write_config_line(root, "  config.tool_mode = :#{mode}",
                           MODE_LINE, /^[ \t]*config\.tool_mode\s*=.*$/)
@@ -134,6 +134,20 @@ module RailsAiContext
         write((read(root: root) || []) | addition, root: root)
       end
 
+      # What to say when a single-value key came back :conflict, nil otherwise.
+      def conflict_message(key, status)
+        return unless status == :conflict
+
+        [ :warn, "#{INITIALIZER} sets config.#{key} in a form this installer does not " \
+                 "rewrite, and it takes precedence - edit it by hand to change it" ]
+      end
+
+      # Whether the app has settled its tool mode, in the record or in an
+      # initializer line of any shape, so no entry asks again.
+      def tool_mode_set?(root:)
+        !tool_mode(root: root).nil? || initializer_content(root).to_s.match?(/^[ \t]*config\.tool_mode\s*=/)
+      end
+
       def initializer_line(tools)
         "  config.ai_tools = %i[#{normalize(tools).join(' ')}]"
       end
@@ -196,6 +210,10 @@ module RailsAiContext
 
           File.write(path, updated)
           :updated
+        elsif content.match?(assignment)
+          # Assigned in a shape this module will not rewrite. A second line
+          # beside it would lose at boot and win on read.
+          :conflict
         elsif content.match?(SELECTION_LINE)
           File.write(path, content.sub(/^([ \t]*config\.ai_tools\s*=[^\n]*)$/) { "#{Regexp.last_match(1)}\n#{line}" })
           :inserted

data/lib/rails_ai_context/introspectors/listeners/schema_dsl_listener.rb

@@ -52,12 +52,18 @@ module RailsAiContext
         # The dumper writes a comment, not a create_table, for a table it could not describe.
         NOT_DUMPED = /\A#\s*Could not dump table "([^"]+)" because of following (\S+)/
 
+        # raw_names: each name as the dump writes it, for a reader that names them after the walk.
+        def initialize(raw_names: false)
+          super()
+          @raw_names = raw_names
+        end
+
         def on_program_node_enter(_node)
           comments = Array(@comments)
           comments.each_with_index do |comment, i|
             match = NOT_DUMPED.match(comment.location.slice) or next
             message = comments[i + 1]&.location&.slice.to_s[/\A#\s+(\S.*)/, 1]
-            @results << { type: :not_dumped, table: SchemaConventions.local_name(match[1]),
+            @results << { type: :not_dumped, table: local_name(match[1]),
                           reason: [ match[2], message ].compact.join(": "), location: comment.location.start_line }
           end
         end
@@ -66,6 +72,13 @@ module RailsAiContext
           note_block(node)
           if node.receiver.nil?
             extract_top_level_call(node)
+          elsif node.name == :[] && node.receiver.is_a?(Prism::ConstantPathNode) && node.receiver.slice == "ActiveRecord::Schema"
+            # ActiveRecord::Schema[8.1].define: the Rails version that wrote the dump.
+            stamp = node.arguments&.arguments&.first
+            @results << { type: :stamp, version: stamp.slice, location: node.location.start_line } if stamp.is_a?(Prism::FloatNode)
+          elsif node.name == :define && node.receiver.is_a?(Prism::ConstantPathNode) && node.receiver.slice == "ActiveRecord::Schema"
+            # Rails before 7.0 writes no stamp.
+            @results << { type: :stamp, version: nil, location: node.location.start_line }
           elsif column_call?(node)
             extract_column(node)
           elsif index_call?(node)
@@ -87,6 +100,11 @@ module RailsAiContext
 
         private
 
+        # Without a search path to read, public's are the bare names.
+        def local_name(name)
+          @raw_names ? name : name.delete_prefix("public.")
+        end
+
         def read_elsewhere?(name)
           OTHER_TABLE_METHODS.include?(name) || MigrationReplayListener::TABLE_OPS.key?(name)
         end
@@ -104,6 +122,9 @@ module RailsAiContext
             extract_foreign_key(node)
           when :create_enum
             extract_enum(node)
+          when :create_schema
+            name = literal_string(node.arguments&.arguments&.first)
+            @results << { type: :create_schema, name: name, location: node.location.start_line } if name
           when :add_index
             extract_top_level_add_index(node)
           when :add_check_constraint
@@ -123,7 +144,7 @@ module RailsAiContext
           name = literal_string(node.arguments&.arguments&.first) or return
           options = extract_keyword_nodes(node)
           @results << {
-            type: :view, name: SchemaConventions.local_name(name), materialized: options[:materialized].is_a?(Prism::TrueNode),
+            type: :view, name: local_name(name), materialized: options[:materialized].is_a?(Prism::TrueNode),
             sql: literal_string(options[:sql_definition])&.strip, location: node.location.start_line
           }.compact
         end
@@ -143,7 +164,7 @@ module RailsAiContext
 
           @results << {
             type:     :create_table,
-            table:    SchemaConventions.local_name(table_arg.unescaped),
+            table:    local_name(table_arg.unescaped),
             # id: false / id: :uuid / primary_key: ... decide whether the
             # implicit primary-key column exists and what to call it.
             options:  extract_keyword_options(node),
@@ -161,8 +182,8 @@ module RailsAiContext
 
           @results << {
             type:        :foreign_key,
-            from:        SchemaConventions.local_name(from_arg.unescaped),
-            to:          SchemaConventions.local_name(to_arg.unescaped),
+            from:        local_name(from_arg.unescaped),
+            to:          local_name(to_arg.unescaped),
             # Absent means the Rails convention holds; naming it here would
             # make a declared column indistinguishable from a guessed one.
             column:      SchemaConventions.primary_key_value(options[:column]),
@@ -191,7 +212,7 @@ module RailsAiContext
 
           @results << {
             type:     :enum,
-            name:     SchemaConventions.local_name(name_arg.unescaped),
+            name:     local_name(name_arg.unescaped),
             values:   values,
             location: node.location.start_line
           }
@@ -207,7 +228,7 @@ module RailsAiContext
 
           @results << {
             type:     :add_index,
-            table:    SchemaConventions.local_name(table_arg.unescaped),
+            table:    local_name(table_arg.unescaped),
             columns:  columns,
             options:  options,
             location: node.location.start_line
@@ -222,7 +243,7 @@ module RailsAiContext
 
           @results << {
             type:       :add_check_constraint,
-            table:      SchemaConventions.local_name(table_arg.unescaped),
+            table:      local_name(table_arg.unescaped),
             expression: expr_arg.unescaped,
             name:       literal_string(extract_keyword_nodes(node)[:name]),
             location:   node.location.start_line
@@ -288,7 +309,7 @@ module RailsAiContext
 
           options = braced.map { |hash| hash_node_to_hash(hash) }.reduce(extract_keyword_options(node), :merge)
           virtual = node.name == :virtual
-          options[:enum_type] = SchemaConventions.local_name(options[:enum_type]) if options[:enum_type].is_a?(String)
+          options[:enum_type] = local_name(options[:enum_type]) if options[:enum_type].is_a?(String)
           # A generated column takes its own type from type: (each adapter's virtual, 7.0 to 8.1).
           column_type = options[:type].to_s if virtual && (options[:type].is_a?(Symbol) || options[:type].is_a?(String))
           names.each do |col_name|

data/lib/rails_ai_context/introspectors/model_introspector.rb

@@ -172,7 +172,7 @@ module RailsAiContext
       # Rails runs no STI on a table without the type column; a table the dump does not hold is not known to lack it.
       def lacks_column?(table, column)
         reader = SchemaReader.for(app.root)
-        reader.tables.key?(table) && column != RailsAiContext::Confidence::INFERRED && !reader.column?(table, column)
+        reader.table?(table) && column != RailsAiContext::Confidence::INFERRED && !reader.column?(table, column)
       end
 
       # Rails' default column, the literal a class sets, or nil where `inheritance_column = nil` turns STI off.

data/lib/rails_ai_context/introspectors/pg_naming.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Introspectors
+    # How Rails' PostgreSQL connection and schema.rb dumper name extensions, enum types and
+    # relations, by Rails version, so the static tier names them as the booted app does.
+    # Each rule cites the activerecord source it mirrors.
+    module PgNaming
+      DEFAULT_SEARCH_PATH = %w[public].freeze
+      # 6.1 schema_dumper.rb:89 writes Schema.define, 7.0 :90 Schema[x.y]; every rule here starts at 7.0 or later.
+      UNSTAMPED_DUMP = "6.1"
+
+      module_function
+
+      # The running Rails when booted, else the lockfile's; nil when neither says.
+      def rails_version(root)
+        return Rails.version if defined?(Rails) && Rails.respond_to?(:version) && !RailsAiContext.static_tier?
+
+        lock = GemLock.for(root)
+        lock.version("rails") || lock.version("railties")
+      end
+
+      # An unknown version takes the newest rules.
+      def at_least?(version, release)
+        version.nil? || Gem::Version.new(version) >= Gem::Version.new(release)
+      end
+
+      # 8.0 postgresql_adapter.rb:506-520 drops the schema only when it is current_schema;
+      # 7.0 :453, 7.1 :497 and 7.2 :496 select extname alone.
+      def extension_name(name, schema, path, version)
+        return name if schema.nil? || !at_least?(version, "8.0") || schema == path.first
+
+        "#{schema}.#{name}"
+      end
+
+      # 7.1 postgresql_adapter.rb:502-522 (to 8.1 :533-553): the types in current_schemas(false),
+      # bare in current_schema. 7.0 :458-469 merges same-name types' labels; the static tier keeps the first set.
+      def enum_list(enums, path, version)
+        legacy = !at_least?(version, "7.1")
+        listed = enums.filter_map do |name, values|
+          schema, dot, bare = name.rpartition(".")
+          shown = if dot.empty? || legacy then bare
+          elsif path.include?(schema) then schema == path.first ? bare : name
+          end
+          { name: shown, values: values } if shown
+        end
+        listed.uniq { |enum| enum[:name] }.sort_by { |enum| enum[:name] }
+      end
+
+      # 8.1 schema_dumper.rb:154-162 (relation_name) qualifies every name in a dump of more than one
+      # schema. Before, the dumper writes connection.tables, enum_types and column.sql_type
+      # (7.2 postgresql/schema_dumper.rb:19-29, :94), the names the booted app reads.
+      def dump_qualifies_names?(version)
+        at_least?(version, "8.1")
+      end
+
+      # Whether a bare name in the dump says its schema. Before 8.1 the dumper names each of
+      # connection.tables bare, whichever search path schema holds it, so only a one-schema path places it.
+      def dump_places_names?(version, path)
+        dump_qualifies_names?(version) || path.size < 2
+      end
+
+      # 7.1 postgresql/schema_dumper.rb:31-40 writes create_schema for every schema; 7.0 has no schemas().
+      def dump_lists_schemas?(version)
+        at_least?(version, "7.1")
+      end
+
+      # current_schemas(false) skips a schema that does not exist; pg_dump never creates public.
+      def existing_path(path, created)
+        path.select { |schema| schema == "public" || created.include?(schema) }
+      end
+
+      # The names a dump's relations and enum types go by, given its qualified names.
+      def names(path, relations: [], types: [])
+        Names.new(path, shadowed(relations, path), shadowed(types, path))
+      end
+
+      # The qualified names an earlier search path schema hides by holding the same bare name.
+      def shadowed(names, path)
+        return Set.new if path.size < 2
+
+        ranked = names.uniq.filter_map do |name|
+          schema, dot, bare = name.rpartition(".")
+          rank = path.index(schema) unless dot.empty?
+          [ rank, bare, name ] if rank
+        end
+        first = ranked.sort_by(&:first).reverse.to_h { |_, bare, name| [ bare, name ] }
+        ranked.filter_map { |_, bare, name| name unless first[bare] == name }.to_set
+      end
+
+      # PostgreSQL resolves a bare name through the search path (data_sources and format_type alike).
+      Names = Struct.new(:path, :shadowed_relations, :shadowed_types) do
+        def relation(name)
+          visible(name, shadowed_relations)
+        end
+
+        def type(name)
+          visible(name, shadowed_types)
+        end
+
+        private
+
+        def visible(name, shadowed)
+          schema, dot, bare = name.rpartition(".")
+          dot.empty? || !path.include?(schema) || shadowed.include?(name) ? name : bare
+        end
+      end
+
+      # The enum types a table's columns use: a bare column type is the first search path schema's
+      # holding it, and a bare list name is the current schema's.
+      def enums_used(enum_types, column_types, path)
+        path = Array(path).presence || DEFAULT_SEARCH_PATH
+        listed = Array(enum_types).to_h { |enum| [ enum[:name].to_s.include?(".") ? enum[:name].to_s : "#{path.first}.#{enum[:name]}", enum ] }
+        used = column_types.map do |type|
+          type.include?(".") ? type : path.map { |schema| "#{schema}.#{type}" }.find { |key| listed.key?(key) }
+        end
+        listed.select { |key, _| used.include?(key) }.values
+      end
+
+      # 8.1 postgresql/schema_dumper.rb:13-23, :50-68 dumps only ActiveRecord.dump_schemas, the search
+      # path by default (active_record.rb:436); 7.1 to 8.0 dump every schema's create_schema and ignore it.
+      # A dump naming no schema off the path is the default; one that does has dump_schemas set.
+      def missing_from_schema_rb(name, path, created, version, dump)
+        schema, dot, = name.to_s.rpartition(".")
+        return if dot.empty? || !at_least?(version, "8.1") || path.include?(schema) || created.include?(schema)
+        return unless (created - path).empty?
+
+        "If schema '#{schema}' exists, #{dump} leaves it out: Rails 8.1 dumps only the search path schemas there by default. " \
+          "`config.active_record.dump_schemas = :all` includes it."
+      end
+    end
+  end
+end

data/lib/rails_ai_context/introspectors/schema_conventions.rb

@@ -189,12 +189,6 @@ module RailsAiContext
         yml.adapter(db_name, entry).first || (yml.adapter("primary", yml.primary(root)).first unless entry)
       end
 
-      # A dump of more than one schema qualifies every name (relation_name, 8.1);
-      # the app sees a public table by its bare name under the default search_path.
-      def local_name(name)
-        name.delete_prefix("public.")
-      end
-
       # A primary key as connection.primary_key gives it: the column's name, or
       # the names in order for a composite key; nil for none.
       def primary_key_value(key)