woods 2.0.1 → 2.1.0

data/lib/woods/chunking/semantic_chunker.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'chunk'
+require_relative 'contributor_chunks'
 
 module Woods
   module Chunking
@@ -181,11 +182,8 @@ module Woods
       # Default token threshold below which units stay whole.
       DEFAULT_THRESHOLD = 200
 
-      # Minimum chars-per-slice budget during tokenizer-driven recursive
-      # splitting. Prevents unbounded halving on pathological content
-      # (e.g., a single 2000-char regex line that tokenizes into 6000
-      # tokens because BERT WordPiece fragments every `\w+` boundary).
-      MIN_SLICE_CHARS = 256
+      # Stop at one Unicode character and refuse if even that cannot fit.
+      MIN_SLICE_CHARS = 1
       private_constant :MIN_SLICE_CHARS
 
       # @param threshold [Integer] Token count threshold for chunking
@@ -222,7 +220,8 @@ module Woods
       # @return [Array<Chunk>] Ordered list of chunks
       def chunk(unit)
         return [] if unit.source_code.nil? || unit.source_code.strip.empty?
-        return [build_whole_chunk(unit)] if unit.estimated_tokens <= @threshold
+        return enforce_char_limit(ContributorChunks.chunks(unit), unit) if SourceContributors.multiple?(unit)
+        return enforce_char_limit([build_whole_chunk(unit)], unit) if unit.estimated_tokens <= @threshold
 
         enforce_char_limit(chunks_for(unit), unit)
       end
@@ -247,6 +246,11 @@ module Woods
         unit.chunks = unit.chunks.flat_map { |chunk| split_oversize_hash_chunk(chunk) }
       end
 
+      def preparation_identity
+        { 'class' => self.class.name, 'contributors_version' => 1, 'threshold' => @threshold, 'max_chars' => @max_chars,
+          'max_tokens' => @max_tokens, 'counter' => @token_counter&.class&.name }
+      end
+
       private
 
       # True when either the char ceiling or the token-based verifier is
@@ -270,12 +274,20 @@ module Woods
       # @param chunk [Hash] a unit-chunk hash (symbol or string keys)
       # @return [Array<Hash>]
       def split_oversize_hash_chunk(chunk)
-        content = chunk[:content] || chunk['content']
+        chunk = chunk.transform_keys(&:to_sym)
+        content = chunk[:content]
         return [chunk] if content.nil? || !oversize?(content)
 
-        chunk_type = chunk[:chunk_type] || chunk['chunk_type'] || :whole
+        chunk_type = chunk[:chunk_type] || :whole
+        offset = SourceContributors.field(chunk[:embedding_slice], :start_byte) || 0
+        initial_offset = offset
         verified_slices(content).each_with_index.map do |slice, idx|
-          { content: slice, chunk_type: :"#{chunk_type}_part_#{idx}" }
+          first = offset
+          offset += slice.bytesize
+          metadata = ContributorChunks.slice_metadata(chunk[:metadata], content, first - initial_offset,
+                                                      offset - initial_offset)
+          chunk.merge(content: slice, chunk_type: :"#{chunk_type}_part_#{idx}", metadata: metadata,
+                      embedding_slice: { start_byte: first, end_byte: offset })
         end
       end
 
@@ -332,12 +344,16 @@ module Woods
       def split_oversize_chunk(chunk, unit)
         return [chunk] unless oversize?(chunk.content)
 
+        offset = 0
         verified_slices(chunk.content).each_with_index.map do |slice, idx|
+          first = offset
+          offset += slice.bytesize
           Chunk.new(
             content: slice,
             chunk_type: :"#{chunk.chunk_type}_part_#{idx}",
             parent_identifier: unit.identifier,
-            parent_type: unit.type
+            parent_type: unit.type,
+            metadata: ContributorChunks.slice_metadata(chunk.metadata, chunk.content, first, offset)
           )
         end
       end
@@ -359,9 +375,8 @@ module Woods
       end
 
       # Ensure a single post-line-split slice fits the token budget.
-      # Halves the char limit and reslices if it doesn't. Stops at
-      # {MIN_SLICE_CHARS} to avoid unbounded recursion on content that
-      # cannot be split line-wise (minified output, huge regex literals).
+      # Halves the character limit and reslices if necessary. A minimum-sized
+      # slice that still exceeds the counter's limit is refused, never emitted.
       #
       # @param slice [String]
       # @param char_limit [Integer]
@@ -370,7 +385,9 @@ module Woods
         return [slice] unless @token_counter.count(slice) > @max_tokens
 
         smaller = char_limit / 2
-        return [slice] if smaller < MIN_SLICE_CHARS
+        if smaller < MIN_SLICE_CHARS || slice.length <= 1
+          raise ArgumentError, 'Chunk input limit cannot fit one source character'
+        end
 
         slice_by_lines(slice, smaller).flat_map { |sub| verify_slice(sub, smaller) }
       end
@@ -385,13 +402,15 @@ module Woods
       end
 
       # Greedy line-based slicing that respects a supplied `limit`.
-      # Lines longer than `limit` are hard-cut (lossy — but such lines
-      # are already pathological: minified JSON dumps, long regexes).
+      # Lines longer than `limit` are cut at Unicode character boundaries;
+      # concatenating the slices preserves every source character.
       #
       # @param content [String]
       # @param limit [Integer]
       # @return [Array<String>]
       def slice_by_lines(content, limit = @max_chars)
+        raise ArgumentError, 'Chunk size must be positive' unless limit.positive?
+
         slices = []
         current = String.new
         content.each_line do |line|
@@ -658,6 +677,8 @@ module Woods
       include ChunkBuilder
       include LineDepthTracking
 
+      METHOD_NAME = /\A\s*def\s+((?:self\s*\.\s*)?(?:#{OPERATOR_METHOD_NAMES}|[[:word:]]+[?!=]?))/
+
       # @param unit [ExtractedUnit]
       def initialize(unit)
         @unit = unit
@@ -677,7 +698,7 @@ module Woods
       # @return [Hash]
       def parse_lines(lines)
         state = {
-          summary: [], methods: {}, private_methods: [],
+          summary: [], methods: {}, method_occurrences: Hash.new(0), private_methods: [],
           current_method: nil, depth: 0, in_private: false
         }
         lines.each do |line|
@@ -725,14 +746,16 @@ module Woods
       end
 
       def start_method(state, line)
-        method_name = line[/def\s+(?:self\.)?(\w+)/, 1] || operator_def_name(line)
+        method_name = line[METHOD_NAME, 1]&.delete(" \t")
 
         if state[:in_private]
           state[:private_methods] << line
         else
-          # Preserve insertion order — Hash does this by default, but we
-          # initialize the entry here so `build_chunks` below walks
-          # methods in source order.
+          # Repeated definitions (nested owners, singleton bodies, or inlined
+          # overrides) must never overwrite earlier source. Preserve existing
+          # keys for unique methods and number later occurrences in source order.
+          occurrence = state[:method_occurrences][method_name] += 1
+          method_name = "#{method_name}@#{occurrence}" if occurrence > 1
           state[:methods][method_name] = [line]
         end
 

data/lib/woods/console/connection_manager.rb

@@ -17,6 +17,12 @@ module Woods
     # process with a direct, Docker, or SSH command.
     class ConnectionManager
       DEFAULT_COMMAND = 'bundle exec rake woods:console'
+      MODE_OPTIONS = {
+        'direct' => %w[mode command directory],
+        'docker' => %w[mode command container],
+        'ssh' => %w[mode command host user]
+      }.freeze
+      CONFIG_KEYS = MODE_OPTIONS.values.flatten.uniq.freeze
 
       # @param config [Hash] Process-launch configuration
       # @option config [String] 'mode' direct, docker, or ssh (default: direct)
@@ -27,8 +33,9 @@ module Woods
       # @option config [String] 'user' Optional SSH user
       def initialize(config:)
         @config = config
+        validate_config!
         @mode = config.fetch('mode', 'direct')
-        @embedded_command = config.fetch('command', DEFAULT_COMMAND)
+        @embedded_command = config['command']
       end
 
       # Return the argv used to launch the embedded MCP server.
@@ -36,6 +43,7 @@ module Woods
       # @return [Array<String>]
       # @raise [ConnectionError] when the mode is invalid or incomplete
       def command
+        validate_mode_options!
         case @mode
         when 'direct' then embedded_argv
         when 'docker' then docker_command
@@ -53,10 +61,11 @@ module Woods
       # @return [void]
       # @raise [ConnectionError] when the process cannot be launched
       def replace_process!
+        argv = command
         if @mode == 'direct' && @config['directory']
-          Dir.chdir(@config['directory']) { exec(*command) }
+          Dir.chdir(@config['directory']) { exec(*argv) }
         else
-          exec(*command)
+          exec(*argv)
         end
       rescue SystemCallError, ArgumentError => e
         raise ConnectionError, "Failed to launch embedded Console MCP (#{@mode}): #{e.message}"
@@ -64,7 +73,43 @@ module Woods
 
       private
 
+      def validate_config!
+        raise ConnectionError, 'Console configuration must be a YAML mapping' unless @config.is_a?(Hash)
+        raise ConnectionError, 'Console configuration keys must be strings' unless @config.keys.all?(String)
+
+        unknown = @config.keys - CONFIG_KEYS
+        unless unknown.empty?
+          raise ConnectionError,
+                "Unsupported console.yml keys: #{unknown.map(&:inspect).join(', ')}. " \
+                "Use top-level #{CONFIG_KEYS.join(', ')} launch options; " \
+                'configure access controls and redaction in the Rails initializer.'
+        end
+
+        @config.each do |key, value|
+          next if valid_launch_string?(value)
+
+          raise ConnectionError, "Console #{key} must be a non-empty string without NUL bytes"
+        end
+      end
+
+      def valid_launch_string?(value)
+        value.is_a?(String) && !value.strip.empty? && !value.include?("\0")
+      end
+
+      def validate_mode_options!
+        accepted = MODE_OPTIONS[@mode]
+        return unless accepted
+
+        unused = @config.keys - accepted
+        return if unused.empty?
+
+        raise ConnectionError,
+              "Console options #{unused.join(', ')} are not used in #{@mode} mode; select the intended mode"
+      end
+
       def embedded_argv
+        return default_argv unless @embedded_command
+
         argv = @embedded_command.to_s.shellsplit
         raise ConnectionError, 'Console command must not be empty' if argv.empty?
 
@@ -73,6 +118,14 @@ module Woods
         raise ConnectionError, "Invalid console command: #{e.message}"
       end
 
+      def default_argv
+        if @mode == 'direct'
+          binstub = File.expand_path('bin/rake', @config.fetch('directory', Dir.pwd))
+          return [binstub, 'woods:console'] if File.file?(binstub) && File.executable?(binstub)
+        end
+        DEFAULT_COMMAND.shellsplit
+      end
+
       def docker_command
         container = @config['container'] || raise(ConnectionError, 'Docker mode requires container name')
         ['docker', 'exec', '-i', container] + embedded_argv

data/lib/woods/console/embedded_executor.rb

@@ -620,9 +620,9 @@ module Woods
 
       def handle_association_count(params)
         model = resolve_model(params['model'])
-        association_name = params['association']
+        association_name = params['association'].to_sym
         requested_scope = params['scope']
-        reflection = model.reflect_on_association(association_name.to_sym)
+        reflection = model.reflect_on_association(association_name)
 
         raise ValidationError, "Unknown association '#{association_name}' on #{params['model']}" unless reflection
 
@@ -637,13 +637,38 @@ module Woods
         # association's own model before any database I/O runs (not just
         # before the association is read): `model.find` below is itself a
         # query, and a request with a bad scope should never reach it.
-        validate_scope_columns!(requested_scope, reflection.klass.name) if requested_scope
+        validate_association_scope!(requested_scope, reflection)
 
         record = checked_relation(model).find(params['id'])
-        scope = record.public_send(association_name)
+        association = record.association(association_name)
+        return { 'count' => 0 } if empty_polymorphic_association?(association, reflection)
+
+        scope = association.scope
+        return { 'count' => 0 } unless scope
+
         scope = apply_scope(scope, requested_scope, model_name: reflection.klass.name) if requested_scope
         gate_association_sql!(scope)
-        { 'count' => scope.count }
+        { 'count' => association_count(scope, reflection) }
+      end
+
+      def validate_association_scope!(scope, reflection)
+        return unless scope
+
+        if reflection.respond_to?(:polymorphic?) && reflection.polymorphic?
+          raise ValidationError, 'Rejected: scoped polymorphic association counts require a concrete target model.'
+        end
+
+        validate_scope_columns!(scope, reflection.klass.name)
+      end
+
+      def empty_polymorphic_association?(association, reflection)
+        reflection.respond_to?(:polymorphic?) && reflection.polymorphic? && association.klass.nil?
+      end
+
+      def association_count(scope, reflection)
+        return scope.count if reflection.collection?
+
+        scope.exists? ? 1 : 0
       end
 
       # Materialize a model's default scope once, inspect the resolved SQL,

data/lib/woods/console/rack_middleware.rb

@@ -73,6 +73,12 @@ module Woods
     # disabled when the host requires a narrower database capability.
     #
     class RackMiddleware # rubocop:disable Metrics/ClassLength
+      EAGER_LOAD_UNAVAILABLE = JSON.generate(
+        jsonrpc: '2.0', id: nil,
+        error: { code: -32_000,
+                 message: 'Console unavailable: Rails eager loading failed. ' \
+                          'Fix the application load error and restart the server.' }
+      ).freeze
       # @param app [#call] The next Rack app in the middleware stack
       # @param path [String] URL path to mount the MCP endpoint (default: '/mcp/console')
       # @param embedded_read_tools [Boolean, #call] Enable sql/query tools in
@@ -118,6 +124,11 @@ module Woods
 
       def handle_request(env)
         transport = ensure_transport
+        unless transport
+          return [503, { 'content-type' => 'application/json', 'cache-control' => 'no-store' },
+                  [EAGER_LOAD_UNAVAILABLE]]
+        end
+
         request_env = env.dup
         request_env.delete('HTTP_MCP_SESSION_ID') if @stateless_mode
         transport.handle_request(Rack::Request.new(request_env))
@@ -168,14 +179,16 @@ module Woods
       # @return [::MCP::Server::Transports::StreamableHTTPTransport]
       def ensure_transport
         return @transport if @transport
+        return if @eager_load_failed
 
         @mutex.synchronize do
           return @transport if @transport
+          return if @eager_load_failed
 
           check_blocked_tables_config!
 
           require 'woods/console/server'
-          Rails.application.eager_load!
+          return unless eager_load_application
 
           server = build_embedded_server
           @stateless_mode = resolve_deferred(@stateless)
@@ -187,6 +200,21 @@ module Woods
         end
       end
 
+      # A failed loader may have registered only part of the application.
+      # Keep this worker unavailable rather than retrying against partial state.
+      def eager_load_application
+        Rails.application.eager_load!
+        true
+      rescue NameError => e
+        @eager_load_failed = true
+        structured_logger.error(
+          'console.eager_load.failed', error_class: e.class.name,
+                                       remediation: 'Run Rails.application.eager_load! in the application ' \
+                                                    'environment; fix the error and restart.'
+        )
+        false
+      end
+
       # Emit a prominent warning (or raise in production) when the Console MCP
       # is enabled but no tables are blocked. An empty block list means Layer 1
       # of the defense stack is fully inactive — every table in the database is

data/lib/woods/dependency_graph.rb

@@ -2,6 +2,7 @@
 
 require 'set'
 require 'json'
+require_relative 'source_contributors'
 
 module Woods
   # DependencyGraph tracks relationships between code units for:
@@ -32,7 +33,7 @@ module Woods
     # enforce_dependencies: package units (Task 7)
     # commit_count, change_frequency: git enrichment (Task 5)
     NODE_ATTRIBUTE_KEYS = %i[
-      database table foreign_key_tables package enforce_dependencies commit_count change_frequency kind
+      database table foreign_key_tables package enforce_dependencies commit_count change_frequency kind source_paths
     ].freeze
 
     # These extractors describe a whole source file rather than one constant.
@@ -86,7 +87,9 @@ module Woods
 
       (@edges[unit.identifier] ||= {})[unit.type] =
         self.class.normalize_edges(unit.dependencies, strict: true)
-      (@file_map[unit.file_path] ||= Set.new).add(unit.identifier) if unit.file_path
+      node_paths(@nodes[unit.identifier][unit.type]).each do |path|
+        (@file_map[path] ||= Set.new).add(unit.identifier)
+      end
 
       # Type index for filtering (Set-based for O(1) insert)
       (@type_index[unit.type] ||= Set.new).add(unit.identifier)
@@ -126,7 +129,7 @@ module Woods
         old_node = @nodes[identifier]&.[](t)
         next unless old_node
 
-        drop_from_file_map(identifier, old_node[:file_path], withdrawing)
+        node_paths(old_node).each { |path| drop_from_file_map(identifier, path, withdrawing) }
         drop_from_type_index(identifier, old_node[:type])
       end
     end
@@ -187,7 +190,7 @@ module Woods
       return unless path
 
       return if (@nodes[identifier] || {}).any? do |type, node|
-        !withdrawing.include?(type) && node[:file_path] == path
+        !withdrawing.include?(type) && node_paths(node).include?(path)
       end
 
       return unless (ids = @file_map[path])
@@ -425,8 +428,9 @@ module Woods
     def units_for_path(file_path)
       (@file_map[file_path] || []).flat_map do |identifier|
         nodes = sorted_nodes(@nodes[identifier] || {})
-        at_path = nodes.select { |_, node| node[:file_path] == file_path }
-        (at_path.empty? ? nodes : at_path).map { |type, _| [identifier, type] }
+        at_path = nodes.select { |_, node| node_paths(node).include?(file_path) }
+        legacy = at_path.empty? && nodes.none? { |_, node| node.key?(:source_paths) }
+        (legacy ? nodes : at_path).map { |type, _| [identifier, type] }
       end
     end
 
@@ -640,6 +644,13 @@ module Woods
       @suffix_groups = groups
     end
 
+    # @param node [Hash] one typed graph node
+    # @return [Array<String>] every registered physical source
+    def node_paths(node)
+      node[:source_paths] || Array(node[:file_path])
+    end
+    private :node_paths
+
     # Node attributes a unit's metadata supplies at registration time.
     #
     # `table` is taken only from model units and `enforce_dependencies` only
@@ -655,6 +666,11 @@ module Woods
       attrs[:table] = metadata[:table_name] if unit.type == :model && !metadata[:table_name].nil?
       tables = Array(metadata[:foreign_keys]).filter_map { |fk| fk[:to_table] || fk['to_table'] if fk.is_a?(Hash) }
       attrs[:foreign_key_tables] = tables if tables.any?
+      if SourceContributors.multiple?(unit)
+        attrs[:source_paths] = SourceContributors.paths(unit).map do |path|
+          self.class.absolutize(path, self.class.graph_root)
+        end
+      end
       attrs[:package] = metadata[:package] unless metadata[:package].nil?
       if unit.type == :package && !metadata[:enforce_dependencies].nil?
         attrs[:enforce_dependencies] = metadata[:enforce_dependencies]
@@ -928,11 +944,18 @@ module Woods
       File.join(root, path)
     end
 
+    def self.relocate_node_paths(node, &block)
+      result = node.dup
+      result[:file_path] = yield(node[:file_path]) if node[:file_path]
+      result[:source_paths] = node[:source_paths].map(&block) if node[:source_paths]
+      result
+    end
+
     def self.relativize_nodes(nodes, root)
       return nodes if root.nil?
 
       nodes.transform_values do |node|
-        node[:file_path] ? node.merge(file_path: relativize(node[:file_path], root)) : node
+        relocate_node_paths(node) { |path| relativize(path, root) }
       end
     end
 
@@ -940,7 +963,7 @@ module Woods
       return nodes if root.nil?
 
       nodes.transform_values do |node|
-        node[:file_path] ? node.merge(file_path: absolutize(node[:file_path], root)) : node
+        relocate_node_paths(node) { |path| absolutize(path, root) }
       end
     end
 
@@ -950,7 +973,7 @@ module Woods
       return variants if root.nil?
 
       variants.map do |record|
-        record[:file_path] ? record.merge(file_path: relativize(record[:file_path], root)) : record
+        relocate_node_paths(record) { |path| relativize(path, root) }
       end
     end
 
@@ -989,7 +1012,7 @@ module Woods
     # @return [Object]
     def self.normalize_node_attribute(key, value)
       case key
-      when :foreign_key_tables then Array(value).map(&:to_s).uniq.sort
+      when :source_paths, :foreign_key_tables then Array(value).map(&:to_s).uniq.sort
       when :commit_count then value.to_i
       when :enforce_dependencies then [true, false].include?(value) ? value : value.to_s
       else value.to_s
@@ -1124,6 +1147,7 @@ module Woods
           file_path: absolutize(record[:file_path] || record['file_path'], root),
           namespace: record[:namespace] || record['namespace']
         }.merge(persisted_node_attributes(record))
+        nodes[identifier][type] = relocate_node_paths(nodes[identifier][type]) { |path| absolutize(path, root) }
         (edges[identifier] ||= {})[type] = normalize_edges(record[:edges] || record['edges'])
       end
     end

data/lib/woods/embedding/fake.rb

@@ -89,6 +89,18 @@ module Woods
           @dims
         end
 
+        alias configured_dimensions dimensions
+
+        # @return [Array] deterministic, non-secret embedding configuration
+        def cache_identity
+          [self.class.name, @model, @dims]
+        end
+
+        # Pure constructor settings for restoring the deterministic provider.
+        def configuration_options
+          { model: @model, dims: @dims }
+        end
+
         # @return [String] the configured model name (default
         #   {DEFAULT_MODEL_NAME})
         def model_name