woods 1.6.1 → 2.0.0.beta2

data/lib/woods/console/bridge.rb

@@ -1,210 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-require_relative 'bridge_protocol'
-require_relative 'model_validator'
-require_relative 'safe_context'
-
-module Woods
-  module Console
-    # **PROTOCOL SCAFFOLD — does not execute real queries.** Every handler
-    # below returns static empty data (`{ 'count' => 0 }`, `{ 'records' =>
-    # [] }`, etc.). Real in-process execution lives in
-    # {Woods::Console::EmbeddedExecutor}; the eventual real bridge process
-    # for Option D will replace this scaffold with a class that performs
-    # actual ActiveRecord queries.
-    #
-    # The scaffold pins the JSON-lines wire protocol — request envelope,
-    # response envelope, supported-tools list, error shape — so other
-    # components (EmbeddedExecutor, ConnectionManager, Server) can be
-    # built and tested against a stable contract before the real
-    # bridge-process implementation lands. Treat this class the way you'd
-    # treat a Sinatra fake of a third-party API in tests: it satisfies
-    # the protocol, nothing more.
-    #
-    # ## Why the name carries "Stub"
-    #
-    # Round-1 audit Track H-4 flagged this class as a "critical SafeContext
-    # bypass" because `handle_request` doesn't wrap calls in `SafeContext`.
-    # That finding wasn't exploitable — no live code path executes through
-    # this class in the shipped gem — but the bare name `Bridge` made the
-    # scaffold status invisible to auditors. The `Stub` prefix removes the
-    # ambiguity. When the real bridge-process implementation is delivered,
-    # it should claim the `Bridge` name; this class will either be deleted
-    # (if the protocol is fully owned by the real bridge) or renamed to
-    # `BridgeProtocol` and reduced to a constants module.
-    #
-    # ## Protocol
-    #
-    # Reads JSON-lines requests from an input IO, validates model/column names,
-    # dispatches to (stub) tool handlers, and writes JSON-lines responses to
-    # an output IO.
-    #
-    # Protocol:
-    #   Request:  {"id":"req_1","tool":"count","params":{"model":"Order","scope":{"status":"pending"}}}
-    #   Response: {"id":"req_1","ok":true,"result":{"count":1847},"timing_ms":12.3}
-    #   Error:    {"id":"req_1","ok":false,"error":"Model not found","error_type":"validation"}
-    #
-    # @example Wiring against a fake input/output (testing only — handlers return empty data)
-    #   bridge = StubBridge.new(input: $stdin, output: $stdout,
-    #                           model_validator: validator, safe_context: ctx)
-    #   bridge.run
-    #
-    class StubBridge
-      # Protocol constants live on {BridgeProtocol} so the real executor
-      # (EmbeddedExecutor) and a future real bridge-process class can
-      # reference them without importing the scaffold. These top-level
-      # aliases keep `StubBridge::SUPPORTED_TOOLS` working for existing
-      # callers and specs.
-      SUPPORTED_TOOLS = BridgeProtocol::SUPPORTED_TOOLS
-      TIER1_TOOLS     = BridgeProtocol::TIER1_TOOLS
-      TOOL_HANDLERS   = BridgeProtocol::TOOL_HANDLERS
-
-      # @param input [IO] Input stream (reads JSON-lines)
-      # @param output [IO] Output stream (writes JSON-lines)
-      # @param model_validator [ModelValidator] Validates model/column names
-      # @param safe_context [SafeContext] Wraps execution in safe transaction
-      def initialize(input:, output:, model_validator:, safe_context:)
-        @input = input
-        @output = output
-        @model_validator = model_validator
-        @safe_context = safe_context
-      end
-
-      # Read loop — processes requests until input is closed.
-      #
-      # @return [void]
-      def run
-        @input.each_line do |line|
-          line = line.strip
-          next if line.empty?
-
-          request = parse_request(line)
-          next unless request
-
-          response = handle_request(request)
-          write_response(response)
-        end
-      end
-
-      # Process a single request hash and return a response hash.
-      #
-      # @param request [Hash] Parsed request with "id", "tool", "params"
-      # @return [Hash] Response with "id", "ok", and "result" or "error"
-      def handle_request(request)
-        id = request['id']
-        tool = request['tool']
-        params = request['params'] || {}
-
-        return error_response(id, "Unknown tool: #{tool}", 'unknown_tool') unless SUPPORTED_TOOLS.include?(tool)
-
-        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        result = dispatch(tool, params)
-        elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(1)
-
-        { 'id' => id, 'ok' => true, 'result' => result, 'timing_ms' => elapsed }
-      rescue ValidationError => e
-        error_response(id, e.message, 'validation')
-      rescue StandardError => e
-        error_response(id, e.message, 'execution')
-      end
-
-      private
-
-      # Parse a JSON line into a request hash.
-      #
-      # @param line [String] Raw JSON line
-      # @return [Hash, nil] Parsed request or nil on parse error
-      def parse_request(line)
-        JSON.parse(line)
-      rescue JSON::ParserError => e
-        write_response(error_response(nil, "Invalid JSON: #{e.message}", 'parse'))
-        nil
-      end
-
-      # Dispatch a tool request to the appropriate handler.
-      #
-      # @param tool [String] Tool name
-      # @param params [Hash] Tool parameters
-      # @return [Hash] Tool result
-      def dispatch(tool, params)
-        case tool
-        when 'status'
-          handle_status
-        when 'schema'
-          handle_schema(params)
-        else
-          validate_model_param(params)
-          handler = TOOL_HANDLERS.fetch(tool) { raise ValidationError, "Unknown tool: #{tool}" }
-          send(handler, params)
-        end
-      end
-
-      # Validate that the model parameter is present and known.
-      def validate_model_param(params)
-        model = params['model']
-        raise ValidationError, 'Missing required parameter: model' unless model
-
-        @model_validator.validate_model!(model)
-      end
-
-      # Stub handlers below return empty/zero data by design — see the
-      # class-level docstring. Real in-process execution happens in
-      # EmbeddedExecutor; the eventual Option-D bridge process will replace
-      # this class entirely.
-
-      def handle_count(_params)
-        { 'count' => 0 }
-      end
-
-      def handle_sample(_params)
-        { 'records' => [] }
-      end
-
-      def handle_find(_params)
-        { 'record' => nil }
-      end
-
-      def handle_pluck(params)
-        @model_validator.validate_columns!(params['model'], params['columns']) if params['columns']
-        { 'columns' => Array(params['columns']), 'values' => [] }
-      end
-
-      def handle_aggregate(params)
-        @model_validator.validate_column!(params['model'], params['column']) if params['column']
-        { 'value' => nil }
-      end
-
-      def handle_association_count(_params)
-        { 'count' => 0 }
-      end
-
-      def handle_schema(params)
-        model = params['model']
-        raise ValidationError, 'Missing required parameter: model' unless model
-
-        @model_validator.validate_model!(model)
-        { 'columns' => @model_validator.columns_for(model), 'indexes' => [] }
-      end
-
-      def handle_recent(_params)
-        { 'records' => [] }
-      end
-
-      def handle_status
-        { 'status' => 'ok', 'models' => @model_validator.model_names }
-      end
-
-      # Build an error response hash.
-      def error_response(id, message, error_type)
-        { 'id' => id, 'ok' => false, 'error' => message, 'error_type' => error_type }
-      end
-
-      # Write a JSON-line response to the output stream.
-      def write_response(response)
-        @output.puts(JSON.generate(response))
-        @output.flush
-      end
-    end
-  end
-end

data/lib/woods/formatting/claude_adapter.rb

@@ -1,98 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'base'
-
-module Woods
-  module Formatting
-    # Formats assembled context as XML for Claude models.
-    #
-    # Produces structured XML with:
-    # - `<codebase-context>` root element
-    # - `<meta>` tag with token usage and budget
-    # - `<content>` section with indented context text
-    # - `<sources>` section with self-closing `<source>` elements
-    #
-    # @example
-    #   adapter = ClaudeAdapter.new
-    #   xml = adapter.format(assembled_context)
-    #   # => "<codebase-context>\n  <meta tokens=\"42\" budget=\"8000\" />\n..."
-    #
-    class ClaudeAdapter < Base
-      # Format assembled context as XML for Claude.
-      #
-      # @param assembled_context [Woods::Retrieval::AssembledContext]
-      # @return [String] XML-formatted context
-      def format(assembled_context)
-        parts = []
-        parts << '<codebase-context>'
-        parts << "  <meta tokens=\"#{assembled_context.tokens_used}\" budget=\"#{assembled_context.budget}\" />"
-        parts << format_content(assembled_context.context)
-        parts << format_sources(assembled_context.sources)
-        parts << '</codebase-context>'
-        parts.join("\n")
-      end
-
-      private
-
-      # Format the content section with indentation.
-      #
-      # @param context [String]
-      # @return [String]
-      def format_content(context)
-        lines = []
-        lines << '  <content>'
-        lines << indent(escape_xml(context), 4) unless context.empty?
-        lines << '  </content>'
-        lines.join("\n")
-      end
-
-      # Format the sources section.
-      #
-      # @param sources [Array<Hash>]
-      # @return [String]
-      def format_sources(sources)
-        lines = []
-        lines << '  <sources>'
-        sources.each do |source|
-          lines << "    <source #{source_attributes(source)} />"
-        end
-        lines << '  </sources>'
-        lines.join("\n")
-      end
-
-      # Build attribute string for a source element.
-      #
-      # @param source [Hash]
-      # @return [String]
-      def source_attributes(source)
-        [
-          "identifier=\"#{escape_xml(source[:identifier].to_s)}\"",
-          "type=\"#{escape_xml(source[:type].to_s)}\"",
-          "score=\"#{source[:score]}\"",
-          "file=\"#{escape_xml(source[:file_path].to_s)}\""
-        ].join(' ')
-      end
-
-      # Indent every line of text by the given number of spaces.
-      #
-      # @param text [String]
-      # @param spaces [Integer]
-      # @return [String]
-      def indent(text, spaces)
-        prefix = ' ' * spaces
-        text.lines.map { |line| "#{prefix}#{line.chomp}" }.join("\n")
-      end
-
-      # Escape XML special characters.
-      #
-      # @param text [String]
-      # @return [String]
-      def escape_xml(text)
-        text.gsub('&', '&amp;')
-            .gsub('<', '&lt;')
-            .gsub('>', '&gt;')
-            .gsub('"', '&quot;')
-      end
-    end
-  end
-end

data/lib/woods/formatting/generic_adapter.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'base'
-
-module Woods
-  module Formatting
-    # Formats assembled context as plain text for generic LLM consumption.
-    #
-    # Produces plain text with:
-    # - `=== CODEBASE CONTEXT ===` header
-    # - Token usage line
-    # - Content separated by `---` dividers
-    # - Sources in bracket notation
-    #
-    # @example
-    #   adapter = GenericAdapter.new
-    #   text = adapter.format(assembled_context)
-    #   # => "=== CODEBASE CONTEXT ===\nTokens: 42 / 8000\n..."
-    #
-    class GenericAdapter < Base
-      # Format assembled context as plain text.
-      #
-      # @param assembled_context [Woods::Retrieval::AssembledContext]
-      # @return [String] Plain text formatted context
-      def format(assembled_context)
-        parts = []
-        parts << '=== CODEBASE CONTEXT ==='
-        parts << "Tokens: #{assembled_context.tokens_used} / #{assembled_context.budget}"
-        parts << '---'
-        parts << assembled_context.context
-        parts.concat(format_sources(assembled_context.sources))
-        parts.join("\n")
-      end
-
-      private
-
-      # Format sources in bracket notation.
-      #
-      # @param sources [Array<Hash>]
-      # @return [Array<String>] Lines to append
-      def format_sources(sources)
-        return [] if sources.empty?
-
-        lines = []
-        lines << '---'
-        sources.each do |source|
-          identifier = source[:identifier]
-          type = source[:type]
-          score = source[:score]
-          lines << "[Source: #{identifier} (#{type}) \u2014 score: #{score}]"
-        end
-        lines
-      end
-    end
-  end
-end

data/lib/woods/formatting/gpt_adapter.rb

@@ -1,64 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'base'
-
-module Woods
-  module Formatting
-    # Formats assembled context as Markdown for GPT models.
-    #
-    # Produces Markdown with:
-    # - `## Codebase Context` heading
-    # - Token usage in bold
-    # - Content in a fenced Ruby code block
-    # - Sources as a bullet list
-    #
-    # @example
-    #   adapter = GptAdapter.new
-    #   md = adapter.format(assembled_context)
-    #   # => "## Codebase Context\n\n**Tokens:** 42/8000\n..."
-    #
-    class GptAdapter < Base
-      # Format assembled context as Markdown for GPT.
-      #
-      # @param assembled_context [Woods::Retrieval::AssembledContext]
-      # @return [String] Markdown-formatted context
-      def format(assembled_context)
-        parts = []
-        parts << '## Codebase Context'
-        parts << ''
-        parts << "**Tokens:** #{assembled_context.tokens_used}/#{assembled_context.budget}"
-        parts << ''
-        parts << '---'
-        parts << ''
-        parts << '```ruby'
-        parts << assembled_context.context
-        parts << '```'
-        parts.concat(format_sources(assembled_context.sources))
-        parts.join("\n")
-      end
-
-      private
-
-      # Format sources as a Markdown bullet list.
-      #
-      # @param sources [Array<Hash>]
-      # @return [Array<String>] Lines to append
-      def format_sources(sources)
-        return [] if sources.empty?
-
-        lines = []
-        lines << ''
-        lines << '### Sources'
-        lines << ''
-        sources.each do |source|
-          identifier = source[:identifier]
-          type = source[:type]
-          score = source[:score]
-          file_path = source[:file_path]
-          lines << "- **#{identifier}** (#{type}) \u2014 score: #{score}, file: #{file_path}"
-        end
-        lines
-      end
-    end
-  end
-end

data/lib/woods/notion/mapper.rb

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'mappers/shared'
-require_relative 'mappers/model_mapper'
-require_relative 'mappers/column_mapper'
-require_relative 'mappers/migration_mapper'
-
-module Woods
-  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/woods/observability/health_check.rb

@@ -1,79 +0,0 @@
-# frozen_string_literal: true
-
-module Woods
-  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/woods/observability/instrumentation.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-module Woods
-  module Observability
-    # Lightweight instrumentation wrapper that delegates to ActiveSupport::Notifications
-    # when available, and falls back to a simple yield otherwise.
-    #
-    # @example
-    #   Instrumentation.instrument('woods.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., 'woods.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