woods 1.0.0

data/lib/woods/extractors/phlex_extractor.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module Woods
+  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
+
+      # Locate the source file for a Phlex component class.
+      #
+      # Convention paths first, then introspection via {#resolve_source_location}
+      # which filters out vendor/node_modules paths.
+      #
+      # @param component [Class]
+      # @return [String, nil]
+      def source_file_for(component)
+        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
+
+        resolve_source_location(component, app_root: Rails.root.to_s, fallback: 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/woods/extractors/policy_extractor.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module Woods
+  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, 'policies')
+
+        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
+
+      # ──────────────────────────────────────────────────────────────────────
+      # 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
+
+      # ──────────────────────────────────────────────────────────────────────
+      # 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

data/lib/woods/extractors/poro_extractor.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module Woods
+  module Extractors
+    # PoroExtractor handles plain Ruby object extraction from app/models/.
+    #
+    # Scans app/models/ for Ruby files that define classes which are NOT
+    # ActiveRecord descendants (those are handled by ModelExtractor). Captures
+    # value objects, form objects, CurrentAttributes subclasses, Struct.new
+    # wrappers, and any other non-AR class living alongside AR models.
+    #
+    # Files under app/models/concerns/ are excluded — those are handled by
+    # ConcernExtractor. Module-only files are also excluded.
+    #
+    # @example
+    #   extractor = PoroExtractor.new
+    #   units = extractor.extract_all
+    #   money = units.find { |u| u.identifier == "Money" }
+    #   money.metadata[:parent_class]  # => nil
+    #   money.metadata[:method_count]  # => 3
+    #
+    class PoroExtractor
+      include SharedUtilityMethods
+      include SharedDependencyScanner
+
+      # Glob pattern for all Ruby files in app/models/ (recursive).
+      MODELS_GLOB = 'app/models/**/*.rb'
+
+      # Subdirectory to exclude — handled by ConcernExtractor.
+      CONCERNS_SEGMENT = '/concerns/'
+
+      def initialize
+        @models_dir = Rails.root.join('app/models')
+      end
+
+      # Extract all PORO units from app/models/.
+      #
+      # Filters out ActiveRecord descendants by name so we don't duplicate
+      # what ModelExtractor already produces. Concerns/ subdir is also skipped.
+      #
+      # @return [Array<ExtractedUnit>] List of PORO units
+      def extract_all
+        return [] unless @models_dir.directory?
+
+        ar_names = ActiveRecord::Base.descendants.filter_map(&:name).to_set
+
+        Dir[Rails.root.join(MODELS_GLOB)].filter_map do |file|
+          next if file.include?(CONCERNS_SEGMENT)
+
+          extract_poro_file(file, ar_names: ar_names)
+        end
+      end
+
+      # Extract a single PORO file.
+      #
+      # Returns nil if the file is not a PORO (e.g., module-only, no class
+      # or PORO pattern found, or the inferred class is an AR descendant).
+      #
+      # @param file_path [String] Absolute path to the Ruby file
+      # @param ar_names [Set<String>] Set of AR descendant names to skip
+      # @return [ExtractedUnit, nil] The extracted unit or nil
+      def extract_poro_file(file_path, ar_names: Set.new)
+        source = File.read(file_path)
+
+        return nil unless poro_file?(source)
+        return nil if module_only?(source)
+
+        class_name = infer_class_name(file_path, source)
+        return nil unless class_name
+        return nil if ar_names.include?(class_name)
+
+        unit = ExtractedUnit.new(
+          type: :poro,
+          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)
+
+        unit
+      rescue StandardError => e
+        Rails.logger.error("Failed to extract PORO #{file_path}: #{e.message}")
+        nil
+      end
+
+      private
+
+      # ──────────────────────────────────────────────────────────────────────
+      # File Classification
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Determine whether a file is worth examining as a PORO.
+      #
+      # A file qualifies if it contains a class definition OR uses one of the
+      # common PORO-without-class patterns (Struct.new, Data.define).
+      # Plain constant assignments and module-only files are excluded upstream.
+      #
+      # @param source [String] Ruby source code
+      # @return [Boolean]
+      def poro_file?(source)
+        source.match?(/^\s*class\s+/) ||
+          source.match?(/\bStruct\.new\b/) ||
+          source.match?(/\bData\.define\b/)
+      end
+
+      # Return true when the file defines only modules, no class keyword.
+      #
+      # @param source [String] Ruby source code
+      # @return [Boolean]
+      def module_only?(source)
+        source.match?(/^\s*module\s+\w+/) && !source.match?(/^\s*class\s+/)
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Class Name Inference
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Infer the primary class name from source or fall back to file path.
+      #
+      # For regular class definitions we parse the first `class Foo` line,
+      # joining outer module namespaces when present. For Struct.new / Data.define
+      # patterns we read the constant assignment name. Falls back to the
+      # Rails camelize convention on the relative path.
+      #
+      # @param file_path [String] Absolute path to the file
+      # @param source [String] Ruby source code
+      # @return [String, nil] The inferred class name
+      def infer_class_name(file_path, source)
+        # Explicit class keyword — combine outer module namespaces + class name
+        class_match = source.match(/^\s*class\s+([\w:]+)/)
+        if class_match
+          base = class_match[1]
+          # If already fully qualified (e.g., Order::Update), use as-is
+          return base if base.include?('::')
+
+          namespaces = source.scan(/^\s*module\s+([\w:]+)/).flatten
+          return namespaces.any? ? "#{namespaces.join('::')}::#{base}" : base
+        end
+
+        # Struct.new / Data.define: ConstantName = Struct.new(...)
+        struct_match = source.match(/^(\w[\w:]*)\s*=\s*(?:Struct\.new|Data\.define)/)
+        return struct_match[1] if struct_match
+
+        # Fall back: derive from file path using Rails naming convention
+        path_based_class_name(file_path)
+      end
+
+      # Derive a class name from a file path using Rails camelize convention.
+      #
+      # app/models/order/update.rb => Order::Update
+      # app/models/money.rb        => Money
+      #
+      # @param file_path [String] Absolute path to the file
+      # @return [String] Camelize-derived class name
+      def path_based_class_name(file_path)
+        relative = file_path.sub("#{Rails.root}/", '')
+        relative
+          .sub(%r{^app/models/}, '')
+          .sub('.rb', '')
+          .split('/')
+          .map(&:camelize)
+          .join('::')
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Source Annotation
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Prepend a summary annotation header to the source.
+      #
+      # @param source [String] Ruby source code
+      # @param class_name [String] The class name
+      # @return [String] Annotated source
+      def annotate_source(source, class_name)
+        parent = extract_parent_class(source)
+        parent_label = parent || 'none'
+
+        annotation = <<~ANNOTATION
+          # ╔═══════════════════════════════════════════════════════════════════════╗
+          # ║ PORO: #{class_name.ljust(63)}║
+          # ║ Parent: #{parent_label.ljust(61)}║
+          # ╚═══════════════════════════════════════════════════════════════════════╝
+
+        ANNOTATION
+
+        annotation + source
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Metadata Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Build the metadata hash for a PORO unit.
+      #
+      # @param source [String] Ruby source code
+      # @param class_name [String] The class name
+      # @return [Hash] PORO metadata
+      def extract_metadata(source, _class_name)
+        {
+          public_methods: extract_public_methods(source),
+          class_methods: extract_class_methods(source),
+          initialize_params: extract_initialize_params(source),
+          parent_class: extract_parent_class(source),
+          loc: count_loc(source),
+          method_count: source.scan(/def\s+(?:self\.)?\w+/).size
+        }
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Dependency Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Build the dependency array for a PORO unit using common scanners.
+      #
+      # @param source [String] Ruby source code
+      # @return [Array<Hash>] Dependency hashes with :type, :target, :via
+      def extract_dependencies(source)
+        deps = scan_common_dependencies(source)
+        deps.uniq { |d| [d[:type], d[:target]] }
+      end
+    end
+  end
+end