woods 2.0.1 → 2.1.0

data/lib/woods/extractors/serializer_extractor.rb

@@ -4,6 +4,7 @@ require_relative '../source_inputs/consumer_errors'
 
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
+require_relative '../source_references/runtime_lookup'
 
 module Woods
   module Extractors
@@ -61,24 +62,11 @@ module Woods
 
         # Class-based discovery for loaded gems
         seen = units.to_set(&:identifier)
-        BASE_CLASSES.each_key do |base_class_name|
-          base_class = begin
-            base_class_name.constantize
-          rescue NameError
-            nil
-          end
-          next unless base_class
-
-          base_class.descendants.each do |klass|
-            next if klass.name.nil?
-            next if seen.include?(klass.name)
-
-            unit = extract_serializer_class(klass, base_class_name)
-            if unit
-              units << unit
-              seen << unit.identifier
-            end
-          end
+        discoverable_classes.each do |klass|
+          next if seen.include?(klass.name)
+
+          unit = extract_serializer_class(klass)
+          units << unit if unit
         end
 
         units.compact
@@ -112,15 +100,22 @@ module Woods
         nil
       end
 
-      private
+      # Current, named descendants of the supported runtime serializer bases.
+      # Stale class objects retained after Rails reload do not own their name.
+      # @return [Array<Class>]
+      def discoverable_classes
+        BASE_CLASSES.keys.filter_map(&:safe_constantize).flat_map(&:descendants).uniq.select do |klass|
+          runtime_base_for(klass)
+        end
+      end
 
       # Extract a serializer from its class (runtime introspection)
       #
       # @param klass [Class] The serializer class
-      # @param base_class_name [String] Name of the detected base class
       # @return [ExtractedUnit, nil] The extracted unit
-      def extract_serializer_class(klass, base_class_name)
-        return nil if klass.name.nil?
+      def extract_serializer_class(klass)
+        base_class_name = runtime_base_for(klass)
+        return nil unless base_class_name
 
         file_path = source_file_for(klass)
         source = file_path && File.exist?(file_path) ? File.read(file_path) : ''
@@ -142,6 +137,23 @@ module Woods
         nil
       end
 
+      private
+
+      # The live constant and a supported ancestor jointly establish ownership.
+      # @param klass [Class]
+      # @return [String, nil] supported base name for a current serializer class
+      def runtime_base_for(klass)
+        return nil unless klass.is_a?(Class) && klass.name
+
+        lookup = SourceReferences::RuntimeLookup.new
+        return nil unless lookup.call("::#{klass.name}", allow_private: true)[:value].equal?(klass)
+
+        BASE_CLASSES.keys.find do |name|
+          base = name.safe_constantize
+          base && klass < base
+        end
+      end
+
       # ──────────────────────────────────────────────────────────────────────
       # Class Discovery
       # ──────────────────────────────────────────────────────────────────────

data/lib/woods/extractors/shared_utility_methods.rb

@@ -54,7 +54,24 @@ module Woods
       def app_source?(path, app_root)
         return false unless path
 
-        path.start_with?(app_root) && !path.include?('/vendor/') && !path.include?('/node_modules/')
+        prefix = File.expand_path(app_root.to_s).delete_suffix(File::SEPARATOR) + File::SEPARATOR
+        absolute = File.expand_path(path.to_s)
+        return false unless absolute.start_with?(prefix)
+
+        relative = absolute.delete_prefix(prefix)
+        relative.split(File::SEPARATOR).none? { |part| %w[vendor node_modules].include?(part) }
+      end
+
+      # Whether a resolved source belongs to this application and is a file.
+      # Framework consumers may still use resolve_source_location's external
+      # fallback; app-only component families apply this narrower final gate.
+      #
+      # @param path [String, nil] resolved source path
+      # @return [Boolean]
+      def app_source_file?(path)
+        return false unless path
+
+        app_source?(path, Rails.root.to_s) && File.file?(path)
       end
 
       # Resolve the source file for a class using reliable introspection,

data/lib/woods/extractors/source_nesting.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'line_neutralizer'
+require 'prism'
 
 module Woods
   module Extractors
@@ -15,19 +16,13 @@ module Woods
     # Wrong identifiers collapse cross-namespace same-named classes onto one
     # graph node and leave edges targeting the real constant dangling.
     #
-    # This module scans source line by line tracking nesting *by position*:
-    # a stack of open +module+/+class+ declarations that pops on the matching
-    # +end+, using the same depth-tracking discipline as
-    # RakeTaskExtractor#block_opener? (the house pattern for what counts as a
-    # block opener). Compact declarations (`class Billing::Payment`) keep
-    # their qualified segments.
-    #
-    # The heuristic is regex-based, not an AST. Pathological constructs
-    # (heredocs containing keywords, keywords inside string literals) can
-    # unbalance the depth count — the accepted house tradeoff, shared with
-    # RakeTaskExtractor: declarations and their +end+s pair up for
-    # conventionally formatted files. Assignment-form conditionals
-    # (`x = if ...`) are counted; see {#block_opener?}.
+    # Prism reads complete source so declarations retain their lexical nesting
+    # on a single line and literal text cannot supply a declaration. Compact
+    # declarations (`class Billing::Payment`) keep their qualified segments.
+    # Conditional declarations remain source candidates, not proof that a
+    # runtime branch executed. Method and singleton-class bodies do not name
+    # ordinary owners. Invalid source retains the legacy line-based class scan;
+    # module ownership requires a successful whole-source parse.
     #
     # @example Qualifying the first class declaration
     #   qualified_first_class_name("module Billing\n  class Payment\n  end\nend")
@@ -100,7 +95,7 @@ module Woods
       # silently dropped all but one.
       #
       # This method computes the expected constant path — from
-      # +Rails.autoloaders.main+ when a Rails autoloader is up, from the
+      # the owning Rails autoloader (main or once) when available, from the
       # same path-to-constant convention offline otherwise — and returns the
       # first declaration (class or module) whose qualified name equals it.
       # When the path is not managed, or no declaration matches (an
@@ -121,12 +116,11 @@ module Woods
 
       # Fully-qualified name of the file's primary module.
       #
-      # Follows the initial chain of module declarations — each opening
-      # directly inside the previous one, with only blank/comment lines
-      # between — and returns the chain joined with `::`. Prelude lines
-      # before the first module (requires, magic comments, guards) are
-      # skipped. The chain stops at the first body content (methods,
-      # `extend`, a class, a self-terminated inner module) and never descends
+      # Follows namespace-only wrappers, each containing a sole nonempty
+      # module, and returns the chain joined with `::`. Prelude statements
+      # before the first module (requires, magic comments, guards) are skipped.
+      # The chain stops at body content (methods, `extend`, a class, an empty
+      # inner module) and never descends
       # into mixin plumbing modules ({MIXIN_INNER_MODULES}), so `module
       # Trackable; module ClassMethods` names +Trackable+ while `module
       # Gateway; module Stripe; module Refundable` names
@@ -138,34 +132,34 @@ module Woods
       # @return [String, nil] Qualified module name, or nil when the source
       #   opens no module
       def qualified_outer_module_name(source)
-        chain = []
-
-        each_significant_line(source) do |stripped|
-          decl = DECLARATION_PATTERN.match(stripped)
+        parsed = Prism.parse(source)
+        return unless parsed.success?
 
-          unless decl
-            next if chain.empty? # prelude before any module (requires, guards)
+        each_syntax_declaration(parsed.value) do |kind, name, _qualified, node|
+          return unless kind == 'module'
+          return if name.split('::').any? { |part| MIXIN_INNER_MODULES.include?(part) }
+          next if !node.body && node.location.start_line == node.location.end_line
 
-            break # body content — the chain is complete
-          end
-
-          break unless decl[1] == 'module'
-          break if decl[2].split('::').any? { |seg| MIXIN_INNER_MODULES.include?(seg) }
+          return primary_module_chain(node) || name
+        end
 
-          unless block_opener?(stripped)
-            # Self-terminated one-liner (`module Foo; end`): encloses nothing.
-            # Before the chain starts it is a sibling prelude (skip it);
-            # afterwards it is body content (chain complete).
-            break unless chain.empty?
+        nil
+      end
 
-            next
-          end
+      # Only a sole nonempty module is a namespace wrapper. Parse the complete
+      # source before calling this so heredoc bodies remain literal text.
+      def primary_module_chain(node)
+        return unless node.is_a?(Prism::ModuleNode) && node.body
 
-          chain << decl[2]
-        end
+        name = DECLARATION_PATTERN.match(node.location.slice)&.[](2)
+        return if !name || name.split('::').any? { |part| MIXIN_INNER_MODULES.include?(part) }
+        return name unless node.body.is_a?(Prism::StatementsNode) # rescue/ensure belongs to this owner
 
-        chain.empty? ? nil : chain.join('::')
+        statements = node.body.body
+        nested = primary_module_chain(statements.first) if statements.one?
+        [name, nested].compact.join('::')
       end
+      private :primary_module_chain
 
       # Check if a line opens a new block (do...end, def...end, etc.).
       #
@@ -185,17 +179,22 @@ module Woods
 
       private
 
-      # Yield every module/class declaration with its position-aware
-      # qualified name. The stack discipline is the one documented on the
-      # module: declarations open frames, {#block_opener?} opens anonymous
-      # (depth-only) frames, and {END_LINE}-matching lines pop them.
+      # Yield named declarations from complete source. Retain the tolerant
+      # line scanner for invalid/incomplete source, where Prism cannot provide
+      # a complete syntax tree.
       #
       # @param source [String] Ruby source code
       # @yieldparam kind [String] 'module' or 'class'
       # @yieldparam name [String] The declared (possibly compact) name
       # @yieldparam qualified [String] Enclosing stack joined with the name
       # @return [void]
-      def each_declaration(source)
+      def each_declaration(source, &block)
+        parsed = Prism.parse(source)
+        if parsed.success?
+          each_syntax_declaration(parsed.value, &block)
+          return
+        end
+
         stack = []
 
         each_significant_line(source) do |stripped|
@@ -213,6 +212,25 @@ module Woods
         end
       end
 
+      # Walk syntactic scopes without evaluating conditionals or interpreting
+      # literal contents as Ruby. Declarations under method/singleton scopes
+      # cannot establish the ordinary constant ownership used by these units.
+      def each_syntax_declaration(node, namespace = [], &block)
+        return unless node
+        return if node.is_a?(Prism::DefNode) || node.is_a?(Prism::SingletonClassNode)
+
+        if node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode)
+          declaration = DECLARATION_PATTERN.match(node.location.slice)
+          return unless declaration
+
+          nesting = [*namespace, declaration[2]]
+          yield declaration[1], declaration[2], nesting.join('::'), node
+          each_syntax_declaration(node.body, nesting, &block)
+        else
+          node.compact_child_nodes.each { |child| each_syntax_declaration(child, namespace, &block) }
+        end
+      end
+
       # First declaration whose qualified name equals +expected+.
       #
       # @param expected [String] The Zeitwerk-expected constant path
@@ -233,16 +251,16 @@ module Woods
       #   is not under a managed root
       def managed_constant_path(file_path)
         file_path = File.expand_path(file_path.to_s)
-        root, owner, foreign_root = managed_root_for(file_path)
+        root, owner, loader, foreign_root = managed_root_for(file_path)
         return nil unless root
 
-        return loader_expected_cpath(file_path) if owner == :loader
-        return foreign_loader_constant_path(file_path, root, foreign_root) if owner == :foreign_loader
+        return loader_expected_cpath(file_path, loader) if owner == :loader
+        return foreign_loader_constant_path(file_path, root, foreign_root, loader) if owner == :foreign_loader
 
         local_managed_constant_path(file_path, root)
       end
 
-      # The constant path the active main loader expects for +file_path+,
+      # The constant path the owning loader expects for +file_path+,
       # asked through the loader's own API so its inflector, namespace
       # collapse, and ignore rules decide (a custom `api => API` inflection
       # must win over the local camelizer). Available on Zeitwerk 2.6.9+;
@@ -251,9 +269,9 @@ module Woods
       # local camelizer must not rescue it.
       #
       # @param file_path [String] Expanded absolute path to the file
+      # @param loader [Zeitwerk::Loader] Owning loader
       # @return [String, nil]
-      def loader_expected_cpath(file_path)
-        loader = main_loader
+      def loader_expected_cpath(file_path, loader)
         return nil unless loader.respond_to?(:cpath_expected_at)
 
         loader.cpath_expected_at(file_path)
@@ -281,19 +299,20 @@ module Woods
       # @param file_path [String] Expanded absolute path to the file
       # @param root [String] Active managed root the path is relative to
       # @param foreign_root [String, nil] Matching managed root from loader.dirs
+      # @param loader [Zeitwerk::Loader] Owning loader for the foreign root
       # @return [String, nil]
-      def foreign_loader_constant_path(file_path, root, foreign_root)
+      def foreign_loader_constant_path(file_path, root, foreign_root, loader)
         mapped = foreign_root && mapped_foreign_path(file_path, root, foreign_root)
         return nil unless mapped
 
         # If the corresponding boot-root path exists, the real loader can
         # answer with full semantics: ignores, root namespaces, collapses,
         # and custom inflections. A nil answer is an authoritative non-claim.
-        return loader_expected_cpath(mapped) if File.exist?(mapped)
+        return loader_expected_cpath(mapped, loader) if File.exist?(mapped)
 
-        return nil unless copied_only_loader_fallback_allowed?(file_path, root, foreign_root)
+        return nil unless copied_only_loader_fallback_allowed?(file_path, root, foreign_root, loader)
 
-        inflected_managed_constant_path(file_path, root)
+        inflected_managed_constant_path(file_path, root, loader)
       end
 
       # @param file_path [String] Expanded absolute path under the active root
@@ -314,22 +333,23 @@ module Woods
       #
       # @param file_path [String] Expanded absolute path to the file
       # @param root [String] The managed root the path is relative to
+      # @param loader [Zeitwerk::Loader] Owning loader for the corresponding foreign root
       # @return [String]
-      def inflected_managed_constant_path(file_path, root)
+      def inflected_managed_constant_path(file_path, root, loader)
         relative = file_path[root.length..].to_s.sub(/\.rb\z/, '')
         segments = relative.split('/').reject(&:empty?)
         current = root.chomp('/')
         segments.map do |segment|
           current = File.join(current, segment)
-          loader_camelize(segment, current)
+          loader_camelize(segment, current, loader)
         end.join('::')
       end
 
       # @param segment [String] Path segment without extension
       # @param abspath [String] Absolute path passed to Zeitwerk inflectors
+      # @param loader [Zeitwerk::Loader] Owning loader
       # @return [String]
-      def loader_camelize(segment, abspath)
-        loader = main_loader
+      def loader_camelize(segment, abspath, loader)
         inflector = loader.respond_to?(:inflector) ? loader.inflector : nil
         return camelize_segment(segment) unless inflector.respond_to?(:camelize)
 
@@ -345,20 +365,27 @@ module Woods
       # @param file_path [String] Expanded absolute path to the file
       # @param root [String] Active managed root the path is relative to
       # @param foreign_root [String] Matching boot-loader managed root
+      # @param loader [Zeitwerk::Loader] Owning loader for the foreign root
       # @return [Boolean]
-      def copied_only_loader_fallback_allowed?(file_path, root, foreign_root)
-        loader_root_namespace(foreign_root) == Object &&
-          !mapped_path_uses_collapsed_directory?(file_path, root, foreign_root) &&
-          !mapped_path_crosses_loader_root?(file_path, root, foreign_root)
+      def copied_only_loader_fallback_allowed?(file_path, root, foreign_root, loader)
+        loader_root_namespace(foreign_root, loader) == Object &&
+          !mapped_path_uses_collapsed_directory?(file_path, root, foreign_root, loader) &&
+          !mapped_path_crosses_loader_root?(file_path, root, foreign_root, loader)
       end
 
       # A nested loader root resets Zeitwerk's constant-path origin. The
       # copied-only fallback cannot ask +cpath_expected_at+ about a file that
       # exists only in the active copy, so it must not camelize the nested
       # root directory as an extra namespace segment.
-      def mapped_path_crosses_loader_root?(file_path, root, foreign_root)
+      #
+      # @param file_path [String] Expanded absolute path to the file
+      # @param root [String] Active managed root
+      # @param foreign_root [String] Matching boot-loader managed root
+      # @param loader [Zeitwerk::Loader] Owning loader for the foreign root
+      # @return [Boolean]
+      def mapped_path_crosses_loader_root?(file_path, root, foreign_root, loader)
         mapped = mapped_foreign_path(file_path, root, foreign_root)
-        Array(main_loader.dirs).any? do |dir|
+        Array(loader.dirs).any? do |dir|
           nested = File.expand_path(dir.to_s.chomp('/'))
           nested != foreign_root && mapped.start_with?("#{nested}/")
         end
@@ -367,9 +394,9 @@ module Woods
       end
 
       # @param foreign_root [String] Matching boot-loader managed root
+      # @param loader [Zeitwerk::Loader] Owning loader for the foreign root
       # @return [Module]
-      def loader_root_namespace(foreign_root)
-        loader = main_loader
+      def loader_root_namespace(foreign_root, loader)
         namespaced_dirs = loader.dirs(namespaces: true) if loader.respond_to?(:dirs)
         return Object unless namespaced_dirs.respond_to?(:[])
 
@@ -381,9 +408,9 @@ module Woods
       # @param file_path [String] Expanded absolute path to the file
       # @param root [String] Active managed root
       # @param foreign_root [String] Matching boot-loader managed root
+      # @param loader [Zeitwerk::Loader] Owning loader for the foreign root
       # @return [Boolean]
-      def mapped_path_uses_collapsed_directory?(file_path, root, foreign_root)
-        loader = main_loader
+      def mapped_path_uses_collapsed_directory?(file_path, root, foreign_root, loader)
         return false unless loader.respond_to?(:__collapse?)
 
         relative = file_path[root.length..].to_s.sub(%r{\A/}, '').sub(/\.rb\z/, '')
@@ -401,11 +428,12 @@ module Woods
       # The managed root directory containing +file_path+, if any, with the
       # authority that vouches for it.
       #
-      # When a Rails autoloader is up, its directory list is the authority
-      # for the files it claims. For a file it does NOT claim, the
-      # non-claim stays authoritative whenever the loader demonstrably
-      # belongs to the active root (any loader directory under it) or
-      # reports an empty set (classic mode): unmanaged. Only when every
+      # Both Rails autoloaders' directory lists are checked for direct
+      # ownership before any copied-root inference. The most specific root
+      # wins; equally specific roots owned by different loaders are ambiguous.
+      # For a file neither claims, the non-claim stays authoritative whenever
+      # either loader has a directory in the active tree, or both report an
+      # empty set (classic mode). Only when every
       # loader root belongs to a DIFFERENT tree — copied-app and
       # multi-worktree extractions, where the loader belongs to the boot
       # root while Rails.root is repointed per slot — does the root-relative
@@ -415,28 +443,37 @@ module Woods
       # {MANAGED_PATH_PATTERN} stands in offline.
       #
       # @param file_path [String] Absolute path to the source file
-      # @return [Array(String, Symbol), nil] `[root, owner]` with owner
-      #   +:loader+, +:foreign_loader+, or +:convention+, or nil when the
-      #   file is unmanaged
+      # @return [Array, nil] `[root, authority, loader, foreign_root]`, with
+      #   authority +:loader+, +:foreign_loader+, or +:convention+; nil when
+      #   unmanaged. The last two fields are omitted for the offline convention.
       def managed_root_for(file_path)
         file_path = File.expand_path(file_path)
-        loader = main_loader
-        unless loader
+        loaders = rails_loaders
+        if loaders.empty?
           root = MANAGED_PATH_PATTERN.match(file_path)&.captures&.first
           return root ? [root, :convention] : nil
         end
 
-        dirs = Array(loader.dirs).map { |dir| File.expand_path(dir.to_s.chomp('/')) }
+        roots = loaders.flat_map do |loader|
+          Array(loader.dirs).map { |dir| [File.expand_path(dir.to_s.chomp('/')), loader] }
+        end.uniq
+
+        claimed = roots.select { |dir, _loader| file_path.start_with?("#{dir}/") }
+        unless claimed.empty?
+          deepest = claimed.map { |dir, _loader| dir.length }.max
+          owners = claimed.select { |dir, _loader| dir.length == deepest }
+          return nil unless owners.one?
 
-        claimed = dirs.find { |dir| file_path.start_with?("#{dir}/") }
-        return [claimed, :loader] if claimed
+          dir, loader = owners.first
+          return [dir, :loader, loader]
+        end
 
         active = active_root
         return nil unless active
-        return nil if dirs.any? { |dir| dir.start_with?("#{active}/") }
-        return nil if dirs.empty?
+        return nil if roots.any? { |dir, _loader| dir == active || dir.start_with?("#{active}/") }
+        return nil if roots.empty?
 
-        active_root_managed_for(file_path, active, dirs)
+        active_root_managed_for(file_path, active, roots)
       end
 
       # Root-relative managed root for a file the autoloader does not
@@ -450,10 +487,9 @@ module Woods
       #
       # @param file_path [String] Absolute path to the source file
       # @param active [String] Expanded active extraction root
-      # @param dirs [Array<String>] Foreign loader roots
-      # @return [Array(String, Symbol, String), nil] `[root, :foreign_loader,
-      #   foreign_root]`, or nil
-      def active_root_managed_for(file_path, active, dirs)
+      # @param roots [Array<Array>] Foreign `[directory, loader]` pairs
+      # @return [Array, nil] `[root, :foreign_loader, loader, foreign_root]`, or nil
+      def active_root_managed_for(file_path, active, roots)
         return nil unless file_path.start_with?("#{active}/")
 
         shape = file_path[active.length..].to_s.match(%r{\A(/app/[^/]+/)})
@@ -461,20 +497,18 @@ module Woods
 
         root = "#{active}#{shape[1]}"
         suffix = shape[1].chomp('/')
-        candidates = dirs.select { |dir| dir.end_with?(suffix) }
+        candidates = roots.select { |dir, _loader| dir.end_with?(suffix) }
         return nil if candidates.empty?
 
-        existing = candidates.select do |foreign_root|
+        existing = candidates.select do |foreign_root, _loader|
           File.exist?(mapped_foreign_path(file_path, root, foreign_root))
         end
 
-        return [root, :foreign_loader, existing.first] if existing.one?
-        return nil if existing.any?
-
-        foreign_root = candidates.one? ? candidates.first : nil
-        return nil unless foreign_root
+        candidates = existing unless existing.empty?
+        return nil unless candidates.one?
 
-        [root, :foreign_loader, foreign_root]
+        foreign_root, loader = candidates.first
+        [root, :foreign_loader, loader, foreign_root]
       end
 
       # The active extraction root, expanded: the boot root in a normal
@@ -490,21 +524,23 @@ module Woods
         nil
       end
 
-      # The main Rails autoloader, or nil when there is none to consult
+      # The available Rails autoloaders, or an empty array when none can be consulted
       # (no Rails, a spec stub). In classic mode the loader exists with an
       # empty directory list — an authoritative empty set.
       #
-      # @return [Zeitwerk::Loader, nil]
-      def main_loader
-        return nil unless defined?(Rails) && Rails.respond_to?(:autoloaders)
+      # @return [Array<Zeitwerk::Loader>]
+      def rails_loaders
+        return [] unless defined?(Rails) && Rails.respond_to?(:autoloaders)
 
         autoloaders = Rails.autoloaders
-        return nil unless autoloaders.respond_to?(:main)
+        %i[main once].filter_map do |name|
+          next unless autoloaders.respond_to?(name)
 
-        main = autoloaders.main
-        main.respond_to?(:dirs) ? main : nil
+          loader = autoloaders.public_send(name)
+          loader if loader.respond_to?(:dirs)
+        end.uniq
       rescue StandardError
-        nil
+        []
       end
 
       # Camelize one path segment the way Zeitwerk's default inflector