codebase_index 0.1.0

data/lib/codebase_index/mcp/tool_response_renderer.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module CodebaseIndex
+  module MCP
+    # Base class for rendering MCP tool responses in different output formats.
+    #
+    # Subclasses implement tool-specific render methods (render_lookup, render_search, etc.)
+    # and a render_default fallback. The dispatch uses convention: tool name maps to method name.
+    #
+    # @example
+    #   renderer = ToolResponseRenderer.for(:markdown)
+    #   renderer.render(:lookup, unit_data)
+    #
+    class ToolResponseRenderer
+      VALID_FORMATS = %i[claude markdown plain json].freeze
+
+      # Factory method to build the appropriate renderer for a format.
+      #
+      # @param format [Symbol] One of :claude, :markdown, :plain, :json
+      # @return [ToolResponseRenderer] A renderer instance
+      # @raise [ArgumentError] if format is unknown
+      def self.for(format)
+        require_relative 'renderers/markdown_renderer'
+        require_relative 'renderers/claude_renderer'
+        require_relative 'renderers/plain_renderer'
+        require_relative 'renderers/json_renderer'
+
+        case format
+        when :claude   then Renderers::ClaudeRenderer.new
+        when :markdown then Renderers::MarkdownRenderer.new
+        when :plain    then Renderers::PlainRenderer.new
+        when :json     then Renderers::JsonRenderer.new
+        else raise ArgumentError, "Unknown format: #{format.inspect}. Valid: #{VALID_FORMATS.inspect}"
+        end
+      end
+
+      # Render a tool response. Dispatches to render_<tool_name> if defined,
+      # otherwise falls back to render_default.
+      #
+      # @param tool_name [Symbol, String] The tool name
+      # @param data [Object] The tool result data
+      # @param opts [Hash] Additional rendering options
+      # @return [String] Rendered response text
+      def render(tool_name, data, **opts)
+        method_name = :"render_#{tool_name}"
+        if respond_to?(method_name, true)
+          send(method_name, data, **opts)
+        else
+          render_default(data)
+        end
+      end
+
+      # Default rendering — subclasses must implement.
+      #
+      # @param data [Object] The data to render
+      # @return [String] Rendered text
+      def render_default(data)
+        raise NotImplementedError, "#{self.class}#render_default must be implemented"
+      end
+    end
+  end
+end

data/lib/codebase_index/model_name_cache.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module CodebaseIndex
+  # Caches ActiveRecord model names and builds a precompiled regex
+  # for scanning source code for model references.
+  #
+  # Avoids O(n*m) per-extractor iteration of ActiveRecord::Base.descendants.
+  # Invalidated per extraction run (call .reset! before a new run).
+  #
+  # @example
+  #   CodebaseIndex::ModelNameCache.model_names
+  #   # => ["User", "Order", "Product", ...]
+  #
+  #   CodebaseIndex::ModelNameCache.model_names_regex
+  #   # => /\b(?:User|Order|Product|...)\b/
+  #
+  module ModelNameCache
+    class << self
+      # @return [Array<String>] All named AR model descendant names
+      def model_names
+        @model_names ||= compute_model_names
+      end
+
+      # @return [Regexp] Precompiled regex matching any model name as a whole word
+      def model_names_regex
+        @model_names_regex ||= build_regex
+      end
+
+      # Clear cache (call at the start of each extraction run)
+      def reset!
+        @model_names = nil
+        @model_names_regex = nil
+      end
+
+      private
+
+      def compute_model_names
+        return [] unless defined?(ActiveRecord::Base)
+
+        ActiveRecord::Base.descendants.filter_map(&:name).uniq
+      end
+
+      def build_regex
+        names = model_names
+        return /(?!)/ if names.empty? # never-matching regex
+
+        /\b(?:#{names.map { |n| Regexp.escape(n) }.join('|')})\b/
+      end
+    end
+  end
+end

data/lib/codebase_index/notion/client.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+require 'codebase_index'
+require_relative 'rate_limiter'
+
+module CodebaseIndex
+  module Notion
+    # Thin wrapper around the Notion REST API (v2022-06-28).
+    #
+    # Uses Net::HTTP (stdlib) for zero external dependencies. All requests are
+    # throttled through a {RateLimiter} to respect Notion's 3 req/sec limit.
+    #
+    # @example
+    #   client = Client.new(api_token: "secret_...")
+    #   client.create_page(database_id: "db-uuid", properties: { ... })
+    #   client.query_database(database_id: "db-uuid", filter: { ... })
+    #
+    class Client # rubocop:disable Metrics/ClassLength
+      BASE_URL = 'https://api.notion.com/v1'
+      NOTION_VERSION = '2022-06-28'
+      MAX_RETRIES = 3
+      DEFAULT_TIMEOUT = 30
+
+      # @param api_token [String] Notion integration API token
+      # @param rate_limiter [RateLimiter] Rate limiter instance (default: 3 req/sec)
+      # @raise [ArgumentError] if api_token is nil or empty
+      def initialize(api_token:, rate_limiter: RateLimiter.new)
+        raise ArgumentError, 'api_token is required' if api_token.nil? || api_token.to_s.empty?
+
+        @api_token = api_token
+        @rate_limiter = rate_limiter
+      end
+
+      # Create a page in a Notion database.
+      #
+      # @param database_id [String] Target database UUID
+      # @param properties [Hash] Page properties in Notion API format
+      # @param children [Array<Hash>] Optional page content blocks
+      # @return [Hash] Created page data
+      def create_page(database_id:, properties:, children: [])
+        body = {
+          parent: { database_id: database_id },
+          properties: properties
+        }
+        body[:children] = children if children.any?
+
+        request(:post, 'pages', body)
+      end
+
+      # Update an existing page's properties.
+      #
+      # @param page_id [String] Page UUID to update
+      # @param properties [Hash] Properties to update
+      # @return [Hash] Updated page data
+      def update_page(page_id:, properties:)
+        request(:patch, "pages/#{page_id}", { properties: properties })
+      end
+
+      # Query a database with optional filter and sort.
+      #
+      # @param database_id [String] Database UUID
+      # @param filter [Hash, nil] Notion filter object
+      # @param sorts [Array<Hash>, nil] Notion sort objects
+      # @return [Hash] Query results with 'results', 'has_more', 'next_cursor'
+      def query_database(database_id:, filter: nil, sorts: nil)
+        body = {}
+        body[:filter] = filter if filter
+        body[:sorts] = sorts if sorts
+
+        request(:post, "databases/#{database_id}/query", body)
+      end
+
+      # Query all pages from a database, auto-paginating.
+      #
+      # @param database_id [String] Database UUID
+      # @param filter [Hash, nil] Notion filter object
+      # @return [Array<Hash>] All matching pages
+      def query_all(database_id:, filter: nil)
+        all_results = []
+        cursor = nil
+
+        loop do
+          body = {}
+          body[:filter] = filter if filter
+          body[:start_cursor] = cursor if cursor
+
+          response = request(:post, "databases/#{database_id}/query", body)
+          all_results.concat(response['results'] || [])
+
+          break unless response['has_more']
+
+          cursor = response['next_cursor']
+        end
+
+        all_results
+      end
+
+      # Find a page by its title property value.
+      #
+      # @param database_id [String] Database UUID
+      # @param title [String] Title text to search for
+      # @return [Hash, nil] First matching page or nil
+      def find_page_by_title(database_id:, title:)
+        response = query_database(
+          database_id: database_id,
+          filter: {
+            property: 'title',
+            title: { equals: title }
+          }
+        )
+
+        results = response['results'] || []
+        results.first
+      end
+
+      private
+
+      # Execute an HTTP request against the Notion API.
+      #
+      # @param method [Symbol] HTTP method (:post, :patch, :get)
+      # @param path [String] API path (appended to BASE_URL)
+      # @param body [Hash, nil] Request body
+      # @return [Hash] Parsed JSON response
+      # @raise [CodebaseIndex::Error] on non-success responses (after retries for 429)
+      def request(method, path, body = nil)
+        retries = 0
+
+        loop do
+          response = execute_with_retry(method, path, body, retries)
+
+          return JSON.parse(response.body) if response.is_a?(Net::HTTPSuccess)
+
+          if response.code == '429' && retries < MAX_RETRIES
+            retries += 1
+            wait_time = (response['Retry-After'] || retries).to_f
+            sleep(wait_time)
+            next
+          end
+
+          raise_api_error(response)
+        end
+      end
+
+      # Execute HTTP with rate limiting and network error retry.
+      #
+      # @return [Net::HTTPResponse]
+      # @raise [CodebaseIndex::Error] on persistent network failures
+      def execute_with_retry(method, path, body, _retries)
+        attempts = 0
+        begin
+          @rate_limiter.throttle { execute_http(method, path, body) }
+        rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET, Errno::ECONNREFUSED => e
+          attempts += 1
+          raise CodebaseIndex::Error, "Network error after #{attempts} retries: #{e.message}" if attempts >= MAX_RETRIES
+
+          sleep(2**attempts)
+          retry
+        end
+      end
+
+      # Raise a descriptive error from a non-success Notion response.
+      #
+      # @raise [CodebaseIndex::Error]
+      def raise_api_error(response)
+        parsed = begin
+          JSON.parse(response.body)
+        rescue JSON::ParserError
+          { 'message' => "Unparseable response body: #{response.body&.slice(0, 200)}" }
+        end
+        message = parsed['message'] || 'Unknown error'
+        raise CodebaseIndex::Error, "Notion API error #{response.code}: #{message}"
+      end
+
+      # Perform the raw HTTP request.
+      #
+      # @param method [Symbol] HTTP method
+      # @param path [String] API path
+      # @param body [Hash, nil] Request body
+      # @return [Net::HTTPResponse]
+      def execute_http(method, path, body)
+        uri = URI("#{BASE_URL}/#{path}")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.open_timeout = DEFAULT_TIMEOUT
+        http.read_timeout = DEFAULT_TIMEOUT
+
+        req = build_request(method, uri, body)
+        http.request(req)
+      end
+
+      # Build an HTTP request object with headers.
+      #
+      # @param method [Symbol] HTTP method
+      # @param uri [URI] Full request URI
+      # @param body [Hash, nil] Request body
+      # @return [Net::HTTPRequest]
+      def build_request(method, uri, body)
+        req = case method
+              when :post then Net::HTTP::Post.new(uri)
+              when :patch then Net::HTTP::Patch.new(uri)
+              when :get then Net::HTTP::Get.new(uri)
+              else raise ArgumentError, "Unsupported HTTP method: #{method}"
+              end
+
+        req['Authorization'] = "Bearer #{@api_token}"
+        req['Notion-Version'] = NOTION_VERSION
+        req['Content-Type'] = 'application/json'
+        req.body = JSON.generate(body) if body
+
+        req
+      end
+    end
+  end
+end

data/lib/codebase_index/notion/exporter.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require 'codebase_index'
+require_relative 'client'
+require_relative 'mapper'
+require_relative 'rate_limiter'
+
+module CodebaseIndex
+  module Notion
+    # Orchestrates syncing CodebaseIndex extraction data to Notion databases.
+    #
+    # Reads extraction output from disk via IndexReader, maps model and column data
+    # to Notion page properties, and pushes via the Notion API. All syncs are idempotent —
+    # existing pages are updated, new pages are created.
+    #
+    # @example
+    #   exporter = Exporter.new(index_dir: "tmp/codebase_index")
+    #   stats = exporter.sync_all
+    #   # => { data_models: 10, columns: 45, errors: [] }
+    #
+    class Exporter # rubocop:disable Metrics/ClassLength
+      # @param index_dir [String] Path to extraction output directory
+      # @param config [Configuration] CodebaseIndex configuration (default: global config)
+      # @param client [Client, nil] Notion API client (auto-created from config if nil)
+      # @param reader [Object, nil] IndexReader instance (auto-created from index_dir if nil)
+      # @raise [ConfigurationError] if notion_api_token is not configured
+      def initialize(index_dir:, config: CodebaseIndex.configuration, client: nil, reader: nil)
+        api_token = config.notion_api_token
+        raise ConfigurationError, 'notion_api_token is required for Notion export' unless api_token
+
+        @database_ids = config.notion_database_ids || {}
+        @client = client || Client.new(api_token: api_token)
+        @reader = reader || build_reader(index_dir)
+        @page_id_cache = {}
+      end
+
+      # Sync all configured databases. Idempotent — safe to re-run.
+      #
+      # @return [Hash] { data_models: Integer, columns: Integer, errors: Array<String> }
+      def sync_all
+        model_stats = @database_ids[:data_models] ? sync_data_models : empty_stats
+        column_stats = @database_ids[:columns] && @database_ids[:data_models] ? sync_columns : empty_stats
+
+        all_errors = model_stats[:errors] + column_stats[:errors]
+
+        {
+          data_models: model_stats[:synced],
+          columns: column_stats[:synced],
+          errors: cap_errors(all_errors)
+        }
+      end
+
+      # Sync model units to the Data Models Notion database.
+      #
+      # @return [Hash] { synced: Integer, errors: Array<String> }
+      def sync_data_models
+        database_id = @database_ids[:data_models]
+        return empty_stats unless database_id
+
+        migration_dates = load_migration_dates
+        sync_units('model', database_id, 'Table Name') do |unit_data|
+          properties = Mappers::ModelMapper.new.map(unit_data)
+          enrich_with_migration_date(properties, migration_dates)
+          properties
+        end
+      end
+
+      # Sync column data to the Columns Notion database.
+      #
+      # @return [Hash] { synced: Integer, errors: Array<String> }
+      def sync_columns
+        database_id = @database_ids[:columns]
+        return empty_stats unless database_id
+
+        synced = 0
+        errors = []
+
+        each_model_unit do |entry, unit_data|
+          synced_count, unit_errors = sync_model_columns(entry, unit_data, database_id)
+          synced += synced_count
+          errors.concat(unit_errors)
+        end
+
+        { synced: synced, errors: errors }
+      end
+
+      MAX_ERRORS = 100
+
+      private
+
+      # Sync all units of a type, yielding each for property mapping.
+      #
+      # @param type [String] Unit type to list
+      # @param database_id [String] Notion database UUID
+      # @param title_property [String] Name of the title property
+      # @yield [Hash] Unit data hash, expects Notion properties hash back
+      # @return [Hash] { synced: Integer, errors: Array<String> }
+      def sync_units(type, database_id, title_property)
+        synced = 0
+        errors = []
+
+        @reader.list_units(type: type).each do |entry|
+          unit_data = @reader.find_unit(entry['identifier'])
+          next unless unit_data
+
+          begin
+            properties = yield(unit_data)
+            title_value = extract_title_text(properties[title_property])
+            page_id = upsert_page(database_id: database_id, title_value: title_value, properties: properties)
+            @page_id_cache[entry['identifier']] = page_id
+            synced += 1
+          rescue StandardError => e
+            errors << "#{entry['identifier']}: #{e.message}"
+          end
+        end
+
+        { synced: synced, errors: errors }
+      end
+
+      # Iterate over loaded model units.
+      #
+      # @yield [Hash, Hash] Index entry and full unit data
+      def each_model_unit
+        @reader.list_units(type: 'model').each do |entry|
+          unit_data = @reader.find_unit(entry['identifier'])
+          next unless unit_data
+
+          yield(entry, unit_data)
+        end
+      end
+
+      # Sync columns for a single model.
+      #
+      # @return [Array(Integer, Array<String>)] Count of synced columns and errors
+      def sync_model_columns(entry, unit_data, database_id)
+        parent_page_id = @page_id_cache[entry['identifier']]
+        columns = unit_data.dig('metadata', 'columns') || []
+        validations = unit_data.dig('metadata', 'validations') || []
+        mapper = Mappers::ColumnMapper.new
+        synced = 0
+        errors = []
+
+        columns.each do |column|
+          properties = mapper.map(column, model_identifier: entry['identifier'],
+                                          validations: validations, parent_page_id: parent_page_id)
+          upsert_page(database_id: database_id, title_value: column['name'], properties: properties)
+          synced += 1
+        rescue StandardError => e
+          errors << "#{entry['identifier']}.#{column['name']}: #{e.message}"
+        end
+
+        [synced, errors]
+      end
+
+      # Enrich model properties with migration date if available.
+      #
+      # @param properties [Hash] Notion properties hash (mutated)
+      # @param migration_dates [Hash] { table_name => date_string }
+      def enrich_with_migration_date(properties, migration_dates)
+        table_name = extract_title_text(properties['Table Name'])
+        return unless migration_dates[table_name]
+
+        properties['Last Schema Change'] = { date: { start: migration_dates[table_name] } }
+      end
+
+      # Load migration units and compute latest change dates per table.
+      #
+      # @return [Hash<String, String>] { table_name => latest_date }
+      def load_migration_dates
+        mapper = Mappers::MigrationMapper.new
+        units = @reader.list_units(type: 'migration').filter_map { |e| @reader.find_unit(e['identifier']) }
+        mapper.latest_changes(units)
+      rescue StandardError
+        {}
+      end
+
+      # Upsert a Notion page: find by title, update if exists, create if not.
+      #
+      # @return [String] Notion page ID
+      def upsert_page(database_id:, title_value:, properties:)
+        existing = @client.find_page_by_title(database_id: database_id, title: title_value)
+
+        if existing
+          @client.update_page(page_id: existing['id'], properties: properties)
+          existing['id']
+        else
+          result = @client.create_page(database_id: database_id, properties: properties)
+          result['id']
+        end
+      end
+
+      # @return [Hash]
+      def empty_stats
+        { synced: 0, errors: [] }
+      end
+
+      # Cap errors to prevent unbounded memory growth.
+      #
+      # @param errors [Array<String>]
+      # @return [Array<String>]
+      def cap_errors(errors)
+        return errors if errors.size <= MAX_ERRORS
+
+        errors.first(MAX_ERRORS) + ["... and #{errors.size - MAX_ERRORS} more errors"]
+      end
+
+      # @return [String]
+      def extract_title_text(title_prop)
+        title_prop&.dig(:title, 0, :text, :content) || ''
+      end
+
+      # @return [Object] IndexReader
+      def build_reader(index_dir)
+        require_relative '../mcp/index_reader'
+        CodebaseIndex::MCP::IndexReader.new(index_dir)
+      end
+    end
+  end
+end

data/lib/codebase_index/notion/mapper.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'mappers/model_mapper'
+require_relative 'mappers/column_mapper'
+require_relative 'mappers/migration_mapper'
+
+module CodebaseIndex
+  module Notion
+    # Dispatcher for Notion mappers. Returns the appropriate mapper for a unit type.
+    #
+    # @example
+    #   mapper = Mapper.for("model")
+    #   properties = mapper.map(unit_data)
+    #
+    class Mapper
+      REGISTRY = {
+        'model' => Mappers::ModelMapper,
+        'column' => Mappers::ColumnMapper,
+        'migration' => Mappers::MigrationMapper
+      }.freeze
+
+      # Get a mapper instance for a unit type.
+      #
+      # @param type [String] Unit type name (e.g. "model", "column", "migration")
+      # @return [Object, nil] Mapper instance or nil if type is not supported
+      def self.for(type)
+        klass = REGISTRY[type]
+        klass&.new
+      end
+
+      # List all supported unit types.
+      #
+      # @return [Array<String>]
+      def self.supported_types
+        REGISTRY.keys
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module CodebaseIndex
+  module Notion
+    module Mappers
+      # Maps individual column metadata to Notion page properties for the Columns database.
+      #
+      # Each column from a model's metadata becomes a separate Notion page, optionally
+      # linked to its parent Data Models page via a relation property.
+      #
+      # @example
+      #   mapper = ColumnMapper.new
+      #   properties = mapper.map(column, model_identifier: "User", validations: [...], parent_page_id: "page-123")
+      #
+      class ColumnMapper
+        MAX_RICH_TEXT_LENGTH = 2000
+
+        # Map a single column to Notion Columns page properties.
+        #
+        # @param column [Hash] Column hash from metadata["columns"] (name, type, null, default)
+        # @param model_identifier [String] Parent model name (for context)
+        # @param validations [Array<Hash>] Model-level validations to match against this column
+        # @param parent_page_id [String, nil] Notion page ID of the Data Models parent page
+        # @return [Hash] Notion page properties hash
+        def map(column, model_identifier: nil, validations: [], parent_page_id: nil) # rubocop:disable Lint/UnusedMethodArgument
+          properties = {
+            'Column Name' => { title: [{ text: { content: column['name'] } }] },
+            'Data Type' => { select: { name: column['type'] } },
+            'Nullable' => { checkbox: column['null'] == true },
+            'Default Value' => rich_text_property(column['default'].to_s),
+            'Validation Rules' => rich_text_property(format_validation_rules(column['name'], validations))
+          }
+
+          properties['Table'] = { relation: [{ id: parent_page_id }] } if parent_page_id
+
+          properties
+        end
+
+        private
+
+        # Find and format validations matching this column name.
+        #
+        # @param column_name [String]
+        # @param validations [Array<Hash>]
+        # @return [String]
+        def format_validation_rules(column_name, validations)
+          matched = validations.select { |v| v['attribute'] == column_name }
+          return 'None' if matched.empty?
+
+          matched.map { |v| v['type'] }.join(', ')
+        end
+
+        # Build a Notion rich_text property.
+        #
+        # @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/mappers/migration_mapper.rb

@@ -0,0 +1,39 @@
+# 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