woods 2.0.1 → 2.1.0

data/lib/woods/source_references/prism_adapter.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'prism'
+
+module Woods
+  module SourceReferences
+    # Retains AST context that the general Woods flow AST intentionally omits.
+    class PrismAdapter
+      KINDS = { class_node: :declaration, module_node: :declaration, constant_read_node: :constant,
+                constant_path_node: :constant, singleton_class_node: :singleton, def_node: :method }.freeze
+      CONSTANT_WRITES = %i[
+        constant_write_node constant_path_write_node constant_operator_write_node constant_path_operator_write_node
+        constant_and_write_node constant_path_and_write_node constant_or_write_node constant_path_or_write_node
+      ].freeze
+      DYNAMIC_BLOCK_METHODS = %i[class_eval module_eval instance_eval class_exec module_exec instance_exec].freeze
+
+      def parse(source)
+        result = Prism.parse(source)
+        error = result.errors.first
+        [result.value, error && { 'message' => error.message, 'line' => error.location.start_line }]
+      end
+
+      def kind(node)
+        return KINDS[node.type] if KINDS.key?(node.type)
+
+        case node.type
+        when :constant_write_node, :constant_path_write_node then value_constructor(node) ? :value_class : :other
+        when :call_node then dynamic_scope?(node) ? :dynamic_scope : :other
+        else :other
+        end
+      end
+
+      def constant_name(node)
+        return unless node
+        return node.name.to_s if node.type == :constant_read_node
+        return unless node.type == :constant_path_node
+
+        parent = node.parent ? constant_name(node.parent) : ''
+        name = node.respond_to?(:name) ? node.name : node.child.name
+        "#{parent}::#{name}" if parent
+      end
+
+      def children(node)
+        return [node.value].compact if CONSTANT_WRITES.include?(node.type)
+        return [] if %i[constant_target_node constant_path_target_node].include?(node.type)
+        return [node.value].compact if node.type == :multi_write_node
+        return [node.parameters, node.body].compact if node.type == :def_node
+
+        node.compact_child_nodes
+      end
+
+      def value_constructor(node)
+        call = node.value
+        return unless call&.type == :call_node
+
+        name = constant_name(call.receiver)
+        name if { new: %w[Struct ::Struct], define: %w[Data ::Data] }.fetch(call.name, []).include?(name)
+      end
+
+      def assignment_name(node)
+        node.type == :constant_write_node ? node.name.to_s : constant_name(node.target)
+      end
+
+      def declaration_name(node)
+        constant_name(node.constant_path)
+      end
+
+      def declaration_kind(node)
+        node.type == :class_node ? 'class' : 'module'
+      end
+
+      def superclass(node)
+        node.superclass if node.type == :class_node
+      end
+
+      def body(node)
+        node.body
+      end
+
+      def self_receiver?(node)
+        node.expression.type == :self_node
+      end
+
+      def local_method?(node)
+        node.receiver.nil? || node.receiver.type == :self_node
+      end
+
+      def line(node)
+        node.location.start_line
+      end
+
+      def end_line(node)
+        node.location.end_line
+      end
+
+      private
+
+      def dynamic_scope?(node)
+        return false unless node.block&.type == :block_node
+        return true if DYNAMIC_BLOCK_METHODS.include?(node.name)
+
+        foreign_method?(node) || anonymous_class?(node.name, node.receiver)
+      end
+
+      def foreign_method?(node)
+        %i[define_method define_singleton_method].include?(node.name) &&
+          node.receiver && node.receiver.type != :self_node
+      end
+
+      def anonymous_class?(method, receiver)
+        name = constant_name(receiver)&.delete_prefix('::')
+        { new: %w[Class Module Struct], define: ['Data'] }.fetch(method, []).include?(name)
+      end
+    end
+  end
+end

data/lib/woods/source_references/registry.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative 'runtime_lookup'
+require_relative 'value_class'
+require_relative '../source_contributors'
+
+module Woods
+  module SourceReferences
+    # Maps verified source declarations to extracted constant-owned units.
+    # File-profile and other non-constant identities are never resolution targets.
+    class Registry # rubocop:disable Metrics/ClassLength -- keep runtime, source and autoload ownership checks together
+      TYPES = %i[model controller service poro lib concern job mailer component view_component
+                 graphql_type graphql_mutation graphql_resolver graphql_query serializer manager
+                 policy validator pundit_policy decorator action_cable_channel].freeze
+
+      # @param units [Array<ExtractedUnit, Hash>] current complete typed unit set
+      # @param sources [Hash{String => Hash}] path to collector result
+      # @param root [String, Pathname] application root
+      def initialize(units:, sources:, root:)
+        @root = File.expand_path(root.to_s)
+        @lookup = RuntimeLookup.new
+        @sources = sources.to_h { |path, result| [absolute(path), result] }
+        @all_types = units.group_by { |unit| field(unit, :identifier) }
+        @entries = units.flat_map { |unit| SourceContributors.paths(unit).filter_map { |path| entry(unit, path) } }
+        @owners = @entries.group_by { |record| [record[:path], record[:identifier]] }
+        @targets = @entries.group_by { |record| record[:identifier] }
+      end
+
+      # @param reference [Hash] JSON-compatible collector reference record
+      # @param file_path [String] source containing the reference
+      # @return [Hash, nil] a dependency, or nil for an unresolved reference
+      def resolve(reference, file_path:)
+        result = explain(reference, file_path: file_path)
+        return unless result['status'] == 'resolved'
+
+        { type: result.fetch('type').to_sym, target: result.fetch('target'), via: :code_reference }
+      end
+
+      # @param reference [Hash] collected spelling, owner and lexical nesting
+      # @param file_path [String] original source path
+      # @return [Hash] JSON-compatible resolution or explicit unresolved reason
+      def explain(reference, file_path:)
+        return unresolved('unverified_owner') unless owner?(reference['owner'], file_path: file_path)
+
+        return unresolved('unsupported_singleton_scope') if reference.fetch('singleton_depth', 0).positive?
+
+        result = @lookup.call(reference['name'], nesting: reference.fetch('nesting', []))
+        target = result[:target] || autoload_target(result) || source_only_target(reference, result)
+        return unresolved(result[:reason] || 'constant_missing') unless target
+
+        target_result(target, owner: reference['owner'])
+      end
+
+      # @param identifier [String] source declaration identity
+      # @param file_path [String] original source path
+      # @return [Boolean] whether exactly one extracted type owns the declaration
+      def owner?(identifier, file_path:)
+        records = @owners[[absolute(file_path), identifier]]
+        records && !records.empty? && !ambiguous?(identifier)
+      end
+
+      private
+
+      def target_result(target, owner:)
+        return unresolved('ambiguous_target') if ambiguous?(target)
+
+        entries = @targets[target]
+        return unresolved('target_not_indexed') unless entries&.any?
+        return unresolved('self_reference') if target == owner
+
+        { 'status' => 'resolved', 'target' => target, 'type' => entries.first[:type].to_s }
+      end
+
+      def entry(unit, path)
+        type = field(unit, :type)&.to_sym
+        return unless TYPES.include?(type)
+
+        identifier = field(unit, :identifier)
+        return unless eligible_identity?(identifier, path)
+
+        path = absolute(path)
+        source = @sources[path]
+        return unless verified_declaration?(source, identifier, type, path)
+
+        { identifier: identifier, type: type, path: path }
+      end
+
+      def eligible_identity?(identifier, path)
+        path && identifier.is_a?(String) && RuntimeLookup::CONSTANT.match?(identifier)
+      end
+
+      def verified_declaration?(source, identifier, type, path)
+        return false unless source && source['parse_error'].nil?
+
+        source.fetch('declarations', []).any? { |decl| declaration?(decl, identifier, type, path) }
+      end
+
+      def declaration?(declaration, identifier, type, path)
+        return false unless declaration['owner'] == identifier
+        return false if declaration.fetch('singleton_depth', 0).positive?
+
+        return ValueClass.new.call(declaration, file_path: path) == identifier if declaration['constructor']
+
+        result = @lookup.call(declaration['name'], nesting: declaration.fetch('enclosing_nesting', []),
+                                                   allow_private: true)
+        return runtime_declaration?(declaration, identifier, result) if result[:status] == :resolved
+
+        source_declaration?(declaration, identifier, type, path)
+      end
+
+      def source_declaration?(declaration, identifier, type, path)
+        return false unless type == :lib && static_declaration?(declaration, identifier)
+
+        root_result = @lookup.call("::#{identifier}", allow_private: true)
+        root_result[:status] == :missing || autoload_declaration?(root_result, identifier, path)
+      end
+
+      def runtime_declaration?(declaration, identifier, result)
+        kind = @lookup.class_object?(result[:value]) ? 'class' : 'module'
+        result[:target] == identifier && declaration['kind'] == kind
+      end
+
+      def static_declaration?(declaration, identifier)
+        name = declaration['name']
+        return false unless name.is_a?(String) && RuntimeLookup::CONSTANT.match?(name)
+        return name.delete_prefix('::') == identifier if name.start_with?('::')
+
+        nesting = declaration.fetch('enclosing_nesting', [])
+        return name == identifier if nesting.empty?
+
+        !name.include?('::') && [nesting.first, name].join('::') == identifier
+      end
+
+      def autoload_declaration?(result, identifier, path)
+        registered = result[:autoload_path]
+        result[:pending_target] == identifier && registered.is_a?(String) &&
+          Pathname.new(registered).absolute? && absolute(registered) == path
+      end
+
+      def autoload_target(result)
+        name = result[:pending_target]
+        candidates = @targets[name]
+        return unless candidates&.any?
+
+        name if candidates.all? { |entry| entry[:type] == :lib && autoload_declaration?(result, name, entry[:path]) }
+      end
+
+      def source_only_target(reference, result)
+        return unless result[:status] == :missing
+
+        return unless reference['name'].to_s.start_with?('::') || result[:root_lookup]
+
+        name = reference['name'].to_s.delete_prefix('::')
+        candidates = @targets[name]
+        name if candidates&.all? { |entry| entry[:type] == :lib }
+      end
+
+      def ambiguous?(identifier)
+        @all_types.fetch(identifier, []).map { |unit| field(unit, :type).to_s }.uniq.size > 1
+      end
+
+      def field(unit, name)
+        return unit.public_send(name) unless unit.is_a?(Hash)
+
+        unit.key?(name) ? unit[name] : unit[name.to_s]
+      end
+
+      def absolute(path)
+        File.expand_path(path.to_s, @root)
+      end
+
+      def unresolved(reason)
+        { 'status' => 'unresolved', 'reason' => reason }
+      end
+    end
+  end
+end

data/lib/woods/source_references/runtime_lookup.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Woods
+  module SourceReferences
+    # Reads already-loaded constant tables without invoking application overrides,
+    # const_missing, or an autoload. Results are scoped to one extraction run.
+    class RuntimeLookup
+      CORE_TYPE = Module.instance_method(:===)
+      CORE_EQUAL = BasicObject.instance_method(:equal?)
+      CONSTANT = /\A(?:::)?[[:upper:]][[:word:]]*(?:::[[:upper:]][[:word:]]*)*\z/
+      REFLECTION = %i[const_defined? const_get autoload? ancestors name constants].to_h do |method|
+        [method, Module.instance_method(method)]
+      end.freeze
+
+      # @param name [String] a literal constant path
+      # @param nesting [Array<String>] lexical scopes, innermost first
+      # @return [Hash] lookup status and canonical target or unresolved reason
+      def call(name, nesting: [], allow_private: false)
+        return unknown('invalid_constant') unless valid_name?(name)
+
+        parts = name.delete_prefix('::').split('::')
+        scopes = name.start_with?('::') ? { scopes: [Object] } : lexical_scopes(nesting)
+        return scopes unless scopes[:scopes]
+
+        result = first_constant(scopes[:scopes], parts.shift, public_only: name.start_with?('::') && !allow_private)
+        parts.each do |part|
+          return result.except(:pending_target, :autoload_path) unless module_object?(result[:value])
+
+          result = first_constant(qualified_scopes(result[:value]), part, public_only: !allow_private)
+        end
+        result
+      end
+
+      # @param scope [Module] runtime module to inspect
+      # @param method [Symbol] one of the bound core reflection methods
+      # @return [Object] core reflection result
+      def reflect(scope, method, *args)
+        REFLECTION.fetch(method).bind(scope).call(*args)
+      end
+
+      # @return [Boolean] core class/module checks that cannot dispatch to application overrides
+      def module_object?(value)
+        CORE_TYPE.bind(Module).call(value)
+      end
+
+      # @return [Boolean] whether a runtime object is a class
+      def class_object?(value)
+        CORE_TYPE.bind(Class).call(value)
+      end
+
+      private
+
+      def valid_name?(name)
+        name.is_a?(String) && CONSTANT.match?(name)
+      end
+
+      def identical?(left, right)
+        CORE_EQUAL.bind(left).call(right)
+      end
+
+      def qualified_scopes(receiver)
+        ancestors = reflect(receiver, :ancestors)
+        return [receiver, *ancestors] if identical?(receiver, Object)
+
+        [receiver, *ancestors.take_while { |ancestor| !identical?(ancestor, Object) }]
+      end
+
+      def lexical_scopes(nesting)
+        return { scopes: [Object] } if nesting.empty?
+
+        modules = nesting.map do |name|
+          result = call("::#{name}", allow_private: true)
+          return unknown('unloaded_scope') unless module_object?(result[:value])
+
+          result[:value]
+        end
+        ancestors = reflect(modules.first, :ancestors)
+        ancestors += [Object] unless class_object?(modules.first)
+        { scopes: modules + ancestors }
+      end
+
+      def first_constant(scopes, name, public_only: false)
+        scopes.each do |scope|
+          next unless reflect(scope, :const_defined?, name, false)
+          return unknown('private_constant') if private_access?(scope, name, public_only)
+
+          autoload_path = reflect(scope, :autoload?, name, false)
+          return pending_autoload(scope, name, autoload_path) if autoload_path
+
+          return constant_value(scope, name)
+        end
+        { status: :missing, reason: 'constant_missing', root_lookup: scopes.any? { |scope| identical?(scope, Object) } }
+      rescue NameError
+        unknown('constant_changed')
+      end
+
+      # Expose registration evidence without evaluating the source file. Only
+      # Registry may promote it, after matching a captured library declaration.
+      def pending_autoload(scope, name, path)
+        namespace = identical?(scope, Object) ? nil : reflect(scope, :name)
+        return unknown('autoload_pending') if namespace.nil? && !identical?(scope, Object)
+
+        unknown('autoload_pending').merge(pending_target: [namespace, name].compact.join('::'), autoload_path: path)
+      end
+
+      def private_access?(scope, name, public_only)
+        public_only && !reflect(scope, :constants, false).include?(name.to_sym)
+      end
+
+      def constant_value(scope, name)
+        value = reflect(scope, :const_get, name, false)
+        return unknown('non_module_constant') unless module_object?(value)
+
+        canonical = reflect(value, :name)
+        namespace = identical?(scope, Object) ? nil : reflect(scope, :name)
+        expected = [namespace, name].compact.join('::')
+        return unknown('constant_alias') unless canonical == expected
+
+        { status: :resolved, target: canonical, value: value }
+      end
+
+      def unknown(reason)
+        { status: :unknown, reason: reason }
+      end
+    end
+  end
+end

data/lib/woods/source_references/value_class.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative 'runtime_lookup'
+
+module Woods
+  module SourceReferences
+    # Verifies literal value-class assignment evidence against loaded Ruby state.
+    # Bound core methods avoid application reflection overrides and never run a
+    # constructor, autoload, const_missing, or an application method body.
+    class ValueClass
+      SOURCE_LOCATION = Module.instance_method(:const_source_location)
+      SINGLETON_CLASS = Object.instance_method(:singleton_class)
+      INSTANCE_METHOD = Module.instance_method(:instance_method)
+      METHOD_OWNER = UnboundMethod.instance_method(:owner)
+      METHOD_SOURCE = UnboundMethod.instance_method(:source_location)
+
+      def initialize
+        @lookup = RuntimeLookup.new
+      end
+
+      # @param declaration [Hash] collector declaration with a literal constructor
+      # @param file_path [String] original file containing the assignment
+      # @return [String, nil] canonical, source-owned class identity
+      def call(declaration, file_path:)
+        return unless candidate?(declaration)
+
+        factory = factory(declaration)
+        return unless factory
+
+        result = @lookup.call(declaration['name'], nesting: declaration['enclosing_nesting'], allow_private: true)
+        return unless value_class?(result, declaration, factory)
+        return unless owns_assignment?(result[:target], declaration, file_path)
+
+        result[:target]
+      rescue NameError, TypeError, ArgumentError
+        nil
+      end
+
+      private
+
+      def candidate?(declaration)
+        declaration['constructor'] && declaration.fetch('singleton_depth', 0).zero?
+      end
+
+      def value_class?(result, declaration, factory)
+        result[:target] == declaration['owner'] && @lookup.class_object?(result[:value]) &&
+          @lookup.reflect(result[:value], :ancestors).any? { |ancestor| identical?(ancestor, factory) }
+      end
+
+      def factory(declaration)
+        name = declaration['constructor']
+        core_name = name.delete_prefix('::')
+        return unless %w[Struct Data].include?(core_name)
+
+        actual = @lookup.call(name, nesting: declaration['enclosing_nesting'])[:value]
+        core = @lookup.call("::#{core_name}")[:value]
+        return unless core && identical?(actual, core)
+
+        singleton = SINGLETON_CLASS.bind(core).call
+        method = INSTANCE_METHOD.bind(singleton).call(core_name == 'Struct' ? :new : :define)
+        return unless identical?(METHOD_OWNER.bind(method).call, singleton) && METHOD_SOURCE.bind(method).call.nil?
+
+        core
+      end
+
+      def owns_assignment?(identifier, declaration, file_path)
+        parts = identifier.split('::')
+        name = parts.pop
+        scope = parts.empty? ? Object : @lookup.call("::#{parts.join('::')}", allow_private: true)[:value]
+        return false unless @lookup.module_object?(scope)
+
+        location = SOURCE_LOCATION.bind(scope).call(name, false)
+        location && File.expand_path(location.first) == File.expand_path(file_path) &&
+          location.last.between?(declaration['line'], declaration['end_line'])
+      end
+
+      def identical?(left, right)
+        RuntimeLookup::CORE_EQUAL.bind(left).call(right)
+      end
+    end
+  end
+end

data/lib/woods/storage/metadata_store.rb

@@ -115,7 +115,10 @@ module Woods
           raise NotImplementedError
         end
 
-        # Every stored identifier.
+        # Every stored identity, including source-empty records without vectors.
+        # Return internal typed keys unchanged; do not collapse same-name units
+        # to their shared public identifier. Embedding reconciliation uses this
+        # inventory independently of the optional snapshot #each_entry seam.
         #
         # Used by the evaluation harness's {Woods::Evaluation::BaselineRunner}
         # to build naive baselines (grep/random/file-level) to score the real

data/lib/woods/storage/qdrant.rb

@@ -193,8 +193,8 @@ module Woods
         def self.validate_host_visibility!(host, allow_private_hosts:)
           return if allow_private_hosts
 
-          # Canonicalize (strip port, trailing dot, IPv6 brackets) via
-          # the shared helper so Qdrant and OriginGuard stay in sync.
+          # Canonicalize URL hosts before applying the numeric-host checks
+          # also used by the HTTP origin policy.
           canonical = Util::HostGuard.canonicalize(host)
 
           # Non-canonical numeric hosts (hex `0x7f000001`, octal

data/lib/woods/unblocked/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'set'
 require 'net/http'
 require 'uri'
 require 'woods'
@@ -145,9 +146,12 @@ module Woods
         query = "limit=#{limit}"
         query += "&after=#{URI.encode_www_form_component(after)}" if after
         result = request(:get, "documents?#{query}")
-        return result if result.is_a?(Array)
+        page = result.is_a?(Array) ? result : result.is_a?(Hash) && (result['items'] || result['data'])
+        unless page.is_a?(Array) && page.all?(Hash)
+          raise Woods::Error, 'Unblocked document inventory incomplete: malformed page'
+        end
 
-        result['items'] || result['data'] || []
+        page
       end
 
       # List every document in a collection, paging until exhausted.
@@ -160,20 +164,21 @@ module Woods
       def all_documents(collection_id:)
         docs = []
         after = nil
+        seen_cursors = Set.new
 
         loop do
           page = list_documents(limit: PAGE_SIZE, after: after)
           break if page.empty?
 
           docs.concat(page)
-          break if page.size < PAGE_SIZE
-
           after = page.last['id']
-          # A full page with no cursor id would refetch page 1 forever —
-          # stop with what we have rather than loop against the budget.
-          break if after.nil?
+          unless after.is_a?(String) && !after.empty? && seen_cursors.add?(after)
+            raise Woods::Error, 'Unblocked document inventory incomplete: missing or repeated pagination cursor'
+          end
         end
 
+        return docs if collection_id.nil?
+
         docs.select { |doc| doc['collectionId'] == collection_id }
       end
 

data/lib/woods/unblocked/document_builder.rb

@@ -28,6 +28,9 @@ module Woods
         @ref = normalize_ref(ref)
       end
 
+      # @return [String] normalized branch/ref used in citation and ownership identity
+      attr_reader :ref
+
       # Ref used when the index does not say which one it came from.
       DEFAULT_REF = 'main'
 
@@ -60,7 +63,7 @@ module Woods
         file_path = unit_data['file_path']
         return @repo_url unless file_path
 
-        "#{@repo_url}/blob/#{@ref}/#{encode_path(file_path)}"
+        "#{@repo_url}/blob/#{encode_path(@ref)}/#{encode_path(file_path)}"
       end
 
       private