woods 1.0.0

data/lib/woods/operator/status_reporter.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module Woods
+  module Operator
+    # Reports pipeline status by reading extraction output metadata.
+    #
+    # @example
+    #   reporter = StatusReporter.new(output_dir: 'tmp/woods')
+    #   status = reporter.report
+    #   status[:status]           # => :ok
+    #   status[:staleness_seconds] # => 3600
+    #
+    class StatusReporter
+      STALE_THRESHOLD = 86_400 # 24 hours
+
+      # @param output_dir [String] Path to extraction output directory
+      def initialize(output_dir:)
+        @output_dir = output_dir
+      end
+
+      # Generate a pipeline status report.
+      #
+      # @return [Hash] Status report with :status, :extracted_at, :total_units, :counts, :staleness_seconds
+      def report
+        manifest = read_manifest
+        return not_extracted_report if manifest.nil?
+
+        staleness = compute_staleness(manifest['extracted_at'])
+
+        {
+          status: staleness < STALE_THRESHOLD ? :ok : :stale,
+          extracted_at: manifest['extracted_at'],
+          total_units: manifest['total_units'] || 0,
+          counts: manifest['counts'] || {},
+          git_sha: manifest['git_sha'],
+          git_branch: manifest['git_branch'],
+          staleness_seconds: staleness
+        }
+      end
+
+      private
+
+      # @return [Hash, nil]
+      def read_manifest
+        path = File.join(@output_dir, 'manifest.json')
+        return nil unless File.exist?(path)
+
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError
+        nil
+      end
+
+      # @return [Hash]
+      def not_extracted_report
+        {
+          status: :not_extracted,
+          extracted_at: nil,
+          total_units: 0,
+          counts: {},
+          git_sha: nil,
+          git_branch: nil,
+          staleness_seconds: nil
+        }
+      end
+
+      # @param extracted_at [String, nil] ISO8601 timestamp
+      # @return [Numeric]
+      def compute_staleness(extracted_at)
+        return Float::INFINITY if extracted_at.nil?
+
+        Time.now - Time.parse(extracted_at)
+      rescue ArgumentError
+        Float::INFINITY
+      end
+    end
+  end
+end

data/lib/woods/railtie.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Woods
+  # Railtie integrates Woods into Rails applications.
+  # Loads rake tasks automatically when the gem is bundled.
+  # Conditionally inserts session tracer middleware when enabled.
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path('../tasks/woods.rake', __dir__)
+    end
+
+    initializer 'woods.session_tracer' do |app|
+      config = Woods.configuration
+      if config.session_tracer_enabled
+        require 'woods/session_tracer/middleware'
+
+        app.middleware.use(
+          Woods::SessionTracer::Middleware,
+          store: config.session_store,
+          session_id_proc: config.session_id_proc,
+          exclude_paths: config.session_exclude_paths
+        )
+      end
+    end
+
+    initializer 'woods.console_mcp' do |app|
+      config = Woods.configuration
+      if config.console_mcp_enabled
+        require 'woods/console/rack_middleware'
+
+        app.middleware.use(
+          Woods::Console::RackMiddleware,
+          path: config.console_mcp_path
+        )
+      end
+    end
+  end
+end

data/lib/woods/resilience/circuit_breaker.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Woods
+  module Resilience
+    # Raised when the circuit breaker is open and calls are being rejected.
+    #
+    # @example Handling a circuit open condition
+    #   begin
+    #     breaker.call { provider.embed(text) }
+    #   rescue CircuitOpenError => e
+    #     use_cached_result(text)
+    #   end
+    class CircuitOpenError < Woods::Error; end
+
+    # Circuit breaker pattern for protecting external service calls.
+    #
+    # Tracks failures and transitions between three states:
+    # - **:closed** — normal operation, calls pass through
+    # - **:open** — too many failures, calls are rejected immediately
+    # - **:half_open** — testing recovery, one call is allowed through
+    #
+    # @example Basic usage
+    #   breaker = CircuitBreaker.new(threshold: 5, reset_timeout: 60)
+    #   result = breaker.call { external_service.request }
+    #
+    # @example With retry logic
+    #   breaker = CircuitBreaker.new(threshold: 3, reset_timeout: 30)
+    #   begin
+    #     breaker.call { api.embed(text) }
+    #   rescue CircuitOpenError
+    #     # Service is down, use fallback
+    #   end
+    class CircuitBreaker
+      # @return [Symbol] Current state — :closed, :open, or :half_open
+      attr_reader :state
+
+      # @param threshold [Integer] Number of consecutive failures before opening the circuit
+      # @param reset_timeout [Numeric] Seconds to wait before transitioning from open to half_open
+      def initialize(threshold: 5, reset_timeout: 60)
+        @threshold = threshold
+        @reset_timeout = reset_timeout
+        @state = :closed
+        @failure_count = 0
+        @last_failure_time = nil
+        @mutex = Mutex.new
+      end
+
+      # Execute a block through the circuit breaker.
+      #
+      # @yield The block to execute
+      # @return [Object] The return value of the block
+      # @raise [CircuitOpenError] if the circuit is open and the timeout has not elapsed
+      # @raise [StandardError] re-raises any error from the block
+      def call(&block)
+        # Phase 1: Check state under mutex
+        @mutex.synchronize do
+          case @state
+          when :open
+            unless Time.now - @last_failure_time >= @reset_timeout
+              raise CircuitOpenError, "Circuit breaker is open (#{@failure_count} failures)"
+            end
+
+            @state = :half_open
+          end
+        end
+
+        # Phase 2: Execute outside mutex
+        result = block.call
+
+        # Phase 3: Record success under mutex
+        @mutex.synchronize { reset! }
+
+        result
+      rescue CircuitOpenError
+        raise
+      rescue StandardError => e
+        # Phase 4: Record failure under mutex
+        @mutex.synchronize { record_failure }
+        raise e
+      end
+
+      private
+
+      # Record a failure and potentially open the circuit.
+      def record_failure
+        @failure_count += 1
+        @last_failure_time = Time.now
+        @state = :open if @failure_count >= @threshold
+      end
+
+      # Reset the circuit breaker to closed state with zero failures.
+      def reset!
+        @state = :closed
+        @failure_count = 0
+        @last_failure_time = nil
+      end
+    end
+  end
+end

data/lib/woods/resilience/index_validator.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../filename_utils'
+
+module Woods
+  module Resilience
+    # Validates the integrity of a codebase index output directory.
+    #
+    # Checks that:
+    # - Each type directory has a valid `_index.json`
+    # - All files referenced in the index exist on disk
+    # - Content hashes (source_hash) match the actual source_code
+    # - No stale unit files exist that aren't listed in the index
+    #
+    # @example
+    #   validator = IndexValidator.new(index_dir: "tmp/woods")
+    #   report = validator.validate
+    #   puts report.errors if !report.valid?
+    class IndexValidator
+      include Woods::FilenameUtils
+
+      # Report produced by {#validate}.
+      #
+      # @!attribute [r] valid?
+      #   @return [Boolean] true if no errors were found
+      # @!attribute [r] warnings
+      #   @return [Array<String>] non-fatal issues (e.g., stale files)
+      # @!attribute [r] errors
+      #   @return [Array<String>] fatal integrity issues
+      ValidationReport = Struct.new(:valid?, :warnings, :errors, keyword_init: true)
+
+      # @param index_dir [String] Path to the codebase index output directory
+      def initialize(index_dir:)
+        @index_dir = index_dir
+      end
+
+      # Validate the index directory and return a report.
+      #
+      # @return [ValidationReport] the validation results
+      def validate
+        warnings = []
+        errors = []
+
+        unless Dir.exist?(@index_dir)
+          errors << "Index directory does not exist: #{@index_dir}"
+          return ValidationReport.new(valid?: false, warnings: warnings, errors: errors)
+        end
+
+        type_dirs = Dir.children(@index_dir).filter_map do |name|
+          full_path = File.join(@index_dir, name)
+          full_path if File.directory?(full_path)
+        end
+
+        type_dirs.each do |type_dir|
+          validate_type_directory(type_dir, warnings, errors)
+        end
+
+        ValidationReport.new(valid?: errors.empty?, warnings: warnings, errors: errors)
+      end
+
+      private
+
+      # Validate a single type directory (e.g., models/, controllers/).
+      #
+      # @param type_dir [String] Absolute path to the type directory
+      # @param warnings [Array<String>] Accumulated warnings
+      # @param errors [Array<String>] Accumulated errors
+      def validate_type_directory(type_dir, warnings, errors)
+        type_name = File.basename(type_dir)
+        index_path = File.join(type_dir, '_index.json')
+
+        unless File.exist?(index_path)
+          errors << "Missing _index.json in #{type_name}/"
+          return
+        end
+
+        index_entries = JSON.parse(File.read(index_path))
+        indexed_identifiers = Set.new
+
+        index_entries.each do |entry|
+          identifier = entry['identifier']
+          indexed_identifiers << identifier
+          validate_index_entry(type_dir, type_name, identifier, errors)
+        end
+
+        check_stale_files(type_dir, type_name, indexed_identifiers, warnings)
+      end
+
+      # Validate that a single index entry has a corresponding unit file with correct hash.
+      #
+      # @param type_dir [String] Path to the type directory
+      # @param type_name [String] Name of the type (for error messages)
+      # @param identifier [String] The unit identifier from the index
+      # @param errors [Array<String>] Accumulated errors
+      def validate_index_entry(type_dir, type_name, identifier, errors)
+        unit_file = find_unit_file(type_dir, identifier)
+
+        unless unit_file
+          errors << "Missing unit file for #{identifier} in #{type_name}/"
+          return
+        end
+
+        validate_content_hash(unit_file, identifier, errors)
+      end
+
+      # Find the JSON file for a given identifier in a type directory.
+      #
+      # @param type_dir [String] Path to the type directory
+      # @param identifier [String] The unit identifier
+      # @return [String, nil] Path to the unit file, or nil if not found
+      def find_unit_file(type_dir, identifier)
+        # Try collision-safe first (current format), then legacy safe_filename, then exact match
+        candidates = [
+          File.join(type_dir, collision_safe_filename(identifier)),
+          File.join(type_dir, safe_filename(identifier)),
+          File.join(type_dir, "#{identifier}.json")
+        ]
+
+        candidates.find { |path| File.exist?(path) }
+      end
+
+      # Validate that the source_hash in a unit file matches the actual source_code.
+      #
+      # @param unit_file [String] Path to the unit JSON file
+      # @param identifier [String] The unit identifier (for error messages)
+      # @param errors [Array<String>] Accumulated errors
+      def validate_content_hash(unit_file, identifier, errors)
+        data = JSON.parse(File.read(unit_file))
+        source_code = data['source_code']
+        stored_hash = data['source_hash']
+
+        return unless source_code && stored_hash
+
+        expected_hash = Digest::SHA256.hexdigest(source_code)
+        return if stored_hash == expected_hash
+
+        errors << "Content hash mismatch for #{identifier}: expected #{expected_hash[0..7]}..., " \
+                  "got #{stored_hash[0..7]}..."
+      end
+
+      # Check for unit files that exist on disk but aren't referenced in the index.
+      #
+      # @param type_dir [String] Path to the type directory
+      # @param type_name [String] Name of the type (for warning messages)
+      # @param indexed_identifiers [Set<String>] Identifiers listed in the index
+      # @param warnings [Array<String>] Accumulated warnings
+      def check_stale_files(type_dir, type_name, indexed_identifiers, warnings)
+        # Build a set of expected filenames from indexed identifiers (both current and legacy formats)
+        expected_filenames = Set.new
+        indexed_identifiers.each do |id|
+          expected_filenames << collision_safe_filename(id)
+          expected_filenames << safe_filename(id)
+          expected_filenames << "#{id}.json"
+        end
+
+        Dir[File.join(type_dir, '*.json')].each do |file|
+          basename = File.basename(file)
+          next if basename == '_index.json'
+          next if expected_filenames.include?(basename)
+
+          warnings << "Stale file not in index: #{type_name}/#{basename}"
+        end
+      end
+    end
+  end
+end

data/lib/woods/resilience/retryable_provider.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative '../embedding/provider'
+require_relative 'circuit_breaker'
+
+module Woods
+  module Resilience
+    # Wraps an embedding provider with retry logic and optional circuit breaker.
+    #
+    # Transparently retries transient failures with exponential backoff.
+    # When a circuit breaker is provided, all calls are routed through it,
+    # and {CircuitOpenError} is never retried.
+    #
+    # @example Without circuit breaker
+    #   retryable = RetryableProvider.new(provider: ollama_provider, max_retries: 3)
+    #   vector = retryable.embed("some text")
+    #
+    # @example With circuit breaker
+    #   breaker = CircuitBreaker.new(threshold: 5, reset_timeout: 60)
+    #   retryable = RetryableProvider.new(
+    #     provider: ollama_provider,
+    #     max_retries: 3,
+    #     circuit_breaker: breaker
+    #   )
+    #   vector = retryable.embed("some text")
+    class RetryableProvider
+      include Woods::Embedding::Provider::Interface
+
+      # @param provider [#embed, #embed_batch, #dimensions, #model_name] The underlying embedding provider
+      # @param max_retries [Integer] Maximum number of retry attempts
+      # @param circuit_breaker [CircuitBreaker, nil] Optional circuit breaker instance
+      def initialize(provider:, max_retries: 3, circuit_breaker: nil)
+        @provider = provider
+        @max_retries = max_retries
+        @circuit_breaker = circuit_breaker
+      end
+
+      # Embed a single text string with retry logic.
+      #
+      # @param text [String] the text to embed
+      # @return [Array<Float>] the embedding vector
+      # @raise [CircuitOpenError] if the circuit breaker is open
+      # @raise [StandardError] if all retries are exhausted
+      def embed(text)
+        with_retries { call_provider { @provider.embed(text) } }
+      end
+
+      # Embed multiple texts with retry logic.
+      #
+      # @param texts [Array<String>] the texts to embed
+      # @return [Array<Array<Float>>] array of embedding vectors
+      # @raise [CircuitOpenError] if the circuit breaker is open
+      # @raise [StandardError] if all retries are exhausted
+      def embed_batch(texts)
+        with_retries { call_provider { @provider.embed_batch(texts) } }
+      end
+
+      # Return the dimensionality of the embedding vectors.
+      #
+      # @return [Integer] number of dimensions
+      def dimensions
+        @provider.dimensions
+      end
+
+      # Return the name of the embedding model.
+      #
+      # @return [String] model name
+      def model_name
+        @provider.model_name
+      end
+
+      private
+
+      # Execute a block with retry logic and exponential backoff.
+      #
+      # @yield The block to execute
+      # @return [Object] The return value of the block
+      # @raise [CircuitOpenError] immediately without retrying
+      # @raise [StandardError] the last error if all retries are exhausted
+      def with_retries
+        attempt = 0
+        begin
+          attempt += 1
+          yield
+        rescue CircuitOpenError
+          raise
+        rescue StandardError => e
+          raise e if attempt > @max_retries
+
+          sleep((2**attempt) * 0.1)
+          retry
+        end
+      end
+
+      # Route a call through the circuit breaker if one is configured.
+      #
+      # @yield The block to execute
+      # @return [Object] The return value of the block
+      def call_provider(&block)
+        if @circuit_breaker
+          @circuit_breaker.call(&block)
+        else
+          block.call
+        end
+      end
+    end
+  end
+end