woods 2.0.0.beta2 → 2.0.0.beta4

data/lib/woods/extractors/route_extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../source_inputs/consumer_errors'
+
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
 
@@ -76,7 +78,7 @@ module Woods
 
         unit
       rescue StandardError => e
-        Rails.logger.error("Failed to extract route: #{e.message}")
+        SourceInputs::ConsumerErrors.log(self, "Failed to extract route: #{e.message}")
         nil
       end
 

data/lib/woods/extractors/route_helper_resolver.rb

@@ -23,41 +23,13 @@ module Woods
     #   end
     #
     module RouteHelperResolver
-      # Route helper prefixes that produce non-navigation dependencies.
-      # These generate asset URLs or are common false positives from
-      # non-route uses of _path/_url suffixes in Ruby code.
-      #
-      # NOTE: `root` is intentionally excluded — root_path is the most common
-      # Rails route helper, but it appears so frequently in non-navigation contexts
-      # (path construction, config, tests) that it generates excessive noise.
-      # The tradeoff: "what links to the home page?" won't appear in graph queries.
-      # Add new prefixes here when false positives are discovered in host apps.
-      IGNORED_HELPER_PREFIXES = %w[
-        asset
-        image
-        stylesheet
-        javascript
-        font
-        audio
-        video
-        turbo_stream
-        file
-        tmp
-        base
-        root
-        log
-        socket
-        download
-      ].freeze
-
       # Build the route helper lookup map from Rails named routes.
       # Call this once in your extractor's initialize method.
       #
       # Resilient to partial test doubles: any exception raised while
       # traversing Rails routes (unstubbed `application` on a double,
       # missing `named_routes`, etc.) is swallowed and leaves the map
-      # empty — extractors fall back to returning the helper name
-      # literal as the dependency target.
+      # empty — extractors omit unresolved navigation dependencies.
       def build_route_helper_map
         @route_helper_map = {}
         return unless defined?(Rails)
@@ -65,6 +37,11 @@ module Woods
         routes = safe_rails_application_routes
         return unless routes
 
+        # Rails lazy route sets do not load when named_routes is read. Use the
+        # runtime route collection reader before caching helpers, just as the
+        # route extractor does. Older route sets and partial doubles still work.
+        routes.routes if routes.respond_to?(:routes)
+
         routes.named_routes.each do |name, route|
           controller = route.defaults[:controller]
           action = route.defaults[:action]
@@ -78,8 +55,8 @@ module Woods
           }
         end
       rescue StandardError
-        # Leave @route_helper_map empty — navigation-edge extractors will
-        # fall back to the helper-name literal.
+        # Leave @route_helper_map empty — navigation-edge extractors omit
+        # helpers whose controller/action cannot be resolved.
         @route_helper_map = {}
       end
 
@@ -105,8 +82,8 @@ module Woods
       # @return [Hash, nil] { controller:, action:, path:, verb: } or nil if unresolvable
       def resolve_route_helper(helper_name)
         base = helper_name.sub(/_(path|url)\z/, '')
-        return nil if IGNORED_HELPER_PREFIXES.any? { |prefix| base.start_with?("#{prefix}_") || base == prefix }
-
+        # A real named route is authoritative even when its name resembles
+        # a filesystem or asset helper. Unresolved names still produce no edge.
         @route_helper_map&.[](base)
       end
 

data/lib/woods/extractors/scheduled_job_extractor.rb

@@ -1,6 +1,14 @@
 # frozen_string_literal: true
 
+require_relative '../source_inputs/consumer_errors'
+
 require 'yaml'
+begin
+  require 'active_support/configuration_file'
+rescue LoadError
+  # Rails 6.0 predates ConfigurationFile.
+  require 'erb'
+end
 
 module Woods
   module Extractors
@@ -38,9 +46,6 @@ module Woods
         '0 0 1 1 *' => 'yearly on January 1st'
       }.freeze
 
-      # Environment keys to unwrap when nested in YAML
-      ENVIRONMENT_KEYS = %w[production development test staging].freeze
-
       # A quoted Whenever command argument in either style. The body runs to
       # the *matching* delimiter, so the inner quotes of `command "echo 'hi'"`
       # stay part of the command.
@@ -79,8 +84,8 @@ module Woods
         else
           []
         end
-      rescue StandardError => e
-        Rails.logger.error("Failed to extract scheduled jobs from #{file_path}: #{e.message}")
+      rescue StandardError, SyntaxError, LoadError => e
+        SourceInputs::ConsumerErrors.log(self, "Failed to extract scheduled jobs from #{file_path}: #{e.message}")
         []
       end
 
@@ -97,12 +102,15 @@ module Woods
       # @return [Array<ExtractedUnit>]
       def extract_yaml_schedule(file_path, format)
         source = File.read(file_path)
-        # aliases: true — schedule files commonly share defaults via anchors
-        # (`<<: *defaults`); without it Psych 4+ raises AliasesNotEnabled and
-        # the whole file is silently dropped (#203). Alias expansion only
-        # re-references the scalar/hash types already permitted, so it adds
-        # no deserialization risk.
-        data = YAML.safe_load(source, permitted_classes: [Symbol], aliases: true)
+        data = if format == :solid_queue
+                 # Match Solid Queue's trusted Rails configuration loader: ERB
+                 # executes with its real filename (including require_relative).
+                 load_recurring_configuration(file_path, source)
+               else
+                 # Sidekiq remains safe-loaded; aliases allow shared defaults
+                 # without permitting additional deserialized classes (#203).
+                 YAML.safe_load(source, permitted_classes: [Symbol], aliases: true)
+               end
 
         return [] unless data.is_a?(Hash) && data.any?
 
@@ -116,10 +124,23 @@ module Woods
         end
       end
 
+      def load_recurring_configuration(file_path, source)
+        if defined?(ActiveSupport::ConfigurationFile)
+          ActiveSupport::ConfigurationFile.parse(file_path)
+        else
+          # Rails 6.0: preserve the same filename-aware ERB evaluation while
+          # retaining the existing scalar/hash YAML policy.
+          require 'erb'
+          erb = ERB.new(source)
+          erb.filename = file_path
+          YAML.safe_load(erb.result, permitted_classes: [Symbol], aliases: true)
+        end
+      end
+
       # Detect and unwrap environment-nested YAML.
       #
-      # If the top-level keys are environment names (production, development,
-      # etc.), unwrap to the section for the environment being extracted,
+      # If the top level contains maps of tasks, unwrap to the section for
+      # the environment being extracted (including custom environment names),
       # falling back to the first section when the current environment has no
       # entry. Taking `values.first` unconditionally meant a file listing
       # `development:` before `production:` indexed the development schedule
@@ -128,9 +149,14 @@ module Woods
       # @param data [Hash] Parsed YAML data
       # @return [Hash] Unwrapped entries
       def unwrap_environment_nesting(data)
-        return data unless data.keys.all? { |k| ENVIRONMENT_KEYS.include?(k.to_s) }
+        # Environment sections contain task maps; task entries contain scalar
+        # configuration values. Shape matters even for a task called production.
+        nested = data.values.all? do |section|
+          section.nil? || (section.is_a?(Hash) && section.values.all?(Hash))
+        end
+        return data unless nested
 
-        data[current_environment] || data.values.first || {}
+        data.key?(current_environment) ? (data[current_environment] || {}) : (data.values.first || {})
       end
 
       # The environment name the extraction is running under, as a String.

data/lib/woods/extractors/serializer_extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../source_inputs/consumer_errors'
+
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
 
@@ -106,7 +108,7 @@ module Woods
 
         unit
       rescue StandardError => e
-        Rails.logger.error("Failed to extract serializer #{file_path}: #{e.message}")
+        SourceInputs::ConsumerErrors.log(self, "Failed to extract serializer #{file_path}: #{e.message}")
         nil
       end
 
@@ -136,7 +138,7 @@ module Woods
 
         unit
       rescue StandardError => e
-        Rails.logger.error("Failed to extract serializer #{klass.name}: #{e.message}")
+        SourceInputs::ConsumerErrors.log(self, "Failed to extract serializer #{klass.name}: #{e.message}")
         nil
       end
 

data/lib/woods/extractors/service_extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../source_inputs/consumer_errors'
+
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
 require_relative 'source_nesting'
@@ -83,7 +85,7 @@ module Woods
 
         unit
       rescue StandardError => e
-        Rails.logger.error("Failed to extract service #{file_path}: #{e.message}")
+        SourceInputs::ConsumerErrors.log(self, "Failed to extract service #{file_path}: #{e.message}")
         nil
       end
 

data/lib/woods/extractors/shared_dependency_scanner.rb

@@ -204,8 +204,8 @@ module Woods
       # Match _path/_url route helpers anywhere in source.
       # This intentionally matches all usages (assignments, string interpolation, etc.)
       # not just link_to/redirect_to calls — any reference to a route helper indicates
-      # a dependency on that controller. False positives from non-route _path/_url
-      # suffixes (file_path, base_url, etc.) are filtered by RouteHelperResolver::IGNORED_HELPER_PREFIXES.
+      # a dependency on that controller. RouteHelperResolver accepts only names
+      # present in the live controller/action route map, excluding unknown helpers.
       # Requires the including class to also include RouteHelperResolver
       # and call build_route_helper_map in its initializer.
       ROUTE_HELPER_PATTERN = /\b(\w+)_(path|url)\b/

data/lib/woods/extractors/shared_utility_methods.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
+require_relative 'declared_parent'
+
 require_relative 'source_nesting'
+require_relative 'method_parameters'
 
 module Woods
   module Extractors
@@ -124,10 +127,10 @@ module Woods
       # Extract the parent class name from a class definition.
       #
       # @param source [String] Ruby source code
-      # @return [String, nil] Parent class name or nil
-      def extract_parent_class(source)
-        match = source.match(/^\s*class\s+[\w:]+\s*<\s*([\w:]+)/)
-        match ? match[1] : nil
+      # @param class_name [String] Already selected extraction identity
+      # @return [String, nil] Explicit parent of that declaration, or nil
+      def extract_parent_class(source, class_name)
+        DeclaredParent.call(source, class_name)
       end
 
       # Count non-blank, non-comment lines of code.
@@ -221,6 +224,44 @@ module Woods
         actions.to_a
       end
 
+      # Rails 6 exposes a numeric Proc identity through #filter, and the
+      # callable through #raw_filter. Newer Rails exposes the callable directly.
+      def callback_filter(callback)
+        stable_filter(callback.respond_to?(:raw_filter) ? callback.raw_filter : callback.filter)
+      end
+
+      # Proc#to_s embeds a process-local address. Model and controller filters
+      # share source-site labels, so metadata and derived chunks agree across
+      # boots. Preserve symbols and other application-defined callback values.
+      def stable_filter(filter)
+        return filter unless filter.is_a?(Proc)
+
+        location = filter.source_location
+        site = if location
+                 path, line = location
+                 "#{path.delete_prefix("#{Rails.root}/")}:#{line}"
+               else
+                 'native'
+               end
+        "#<#{filter.lambda? ? 'lambda' : 'Proc'} #{site}>"
+      end
+
+      # Preserve application labels; strip addresses only from Ruby's actual
+      # default representation. Nested identities occur for anonymous classes.
+      # These are descriptive labels, not serialization of callback object state.
+      def callback_filter_label(callback)
+        filter = callback_filter(callback)
+        label = filter.to_s
+        return label unless label.start_with?('#<')
+
+        owner = filter.is_a?(Module) ? Module : Kernel
+        return label unless label == owner.instance_method(:to_s).bind(filter).call
+
+        label.gsub(/:0x[0-9a-f]+(?=>)/i, '')
+      end
+
+      private :callback_filter, :stable_filter, :callback_filter_label
+
       # Human-readable label for a non-ActionFilter condition.
       #
       # @param condition [Object] A proc, symbol, or other condition
@@ -292,7 +333,7 @@ module Woods
         source.scan(/def\s+self\.(\w+[?!=]?)/).flatten
       end
 
-      # Extract initialize parameters from source code via regex.
+      # Extract initialize parameters from source syntax without evaluating defaults.
       #
       # Parses the parameter list of the initialize method to determine
       # parameter names, defaults, and whether they are keyword arguments.
@@ -304,21 +345,9 @@ module Woods
       # @param source [String] Ruby source code
       # @return [Array<Hash>] Parameter info hashes with :name, :has_default, :keyword
       def extract_initialize_params(source)
-        init_match = source.match(/def\s+initialize\s*\((.*?)\)/m)
-        return [] unless init_match
-
-        params_str = init_match[1]
-        params = []
-
-        params_str.scan(/(\w+)(?::\s*([^,\n]+))?/) do |name, default|
-          params << {
-            name: name,
-            has_default: !default.nil?,
-            keyword: params_str.include?("#{name}:")
-          }
+        MethodParameters.extract(source, :initialize).map do |parameter|
+          parameter.slice(:name, :has_default, :keyword)
         end
-
-        params
       end
     end
   end

data/lib/woods/extractors/source_nesting.rb

@@ -245,7 +245,7 @@ module Woods
       # The constant path the active main 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.4+;
+      # must win over the local camelizer). Available on Zeitwerk 2.6.9+;
       # nil — unmanaged — when the loader's API is older, declines the
       # file, or cannot derive a name. A decline is authoritative: the
       # local camelizer must not rescue it.

data/lib/woods/extractors/state_machine_extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../source_inputs/consumer_errors'
+
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
 require_relative 'source_nesting'
@@ -58,7 +60,7 @@ module Woods
         units.concat(extract_state_machines_units(source, class_name, file_path))
         units
       rescue StandardError => e
-        Rails.logger.error("Failed to extract state machines from #{file_path}: #{e.message}")
+        SourceInputs::ConsumerErrors.log(self, "Failed to extract state machines from #{file_path}: #{e.message}")
         []
       end
 

data/lib/woods/extractors/test_mapping_extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../source_inputs/consumer_errors'
+
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
 
@@ -70,7 +72,7 @@ module Woods
 
         unit
       rescue StandardError => e
-        Rails.logger.error("Failed to extract test mapping from #{file_path}: #{e.message}")
+        SourceInputs::ConsumerErrors.log(self, "Failed to extract test mapping from #{file_path}: #{e.message}")
         nil
       end
 

data/lib/woods/extractors/validator_extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../source_inputs/consumer_errors'
+
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
 
@@ -70,7 +72,7 @@ module Woods
 
         unit
       rescue StandardError => e
-        Rails.logger.error("Failed to extract validator #{file_path}: #{e.message}")
+        SourceInputs::ConsumerErrors.log(self, "Failed to extract validator #{file_path}: #{e.message}")
         nil
       end
 

data/lib/woods/extractors/view_component_extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../source_inputs/consumer_errors'
+
 require_relative 'component_discovery'
 require_relative 'shared_utility_methods'
 require_relative 'shared_dependency_scanner'
@@ -95,7 +97,7 @@ module Woods
 
         unit
       rescue StandardError => e
-        Rails.logger.error("Failed to extract view component #{component.name}: #{e.message}")
+        SourceInputs::ConsumerErrors.log(self, "Failed to extract view component #{component.name}: #{e.message}")
         nil
       end
 

data/lib/woods/extractors/view_template_extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../source_inputs/consumer_errors'
+
 require 'set'
 require_relative 'route_helper_resolver'
 require_relative 'view_engines/base'
@@ -95,7 +97,7 @@ module Woods
 
         unit
       rescue StandardError => e
-        Rails.logger.error("Failed to extract view template #{file_path}: #{e.message}")
+        SourceInputs::ConsumerErrors.log(self, "Failed to extract view template #{file_path}: #{e.message}")
         nil
       end
 

data/lib/woods/gem_mapper.rb

@@ -7,6 +7,7 @@ require 'pathname'
 require 'time'
 
 require_relative 'atomic_file'
+require_relative 'version'
 require_relative 'coordination/pipeline_lock'
 require_relative 'dependency_graph'
 require_relative 'extracted_unit'
@@ -267,6 +268,7 @@ module Woods
       end
       manifest = {
         extracted_at: Time.now.utc.iso8601, rails_version: nil, ruby_version: RUBY_VERSION,
+        woods_version: Woods::VERSION,
         counts: counts, total_units: @units.size, total_chunks: 0, git_sha: nil, git_branch: nil,
         provenance: GemMapper::PROVENANCE.merge(source_checksum: @checksum),
         graph_nodes: @graph.to_h.dig(:stats, :node_count), graph_edges: @graph.to_h.dig(:stats, :edge_count)

data/lib/woods/git_history.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'time'
+require_relative 'git_command'
+
+module Woods
+  # Stream HEAD-reachable touched-path events without pathspec simplification.
+  # Raw NUL records keep filenames separate from commit fields; only requested
+  # paths are retained. Merge diffs compare against the first parent, while
+  # traversal still visits every parent. Requires Git 2.31 or newer.
+  class GitHistory
+    class ReadError < StandardError; end
+
+    FORMAT = '%x00%H%x00%an%x00%cI%x00%s%x00'
+    private_constant :FORMAT
+
+    def initialize(root:, logger:)
+      @root = root
+      @logger = logger
+    end
+
+    # @return [Hash, nil] raw per-path aggregates, or nil on any incomplete read
+    def read(paths, recent_after:)
+      requested = paths.to_h { |path| [repository_prefix + path.b, path] }
+      result = paths.to_h { |path| [path, {}] }
+      stream { |stdout| parse(stdout, requested, result, recent_after) }
+      result
+    rescue StandardError => e
+      @logger.warn('[Woods] Git enrichment omitted: history could not be read completely. ' \
+                   'Git 2.31 or newer is required; check the application repository and git installation. ' \
+                   "(#{e.class})")
+      nil
+    end
+
+    private
+
+    def repository_prefix
+      return @repository_prefix if defined?(@repository_prefix)
+
+      prefix, _error, status = Open3.capture3(*GitCommand.argv(@root, 'rev-parse', '--show-prefix'))
+      raise ReadError, 'cannot resolve application path in repository' unless status.success?
+
+      @repository_prefix = prefix.delete_suffix("\n").b
+    end
+
+    def stream
+      argv = GitCommand.argv(@root, '-c', 'log.showSignature=false', 'log', 'HEAD',
+                             '--since=365 days ago', '--root', '--raw', '-z', '--no-renames',
+                             '--no-relative', '--no-ext-diff', '--encoding=UTF-8',
+                             '--diff-merges=first-parent', "--format=#{FORMAT}")
+      Open3.popen3(*argv) do |stdin, stdout, stderr, wait|
+        stdin.close
+        stdout.binmode
+        # Drain stderr without retaining a potentially unbounded diagnostic.
+        drain = Thread.new { stderr.read(16_384) until stderr.eof? }
+        begin
+          yield stdout
+          raise ReadError, "history command exited #{wait.value.exitstatus}" unless wait.value.success?
+        ensure
+          stdout.close
+          drain.join
+        end
+      end
+    end
+
+    def token(io)
+      value = io.gets("\0")
+      return nil unless value
+      raise ReadError, 'unterminated history record' unless value.end_with?("\0")
+
+      value.delete_suffix("\0")
+    end
+
+    def parse(io, requested, result, recent_after)
+      commit = nil
+      while (field = token(io))
+        next if field.empty?
+
+        if field.match?(/\A[0-9a-f]{40}(?:[0-9a-f]{24})?\z/)
+          commit = read_commit(io, field, recent_after)
+        elsif field.match?(/\A\n?:[0-7]{6} [0-7]{6} [0-9a-f]+ [0-9a-f]+ [A-Z]\z/)
+          record_path(io, requested, result, commit)
+        else
+          raise ReadError, 'unexpected history record'
+        end
+      end
+    end
+
+    def read_commit(io, sha, recent_after)
+      author, date, message = Array.new(3) { token(io) }
+      raise ReadError, 'incomplete commit header' unless author && date && message
+
+      { sha: sha, author: author.force_encoding(Encoding::UTF_8),
+        date: date, message: message.force_encoding(Encoding::UTF_8), recent: Time.iso8601(date) > recent_after }
+    end
+
+    def record_path(io, requested, result, commit)
+      path = token(io)
+      raise ReadError, 'incomplete path record' unless commit && path
+
+      relative = requested[path]
+      record(result[relative], commit) if relative
+    end
+
+    def record(data, commit)
+      data[:last_modified] ||= commit[:date]
+      data[:last_author] ||= commit[:author]
+      data[:commit_count] = data.fetch(:commit_count, 0) + 1
+      data[:recent_count] = data.fetch(:recent_count, 0) + (commit[:recent] ? 1 : 0)
+      commits = (data[:commits] ||= [])
+      commits << commit if commits.size < 5
+      (data[:contributors] ||= Hash.new(0))[commit[:author]] += 1
+    end
+  end
+end

data/lib/woods/graph_analyzer.rb

@@ -71,12 +71,14 @@ module Woods
 
     # @param dependency_graph [DependencyGraph] The graph to analyze
     # @param volatile_ratio [Numeric] see {#volatile_dependencies}
+    # @param volatile_limit_per_target [Integer, nil] maximum edges per typed dependency, before the global limit
     # @param cycle_limit [Integer, nil] see {DEFAULT_CYCLE_LIMIT}
     # @param cycle_max_length [Integer, nil] see {DEFAULT_CYCLE_MAX_LENGTH}
-    def initialize(dependency_graph, volatile_ratio: DEFAULT_VOLATILE_RATIO,
+    def initialize(dependency_graph, volatile_ratio: DEFAULT_VOLATILE_RATIO, volatile_limit_per_target: nil,
                    cycle_limit: DEFAULT_CYCLE_LIMIT, cycle_max_length: DEFAULT_CYCLE_MAX_LENGTH)
       @graph = dependency_graph
       @volatile_ratio = volatile_ratio.to_f
+      @volatile_limit_per_target = volatile_limit_per_target
       @cycle_limit = cycle_limit
       @cycle_max_length = cycle_max_length
       @cycle_limit_reached = false
@@ -296,15 +298,16 @@ module Woods
     # dependencies with fewer than {VOLATILE_MIN_COMMITS} commits or a
     # `new` change frequency are skipped. Ranked by the dependency's
     # PageRank so the most-depended-on volatile unit comes first. `limit`
-    # caps what this method hands back; {#analyze}'s
+    # caps what this method hands back after the optional per-target cap; {#analyze}'s
     # `stats[:volatile_dependency_count]` reports the full qualifying count
     # regardless of `limit`, and `stats[:volatile_dependencies_limit]` reports
-    # the cap, so a reader of the array alone can tell it was truncated.
+    # the global cap. An enabled per-target cap also publishes its setting
+    # and the final reported count; the full qualifying count is unchanged.
     #
     # @param limit [Integer] maximum entries
     # @return [Array<Hash>] `{ from:, from_type:, to:, to_type:, via:, from_commits:, to_commits:, ratio:, pagerank: }`
     def volatile_dependencies(limit: DEFAULT_VOLATILE_LIMIT)
-      all_volatile_dependencies.first(limit)
+      capped_volatile_dependencies.first(limit)
     end
 
     # Edges that cross a Packwerk package boundary the source package never
@@ -397,8 +400,7 @@ module Woods
           cycle_count: computed_cycles.size,
           cycle_limit_reached: cycle_limit_reached?,
           cross_database_edge_count: computed_cross_database.size,
-          volatile_dependency_count: all_volatile_dependencies.size,
-          volatile_dependencies_limit: DEFAULT_VOLATILE_LIMIT,
+          **volatile_dependency_stats(computed_volatile),
           undeclared_package_edge_count: computed_undeclared.size
         }
       }
@@ -722,6 +724,33 @@ module Woods
       @all_volatile_dependencies ||= compute_volatile_dependencies
     end
 
+    # Apply the optional hub cap after ranking, before the overall report
+    # limit. Keep individual relationship edges; two `via` values consume two
+    # slots. Type is part of dependency identity, never just the display name.
+    def capped_volatile_dependencies
+      return all_volatile_dependencies unless @volatile_limit_per_target
+
+      counts = Hash.new(0)
+      all_volatile_dependencies.select do |entry|
+        target = [entry[:to_type], entry[:to]]
+        counts[target] += 1
+        counts[target] <= @volatile_limit_per_target
+      end
+    end
+
+    # Preserve the default artifact exactly; expose extra selection metadata
+    # only when the per-target cap was requested. The full count always means
+    # all ratio-qualified edges, before either cap.
+    def volatile_dependency_stats(reported)
+      stats = { volatile_dependency_count: all_volatile_dependencies.size,
+                volatile_dependencies_limit: DEFAULT_VOLATILE_LIMIT }
+      if @volatile_limit_per_target
+        stats[:volatile_dependencies_limit_per_target] = @volatile_limit_per_target
+        stats[:volatile_dependency_reported_count] = reported.size
+      end
+      stats
+    end
+
     # Short-circuits to `[]`, skipping the PageRank computation entirely,
     # when no node carries an Integer `commit_count` (git enrichment never
     # ran): there is nothing to rank.