woods 1.0.0

data/lib/woods/extractors/controller_extractor.rb

@@ -0,0 +1,404 @@
+# frozen_string_literal: true
+
+require 'digest'
+require_relative 'ast_source_extraction'
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module Woods
+  module Extractors
+    # ControllerExtractor handles ActionController extraction with:
+    # - Route mapping (which HTTP endpoints hit which actions)
+    # - Before/after action filter chain resolution
+    # - Per-action chunking for precise retrieval
+    # - Concern inlining
+    #
+    # Controllers are chunked more aggressively than models because
+    # queries are often action-specific ("how does the create action work").
+    #
+    # @example
+    #   extractor = ControllerExtractor.new
+    #   units = extractor.extract_all
+    #   registrations = units.find { |u| u.identifier == "Users::RegistrationsController" }
+    #
+    class ControllerExtractor
+      include AstSourceExtraction
+      include SharedUtilityMethods
+      include SharedDependencyScanner
+
+      def initialize
+        @routes_map = build_routes_map
+      end
+
+      # Extract all controllers in the application
+      #
+      # @return [Array<ExtractedUnit>] List of controller units
+      def extract_all
+        controllers = ApplicationController.descendants
+
+        controllers = (controllers + ActionController::API.descendants).uniq if defined?(ActionController::API)
+
+        controllers.map do |controller|
+          extract_controller(controller)
+        end.compact
+      end
+
+      # Extract a single controller
+      #
+      # @param controller [Class] The controller class
+      # @return [ExtractedUnit] The extracted unit
+      def extract_controller(controller)
+        unit = ExtractedUnit.new(
+          type: :controller,
+          identifier: controller.name,
+          file_path: source_file_for(controller)
+        )
+
+        source_path = unit.file_path
+        source = source_path && File.exist?(source_path) ? File.read(source_path) : ''
+
+        unit.namespace = extract_namespace(controller)
+        unit.source_code = build_composite_source(controller, source)
+        unit.metadata = extract_metadata(controller, source)
+        unit.dependencies = extract_dependencies(controller, source)
+
+        # Controllers benefit from per-action chunks
+        unit.chunks = build_action_chunks(controller, unit)
+
+        unit
+      rescue StandardError => e
+        Rails.logger.error("[Woods] Failed to extract controller #{controller.name}: #{e.class}: #{e.message}")
+        Rails.logger.error("[Woods]   #{e.backtrace&.first(5)&.join("\n  ")}")
+        nil
+      end
+
+      private
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Route Mapping
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Build a map of controller -> action -> route info from Rails routes
+      def build_routes_map
+        routes = {}
+
+        Rails.application.routes.routes.each do |route|
+          next unless route.defaults[:controller]
+
+          controller = "#{route.defaults[:controller].camelize}Controller"
+          action = route.defaults[:action]
+
+          routes[controller] ||= {}
+          routes[controller][action] ||= []
+          routes[controller][action] << {
+            verb: extract_verb(route),
+            path: route.path.spec.to_s.gsub('(.:format)', ''),
+            name: route.name,
+            constraints: route.constraints.except(:request_method)
+          }
+        end
+
+        routes
+      end
+
+      def extract_verb(route)
+        verb = route.verb
+        return verb if verb.is_a?(String)
+        return verb.source.gsub(/[\^$]/, '') if verb.respond_to?(:source)
+
+        verb.to_s
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Source Building
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Find the source file for a controller, validating paths are within Rails.root.
+      #
+      # Convention path first, then introspection via {#resolve_source_location}
+      # which filters out vendor/node_modules paths.
+      #
+      # @param controller [Class] The controller class
+      # @return [String] Absolute path to the controller source file
+      def source_file_for(controller)
+        convention_path = Rails.root.join("app/controllers/#{controller.name.underscore}.rb").to_s
+        return convention_path if File.exist?(convention_path)
+
+        resolve_source_location(controller, app_root: Rails.root.to_s, fallback: convention_path)
+      end
+
+      # Build composite source with routes and filters as headers
+      def build_composite_source(controller, source = nil)
+        if source.nil?
+          source_path = source_file_for(controller)
+          return '' unless source_path && File.exist?(source_path)
+
+          source = File.read(source_path)
+        end
+
+        # Prepend route information
+        routes_comment = build_routes_comment(controller)
+
+        # Prepend before_action chain
+        filters_comment = build_filters_comment(controller)
+
+        "#{routes_comment}\n#{filters_comment}\n#{source}"
+      end
+
+      def build_routes_comment(controller)
+        routes = @routes_map[controller.name] || {}
+        return '' if routes.empty?
+
+        lines = routes.flat_map do |action, route_list|
+          route_list.map do |info|
+            verb = info[:verb].to_s.ljust(7)
+            path = info[:path].ljust(45)
+            "  #{verb} #{path} → ##{action}"
+          end
+        end
+
+        <<~ROUTES
+          # ╔═══════════════════════════════════════════════════════════════════════╗
+          # ║ Routes                                                                 ║
+          # ╚═══════════════════════════════════════════════════════════════════════╝
+          #
+          #{lines.map { |l| "# #{l}" }.join("\n")}
+          #
+        ROUTES
+      end
+
+      def build_filters_comment(controller)
+        filters = extract_filter_chain(controller)
+        return '' if filters.empty?
+
+        lines = filters.map do |f|
+          opts = []
+          opts << "only: [#{f[:only].map { |a| ":#{a}" }.join(', ')}]" if f[:only]&.any?
+          opts << "except: [#{f[:except].map { |a| ":#{a}" }.join(', ')}]" if f[:except]&.any?
+          opts << "if: #{f[:if]}" if f[:if]
+
+          opts_str = opts.any? ? " (#{opts.join('; ')})" : ''
+          "  #{f[:kind].to_s.ljust(8)} :#{f[:filter]}#{opts_str}"
+        end
+
+        <<~FILTERS
+          # ╔═══════════════════════════════════════════════════════════════════════╗
+          # ║ Filter Chain                                                           ║
+          # ╚═══════════════════════════════════════════════════════════════════════╝
+          #
+          #{lines.map { |l| "# #{l}" }.join("\n")}
+          #
+        FILTERS
+      end
+
+      def extract_filter_chain(controller)
+        controller._process_action_callbacks.map do |callback|
+          only, except, if_conds, unless_conds = extract_callback_conditions(callback)
+
+          result = { kind: callback.kind, filter: callback.filter }
+          result[:only] = only if only.any?
+          result[:except] = except if except.any?
+          result[:if] = if_conds.join(', ') if if_conds.any?
+          result[:unless] = unless_conds.join(', ') if unless_conds.any?
+          result
+        end
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Metadata Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Extract comprehensive metadata
+      def extract_metadata(controller, source = nil)
+        own_methods = controller.instance_methods(false).to_set(&:to_s)
+        actions = controller.action_methods.select { |m| own_methods.include?(m) }.to_a
+
+        {
+          # Actions and routes
+          actions: actions,
+          routes: @routes_map[controller.name] || {},
+
+          # Filter chain
+          filters: extract_filter_chain(controller),
+
+          # Parent chain for understanding inherited behavior
+          ancestors: controller.ancestors
+                     .take_while { |a| a != ActionController::Base && a != ActionController::API }
+                     .grep(Class)
+                     .map(&:name)
+                     .compact,
+
+          # Concerns included
+          included_concerns: extract_included_concerns(controller),
+
+          # Response formats
+          responds_to: extract_respond_formats(controller, source),
+
+          # Metrics
+          action_count: actions.size,
+          filter_count: controller._process_action_callbacks.count,
+
+          # Strong parameters if definable
+          permitted_params: extract_permitted_params(controller, source)
+        }
+      end
+
+      def extract_included_concerns(controller)
+        controller.included_modules
+                  .select { |m| m.name&.include?('Concern') || m.name&.include?('Concerns') }
+                  .map(&:name)
+      end
+
+      def extract_respond_formats(controller, source = nil)
+        if source.nil?
+          source_path = source_file_for(controller)
+          return [] unless source_path && File.exist?(source_path)
+
+          source = File.read(source_path)
+        end
+
+        formats = []
+
+        formats << :html if source.include?('respond_to do') || !source.include?('respond_to')
+        formats << :json if source.include?(':json') || source.include?('render json:')
+        formats << :xml if source.include?(':xml') || source.include?('render xml:')
+        formats << :turbo_stream if source.include?('turbo_stream')
+
+        formats.uniq
+      end
+
+      def extract_permitted_params(controller, source = nil)
+        if source.nil?
+          source_path = source_file_for(controller)
+          return {} unless source_path && File.exist?(source_path)
+
+          source = File.read(source_path)
+        end
+
+        params = {}
+
+        # Match params.require(:x).permit(...) patterns
+        source.scan(/def\s+(\w+_params).*?params\.require\(:(\w+)\)\.permit\((.*?)\)/m) do |method, model, permitted|
+          params[method] = {
+            model: model,
+            permitted: permitted.scan(/:(\w+)/).flatten
+          }
+        end
+
+        params
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Dependency Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      def extract_dependencies(controller, source = nil)
+        deps = []
+
+        if source.nil?
+          source_path = source_file_for(controller)
+          source = File.read(source_path) if source_path && File.exist?(source_path)
+        end
+
+        if source
+          deps.concat(scan_common_dependencies(source))
+
+          # Phlex component references
+          source.scan(/render\s+(\w+(?:::\w+)*Component)/).flatten.uniq.each do |component|
+            deps << { type: :component, target: component, via: :render }
+          end
+
+          # Other view renders
+          source.scan(%r{render\s+["'](\w+/\w+)["']}).flatten.uniq.each do |template|
+            deps << { type: :view, target: template, via: :render }
+          end
+        end
+
+        deps.uniq { |d| [d[:type], d[:target]] }
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Per-Action Chunking
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Build per-action chunks for precise retrieval
+      def build_action_chunks(controller, unit)
+        controller.action_methods.filter_map do |action|
+          route_info = @routes_map.dig(controller.name, action.to_s)
+          filters = applicable_filters(controller, action)
+
+          # Extract just this action's source
+          action_source = extract_action_source(controller, action)
+          next if action_source.nil? || action_source.strip.empty?
+
+          route_desc = if route_info&.any?
+                         route_info.map { |r| "#{r[:verb]} #{r[:path]}" }.join(', ')
+                       else
+                         'No direct route'
+                       end
+
+          chunk_content = <<~ACTION
+            # Controller: #{controller.name}
+            # Action: #{action}
+            # Route: #{route_desc}
+            # Filters: #{filters.map { |f| "#{f[:kind]}(:#{f[:filter]})" }.join(', ').presence || 'none'}
+
+            #{action_source}
+          ACTION
+
+          {
+            chunk_type: :action,
+            identifier: "#{controller.name}##{action}",
+            content: chunk_content,
+            content_hash: Digest::SHA256.hexdigest(chunk_content),
+            metadata: {
+              parent: unit.identifier,
+              action: action.to_s,
+              route: route_info,
+              filters: filters,
+              http_methods: route_info&.map { |r| r[:verb] }&.uniq || []
+            }
+          }
+        end
+      end
+
+      def applicable_filters(controller, action)
+        action_name = action.to_s
+
+        applicable = controller._process_action_callbacks.select do |cb|
+          callback_applies_to_action?(cb, action_name)
+        end
+        applicable.map { |cb| { kind: cb.kind, filter: cb.filter } }
+      end
+
+      # Determine if a callback applies to a given action name.
+      #
+      # Checks ActionFilter objects in @if (only) and @unless (except).
+      # Non-ActionFilter conditions (procs, symbols) are assumed true.
+      #
+      # @param callback [ActiveSupport::Callbacks::Callback]
+      # @param action_name [String]
+      # @return [Boolean]
+      def callback_applies_to_action?(callback, action_name)
+        if_conditions = callback.instance_variable_get(:@if) || []
+        unless_conditions = callback.instance_variable_get(:@unless) || []
+
+        # Check @if conditions — all must pass for the callback to apply
+        if_conditions.each do |cond|
+          actions = extract_action_filter_actions(cond)
+          next unless actions # skip non-ActionFilter conditions (assume true)
+          return false unless actions.include?(action_name)
+        end
+
+        # Check @unless conditions — if any match, callback doesn't apply
+        unless_conditions.each do |cond|
+          actions = extract_action_filter_actions(cond)
+          next unless actions
+          return false if actions.include?(action_name)
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/woods/extractors/database_view_extractor.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module Woods
+  module Extractors
+    # DatabaseViewExtractor handles SQL view file extraction.
+    #
+    # Scans `db/views/` for Scenic gem convention SQL files
+    # (e.g., `db/views/active_users_v01.sql`). Extracts one unit per
+    # view name using the latest version only, parsing basic SQL metadata
+    # (materialized flag, referenced tables, selected columns) via regex.
+    #
+    # @example
+    #   extractor = DatabaseViewExtractor.new
+    #   units = extractor.extract_all
+    #   view = units.find { |u| u.identifier == "active_users" }
+    #   view.metadata[:is_materialized] # => false
+    #   view.metadata[:tables_referenced] # => ["users", "orders"]
+    #
+    class DatabaseViewExtractor
+      include SharedUtilityMethods
+      include SharedDependencyScanner
+
+      # Rails internal tables that should not generate model dependencies
+      INTERNAL_TABLES = %w[
+        schema_migrations
+        ar_internal_metadata
+        active_storage_blobs
+        active_storage_attachments
+        active_storage_variant_records
+        action_text_rich_texts
+        action_mailbox_inbound_emails
+      ].freeze
+
+      # SQL keywords that are not table names
+      SQL_KEYWORDS = %w[
+        select from where join inner outer left right full cross
+        on and or not in is null true false as with having group by
+        order limit offset union intersect except distinct all case when
+        then else end between like ilike similar to cast values lateral
+        returning exists any some
+      ].freeze
+
+      def initialize
+        @views_dir = Rails.root.join('db/views')
+        @has_directory = @views_dir.directory?
+      end
+
+      # Extract all database view units from db/views/.
+      #
+      # Only the latest version of each view is extracted.
+      #
+      # @return [Array<ExtractedUnit>] List of database view units
+      def extract_all
+        return [] unless @has_directory
+
+        latest_view_files.filter_map do |file|
+          extract_view_file(file)
+        end
+      end
+
+      # Extract a single SQL view file.
+      #
+      # @param file_path [String] Absolute path to the SQL file
+      # @return [ExtractedUnit, nil] The extracted unit or nil on failure
+      def extract_view_file(file_path)
+        source = File.read(file_path)
+        view_name = extract_view_name(file_path)
+        version   = extract_version(file_path)
+
+        return nil unless view_name
+
+        unit = ExtractedUnit.new(
+          type: :database_view,
+          identifier: view_name,
+          file_path: file_path
+        )
+
+        unit.namespace = nil
+        unit.source_code = annotate_source(source, view_name, version)
+        unit.metadata = extract_metadata(source, view_name, version)
+        unit.dependencies = extract_dependencies(source, unit.metadata)
+
+        unit
+      rescue StandardError => e
+        Rails.logger.error("Failed to extract database view #{file_path}: #{e.message}")
+        nil
+      end
+
+      private
+
+      # ──────────────────────────────────────────────────────────────────────
+      # File Discovery
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Return only the latest-version SQL file for each view name.
+      #
+      # Scenic filenames: <view_name>_v<NN>.sql (e.g., active_users_v02.sql)
+      # Groups by view name, picks the file with the highest version number.
+      #
+      # @return [Array<String>] Paths to latest-version files
+      def latest_view_files
+        all_files = Dir[@views_dir.join('*.sql')].select do |f|
+          File.basename(f).match?(/\A\w+_v\d+\.sql\z/)
+        end
+
+        grouped = all_files.group_by { |f| extract_view_name(f) }
+        grouped.values.map do |files|
+          files.max_by { |f| extract_version(f) }
+        end
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Name and Version Parsing
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Extract the view name (without version suffix) from the filename.
+      #
+      # @param file_path [String] Path to the SQL file
+      # @return [String, nil] The view name (e.g., "active_users") or nil
+      def extract_view_name(file_path)
+        basename = File.basename(file_path, '.sql')
+        match = basename.match(/\A(.+?)_v(\d+)\z/)
+        match ? match[1] : nil
+      end
+
+      # Extract the integer version number from the filename.
+      #
+      # @param file_path [String] Path to the SQL file
+      # @return [Integer] The version number (e.g., 1 for "_v01")
+      def extract_version(file_path)
+        basename = File.basename(file_path, '.sql')
+        match = basename.match(/_v(\d+)\z/)
+        match ? match[1].to_i : 0
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Source Annotation
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Prepend a summary annotation to the SQL source.
+      #
+      # @param source [String] SQL source
+      # @param view_name [String] The view name
+      # @param version [Integer] The version number
+      # @return [String] Annotated SQL
+      def annotate_source(source, view_name, version)
+        materialized = materialized_view?(source) ? 'YES' : 'NO'
+
+        annotation = <<~ANNOTATION
+          -- ╔═══════════════════════════════════════════════════════════════════════╗
+          -- ║ Database View: #{view_name.ljust(52)}║
+          -- ║ Version: #{version.to_s.ljust(59)}║
+          -- ║ Materialized: #{materialized.ljust(54)}║
+          -- ╚═══════════════════════════════════════════════════════════════════════╝
+
+        ANNOTATION
+
+        annotation + source
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Metadata Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Build the metadata hash for a database view unit.
+      #
+      # @param source [String] SQL source
+      # @param view_name [String] The view name
+      # @param version [Integer] The version number
+      # @return [Hash] View metadata
+      def extract_metadata(source, view_name, version)
+        {
+          view_name: view_name,
+          version: version,
+          is_materialized: materialized_view?(source),
+          tables_referenced: extract_referenced_tables(source),
+          columns_selected: extract_selected_columns(source),
+          loc: source.lines.count { |l| l.strip.length.positive? && !l.strip.start_with?('--') }
+        }
+      end
+
+      # Detect whether this is a materialized view.
+      #
+      # @param source [String] SQL source
+      # @return [Boolean]
+      def materialized_view?(source)
+        source.match?(/\bMATERIALIZED\b/i)
+      end
+
+      # Extract table names referenced in FROM and JOIN clauses.
+      #
+      # Uses a simple regex approach. Handles basic FROM/JOIN patterns
+      # and filters out SQL keywords and subqueries.
+      #
+      # @param source [String] SQL source
+      # @return [Array<String>] Deduplicated table names (lowercase)
+      def extract_referenced_tables(source)
+        tables = []
+
+        # FROM clause: FROM table_name [alias]
+        source.scan(/\bFROM\s+([a-zA-Z_][a-zA-Z0-9_]*)/i).flatten.each do |t|
+          tables << t.downcase unless sql_keyword?(t)
+        end
+
+        # JOIN clauses: [INNER|LEFT|RIGHT|...] JOIN table_name
+        source.scan(/\bJOIN\s+([a-zA-Z_][a-zA-Z0-9_]*)/i).flatten.each do |t|
+          tables << t.downcase unless sql_keyword?(t)
+        end
+
+        tables.uniq
+      end
+
+      # Extract column names from the SELECT clause.
+      #
+      # Handles simple column names and table.column patterns.
+      # Returns '*' for SELECT * queries.
+      #
+      # @param source [String] SQL source
+      # @return [Array<String>] Column names
+      def extract_selected_columns(source)
+        # Find the SELECT ... FROM block
+        select_match = source.match(/\bSELECT\s+(.+?)\s+FROM\b/im)
+        return [] unless select_match
+
+        select_clause = select_match[1].strip
+        return ['*'] if select_clause == '*'
+
+        # Split on commas, strip whitespace and aliases, handle table.column
+        select_clause.split(',').filter_map do |col|
+          col = col.strip
+          # Remove AS alias: "col AS alias" or "table.col alias" → take first token
+          col = col.split(/\s+AS\s+/i).first.strip
+          # For table.column, take the column part
+          col = col.split('.').last.strip
+          # Skip expressions, subqueries, and empty strings
+          next if col.empty? || col.include?('(') || col.include?(')')
+
+          col.delete('"').delete("'")
+        end.uniq
+      end
+
+      # Check if a token is a SQL keyword.
+      #
+      # @param token [String] The token to check
+      # @return [Boolean]
+      def sql_keyword?(token)
+        SQL_KEYWORDS.include?(token.downcase)
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Dependency Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Build the dependency array by linking referenced tables to models.
+      #
+      # Uses the same table → model classify pattern as MigrationExtractor.
+      #
+      # @param source [String] SQL source
+      # @param metadata [Hash] Extracted metadata
+      # @return [Array<Hash>] Dependency hashes with :type, :target, :via
+      def extract_dependencies(_source, metadata)
+        deps = []
+
+        metadata[:tables_referenced].each do |table|
+          next if INTERNAL_TABLES.include?(table)
+
+          model_name = table.classify
+          deps << { type: :model, target: model_name, via: :table_name }
+        end
+
+        deps.uniq { |d| [d[:type], d[:target]] }
+      end
+    end
+  end
+end