rigor-module-graph 0.1.0

data/lib/rigor/module_graph/reachability.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module Rigor
+  module ModuleGraph
+    # Restricts an edge list to the subgraph reachable from a set
+    # of root nodes within a hop limit.
+    #
+    # Used by the +--from+ / +--depth+ CLI flags to make a graph
+    # focused on one or a few constants tractable to look at on a
+    # large project (where dumping every edge produces 1000+-node
+    # Mermaid output that browsers refuse to render).
+    #
+    # Direction is configurable:
+    #
+    # +:out+::   follow edges in the natural direction
+    #            (depends-on)
+    # +:in+::    follow edges backwards (depended-on-by)
+    # +:both+::  union of the two (the default — usually what
+    #            "what's around Article?" means)
+    module Reachability
+      module_function
+
+      VALID_DIRECTIONS = %i[out in both].freeze
+      VALID_EDGE_SCOPES = %i[cluster walk].freeze
+
+      EMPTY = [].freeze
+      private_constant :EMPTY
+
+      # @param edges [Array<Edge>]
+      # @param roots [Array<String>] node names to start from
+      # @param depth [Integer, nil] hop limit, nil for unlimited
+      # @param direction [Symbol] one of VALID_DIRECTIONS
+      # @param edge_scope [Symbol] one of VALID_EDGE_SCOPES.
+      #   +:cluster+ (default) keeps every edge whose endpoints
+      #   both fall in the reachable node set — useful when you
+      #   want the neighbourhood as a cluster. +:walk+ keeps only
+      #   the edges the BFS itself traverses, so a
+      #   +depth=1 --direction out+ walk from +Article+ returns
+      #   exactly the edges whose +from+ is +Article+, never the
+      #   sibling +inherits ApplicationRecord+ rows from the
+      #   reached set.
+      # @return [Array<Edge>] filtered edges with original order
+      #   preserved.
+      def filter(edges, roots:, depth: nil, direction: :both, edge_scope: :cluster)
+        roots = Array(roots).map(&:to_s).reject(&:empty?)
+        return edges if roots.empty?
+
+        unless VALID_DIRECTIONS.include?(direction)
+          raise ArgumentError, "unknown direction #{direction.inspect}; expected one of #{VALID_DIRECTIONS.inspect}"
+        end
+        unless VALID_EDGE_SCOPES.include?(edge_scope)
+          raise ArgumentError, "unknown edge_scope #{edge_scope.inspect}; expected one of #{VALID_EDGE_SCOPES.inspect}"
+        end
+
+        case edge_scope
+        when :cluster
+          reachable = walk(edges, roots, depth, direction)
+          edges.select { |e| reachable.key?(e.from) && reachable.key?(e.to) }
+        when :walk
+          indexes = walked_edge_indexes(edges, roots, depth, direction)
+          # `walked` is a Hash<edge_index, true>; filter by
+          # membership keeping the original edge order.
+          out = []
+          edges.each_with_index do |e, i|
+            out << e if indexes.key?(i)
+          end
+          out
+        end
+      end
+
+      # BFS over the edge graph; returns a Hash<node_name, true>
+      # whose keys are the reachable nodes. We use a Hash instead
+      # of Set because Hash key lookup is faster on Ruby 4 and we
+      # don't need Set's union/intersection methods here.
+      def walk(edges, roots, depth, direction)
+        forward, backward = build_adjacency(edges, direction)
+
+        visited = {}
+        frontier = []
+        roots.each do |r|
+          visited[r] = true
+          frontier << r
+        end
+        hops = 0
+
+        until frontier.empty?
+          break if depth && hops >= depth
+
+          next_frontier = []
+          frontier.each do |node|
+            each_neighbour(node, forward, backward, direction) do |n|
+              next if visited.key?(n)
+
+              visited[n] = true
+              next_frontier << n
+            end
+          end
+          frontier = next_frontier
+          hops += 1
+        end
+        visited
+      end
+
+      # Returns a Hash<edge_index, true> for the edges actually
+      # traversed by the BFS. `direction=both` runs the out-walk
+      # and in-walk against separate adjacency tables so the
+      # zigzag chain (+A <- X -> Y+ whose +X -> Y+ isn't on any
+      # genuine path from the roots) stays excluded.
+      def walked_edge_indexes(edges, roots, depth, direction)
+        if direction == :both
+          forward, backward = build_indexed_adjacencies(edges)
+          walked = {}
+          run_indexed_walk(forward, roots, depth, walked)
+          run_indexed_walk(backward, roots, depth, walked)
+          return walked
+        end
+
+        adjacency = build_indexed_adjacency(edges, direction)
+        walked = {}
+        run_indexed_walk(adjacency, roots, depth, walked)
+        walked
+      end
+
+      # @api private
+      def build_adjacency(edges, direction)
+        # Build only the adjacency tables we actually need. The
+        # caller asking for +:out+ never touches +backward+ etc.
+        forward = direction == :in ? nil : Hash.new { |h, k| h[k] = [] }
+        backward = direction == :out ? nil : Hash.new { |h, k| h[k] = [] }
+        edges.each do |edge|
+          forward[edge.from] << edge.to if forward
+          backward[edge.to] << edge.from if backward
+        end
+        [forward, backward]
+      end
+
+      def each_neighbour(node, forward, backward, direction, &block)
+        case direction
+        when :out
+          forward.fetch(node, EMPTY).each(&block)
+        when :in
+          backward.fetch(node, EMPTY).each(&block)
+        when :both
+          forward.fetch(node, EMPTY).each(&block)
+          backward.fetch(node, EMPTY).each(&block)
+        end
+      end
+
+      def build_indexed_adjacency(edges, direction)
+        adjacency = Hash.new { |h, k| h[k] = [] }
+        edges.each_with_index do |edge, i|
+          case direction
+          when :out then adjacency[edge.from] << [edge.to, i]
+          when :in then adjacency[edge.to] << [edge.from, i]
+          end
+        end
+        adjacency
+      end
+
+      def build_indexed_adjacencies(edges)
+        forward = Hash.new { |h, k| h[k] = [] }
+        backward = Hash.new { |h, k| h[k] = [] }
+        edges.each_with_index do |edge, i|
+          forward[edge.from] << [edge.to, i]
+          backward[edge.to] << [edge.from, i]
+        end
+        [forward, backward]
+      end
+
+      def run_indexed_walk(adjacency, roots, depth, walked)
+        visited = {}
+        frontier = []
+        roots.each do |r|
+          visited[r] = true
+          frontier << r
+        end
+        hops = 0
+        until frontier.empty?
+          break if depth && hops >= depth
+
+          next_frontier = []
+          frontier.each do |node|
+            adjacency.fetch(node, EMPTY).each do |neighbour, edge_index|
+              walked[edge_index] = true
+              next if visited.key?(neighbour)
+
+              visited[neighbour] = true
+              next_frontier << neighbour
+            end
+          end
+          frontier = next_frontier
+          hops += 1
+        end
+      end
+    end
+  end
+end

data/lib/rigor/module_graph/stats.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Rigor
+  module ModuleGraph
+    # Computes per-namespace dependency metrics over an edge list.
+    #
+    # Five numbers per namespace:
+    #
+    # +nodes+::      number of distinct constants in the namespace
+    # +fan_out+::    edges whose +from+ is in the namespace and
+    #                +to+ is outside it
+    # +fan_in+::     edges whose +to+ is in the namespace and
+    #                +from+ is outside it
+    # +internal+::   edges where both endpoints sit in the namespace
+    # +total+::      +fan_out+ + +internal+ — every edge originating
+    #                in the namespace
+    #
+    # Grouping is by top-level namespace by default
+    # (+Billing::Invoice+ → +Billing+). Pass +depth: N+ for a
+    # deeper split (+Billing::Invoice::Line+ at depth 2 →
+    # +Billing::Invoice+). Names without enough segments at the
+    # requested depth bucket under the special label
+    # +"(top-level)"+ so they stay visible in the report.
+    module Stats
+      module_function
+
+      TOP_LEVEL_BUCKET = "(top-level)"
+
+      # @param edges [Array<Edge>]
+      # @param depth [Integer] number of leading +::+ segments to
+      #   keep when grouping
+      # @return [Array<NamespaceMetrics>] sorted by fan_out desc,
+      #   then namespace asc; deterministic output.
+      def compute(edges, depth: 1)
+        # Single pass over edges. For each edge we resolve both
+        # endpoints to a normalised name (cached), then to a
+        # bucket (cached), then update the bucket's mutable
+        # `[nodes_set, fan_out, fan_in, internal]` counter array.
+        # Allocating one immutable `NamespaceMetrics` per edge via
+        # `Data#with` is what made the old implementation slow.
+        normalised = {}
+        groups = {}
+        counters = Hash.new { |h, k| h[k] = [{}, 0, 0, 0] }
+
+        edges.each do |edge|
+          from = (normalised[edge.from] ||= fast_normalise(edge.from))
+          to = (normalised[edge.to] ||= fast_normalise(edge.to))
+
+          from_group = (groups[from] ||= bucket_for_normalised(from, depth))
+          to_group = (groups[to] ||= bucket_for_normalised(to, depth))
+
+          from_counter = counters[from_group]
+          to_counter = counters[to_group]
+          from_counter[0][from] = true
+          to_counter[0][to] = true
+
+          if from_group == to_group
+            from_counter[3] += 1
+          else
+            from_counter[1] += 1
+            to_counter[2] += 1
+          end
+        end
+
+        metrics = counters.map do |namespace, counter|
+          NamespaceMetrics.new(
+            namespace: namespace,
+            nodes: counter[0].size,
+            fan_out: counter[1],
+            fan_in: counter[2],
+            internal: counter[3]
+          )
+        end
+        metrics.sort_by { |m| [-m.fan_out, m.namespace] }
+      end
+
+      # Strip leading "::" so absolute and relative names share
+      # the same bucket / node identity — they refer to the same
+      # constant either way.
+      def fast_normalise(name)
+        name.start_with?("::") ? name[2..] : name
+      end
+
+      # Like +bucket_for+, but skips the +split+ allocation when
+      # the name has more segments than +depth+. Walks +index+
+      # once per +::+ separator and slices once at the boundary.
+      def bucket_for_normalised(name, depth)
+        cursor = -2
+        depth.times do
+          cursor = name.index("::", cursor + 2)
+          return TOP_LEVEL_BUCKET unless cursor
+        end
+        name[0...cursor]
+      end
+
+      # The five numbers for one namespace, exposed as a Data
+      # value so callers can treat the result like a row of a
+      # table.
+      NamespaceMetrics = Data.define(:namespace, :nodes, :fan_out, :fan_in, :internal) do
+        # Sum of edges originating in the namespace
+        # (fan_out + internal).
+        def total
+          fan_out + internal
+        end
+
+        def to_h
+          {
+            "namespace" => namespace,
+            "nodes" => nodes,
+            "fan_out" => fan_out,
+            "fan_in" => fan_in,
+            "internal" => internal,
+            "total" => total
+          }
+        end
+      end
+    end
+  end
+end

data/lib/rigor/module_graph/templates/view.html.erb

@@ -0,0 +1,50 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title><%= title %></title>
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs";
+      mermaid.initialize({
+        startOnLoad: true,
+        securityLevel: "loose",
+        maxTextSize: 5_000_000,
+        maxEdges: 50_000,
+        flowchart: { useMaxWidth: false, htmlLabels: true }
+      });
+    </script>
+    <style>
+      body { font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; margin: 2rem; color: #0f172a; background: #f8fafc; }
+      h1 { margin-top: 0; }
+      .meta { color: #64748b; margin-bottom: 1.5rem; }
+      .card { background: white; border: 1px solid #e2e8f0; border-radius: 8px; padding: 1.5rem; box-shadow: 0 1px 2px rgba(15,23,42,0.04); }
+      .legend { display: flex; gap: 1rem; flex-wrap: wrap; margin-top: 1rem; }
+      .legend span { padding: 0.25rem 0.75rem; border-radius: 999px; color: white; font-size: 12px; }
+      .legend .inherits { background: #0f172a; }
+      .legend .include { background: #1d4ed8; }
+      .legend .prepend { background: #9333ea; }
+      .legend .extend { background: #0f766e; }
+      .legend .const_ref { background: #94a3b8; color: #0f172a; }
+      .legend .unresolved { background: #fef3c7; color: #0f172a; }
+    </style>
+  </head>
+  <body>
+    <h1><%= title %></h1>
+    <% if subtitle -%>
+      <p class="meta"><%= subtitle %></p>
+    <% end -%>
+    <div class="card">
+      <pre class="mermaid">
+<%= indented_mermaid %>
+      </pre>
+    </div>
+    <div class="legend">
+      <span class="inherits">inherits</span>
+      <span class="include">include</span>
+      <span class="prepend">prepend</span>
+      <span class="extend">extend</span>
+      <span class="const_ref">const_ref</span>
+      <span class="unresolved">unresolved</span>
+    </div>
+  </body>
+</html>

data/lib/rigor/module_graph/uml/class_diagram.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Rigor
+  module ModuleGraph
+    module Uml
+      # Renders a +classDiagram+ Mermaid document from a list of
+      # edges plus a list of node metadata rows (the +nodes.jsonl+
+      # the collector writes alongside +edges.jsonl+).
+      #
+      # Differences from the +flowchart+ renderer:
+      #
+      # * Each class / module gets a body block listing its
+      #   instance methods, class methods, and attributes, with the
+      #   standard UML visibility glyphs (+, -, #).
+      # * Modules are annotated +<<module>>+ so a Ruby module is
+      #   visually distinct from a class.
+      # * +inherits+ uses +--|>+, mixin uses +..|>+, +const_ref+
+      #   uses +..>+, ActiveRecord associations carry cardinality
+      #   pairs ("1" / "*") as edge endpoints.
+      # * Mermaid disallows +::+ in class identifiers; we sanitise
+      #   to +__+ and keep the original as the label only.
+      #
+      # Filtering knobs:
+      #
+      # * +include_methods:+ (default true) — show methods inside
+      #   class bodies.
+      # * +include_attributes:+ (default true) — show attributes.
+      # * +visibilities:+ — array subset of +%w[public protected
+      #   private]+, default all.
+      module ClassDiagram
+        module_function
+
+        VISIBILITY_GLYPH = {
+          "public" => "+",
+          "protected" => "#",
+          "private" => "-"
+        }.freeze
+
+        ARROW_FOR_KIND = {
+          "inherits" => "<|--",
+          "include" => "<|..",
+          "prepend" => "<|..",
+          "extend" => "<|..",
+          "const_ref" => "<.."
+        }.freeze
+
+        CARDINALITY = {
+          "has_many" => ['"1"', '"*"'],
+          "belongs_to" => ['"*"', '"1"'],
+          "has_one" => ['"1"', '"1"'],
+          "has_and_belongs_to_many" => ['"*"', '"*"']
+        }.freeze
+
+        def render(edges, nodes,
+                   include_methods: true,
+                   include_attributes: true,
+                   visibilities: %w[public protected private])
+          declarations = node_declarations(nodes)
+          members = node_members(nodes, include_methods, include_attributes, visibilities)
+
+          out = +"classDiagram\n"
+          render_classes(out, declarations, members, edges)
+          render_edges(out, dedup(edges))
+          out
+        end
+
+        # +Foo::Bar+ can't be a Mermaid identifier; coerce to a
+        # safe form. The label always carries the original.
+        def safe_id(name)
+          name.gsub(/[^A-Za-z0-9_]+/, "__")
+        end
+
+        def dedup(edges)
+          seen = {}
+          edges.each_with_object([]) do |edge, acc|
+            key = edge.dedup_key
+            next if seen[key]
+
+            seen[key] = true
+            acc << edge
+          end
+        end
+
+        # Build a +{name => "class"|"module"}+ table from the
+        # node-declaration rows.
+        def node_declarations(nodes)
+          decl = {}
+          nodes.each do |row|
+            case row.kind
+            when "class", "module"
+              # Re-opens may set the same row multiple times —
+              # whichever wins doesn't matter because the kind is
+              # the same.
+              decl[row.name] = row.kind
+            end
+          end
+          decl
+        end
+
+        # Build a +{owner_name => [{glyph, name, label}, ...]}+
+        # table covering the displayable members for every owner.
+        def node_members(nodes, include_methods, include_attributes, visibilities)
+          members = Hash.new { |h, k| h[k] = [] }
+          nodes.each do |row|
+            owner = row.owner
+            next if owner.nil?
+
+            visibility = row.visibility || "public"
+            next unless visibilities.include?(visibility)
+
+            glyph = VISIBILITY_GLYPH.fetch(visibility, "+")
+
+            case row.kind
+            when "instance_method", "class_method"
+              next unless include_methods
+
+              suffix = row.kind == "class_method" ? "$ " : ""
+              members[owner] << "#{glyph}#{row.name}() #{suffix}".strip
+            when "attribute"
+              next unless include_attributes
+
+              # access (read/write/accessor) hints at getter/setter
+              # presence; we annotate it after the name.
+              members[owner] << "#{glyph}#{row.name} : #{row.access}"
+            end
+          end
+          members
+        end
+
+        # Emit one +class Foo+ line per node, plus a body block of
+        # methods / attributes when we have any.
+        #
+        # We intentionally do NOT emit the UML +<<module>>+
+        # annotation: Mermaid 10.x's classDiagram parser silently
+        # rejects the document when an annotation co-exists with
+        # the +class Foo["Label"]+ form we need for namespaced
+        # constants, and rejecting the namespace label is worse for
+        # a Ruby graph than losing the module marker. The module
+        # vs class distinction is therefore encoded as a +" (mod)"+
+        # label suffix for module nodes — it is rendered inside the
+        # box where every Mermaid renderer surfaces it.
+        #
+        # Any class that appears only in an edge keeps its bare
+        # +class Foo+ line so the arrow has a target.
+        def render_classes(out, declarations, members, edges)
+          known = Set.new(declarations.keys)
+          edges.each do |edge|
+            known << edge.from << edge.to
+          end
+          known.sort.each do |name|
+            id = safe_id(name)
+            kind = declarations[name]
+            label = label_for(name, kind)
+            label_suffix = (label == id ? "" : "[\"#{label}\"]")
+            out << "  class #{id}#{label_suffix}\n"
+
+            owner_members = members[name]
+            next if owner_members.nil? || owner_members.empty?
+
+            out << "  class #{id} {\n"
+            owner_members.each do |line|
+              out << "    #{line}\n"
+            end
+            out << "  }\n"
+          end
+        end
+
+        def label_for(name, kind)
+          if kind == "module"
+            "#{name} «module»"
+          else
+            name
+          end
+        end
+
+        def render_edges(out, edges)
+          out << "\n" unless edges.empty?
+          edges.each do |edge|
+            from_id = safe_id(edge.from)
+            to_id = safe_id(edge.to)
+            if (cardinality = CARDINALITY[edge.kind])
+              left, right = cardinality
+              # `from --> to : has_many` — Mermaid renders this as
+              # an association arrow with the kind label.
+              out << "  #{to_id} #{left} -- #{right} #{from_id} : #{edge.kind}\n"
+            elsif (arrow = ARROW_FOR_KIND[edge.kind])
+              out << "  #{to_id} #{arrow} #{from_id} : #{edge.kind}\n"
+            else
+              out << "  #{to_id} <-- #{from_id} : #{edge.kind}\n"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rigor/module_graph/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Rigor
+  # The +rigor-module-graph+ gem's public API. See the README for
+  # an overview and Rigor::ModuleGraph::CLI for the CLI surface.
+  module ModuleGraph
+    # The installed gem version.
+    VERSION = "0.1.0"
+  end
+end

data/lib/rigor/module_graph/visibility_map.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module ModuleGraph
+    # Pre-walks a Prism tree once and records each +DefNode+'s
+    # effective visibility based on the running +public+ /
+    # +protected+ / +private+ marker calls inside its enclosing
+    # class / module body.
+    #
+    # The Analyzer's per-node rules can then look up a visibility
+    # in O(1) without re-walking the surrounding body. Built once
+    # per file by the plugin's +node_file_context+ hook.
+    #
+    # Limitations (acknowledged):
+    #
+    # * +private :foo+ (explicit symbol form) is ignored; only the
+    #   bare keyword that flips the running visibility is honoured.
+    #   The bare form covers ~90% of Ruby; the symbol form mostly
+    #   shows up in DSL-generated method blocks.
+    # * +private_class_method+ and singleton-class blocks
+    #   (+class << self+) are not interpreted.
+    # * Methods inside a +class+ inside a method body (rare) stay
+    #   at +public+.
+    class VisibilityMap
+      VISIBILITY_MARKERS = %i[public protected private].freeze
+
+      def initialize
+        @table = {}.compare_by_identity
+      end
+
+      # @param root [Prism::Node]
+      # @return [VisibilityMap]
+      def self.build(root)
+        map = new
+        walk_top_level(root, map) if root
+        map
+      end
+
+      def visibility_for(node)
+        @table[node]
+      end
+
+      def self.walk_top_level(node, map)
+        return unless node.is_a?(Prism::Node)
+
+        # The top level is a module-like scope; defs there read as
+        # public. Modules nested below get their own pass with the
+        # visibility reset to public.
+        case node
+        when Prism::ProgramNode
+          walk_top_level(node.statements, map)
+        when Prism::StatementsNode
+          node.body.each { |child| walk_top_level(child, map) }
+        when Prism::ClassNode, Prism::ModuleNode
+          walk_body(node, map)
+        end
+      end
+
+      def self.walk_body(class_or_module, map)
+        body = class_or_module.body
+        statements = body.respond_to?(:body) ? Array(body.body) : []
+        current = "public"
+
+        statements.each do |stmt|
+          case stmt
+          when Prism::CallNode
+            if VISIBILITY_MARKERS.include?(stmt.name) && bare_marker?(stmt)
+              current = stmt.name.to_s
+            end
+          when Prism::DefNode
+            map.record(stmt, current)
+          when Prism::ClassNode, Prism::ModuleNode
+            walk_body(stmt, map)
+          end
+        end
+      end
+
+      def self.bare_marker?(call_node)
+        call_node.receiver.nil? &&
+          (call_node.arguments.nil? || call_node.arguments.arguments.empty?)
+      end
+
+      def record(node, visibility)
+        @table[node] = visibility
+      end
+    end
+  end
+end