woods 2.0.1 → 2.1.0

data/lib/woods/extractors/migration_declaration.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative 'class_declarations'
+require_relative '../source_references/runtime_lookup'
+
+module Woods
+  module Extractors
+    # Identifies migration declarations without running historical migration code.
+    # Filename ownership disambiguates a migration from its local migration base.
+    class MigrationDeclaration
+      class Ambiguous < StandardError; end
+
+      # @param source [String] original Ruby source
+      # @param file_path [String] migration filename
+      def initialize(source:, file_path:)
+        @declarations = ClassDeclarations.read(source)
+        @lookup = SourceReferences::RuntimeLookup.new
+        @expected = File.basename(file_path, '.rb').sub(/\A\d+_/, '').camelize
+      end
+
+      # @return [Hash, nil] selected identifier and its declaration source
+      # @raise [Ambiguous] when ownership is ambiguous
+      def call
+        candidates = @declarations.select { |record| migration?(record, []) }.group_by { |record| record[:identifier] }
+        selected = select_identity(candidates.keys)
+        return unless selected
+
+        source = @declarations.select { |record| record[:identifier] == selected }.map { |record| record[:source] }
+        { identifier: selected, source: source.join("\n") }
+      end
+
+      private
+
+      def select_identity(identifiers)
+        matching = identifiers.select { |name| name == @expected }
+        matching = identifiers.select { |name| name.split('::').last == @expected } if matching.empty?
+        matching = identifiers if matching.empty?
+        return matching.first if matching.size <= 1
+
+        raise Ambiguous, "Ambiguous migration declaration: #{matching.join(', ')}"
+      end
+
+      def migration?(record, visiting)
+        identifier = record.fetch(:identifier)
+        return false if visiting.include?(identifier)
+
+        parent = ClassDeclarations.parent_name(record)
+        return false unless parent
+
+        local = local_parent(parent, record.fetch(:nesting))
+        return local.any? { |candidate| migration?(candidate, [*visiting, identifier]) } unless local.empty?
+
+        runtime_parent?(parent, record.fetch(:nesting))
+      end
+
+      def local_parent(parent, nesting)
+        candidates = if parent.start_with?('::')
+                       [parent.delete_prefix('::')]
+                     else
+                       nesting.map { |scope| "#{scope}::#{parent}" } + [parent]
+                     end
+        candidates.each do |name|
+          records = @declarations.select { |record| record[:identifier] == name }
+          return records unless records.empty?
+        end
+        []
+      end
+
+      def runtime_parent?(parent, nesting)
+        result = @lookup.call(parent, nesting: nesting, allow_private: true)
+        if result[:status] == :resolved
+          return false unless @lookup.class_object?(result[:value])
+
+          return @lookup.reflect(result[:value], :ancestors).any? do |ancestor|
+            @lookup.reflect(ancestor, :name) == 'ActiveRecord::Migration'
+          end
+        end
+        return false unless %w[constant_missing unloaded_scope autoload_pending].include?(result[:reason])
+
+        # The standard Rails declaration is structural evidence even when the
+        # migration namespace has never been loaded. Unknown custom bases are
+        # not inferred from their spelling or evaluated to find out.
+        parent.delete_prefix('::') == 'ActiveRecord::Migration'
+      end
+    end
+  end
+end

data/lib/woods/extractors/migration_extractor.rb

@@ -4,6 +4,7 @@ require_relative '../source_inputs/consumer_errors'
 
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
+require_relative 'migration_declaration'
 
 module Woods
   module Extractors
@@ -106,10 +107,10 @@ module Woods
       # @return [ExtractedUnit, nil] The extracted unit or nil if not a migration
       def extract_migration_file(file_path)
         source = File.read(file_path)
-        class_name = extract_class_name(source)
+        declaration = MigrationDeclaration.new(source: source, file_path: file_path).call
+        return nil unless declaration
 
-        return nil unless class_name
-        return nil unless migration_class?(source)
+        class_name = declaration.fetch(:identifier)
 
         unit = ExtractedUnit.new(
           type: :migration,
@@ -118,7 +119,7 @@ module Woods
         )
 
         unit.namespace = extract_namespace(class_name)
-        unit.metadata = extract_metadata(source, file_path)
+        unit.metadata = extract_metadata(declaration.fetch(:source), file_path)
         unit.source_code = annotate_source(source, class_name, unit.metadata)
         unit.dependencies = extract_dependencies(source, unit.metadata)
 
@@ -130,41 +131,6 @@ module Woods
 
       private
 
-      # ──────────────────────────────────────────────────────────────────────
-      # Class Discovery
-      # ──────────────────────────────────────────────────────────────────────
-
-      # Extract the class name from migration source code.
-      #
-      # @param source [String] Ruby source code
-      # @return [String, nil] The class name or nil
-      def extract_class_name(source)
-        # Match namespaced or plain class declarations
-        namespaces = source.scan(/^\s*module\s+([\w:]+)/).flatten
-        class_match = source.match(/^\s*class\s+([\w:]+)\s*</)
-        return nil unless class_match
-
-        base_class = class_match[1]
-        if namespaces.any? && !base_class.include?('::')
-          "#{namespaces.join('::')}::#{base_class}"
-        else
-          base_class
-        end
-      end
-
-      # Check whether the source defines an ActiveRecord::Migration subclass.
-      #
-      # `[\w:]+`, matching {#extract_class_name}'s class-name pattern — a
-      # compact-form declaration (`class Billing::AddFoo < ...`) satisfies
-      # extract_class_name but failed the plain `\w+` here, so the file was
-      # silently skipped even though it had a resolvable identifier.
-      #
-      # @param source [String] Ruby source code
-      # @return [Boolean]
-      def migration_class?(source)
-        source.match?(/class\s+[\w:]+\s*<\s*ActiveRecord::Migration/)
-      end
-
       # ──────────────────────────────────────────────────────────────────────
       # Metadata Extraction
       # ──────────────────────────────────────────────────────────────────────

data/lib/woods/extractors/phlex_extractor.rb

@@ -66,7 +66,7 @@ module Woods
         return [] unless @component_base
 
         load_component_files
-        @component_base.descendants
+        @component_base.descendants.select { |component| app_component?(component) }
       end
 
       # Extract a single component
@@ -74,7 +74,7 @@ module Woods
       # @param component [Class] The component class
       # @return [ExtractedUnit] The extracted unit
       def extract_component(component)
-        return nil if component.name.nil?
+        return nil unless app_component?(component)
 
         unit = ExtractedUnit.new(
           type: :component,
@@ -95,6 +95,10 @@ module Woods
 
       private
 
+      def app_component?(component)
+        @component_base && component.name && component < @component_base && app_source_file?(source_file_for(component))
+      end
+
       # Find the base component class used in the application.
       # Skips ApplicationComponent if it's actually a ViewComponent subclass
       # to avoid extracting ViewComponent classes with Phlex-specific metadata.

data/lib/woods/extractors/policy_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
@@ -66,7 +67,8 @@ module Woods
 
         unit.namespace = extract_namespace(class_name)
         unit.source_code = annotate_source(source, class_name)
-        unit.metadata = extract_metadata(source, class_name)
+        ancestry = DeclarationAncestry.new(source: source, identifier: class_name, file_path: file_path)
+        unit.metadata = extract_metadata(source, class_name, ancestry)
         unit.dependencies = extract_dependencies(source, class_name)
 
         unit
@@ -100,14 +102,14 @@ module Woods
       # Metadata Extraction
       # ──────────────────────────────────────────────────────────────────────
 
-      def extract_metadata(source, class_name)
+      def extract_metadata(source, class_name, ancestry)
         {
           evaluated_models: detect_evaluated_models(source, class_name),
           decision_methods: detect_decision_methods(source),
           public_methods: extract_public_methods(source),
           class_methods: extract_class_methods(source),
           initialize_params: extract_initialize_params(source),
-          is_pundit: pundit_policy?(source),
+          is_pundit: pundit_policy?(source, ancestry),
           custom_errors: extract_custom_errors(source),
           loc: source.lines.count { |l| l.strip.length.positive? && !l.strip.start_with?('#') },
           method_count: source.scan(/def\s+(?:self\.)?\w+/).size
@@ -165,8 +167,10 @@ module Woods
         models.uniq
       end
 
-      def pundit_policy?(source)
-        source.match?(/< ApplicationPolicy/) ||
+      def pundit_policy?(source, ancestry)
+        return false if ancestry.foreign?
+
+        ancestry.application_policy? ||
           source.match?(/def\s+initialize\s*\(\s*user\s*,/) ||
           source.match?(/attr_reader\s+:user\s*,\s*:record/)
       end

data/lib/woods/extractors/poro_extractor.rb

@@ -5,6 +5,9 @@ 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 'standalone_module_discovery'
+require_relative 'assigned_value_discovery'
 
 module Woods
   module Extractors
@@ -16,7 +19,8 @@ module Woods
     # wrappers, and any other non-AR class living alongside AR models.
     #
     # Files under app/models/concerns/ are excluded — those are handled by
-    # ConcernExtractor. Module-only files are also excluded.
+    # ConcernExtractor. Callable standalone modules use the existing poro type,
+    # with explicit module metadata and verified runtime/source ownership.
     #
     # @example
     #   extractor = PoroExtractor.new
@@ -51,76 +55,121 @@ module Woods
 
         ar_names = ActiveRecord::Base.descendants.filter_map(&:name).to_set
 
-        Dir[Rails.root.join(MODELS_GLOB)].filter_map do |file|
-          next if file.include?(CONCERNS_SEGMENT)
+        @module_discovery = StandaloneModuleDiscovery.new
+        Dir[Rails.root.join(MODELS_GLOB)].flat_map do |file|
+          next [] if file.include?(CONCERNS_SEGMENT)
 
-          extract_poro_file(file, ar_names: ar_names)
+          extract_poro_units(file, ar_names: ar_names)
         end
       end
 
-      # Extract a single PORO file.
-      #
-      # Returns nil if the file is not a PORO (e.g., module-only, no class
-      # or PORO pattern found, or the inferred class is an AR descendant).
+      # Preserve the historical single-unit return contract. A class remains
+      # primary when a file also declares callable standalone modules.
       #
-      # @param file_path [String] Absolute path to the Ruby file
-      # @param ar_names [Set<String>] Set of AR descendant names to skip
-      # @return [ExtractedUnit, nil] The extracted unit or nil
+      # @param file_path [String] original Ruby file
+      # @param ar_names [Set<String>] Active Record identities to exclude
+      # @return [ExtractedUnit, nil] primary class or first standalone module
       def extract_poro_file(file_path, ar_names: Set.new)
+        extract_poro_units(file_path, ar_names: ar_names).first
+      end
+
+      # Extract every owned unit from one file; incremental dispatch uses this
+      # form so a concern and a standalone sibling can share source safely.
+      #
+      # @param file_path [String] original Ruby file
+      # @param ar_names [Set<String>] Active Record identities to exclude
+      # @return [Array<ExtractedUnit>] legacy class followed by standalone modules
+      def extract_poro_units(file_path, ar_names: Set.new)
         source = File.read(file_path)
+        analysis = SourceReferences::Collector.new.call(source)
+        primary = extract_class_unit(file_path, source, ar_names, analysis)
+        discovery = (@module_discovery ||= StandaloneModuleDiscovery.new)
+        modules = discovery.call(file_path, analysis: analysis).map { |record| module_unit(file_path, source, record) }
+        [primary, *modules].compact
+      rescue StandardError => e
+        SourceInputs::ConsumerErrors.log(self, "Failed to extract PORO #{file_path}: #{e.message}")
+        []
+      end
+
+      # Recompute unclaimed module identities for includer-only reconciliation.
+      # The root pipeline owns cross-family migration and source-consumption.
+      #
+      # @return [Hash<String, Array<ExtractedUnit>>] absolute paths and module units
+      def standalone_modules
+        @module_discovery = StandaloneModuleDiscovery.new
+        return {} unless @models_dir.directory?
+
+        Dir[Rails.root.join(MODELS_GLOB)].each_with_object({}) do |file, result|
+          next if file.include?(CONCERNS_SEGMENT)
+
+          units = extract_standalone_module_file(file)
+          result[file] = units unless units.empty?
+        end
+      end
+
+      private
+
+      def extract_standalone_module_file(file)
+        source = File.read(file)
+        analysis = SourceReferences::Collector.new.call(source)
+        @module_discovery.call(file, analysis: analysis).map { |record| module_unit(file, source, record) }
+      rescue StandardError => e
+        SourceInputs::ConsumerErrors.log(self, "Failed to extract standalone module #{file}: #{e.message}")
+        []
+      end
 
-        return nil unless poro_file?(source)
-        return nil if module_only?(source)
+      def extract_class_unit(file_path, source, ar_names, analysis)
+        return nil unless class_source?(source, analysis)
 
-        class_name = infer_class_name(file_path, source)
+        class_name = infer_class_name(file_path, source, analysis)
         return nil unless class_name
         return nil if ar_names.include?(class_name)
+        return nil if analysis.fetch('declarations').any? do |declaration|
+          declaration['owner'] == class_name && declaration['kind'] == 'module'
+        end
 
-        unit = ExtractedUnit.new(
-          type: :poro,
-          identifier: class_name,
-          file_path: file_path
-        )
-
+        unit = ExtractedUnit.new(type: :poro, identifier: class_name, file_path: file_path)
         parent_class = extract_parent_class(source, class_name)
-
-        unit.namespace    = extract_namespace(class_name)
-        unit.source_code  = annotate_source(source, class_name, parent_class)
-        unit.metadata     = extract_metadata(source, parent_class)
+        unit.namespace = extract_namespace(class_name)
+        unit.source_code = annotate_source(source, class_name, parent_class)
+        unit.metadata = extract_metadata(source, parent_class)
         unit.dependencies = extract_dependencies(source)
-
         unit
-      rescue StandardError => e
-        SourceInputs::ConsumerErrors.log(self, "Failed to extract PORO #{file_path}: #{e.message}")
-        nil
       end
 
-      private
+      def module_unit(file_path, source, record)
+        identifier = record.fetch(:identifier)
+        unit = ExtractedUnit.new(type: :poro, identifier: identifier, file_path: file_path)
+        unit.namespace = extract_namespace(identifier)
+        unit.source_code = annotate_source(source, identifier, nil)
+        unit.metadata = record.except(:identifier).merge(ruby_kind: 'module', parent_class: nil,
+                                                         initialize_params: [], loc: count_loc(source))
+        # Shared-file regex scans cannot attribute a sibling's references safely.
+        # The source-reference pass owns method/body references for these units.
+        unit.dependencies = []
+        unit
+      end
 
       # ──────────────────────────────────────────────────────────────────────
       # File Classification
       # ──────────────────────────────────────────────────────────────────────
 
-      # Determine whether a file is worth examining as a PORO.
-      #
-      # A file qualifies if it contains a class definition OR uses one of the
-      # common PORO-without-class patterns (Struct.new, Data.define).
-      # Plain constant assignments and module-only files are excluded upstream.
-      #
-      # @param source [String] Ruby source code
-      # @return [Boolean]
-      def poro_file?(source)
-        source.match?(/^\s*class\s+/) ||
-          source.match?(/\bStruct\.new\b/) ||
-          source.match?(/\bData\.define\b/)
-      end
-
-      # Return true when the file defines only modules, no class keyword.
-      #
-      # @param source [String] Ruby source code
-      # @return [Boolean]
-      def module_only?(source)
-        source.match?(/^\s*module\s+\w+/) && !source.match?(/^\s*class\s+/)
+      # Singleton-class syntax does not establish a class-owned unit. Keep
+      # legacy Struct/Data handling while requiring an actual class declaration.
+      def class_source?(source, analysis)
+        # Preserve the legacy single-class excerpt behavior on invalid fragments;
+        # no runtime module ownership is inferred from an unsuccessful parse.
+        has_class = if analysis['parse_error']
+                      source.match?(/^\s*class\s+/)
+                    else
+                      analysis.fetch('declarations').any? do |declaration|
+                        declaration['kind'] == 'class' && declaration.fetch('singleton_depth', 0).zero?
+                      end
+                    end
+        return true if has_class
+        return false if source.match?(/^\s*module\s+\w+/)
+
+        source.match?(/\bStruct\.new\b/) || source.match?(/\bData\.define\b/)
       end
 
       # ──────────────────────────────────────────────────────────────────────
@@ -140,15 +189,25 @@ module Woods
       # @param file_path [String] Absolute path to the file
       # @param source [String] Ruby source code
       # @return [String, nil] The inferred class name
-      def infer_class_name(file_path, source)
+      def infer_class_name(file_path, source, analysis = SourceReferences::Collector.new.call(source))
         # Explicit class keyword — Zeitwerk-governed naming first (G-1), then
         # enclosing modules joined by position (#174)
+        assigned = AssignedValueDiscovery.new.call(file_path, analysis: analysis,
+                                                              expected: managed_constant_path(file_path.to_s))
+        return assigned if assigned
+
         qualified = governed_class_name(file_path, source) || qualified_first_class_name(source)
         return qualified if qualified
 
-        # Struct.new / Data.define: ConstantName = Struct.new(...)
-        struct_match = source.match(/^(\w[\w:]*)\s*=\s*(?:Struct\.new|Data\.define)/)
-        return struct_match[1] if struct_match
+        # Preserve historical top-level assignment lookup identities, including
+        # named Struct aliases. Reference targets still require verified ownership.
+        assignments = analysis.fetch('declarations').select { |record| record['constructor'] }
+        unless assignments.empty?
+          legacy = assignments.find do |record|
+            record['enclosing_nesting'].empty? && record.fetch('singleton_depth', 0).zero?
+          end
+          return legacy && legacy['owner']
+        end
 
         # Fall back: derive from file path using Rails naming convention
         path_based_class_name(file_path)

data/lib/woods/extractors/pundit_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
@@ -54,7 +55,9 @@ module Woods
         class_name = extract_class_name(file_path, source)
 
         return nil unless class_name
-        return nil unless pundit_policy?(source)
+
+        ancestry = DeclarationAncestry.new(source: source, identifier: class_name, file_path: file_path)
+        return nil unless pundit_policy?(source, ancestry)
 
         unit = ExtractedUnit.new(
           type: :pundit_policy,
@@ -64,7 +67,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
@@ -100,8 +103,10 @@ module Woods
       #
       # @param source [String] Ruby source code
       # @return [Boolean]
-      def pundit_policy?(source)
-        source.match?(/< ApplicationPolicy/) ||
+      def pundit_policy?(source, ancestry)
+        return false if ancestry.foreign?
+
+        ancestry.application_policy? ||
           (source.match?(/attr_reader\s+:user/) && source.match?(/attr_reader.*:record/)) ||
           (source.match?(/def\s+initialize\s*\(\s*user\s*,/) && source.match?(/def\s+\w+\?/))
       end
@@ -135,7 +140,7 @@ module Woods
       # @param source [String]
       # @param class_name [String]
       # @return [Hash]
-      def extract_metadata(source, class_name)
+      def extract_metadata(source, class_name, ancestry)
         actions = detect_authorization_actions(source)
         {
           model: infer_model(class_name),
@@ -143,7 +148,7 @@ module Woods
           standard_actions: actions & PUNDIT_ACTIONS,
           custom_actions: actions - PUNDIT_ACTIONS,
           has_scope_class: source.match?(/class\s+Scope\b/) || false,
-          inherits_application_policy: source.match?(/< ApplicationPolicy/) || false,
+          inherits_application_policy: ancestry.application_policy?,
           public_methods: extract_public_methods(source),
           class_methods: extract_class_methods(source),
           loc: source.lines.count { |l| l.strip.length.positive? && !l.strip.start_with?('#') },

data/lib/woods/extractors/scheduled_job_extractor.rb

@@ -3,6 +3,7 @@
 require_relative '../source_inputs/consumer_errors'
 
 require 'yaml'
+require 'set'
 begin
   require 'active_support/configuration_file'
 rescue LoadError
@@ -62,9 +63,7 @@ module Woods
       #
       # @return [Array<ExtractedUnit>] List of scheduled job units
       def extract_all
-        @schedule_files.flat_map do |file_path, format|
-          extract_scheduled_job_file(file_path, format)
-        end
+        allocate_identifiers(schedule_units(@schedule_files))
       end
 
       # Extract scheduled job entries from a single schedule file.
@@ -76,6 +75,18 @@ module Woods
       # @param format [Symbol] One of :solid_queue, :sidekiq_cron, :whenever
       # @return [Array<ExtractedUnit>] List of scheduled job units
       def extract_scheduled_job_file(file_path, format)
+        path = File.expand_path(file_path.to_s)
+        files = @schedule_files.merge(path => format)
+        allocate_identifiers(schedule_units(files)).select { |unit| unit.file_path == path }
+      end
+
+      private
+
+      def schedule_units(files)
+        files.flat_map { |path, format| extract_schedule_file(path, format) }
+      end
+
+      def extract_schedule_file(file_path, format)
         case format
         when :solid_queue, :sidekiq_cron
           extract_yaml_schedule(file_path, format)
@@ -89,7 +100,35 @@ module Woods
         []
       end
 
-      private
+      # Keep every unique legacy identifier. Reserve those first, then qualify
+      # conflicting names in deterministic format order without stealing a
+      # literal task name that already looks like one of our generated names.
+      def allocate_identifiers(units)
+        groups = units.group_by(&:identifier)
+        reserved = groups.select { |_identifier, entries| entries.one? }.keys.to_set
+        groups.keys.sort.each do |identifier|
+          entries = groups.fetch(identifier)
+          next if entries.one?
+
+          formats = entries.map { |unit| unit.metadata.fetch(:schedule_format) }
+          if formats.uniq.size != formats.size
+            raise ArgumentError, "Ambiguous same-format schedule name: #{identifier.inspect}"
+          end
+
+          entries.sort_by { |unit| unit.metadata.fetch(:schedule_format).to_s }.each do |unit|
+            base = "scheduled:#{unit.metadata.fetch(:schedule_format)}:#{identifier.delete_prefix('scheduled:')}"
+            candidate = base
+            suffix = 1
+            while reserved.include?(candidate)
+              suffix += 1
+              candidate = "#{base}:#{suffix}"
+            end
+            unit.identifier = candidate
+            reserved.add(candidate)
+          end
+        end
+        units
+      end
 
       # ──────────────────────────────────────────────────────────────────────
       # YAML-based formats (Solid Queue, Sidekiq-Cron)
@@ -190,6 +229,7 @@ module Woods
         unit.source_code = source
         unit.metadata = {
           schedule_format: format,
+          task_name: task_name.to_s,
           job_class: job_class,
           cron_expression: cron,
           queue: config['queue'],
@@ -324,6 +364,7 @@ module Woods
         unit.source_code = source
         unit.metadata = {
           schedule_format: :whenever,
+          task_name: identifier.delete_prefix('scheduled:'),
           job_class: block[:job_class],
           cron_expression: block[:frequency],
           command_type: block[:command_type],