rails_map 1.1.0

data/lib/rails_map/parsers/route_parser.rb

@@ -0,0 +1,356 @@
+# frozen_string_literal: true
+
+module RailsMap
+  module Parsers
+    class RouteParser
+      RouteInfo = Struct.new(
+        :verb, :path, :controller, :action, :name, :constraints, :defaults, :base_path,
+        :path_params, :query_params, :request_body_params,
+        keyword_init: true
+      )
+
+      def parse
+        routes = collect_routes
+        Rails.logger.info "RouteParser: Collected #{routes.size} routes" if defined?(Rails.logger)
+        grouped = group_by_controller(routes)
+        Rails.logger.info "RouteParser: Grouped into #{grouped.size} controllers" if defined?(Rails.logger)
+        grouped
+      end
+
+      private
+
+      def collect_routes
+        return [] unless defined?(Rails)
+
+        Rails.application.routes.routes.map do |route|
+          next if internal_route?(route)
+
+          requirements = route.requirements
+          controller = requirements[:controller]
+          action = requirements[:action]
+
+          next unless controller && action
+
+          path = extract_path(route)
+          path_params = extract_path_params(path)
+          
+          RouteInfo.new(
+            verb: extract_verb(route),
+            path: path,
+            controller: controller,
+            action: action,
+            name: route.name,
+            constraints: extract_constraints(route),
+            defaults: extract_defaults(route),
+            base_path: extract_base_path(path),
+            path_params: path_params,
+            query_params: extract_query_params(controller, action),
+            request_body_params: extract_body_params(controller, action)
+          )
+        end.compact
+      end
+
+      def extract_verb(route)
+        verb = route.verb
+        return verb if verb.is_a?(String)
+        return verb.source.gsub(/[$^]/, "") if verb.respond_to?(:source)
+
+        "ANY"
+      end
+
+      def extract_path(route)
+        path = route.path.spec.to_s
+        # Remove format segment if present
+        path.gsub("(.:format)", "")
+      end
+
+      def extract_path_params(path)
+        # Extract parameters from path like :id, :user_id, etc.
+        params = []
+        path.scan(/:(\w+)/).flatten.each do |param|
+          params << {
+            name: param,
+            type: infer_param_type(param),
+            required: true,
+            location: 'path'
+          }
+        end
+        params
+      end
+
+      def extract_query_params(controller, action)
+        # Try to extract query parameters from controller action
+        params = []
+        begin
+          controller_file = find_controller_file(controller)
+          return params unless controller_file && File.exist?(controller_file)
+
+          content = File.read(controller_file)
+          
+          # Look for params.permit or params.require patterns in the action
+          action_content = extract_action_content(content, action)
+          return params unless action_content
+
+          # Extract permitted parameters
+          permitted_params = extract_permitted_params(action_content)
+          
+          # For GET requests, these are typically query params
+          permitted_params.each do |param|
+            params << {
+              name: param[:name],
+              type: param[:type] || 'string',
+              required: param[:required] || false,
+              location: 'query'
+            }
+          end
+        rescue => e
+          Rails.logger.debug "Could not extract query params for #{controller}##{action}: #{e.message}" if defined?(Rails.logger)
+        end
+        params
+      end
+
+      def extract_body_params(controller, action)
+        # Try to extract request body parameters from controller action
+        params = []
+        begin
+          controller_file = find_controller_file(controller)
+          return params unless controller_file && File.exist?(controller_file)
+
+          content = File.read(controller_file)
+          
+          # Look for params.permit or params.require patterns in the action
+          action_content = extract_action_content(content, action)
+          return params unless action_content
+
+          # Extract permitted parameters
+          permitted_params = extract_permitted_params(action_content)
+          
+          # For POST/PUT/PATCH requests, these are typically body params
+          permitted_params.each do |param|
+            params << {
+              name: param[:name],
+              type: param[:type] || 'string',
+              required: param[:required] || false,
+              location: 'body'
+            }
+          end
+        rescue => e
+          Rails.logger.debug "Could not extract body params for #{controller}##{action}: #{e.message}" if defined?(Rails.logger)
+        end
+        params
+      end
+
+      def find_controller_file(controller)
+        return nil unless defined?(Rails.root)
+        Rails.root.join('app', 'controllers', "#{controller}_controller.rb")
+      end
+
+      def extract_action_content(content, action)
+        # Extract the content of a specific action method
+        action_regex = /def\s+#{Regexp.escape(action)}\b.*?(?=\n\s*def\s|\n\s*private\s|\n\s*protected\s|\nend\s*\z)/m
+        match = content.match(action_regex)
+        match ? match[0] : nil
+      end
+
+      def extract_permitted_params(action_content)
+        params = []
+        
+        # Pattern 1: params.require(:model).permit(:attr1, :attr2, ...)
+        require_permit_pattern = /params\.require\(:(\w+)\)\.permit\((.*?)\)/m
+        if match = action_content.match(require_permit_pattern)
+          model_name = match[1]
+          permitted_attrs = match[2]
+          
+          # Extract individual attributes
+          permitted_attrs.scan(/:(\w+)/).flatten.each do |attr|
+            params << {
+              name: "#{model_name}[#{attr}]",
+              type: infer_param_type(attr),
+              required: true
+            }
+          end
+        end
+        
+        # Pattern 2: params.permit(:attr1, :attr2, ...)
+        permit_pattern = /params\.permit\((.*?)\)/m
+        action_content.scan(permit_pattern).flatten.each do |permitted_attrs|
+          permitted_attrs.scan(/:(\w+)/).flatten.each do |attr|
+            # Avoid duplicates
+            unless params.any? { |p| p[:name].include?(attr) }
+              params << {
+                name: attr,
+                type: infer_param_type(attr),
+                required: false
+              }
+            end
+          end
+        end
+        
+        # Pattern 3: params[:key] or params['key']
+        params_access_pattern = /params\[['"]?:?(\w+)['"]?\]/
+        action_content.scan(params_access_pattern).flatten.uniq.each do |attr|
+          # Avoid duplicates and common Rails params
+          next if %w[controller action format id].include?(attr)
+          unless params.any? { |p| p[:name] == attr || p[:name].include?(attr) }
+            params << {
+              name: attr,
+              type: infer_param_type(attr),
+              required: false
+            }
+          end
+        end
+        
+        params.uniq { |p| p[:name] }
+      end
+
+      def infer_param_type(param_name)
+        # Infer parameter type from name
+        case param_name.to_s
+        when /_(id|ids)$/
+          'integer'
+        when /^is_/, /^has_/, /_flag$/, /_enabled$/
+          'boolean'
+        when /_at$/, /_date$/
+          'datetime'
+        when /_count$/, /_number$/, /^count_/, /^num_/
+          'integer'
+        when /_price$/, /_amount$/, /_total$/
+          'decimal'
+        when /_email$/
+          'email'
+        when /_url$/
+          'url'
+        else
+          'string'
+        end
+      end
+
+      def extract_constraints(route)
+        constraints = {}
+        route.requirements.each do |key, value|
+          next if %i[controller action].include?(key)
+
+          constraints[key] = value.is_a?(Regexp) ? value.source : value.to_s
+        end
+        constraints
+      end
+
+      def extract_defaults(route)
+        defaults = {}
+        route.defaults.each do |key, value|
+          next if %i[controller action].include?(key)
+
+          defaults[key] = value.to_s
+        end
+        defaults
+      end
+
+      def group_by_controller(routes)
+        grouped = routes.group_by(&:controller)
+
+        grouped.transform_values do |controller_routes|
+          sorted_routes = controller_routes.sort_by { |r| [r.path, verb_order(r.verb)] }
+          {
+            routes: sorted_routes,
+            actions: controller_routes.map(&:action).uniq.sort,
+            base_path: find_common_base_path(controller_routes)
+          }
+        end.sort_by { |controller, _| controller.downcase }.to_h
+      end
+
+      def extract_base_path(path)
+        # Extract first meaningful segment: /users/:id -> /users
+        segments = path.split('/').reject(&:empty?)
+        return '/' if segments.empty?
+        
+        # Take first segment that doesn't start with : or *
+        base = segments.take_while { |s| !s.start_with?(':', '*') }
+        base.empty? ? "/#{segments.first}" : "/#{base.join('/')}"
+      end
+
+      def find_common_base_path(routes)
+        paths = routes.map(&:base_path).uniq
+        return paths.first if paths.size == 1
+        
+        # Find common prefix
+        paths.min_by(&:length) || '/'
+      end
+
+      def verb_order(verb)
+        # Order: GET, POST, PUT, PATCH, DELETE, others
+        order = { 'GET' => 0, 'POST' => 1, 'PUT' => 2, 'PATCH' => 3, 'DELETE' => 4 }
+        order[verb.to_s.upcase] || 5
+      end
+
+      def internal_route?(route)
+        # Rails 7+ uses internal? method
+        return true if route.respond_to?(:internal?) && route.internal?
+        
+        # Rails 6.x uses internal attribute
+        return true if route.respond_to?(:internal) && route.internal
+        
+        # Check if it's a Rails internal route by path
+        path = route.path.spec.to_s rescue ''
+        return true if path.start_with?('/rails/')
+        
+        # Check controller namespace - exclude gem/engine controllers
+        controller = route.requirements[:controller].to_s
+        return true if excluded_controller?(controller)
+        
+        false
+      end
+
+      def excluded_controller?(controller)
+        return true if controller.nil? || controller.empty?
+        
+        controller_downcase = controller.to_s.downcase
+        
+        # Exclude common gem/internal controller namespaces (check first segment)
+        excluded_prefixes = %w[
+          rails_map
+          action_mailbox
+          action_cable
+          active_storage
+          action_text
+          turbo
+          devise
+          sidekiq
+          letter_opener
+          better_errors
+          web_console
+          solid_queue
+          solid_cache
+          mission_control
+          rails
+          graphiql
+          pghero
+          blazer
+          flipper
+          rswag
+          swagger
+          avo
+          administrate
+          rails_admin
+          good_job
+          que
+          delayed
+        ]
+        
+        # Check if controller starts with any excluded prefix
+        first_segment = controller_downcase.split('/').first
+        return true if excluded_prefixes.include?(first_segment)
+        
+        # Check prefix match (e.g., "action_mailbox/ingresses/...")
+        return true if excluded_prefixes.any? { |prefix| controller_downcase.start_with?("#{prefix}/") }
+        
+        # Check if controller file exists in app/controllers of host app
+        if defined?(Rails.root)
+          controller_file = Rails.root.join('app', 'controllers', "#{controller}_controller.rb")
+          return true unless File.exist?(controller_file)
+        end
+        
+        false
+      end
+    end
+  end
+end

data/lib/rails_map/railtie.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module RailsMap
+  class Railtie < Rails::Railtie
+    railtie_name :rails_map
+
+    rake_tasks do
+      namespace :doc do
+        desc "Generate HTML documentation for routes and models"
+        task generate: :environment do
+          puts "Generating documentation..."
+          RailsMap.generate
+        end
+
+        desc "Generate documentation and open in browser"
+        task open: :generate do
+          index_path = File.join(RailsMap.configuration.output_dir, "index.html")
+          
+          if File.exist?(index_path)
+            system("open", index_path) || system("xdg-open", index_path) || system("start", index_path)
+          else
+            puts "Documentation not found at #{index_path}"
+          end
+        end
+
+        desc "Clean generated documentation"
+        task clean: :environment do
+          output_dir = RailsMap.configuration.output_dir
+          if Dir.exist?(output_dir)
+            FileUtils.rm_rf(output_dir)
+            puts "Removed documentation at #{output_dir}"
+          else
+            puts "No documentation found at #{output_dir}"
+          end
+        end
+      end
+    end
+
+    # Allow configuration via Rails initializer
+    initializer "rails_map.configure" do
+      # Configuration can be done in config/initializers/rails_map.rb
+    end
+  end
+end

data/lib/rails_map/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsMap
+  VERSION = "1.1.0"
+end

data/lib/rails_map.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "rails_map/version"
+require_relative "rails_map/configuration"
+require_relative "rails_map/auth"
+require_relative "rails_map/parsers/route_parser"
+require_relative "rails_map/parsers/model_parser"
+require_relative "rails_map/generators/html_generator"
+
+module RailsMap
+  class Error < StandardError; end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def generate
+      Generator.new(configuration).generate
+    end
+  end
+
+  class Generator
+    attr_reader :config
+
+    def initialize(config)
+      @config = config
+    end
+
+    def generate
+      ensure_output_directory
+
+      routes_data = Parsers::RouteParser.new.parse
+      models_data = Parsers::ModelParser.new.parse
+
+      generator = Generators::HtmlGenerator.new(
+        routes: routes_data,
+        models: models_data,
+        output_dir: config.output_dir
+      )
+
+      generator.generate_all
+
+      puts "Documentation generated successfully in #{config.output_dir}"
+    end
+
+    private
+
+    def ensure_output_directory
+      FileUtils.mkdir_p(config.output_dir)
+      FileUtils.mkdir_p(File.join(config.output_dir, "controllers"))
+      FileUtils.mkdir_p(File.join(config.output_dir, "models"))
+    end
+  end
+end
+
+if defined?(Rails::Railtie)
+  require_relative "rails_map/engine"
+  require_relative "rails_map/railtie"
+end

data/templates/controller.html.erb

@@ -0,0 +1,74 @@
+<div class="breadcrumb">
+  <a href="../index.html">Home</a>
+  <span>/</span>
+  <a href="../routes.html">Routes</a>
+  <span>/</span>
+  <span><%= controller_name.camelize %>Controller</span>
+</div>
+
+<div class="card">
+  <div class="card-header">
+    <h2 class="card-title"><%= controller_name.camelize %>Controller</h2>
+    <span class="badge badge-any"><%= routes.size %> routes</span>
+  </div>
+
+  <div style="display: flex; gap: 2rem; margin-bottom: 1.5rem; flex-wrap: wrap;">
+    <div>
+      <strong>Base Path:</strong><br>
+      <code style="background: var(--primary-color); color: white; padding: 0.25rem 0.5rem; border-radius: 0.25rem; font-size: 1rem;"><%= base_path || '/' %></code>
+    </div>
+    <div>
+      <strong>Actions:</strong><br>
+      <% actions.each_with_index do |action, index| %>
+        <code><%= action %></code><%= index < actions.size - 1 ? ' ' : '' %>
+      <% end %>
+    </div>
+  </div>
+
+  <% if routes.any? %>
+    <div class="table-container">
+      <table>
+        <thead>
+          <tr>
+            <th>Method</th>
+            <th>Path</th>
+            <th>Action</th>
+            <th>Route Name</th>
+            <th>Constraints</th>
+          </tr>
+        </thead>
+        <tbody>
+          <% routes.each do |route| %>
+            <tr>
+              <td>
+                <span class="badge badge-<%= route.verb.downcase.split('|').first %>">
+                  <%= route.verb %>
+                </span>
+              </td>
+              <td><code><%= route.path %></code></td>
+              <td><code><%= route.action %></code></td>
+              <td>
+                <% if route.name %>
+                  <code><%= route.name %></code>
+                <% else %>
+                  <span style="color: var(--text-muted);">—</span>
+                <% end %>
+              </td>
+              <td>
+                <% if route.constraints.any? %>
+                  <% route.constraints.each do |key, value| %>
+                    <code><%= key %>: <%= value %></code><br>
+                  <% end %>
+                <% else %>
+                  <span style="color: var(--text-muted);">—</span>
+                <% end %>
+              </td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+  <% else %>
+    <div class="empty-state">No routes found for this controller</div>
+  <% end %>
+</div>

data/templates/index.html.erb

@@ -0,0 +1,64 @@
+<div class="stats">
+  <div class="stat">
+    <div class="stat-value"><%= controllers_count %></div>
+    <div class="stat-label">Controllers</div>
+  </div>
+  <div class="stat">
+    <div class="stat-value"><%= routes_count %></div>
+    <div class="stat-label">Routes</div>
+  </div>
+  <div class="stat">
+    <div class="stat-value"><%= models_count %></div>
+    <div class="stat-label">Models</div>
+  </div>
+</div>
+
+<div class="nav">
+  <a href="routes.html">All Routes</a>
+</div>
+
+<h2 class="section-header">Controllers</h2>
+<% if controllers.any? %>
+  <div class="grid">
+    <% controllers.each do |controller, data| %>
+      <div class="card">
+        <div class="card-header">
+          <h3 class="card-title"><%= controller.camelize %>Controller</h3>
+          <span class="badge badge-any"><%= data[:routes].size %> routes</span>
+        </div>
+        <p style="margin-bottom: 0.5rem;">
+          <code style="background: var(--primary-color); color: white; padding: 0.25rem 0.5rem; border-radius: 0.25rem;"><%= data[:base_path] || '/' %></code>
+        </p>
+        <p style="color: var(--text-muted); margin-bottom: 1rem; font-size: 0.875rem;">
+          Actions: <%= data[:actions].join(', ') %>
+        </p>
+        <a href="controllers/<%= controller.gsub('/', '_') %>.html" class="link">View Details →</a>
+      </div>
+    <% end %>
+  </div>
+<% else %>
+  <div class="empty-state">No controllers found</div>
+<% end %>
+
+<h2 class="section-header">Models</h2>
+<% if models.any? %>
+  <div class="grid">
+    <% models.each do |name, model| %>
+      <div class="card">
+        <div class="card-header">
+          <h3 class="card-title"><%= name %></h3>
+          <span class="badge badge-any"><%= model.columns.size %> columns</span>
+        </div>
+        <p style="color: var(--text-muted); margin-bottom: 0.5rem;">
+          Table: <code><%= model.table_name || 'N/A' %></code>
+        </p>
+        <p style="color: var(--text-muted); margin-bottom: 1rem;">
+          <%= model.associations.size %> associations
+        </p>
+        <a href="models/<%= name.underscore.gsub('/', '_') %>.html" class="link">View Details →</a>
+      </div>
+    <% end %>
+  </div>
+<% else %>
+  <div class="empty-state">No models found</div>
+<% end %>