codebase_index 0.2.1 → 0.3.1

data/lib/codebase_index/extractor.rb

@@ -7,6 +7,7 @@ require 'open3'
 require 'pathname'
 require 'set'
 
+require_relative 'filename_utils'
 require_relative 'extracted_unit'
 require_relative 'dependency_graph'
 require_relative 'extractors/model_extractor'
@@ -62,6 +63,8 @@ module CodebaseIndex
   #   extractor.extract_changed(["app/models/user.rb", "app/services/checkout.rb"])
   #
   class Extractor
+    include FilenameUtils
+
     # Directories under app/ that contain classes we need to extract.
     # Used by eager_load_extraction_directories as a fallback when
     # Rails.application.eager_load! fails (e.g., NameError from graphql/).
@@ -443,19 +446,24 @@ module CodebaseIndex
     # ──────────────────────────────────────────────────────────────────────
 
     def resolve_dependents
-      all_units = @results.values.flatten
-      unit_map = all_units.index_by(&:identifier)
-
-      all_units.each do |unit|
-        unit.dependencies.each do |dep|
-          target_unit = unit_map[dep[:target]]
-          next unless target_unit
-
-          target_unit.dependents ||= []
-          target_unit.dependents << {
-            type: unit.type,
-            identifier: unit.identifier
-          }
+      # Build complete unit map first (cross-type dependencies require all units indexed).
+      unit_map = @results.each_with_object({}) do |(_type, units), map|
+        units.each { |u| map[u.identifier] = u }
+      end
+
+      # Resolve dependents using the complete map.
+      @results.each_value do |units|
+        units.each do |unit|
+          unit.dependencies.each do |dep|
+            target_unit = unit_map[dep[:target]]
+            next unless target_unit
+
+            target_unit.dependents ||= []
+            target_unit.dependents << {
+              type: unit.type,
+              identifier: unit.identifier
+            }
+          end
         end
       end
     end
@@ -480,7 +488,7 @@ module CodebaseIndex
     # ──────────────────────────────────────────────────────────────────────
 
     def precompute_flows
-      all_units = @results.values.flatten
+      all_units = @results.values.flatten(1)
       precomputer = FlowPrecomputer.new(units: all_units, graph: @dependency_graph, output_dir: @output_dir.to_s)
       flow_map = precomputer.precompute
       Rails.logger.info "[CodebaseIndex] Precomputed #{flow_map.size} request flows"
@@ -585,6 +593,7 @@ module CodebaseIndex
       result = {}
       relative_paths.each { |rp| result[rp] = {} }
 
+      path_set = relative_paths.to_set
       relative_paths.each_slice(500) do |batch|
         log_output = run_git(
           'log', '--all', '--name-only',
@@ -592,7 +601,7 @@ module CodebaseIndex
           '--since=365 days ago',
           '--', *batch
         )
-        parse_git_log_output(log_output, relative_paths.to_set, result)
+        parse_git_log_output(log_output, path_set, result)
       end
 
       ninety_days_ago = (Time.current - 90.days).iso8601
@@ -708,9 +717,16 @@ module CodebaseIndex
     def write_graph_analysis
       return unless @graph_analysis
 
+      enriched = @graph_analysis.merge(
+        generated_at: Time.current.iso8601,
+        graph_sha: Digest::SHA256.hexdigest(
+          File.read(@output_dir.join('dependency_graph.json'))
+        )
+      )
+
       File.write(
         @output_dir.join('graph_analysis.json'),
-        json_serialize(@graph_analysis)
+        json_serialize(enriched)
       )
     end
 
@@ -725,7 +741,7 @@ module CodebaseIndex
 
         # Total stats
         total_units: @results.values.sum(&:size),
-        total_chunks: @results.values.flatten.sum { |u| u.chunks.size },
+        total_chunks: @results.sum { |_, units| units.sum { |u| u.chunks.size } },
 
         # Git info
         git_sha: run_git('rev-parse', 'HEAD').presence,
@@ -753,7 +769,7 @@ module CodebaseIndex
       return if @results.empty?
 
       total_units    = @results.values.sum(&:size)
-      total_chunks   = @results.values.flatten.sum { |u| [u.chunks.size, 1].max }
+      total_chunks   = @results.sum { |_, units| units.sum { |u| [u.chunks.size, 1].max } }
       category_count = @results.count { |_, units| units.any? }
 
       summary = []
@@ -841,31 +857,11 @@ module CodebaseIndex
     end
 
     def schema_sha
-      schema_path = Rails.root.join('db/schema.rb')
-      return nil unless schema_path.exist?
-
-      Digest::SHA256.file(schema_path).hexdigest
-    end
-
-    # Generate a safe JSON filename from a unit identifier.
-    #
-    # @param identifier [String] Unit identifier (e.g., "Admin::UsersController")
-    # @return [String] Safe filename (e.g., "Admin__UsersController.json")
-    def safe_filename(identifier)
-      "#{identifier.gsub('::', '__').gsub(/[^a-zA-Z0-9_-]/, '_')}.json"
-    end
-
-    # Generate a collision-safe JSON filename by appending a short digest.
-    # Unlike safe_filename, this guarantees distinct filenames even when two
-    # identifiers differ only in characters that safe_filename normalizes
-    # (e.g., "GET /foo/bar" vs "GET /foo_bar" both become "GET__foo_bar.json").
-    #
-    # @param identifier [String] Unit identifier
-    # @return [String] Collision-safe filename (e.g., "GET__foo_bar_a1b2c3d4.json")
-    def collision_safe_filename(identifier)
-      base = identifier.gsub('::', '__').gsub(/[^a-zA-Z0-9_-]/, '_')
-      digest = ::Digest::SHA256.hexdigest(identifier)[0, 8]
-      "#{base}_#{digest}.json"
+      %w[db/schema.rb db/structure.sql].each do |path|
+        full = Rails.root.join(path)
+        return Digest::SHA256.file(full).hexdigest if full.exist?
+      end
+      nil
     end
 
     def json_serialize(data)
@@ -878,7 +874,7 @@ module CodebaseIndex
 
     def log_summary
       total = @results.values.sum(&:size)
-      chunks = @results.values.flatten.sum { |u| u.chunks.size }
+      chunks = @results.sum { |_, units| units.sum { |u| u.chunks.size } }
 
       Rails.logger.info '[CodebaseIndex] ═══════════════════════════════════════════'
       Rails.logger.info '[CodebaseIndex] Extraction Complete'

data/lib/codebase_index/extractors/action_cable_extractor.rb

@@ -50,7 +50,7 @@ module CodebaseIndex
       # @return [ExtractedUnit, nil]
       def extract_channel(klass)
         name = klass.name
-        file_path = discover_source_path(klass, name)
+        file_path = source_file_for(klass, name)
         source = read_source(file_path)
         own_methods = klass.instance_methods(false)
 
@@ -89,48 +89,21 @@ module CodebaseIndex
         end
       end
 
-      # Discover the source file path for a channel class.
+      # Locate the source file for a channel class.
       #
-      # Tries source_location on instance methods, then falls back to
-      # the Rails convention path.
+      # Convention path first, then introspection via {#resolve_source_location}
+      # which filters out vendor/node_modules paths.
       #
       # @param klass [Class] The channel class
       # @param name [String] The channel class name
       # @return [String, nil]
-      def discover_source_path(klass, name)
-        path = source_location_from_methods(klass)
-        return path if path
-
-        convention_fallback(name)
-      end
-
-      # Try to get source_location from the channel's instance methods.
-      # Tries subscribed first, then any other instance method.
-      #
-      # @param klass [Class] The channel class
-      # @return [String, nil]
-      def source_location_from_methods(klass)
-        try_methods = [:subscribed] + (klass.instance_methods(false) - [:subscribed])
-        try_methods.each do |method_name|
-          location = klass.instance_method(method_name).source_location
-          return location[0] if location
-        rescue NameError, TypeError
-          next
-        end
-        nil
-      rescue StandardError
-        nil
-      end
-
-      # Fall back to Rails convention path for channel files.
-      #
-      # @param name [String] Channel class name
-      # @return [String, nil]
-      def convention_fallback(name)
+      def source_file_for(klass, name)
         return nil unless defined?(Rails) && Rails.respond_to?(:root) && Rails.root
 
-        path = Rails.root.join('app', 'channels', "#{name.underscore}.rb").to_s
-        File.exist?(path) ? path : nil
+        convention_path = Rails.root.join('app', 'channels', "#{name.underscore}.rb").to_s
+        return convention_path if File.exist?(convention_path)
+
+        resolve_source_location(klass, app_root: Rails.root.to_s, fallback: nil)
       end
 
       # Read source code from a file path.

data/lib/codebase_index/extractors/callback_analyzer.rb

@@ -34,6 +34,21 @@ module CodebaseIndex
       # Async enqueue methods that indicate a job is being dispatched.
       ASYNC_METHODS = %w[perform_later perform_async perform_in perform_at].freeze
 
+      # Pre-compiled regex patterns (avoid dynamic regex construction in hot loops)
+      SINGLE_COLUMN_WRITER_PATTERNS = SINGLE_COLUMN_WRITERS.to_h do |w|
+        [w, /\b#{Regexp.escape(w)}\s*\(?\s*[:'"](\w+)/]
+      end.freeze
+
+      MULTI_COLUMN_WRITER_PATTERNS = MULTI_COLUMN_WRITERS.to_h do |w|
+        [w, /\b#{Regexp.escape(w)}\s*\(([^)]+)\)/m]
+      end.freeze
+
+      ASYNC_PATTERN = /(\w+(?:Job|Worker))\.(?:#{ASYNC_METHODS.map { |m| Regexp.escape(m) }.join('|')})/
+
+      DB_READ_PATTERNS = DB_READ_METHODS.to_h do |m|
+        [m, /\.#{Regexp.escape(m)}\b/]
+      end.freeze
+
       # @param source_code [String] Composite model source (with inlined concerns)
       # @param column_names [Array<String>] Model's database column names
       def initialize(source_code:, column_names: [])
@@ -141,15 +156,15 @@ module CodebaseIndex
         end
 
         # Pattern: update_column(:col, ...) / write_attribute(:col, ...)
-        SINGLE_COLUMN_WRITERS.each do |writer|
-          method_source.scan(/\b#{Regexp.escape(writer)}\s*\(?\s*[:'"](\w+)/).flatten.each do |col|
+        SINGLE_COLUMN_WRITER_PATTERNS.each_value do |pattern|
+          method_source.scan(pattern).flatten.each do |col|
             columns << col if @column_names.include?(col)
           end
         end
 
         # Pattern: update_columns(col: ...) / assign_attributes(col: ...)
-        MULTI_COLUMN_WRITERS.each do |writer|
-          method_source.scan(/\b#{Regexp.escape(writer)}\s*\(([^)]+)\)/m).each do |match|
+        MULTI_COLUMN_WRITER_PATTERNS.each_value do |pattern|
+          method_source.scan(pattern).each do |match|
             match[0].scan(/\b(\w+)\s*:(?!:)/).flatten.each do |col|
               columns << col if @column_names.include?(col)
             end
@@ -166,8 +181,7 @@ module CodebaseIndex
       # @param method_source [String]
       # @return [Array<String>]
       def detect_jobs_enqueued(method_source)
-        async_pattern = ASYNC_METHODS.map { |m| Regexp.escape(m) }.join('|')
-        method_source.scan(/(\w+(?:Job|Worker))\.(?:#{async_pattern})/).flatten.uniq.sort
+        method_source.scan(ASYNC_PATTERN).flatten.uniq.sort
       end
 
       # Detect service objects called by the callback method.
@@ -197,8 +211,8 @@ module CodebaseIndex
       # @param method_source [String]
       # @return [Array<String>]
       def detect_database_reads(method_source)
-        DB_READ_METHODS.select do |method|
-          method_source.match?(/\.#{Regexp.escape(method)}\b/)
+        DB_READ_PATTERNS.filter_map do |method, pattern|
+          method if method_source.match?(pattern)
         end
       end
 

data/lib/codebase_index/extractors/controller_extractor.rb

@@ -115,40 +115,16 @@ module CodebaseIndex
 
       # Find the source file for a controller, validating paths are within Rails.root.
       #
-      # Uses a multi-tier strategy to avoid returning gem/vendor paths that appear
-      # when controllers include modules from gems (e.g., decent_exposure, appsignal).
+      # 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)
-        app_root = Rails.root.to_s
         convention_path = Rails.root.join("app/controllers/#{controller.name.underscore}.rb").to_s
-
-        # Tier 1: Instance methods defined directly on this controller
-        controller.instance_methods(false).each do |method_name|
-          loc = controller.instance_method(method_name).source_location&.first
-          return loc if loc&.start_with?(app_root)
-        end
-
-        # Tier 2: Class/singleton methods defined on this controller
-        controller.methods(false).each do |method_name|
-          loc = controller.method(method_name).source_location&.first
-          return loc if loc&.start_with?(app_root)
-        end
-
-        # Tier 3: Convention path if file exists
         return convention_path if File.exist?(convention_path)
 
-        # Tier 4: const_source_location (Ruby 3.0+)
-        if Object.respond_to?(:const_source_location)
-          loc = Object.const_source_location(controller.name)&.first
-          return loc if loc&.start_with?(app_root)
-        end
-
-        # Tier 5: Always return convention path — never a gem path
-        convention_path
-      rescue StandardError
-        Rails.root.join("app/controllers/#{controller.name.underscore}.rb").to_s
+        resolve_source_location(controller, app_root: Rails.root.to_s, fallback: convention_path)
       end
 
       # Build composite source with routes and filters as headers
@@ -228,72 +204,6 @@ module CodebaseIndex
         end
       end
 
-      # Extract :only/:except action lists and :if/:unless conditions from a callback.
-      #
-      # Modern Rails (4.2+) stores conditions in @if/@unless ivar arrays.
-      # ActionFilter objects hold action Sets; other conditions are procs/symbols.
-      #
-      # @param callback [ActiveSupport::Callbacks::Callback]
-      # @return [Array(Array<String>, Array<String>, Array<String>, Array<String>)]
-      #   [only_actions, except_actions, if_labels, unless_labels]
-      def extract_callback_conditions(callback)
-        if_conditions = callback.instance_variable_get(:@if) || []
-        unless_conditions = callback.instance_variable_get(:@unless) || []
-
-        only = []
-        except = []
-        if_labels = []
-        unless_labels = []
-
-        if_conditions.each do |cond|
-          actions = extract_action_filter_actions(cond)
-          if actions
-            only.concat(actions)
-          else
-            if_labels << condition_label(cond)
-          end
-        end
-
-        unless_conditions.each do |cond|
-          actions = extract_action_filter_actions(cond)
-          if actions
-            except.concat(actions)
-          else
-            unless_labels << condition_label(cond)
-          end
-        end
-
-        [only, except, if_labels, unless_labels]
-      end
-
-      # Extract action names from an ActionFilter-like condition object.
-      # Duck-types on the @actions ivar being a Set, avoiding dependence
-      # on private class names across Rails versions.
-      #
-      # @param condition [Object] A condition from the callback's @if/@unless array
-      # @return [Array<String>, nil] Action names, or nil if not an ActionFilter
-      def extract_action_filter_actions(condition)
-        return nil unless condition.instance_variable_defined?(:@actions)
-
-        actions = condition.instance_variable_get(:@actions)
-        return nil unless actions.is_a?(Set)
-
-        actions.to_a
-      end
-
-      # Human-readable label for a non-ActionFilter condition.
-      #
-      # @param condition [Object] A proc, symbol, or other condition
-      # @return [String]
-      def condition_label(condition)
-        case condition
-        when Symbol then ":#{condition}"
-        when Proc then 'Proc'
-        when String then condition
-        else condition.class.name
-        end
-      end
-
       # ──────────────────────────────────────────────────────────────────────
       # Metadata Extraction
       # ──────────────────────────────────────────────────────────────────────

data/lib/codebase_index/extractors/decorator_extractor.rb

@@ -90,11 +90,10 @@ module CodebaseIndex
       # 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").
+      # Override SharedUtilityMethods#extract_class_name for decorator-specific
+      # namespace resolution. The shared version only matches `class Foo::Bar`
+      # (inline namespacing); this version also handles `module Admin / class
+      # UserDecorator` (block namespacing) by scanning for enclosing modules.
       #
       # @param file_path [String] Path to the file
       # @param source [String] Ruby source code
@@ -119,14 +118,6 @@ module CodebaseIndex
         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
       # ──────────────────────────────────────────────────────────────────────
@@ -220,7 +211,9 @@ module CodebaseIndex
         methods.uniq
       end
 
-      # Detect common entry points for decorator invocation.
+      # Override SharedUtilityMethods#detect_entry_points with decorator-specific
+      # entry points (decorate, present, to_partial_path) instead of the generic
+      # service-oriented ones (perform, execute, run, process).
       #
       # @param source [String] Ruby source code
       # @return [Array<String>] Entry point method names

data/lib/codebase_index/extractors/engine_extractor.rb

@@ -132,7 +132,8 @@ module CodebaseIndex
           mounted_path: mounted_path,
           route_count: route_count,
           isolate_namespace: isolated,
-          controllers: controllers
+          controllers: controllers,
+          engine_source: framework_engine?(engine) ? :framework : :application
         }
         unit.dependencies = build_engine_dependencies(controllers)
 
@@ -142,6 +143,24 @@ module CodebaseIndex
         nil
       end
 
+      # Check if an engine is a framework gem rather than an application engine.
+      #
+      # An engine is framework if it lives outside Rails.root, or inside
+      # Rails.root but under vendor/bundle or bundler/gems (common in Docker
+      # where Rails.root is /app and gems install to /app/vendor/bundle).
+      #
+      # @param engine [Class] A Rails::Engine subclass
+      # @return [Boolean]
+      def framework_engine?(engine)
+        root = engine.root.to_s
+
+        # Engine outside Rails.root is definitely framework
+        return true unless root.start_with?(Rails.root.to_s)
+
+        # Engine inside Rails.root but in vendor/bundler paths is framework
+        root.include?('/vendor/') || root.include?('/bundler/gems/')
+      end
+
       # Count routes defined by an engine.
       #
       # @param engine [Class] A Rails::Engine subclass

data/lib/codebase_index/extractors/graphql_extractor.rb

@@ -202,39 +202,16 @@ module CodebaseIndex
       # Determine the source file for a runtime-loaded class, validating that
       # paths are within Rails.root to avoid returning graphql gem internals.
       #
-      # Uses a multi-tier strategy matching the model extractor's pattern.
+      # Convention path first, then introspection via {#resolve_source_location}
+      # which filters out vendor/node_modules paths.
       #
       # @param klass [Class]
       # @return [String] Absolute path to the source file
       def source_file_for_class(klass)
-        app_root = Rails.root.to_s
         convention_path = Rails.root.join("#{GRAPHQL_DIRECTORY}/#{klass.name.underscore}.rb").to_s
-
-        # Tier 1: Instance methods defined directly on this class
-        klass.instance_methods(false).each do |method_name|
-          loc = klass.instance_method(method_name).source_location&.first
-          return loc if loc&.start_with?(app_root)
-        end
-
-        # Tier 2: Singleton methods defined on this class
-        klass.singleton_methods(false).each do |method_name|
-          loc = klass.method(method_name).source_location&.first
-          return loc if loc&.start_with?(app_root)
-        end
-
-        # Tier 3: Convention path if file exists
         return convention_path if File.exist?(convention_path)
 
-        # Tier 4: const_source_location (Ruby 3.0+)
-        if Object.respond_to?(:const_source_location)
-          loc = Object.const_source_location(klass.name)&.first
-          return loc if loc&.start_with?(app_root)
-        end
-
-        # Tier 5: Always return convention path — never a gem path
-        convention_path
-      rescue StandardError
-        Rails.root.join("#{GRAPHQL_DIRECTORY}/#{klass.name.underscore}.rb").to_s
+        resolve_source_location(klass, app_root: Rails.root.to_s, fallback: convention_path)
       end
 
       # ──────────────────────────────────────────────────────────────────────
@@ -619,9 +596,7 @@ module CodebaseIndex
       # @return [Array<String>]
       def extract_connections(source)
         # field :items, Types::ItemType.connection_type
-        connections = source.scan(/([\w:]+)\.connection_type/).flatten.map do |type|
-          type
-        end
+        connections = source.scan(/([\w:]+)\.connection_type/).flatten
 
         # connection_type_class ConnectionType
         source.scan(/connection_type_class\s+([\w:]+)/).flatten.each do |type|

data/lib/codebase_index/extractors/job_extractor.rb

@@ -152,13 +152,18 @@ module CodebaseIndex
           source.match?(/def perform/)
       end
 
+      # Locate the source file for a job class.
+      #
+      # Convention path first, then introspection via {#resolve_source_location}
+      # which filters out vendor/node_modules paths.
+      #
+      # @param job_class [Class]
+      # @return [String, nil]
       def source_file_for(job_class)
-        # Try to get from method source location
-        if job_class.method_defined?(:perform, false)
-          job_class.instance_method(:perform).source_location&.first
-        end || Rails.root.join("app/jobs/#{job_class.name.underscore}.rb").to_s
-      rescue StandardError
-        nil
+        convention_path = Rails.root.join("app/jobs/#{job_class.name.underscore}.rb").to_s
+        return convention_path if File.exist?(convention_path)
+
+        resolve_source_location(job_class, app_root: Rails.root.to_s, fallback: convention_path)
       end
 
       # ──────────────────────────────────────────────────────────────────────

data/lib/codebase_index/extractors/lib_extractor.rb

@@ -201,37 +201,6 @@ module CodebaseIndex
         }
       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
-
-      # Detect common entry point methods.
-      #
-      # @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 << 'perform' if source.match?(/def (self\.)?perform\b/)
-        points << 'execute' if source.match?(/def (self\.)?execute\b/)
-        points << 'run'     if source.match?(/def (self\.)?run\b/)
-        points << 'process' if source.match?(/def (self\.)?process\b/)
-        points.empty? ? ['unknown'] : points
-      end
-
       # ──────────────────────────────────────────────────────────────────────
       # Dependency Extraction
       # ──────────────────────────────────────────────────────────────────────