codebase_index 0.1.0

data/lib/codebase_index/extractors/poro_extractor.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module CodebaseIndex
+  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
+
+      # Extract the parent class name from a class definition.
+      #
+      # @param source [String] Ruby source code
+      # @return [String, nil] Parent class name or nil
+      def extract_parent_class(source)
+        match = source.match(/^\s*class\s+[\w:]+\s*<\s*([\w:]+)/)
+        match ? match[1] : nil
+      end
+
+      # Count non-blank, non-comment lines of code.
+      #
+      # @param source [String] Ruby source code
+      # @return [Integer] LOC count
+      def count_loc(source)
+        source.lines.count { |l| l.strip.length.positive? && !l.strip.start_with?('#') }
+      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

data/lib/codebase_index/extractors/pundit_extractor.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module CodebaseIndex
+  module Extractors
+    # PunditExtractor handles Pundit authorization policy extraction.
+    #
+    # Specifically targets Pundit convention: classes in `app/policies/`
+    # that inherit from ApplicationPolicy or follow Pundit patterns
+    # (user/record attrs, action? methods). This is distinct from the
+    # generic PolicyExtractor which handles domain eligibility policies.
+    #
+    # @example
+    #   extractor = PunditExtractor.new
+    #   units = extractor.extract_all
+    #   post_policy = units.find { |u| u.identifier == "PostPolicy" }
+    #
+    class PunditExtractor
+      include SharedUtilityMethods
+      include SharedDependencyScanner
+
+      # Directories to scan for Pundit policies
+      PUNDIT_DIRECTORIES = %w[
+        app/policies
+      ].freeze
+
+      # Standard Pundit action methods
+      PUNDIT_ACTIONS = %w[index? show? create? new? update? edit? destroy?].freeze
+
+      def initialize
+        @directories = PUNDIT_DIRECTORIES.map { |d| Rails.root.join(d) }
+                                         .select(&:directory?)
+      end
+
+      # Extract all Pundit policy classes
+      #
+      # @return [Array<ExtractedUnit>] List of Pundit policy units
+      def extract_all
+        @directories.flat_map do |dir|
+          Dir[dir.join('**/*.rb')].filter_map do |file|
+            extract_pundit_file(file)
+          end
+        end
+      end
+
+      # Extract a single Pundit policy file
+      #
+      # @param file_path [String] Path to the policy file
+      # @return [ExtractedUnit, nil] The extracted unit or nil if not a Pundit policy
+      def extract_pundit_file(file_path)
+        source = File.read(file_path)
+        class_name = extract_class_name(file_path, source)
+
+        return nil unless class_name
+        return nil unless pundit_policy?(source)
+
+        unit = ExtractedUnit.new(
+          type: :pundit_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 Pundit policy #{file_path}: #{e.message}")
+        nil
+      end
+
+      private
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Class Discovery
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Extract class name from source or infer from file path.
+      #
+      # @param file_path [String]
+      # @param source [String]
+      # @return [String, nil]
+      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', '')
+          .split('/')
+          .map { |s| s.split('_').map(&:capitalize).join }
+          .join('::')
+      end
+
+      # Detect whether this is a Pundit policy.
+      #
+      # @param source [String] Ruby source code
+      # @return [Boolean]
+      def pundit_policy?(source)
+        source.match?(/< ApplicationPolicy/) ||
+          (source.match?(/attr_reader\s+:user/) && source.match?(/attr_reader.*:record/)) ||
+          (source.match?(/def\s+initialize\s*\(\s*user\s*,/) && source.match?(/def\s+\w+\?/))
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Source Annotation
+      # ──────────────────────────────────────────────────────────────────────
+
+      # @param source [String]
+      # @param class_name [String]
+      # @return [String]
+      def annotate_source(source, class_name)
+        model = infer_model(class_name)
+        actions = detect_authorization_actions(source)
+
+        <<~ANNOTATION
+          # ╔═══════════════════════════════════════════════════════════════════════╗
+          # ║ Pundit Policy: #{class_name.ljust(53)}║
+          # ║ Model: #{model.to_s.ljust(61)}║
+          # ║ Actions: #{actions.join(', ').ljust(59)}║
+          # ╚═══════════════════════════════════════════════════════════════════════╝
+
+          #{source}
+        ANNOTATION
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Metadata Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      # @param source [String]
+      # @param class_name [String]
+      # @return [Hash]
+      def extract_metadata(source, class_name)
+        actions = detect_authorization_actions(source)
+        {
+          model: infer_model(class_name),
+          authorization_actions: actions,
+          standard_actions: actions & PUNDIT_ACTIONS,
+          custom_actions: actions - PUNDIT_ACTIONS,
+          has_scope_class: source.match?(/class\s+Scope\b/) || false,
+          inherits_application_policy: source.match?(/< ApplicationPolicy/) || false,
+          public_methods: extract_public_methods(source),
+          class_methods: extract_class_methods(source),
+          loc: source.lines.count { |l| l.strip.length.positive? && !l.strip.start_with?('#') },
+          method_count: source.scan(/def\s+(?:self\.)?\w+/).size
+        }
+      end
+
+      # Detect authorization action methods (public methods ending in ?).
+      #
+      # @param source [String]
+      # @return [Array<String>]
+      def detect_authorization_actions(source)
+        methods = []
+        in_private = false
+        in_protected = false
+        in_scope_class = false
+        scope_depth = 0
+
+        source.each_line do |line|
+          stripped = line.strip
+
+          # Track Scope inner class
+          if stripped =~ /class\s+Scope\b/
+            in_scope_class = true
+            scope_depth = 0
+          end
+          if in_scope_class
+            scope_depth += stripped.scan(/\b(class|module|do)\b/).size
+            scope_depth -= stripped.scan(/\bend\b/).size
+            if scope_depth <= 0
+              in_scope_class = false
+              next
+            end
+            next
+          end
+
+          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
+
+          methods << ::Regexp.last_match(1) if stripped =~ /def\s+(\w+\?)/
+        end
+
+        methods.uniq
+      end
+
+      # Infer the model name from the policy class name.
+      #
+      # @param class_name [String]
+      # @return [String]
+      def infer_model(class_name)
+        stripped = class_name.split('::').last
+        stripped.sub(/Policy\z/, '')
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Dependency Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      # @param source [String]
+      # @param class_name [String]
+      # @return [Array<Hash>]
+      def extract_dependencies(source, class_name)
+        model = infer_model(class_name)
+        deps = [{ type: :model, target: model, via: :authorization }]
+
+        deps.concat(scan_model_dependencies(source))
+        deps.concat(scan_service_dependencies(source))
+
+        deps.uniq { |d| [d[:type], d[:target]] }
+      end
+    end
+  end
+end