woods 1.6.1 → 2.0.0.beta2

data/lib/woods/extractors/model_extractor.rb

@@ -48,12 +48,22 @@ module Woods
       #
       # @return [Array<ExtractedUnit>] List of model units
       def extract_all
+        discoverable_classes.map { |model| extract_model(model) }.compact
+      end
+
+      # The model classes this extractor would extract from the running app.
+      #
+      # Shared with the incremental path, which reconciles this set against
+      # the identifiers already in the dependency graph to spot classes added
+      # since the last extraction (#164). Keeping discovery in one method is
+      # what makes that reconciliation exact rather than a re-guess.
+      #
+      # @return [Array<Class>]
+      def discoverable_classes
         ActiveRecord::Base.descendants
-                          .reject(&:abstract_class?)
+                          .reject { |m| abstract_class?(m) }
                           .reject { |m| m.name.nil? } # Skip anonymous classes
                           .reject { |m| habtm_join_model?(m) }
-                          .map { |model| extract_model(model) }
-                          .compact
       end
 
       # Extract a single model
@@ -71,12 +81,15 @@ module Woods
         source = source_path && File.exist?(source_path) ? File.read(source_path) : nil
 
         unit.namespace = model.module_parent.name unless model.module_parent == Object
-        unit.source_code = build_composite_source(model, source)
-        unit.metadata = extract_metadata(model, source)
+        inlined_source, inlined_concerns = build_model_source_with_concerns(model, source)
+        unit.source_code = build_composite_source(model, inlined_source)
+        unit.metadata = extract_metadata(model, source, inlined_concerns: inlined_concerns)
         unit.dependencies = extract_dependencies(model, source)
 
-        # Enrich callbacks with side-effect analysis
-        enrich_callbacks_with_side_effects(unit, source)
+        # Enrich callbacks with side-effect analysis. The analyzer parses real
+        # Ruby, so it gets the raw analysis composite — the display composite
+        # comments concern bodies out, which Prism cannot see.
+        enrich_callbacks_with_side_effects(unit, source, analysis_source: build_analysis_source(model, source))
 
         # Build semantic chunks for all models (summary, associations, callbacks, validations)
         unit.chunks = build_chunks(unit)
@@ -90,11 +103,28 @@ module Woods
 
       private
 
+      # Is this an abstract AR base class? Guarded exactly like
+      # {Woods::ModelNameCache#abstract_model?}: a descendant that raises on
+      # the call (a half-loaded class under the NameError fallback) is kept
+      # rather than dropped. An unguarded `.reject(&:abstract_class?)` here
+      # let that raise escape {#discoverable_classes} and abort the whole
+      # models phase (L1); per-class extraction failures are already handled
+      # by {#extract_model}'s own rescue.
+      #
+      # @param klass [Class]
+      # @return [Boolean] true when the class is an abstract AR base class
+      def abstract_class?(klass)
+        klass.respond_to?(:abstract_class?) && klass.abstract_class?
+      rescue StandardError
+        false
+      end
+
       # Find the source file for a model, handling STI and namespacing.
       #
       # Uses convention path first (most reliable for models), then falls
-      # back to introspection via {#resolve_source_location} which filters
-      # out vendor/node_modules paths.
+      # back to introspection via {#resolve_source_location}, which prefers
+      # app-owned locations and keeps a gem-owned class (an engine model) at
+      # its real gem path rather than a synthesized app path.
       def source_file_for(model)
         convention_path = Rails.root.join("app/models/#{model.name.underscore}.rb").to_s
         return convention_path if File.exist?(convention_path)
@@ -110,17 +140,15 @@ module Woods
         model.name.demodulize.start_with?('HABTM_')
       end
 
-      # Build composite source with schema header and inlined concerns
-      def build_composite_source(model, source = nil)
-        parts = []
-
-        # Schema information as a header comment
-        parts << build_schema_comment(model)
-
-        # Main model source with concerns inlined
-        parts << build_model_source_with_concerns(model, source)
-
-        parts.compact.join("\n\n")
+      # Build composite source with schema header and the concern-inlined
+      # model source.
+      #
+      # @param model [Class] The ActiveRecord model class
+      # @param inlined_source [String] Model source with concerns already
+      #   inlined (see {#build_model_source_with_concerns})
+      # @return [String]
+      def build_composite_source(model, inlined_source)
+        [build_schema_comment(model), inlined_source].compact.join("\n\n")
       end
 
       # Generate schema comment block with columns, indexes, and foreign keys
@@ -181,39 +209,93 @@ module Woods
         []
       end
 
-      # Read model source and inline all included concerns
+      # Read model source and inline all included concerns.
+      #
+      # Concern code is inserted as '# '-prefixed comment lines right after
+      # the model's class declaration, matching both nested (+class Book+)
+      # and compact (+class Library::Book+) declaration styles. When no
+      # declaration line can be found in unconventional source, the block is
+      # appended at the end instead of being silently discarded, and a
+      # warning naming the model is recorded.
+      #
+      # @param model [Class] The ActiveRecord model class
+      # @param source [String, nil] Pre-read model source (read from disk when nil)
+      # @return [Array(String, Array<String>)] The concern-inlined source and
+      #   the demodulized names of the concerns actually inlined into it.
+      #   Returning the pair keeps metadata[:inlined_concerns] truthful —
+      #   it is derived from the insertion result, never recomputed
+      #   independently of what the composite source carries.
       def build_model_source_with_concerns(model, source = nil)
         if source.nil?
           source_path = source_file_for(model)
-          return '' unless source_path && File.exist?(source_path)
+          return ['', []] unless source_path && File.exist?(source_path)
 
           source = File.read(source_path)
         end
 
-        # Find all included concerns and inline them
-        included_modules = extract_included_modules(model)
-        concern_sources = included_modules.filter_map { |mod| concern_source(mod) }
-
-        if concern_sources.any?
-          # Insert concern code as comments showing what's mixed in
-          concern_block = concern_sources.map do |name, code|
-            indented = code.lines.map { |l| "  # #{l.rstrip}" }.join("\n")
-            <<~CONCERN
-              # ┌─────────────────────────────────────────────────────────────────────┐
-              # │ Included from: #{name.ljust(54)}│
-              # └─────────────────────────────────────────────────────────────────────┘
-              #{indented}
-              # ─────────────────────────── End #{name} ───────────────────────────
-            CONCERN
-          end.join("\n\n")
-
-          # Insert after class declaration line
-          source.sub(/(class\s+#{Regexp.escape(model.name.demodulize)}.*$)/) do
-            "#{::Regexp.last_match(1)}\n\n#{concern_block}"
-          end
-        else
-          source
-        end
+        concern_sources = resolved_concern_sources(model)
+        return [source, []] if concern_sources.empty?
+
+        [insert_concern_block(model, source, build_concern_block(concern_sources)),
+         concern_sources.map { |name, _code| name.demodulize }]
+      end
+
+      # Resolve [name, code] pairs for every concern included in the model
+      # whose source file can be located.
+      #
+      # @param model [Class] The ActiveRecord model class
+      # @return [Array<Array(String, String)>]
+      def resolved_concern_sources(model)
+        extract_included_modules(model).filter_map { |mod| concern_source(mod) }
+      end
+
+      # Render concern sources as a '#'-commented display block showing
+      # what's mixed in.
+      #
+      # @param concern_sources [Array<Array(String, String)>] [name, code] pairs
+      # @return [String]
+      def build_concern_block(concern_sources)
+        concern_sources.map do |name, code|
+          indented = code.lines.map { |l| "  # #{l.rstrip}" }.join("\n")
+          <<~CONCERN
+            # ┌─────────────────────────────────────────────────────────────────────┐
+            # │ Included from: #{name.ljust(54)}│
+            # └─────────────────────────────────────────────────────────────────────┘
+            #{indented}
+            # ─────────────────────────── End #{name} ───────────────────────────
+          CONCERN
+        end.join("\n\n")
+      end
+
+      # Insert the concern block after the model's class declaration line.
+      #
+      # Falls back to appending at end-of-source (recording a warning) when
+      # no declaration matches — dropping the block silently would leave
+      # source_code contradicting metadata[:inlined_concerns].
+      #
+      # @param model [Class] The ActiveRecord model class
+      # @param source [String] The model source
+      # @param concern_block [String] Commented concern block to insert
+      # @return [String]
+      def insert_concern_block(model, source, concern_block)
+        pattern = class_declaration_pattern(model)
+        return source.sub(pattern) { "#{::Regexp.last_match(1)}\n\n#{concern_block}" } if source.match?(pattern)
+
+        @warnings << "[#{model.name}] No class declaration matched for concern inlining; " \
+                     'appending inlined concern block at end of source'
+        "#{source.chomp}\n\n#{concern_block}"
+      end
+
+      # Regexp matching the model's class declaration in either nested
+      # (+class Book+) or compact (+class Library::Book+) style. The word
+      # boundary stops +class BookmarkError+ from claiming model Book's
+      # concern block; the +(?!::)+ lookahead stops a nested
+      # +class Book::Error+ from claiming it either.
+      #
+      # @param model [Class] The ActiveRecord model class
+      # @return [Regexp]
+      def class_declaration_pattern(model)
+        /(class\s+(?:[\w:]+::)?#{Regexp.escape(model.name.demodulize)}\b(?!::).*$)/
       end
 
       # Get modules included specifically in this model (not inherited)
@@ -315,11 +397,21 @@ module Woods
       # ──────────────────────────────────────────────────────────────────────
 
       # Extract comprehensive metadata for retrieval and filtering
-      def extract_metadata(model, source = nil)
+      #
+      # @param model [Class] The ActiveRecord model class
+      # @param source [String, nil] The model source code
+      # @param inlined_concerns [Array<String>, nil] Demodulized names of the
+      #   concerns actually inlined into the unit's source_code (from
+      #   {#build_model_source_with_concerns}). When nil, derived by running
+      #   the same inlining — the metadata must never claim a concern the
+      #   composite source does not carry.
+      # @return [Hash]
+      def extract_metadata(model, source = nil, inlined_concerns: nil)
         {
           # Core identifiers
           table_name: model.table_name,
           primary_key: model.primary_key,
+          database: database_name_for(model),
 
           # Relationships and behaviors
           associations: extract_associations(model),
@@ -327,9 +419,7 @@ module Woods
           callbacks: extract_callbacks(model),
           scopes: extract_scopes(model, source),
           enums: extract_enums(model),
-          inlined_concerns: extract_included_modules(model)
-                            .select { |mod| mod.name && concern_source(mod) }
-                            .map { |mod| mod.name.demodulize },
+          inlined_concerns: inlined_concerns || build_model_source_with_concerns(model, source).last,
 
           # API surface
           class_methods: model.methods(false).sort,
@@ -359,6 +449,11 @@ module Woods
                      []
                    end,
 
+          # Foreign keys as the connection reports them. The target table's
+          # database is a graph-level concern, resolved by the
+          # cross_database_edges report, not stored per model here (#280).
+          foreign_keys: extract_foreign_keys(model),
+
           # ActiveStorage / ActionText
           active_storage_attachments: extract_active_storage_attachments(source),
           action_text_fields: extract_action_text_fields(source),
@@ -464,7 +559,15 @@ module Woods
       # Extract all associations with full details.
       # Broken associations (e.g. missing class_name) are skipped with a warning
       # instead of aborting the entire model extraction.
+      #
+      # `from_db` and `to_db` name the database each side resolves to (nil on
+      # Rails 6.0, where `connection_db_config` does not exist, and nil on
+      # the target side for a polymorphic or unresolvable class). `through_db`
+      # names the database a has_many :through join model resolves to (#280),
+      # nil for a plain association.
+      # `disable_joins` is the Rails 7.0+ option read from the reflection.
       def extract_associations(model)
+        from_db = database_name_for(model)
         model.reflect_on_all_associations.filter_map do |assoc|
           {
             name: assoc.name,
@@ -472,9 +575,13 @@ module Woods
             target: assoc.class_name,
             options: extract_association_options(assoc),
             through: assoc.options[:through],
+            through_db: through_association_database(assoc),
             polymorphic: assoc.polymorphic?,
             foreign_key: assoc.foreign_key,
-            inverse_of: assoc.inverse_of&.name
+            inverse_of: assoc.inverse_of&.name,
+            from_db: from_db,
+            to_db: association_target_database(assoc),
+            disable_joins: assoc.options[:disable_joins] == true
           }
         rescue NameError => e
           @warnings << "[#{model.name}] Skipping broken association #{assoc.name}: #{e.message}"
@@ -487,7 +594,7 @@ module Woods
           :dependent, :through, :source, :source_type,
           :foreign_key, :primary_key, :inverse_of,
           :counter_cache, :touch, :optional, :required,
-          :class_name, :as, :foreign_type
+          :class_name, :as, :foreign_type, :disable_joins
         )
       end
 
@@ -615,11 +722,34 @@ module Woods
       # Dependency Extraction
       # ──────────────────────────────────────────────────────────────────────
 
-      # Extract what this model depends on
+      # Extract what this model depends on.
+      #
+      # Association reflections normally become a +:model+ edge labeled with
+      # the association macro. Polymorphic associations are the exception:
+      # `belongs_to :commentable, polymorphic: true` names an *interface*,
+      # not a model — +AssociationReflection#class_name+ camelizes the
+      # association name ("Commentable") without constantizing it, so the
+      # NameError rescue never fires and the edge pointed at a nonexistent
+      # node, or worse, at an unrelated real constant (an app's Commentable
+      # concern) mislabeled as a +:belongs_to+ model edge (#199). Those
+      # edges now carry +via: :polymorphic_interface+ instead of the macro:
+      # the interface name stays visible in the graph but is distinguishable
+      # from a resolvable model reference.
       def extract_dependencies(model, source = nil)
-        # Associations point to other models
+        # Associations point to other models. `through`, `through_db`, and
+        # `disable_joins` ride on the edge so the graph can report a
+        # has_many :through that crosses databases without disable_joins,
+        # or whose join model itself sits on a third database (#280).
         deps = model.reflect_on_all_associations.filter_map do |assoc|
-          { type: :model, target: assoc.class_name, via: assoc.macro }
+          via = polymorphic_reflection?(assoc) ? :polymorphic_interface : assoc.macro
+          dep = { type: :model, target: assoc.class_name, via: via }
+          if assoc.options[:through]
+            dep[:through] = assoc.options[:through].to_s
+            through_db = through_association_database(assoc)
+            dep[:through_db] = through_db if through_db
+          end
+          dep[:disable_joins] = true if assoc.options[:disable_joins] == true
+          dep
         rescue NameError => e
           @warnings << "[#{model.name}] Skipping broken association dep #{assoc.name}: #{e.message}"
           nil
@@ -657,18 +787,123 @@ module Woods
         consolidate_dependencies(deps)
       end
 
+      # Whether an association reflection declares a polymorphic interface.
+      #
+      # Guarded with +respond_to?+ because not every reflection type across
+      # Rails versions exposes +#polymorphic?+ — a reflection without it is
+      # treated as a plain (non-polymorphic) association.
+      #
+      # @param assoc [ActiveRecord::Reflection::AbstractReflection]
+      # @return [Boolean]
+      def polymorphic_reflection?(assoc)
+        assoc.respond_to?(:polymorphic?) && assoc.polymorphic?
+      end
+
+      # The database a class resolves to, by runtime reflection.
+      #
+      # `connection_db_config` (Rails 6.1+) climbs to the abstract class that
+      # declared `connects_to`, so a concrete model that inherits its
+      # connection answers with the inherited database. This is what a
+      # regex over `connects_to database:` in the source could never see.
+      # Rails 6.0 has no `connection_db_config`; the answer degrades to nil.
+      #
+      # @param klass [Class]
+      # @return [String, nil]
+      def database_name_for(klass)
+        return nil unless klass.respond_to?(:connection_db_config)
+
+        config = klass.connection_db_config
+        config.respond_to?(:name) ? config.name.to_s : nil
+      rescue StandardError
+        nil
+      end
+
+      # The database an association's target resolves to. Nil for a
+      # polymorphic interface (no single class) and for a target that does
+      # not constantize.
+      #
+      # @param assoc [ActiveRecord::Reflection::AbstractReflection]
+      # @return [String, nil]
+      def association_target_database(assoc)
+        return nil if polymorphic_reflection?(assoc)
+
+        database_name_for(assoc.klass)
+      rescue StandardError
+        nil
+      end
+
+      # The database a has_many :through association's join model resolves
+      # to. Nil for a plain association, when the through reflection cannot
+      # resolve its class, and on Rails 6.0 (no connection_db_config).
+      #
+      # @param assoc [ActiveRecord::Reflection::AbstractReflection]
+      # @return [String, nil]
+      def through_association_database(assoc)
+        return nil unless assoc.options[:through]
+
+        database_name_for(assoc.through_reflection.klass)
+      rescue StandardError
+        nil
+      end
+
+      # Foreign keys declared on the model's table, as the connection
+      # reports them. The target table's database is intentionally not
+      # resolved here, that is left to the graph-level cross_database_edges
+      # report, which resolves it from table owners.
+      #
+      # @param model [Class]
+      # @return [Array<Hash>] `{ from_table:, to_table:, column: }`
+      def extract_foreign_keys(model)
+        return [] unless model.table_exists?
+
+        model.connection.foreign_keys(model.table_name).map do |fk|
+          { from_table: fk.from_table.to_s, to_table: fk.to_table.to_s, column: fk.column.to_s }
+        end
+      rescue StandardError
+        []
+      end
+
+      # Build a parse-friendly composite for callback side-effect analysis.
+      #
+      # The displayed source_code inlines concern code as comment lines — a
+      # deliberate presentation choice — but Prism cannot see commented
+      # code, so the standard idiom (a concern's +included do+ registering a
+      # callback whose method is defined in the concern body) was invisible
+      # to CallbackAnalyzer. This composite concatenates the raw model
+      # source with each concern's raw module source: top-level modules
+      # parse fine and the analyzer's method search walks the whole tree.
+      #
+      # @param model [Class] The ActiveRecord model class
+      # @param source [String, nil] The raw model source
+      # @return [String, nil] Concatenated raw sources, or +source+ when no
+      #   concern source is resolvable
+      def build_analysis_source(model, source)
+        return source unless source
+
+        concern_codes = resolved_concern_sources(model).map { |_name, code| code }
+        return source if concern_codes.empty?
+
+        ([source] + concern_codes).join("\n\n")
+      end
+
       # Enrich callback metadata with side-effect analysis.
       #
       # Uses CallbackAnalyzer to find each callback's method body and
       # classify its side effects (column writes, job enqueues, etc.).
+      # The analyzer parses real Ruby, so callers should hand it a
+      # parse-friendly +analysis_source+ (raw model + raw concern code, see
+      # {#build_analysis_source}) rather than the display composite whose
+      # concern bodies are commented out. Falls back to +unit.source_code+
+      # when no analysis source is given.
       #
       # @param unit [ExtractedUnit] The model unit with metadata[:callbacks] set
       # @param source [String, nil] The model source code
-      def enrich_callbacks_with_side_effects(unit, source)
+      # @param analysis_source [String, nil] Parse-friendly composite source
+      def enrich_callbacks_with_side_effects(unit, source, analysis_source: nil)
         return unless source && unit.metadata[:callbacks]&.any?
 
         analyzer = CallbackAnalyzer.new(
-          source_code: unit.source_code,
+          source_code: analysis_source || unit.source_code,
           column_names: unit.metadata[:column_names] || []
         )
 

data/lib/woods/extractors/package_extractor.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'pathname'
+
+module Woods
+  module Extractors
+    # PackageExtractor reads Packwerk / pks package boundaries (#280).
+    #
+    # One unit per `package.yml`, identified the way Packwerk names packages:
+    # the package directory relative to Rails.root, with `.` for the root
+    # package. Declared dependencies become `:package_dependency` edges, so
+    # the graph can tell a declared cross-package call from an undeclared
+    # one ({Woods::GraphAnalyzer#undeclared_package_edges}). Enforcement stays
+    # with `packwerk check` / `pks check`; Woods only makes the boundary
+    # visible before an agent writes the call.
+    #
+    # Pure file read, no Rails boot needed. Registered as a whole-app
+    # extractor: a package root decides which package every other unit
+    # belongs to, so any `package.yml` change re-runs it wholesale.
+    #
+    # @example
+    #   extractor = PackageExtractor.new
+    #   extractor.extract_all.map(&:identifier)        # => [".", "packs/billing"]
+    #   extractor.package_for("packs/billing/app/x.rb") # => "packs/billing"
+    #
+    class PackageExtractor
+      PACKAGE_FILE = 'package.yml'
+      PACKWERK_CONFIG = 'packwerk.yml'
+      ROOT_PACKAGE = '.'
+
+      # Packwerk's own defaults when packwerk.yml is absent or silent.
+      DEFAULT_PACKAGE_PATHS = ['**/'].freeze
+      DEFAULT_EXCLUDE = ['{bin,node_modules,script,tmp,vendor}/**/*'].freeze
+
+      def initialize
+        @rails_root = Pathname.new(Rails.root.to_s)
+        @packwerk = load_packwerk_config
+      end
+
+      # @return [Array<ExtractedUnit>] one unit per package
+      def extract_all
+        package_files.filter_map { |path| extract_package_file(path) }
+      end
+
+      # Extract one package.yml into a unit.
+      #
+      # @param file_path [String] absolute path to a package.yml
+      # @return [ExtractedUnit, nil] nil when the file is not a YAML mapping
+      def extract_package_file(file_path)
+        source = File.read(file_path)
+        data = YAML.safe_load(source, permitted_classes: [Symbol], aliases: true) || {}
+        raise ArgumentError, 'package.yml is not a mapping' unless data.is_a?(Hash)
+
+        name = package_name(file_path)
+        dependencies = Array(data['dependencies']).map(&:to_s).uniq.sort
+
+        unit = ExtractedUnit.new(type: :package, identifier: name, file_path: file_path)
+        unit.source_code = source
+        unit.metadata = {
+          name: name,
+          dependencies: dependencies,
+          enforce_dependencies: normalize_enforcement(data['enforce_dependencies']),
+          enforce_privacy: normalize_enforcement(data['enforce_privacy']),
+          layer: data['layer'],
+          public_path: data['public_path'] || 'app/public',
+          owner: data.dig('metadata', 'owner') || data['owner']
+        }
+        unit.dependencies = dependencies.map { |dep| { type: :package, target: dep, via: :package_dependency } }
+        unit
+      rescue StandardError => e
+        Rails.logger.error("Failed to extract package from #{file_path}: #{e.message}")
+        nil
+      end
+
+      # Package names, longest path first so a nested package wins over its
+      # parent, with the root package last. Memoized per instance: an
+      # instance lives for one extraction run.
+      #
+      # @return [Array<String>]
+      def package_roots
+        @package_roots ||= package_files.map { |path| package_name(path) }
+                                        .sort_by { |name| [name == ROOT_PACKAGE ? 1 : 0, -name.length, name] }
+      end
+
+      # The package a path belongs to.
+      #
+      # @param path [String, Pathname] absolute or Rails.root-relative
+      # @return [String, nil] nil outside Rails.root or when no package claims it
+      def package_for(path)
+        relative = relativize(path)
+        return nil if relative.nil?
+
+        package_roots.find { |root| root == ROOT_PACKAGE || relative.start_with?("#{root}/") }
+      end
+
+      private
+
+      # Every package.yml the packwerk configuration admits, sorted.
+      #
+      # @return [Array<String>] absolute paths
+      def package_files
+        @package_files ||= begin
+          patterns = Array(@packwerk['package_paths'] || DEFAULT_PACKAGE_PATHS)
+          excludes = Array(@packwerk['exclude'] || DEFAULT_EXCLUDE)
+          found = patterns.flat_map do |pattern|
+            Dir.glob(@rails_root.join(pattern.to_s, PACKAGE_FILE).to_s)
+          end
+          found.uniq.reject { |path| excluded?(relativize(path), excludes) }.sort
+        end
+      end
+
+      def excluded?(relative, excludes)
+        excludes.any? { |glob| File.fnmatch?(glob.to_s, relative, File::FNM_PATHNAME | File::FNM_EXTGLOB) }
+      end
+
+      # @return [Hash] parsed packwerk.yml, or {} when absent or unreadable
+      def load_packwerk_config
+        path = @rails_root.join(PACKWERK_CONFIG)
+        return {} unless path.file?
+
+        data = YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: true)
+        data.is_a?(Hash) ? data : {}
+      rescue StandardError => e
+        Rails.logger.warn("[Woods] Could not read #{PACKWERK_CONFIG}: #{e.message}")
+        {}
+      end
+
+      # @param file_path [String] absolute path to a package.yml
+      # @return [String] Packwerk package name
+      def package_name(file_path)
+        dir = File.dirname(relativize(file_path).to_s)
+        dir == '.' ? ROOT_PACKAGE : dir
+      end
+
+      # @return [String, nil] Rails.root-relative path, nil when outside the root
+      def relativize(path)
+        string = path.to_s
+        return string unless string.start_with?('/')
+
+        prefix = "#{@rails_root}/"
+        string.start_with?(prefix) ? string.delete_prefix(prefix) : nil
+      end
+
+      # Packwerk accepts true, false, and "strict"; keep the value shape.
+      def normalize_enforcement(value)
+        return false if value.nil? || value == false
+        return true if value == true
+
+        value.to_s
+      end
+    end
+  end
+end

data/lib/woods/extractors/phlex_extractor.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'component_discovery'
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
 require_relative 'route_helper_resolver'
@@ -22,6 +23,7 @@ module Woods
     #   card = units.find { |u| u.identifier == "Components::CardComponent" }
     #
     class PhlexExtractor
+      include ComponentDiscovery
       include SharedUtilityMethods
       include SharedDependencyScanner
       include RouteHelperResolver
@@ -45,13 +47,26 @@ module Woods
       #
       # @return [Array<ExtractedUnit>] List of component units
       def extract_all
-        return [] unless @component_base
-
-        @component_base.descendants.map do |component|
+        discoverable_classes.map do |component|
           extract_component(component)
         end.compact
       end
 
+      # The component classes this extractor would extract from the running
+      # app. Shared with the incremental path's class reconciliation (#164).
+      #
+      # The component directories are walked first: `descendants` only knows
+      # what something has already loaded, and a component under an autoloaded
+      # but not eager-loaded subtree of app/views is loaded by nothing (B-184).
+      #
+      # @return [Array<Class>]
+      def discoverable_classes
+        return [] unless @component_base
+
+        load_component_files
+        @component_base.descendants
+      end
+
       # Extract a single component
       #
       # @param component [Class] The component class