codebase_index 0.2.1 → 0.3.1

data/lib/codebase_index/mcp/renderers/plain_renderer.rb

@@ -58,17 +58,17 @@ module CodebaseIndex
         end
 
         def render_search(data, **)
-          query = data[:query] || data['query']
-          count = data[:result_count] || data['result_count'] || 0
-          results = data[:results] || data['results'] || []
+          query = fetch_key(data, :query)
+          count = fetch_key(data, :result_count, 0)
+          results = fetch_key(data, :results, [])
 
           lines = []
           lines << "Search: \"#{query}\" (#{count} results)"
           lines << DIVIDER
 
           results.each do |r|
-            ident = r['identifier'] || r[:identifier]
-            type = r['type'] || r[:type]
+            ident = fetch_key(r, :identifier)
+            type = fetch_key(r, :type)
             lines << "  #{ident} (#{type})"
           end
 
@@ -84,7 +84,7 @@ module CodebaseIndex
         end
 
         def render_structure(data, **)
-          manifest = data[:manifest] || data['manifest'] || {}
+          manifest = fetch_key(data, :manifest, {})
           lines = []
           lines << 'Codebase Structure'
           lines << DIVIDER
@@ -100,7 +100,7 @@ module CodebaseIndex
             counts.sort_by { |_k, v| -v }.each { |type, count| lines << "  #{type}: #{count}" }
           end
 
-          summary = data[:summary] || data['summary']
+          summary = fetch_key(data, :summary)
           if summary
             lines << ''
             lines << DIVIDER
@@ -115,14 +115,14 @@ module CodebaseIndex
           lines << 'Graph Analysis'
           lines << DIVIDER
 
-          stats = data['stats'] || data[:stats]
+          stats = fetch_key(data, :stats)
           if stats.is_a?(Hash)
             stats.each { |k, v| lines << "  #{k}: #{v}" }
             lines << ''
           end
 
           %w[orphans dead_ends hubs cycles bridges].each do |section|
-            items = data[section] || data[section.to_sym]
+            items = fetch_key(data, section)
             next unless items.is_a?(Array) && items.any?
 
             lines << "#{section.tr('_', ' ').upcase}:"
@@ -144,14 +144,14 @@ module CodebaseIndex
 
         def render_pagerank(data, **)
           lines = []
-          lines << "PageRank Scores (#{data[:total_nodes] || data['total_nodes']} nodes)"
+          lines << "PageRank Scores (#{fetch_key(data, :total_nodes)} nodes)"
           lines << DIVIDER
 
-          results = data[:results] || data['results'] || []
+          results = fetch_key(data, :results, [])
           results.each_with_index do |r, i|
-            ident = r[:identifier] || r['identifier']
-            type = r[:type] || r['type']
-            score = r[:score] || r['score']
+            ident = fetch_key(r, :identifier)
+            type = fetch_key(r, :type)
+            score = fetch_key(r, :score)
             lines << "  #{i + 1}. #{ident} (#{type}) - #{score}"
           end
 
@@ -159,17 +159,17 @@ module CodebaseIndex
         end
 
         def render_framework(data, **)
-          keyword = data[:keyword] || data['keyword']
-          count = data[:result_count] || data['result_count'] || 0
-          results = data[:results] || data['results'] || []
+          keyword = fetch_key(data, :keyword)
+          count = fetch_key(data, :result_count, 0)
+          results = fetch_key(data, :results, [])
 
           lines = []
           lines << "Framework: \"#{keyword}\" (#{count} results)"
           lines << DIVIDER
 
           results.each do |r|
-            ident = r['identifier'] || r[:identifier]
-            type = r['type'] || r[:type]
+            ident = fetch_key(r, :identifier)
+            type = fetch_key(r, :type)
             lines << "  #{ident} (#{type})"
           end
 
@@ -177,17 +177,17 @@ module CodebaseIndex
         end
 
         def render_recent_changes(data, **)
-          count = data[:result_count] || data['result_count'] || 0
-          results = data[:results] || data['results'] || []
+          count = fetch_key(data, :result_count, 0)
+          results = fetch_key(data, :results, [])
 
           lines = []
           lines << "Recent Changes (#{count} units)"
           lines << DIVIDER
 
           results.each do |r|
-            ident = r['identifier'] || r[:identifier]
-            type = r['type'] || r[:type]
-            modified = r['last_modified'] || r[:last_modified] || '-'
+            ident = fetch_key(r, :identifier)
+            type = fetch_key(r, :type)
+            modified = fetch_key(r, :last_modified) || '-'
             lines << "  #{ident} (#{type}) - #{modified}"
           end
 
@@ -210,10 +210,10 @@ module CodebaseIndex
         private
 
         def render_plain_traversal(label, data)
-          root = data[:root] || data['root']
+          root = fetch_key(data, :root)
           found = data[:found] || data['found']
-          nodes = data[:nodes] || data['nodes'] || {}
-          message = data[:message] || data['message']
+          nodes = fetch_key(data, :nodes, {})
+          message = fetch_key(data, :message)
 
           lines = []
           lines << "#{label} of #{root}"
@@ -225,8 +225,8 @@ module CodebaseIndex
           end
 
           nodes.each do |id, info|
-            depth = info['depth'] || info[:depth] || 0
-            deps = info['deps'] || info[:deps] || []
+            depth = fetch_key(info, :depth) || 0
+            deps = fetch_key(info, :deps, [])
             indent = '  ' * (depth + 1)
             lines << "#{indent}#{id}"
             deps.each { |d| lines << "#{indent}  -> #{d}" }

data/lib/codebase_index/mcp/server.rb

@@ -48,8 +48,16 @@ module CodebaseIndex
 
           define_lookup_tool(server, reader, respond, renderer)
           define_search_tool(server, reader, respond, renderer)
-          define_dependencies_tool(server, reader, respond, renderer)
-          define_dependents_tool(server, reader, respond, renderer)
+          define_traversal_tool(server, reader, respond, renderer,
+                                name: 'dependencies',
+                                description: 'Traverse forward dependencies of a unit (what it depends on). Returns a BFS tree with depth.',
+                                reader_method: :traverse_dependencies,
+                                render_key: :dependencies)
+          define_traversal_tool(server, reader, respond, renderer,
+                                name: 'dependents',
+                                description: 'Traverse reverse dependencies of a unit (what depends on it). Returns a BFS tree with depth.',
+                                reader_method: :traverse_dependents,
+                                render_key: :dependents)
           define_structure_tool(server, reader, respond, renderer)
           define_graph_analysis_tool(server, reader, respond, renderer)
           define_pagerank_tool(server, reader, respond, renderer)
@@ -89,7 +97,38 @@ module CodebaseIndex
           end
         end
 
+        # Coerce a value to an Array. Wraps a single String in an Array;
+        # leaves existing Arrays and nil unchanged.
+        #
+        # @param value [String, Array, nil] The input value
+        # @return [Array, nil]
+        def coerce_array(value)
+          value.is_a?(String) ? [value] : value
+        end
+
+        # Apply offset+limit pagination to a single section key within a container hash.
+        # Adds `_total`, `_truncated`, and `_offset` metadata keys when truncating.
+        #
+        # @param container [Hash] The hash to mutate
+        # @param key [String] The section key whose value is an Array
+        # @param limit [Integer, nil] Max items to retain; nil means no limit
+        # @param offset [Integer] Items to skip from the front
+        # @return [void]
+        def paginate_section(container, key, limit, offset)
+          original = container[key]
+          return unless original.is_a?(Array)
+
+          sliced = offset.positive? ? original.drop(offset) : original
+          container[key] = limit ? truncate_section(sliced, limit) : sliced
+          if original.size > offset + (limit || original.size)
+            container["#{key}_total"] = original.size
+            container["#{key}_truncated"] = true
+          end
+          container["#{key}_offset"] = offset if offset.positive?
+        end
+
         def define_lookup_tool(server, reader, respond, renderer)
+          coerce = method(:coerce_array)
           server.define_tool(
             name: 'lookup',
             description: 'Look up a code unit by its exact identifier. Returns full source code, metadata, ' \
@@ -108,7 +147,7 @@ module CodebaseIndex
               required: ['identifier']
             }
           ) do |identifier:, server_context:, include_source: nil, sections: nil|
-            sections = [sections] if sections.is_a?(String)
+            sections = coerce.call(sections)
             unit = reader.find_unit(identifier)
             if unit
               always_include = %w[type identifier file_path namespace]
@@ -126,6 +165,7 @@ module CodebaseIndex
         end
 
         def define_search_tool(server, reader, respond, renderer)
+          coerce = method(:coerce_array)
           server.define_tool(
             name: 'search',
             description: 'Search code units by pattern. Matches against identifiers by default; can also search source_code and metadata fields.',
@@ -145,8 +185,8 @@ module CodebaseIndex
               required: ['query']
             }
           ) do |query:, server_context:, types: nil, fields: nil, limit: nil|
-            types = [types] if types.is_a?(String)
-            fields = [fields] if fields.is_a?(String)
+            types = coerce.call(types)
+            fields = coerce.call(fields)
             results = reader.search(
               query,
               types: types,
@@ -161,10 +201,11 @@ module CodebaseIndex
           end
         end
 
-        def define_dependencies_tool(server, reader, respond, renderer)
+        def define_traversal_tool(server, reader, respond, renderer, name:, description:, reader_method:, render_key:)
+          coerce = method(:coerce_array)
           server.define_tool(
-            name: 'dependencies',
-            description: 'Traverse forward dependencies of a unit (what it depends on). Returns a BFS tree with depth.',
+            name: name,
+            description: description,
             input_schema: {
               properties: {
                 identifier: { type: 'string', description: 'Unit identifier to start from' },
@@ -177,47 +218,13 @@ module CodebaseIndex
               required: ['identifier']
             }
           ) do |identifier:, server_context:, depth: nil, types: nil|
-            types = [types] if types.is_a?(String)
-            result = reader.traverse_dependencies(
-              identifier,
-              depth: depth || 2,
-              types: types
-            )
+            types = coerce.call(types)
+            result = reader.send(reader_method, identifier, depth: depth || 2, types: types)
             if result[:found] == false
               result[:message] =
                 "Identifier '#{identifier}' not found in the index. Use 'search' to find valid identifiers."
             end
-            respond.call(renderer.render(:dependencies, result))
-          end
-        end
-
-        def define_dependents_tool(server, reader, respond, renderer)
-          server.define_tool(
-            name: 'dependents',
-            description: 'Traverse reverse dependencies of a unit (what depends on it). Returns a BFS tree with depth.',
-            input_schema: {
-              properties: {
-                identifier: { type: 'string', description: 'Unit identifier to start from' },
-                depth: { type: 'integer', description: 'Maximum traversal depth (default: 2)' },
-                types: {
-                  type: 'array', items: { type: 'string' },
-                  description: 'Filter to these types'
-                }
-              },
-              required: ['identifier']
-            }
-          ) do |identifier:, server_context:, depth: nil, types: nil|
-            types = [types] if types.is_a?(String)
-            result = reader.traverse_dependents(
-              identifier,
-              depth: depth || 2,
-              types: types
-            )
-            if result[:found] == false
-              result[:message] =
-                "Identifier '#{identifier}' not found in the index. Use 'search' to find valid identifiers."
-            end
-            respond.call(renderer.render(:dependents, result))
+            respond.call(renderer.render(render_key, result))
           end
         end
 
@@ -241,7 +248,7 @@ module CodebaseIndex
         end
 
         def define_graph_analysis_tool(server, reader, respond, renderer)
-          truncate = method(:truncate_section)
+          paginate = method(:paginate_section)
           server.define_tool(
             name: 'graph_analysis',
             description: 'Get structural analysis of the dependency graph: orphans, dead ends, hubs, cycles, and bridges.',
@@ -265,16 +272,7 @@ module CodebaseIndex
                        if limit || effective_offset.positive?
                          truncated = data.dup
                          %w[orphans dead_ends hubs cycles bridges].each do |key|
-                           next unless truncated[key].is_a?(Array)
-
-                           original = truncated[key]
-                           sliced = effective_offset.positive? ? original.drop(effective_offset) : original
-                           truncated[key] = limit ? truncate.call(sliced, limit) : sliced
-                           if original.size > effective_offset + (limit || original.size)
-                             truncated["#{key}_total"] = original.size
-                             truncated["#{key}_truncated"] = true
-                           end
-                           truncated["#{key}_offset"] = effective_offset if effective_offset.positive?
+                           paginate.call(truncated, key, limit, effective_offset)
                          end
                          truncated
                        else
@@ -282,16 +280,7 @@ module CodebaseIndex
                        end
                      else
                        single = { section => data[section], 'stats' => data['stats'] }
-                       if data[section].is_a?(Array) && (limit || effective_offset.positive?)
-                         original = data[section]
-                         sliced = effective_offset.positive? ? original.drop(effective_offset) : original
-                         single[section] = limit ? truncate.call(sliced, limit) : sliced
-                         if original.size > effective_offset + (limit || original.size)
-                           single["#{section}_total"] = original.size
-                           single["#{section}_truncated"] = true
-                         end
-                         single["#{section}_offset"] = effective_offset if effective_offset.positive?
-                       end
+                       paginate.call(single, section, limit, effective_offset) if limit || effective_offset.positive?
                        single
                      end
 
@@ -300,6 +289,7 @@ module CodebaseIndex
         end
 
         def define_pagerank_tool(server, reader, respond, renderer)
+          coerce = method(:coerce_array)
           server.define_tool(
             name: 'pagerank',
             description: 'Get PageRank importance scores for code units. Higher scores indicate more structurally important nodes.',
@@ -313,7 +303,7 @@ module CodebaseIndex
               }
             }
           ) do |server_context:, limit: nil, types: nil|
-            types = [types] if types.is_a?(String)
+            types = coerce.call(types)
             scores = reader.dependency_graph.pagerank
             graph_data = reader.raw_graph_data
             nodes = graph_data['nodes'] || {}
@@ -362,6 +352,7 @@ module CodebaseIndex
         end
 
         def define_recent_changes_tool(server, reader, respond, renderer)
+          coerce = method(:coerce_array)
           server.define_tool(
             name: 'recent_changes',
             description: 'List recently modified code units sorted by git last_modified timestamp. ' \
@@ -376,7 +367,7 @@ module CodebaseIndex
               }
             }
           ) do |server_context:, limit: nil, types: nil|
-            types = [types] if types.is_a?(String)
+            types = coerce.call(types)
             results = reader.recent_changes(limit: limit || 10, types: types)
             respond.call(renderer.render(:recent_changes, {
                                            result_count: results.size,

data/lib/codebase_index/mcp/tool_response_renderer.rb

@@ -57,6 +57,29 @@ module CodebaseIndex
       def render_default(data)
         raise NotImplementedError, "#{self.class}#render_default must be implemented"
       end
+
+      private
+
+      # Fetch a value from a hash by symbol or string key, falling back to a default.
+      #
+      # Handles data hashes that may use either symbol or string keys (e.g., data
+      # assembled from JSON parsing vs. direct Hash literals).
+      #
+      # @param data [Hash] The source hash
+      # @param key [Symbol, String] The key to look up
+      # @param default [Object] Value to return when key is absent (default: nil)
+      # @return [Object]
+      def fetch_key(data, key, default = nil)
+        sym_key = key.to_sym
+        str_key = key.to_s
+        if data.key?(sym_key)
+          data[sym_key]
+        elsif data.key?(str_key)
+          data[str_key]
+        else
+          default
+        end
+      end
     end
   end
 end

data/lib/codebase_index/notion/client.rb

@@ -129,7 +129,7 @@ module CodebaseIndex
         retries = 0
 
         loop do
-          response = execute_with_retry(method, path, body, retries)
+          response = execute_with_retry(method, path, body)
 
           return JSON.parse(response.body) if response.is_a?(Net::HTTPSuccess)
 
@@ -148,7 +148,7 @@ module CodebaseIndex
       #
       # @return [Net::HTTPResponse]
       # @raise [CodebaseIndex::Error] on persistent network failures
-      def execute_with_retry(method, path, body, _retries)
+      def execute_with_retry(method, path, body)
         attempts = 0
         begin
           @rate_limiter.throttle { execute_http(method, path, body) }

data/lib/codebase_index/notion/mapper.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'mappers/shared'
 require_relative 'mappers/model_mapper'
 require_relative 'mappers/column_mapper'
 require_relative 'mappers/migration_mapper'

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'shared'
+
 module CodebaseIndex
   module Notion
     module Mappers
@@ -13,7 +15,7 @@ module CodebaseIndex
       #   properties = mapper.map(column, model_identifier: "User", validations: [...], parent_page_id: "page-123")
       #
       class ColumnMapper
-        MAX_RICH_TEXT_LENGTH = 2000
+        include Shared
 
         # Map a single column to Notion Columns page properties.
         #
@@ -49,16 +51,6 @@ module CodebaseIndex
 
           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

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'shared'
+
 module CodebaseIndex
   module Notion
     module Mappers
@@ -14,7 +16,7 @@ module CodebaseIndex
       #   client.create_page(database_id: db_id, properties: properties)
       #
       class ModelMapper
-        MAX_RICH_TEXT_LENGTH = 2000
+        include Shared
 
         # Map a model unit to Notion Data Models page properties.
         #
@@ -83,9 +85,7 @@ module CodebaseIndex
 
         # @return [String]
         def format_associations(associations)
-          return 'None' if associations.nil? || associations.empty?
-
-          associations.map { |a| format_single_association(a) }.join("\n")
+          format_list(associations) { |items| items.map { |a| format_single_association(a) }.join("\n") }
         end
 
         # @return [String]
@@ -99,18 +99,16 @@ module CodebaseIndex
 
         # @return [String]
         def format_validations(validations)
-          return 'None' if validations.nil? || validations.empty?
-
-          validations.group_by { |v| v['attribute'] }.map do |attr, vals|
-            "#{attr}: #{vals.map { |v| v['type'] }.join(', ')}"
-          end.join("\n")
+          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)
-          return 'None' if callbacks.nil? || callbacks.empty?
-
-          callbacks.map { |callback| format_single_callback(callback) }.join("\n")
+          format_list(callbacks) { |items| items.map { |callback| format_single_callback(callback) }.join("\n") }
         end
 
         # @return [String]
@@ -135,16 +133,12 @@ module CodebaseIndex
 
         # @return [String]
         def format_scopes(scopes)
-          return 'None' if scopes.nil? || scopes.empty?
-
-          scopes.map { |s| s['name'] }.join(', ')
+          format_list(scopes) { |items| items.map { |s| s['name'] }.join(', ') }
         end
 
         # @return [String]
         def format_dependencies(dependencies)
-          return 'None' if dependencies.nil? || dependencies.empty?
-
-          dependencies.map { |dep| "#{dep['target']} (via #{dep['via']})" }.join(', ')
+          format_list(dependencies) { |items| items.map { |dep| "#{dep['target']} (via #{dep['via']})" }.join(', ') }
         end
 
         # @return [Hash]
@@ -152,11 +146,14 @@ module CodebaseIndex
           { title: [{ text: { content: text } }] }
         end
 
-        # @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 } }] }
+        # 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

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

@@ -0,0 +1,22 @@
+# 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/observability/health_check.rb

@@ -73,8 +73,6 @@ module CodebaseIndex
         else
           :error
         end
-      rescue StandardError
-        :error
       end
     end
   end

data/lib/codebase_index/observability/structured_logger.rb

@@ -22,36 +22,18 @@ module CodebaseIndex
         @output = output
       end
 
-      # Log at info level.
-      #
-      # @param event [String] Event name
-      # @param data [Hash] Additional structured data
-      def info(event, **data)
-        write_entry('info', event, data)
-      end
-
-      # Log at warn level.
-      #
-      # @param event [String] Event name
-      # @param data [Hash] Additional structured data
-      def warn(event, **data)
-        write_entry('warn', event, data)
-      end
-
-      # Log at error level.
-      #
-      # @param event [String] Event name
-      # @param data [Hash] Additional structured data
-      def error(event, **data)
-        write_entry('error', event, data)
-      end
-
-      # Log at debug level.
-      #
-      # @param event [String] Event name
-      # @param data [Hash] Additional structured data
-      def debug(event, **data)
-        write_entry('debug', event, data)
+      # @!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

data/lib/codebase_index/operator/pipeline_guard.rb

@@ -87,13 +87,6 @@ module CodebaseIndex
       rescue JSON::ParserError
         {}
       end
-
-      # @param state [Hash]
-      # @return [void]
-      def write_state(state)
-        FileUtils.mkdir_p(@state_dir)
-        File.write(@state_path, JSON.generate(state))
-      end
     end
   end
 end