codebase_index 0.1.0

data/lib/codebase_index/extractors/phlex_extractor.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module CodebaseIndex
+  module Extractors
+    # PhlexExtractor handles Phlex component extraction.
+    #
+    # Phlex components are Ruby classes, making them more introspectable
+    # than ERB templates. We can extract:
+    # - Slot definitions (renders_one, renders_many)
+    # - Initialize parameters (the component's API)
+    # - Component dependencies (what other components it renders)
+    # - Helper usage
+    # - Stimulus controller references
+    #
+    # @example
+    #   extractor = PhlexExtractor.new
+    #   units = extractor.extract_all
+    #   card = units.find { |u| u.identifier == "Components::CardComponent" }
+    #
+    class PhlexExtractor
+      include SharedUtilityMethods
+      include SharedDependencyScanner
+
+      # Common Phlex base classes to look for
+      PHLEX_BASES = %w[
+        Phlex::HTML
+        Phlex::Component
+        ApplicationComponent
+      ].freeze
+
+      def initialize
+        @component_base = find_component_base
+      end
+
+      # Extract all Phlex/ViewComponent components
+      #
+      # @return [Array<ExtractedUnit>] List of component units
+      def extract_all
+        return [] unless @component_base
+
+        @component_base.descendants.map do |component|
+          extract_component(component)
+        end.compact
+      end
+
+      # Extract a single component
+      #
+      # @param component [Class] The component class
+      # @return [ExtractedUnit] The extracted unit
+      def extract_component(component)
+        return nil if component.name.nil?
+
+        unit = ExtractedUnit.new(
+          type: :component,
+          identifier: component.name,
+          file_path: source_file_for(component)
+        )
+
+        unit.namespace = extract_namespace(component)
+        unit.source_code = read_source(unit.file_path)
+        unit.metadata = extract_metadata(component, unit.source_code)
+        unit.dependencies = extract_dependencies(component, unit.source_code)
+
+        unit
+      rescue StandardError => e
+        Rails.logger.error("Failed to extract component #{component.name}: #{e.message}")
+        nil
+      end
+
+      private
+
+      # Find the base component class used in the application.
+      # Skips ApplicationComponent if it's actually a ViewComponent subclass
+      # to avoid extracting ViewComponent classes with Phlex-specific metadata.
+      #
+      # @return [Class, nil]
+      def find_component_base
+        PHLEX_BASES.each do |base_name|
+          klass = base_name.safe_constantize
+          next unless klass
+          next if base_name == 'ApplicationComponent' && view_component_subclass?(klass)
+
+          return klass
+        end
+        nil
+      end
+
+      # Check if a class descends from ViewComponent::Base.
+      #
+      # @param klass [Class]
+      # @return [Boolean]
+      def view_component_subclass?(klass)
+        defined?(ViewComponent::Base) && klass < ViewComponent::Base
+      end
+
+      def source_file_for(component)
+        # Try common locations
+        possible_paths = [
+          Rails.root.join("app/views/components/#{component.name.underscore}.rb"),
+          Rails.root.join("app/components/#{component.name.underscore}.rb"),
+          Rails.root.join("app/views/#{component.name.underscore}.rb")
+        ]
+
+        found = possible_paths.find { |p| File.exist?(p) }
+        return found.to_s if found
+
+        # Try to get from method source location
+        if component.instance_methods(false).any?
+          method = component.instance_methods(false).first
+          component.instance_method(method).source_location&.first
+        end
+      rescue StandardError
+        nil
+      end
+
+      def read_source(file_path)
+        return '' unless file_path && File.exist?(file_path)
+
+        File.read(file_path)
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Metadata Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      def extract_metadata(component, source)
+        {
+          # Component API
+          slots: extract_slots(component, source),
+          initialize_params: extract_initialize_params(component),
+
+          # Public interface
+          public_methods: component.public_instance_methods(false),
+
+          # Hierarchy
+          parent_component: component.superclass.name,
+
+          # Phlex-specific
+          has_view_template: component.method_defined?(:view_template),
+
+          # For rendering context
+          renders_many: extract_renders_many(source),
+          renders_one: extract_renders_one(source),
+
+          # Metrics
+          loc: source.lines.count { |l| l.strip.present? && !l.strip.start_with?('#') }
+        }
+      end
+
+      # Extract slot definitions from Phlex components
+      def extract_slots(_component, source)
+        slots = []
+
+        # Phlex 1.x style: renders_one, renders_many
+        source.scan(/renders_one\s+:(\w+)(?:,\s*(\w+))?/) do |name, klass|
+          slots << { name: name, type: :one, class: klass }
+        end
+
+        source.scan(/renders_many\s+:(\w+)(?:,\s*(\w+))?/) do |name, klass|
+          slots << { name: name, type: :many, class: klass }
+        end
+
+        # Also check for slot method definitions
+        source.scan(/def\s+(\w+)_slot/) do |name|
+          slots << { name: name[0], type: :method }
+        end
+
+        slots
+      end
+
+      def extract_renders_many(source)
+        source.scan(/renders_many\s+:(\w+)/).flatten
+      end
+
+      def extract_renders_one(source)
+        source.scan(/renders_one\s+:(\w+)/).flatten
+      end
+
+      # Extract initialize parameters to understand component's data requirements
+      def extract_initialize_params(component)
+        method = component.instance_method(:initialize)
+        params = method.parameters
+
+        params.map do |type, name|
+          param_type = case type
+                       when :req then :required
+                       when :opt then :optional
+                       when :keyreq then :keyword_required
+                       when :key then :keyword_optional
+                       when :rest then :splat
+                       when :keyrest then :double_splat
+                       when :block then :block
+                       else type
+                       end
+          { name: name, type: param_type }
+        end
+      rescue StandardError
+        []
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Dependency Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      def extract_dependencies(component, source)
+        deps = []
+
+        # Other components rendered
+        # Phlex style: render ComponentName.new(...)
+        source.scan(/render\s+(\w+(?:::\w+)*)(?:\.new|\()/).flatten.uniq.each do |comp|
+          next if comp == component.name # Skip self-references
+
+          deps << { type: :component, target: comp, via: :render }
+        end
+
+        # ViewComponent style: render(ComponentName.new(...))
+        source.scan(/render\((\w+(?:::\w+)*)\.new/).flatten.uniq.each do |comp|
+          next if comp == component.name
+
+          deps << { type: :component, target: comp, via: :render }
+        end
+
+        # Model references (often passed as props)
+        deps.concat(scan_model_dependencies(source, via: :data_dependency))
+
+        # Helper modules
+        source.scan(/include\s+(\w+Helper)/).flatten.uniq.each do |helper|
+          deps << { type: :helper, target: helper, via: :include }
+        end
+
+        source.scan(/helpers\.(\w+)/).flatten.uniq.each do |method|
+          deps << { type: :helper_method, target: method, via: :call }
+        end
+
+        # Stimulus controllers (from data-controller attributes)
+        source.scan(/data[_-]controller[=:]\s*["']([^"']+)["']/).flatten.uniq.each do |controller|
+          deps << { type: :stimulus_controller, target: controller, via: :html_attribute }
+        end
+
+        # URL helpers
+        source.scan(/(\w+)_(?:path|url)/).flatten.uniq.each do |route|
+          deps << { type: :route, target: route, via: :url_helper }
+        end
+
+        deps.uniq { |d| [d[:type], d[:target]] }
+      end
+    end
+  end
+end

data/lib/codebase_index/extractors/policy_extractor.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module CodebaseIndex
+  module Extractors
+    # PolicyExtractor handles domain policy class extraction.
+    #
+    # Policy classes encode business eligibility rules — "can this user
+    # upgrade?", "is this order refundable?". These are NOT Pundit
+    # authorization policies. They live in `app/policies/`.
+    #
+    # We extract:
+    # - Policy name and namespace
+    # - Decision methods (allowed?, eligible?, valid?, etc.)
+    # - Models they evaluate (from initializer params and method bodies)
+    # - Dependencies (what models/services they reference)
+    #
+    # @example
+    #   extractor = PolicyExtractor.new
+    #   units = extractor.extract_all
+    #   refund = units.find { |u| u.identifier == "RefundPolicy" }
+    #
+    class PolicyExtractor
+      include SharedUtilityMethods
+      include SharedDependencyScanner
+
+      # Directories to scan for policy classes
+      POLICY_DIRECTORIES = %w[
+        app/policies
+      ].freeze
+
+      # Method name patterns that indicate decision/eligibility logic
+      DECISION_METHOD_PATTERN = /\b(allowed|eligible|valid|permitted|can_\w+|should_\w+|qualifies|meets_\w+|satisfies)\?/
+
+      def initialize
+        @directories = POLICY_DIRECTORIES.map { |d| Rails.root.join(d) }
+                                         .select(&:directory?)
+      end
+
+      # Extract all policy classes
+      #
+      # @return [Array<ExtractedUnit>] List of policy units
+      def extract_all
+        @directories.flat_map do |dir|
+          Dir[dir.join('**/*.rb')].filter_map do |file|
+            extract_policy_file(file)
+          end
+        end
+      end
+
+      # Extract a single policy file
+      #
+      # @param file_path [String] Path to the policy file
+      # @return [ExtractedUnit, nil] The extracted unit or nil if not a policy
+      def extract_policy_file(file_path)
+        source = File.read(file_path)
+        class_name = extract_class_name(file_path, source)
+
+        return nil unless class_name
+        return nil if skip_file?(source)
+
+        unit = ExtractedUnit.new(
+          type: :policy,
+          identifier: class_name,
+          file_path: file_path
+        )
+
+        unit.namespace = extract_namespace(class_name)
+        unit.source_code = annotate_source(source, class_name)
+        unit.metadata = extract_metadata(source, class_name)
+        unit.dependencies = extract_dependencies(source, class_name)
+
+        unit
+      rescue StandardError => e
+        Rails.logger.error("Failed to extract policy #{file_path}: #{e.message}")
+        nil
+      end
+
+      private
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Class Discovery
+      # ──────────────────────────────────────────────────────────────────────
+
+      def extract_class_name(file_path, source)
+        return ::Regexp.last_match(1) if source =~ /^\s*class\s+([\w:]+)/
+
+        file_path
+          .sub("#{Rails.root}/", '')
+          .sub(%r{^app/policies/}, '')
+          .sub('.rb', '')
+          .camelize
+      end
+
+      def skip_file?(source)
+        # Skip module-only files (concerns, base modules)
+        source.match?(/^\s*module\s+\w+\s*$/) && !source.match?(/^\s*class\s+/)
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Source Annotation
+      # ──────────────────────────────────────────────────────────────────────
+
+      def annotate_source(source, class_name)
+        decisions = detect_decision_methods(source)
+        evaluated = detect_evaluated_models(source, class_name)
+
+        <<~ANNOTATION
+          # ╔═══════════════════════════════════════════════════════════════════════╗
+          # ║ Policy: #{class_name.ljust(60)}║
+          # ║ Evaluates: #{evaluated.join(', ').ljust(57)}║
+          # ║ Decisions: #{decisions.join(', ').ljust(57)}║
+          # ╚═══════════════════════════════════════════════════════════════════════╝
+
+          #{source}
+        ANNOTATION
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Metadata Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      def extract_metadata(source, class_name)
+        {
+          evaluated_models: detect_evaluated_models(source, class_name),
+          decision_methods: detect_decision_methods(source),
+          public_methods: extract_public_methods(source),
+          class_methods: extract_class_methods(source),
+          initialize_params: extract_initialize_params(source),
+          is_pundit: pundit_policy?(source),
+          custom_errors: extract_custom_errors(source),
+          loc: source.lines.count { |l| l.strip.length.positive? && !l.strip.start_with?('#') },
+          method_count: source.scan(/def\s+(?:self\.)?\w+/).size
+        }
+      end
+
+      def detect_decision_methods(source)
+        methods = []
+        in_private = false
+        in_protected = false
+
+        source.each_line do |line|
+          stripped = line.strip
+
+          in_private = true if stripped == 'private'
+          in_protected = true if stripped == 'protected'
+          in_private = false if stripped == 'public'
+          in_protected = false if stripped == 'public'
+
+          next if in_private || in_protected
+
+          if stripped =~ /def\s+((?:self\.)?\w+\?)/
+            method_name = ::Regexp.last_match(1)
+            methods << method_name
+          end
+        end
+
+        methods.uniq
+      end
+
+      def detect_evaluated_models(source, class_name)
+        models = []
+
+        # From initialize params
+        if source =~ /def\s+initialize\s*\(([^)]*)\)/
+          params = ::Regexp.last_match(1)
+          params.scan(/(\w+)/).flatten.each do |param|
+            # Skip generic param names
+            next if %w[args options params attributes context].include?(param)
+
+            capitalized = param.sub(/\A\w/, &:upcase).gsub(/_(\w)/) { ::Regexp.last_match(1).upcase }
+            models << capitalized
+          end
+        end
+
+        # Infer from class name: RefundPolicy -> Refund
+        stripped = class_name.split('::').last
+        inferred = stripped.sub(/Policy\z/, '')
+        models << inferred if !inferred.nil? && !inferred.empty? && !models.include?(inferred)
+
+        models.uniq
+      end
+
+      def pundit_policy?(source)
+        source.match?(/< ApplicationPolicy/) ||
+          source.match?(/def\s+initialize\s*\(\s*user\s*,/) ||
+          source.match?(/attr_reader\s+:user\s*,\s*:record/)
+      end
+
+      def extract_custom_errors(source)
+        source.scan(/class\s+(\w+(?:Error|Exception))\s*</).flatten
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Dependency Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      def extract_dependencies(source, class_name)
+        # Evaluated model dependencies (specific :via)
+        deps = detect_evaluated_models(source, class_name).map do |model|
+          { type: :model, target: model, via: :policy_evaluation }
+        end
+
+        deps.concat(scan_model_dependencies(source))
+        deps.concat(scan_service_dependencies(source))
+        deps.concat(scan_job_dependencies(source))
+
+        deps.uniq { |d| [d[:type], d[:target]] }
+      end
+    end
+  end
+end