codebase_index 0.3.2 → 0.4.0

data/lib/codebase_index/notion/mappers/migration_mapper.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-module CodebaseIndex
-  module Notion
-    module Mappers
-      # Extracts latest migration dates per table from migration ExtractedUnits.
-      #
-      # Used to update Data Models pages with the most recent schema change date.
-      #
-      # @example
-      #   mapper = MigrationMapper.new
-      #   changes = mapper.latest_changes(migration_units)
-      #   # => { "users" => "2026-02-20T10:00:00Z", "posts" => "2026-01-15T09:00:00Z" }
-      #
-      class MigrationMapper
-        # Compute the latest migration date for each affected table.
-        #
-        # @param migration_units [Array<Hash>] Parsed migration ExtractedUnit JSONs
-        # @return [Hash<String, String>] Table name to latest extracted_at timestamp
-        def latest_changes(migration_units)
-          migration_units.each_with_object({}) do |unit, changes|
-            extracted_at = unit['extracted_at']
-            next unless extracted_at
-
-            tables = (unit['metadata'] || {})['tables_affected'] || []
-            tables.each { |table| update_latest(changes, table, extracted_at) }
-          end
-        end
-
-        private
-
-        # @return [void]
-        def update_latest(changes, table, extracted_at)
-          changes[table] = extracted_at if changes[table].nil? || extracted_at > changes[table]
-        end
-      end
-    end
-  end
-end

data/lib/codebase_index/notion/mappers/model_mapper.rb

@@ -1,161 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'shared'
-
-module CodebaseIndex
-  module Notion
-    module Mappers
-      # Maps a model ExtractedUnit to Notion page properties for the Data Models database.
-      #
-      # Transforms model metadata (associations, validations, callbacks, scopes, git data)
-      # into Notion API property format for the Data Models database.
-      #
-      # @example
-      #   mapper = ModelMapper.new
-      #   properties = mapper.map(unit_data)
-      #   client.create_page(database_id: db_id, properties: properties)
-      #
-      class ModelMapper
-        include Shared
-
-        # Map a model unit to Notion Data Models page properties.
-        #
-        # @param unit_data [Hash] Parsed model ExtractedUnit JSON
-        # @return [Hash] Notion page properties hash
-        def map(unit_data)
-          metadata = unit_data['metadata'] || {}
-          properties = build_text_properties(unit_data, metadata)
-          properties['Column Count'] = { number: column_count(metadata) }
-          add_git_properties(properties, metadata['git'] || {})
-          properties
-        end
-
-        private
-
-        # @return [Hash] Text-based Notion properties
-        def build_text_properties(unit_data, metadata)
-          {
-            'Table Name' => title_property(table_name(unit_data, metadata)),
-            'Model Name' => rich_text_property(unit_data['identifier']),
-            'Description' => rich_text_property(extract_description(unit_data['source_code'])),
-            'Associations' => rich_text_property(format_associations(metadata['associations'])),
-            'Validations' => rich_text_property(format_validations(metadata['validations'])),
-            'Callbacks' => rich_text_property(format_callbacks(metadata['callbacks'])),
-            'Scopes' => rich_text_property(format_scopes(metadata['scopes'])),
-            'File Path' => rich_text_property(unit_data['file_path'] || ''),
-            'Dependencies' => rich_text_property(format_dependencies(unit_data['dependencies']))
-          }
-        end
-
-        # @return [void]
-        def add_git_properties(properties, git)
-          properties['Last Modified'] = { date: { start: git['last_modified'] } } if git['last_modified']
-          properties['Change Frequency'] = { select: { name: git['change_frequency'] } } if git['change_frequency']
-        end
-
-        # @return [String]
-        def table_name(unit_data, metadata)
-          return metadata['table_name'] if metadata['table_name']
-
-          identifier = unit_data['identifier'] || ''
-          "#{identifier.split('::').last.to_s.gsub(/([a-z])([A-Z])/, '\1_\2').downcase}s"
-        end
-
-        # @return [Integer]
-        def column_count(metadata)
-          metadata['column_count'] || (metadata['columns'] || []).size
-        end
-
-        # @return [String]
-        def extract_description(source_code)
-          return '' unless source_code
-
-          comment_lines = []
-          source_code.lines.each do |line|
-            stripped = line.strip
-            if stripped.start_with?('#')
-              comment_lines << stripped.sub(/^#\s?/, '')
-            elsif comment_lines.any?
-              break
-            end
-          end
-
-          comment_lines.any? ? comment_lines.join(' ').strip : ''
-        end
-
-        # @return [String]
-        def format_associations(associations)
-          format_list(associations) { |items| items.map { |a| format_single_association(a) }.join("\n") }
-        end
-
-        # @return [String]
-        def format_single_association(assoc)
-          parts = ["#{assoc['type']} :#{assoc['name']}"]
-          parts << "through: :#{assoc['through']}" if assoc['through']
-          parts << "class_name: '#{assoc['class_name']}'" if assoc['class_name']
-          parts << "foreign_key: :#{assoc['foreign_key']}" if assoc['foreign_key']
-          parts.join(', ')
-        end
-
-        # @return [String]
-        def format_validations(validations)
-          format_list(validations) do |items|
-            items.group_by { |v| v['attribute'] }.map do |attr, vals|
-              "#{attr}: #{vals.map { |v| v['type'] }.join(', ')}"
-            end.join("\n")
-          end
-        end
-
-        # @return [String]
-        def format_callbacks(callbacks)
-          format_list(callbacks) { |items| items.map { |callback| format_single_callback(callback) }.join("\n") }
-        end
-
-        # @return [String]
-        def format_single_callback(callback)
-          parts = ["#{callback['type']}: #{callback['filter']}"]
-          effects = callback_side_effects(callback['side_effects'])
-          parts << "(#{effects.join('; ')})" if effects.any?
-          parts.join(' ')
-        end
-
-        # @return [Array<String>]
-        def callback_side_effects(side_effects)
-          return [] unless side_effects
-
-          effects = []
-          jobs = side_effects['jobs_enqueued']
-          effects << "enqueues #{jobs.join(', ')}" if jobs&.any?
-          services = side_effects['services_called']
-          effects << "calls #{services.join(', ')}" if services&.any?
-          effects
-        end
-
-        # @return [String]
-        def format_scopes(scopes)
-          format_list(scopes) { |items| items.map { |s| s['name'] }.join(', ') }
-        end
-
-        # @return [String]
-        def format_dependencies(dependencies)
-          format_list(dependencies) { |items| items.map { |dep| "#{dep['target']} (via #{dep['via']})" }.join(', ') }
-        end
-
-        # @return [Hash]
-        def title_property(text)
-          { title: [{ text: { content: text } }] }
-        end
-
-        # Return 'None' for nil/empty lists; otherwise yield items to a formatting block.
-        #
-        # @param items [Array, nil]
-        # @return [String]
-        def format_list(items)
-          return 'None' if items.nil? || items.empty?
-
-          yield items
-        end
-      end
-    end
-  end
-end

data/lib/codebase_index/notion/mappers/shared.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-module CodebaseIndex
-  module Notion
-    module Mappers
-      # Shared helpers for Notion mapper classes.
-      module Shared
-        MAX_RICH_TEXT_LENGTH = 2000
-
-        # Build a Notion rich_text property, truncating to API limits.
-        #
-        # @param text [String]
-        # @return [Hash]
-        def rich_text_property(text)
-          content = text.to_s
-          content = "#{content[0...1997]}..." if content.length > MAX_RICH_TEXT_LENGTH
-          { rich_text: [{ text: { content: content } }] }
-        end
-      end
-    end
-  end
-end

data/lib/codebase_index/notion/rate_limiter.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-module CodebaseIndex
-  module Notion
-    # Thread-safe rate limiter for Notion API (3 requests/second default).
-    #
-    # Enforces a minimum interval between API calls by sleeping when necessary.
-    # Uses a Mutex to ensure thread safety when called from concurrent contexts.
-    #
-    # @example
-    #   limiter = RateLimiter.new(requests_per_second: 3)
-    #   limiter.throttle { client.create_page(...) }
-    #   limiter.throttle { client.update_page(...) }
-    #
-    class RateLimiter
-      # @param requests_per_second [Numeric] Maximum requests per second (default: 3)
-      # @raise [ArgumentError] if requests_per_second is not positive
-      def initialize(requests_per_second: 3)
-        unless requests_per_second.is_a?(Numeric) && requests_per_second.positive?
-          raise ArgumentError, "requests_per_second must be positive, got #{requests_per_second.inspect}"
-        end
-
-        @min_interval = 1.0 / requests_per_second
-        @last_request_at = nil
-        @mutex = Mutex.new
-      end
-
-      # Execute a block after enforcing the rate limit.
-      #
-      # Sleeps if the minimum interval since the last request hasn't elapsed.
-      # Thread-safe — only one request proceeds at a time.
-      #
-      # @yield The block to execute after rate limiting
-      # @return [Object] The block's return value
-      # @raise [ArgumentError] if no block is given
-      def throttle
-        raise ArgumentError, 'block required' unless block_given?
-
-        @mutex.synchronize do
-          wait_for_interval
-          @last_request_at = monotonic_now
-        end
-
-        yield
-      end
-
-      private
-
-      # Sleep if minimum interval hasn't elapsed since last request.
-      #
-      # @return [void]
-      def wait_for_interval
-        return unless @last_request_at
-
-        elapsed = monotonic_now - @last_request_at
-        remaining = @min_interval - elapsed
-        sleep(remaining) if remaining.positive?
-      end
-
-      # Monotonic clock for accurate interval measurement.
-      #
-      # @return [Float] Current monotonic time in seconds
-      def monotonic_now
-        Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      end
-    end
-  end
-end

data/lib/codebase_index/observability/health_check.rb

@@ -1,79 +0,0 @@
-# frozen_string_literal: true
-
-module CodebaseIndex
-  module Observability
-    # Probes configured components and reports overall system health.
-    #
-    # Checks vector store, metadata store, and embedding provider by calling
-    # lightweight operations on each. Components that are nil are reported
-    # as :not_configured and do not affect the overall healthy? status.
-    #
-    # @example
-    #   check = HealthCheck.new(
-    #     vector_store: vector_store,
-    #     metadata_store: metadata_store,
-    #     embedding_provider: provider
-    #   )
-    #   status = check.run
-    #   status.healthy?    # => true
-    #   status.components  # => { vector_store: :ok, metadata_store: :ok, embedding_provider: :ok }
-    #
-    class HealthCheck
-      # Value object representing the result of a health check.
-      HealthStatus = Struct.new(:healthy?, :components, keyword_init: true)
-
-      # @param vector_store [Object, nil] Vector store adapter (must respond to #count)
-      # @param metadata_store [Object, nil] Metadata store adapter (must respond to #count)
-      # @param embedding_provider [Object, nil] Embedding provider (must respond to #embed)
-      def initialize(vector_store: nil, metadata_store: nil, embedding_provider: nil)
-        @vector_store = vector_store
-        @metadata_store = metadata_store
-        @embedding_provider = embedding_provider
-      end
-
-      # Run health probes on all configured components.
-      #
-      # @return [HealthStatus] Result with healthy? flag and per-component status
-      def run
-        components = {
-          vector_store: probe_store(@vector_store),
-          metadata_store: probe_store(@metadata_store),
-          embedding_provider: probe_provider(@embedding_provider)
-        }
-
-        all_healthy = components.values.all? { |status| %i[ok not_configured].include?(status) }
-
-        HealthStatus.new(healthy?: all_healthy, components: components)
-      end
-
-      private
-
-      # Probe a store component by calling #count.
-      #
-      # @param store [Object, nil] Store adapter
-      # @return [Symbol] :ok, :error, or :not_configured
-      def probe_store(store)
-        return :not_configured if store.nil?
-
-        store.count
-        :ok
-      rescue StandardError
-        :error
-      end
-
-      # Probe an embedding provider by checking its capabilities without making network calls.
-      #
-      # @param provider [Object, nil] Embedding provider
-      # @return [Symbol] :ok, :error, or :not_configured
-      def probe_provider(provider)
-        return :not_configured if provider.nil?
-
-        if provider.respond_to?(:embed) && provider.respond_to?(:dimensions)
-          :ok
-        else
-          :error
-        end
-      end
-    end
-  end
-end

data/lib/codebase_index/observability/instrumentation.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-module CodebaseIndex
-  module Observability
-    # Lightweight instrumentation wrapper that delegates to ActiveSupport::Notifications
-    # when available, and falls back to a simple yield otherwise.
-    #
-    # @example
-    #   Instrumentation.instrument('codebase_index.extraction', unit: 'User') do
-    #     extract_unit(user_model)
-    #   end
-    #
-    module Instrumentation
-      module_function
-
-      # Instrument a block of code with an event name and payload.
-      #
-      # Delegates to ActiveSupport::Notifications.instrument when available.
-      # Otherwise, yields the block directly.
-      #
-      # @param event [String] Event name (e.g., 'codebase_index.extraction')
-      # @param payload [Hash] Additional data to include with the event
-      # @yield [payload] The block to instrument
-      # @return [Object] The return value of the block
-      def instrument(event, payload = {}, &block)
-        if defined?(ActiveSupport::Notifications)
-          ActiveSupport::Notifications.instrument(event, payload, &block)
-        elsif block
-          yield payload
-        end
-      end
-    end
-  end
-end

data/lib/codebase_index/observability/structured_logger.rb

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-require 'time'
-
-module CodebaseIndex
-  module Observability
-    # Structured JSON logger that writes one JSON object per line.
-    #
-    # Each log entry includes a timestamp, level, event name, and any
-    # additional data passed as keyword arguments.
-    #
-    # @example
-    #   logger = StructuredLogger.new(output: $stderr)
-    #   logger.info('extraction.complete', units: 42, duration_ms: 1200)
-    #   # => {"timestamp":"2026-02-15T12:00:00Z","level":"info",
-    #   #     "event":"extraction.complete","units":42,"duration_ms":1200}
-    #
-    class StructuredLogger
-      # @param output [IO] Output stream (default: $stderr)
-      def initialize(output: $stderr)
-        @output = output
-      end
-
-      # @!method info(event, **data)
-      #   Log at info level.
-      #   @param event [String] Event name
-      #   @param data [Hash] Additional structured data
-      # @!method warn(event, **data)
-      #   Log at warn level.
-      # @!method error(event, **data)
-      #   Log at error level.
-      # @!method debug(event, **data)
-      #   Log at debug level.
-      %w[info warn error debug].each do |level|
-        define_method(level) { |event, **data| write_entry(level, event, data) }
-      end
-
-      private
-
-      # Write a single JSON log line.
-      #
-      # @param level [String] Log level
-      # @param event [String] Event name
-      # @param data [Hash] Additional data
-      def write_entry(level, event, data)
-        entry = {
-          timestamp: Time.now.utc.iso8601,
-          level: level,
-          event: event
-        }.merge(data)
-
-        @output.puts(JSON.generate(entry))
-      end
-    end
-  end
-end

data/lib/codebase_index/operator/error_escalator.rb

@@ -1,81 +0,0 @@
-# frozen_string_literal: true
-
-module CodebaseIndex
-  module Operator
-    # Classifies pipeline errors by severity and suggests remediation.
-    #
-    # @example
-    #   escalator = ErrorEscalator.new
-    #   result = escalator.classify(Timeout::Error.new("connection timed out"))
-    #   result[:severity]     # => :transient
-    #   result[:remediation]  # => "Retry after a short delay"
-    #
-    class ErrorEscalator
-      TRANSIENT_PATTERNS = [
-        { class_pattern: /Timeout|ETIMEDOUT/, category: 'timeout', remediation: 'Retry after a short delay' },
-        { class_pattern: /Net::/, category: 'network', remediation: 'Check network connectivity and retry' },
-        { class_pattern: /RateLimited|429/, category: 'rate_limit',
-          remediation: 'Back off and retry with exponential delay' },
-        { class_pattern: /CircuitOpenError/, category: 'circuit_open',
-          remediation: 'Wait for circuit breaker reset timeout' },
-        { class_pattern: /ConnectionPool|Busy/, category: 'resource_contention',
-          remediation: 'Wait for resources to free up' }
-      ].freeze
-
-      PERMANENT_PATTERNS = [
-        { class_pattern: /NameError|NoMethodError/, category: 'code_error',
-          remediation: 'Fix the code error and re-extract' },
-        { class_pattern: /Errno::ENOENT|FileNotFoundError/, category: 'missing_file',
-          remediation: 'Verify file paths and re-run extraction' },
-        { class_pattern: /JSON::ParserError/, category: 'corrupt_data',
-          remediation: 'Clean index and re-extract' },
-        { class_pattern: /ConfigurationError/, category: 'configuration',
-          remediation: 'Review CodebaseIndex configuration' },
-        { class_pattern: /ExtractionError/, category: 'extraction_failure',
-          remediation: 'Check extraction logs for specific failure details' }
-      ].freeze
-
-      # Classify an error by severity and suggest remediation.
-      #
-      # @param error [StandardError] The error to classify
-      # @return [Hash] :severity (:transient or :permanent), :category, :remediation, :error_class, :message
-      def classify(error)
-        error_string = "#{error.class} #{error.message}"
-
-        match = find_match(error_string, TRANSIENT_PATTERNS, :transient) ||
-                find_match(error_string, PERMANENT_PATTERNS, :permanent)
-
-        if match
-          match.merge(error_class: error.class.name, message: error.message)
-        else
-          {
-            severity: :unknown,
-            category: 'unclassified',
-            remediation: 'Investigate error details and check logs',
-            error_class: error.class.name,
-            message: error.message
-          }
-        end
-      end
-
-      private
-
-      # @param error_string [String]
-      # @param patterns [Array<Hash>]
-      # @param severity [Symbol]
-      # @return [Hash, nil]
-      def find_match(error_string, patterns, severity)
-        patterns.each do |pattern|
-          next unless error_string.match?(pattern[:class_pattern])
-
-          return {
-            severity: severity,
-            category: pattern[:category],
-            remediation: pattern[:remediation]
-          }
-        end
-        nil
-      end
-    end
-  end
-end

data/lib/codebase_index/operator/pipeline_guard.rb

@@ -1,92 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-require 'fileutils'
-require 'time'
-
-module CodebaseIndex
-  module Operator
-    # Rate limiter for pipeline operations using file-based state.
-    #
-    # Enforces a cooldown between consecutive runs of the same operation
-    # to prevent accidental repeated extraction or embedding.
-    #
-    # @example
-    #   guard = PipelineGuard.new(state_dir: '/tmp', cooldown: 300)
-    #   if guard.allow?(:extraction)
-    #     run_extraction
-    #     guard.record!(:extraction)
-    #   end
-    #
-    class PipelineGuard
-      # @param state_dir [String] Directory for persisting state
-      # @param cooldown [Integer] Minimum seconds between runs
-      def initialize(state_dir:, cooldown: 300)
-        @state_dir = state_dir
-        @cooldown = cooldown
-        @state_path = File.join(state_dir, 'pipeline_guard.json')
-      end
-
-      # Check if an operation is allowed (cooldown elapsed).
-      #
-      # @param operation [Symbol, String] Operation name
-      # @return [Boolean]
-      def allow?(operation)
-        last = last_run(operation)
-        return true if last.nil?
-
-        (Time.now - last) >= @cooldown
-      end
-
-      # Record that an operation has just run.
-      #
-      # @param operation [Symbol, String] Operation name
-      # @return [void]
-      def record!(operation)
-        FileUtils.mkdir_p(@state_dir)
-        File.open(@state_path, File::RDWR | File::CREAT) do |f|
-          f.flock(File::LOCK_EX)
-          content = f.read
-          state = if content.empty?
-                    {}
-                  else
-                    begin
-                      JSON.parse(content)
-                    rescue StandardError
-                      {}
-                    end
-                  end
-          state[operation.to_s] = Time.now.iso8601
-          f.rewind
-          f.write(JSON.generate(state))
-          f.truncate(f.pos)
-        end
-      end
-
-      # Get the last run time for an operation.
-      #
-      # @param operation [Symbol, String] Operation name
-      # @return [Time, nil]
-      def last_run(operation)
-        state = read_state
-        timestamp = state[operation.to_s]
-        return nil if timestamp.nil?
-
-        Time.parse(timestamp)
-      rescue ArgumentError
-        nil
-      end
-
-      private
-
-      # @return [Hash]
-      def read_state
-        return {} unless File.exist?(@state_path)
-
-        JSON.parse(File.read(@state_path))
-      rescue JSON::ParserError
-        {}
-      end
-    end
-  end
-end