codebase_index 0.1.0

data/lib/codebase_index/extractors/database_view_extractor.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module CodebaseIndex
+  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

data/lib/codebase_index/extractors/decorator_extractor.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module CodebaseIndex
+  module Extractors
+    # DecoratorExtractor handles decorator, presenter, and form object extraction.
+    #
+    # Scans conventional directories for view-layer wrapper objects:
+    # decorators (Draper-style or PORO), presenters, and form objects.
+    # Extracts the decorated model relationship, delegation chains, and
+    # whether the Draper gem is in use.
+    #
+    # @example
+    #   extractor = DecoratorExtractor.new
+    #   units = extractor.extract_all
+    #   user_dec = units.find { |u| u.identifier == "UserDecorator" }
+    #   user_dec.metadata[:decorated_model]  # => "User"
+    #   user_dec.metadata[:uses_draper]      # => true
+    #
+    class DecoratorExtractor
+      include SharedUtilityMethods
+      include SharedDependencyScanner
+
+      # Directories to scan for decorator-style objects
+      DECORATOR_DIRECTORIES = %w[
+        app/decorators
+        app/presenters
+        app/form_objects
+      ].freeze
+
+      # Maps directory segment to decorator_type symbol
+      DIRECTORY_TYPE_MAP = {
+        'decorators' => :decorator,
+        'presenters' => :presenter,
+        'form_objects' => :form_object
+      }.freeze
+
+      # Suffixes used to infer the decorated model name
+      DECORATOR_SUFFIXES = %w[Decorator Presenter Form].freeze
+
+      def initialize
+        @directories = DECORATOR_DIRECTORIES.map { |d| Rails.root.join(d) }
+                                            .select(&:directory?)
+      end
+
+      # Extract all decorator, presenter, and form object units.
+      #
+      # @return [Array<ExtractedUnit>] List of decorator units
+      def extract_all
+        @directories.flat_map do |dir|
+          Dir[dir.join('**/*.rb')].filter_map do |file|
+            extract_decorator_file(file)
+          end
+        end
+      end
+
+      # Extract a single decorator file.
+      #
+      # @param file_path [String] Absolute path to the Ruby file
+      # @return [ExtractedUnit, nil] The extracted unit or nil if not a decorator
+      def extract_decorator_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: :decorator,
+          identifier: class_name,
+          file_path: file_path
+        )
+
+        unit.namespace = extract_namespace(class_name)
+        unit.source_code = annotate_source(source, class_name, file_path)
+        unit.metadata = extract_metadata(source, class_name, file_path)
+        unit.dependencies = extract_dependencies(source, class_name)
+
+        unit
+      rescue StandardError => e
+        Rails.logger.error("Failed to extract decorator #{file_path}: #{e.message}")
+        nil
+      end
+
+      private
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Class Discovery
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Extract the class name from source or fall back to filename convention.
+      #
+      # Handles namespaced classes defined inside module blocks by combining
+      # outer module names with the class name (e.g., module Admin / class
+      # UserDecorator → "Admin::UserDecorator").
+      #
+      # @param file_path [String] Path to the file
+      # @param source [String] Ruby source code
+      # @return [String, nil] The class name or nil
+      def extract_class_name(file_path, source)
+        namespaces = source.scan(/^\s*module\s+([\w:]+)/).flatten
+        class_match = source.match(/^\s*class\s+([\w:]+)/)
+
+        if class_match
+          base_class = class_match[1]
+          if namespaces.any? && !base_class.include?('::')
+            "#{namespaces.join('::')}::#{base_class}"
+          else
+            base_class
+          end
+        else
+          relative = file_path.sub("#{Rails.root}/", '')
+          relative
+            .sub(%r{^app/(decorators|presenters|form_objects)/}, '')
+            .sub('.rb', '')
+            .camelize
+        end
+      end
+
+      # Skip module-only files (concerns, base modules without a class).
+      #
+      # @param source [String] Ruby source code
+      # @return [Boolean]
+      def skip_file?(source)
+        source.match?(/^\s*module\s+\w+\s*$/) && !source.match?(/^\s*class\s+/)
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Source Annotation
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Prepend a summary annotation header to the source.
+      #
+      # @param source [String] Ruby source code
+      # @param class_name [String] The class name
+      # @param file_path [String] Path to the file
+      # @return [String] Annotated source
+      def annotate_source(source, class_name, file_path)
+        decorator_type = infer_decorator_type(file_path)
+        decorated_model = infer_decorated_model(class_name)
+
+        annotation = <<~ANNOTATION
+          # ╔═══════════════════════════════════════════════════════════════════════╗
+          # ║ Decorator: #{class_name.ljust(57)}║
+          # ║ Type: #{decorator_type.to_s.ljust(62)}║
+          # ║ Decorates: #{(decorated_model || 'unknown').ljust(57)}║
+          # ╚═══════════════════════════════════════════════════════════════════════╝
+
+        ANNOTATION
+
+        annotation + source
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Metadata Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Build the metadata hash for a decorator unit.
+      #
+      # @param source [String] Ruby source code
+      # @param class_name [String] The class name
+      # @param file_path [String] Path to the file
+      # @return [Hash] Decorator metadata
+      def extract_metadata(source, class_name, file_path)
+        {
+          decorator_type: infer_decorator_type(file_path),
+          decorated_model: infer_decorated_model(class_name),
+          uses_draper: draper?(source),
+          delegated_methods: extract_delegated_methods(source),
+          public_methods: extract_public_methods(source),
+          entry_points: detect_entry_points(source),
+          class_methods: extract_class_methods(source),
+          initialize_params: extract_initialize_params(source),
+          loc: source.lines.count { |l| l.strip.length.positive? && !l.strip.start_with?('#') }
+        }
+      end
+
+      # Infer the decorator_type symbol from the file path.
+      #
+      # @param file_path [String] Absolute path to the file
+      # @return [Symbol] :decorator, :presenter, or :form_object
+      def infer_decorator_type(file_path)
+        DIRECTORY_TYPE_MAP.each do |dir_segment, type|
+          return type if file_path.include?("/#{dir_segment}/")
+        end
+        :decorator
+      end
+
+      # Infer the decorated model name by stripping known suffixes.
+      #
+      # @param class_name [String] e.g. "UserDecorator", "ProductPresenter"
+      # @return [String, nil] e.g. "User", "Product", or nil if not inferable
+      def infer_decorated_model(class_name)
+        base = class_name.split('::').last
+        DECORATOR_SUFFIXES.each do |suffix|
+          return base.delete_suffix(suffix) if base.end_with?(suffix) && base.length > suffix.length
+        end
+        nil
+      end
+
+      # Detect whether the class uses the Draper gem.
+      #
+      # @param source [String] Ruby source code
+      # @return [Boolean]
+      def draper?(source)
+        source.match?(/Draper::Decorator/)
+      end
+
+      # Extract method names passed to `delegate` calls.
+      #
+      # @param source [String] Ruby source code
+      # @return [Array<String>] Delegated method names
+      def extract_delegated_methods(source)
+        methods = []
+        source.scan(/\bdelegate\s+(.*?)(?:,\s*to:|$)/m) do |match|
+          match[0].scan(/:(\w+)/).flatten.each { |m| methods << m }
+        end
+        methods.uniq
+      end
+
+      # Detect common entry points for decorator invocation.
+      #
+      # @param source [String] Ruby source code
+      # @return [Array<String>] Entry point method names
+      def detect_entry_points(source)
+        points = []
+        points << 'call'       if source.match?(/def (self\.)?call\b/)
+        points << 'decorate'   if source.match?(/def (self\.)?decorate\b/)
+        points << 'present'    if source.match?(/def (self\.)?present\b/)
+        points << 'to_partial_path' if source.match?(/def to_partial_path\b/)
+        points.empty? ? ['unknown'] : points
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Dependency Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Build the dependency array for a decorator unit.
+      #
+      # Links to the decorated model via :decoration and scans the source
+      # for common code references (models, services, jobs, mailers).
+      #
+      # @param source [String] Ruby source code
+      # @param class_name [String] The class name
+      # @return [Array<Hash>] Dependency hashes with :type, :target, :via
+      def extract_dependencies(source, class_name)
+        deps = []
+
+        decorated_model = infer_decorated_model(class_name)
+        deps << { type: :model, target: decorated_model, via: :decoration } if decorated_model
+
+        deps.concat(scan_common_dependencies(source))
+
+        deps.uniq { |d| [d[:type], d[:target]] }
+      end
+    end
+  end
+end