woods 2.0.1 → 2.1.0

data/lib/woods/extractors/graphql_extractor.rb

@@ -5,19 +5,20 @@ require_relative '../source_inputs/consumer_errors'
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
 require_relative 'source_nesting'
+require_relative '../source_references/runtime_lookup'
 
 module Woods
   module Extractors
-    # GraphQLExtractor handles graphql-ruby type and mutation extraction.
+    # GraphQLExtractor handles graphql-ruby schema, type and mutation extraction.
     #
     # GraphQL schemas are rich in structure — types, fields, arguments,
     # resolvers, and mutations form a typed API layer over the domain.
     # We extract these with runtime introspection when available (via
-    # `GraphQL::Schema.types`) and fall back to file-based discovery
-    # when the schema isn't fully loadable.
+    # `GraphQL::Schema.types`) and retain limited file-based discovery
+    # when graphql-ruby is unavailable.
     #
     # We extract:
-    # - Object types, input types, enum types, interface types, union types, scalar types
+    # - Schema classes and object, input, enum, interface, union and scalar types
     # - Mutations and their arguments/return fields
     # - Query fields and resolvers
     # - Standalone resolver classes
@@ -43,28 +44,38 @@ module Woods
 
       def initialize
         @graphql_dir = defined?(Rails) ? Rails.root.join(GRAPHQL_DIRECTORY) : nil
-        @schema_class = find_schema_class
+        @runtime_lookup = SourceReferences::RuntimeLookup.new
+        @runtime_discovery_complete = true
+        @schema_classes = find_schema_classes
+        @query_roots = []
         @runtime_types = load_runtime_types
       end
 
-      # The type classes runtime introspection can reach.
-      #
-      # Shared with the incremental path's class reconciliation (#167), which
-      # uses it for **additions only**. A runtime-defined type — built by a
-      # schema builder or a DSL rather than a literal `class ... <
-      # Types::BaseObject` — has no source file, so no changed path ever
-      # dispatches to it and `extract_graphql_file` cannot reproduce it. Only a
-      # full extraction emitted such units, which meant an incremental run
-      # could never create them and an index built incrementally from empty
-      # never had them at all.
+      # Current application schemas and the named type classes they expose.
+      # Incremental reconciliation adds runtime-defined units that the file
+      # pass cannot discover and updates known types whose query-root role
+      # changed. It does not infer removals from absence in this inventory.
       #
       # Empty when graphql-ruby is not loaded or the app has no schema, which is
       # why the reconciliation must not read absence here as deletion — see
       # `reconcile_removals: false` in {Extractor::CLASS_BASED_DISCOVERY}.
       #
-      # @return [Array<Class>]
+      # @return [Array<Class, Module>]
       def discoverable_classes
-        @runtime_types.values.reject { |type_class| type_class.name.nil? }
+        (@schema_classes + @runtime_types.values).uniq(&:name)
+      end
+
+      # @return [Boolean] whether every discovered schema exposed its inventory
+      def runtime_discovery_complete?
+        @runtime_discovery_complete
+      end
+
+      # Shared with incremental reconciliation when a schema changes the role
+      # of an unchanged type (ordinary object versus query root).
+      # @param klass [Class, Module] current loaded GraphQL declaration
+      # @return [Symbol, nil] existing public GraphQL unit type
+      def runtime_unit_type(klass)
+        classify_runtime_type(klass) if current_runtime_class?(klass) && graphql_runtime_class?(klass)
       end
 
       # Extract all GraphQL types, mutations, queries, and resolvers
@@ -72,28 +83,24 @@ module Woods
       # Returns an empty array when the app has neither an `app/graphql`
       # directory nor a loadable schema class.
       #
-      # Deliberately **not** gated on graphql-ruby being loaded. The file pass
-      # is static — a regex over source plus a `safe_constantize` that is
-      # allowed to fail — so it works perfectly well without the gem, and
-      # `app/graphql/*.rb` is real source an agent wants indexed either way.
-      # Gating it produced a genuine full-vs-incremental divergence: the
-      # `PathDispatcher` rule routes those paths at `extract_graphql_file`,
-      # which never had the gate, so an app whose GraphQL gem was not loaded at
-      # extraction time got its types indexed incrementally and dropped by a
-      # full run. Runtime introspection stays optional and additive — it makes
-      # the units richer when the gem is there, it does not decide whether they
-      # exist.
+      # Without graphql-ruby, the file pass retains its limited source-form
+      # fallback. With loaded declarations, verified GraphQL ancestry governs
+      # admission, alongside legacy Ruby Resolvers::Base helpers; unresolved
+      # constants are never autoloaded by this extractor.
       #
       # @return [Array<ExtractedUnit>] List of GraphQL units
       def extract_all
+        unless runtime_discovery_complete?
+          raise Woods::ExtractionError, 'GraphQL runtime discovery incomplete; fix the logged schema error and retry'
+        end
         return [] unless graphql_source_present?
 
         units = []
         seen_identifiers = Set.new
 
         # First pass: runtime introspection (most accurate)
-        if @runtime_types.any?
-          @runtime_types.each_value do |type_class|
+        if discoverable_classes.any?
+          discoverable_classes.each do |type_class|
             unit = extract_from_runtime_type(type_class)
             next unless unit
             next if seen_identifiers.include?(unit.identifier)
@@ -103,7 +110,7 @@ module Woods
           end
         end
 
-        # Second pass: file-based discovery (catches everything)
+        # Second pass: governed declarations, including unattached resolvers.
         if @graphql_dir&.directory?
           Dir[@graphql_dir.join('**/*.rb')].each do |file_path|
             unit = extract_graphql_file(file_path)
@@ -124,13 +131,16 @@ module Woods
       # @return [ExtractedUnit, nil] The extracted unit, or nil if the file
       #   does not contain a recognizable GraphQL class
       def extract_graphql_file(file_path)
+        SourceInputs::ConsumerErrors.record(self) unless runtime_discovery_complete?
         source = File.read(file_path)
         class_name = extract_class_name(file_path, source)
 
         return nil unless class_name
-        return nil unless graphql_class?(source)
 
-        runtime_class = class_name.safe_constantize
+        runtime_class = loaded_graphql_constant(class_name)
+        return nil if runtime_class && !graphql_runtime_class?(runtime_class) && !ruby_resolver_helper?(runtime_class)
+        return nil unless runtime_class || graphql_class?(source)
+
         # Classify from the resolved runtime class first, matching
         # {#extract_from_runtime_type}'s classifier. Keeps the two passes
         # from disagreeing on a type's unit_type (a mutation that looks like
@@ -173,9 +183,11 @@ module Woods
       # @param type_class [Class] A graphql-ruby type class
       # @return [ExtractedUnit, nil]
       def extract_from_runtime_type(type_class)
+        SourceInputs::ConsumerErrors.record(self) unless runtime_discovery_complete?
         return nil unless type_class.respond_to?(:name) && type_class.name
         # Skip anonymous or internal graphql-ruby classes
         return nil if type_class.name.start_with?('GraphQL::')
+        return nil unless current_runtime_class?(type_class) && graphql_runtime_class?(type_class)
 
         file_path = source_file_for_class(type_class)
         source = file_path && File.exist?(file_path) ? File.read(file_path) : ''
@@ -216,70 +228,113 @@ module Woods
       def graphql_source_present?
         return true if @graphql_dir&.directory?
 
-        !@schema_class.nil?
+        @schema_classes.any?
       end
 
-      # Find the application's schema class (descendant of GraphQL::Schema)
+      # Find every current, named application schema. Stale reload descendants
+      # and schemas defined in installed gems cannot claim application ownership.
       #
-      # @return [Class, nil]
-      def find_schema_class
-        return nil unless defined?(GraphQL::Schema)
+      # @return [Array<Class>]
+      def find_schema_classes
+        return [] unless defined?(GraphQL::Schema)
 
-        GraphQL::Schema.descendants.find do |klass|
-          klass.name && !klass.name.start_with?('GraphQL::')
-        end
-      rescue StandardError
-        nil
+        GraphQL::Schema.descendants.select do |klass|
+          next false unless klass.name && !klass.name.start_with?('GraphQL::') && current_runtime_class?(klass)
+
+          path = source_file_for_class(klass)
+          path.nil? || (File.expand_path(path).start_with?("#{Rails.root}/") && app_source?(path, Rails.root.to_s))
+        end.sort_by(&:name)
+      rescue StandardError => e
+        log_discovery_failure('schema inventory', e)
+        []
       end
 
       # Load types from the runtime schema for introspection
       #
       # @return [Hash{String => Class}] Map of type name to type class
       def load_runtime_types
-        return {} unless @schema_class
-
         types = {}
-        @schema_class.types.each do |name, type_class|
-          # Skip built-in introspection types
-          next if name.start_with?('__')
-          next unless type_class.respond_to?(:name) && type_class.name
+        @schema_classes.each do |schema|
+          query = schema.query if schema.respond_to?(:query)
+          schema_types = {}
+          schema.types.each do |name, type_class|
+            next if name.start_with?('__') || !current_runtime_class?(type_class)
+            next unless graphql_runtime_class?(type_class)
+
+            # GraphQL names are schema-local; two schemas may both have Query.
+            schema_types[type_class.name] = type_class
+          end
+          types.merge!(schema_types)
+          @query_roots << query if query
+        rescue StandardError => e
+          log_discovery_failure(schema.name, e)
+        end
+        types
+      end
+
+      def log_discovery_failure(name, error)
+        @runtime_discovery_complete = false
+        SourceInputs::ConsumerErrors.record(self)
+        return unless defined?(Rails)
+
+        Rails.logger.warn("[Woods] GraphQL runtime discovery incomplete for #{name}: #{error.message}")
+      end
+
+      def loaded_graphql_constant(name)
+        result = @runtime_lookup.call("::#{name}", allow_private: true)
+        result[:value] if result[:status] == :resolved
+      end
+
+      def current_runtime_class?(klass)
+        return false unless @runtime_lookup.module_object?(klass)
+
+        name = @runtime_lookup.reflect(klass, :name)
+        name && SourceReferences::RuntimeLookup::CORE_EQUAL.bind(klass).call(loaded_graphql_constant(name))
+      end
+
+      def graphql_runtime_class?(klass)
+        return false unless defined?(GraphQL::Schema) && @runtime_lookup.module_object?(klass)
 
-          types[name] = type_class
+        ancestors = @runtime_lookup.reflect(klass, :ancestors)
+        return true if ancestors.include?(GraphQL::Schema) && klass != GraphQL::Schema
+
+        %i[Object InputObject Enum Union Scalar Mutation Resolver Interface].any? do |name|
+          GraphQL::Schema.const_defined?(name, false) && ancestors.include?(GraphQL::Schema.const_get(name, false))
         end
+      end
 
-        types
-      rescue StandardError
-        {}
+      # Older file discovery admitted ordinary Resolvers::Base subclasses.
+      # Keep those application helpers under their historical graphql_type
+      # identity even though schema introspection cannot discover them. Verify
+      # real inheritance; directory names and example strings are not evidence.
+      def ruby_resolver_helper?(klass)
+        return false unless @runtime_lookup.class_object?(klass)
+
+        base = loaded_graphql_constant('Resolvers::Base')
+        return false unless @runtime_lookup.class_object?(base)
+
+        @runtime_lookup.reflect(klass, :ancestors).drop(1).any? do |ancestor|
+          SourceReferences::RuntimeLookup::CORE_EQUAL.bind(ancestor).call(base)
+        end
       end
 
       # Locate the file this type was defined in, or nil when there is none.
       #
-      # nil, not a fabricated convention path. A runtime-defined type
-      # (built by a schema builder or DSL) has no file, and inventing
-      # `app/graphql/<constant>.rb` for it created a unit indistinguishable from a
-      # file-defined one whose file had since been deleted. That ambiguity is
-      # unresolvable downstream: the conventional location of `Types::FooType`
-      # *is* `app/graphql/types/foo_type.rb`, so no path comparison can separate
-      # "never had a file" from "file was deleted".
-      #
-      # Returning nil resolves it at the only point where the answer is known.
-      # `DependencyGraph#register` skips nil paths, so such a unit never enters
-      # `file_map` and the deletion sweep — which walks registered paths — cannot
-      # reach it. No predicate required, and a full extraction produces the same
-      # nil, so the two paths still agree.
-      #
-      # `resolve_source_location` is tried first and has three tiers of real
-      # discovery (`const_source_location`, then instance and singleton method
-      # locations). It reaches its fallback only when Ruby cannot place the class
-      # in app source at all, which is precisely the no-file case.
+      # Prefer the real definition or method location, including classes built
+      # in initializers, over a convention-named file. Fall back only to an
+      # existing convention path. A genuinely fileless type keeps nil and stays
+      # out of the graph's file_map and path-based deletion sweep.
       #
       # @param klass [Class]
       # @return [String, nil]
       def source_file_for_class(klass)
+        actual = resolve_source_location(klass, app_root: Rails.root.to_s, fallback: nil)
+        return actual if actual
+
         convention_path = Rails.root.join("#{GRAPHQL_DIRECTORY}/#{klass.name.underscore}.rb").to_s
         return convention_path if File.exist?(convention_path)
 
-        resolve_source_location(klass, app_root: Rails.root.to_s, fallback: nil)
+        nil
       end
 
       # ──────────────────────────────────────────────────────────────────────
@@ -299,7 +354,7 @@ module Woods
           :graphql_type
         elsif defined?(GraphQL::Schema::Union) && type_class < GraphQL::Schema::Union
           :graphql_type
-        elsif defined?(GraphQL::Schema::Interface) && type_class.is_a?(Module) && type_class.respond_to?(:fields)
+        elsif defined?(GraphQL::Schema::Interface) && type_class.ancestors.include?(GraphQL::Schema::Interface)
           :graphql_type
         elsif defined?(GraphQL::Schema::InputObject) && type_class < GraphQL::Schema::InputObject
           :graphql_type
@@ -307,7 +362,7 @@ module Woods
           :graphql_type
         elsif defined?(GraphQL::Schema::Object) && type_class < GraphQL::Schema::Object
           # Check if this is the Query root type
-          if @schema_class.respond_to?(:query) && @schema_class.query == type_class
+          if @query_roots.include?(type_class)
             :graphql_query
           else
             :graphql_type
@@ -326,9 +381,9 @@ module Woods
         return :graphql_mutation if file_path.include?('/mutations/')
         return :graphql_resolver if file_path.include?('/resolvers/')
 
-        return :graphql_mutation if source.match?(/< (GraphQL::Schema::Mutation|Mutations::Base|BaseMutation)/)
+        return :graphql_mutation if source.match?(/<\s*(?:::)?(GraphQL::Schema::Mutation|Mutations::Base|BaseMutation)/)
 
-        return :graphql_resolver if source.match?(/< (GraphQL::Schema::Resolver|Resolvers::Base|BaseResolver)/)
+        return :graphql_resolver if source.match?(/<\s*(?:::)?(GraphQL::Schema::Resolver|Resolvers::Base|BaseResolver)/)
 
         # Query type is usually the root query object
         return :graphql_query if file_path.match?(/query_type\.rb$/) || source.match?(/class QueryType\b/)
@@ -341,7 +396,7 @@ module Woods
       # @param source [String]
       # @return [Boolean]
       def graphql_class?(source)
-        source.match?(/< GraphQL::Schema::(Object|InputObject|Enum|Union|Scalar|Mutation|Resolver|Interface|RelayClassicMutation)/) ||
+        source.match?(/<\s*(?:::)?GraphQL::Schema(?:\b(?!::)|::(?:Object|InputObject|Enum|Union|Scalar|Mutation|Resolver|Interface|RelayClassicMutation)\b)/) ||
           source.match?(/< (Types::Base\w+|Base(Type|InputObject|Enum|Union|Scalar|Mutation|Resolver|Interface))/) ||
           source.match?(/< (Mutations::Base|Resolvers::Base)/) ||
           source.match?(/include GraphQL::Schema::Interface/) ||
@@ -484,6 +539,7 @@ module Woods
       # @return [Symbol]
       def detect_graphql_kind(source, runtime_class)
         if runtime_class
+          return :schema if defined?(GraphQL::Schema) && runtime_class < GraphQL::Schema
           return :enum if defined?(GraphQL::Schema::Enum) && runtime_class < GraphQL::Schema::Enum
           return :union if defined?(GraphQL::Schema::Union) && runtime_class < GraphQL::Schema::Union
           return :input_object if defined?(GraphQL::Schema::InputObject) && runtime_class < GraphQL::Schema::InputObject
@@ -497,6 +553,7 @@ module Woods
         end
 
         # Fall back to source analysis
+        return :schema if source.match?(/<\s*(?:::)?GraphQL::Schema\b(?!::)/)
         return :enum if source.match?(/< .*Enum\b/) || source.match?(/value\s+["']/)
         return :union if source.match?(/< .*Union\b/) || source.match?(/possible_types\s/)
         return :input_object if source.match?(/< .*InputObject\b/)

data/lib/woods/extractors/job_extractor.rb

@@ -5,6 +5,7 @@ require_relative '../source_inputs/consumer_errors'
 require_relative 'reference_patterns'
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
+require_relative '../source_references/runtime_lookup'
 
 module Woods
   module Extractors
@@ -82,7 +83,10 @@ module Woods
       def discoverable_classes
         return [] unless defined?(ApplicationJob)
 
-        ApplicationJob.descendants.reject { |job_class| job_class.name.nil? }
+        lookup = SourceReferences::RuntimeLookup.new
+        ApplicationJob.descendants.select do |klass|
+          klass.name && lookup.call("::#{klass.name}", allow_private: true)[:value].equal?(klass)
+        end
       end
 
       # Extract a job from its file

data/lib/woods/extractors/lib_extractor.rb

@@ -5,6 +5,11 @@ require_relative '../source_inputs/consumer_errors'
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
 require_relative 'source_nesting'
+require_relative '../source_references/collector'
+require_relative 'assigned_value_discovery'
+require_relative '../source_contributors'
+require_relative '../source_references/registry'
+require_relative 'class_declarations'
 
 module Woods
   module Extractors
@@ -51,25 +56,48 @@ module Woods
       #
       # @return [Array<ExtractedUnit>] List of lib units
       def extract_all
-        return [] unless @lib_dir.directory?
-
-        Dir[@lib_dir.join('**/*.rb')].filter_map do |file|
-          next if excluded_path?(file)
-
-          extract_lib_file(file)
-        end
+        library_groups.flat_map { |group| aggregate(group) || group.map { |entry| copy_unit(entry[:unit]) } }
       end
 
-      # Extract a single lib file.
+      # Extract the complete library owner containing this physical file.
       #
-      # Returns nil if the file cannot be read or yields no extractable unit.
-      # Module-only files are extracted (unlike some other extractors) since
-      # lib/ commonly contains standalone utility modules.
+      # Returns nil when the file yields no extractable unit. Discovery errors
+      # or incompatible contributors refuse extraction instead of returning a
+      # partial owner. This entry point never loads application source.
       #
       # @param file_path [String] Absolute path to the Ruby file
-      # @return [ExtractedUnit, nil] The extracted unit or nil on failure
+      # @return [ExtractedUnit, nil] The complete owner or nil when absent
+      # @raise [Woods::ExtractionError] when complete ownership cannot be established
       def extract_lib_file(file_path)
-        source = File.read(file_path)
+        group = library_groups.find { |entries| entries.any? { |entry| entry[:unit].file_path == file_path.to_s } }
+        return unless group
+        return copy_unit(group.first[:unit]) if group.one?
+
+        aggregate(group) || raise(Woods::ExtractionError, "Ambiguous library owner: #{group.first[:unit].identifier}")
+      end
+
+      private
+
+      def library_groups
+        @library_groups ||= begin
+          files = @lib_dir.directory? ? Dir.glob('**/*.rb', base: @lib_dir).sort : []
+          entries = files.filter_map do |relative|
+            path = @lib_dir.join(relative).to_s
+            next if excluded_path?(path)
+
+            build_file(path)
+          end
+          if SourceInputs::ConsumerErrors.failed?(self)
+            raise Woods::ExtractionError, 'Cannot establish the complete library contributor set after a source failure'
+          end
+
+          entries.group_by { |entry| entry[:unit].identifier }.values
+        end
+      end
+
+      def build_file(file_path)
+        source = File.read(file_path, encoding: 'UTF-8')
+        raise Woods::ExtractionError, 'Source is not valid UTF-8' unless source.valid_encoding?
 
         class_name = infer_class_name(file_path, source)
         return nil unless class_name
@@ -87,13 +115,96 @@ module Woods
         unit.metadata     = extract_metadata(source, parent_class)
         unit.dependencies = extract_dependencies(source)
 
-        unit
+        { unit: unit, source: source, analysis: SourceReferences::Collector.new.call(source) }
       rescue StandardError => e
         SourceInputs::ConsumerErrors.log(self, "Failed to extract lib file #{file_path}: #{e.message}")
         nil
       end
 
-      private
+      def copy_unit(original)
+        original.dup.tap do |unit|
+          unit.metadata = original.metadata.dup
+          unit.dependencies = original.dependencies.map(&:dup)
+        end
+      end
+
+      def aggregate(group)
+        return copy_unit(group.first[:unit]) if group.one?
+        return unless compatible_contributors?(group)
+
+        primary = group.first[:unit]
+        unit = ExtractedUnit.new(type: :lib, identifier: primary.identifier, file_path: primary.file_path)
+        unit.namespace = primary.namespace
+        unit.source_code = +''
+        records = group.map { |entry| append_contributor(unit, entry) }
+        unit.metadata = common_facts(group)
+        unit.metadata[:source_contributors_version] = SourceContributors::VERSION
+        unit.metadata[:source_contributors] = records
+        unit.metadata[:defined_in] = records.map { |record| record['file_path'] }
+        unit.dependencies = group.flat_map { |entry| entry[:unit].dependencies }.uniq
+        unit
+      end
+
+      def compatible_contributors?(group)
+        units = group.map { |entry| entry[:unit] }
+        sources = group.to_h { |entry| [entry[:unit].file_path, entry[:analysis]] }
+        registry = SourceReferences::Registry.new(units: units, sources: sources, root: Rails.root)
+        kinds = group.map do |entry|
+          unit = entry[:unit]
+          declarations = entry[:analysis].fetch('declarations', []).select { |decl| decl['owner'] == unit.identifier }
+          return false if declarations.empty? || declarations.any? { |decl| decl['constructor'] }
+          return false unless registry.owner?(unit.identifier, file_path: unit.file_path)
+
+          declarations.map { |decl| decl['kind'] }.uniq
+        end
+        kinds.flatten.uniq.one? && compatible_parents?(group)
+      end
+
+      def compatible_parents?(group)
+        parents = group.flat_map do |entry|
+          ClassDeclarations.read(entry[:source]).filter_map do |declaration|
+            next unless declaration[:identifier] == entry[:unit].identifier
+            next unless declaration[:node].superclass
+
+            parent = ClassDeclarations.parent_name(declaration)
+            return false unless parent
+
+            parent.delete_prefix('::')
+          end
+        end
+        parents.uniq.size <= 1
+      rescue ClassDeclarations::Unresolved
+        false
+      end
+
+      def append_contributor(unit, entry)
+        path = entry[:unit].file_path.delete_prefix("#{Rails.root}/")
+        source = entry[:source]
+        unit.source_code << "# Library contributor: #{path}\n"
+        start_byte = unit.source_code.bytesize
+        start_line = unit.source_code.count("\n") + 1
+        unit.source_code << source
+        record = { 'file_path' => path, 'source_sha256' => Digest::SHA256.hexdigest(source),
+                   'source_start_line' => 1, 'source_end_line' => source.lines.size,
+                   'published_start_byte' => start_byte, 'published_end_byte' => unit.source_code.bytesize,
+                   'published_start_line' => start_line, 'published_end_line' => start_line + source.lines.size - 1,
+                   'facts' => entry[:unit].metadata }
+        unit.source_code << "\n\n"
+        record
+      end
+
+      # Conflicting scalar/list facts remain available per contributor; sorted
+      # paths are display order and cannot establish runtime override order.
+      def common_facts(group)
+        facts = group.first[:unit].metadata.select do |key, value|
+          group.all? { |entry| entry[:unit].metadata[key] == value }
+        end
+        %i[public_methods class_methods entry_points].each do |key|
+          facts[key] = group.flat_map { |entry| entry[:unit].metadata.fetch(key) }.uniq
+        end
+        %i[loc method_count].each { |key| facts[key] = group.sum { |entry| entry[:unit].metadata.fetch(key) } }
+        facts
+      end
 
       # ──────────────────────────────────────────────────────────────────────
       # Path Filtering
@@ -135,6 +246,12 @@ module Woods
         # closed before the class opened, no longer pollutes the identifier
         # (#174). lib/ files are typically unmanaged, so the governed lookup
         # returns nil and the source scan decides.
+        analysis = SourceReferences::Collector.new.call(source)
+        expected = managed_constant_path(file_path.to_s) || path_based_class_name(file_path)
+        assigned = AssignedValueDiscovery.new.call(file_path, analysis: analysis, expected: expected,
+                                                              preserve_modules: true)
+        return assigned if assigned
+
         qualified = governed_class_name(file_path, source) || qualified_first_class_name(source)
         return qualified if qualified
 

data/lib/woods/extractors/mailer_extractor.rb

@@ -29,9 +29,7 @@ module Woods
       include RouteHelperResolver
 
       def initialize
-        if defined?(ActionMailer::Base)
-          @mailer_base = defined?(ApplicationMailer) ? ApplicationMailer : ActionMailer::Base
-        end
+        @mailer_base = ActionMailer::Base if defined?(ActionMailer::Base)
         build_route_helper_map
       end
 
@@ -90,11 +88,11 @@ module Woods
       # Discovery and direct incremental extraction must agree on ownership;
       # otherwise a gem class with a fabricated path becomes a phantom unit.
       def app_defined_mailer?(mailer)
-        return false unless @mailer_base && mailer.name
+        return false unless @mailer_base && mailer.name && mailer < @mailer_base
         return false if mailer == ActionMailer::Base
 
         path = source_file_for(mailer)
-        path && File.file?(path) && app_source?(path, Rails.root.to_s)
+        app_source_file?(path)
       end
 
       # Locate the source file for a mailer class.

data/lib/woods/extractors/manager_extractor.rb

@@ -4,6 +4,7 @@ require_relative '../source_inputs/consumer_errors'
 
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
+require_relative 'declaration_ancestry'
 
 module Woods
   module Extractors
@@ -56,7 +57,9 @@ module Woods
         class_name = extract_class_name(file_path, source, 'managers')
 
         return nil unless class_name
-        return nil unless manager_file?(source)
+
+        ancestry = DeclarationAncestry.new(source: source, identifier: class_name, file_path: file_path)
+        return nil unless ancestry.manager?
 
         unit = ExtractedUnit.new(
           type: :manager,
@@ -66,7 +69,7 @@ module Woods
 
         unit.namespace = extract_namespace(class_name)
         unit.source_code = annotate_source(source, class_name)
-        unit.metadata = extract_metadata(source, class_name)
+        unit.metadata = extract_metadata(source, class_name, ancestry)
         unit.dependencies = extract_dependencies(source, class_name)
 
         unit
@@ -77,16 +80,6 @@ module Woods
 
       private
 
-      # ──────────────────────────────────────────────────────────────────────
-      # Class Discovery
-      # ──────────────────────────────────────────────────────────────────────
-
-      def manager_file?(source)
-        source.match?(/< SimpleDelegator/) ||
-          source.match?(/< DelegateClass\(/) ||
-          source.match?(/include Delegator/)
-      end
-
       # ──────────────────────────────────────────────────────────────────────
       # Source Annotation
       # ──────────────────────────────────────────────────────────────────────
@@ -108,10 +101,10 @@ module Woods
       # Metadata Extraction
       # ──────────────────────────────────────────────────────────────────────
 
-      def extract_metadata(source, class_name)
+      def extract_metadata(source, class_name, ancestry)
         {
           wrapped_model: detect_wrapped_model(source, class_name),
-          delegation_type: detect_delegation_type(source),
+          delegation_type: ancestry.delegation_type,
           public_methods: extract_public_methods(source),
           class_methods: extract_class_methods(source),
           initialize_params: extract_initialize_params(source),
@@ -162,13 +155,6 @@ module Woods
         name.respond_to?(:camelize) ? name.camelize : name.split('_').map(&:capitalize).join
       end
 
-      def detect_delegation_type(source)
-        return :delegate_class if source.match?(/< DelegateClass\(/)
-        return :simple_delegator if source.match?(/< SimpleDelegator/)
-
-        :unknown
-      end
-
       def extract_delegated_methods(source)
         methods = []