woods 1.6.1 → 2.0.0.beta2

data/lib/woods/graph_analyzer.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'digest'
 require 'set'
 
 module Woods
@@ -23,12 +24,62 @@ module Woods
   class GraphAnalyzer
     # Types that are naturally root nodes and should not be flagged as orphans.
     # Framework and gem sources are consumed but never referenced by application code
-    # in the dependency graph's reverse index.
-    EXCLUDED_ORPHAN_TYPES = %i[rails_source gem_source].freeze
+    # in the dependency graph's reverse index. Package units (#280) declare
+    # boundaries via metadata and `:package_dependency` edges to other
+    # packages; nothing points back at a leaf package in the reverse index,
+    # so it would otherwise be flagged as dead code it is not.
+    EXCLUDED_ORPHAN_TYPES = %i[rails_source gem_source package].freeze
+
+    # How many rounds {#assign_orphaned_units} runs before it stops pulling
+    # unnamespaced units into clusters through other unnamespaced units. The
+    # loop already stops early on the first round that assigns nothing; this
+    # bounds the pathological case (a long chain of unnamespaced units, where
+    # each round advances the frontier by one) so clustering stays linear-ish
+    # on large graphs.
+    ORPHAN_ASSIGNMENT_ROUNDS = 10
+
+    # Edge labels that come from an Active Record association reflection.
+    # Only these can cross a database boundary through Rails itself.
+    ASSOCIATION_VIAS = %w[belongs_to has_many has_one has_and_belongs_to_many].freeze
+
+    # A dependency must change at least this many times more often than
+    # its dependent to be reported by {#volatile_dependencies}.
+    DEFAULT_VOLATILE_RATIO = 3.0
+
+    # A dependency with fewer commits in the last year than this is too
+    # young to judge; POODR's rule is about things that keep changing, and
+    # a class touched four times could be settling down.
+    VOLATILE_MIN_COMMITS = 5
+
+    # How many volatile-dependency entries {#analyze} keeps. Published as
+    # `stats[:volatile_dependencies_limit]` so a reader of the array alone
+    # can tell whether it was truncated (B-182).
+    DEFAULT_VOLATILE_LIMIT = 20
+
+    # How many distinct cycles {#detect_cycles} enumerates before it stops.
+    # The DFS finds one cycle per back-edge, and a dense graph has tens of
+    # thousands of them; nobody reads past the first few hundred, and the
+    # per-cycle signature work is what made analysis the fixed floor of every
+    # incremental run. `nil` means no cap.
+    DEFAULT_CYCLE_LIMIT = 500
+
+    # The longest cycle {#detect_cycles} will record, counted in distinct
+    # nodes. A back-edge deep in a DFS closes a cycle as long as the path,
+    # which on a large graph is thousands of nodes: unreadable as a report and
+    # expensive to canonicalize. `nil` means no cap.
+    DEFAULT_CYCLE_MAX_LENGTH = 50
 
     # @param dependency_graph [DependencyGraph] The graph to analyze
-    def initialize(dependency_graph)
+    # @param volatile_ratio [Numeric] see {#volatile_dependencies}
+    # @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,
+                   cycle_limit: DEFAULT_CYCLE_LIMIT, cycle_max_length: DEFAULT_CYCLE_MAX_LENGTH)
       @graph = dependency_graph
+      @volatile_ratio = volatile_ratio.to_f
+      @cycle_limit = cycle_limit
+      @cycle_max_length = cycle_max_length
+      @cycle_limit_reached = false
     end
 
     # ══════════════════════════════════════════════════════════════════════
@@ -49,7 +100,7 @@ module Woods
 
           dependents = @graph.dependents_of(identifier)
           result << identifier if dependents.empty?
-        end
+        end.sort
       end
     end
 
@@ -65,7 +116,7 @@ module Woods
         nodes.each_with_object([]) do |(identifier, _meta), result|
           dependencies = @graph.dependencies_of(identifier)
           result << identifier if dependencies.empty?
-        end
+        end.sort
       end
     end
 
@@ -86,10 +137,21 @@ module Woods
           identifier: identifier,
           type: meta[:type],
           dependent_count: dependents.size,
-          dependents: dependents
+          # Sorted for the same reason the outer list tie-breaks on identifier:
+          # `dependents_of` returns graph-registration order, so an incremental
+          # run that appended a dependent would publish a different hub entry
+          # for an identical graph.
+          dependents: dependents.sort
         }
       end
-      identifiers_with_dependents.max_by(limit) { |h| h[:dependent_count] }
+      # Tie-break on identifier. Without it, which of the (often many) nodes
+      # sharing a dependent count land inside the top-N depends on graph
+      # insertion order, so two extractions of the same tree could publish
+      # different hub lists (#164) — incremental runs append new nodes at the
+      # end where a full extraction interleaves them by extractor.
+      identifiers_with_dependents
+        .sort_by { |h| [-h[:dependent_count], h[:identifier].to_s] }
+        .first(limit)
     end
 
     # Detect circular dependency chains in the graph.
@@ -105,6 +167,19 @@ module Woods
       @cycles ||= detect_cycles
     end
 
+    # Whether {#cycles} is a truncated view of the graph's cycles.
+    #
+    # True when either cap fired: the count cap stopped enumeration, or at
+    # least one cycle was longer than the length cap and was skipped. A reader
+    # of the array alone cannot tell, so this is published as
+    # `stats[:cycle_limit_reached]` alongside it.
+    #
+    # @return [Boolean]
+    def cycle_limit_reached?
+      cycles
+      @cycle_limit_reached
+    end
+
     # Units that bridge different types in the graph.
     #
     # Computes a simplified betweenness centrality metric — for each unit, we
@@ -123,7 +198,11 @@ module Woods
       nodes = graph_nodes
       return [] if nodes.size < 3
 
-      node_ids = nodes.keys
+      # Sorted, not insertion-ordered: the seeded sample indexes into this
+      # list, so leaving it in graph order would make the sampled pairs (and
+      # therefore the bridge scores) depend on the order units happened to be
+      # registered in rather than on the graph's content (#164).
+      node_ids = nodes.keys.sort
       scores = Hash.new(0)
 
       # Sample random pairs of nodes for shortest-path computation.
@@ -133,6 +212,7 @@ module Woods
 
       pairs.each do |source, target|
         path = bfs_shortest_path(source, target)
+
         next unless path && path.size > 2
 
         # Credit intermediate nodes (exclude source and target)
@@ -154,6 +234,93 @@ module Woods
         end
     end
 
+    # Association and foreign-key edges whose two ends resolve to different
+    # databases (#280).
+    #
+    # Reads only node attributes (`database`, `table`, `foreign_key_tables`)
+    # and edge attributes (`through`, `through_db`, `disable_joins`), so an
+    # incremental run that loaded the graph from disk computes exactly what
+    # a full run does.
+    #
+    # Scoped to primary nodes: identifiers as registered in {#graph_nodes}.
+    # A variant, the non-primary type registered under an identifier that
+    # collides across types, is not walked separately. Association edges are
+    # read with `type: :model`, so a variant sharing the identifier under a
+    # different type cannot contribute a crossing that belongs to it alone.
+    #
+    # A foreign key never picks a target owner that lives in `from_db`, even
+    # when another database also owns the table: an owner in the source
+    # database means the key resolves locally, whatever else claims the same
+    # table name. Only when every owner sits outside `from_db`, in more than
+    # one other database, does the entry come back ambiguous.
+    #
+    # `kind`:
+    # * `join_through_across_databases`: a `has_many :through` where
+    #   `disable_joins` is false and `from_db`, `through_db`, and `to_db` are
+    #   not all equal (a nil `through_db` falls back to comparing the two
+    #   ends). Rails will try to JOIN across connections; this is the
+    #   Uchitelle rule.
+    # * `association_across_databases`: any other association edge across
+    #   databases, including a through with `disable_joins`.
+    # * `foreign_key_across_databases`: a database-level foreign key whose
+    #   target table's owner (or every owner, when ambiguous) lives in
+    #   another database.
+    #
+    # @return [Array<Hash>] sorted by from, to, via
+    def cross_database_edges
+      @cross_database_edges ||= begin
+        nodes = graph_nodes
+        owners = table_owners(nodes)
+        entries = nodes.keys.sort.flat_map do |identifier|
+          meta = nodes[identifier]
+          from_db = meta[:database]
+          next [] unless from_db
+
+          association_crossings(identifier, from_db, nodes) +
+            foreign_key_crossings(identifier, from_db, meta, owners)
+        end
+        # Whole-hash dedup, not a `[from, to, via]` key: an ambiguous foreign
+        # key entry carries `to: nil` regardless of which table it names, so
+        # two distinct ambiguous foreign keys on the same model would
+        # otherwise collapse into one.
+        entries.uniq.sort_by { |e| [e[:from], e[:to], e[:via]] }
+      end
+    end
+
+    # Edges that point at something changing much faster than the thing
+    # that depends on it: "depend on things that change less often than
+    # you do" (POODR ch. 3), made checkable because the graph now carries
+    # commit counts (#280).
+    #
+    # Report only, never a gate: young classes produce false positives, so
+    # 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
+    # `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.
+    #
+    # @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)
+    end
+
+    # Edges that cross a Packwerk package boundary the source package never
+    # declared (#280).
+    #
+    # Membership comes from the `package` node attribute (Task 8); a
+    # declaration comes from a package unit's own `:package_dependency`
+    # edges (Task 7). Both are graph-only, so a full and an incremental run
+    # compute the same report. Enforcement stays with `packwerk check` /
+    # `pks check`; this only makes the undeclared boundary visible.
+    #
+    # @return [Array<Hash>] `{ from:, from_type:, to:, to_type:, via:, from_package:, to_package: }`, sorted
+    def undeclared_package_edges
+      @undeclared_package_edges ||= compute_undeclared_package_edges
+    end
+
     # Group units into semantic domains using namespace prefixes and graph connectivity.
     #
     # Strategy:
@@ -191,13 +358,13 @@ module Woods
       merge_small_clusters(clusters, min_size)
 
       # Step 4: Enrich each cluster with hub, entry points, boundary edges
-      pagerank_scores = @graph.pagerank
+      pagerank_scores = self.pagerank_scores
       enrich_clusters(clusters, nodes, pagerank_scores)
 
       # Sort by member count descending
       clusters.values
               .select { |c| c[:members].any? }
-              .sort_by { |c| -c[:member_count] }
+              .sort_by { |c| [-c[:member_count], c[:name].to_s] }
     end
 
     # Full analysis report combining all structural metrics.
@@ -210,6 +377,9 @@ module Woods
       computed_hubs = hubs
       computed_cycles = cycles
       computed_bridges = bridges(limit: 10)
+      computed_cross_database = cross_database_edges
+      computed_volatile = volatile_dependencies
+      computed_undeclared = undeclared_package_edges
 
       {
         orphans: computed_orphans,
@@ -217,11 +387,19 @@ module Woods
         hubs: computed_hubs,
         cycles: computed_cycles,
         bridges: computed_bridges,
+        cross_database_edges: computed_cross_database,
+        volatile_dependencies: computed_volatile,
+        undeclared_package_edges: computed_undeclared,
         stats: {
           orphan_count: computed_orphans.size,
           dead_end_count: computed_dead_ends.size,
           hub_count: computed_hubs.size,
-          cycle_count: computed_cycles.size
+          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,
+          undeclared_package_edge_count: computed_undeclared.size
         }
       }
     end
@@ -258,41 +436,72 @@ module Woods
     end
 
     # Assign units with no namespace prefix to their most-connected cluster.
+    #
+    # Order-free (EXTB-7). Each round scores *every* still-unassigned unit
+    # against one membership snapshot taken before the round, then applies all
+    # of that round's assignments at once. Assigning inside the scoring loop —
+    # as this did — let a unit whose only connection is another unnamespaced
+    # unit join a cluster or not depending on which of the two the graph
+    # happened to enumerate first, i.e. on registration order, which differs
+    # between a full and an incremental run.
+    #
+    # Rounds are bounded: each one either assigns at least one unit or ends the
+    # loop, and {ORPHAN_ASSIGNMENT_ROUNDS} caps how far a chain of unnamespaced
+    # units can pull its successors in. Units past that depth stay unassigned —
+    # deterministically, which is the property that matters here.
     def assign_orphaned_units(clusters, filtered_ids, _nodes)
       return if clusters.empty?
 
-      unassigned = filtered_ids.select { |id| cluster_prefix(id).nil? }
+      pending = filtered_ids.select { |id| cluster_prefix(id).nil? }.sort
+
+      ORPHAN_ASSIGNMENT_ROUNDS.times do
+        break if pending.empty?
 
-      unassigned.each do |id|
-        best_cluster = find_most_connected_cluster(id, clusters)
-        next unless best_cluster
+        membership = clusters.transform_values { |cluster| cluster[:member_set] }.freeze
+        assignments = pending.filter_map do |id|
+          best_cluster = find_most_connected_cluster(id, clusters.keys, membership)
+          [id, best_cluster] if best_cluster
+        end
+        break if assignments.empty?
 
-        clusters[best_cluster][:members] << id
-        clusters[best_cluster][:member_set].add(id)
+        assignments.each do |id, name|
+          clusters[name][:members] << id
+          clusters[name][:member_set].add(id)
+        end
+        pending -= assignments.map(&:first)
       end
     end
 
     # Find which cluster a unit has the most connections to.
-    def find_most_connected_cluster(identifier, clusters)
+    #
+    # @param identifier [String]
+    # @param cluster_names [Array<String>]
+    # @param membership [Hash{String => Set<String>}] name => members, read as
+    #   of the start of the assignment round (see {#assign_orphaned_units})
+    # @return [String, nil]
+    def find_most_connected_cluster(identifier, cluster_names, membership)
       connections = Hash.new(0)
 
       # Check forward edges (dependencies)
       @graph.dependencies_of(identifier).each do |dep|
-        clusters.each do |name, cluster|
-          connections[name] += 1 if cluster[:member_set].include?(dep)
+        cluster_names.each do |name|
+          connections[name] += 1 if membership[name].include?(dep)
         end
       end
 
       # Check reverse edges (dependents)
       @graph.dependents_of(identifier).each do |dep|
-        clusters.each do |name, cluster|
-          connections[name] += 1 if cluster[:member_set].include?(dep)
+        cluster_names.each do |name|
+          connections[name] += 1 if membership[name].include?(dep)
         end
       end
 
       return nil if connections.empty?
 
-      connections.max_by { |_, count| count }.first
+      # Tie-break on cluster name. `max_by` alone returns whichever equal-count
+      # cluster the hash happened to enumerate first, which is registration
+      # order — the one determinism hole left in this class.
+      connections.max_by { |name, count| [count, name] }.first
     end
 
     # Merge clusters smaller than min_size into their most-connected neighbor.
@@ -302,7 +511,7 @@ module Woods
         break if small.empty?
 
         # Merge the smallest cluster first
-        name, cluster = small.min_by { |_, c| c[:members].size }
+        name, cluster = small.min_by { |cluster_name, c| [c[:members].size, cluster_name] }
 
         # Find which other cluster this one connects to most
         target = find_merge_target(cluster, clusters, name)
@@ -331,17 +540,26 @@ module Woods
 
       return nil if connections.empty?
 
-      connections.max_by { |_, count| count }.first
+      # Tie-break on cluster name. `max_by` alone returns whichever equal-count
+      # cluster the hash happened to enumerate first, which is registration
+      # order — the one determinism hole left in this class.
+      connections.max_by { |name, count| [count, name] }.first
     end
 
     # Enrich clusters with hub, entry points, boundary edges, and type breakdown.
     def enrich_clusters(clusters, nodes, pagerank_scores)
       clusters.each_value do |cluster|
-        members = cluster[:members]
+        # Sorted, like orphans/dead_ends/hubs. Members accumulate in graph
+        # registration order, and an incremental run appends where a full
+        # extraction interleaves by extractor — so an unsorted list publishes
+        # a different cluster for an identical graph. Everything derived below
+        # (entry points, boundary edges) inherits this order too.
+        members = cluster[:members].sort
+        cluster[:members] = members
         member_set = cluster[:member_set]
 
         # Hub: highest PageRank within the cluster
-        hub_id = members.max_by { |id| pagerank_scores[id] || 0 }
+        hub_id = members.max_by { |id| [pagerank_scores[id] || 0, id] }
         cluster[:hub] = hub_id
 
         # Entry points: controllers and GraphQL resolvers in the cluster's dependents
@@ -353,7 +571,7 @@ module Woods
             entry_points.add(dep) if meta && entry_types.include?(meta[:type].to_s)
           end
         end
-        cluster[:entry_points] = entry_points.to_a
+        cluster[:entry_points] = entry_points.to_a.sort
 
         # Boundary edges: connections that cross cluster boundaries
         boundary = []
@@ -377,7 +595,8 @@ module Woods
           end
         end
         # Deduplicate and limit boundary edges
-        cluster[:boundary_edges] = boundary.uniq { |e| [e[:from], e[:to]] }.first(20)
+        cluster[:boundary_edges] = boundary.uniq { |e| [e[:from], e[:to]] }
+                                           .sort_by { |e| [e[:from].to_s, e[:to].to_s] }.first(20)
 
         # Type breakdown
         type_counts = members.each_with_object(Hash.new(0)) do |id, counts|
@@ -410,11 +629,196 @@ module Woods
       @graph_nodes ||= graph_data[:nodes]
     end
 
-    # Access graph forward edges from cached graph data.
+    # ──────────────────────────────────────────────────────────────────────
+    # Cross-database helpers
+    # ──────────────────────────────────────────────────────────────────────
+
+    # table name => { database name => sorted identifiers of the model nodes
+    # in that database owning it }. Sorted identifier iteration makes a
+    # table owned by several nodes in one database resolve to the same
+    # first identifier every run; nodes with no table or no database
+    # contribute no ownership claim.
+    #
+    # @param nodes [Hash]
+    # @return [Hash{String => Hash{String => Array<String>}}]
+    def table_owners(nodes)
+      nodes.keys.sort.each_with_object({}) do |identifier, owners|
+        node = nodes[identifier]
+        table = node[:table]
+        database = node[:database]
+        next unless table && database
+
+        by_database = (owners[table] ||= {})
+        (by_database[database] ||= []) << identifier
+      end
+    end
+
+    # @return [Array<Hash>] association edges from `identifier` that land in another database
+    def association_crossings(identifier, from_db, nodes)
+      @graph.edge_records(identifier, type: :model).filter_map do |edge|
+        via = edge[:via].to_s
+        next unless ASSOCIATION_VIAS.include?(via)
+
+        target = nodes[edge[:target]]
+        to_db = target && target[:database]
+        through_db = edge[:through] ? edge[:through_db] : nil
+        databases = [from_db, to_db, through_db].compact.uniq
+        next if databases.size < 2
+
+        disable_joins = edge[:disable_joins] == true
+        kind = edge[:through] && !disable_joins ? 'join_through_across_databases' : 'association_across_databases'
+        {
+          from: identifier, to: edge[:target], via: via, from_db: from_db, to_db: to_db,
+          through: edge[:through], through_db: through_db, disable_joins: disable_joins, kind: kind
+        }
+      end
+    end
+
+    # @return [Array<Hash>] foreign keys from `identifier`'s table into a table owned by another database
+    def foreign_key_crossings(identifier, from_db, meta, owners)
+      Array(meta[:foreign_key_tables]).filter_map do |table|
+        foreign_key_crossing(identifier, from_db, table, owners)
+      end
+    end
+
+    # A single foreign key's crossing entry, or nil when an owner of `table`
+    # lives in `from_db` (the key resolves locally regardless of what else
+    # claims the table name) or when no node claims the table at all.
+    #
+    # @return [Hash, nil]
+    def foreign_key_crossing(identifier, from_db, table, owners)
+      by_database = owners[table]
+      return nil if by_database.nil? || by_database.key?(from_db)
+
+      base = {
+        from: identifier, via: 'foreign_key', from_db: from_db,
+        through: nil, through_db: nil, disable_joins: false, kind: 'foreign_key_across_databases'
+      }
+      databases = by_database.keys.sort
+      if databases.size == 1
+        owner_db = databases.first
+        base.merge(to: by_database[owner_db].first, to_db: owner_db)
+      else
+        base.merge(to: nil, to_db: nil, ambiguous_owners: by_database.values.flatten.sort)
+      end
+    end
+
+    # ──────────────────────────────────────────────────────────────────────
+    # Volatile dependency helpers
+    # ──────────────────────────────────────────────────────────────────────
+
+    # PageRank computed once per analyzer instance.
+    #
+    # @return [Hash{String => Float}]
+    def pagerank_scores
+      @pagerank_scores ||= @graph.pagerank
+    end
+
+    # Every qualifying edge, unranked by {#volatile_dependencies}'s `limit`.
+    # {#analyze} needs the full count separately from the persisted top 20.
     #
-    # @return [Hash] identifier => [dependency identifiers]
-    def graph_edges
-      @graph_edges ||= graph_data[:edges]
+    # @return [Array<Hash>] sorted by pagerank, ratio, from, to, via
+    def all_volatile_dependencies
+      @all_volatile_dependencies ||= compute_volatile_dependencies
+    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.
+    #
+    # @return [Array<Hash>]
+    def compute_volatile_dependencies
+      nodes = graph_nodes
+      return [] unless nodes.each_value.any? { |meta| meta[:commit_count].is_a?(Integer) }
+
+      scores = pagerank_scores
+      entries = nodes.keys.sort.flat_map do |from|
+        from_meta = nodes[from]
+        from_commits = from_meta[:commit_count]
+        next [] unless from_commits.is_a?(Integer)
+
+        @graph.edge_records(from, type: from_meta[:type]).filter_map do |edge|
+          volatile_entry(from, from_meta, from_commits, edge, nodes, scores)
+        end
+      end
+      entries.uniq { |e| [e[:from], e[:to], e[:via]] }
+             .sort_by { |e| [-e[:pagerank], -e[:ratio], e[:from], e[:to], e[:via]] }
+    end
+
+    # @return [Hash, nil] the report entry for one edge, or nil when it is not volatile
+    def volatile_entry(from, from_meta, from_commits, edge, nodes, scores)
+      to = edge[:target]
+      to_meta = nodes[to]
+      return nil unless to_meta
+
+      to_commits = to_meta[:commit_count]
+      return nil unless to_commits.is_a?(Integer) && to_commits >= VOLATILE_MIN_COMMITS
+      return nil if to_meta[:change_frequency] == 'new'
+
+      ratio = to_commits.to_f / [from_commits, 1].max
+      return nil if ratio < @volatile_ratio
+
+      {
+        from: from, from_type: from_meta[:type], to: to, to_type: to_meta[:type], via: edge[:via].to_s,
+        from_commits: from_commits, to_commits: to_commits,
+        ratio: ratio.round(2), pagerank: (scores[to] || 0.0).round(4)
+      }
+    end
+
+    # ──────────────────────────────────────────────────────────────────────
+    # Package boundary helpers
+    # ──────────────────────────────────────────────────────────────────────
+
+    # Short-circuits to `[]`, skipping declaration lookup entirely, when no
+    # node carries a `package` attribute (no package extraction ran).
+    #
+    # @return [Array<Hash>]
+    def compute_undeclared_package_edges
+      nodes = graph_nodes
+      return [] unless nodes.each_value.any? { |meta| meta.key?(:package) }
+
+      declared = package_declarations(nodes)
+      entries = nodes.keys.sort.flat_map do |from|
+        meta = nodes[from]
+        from_package = meta[:package]
+        next [] if from_package.nil? || meta[:type] == :package
+
+        @graph.edge_records(from, type: meta[:type]).filter_map do |edge|
+          undeclared_entry(from, meta, from_package, edge, nodes, declared)
+        end
+      end
+      entries.uniq.sort_by { |e| [e[:from], e[:to], e[:via]] }
+    end
+
+    # package identifier => Set of package identifiers it declares as
+    # dependencies, read from that package unit's own `:package_dependency`
+    # edges. A root package (`.`) declaring nothing is just another entry
+    # with an empty Set, no special-cased root handling.
+    #
+    # @param nodes [Hash]
+    # @return [Hash{String => Set<String>}]
+    def package_declarations(nodes)
+      nodes.each_with_object({}) do |(identifier, meta), declared|
+        next unless meta[:type] == :package
+
+        declared[identifier] = @graph.dependencies_of(identifier, via: :package_dependency).to_set
+      end
+    end
+
+    # @return [Hash, nil] the report entry, or nil when the edge stays inside declared boundaries
+    def undeclared_entry(from, from_meta, from_package, edge, nodes, declared)
+      to = edge[:target]
+      to_meta = nodes[to]
+      to_package = to_meta && to_meta[:package]
+      return nil if to_package.nil? || to_package == from_package
+
+      declared_deps = declared[from_package] || Set.new
+      return nil if declared_deps.include?(to_package)
+
+      {
+        from: from, from_type: from_meta[:type], to: to, to_type: to_meta[:type], via: edge[:via].to_s,
+        from_package: from_package, to_package: to_package
+      }
     end
 
     # ──────────────────────────────────────────────────────────────────────
@@ -433,6 +837,7 @@ module Woods
     # @return [Array<Array<String>>] Detected cycles
     def detect_cycles
       nodes = graph_nodes
+      @cycle_limit_reached = false
       return [] if nodes.empty?
 
       white = 0
@@ -444,67 +849,103 @@ module Woods
       found_cycles = []
       seen_cycle_signatures = Set.new
 
-      nodes.each_key do |start_node|
-        next unless color[start_node] == white
+      catch(:cycle_limit) do
+        nodes.keys.sort.each do |start_node|
+          next unless color[start_node] == white
 
-        # Iterative DFS using an explicit stack.
-        # Each entry is [node, :enter] or [node, :exit].
-        stack = [[start_node, :enter]]
+          # Iterative DFS using an explicit stack.
+          # Each entry is [node, :enter] or [node, :exit].
+          stack = [[start_node, :enter]]
 
-        # Track the current DFS path for cycle extraction.
-        path = []
+          # Track the current DFS path for cycle extraction.
+          path = []
 
-        while stack.any?
-          node, action = stack.pop
+          while stack.any?
+            node, action = stack.pop
 
-          if action == :exit
-            color[node] = black
-            path.pop
-            next
-          end
+            if action == :exit
+              color[node] = black
+              path.pop
+              next
+            end
 
-          # :enter action
-          next unless color[node] == white
-
-          color[node] = gray
-          path.push(node)
-          stack.push([node, :exit])
-
-          neighbors = @graph.dependencies_of(node)
-          neighbors.each do |neighbor|
-            case color[neighbor]
-            when white
-              parent[neighbor] = node
-              stack.push([neighbor, :enter])
-            when gray
-              # Found a cycle — extract it from the path
-              cycle = extract_cycle_from_path(path, neighbor)
-              if cycle
-                sig = normalize_cycle_signature(cycle)
-                unless seen_cycle_signatures.include?(sig)
-                  seen_cycle_signatures.add(sig)
-                  found_cycles << cycle
-                end
+            # :enter action
+            next unless color[node] == white
+
+            color[node] = gray
+            path.push(node)
+            stack.push([node, :exit])
+
+            # Not sorted, deliberately: this list is the unit's own declared
+            # dependency order, which is identical in a full and an incremental
+            # run, so sorting it would change nothing any test can observe.
+            neighbors = @graph.dependencies_of(node)
+            neighbors.each do |neighbor|
+              case color[neighbor]
+              when white
+                parent[neighbor] = node
+                stack.push([neighbor, :enter])
+              when gray
+                # Found a cycle: extract it from the path
+                collect_cycle(path, neighbor, found_cycles, seen_cycle_signatures)
               end
+              # black nodes are fully explored, skip them
             end
-            # black nodes are fully explored, skip them
           end
         end
       end
 
+      # Deterministic without a final sort: the DFS starts from a sorted
+      # node list, so cycles are discovered in the same order every run.
       found_cycles
     end
 
+    # Record the cycle closed by a back-edge to +cycle_start+.
+    #
+    # Skips a cycle longer than the length cap and one already recorded under
+    # another rotation. Throws +:cycle_limit+ once the count cap is full,
+    # which ends the whole scan in {#detect_cycles}.
+    #
+    # @param path [Array<String>] Current DFS path
+    # @param cycle_start [String] The node that closes the cycle
+    # @param found_cycles [Array<Array<String>>] Accumulator
+    # @param seen [Set<String>] Signatures already recorded
+    # @return [void]
+    def collect_cycle(path, cycle_start, found_cycles, seen)
+      cycle = extract_cycle_from_path(path, cycle_start, max_length: @cycle_max_length)
+      if cycle == :too_long
+        @cycle_limit_reached = true
+        return
+      end
+      return unless cycle
+
+      signature = normalize_cycle_signature(cycle)
+      return if seen.include?(signature)
+
+      seen.add(signature)
+      found_cycles << cycle
+      return unless @cycle_limit && found_cycles.size >= @cycle_limit
+
+      @cycle_limit_reached = true
+      throw :cycle_limit
+    end
+
     # Extracts a cycle from the current DFS path when a back-edge to
     # +cycle_start+ is found.
     #
+    # The length check runs on indexes, before the slice: an over-long cycle
+    # costs nothing beyond the +index+ lookup that found it.
+    #
     # @param path [Array<String>] Current DFS path
     # @param cycle_start [String] The node that closes the cycle
-    # @return [Array<String>, nil] The cycle path ending with cycle_start repeated,
-    #   or nil if cycle_start is not in the path
-    def extract_cycle_from_path(path, cycle_start)
+    # @param max_length [Integer, nil] Longest cycle to build, in distinct nodes
+    # @return [Array<String>, Symbol, nil] The cycle path ending with cycle_start
+    #   repeated; +:too_long+ when it exceeds +max_length+; nil when cycle_start
+    #   is not in the path
+    def extract_cycle_from_path(path, cycle_start, max_length: nil)
       start_index = path.index(cycle_start)
       return nil unless start_index
+      return :too_long if max_length && (path.size - start_index) > max_length
 
       path[start_index..] + [cycle_start]
     end
@@ -512,17 +953,20 @@ module Woods
     # Normalize a cycle so that duplicate rotations are treated as the same cycle.
     # For example, [A, B, C, A] and [B, C, A, B] are the same cycle.
     #
+    # Keyed by digest rather than by the joined path: the set holds one
+    # 64-byte key per cycle instead of a string as long as the cycle, so
+    # membership stays constant-cost however deep the DFS went.
+    #
     # @param cycle [Array<String>] Cycle path with repeated last element
-    # @return [String] Canonical string representation
+    # @return [String] Canonical hex digest of the rotated loop
     def normalize_cycle_signature(cycle)
       # Remove the trailing repeated element to get the raw loop
       loop_nodes = cycle[0..-2]
-      return loop_nodes.join('->') if loop_nodes.empty?
+      return Digest::SHA256.hexdigest('') if loop_nodes.empty?
 
       # Rotate so the lexicographically smallest element is first
       min_index = loop_nodes.each_with_index.min_by { |node, _i| node }.last
-      rotated = loop_nodes.rotate(min_index)
-      rotated.join('->')
+      Digest::SHA256.hexdigest(loop_nodes.rotate(min_index).join('->'))
     end
 
     # ──────────────────────────────────────────────────────────────────────
@@ -553,32 +997,65 @@ module Woods
       pairs.to_a
     end
 
+    # Forward adjacency, resolved once per node per analyzer instance.
+    #
+    # {#bridges} runs `sample_size` whole-graph traversals, and
+    # `DependencyGraph#dependencies_of` sorts and flattens the node's edge
+    # buckets on every call, so an uncached BFS re-derived the same adjacency
+    # list up to 200 times per node. Populated on demand rather than up front:
+    # a traversal that never reaches a node should not pay for it.
+    #
+    # @return [Hash{String => Array<String>}]
+    def adjacency
+      @adjacency ||= Hash.new { |cache, identifier| cache[identifier] = @graph.dependencies_of(identifier) }
+    end
+
     # BFS shortest path between two nodes, following forward edges.
     #
+    # Carries parent pointers rather than a path per queue entry. The old form
+    # allocated a copy of the path so far for every node it enqueued, which on
+    # a large graph is a full array per node per traversal; the path is now
+    # built once, for the one node that matched.
+    #
     # @param source [String] Starting node identifier
     # @param target [String] Target node identifier
     # @return [Array<String>, nil] Shortest path or nil if unreachable
     def bfs_shortest_path(source, target)
       return [source] if source == target
 
-      visited = Set.new([source])
-      queue = [[source, [source]]]
+      parents = { source => nil }
+      queue = [source]
+      head = 0
 
-      while queue.any?
-        current, path = queue.shift
+      while head < queue.size
+        current = queue[head]
+        head += 1
 
-        @graph.dependencies_of(current).each do |neighbor|
-          next if visited.include?(neighbor)
+        adjacency[current].each do |neighbor|
+          next if parents.key?(neighbor)
 
-          new_path = path + [neighbor]
-          return new_path if neighbor == target
+          parents[neighbor] = current
+          return path_to(parents, neighbor) if neighbor == target
 
-          visited.add(neighbor)
-          queue.push([neighbor, new_path])
+          queue.push(neighbor)
         end
       end
 
       nil
     end
+
+    # Walk parent pointers back to the source and reverse.
+    #
+    # @param parents [Hash{String => String, nil}] node => the node it was reached from
+    # @param node [String] the end of the path
+    # @return [Array<String>] source-first path ending at +node+
+    def path_to(parents, node)
+      path = []
+      while node
+        path << node
+        node = parents[node]
+      end
+      path.reverse
+    end
   end
 end