rigor-module-graph 0.1.0

data/lib/rigor/module_graph/mermaid.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Rigor
+  module ModuleGraph
+    # Renders edges as a Mermaid flowchart.
+    #
+    # Mermaid does not have per-edge style classes the way DOT does;
+    # we use distinct arrow heads per kind (`==>`, `-->`, `-.->`)
+    # plus an `:::kind` classDef on the target node so the legend is
+    # readable in any Mermaid renderer.
+    #
+    # When `collapse:` is given, every node whose name sits under one
+    # of the listed prefixes is wrapped in a `subgraph <prefix>`
+    # block, with the prefix stripped from the visible label.
+    module Mermaid
+      module_function
+
+      ARROW_FOR_KIND = {
+        "inherits" => "==>",
+        "include" => "-->",
+        "prepend" => "-->",
+        "extend" => "-.->",
+        "const_ref" => "-.->"
+      }.freeze
+
+      CLASS_DEFS = <<~MERMAID
+        classDef inherits fill:#0f172a,color:#fff,stroke:#0f172a;
+        classDef include fill:#1d4ed8,color:#fff,stroke:#1d4ed8;
+        classDef prepend fill:#9333ea,color:#fff,stroke:#9333ea;
+        classDef extend fill:#0f766e,color:#fff,stroke:#0f766e;
+        classDef const_ref fill:#cbd5e1,color:#0f172a,stroke:#94a3b8;
+        classDef unresolved fill:#fef3c7,color:#0f172a,stroke:#d97706,stroke-dasharray: 4 4;
+      MERMAID
+
+      # @param edges [Array<Edge>]
+      # @param collapse [Array<String>] namespace prefixes to fold
+      #   into subgraphs (mutually exclusive with +groups+)
+      # @param groups [Hash{String=>String}, nil] explicit
+      #   +{node_name => cluster_label}+ mapping. Takes precedence
+      #   over +collapse+ when given.
+      def render(edges, collapse: [], groups: nil)
+        edges = dedup(edges)
+        node_ids = assign_node_ids(edges)
+        clusters, ungrouped = build_groups(node_ids.keys.sort, collapse, groups)
+
+        out = +"flowchart LR\n"
+        clusters.each do |label, members|
+          out << render_cluster(label, members, node_ids, use_namespace_prefix: groups.nil?)
+        end
+        ungrouped.each do |name|
+          out << "  #{node_ids[name]}[\"#{escape_label(name)}\"]\n"
+        end
+        out << "\n" unless node_ids.empty?
+        edges.each do |edge|
+          arrow = ARROW_FOR_KIND.fetch(edge.kind, "-->")
+          out << "  #{node_ids[edge.from]} #{arrow}|#{edge.kind}| #{node_ids[edge.to]}\n"
+        end
+        out << "\n"
+        out << CLASS_DEFS
+        # One class assignment per node id. Mermaid silently keeps
+        # the last assignment but starts to error out when the same
+        # `class N kind;` line repeats many hundreds of times in a
+        # large graph, so we dedupe and pick the most structural
+        # kind per node (inherits > include > prepend > extend >
+        # const_ref) so the resulting colour conveys intent.
+        out << render_class_assignments(edges, node_ids)
+        out
+      end
+
+      KIND_PRIORITY = {
+        "inherits" => 0,
+        "include" => 1,
+        "prepend" => 2,
+        "extend" => 3,
+        "const_ref" => 4
+      }.freeze
+
+      def render_class_assignments(edges, node_ids)
+        per_node = {}
+        edges.each do |edge|
+          id = node_ids[edge.to]
+          tag = edge.confidence == "unresolved" ? "unresolved" : edge.kind
+          current = per_node[id]
+          if current.nil? || better_tag?(tag, current)
+            per_node[id] = tag
+          end
+        end
+        per_node.map { |id, tag| "  class #{id} #{tag};\n" }.join
+      end
+
+      def better_tag?(candidate, current)
+        return false if current == "unresolved"
+        return true if candidate == "unresolved"
+
+        (KIND_PRIORITY[candidate] || 99) < (KIND_PRIORITY[current] || 99)
+      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
+
+      def assign_node_ids(edges)
+        names = edges.flat_map { |edge| [edge.from, edge.to] }.uniq.sort
+        names.each_with_index.to_h { |name, idx| [name, "n#{idx}"] }
+      end
+
+      def build_groups(names, collapse, groups)
+        if groups && !groups.empty?
+          clusters = Hash.new { |h, k| h[k] = [] }
+          ungrouped = []
+          names.each do |name|
+            if (label = groups[name])
+              clusters[label] << name
+            else
+              ungrouped << name
+            end
+          end
+          [clusters, ungrouped]
+        else
+          group_by_prefix(names, collapse)
+        end
+      end
+
+      def group_by_prefix(names, collapse)
+        prefixes = Array(collapse).map(&:to_s).reject(&:empty?)
+        return [{}, names] if prefixes.empty?
+
+        sorted = prefixes.sort_by { |p| -p.length }
+        clusters = Hash.new { |h, k| h[k] = [] }
+        ungrouped = []
+        names.each do |name|
+          match = sorted.find { |p| name.start_with?(p + "::") }
+          if match
+            clusters[match] << name
+          else
+            ungrouped << name
+          end
+        end
+        [clusters, ungrouped]
+      end
+
+      def render_cluster(label, members, node_ids, use_namespace_prefix: true)
+        out = +"  subgraph #{cluster_id(label)} [\"#{escape_label(label)}\"]\n"
+        members.each do |name|
+          short = use_namespace_prefix ? name.sub(/\A#{Regexp.escape(label)}::/, "") : name
+          out << "    #{node_ids[name]}[\"#{escape_label(short)}\"]\n"
+        end
+        out << "  end\n"
+      end
+
+      # Mermaid subgraph ids must be plain identifiers; anything
+      # else breaks the parser silently. Coerce non-alnum
+      # characters to `_` so `packages/billing` ends up as
+      # `sg_packages_billing` and stays unambiguous.
+      def cluster_id(prefix)
+        "sg_#{prefix.gsub(/[^A-Za-z0-9_]+/, "_")}"
+      end
+
+      def escape_label(name)
+        name.gsub('"', "#quot;")
+      end
+    end
+  end
+end

data/lib/rigor/module_graph/node.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rigor
+  module ModuleGraph
+    # Kinds of node metadata the plugin emits. Class and module
+    # declarations carry the class itself; the remaining kinds are
+    # children of one — methods and attributes.
+    NODE_KINDS = %w[
+      class
+      module
+      instance_method
+      class_method
+      attribute
+    ].freeze
+
+    # Visibility values for a method / attribute. Matches the Ruby
+    # access modifiers.
+    NODE_VISIBILITIES = %w[public protected private].freeze
+
+    # Access flavours for an +attr_*+ macro. Used to label
+    # attribute glyphs in a class diagram and nothing else.
+    NODE_ACCESSES = %w[read write accessor].freeze
+
+    # A piece of node metadata extracted from a source file.
+    #
+    # Three flavours, distinguished by +kind+:
+    #
+    # * +class+ / +module+ — a constant declaration. Carries
+    #   +name+, +path+, +line+, +column+. +owner+/+visibility+/
+    #   +access+ are nil.
+    # * +instance_method+ / +class_method+ — a method definition.
+    #   Carries +name+, +owner+ (the enclosing class/module),
+    #   +visibility+, +path+, +line+, +column+.
+    # * +attribute+ — an +attr_reader+ / +attr_writer+ /
+    #   +attr_accessor+ symbol. Carries +name+, +owner+,
+    #   +visibility+, +access+, +path+, +line+, +column+.
+    class Node < Data.define(:kind, :name, :owner, :path, :line, :column, :visibility, :access)
+      KINDS = NODE_KINDS
+      VISIBILITIES = NODE_VISIBILITIES
+      ACCESSES = NODE_ACCESSES
+
+      def self.build(kind:, name:, owner: nil, path: nil, line: nil, column: nil,
+                     visibility: nil, access: nil)
+        new(
+          kind: validate_kind!(kind),
+          name: name.to_s.freeze,
+          owner: owner && owner.to_s.freeze,
+          path: path,
+          line: line,
+          column: column,
+          visibility: visibility && validate_visibility!(visibility),
+          access: access && validate_access!(access)
+        )
+      end
+
+      def self.validate_kind!(kind) # :nodoc:
+        kind = kind.to_s
+        return kind if KINDS.include?(kind)
+
+        raise ArgumentError, "unknown node kind #{kind.inspect}; expected one of #{KINDS.inspect}"
+      end
+
+      def self.validate_visibility!(visibility) # :nodoc:
+        visibility = visibility.to_s
+        return visibility if VISIBILITIES.include?(visibility)
+
+        raise ArgumentError, "unknown visibility #{visibility.inspect}; expected one of #{VISIBILITIES.inspect}"
+      end
+
+      def self.validate_access!(access) # :nodoc:
+        access = access.to_s
+        return access if ACCESSES.include?(access)
+
+        raise ArgumentError, "unknown access #{access.inspect}; expected one of #{ACCESSES.inspect}"
+      end
+
+      def to_h
+        h = { "kind" => kind, "name" => name }
+        h["owner"] = owner if owner
+        h["path"] = path if path
+        h["line"] = line if line
+        h["column"] = column if column
+        h["visibility"] = visibility if visibility
+        h["access"] = access if access
+        h
+      end
+
+      # The payload embedded in the plugin's +:info+ diagnostic
+      # message. Position is intentionally absent — the diagnostic
+      # row carries +path+/+line+/+column+ on its own.
+      def to_message_payload
+        h = { "kind" => kind, "name" => name }
+        h["owner"] = owner if owner
+        h["visibility"] = visibility if visibility
+        h["access"] = access if access
+        h
+      end
+
+      # Key used to dedupe node rows. Two declarations of the same
+      # method on the same owner collapse to one row; class re-opens
+      # collapse to one class node.
+      def dedup_key
+        [kind, owner, name]
+      end
+    end
+
+    # JSONL reader / writer for Node rows.
+    module NodeIO
+      module_function
+
+      def write(nodes, io)
+        seen = {}
+        nodes.each do |node|
+          key = node.dedup_key
+          next if seen[key]
+
+          seen[key] = true
+          io.puts(JSON.generate(node.to_h))
+        end
+      end
+
+      def read(io)
+        nodes = []
+        io.each_line do |line|
+          line = line.strip
+          next if line.empty?
+
+          row = JSON.parse(line)
+          nodes << Node.build(
+            kind: row.fetch("kind"),
+            name: row.fetch("name"),
+            owner: row["owner"],
+            path: row["path"],
+            line: row["line"],
+            column: row["column"],
+            visibility: row["visibility"],
+            access: row["access"]
+          )
+        end
+        nodes
+      end
+    end
+  end
+end

data/lib/rigor/module_graph/packwerk_overlay.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "find"
+
+module Rigor
+  module ModuleGraph
+    # Discovers Packwerk-style packages (`package.yml`) inside a
+    # project tree and maps source file paths to their owning
+    # package.
+    #
+    # Treats every directory that contains a +package.yml+ as a
+    # package root. The package's name is its path relative to the
+    # project root with a leading +./+ stripped — that's how
+    # +packwerk+ itself reports them, and it's stable across
+    # Packwerk versions which gives the renderer something to use
+    # as the cluster label.
+    #
+    # Files map to the +deepest+ ancestor package — if a nested
+    # `packages/billing/invoices/package.yml` lives under
+    # `packages/billing/package.yml`, a file under the inner one
+    # belongs to +packages/billing/invoices+, not +packages/billing+.
+    class PackwerkOverlay
+      Package = Data.define(:name, :root) do
+        # Stable rendering for snapshot / debug output.
+        def to_s
+          "Package(#{name})"
+        end
+      end
+
+      EXCLUDED_DIRS = %w[.git node_modules tmp log vendor].freeze
+      private_constant :EXCLUDED_DIRS
+
+      attr_reader :project_root, :packages
+
+      # @param project_root [String] the project root the packages
+      #   are reported relative to
+      # @param packages [Array<Package>] frozen
+      def initialize(project_root:, packages:)
+        @project_root = realpath_or_expand(project_root)
+        @packages = packages
+                    .map { |pkg| Package.new(name: pkg.name, root: realpath_or_expand(pkg.root)) }
+                    .sort_by { |p| -p.root.length }
+                    .freeze
+      end
+
+      # @param project_root [String]
+      # @return [PackwerkOverlay]
+      def self.discover(project_root)
+        root = File.expand_path(project_root)
+        packages = []
+        Find.find(root) do |path|
+          base = File.basename(path)
+          if File.directory?(path) && EXCLUDED_DIRS.include?(base) && path != root
+            Find.prune
+            next
+          end
+          next unless File.file?(path) && base == "package.yml"
+
+          pkg_root = File.dirname(path)
+          packages << Package.new(name: package_name(pkg_root, root), root: pkg_root)
+        end
+        new(project_root: root, packages: packages)
+      end
+
+      def self.package_name(pkg_root, project_root)
+        # The root package (a `package.yml` at the project root) is
+        # canonically called `.` in Packwerk output. Match that so
+        # users see the familiar label.
+        return "." if pkg_root == project_root
+
+        rel = pkg_root.sub(%r{\A#{Regexp.escape(project_root)}/?}, "")
+        rel.empty? ? "." : rel
+      end
+
+      # @return [Boolean] true when at least one package.yml was
+      #   found.
+      def any?
+        !@packages.empty?
+      end
+
+      # Find the deepest package whose root is an ancestor of
+      # +path+. Returns nil when the path is outside every
+      # package's root.
+      #
+      # Both sides are normalised through +realpath+ when
+      # possible so a macOS +/tmp+ ↔ +/private/tmp+ symlink (or
+      # any other symlink in the project root path) doesn't make
+      # the comparison spuriously miss.
+      def package_for(path)
+        return nil if path.nil? || path.empty?
+
+        absolute = realpath_of(File.expand_path(path, @project_root))
+        @packages.find do |pkg|
+          absolute == pkg.root || absolute.start_with?(pkg.root + "/")
+        end
+      end
+
+      def realpath_or_expand(path)
+        File.realpath(File.expand_path(path))
+      rescue Errno::ENOENT
+        File.expand_path(path)
+      end
+
+      def realpath_of(path)
+        File.realpath(path)
+      rescue Errno::ENOENT
+        # Tests and synthetic edges may carry paths whose tail
+        # doesn't exist on disk; walk up to the deepest existing
+        # ancestor, realpath that, then reattach the missing tail.
+        # That makes a macOS +/tmp+ ↔ +/private/tmp+ symlink
+        # transparent even for synthetic paths.
+        parent = path
+        until parent == File.dirname(parent)
+          parent = File.dirname(parent)
+          if File.exist?(parent)
+            return File.realpath(parent) + path[parent.length..]
+          end
+        end
+        path
+      end
+
+      # Build a +{node_name => package_name}+ mapping from a list
+      # of edges. We only attribute a node to a package when we
+      # have evidence the node is *declared* under that package's
+      # root — that is, the node appears as +edge.from+ for at
+      # least one edge, and that edge's path lives under the
+      # package. The +to+ side is just a reference; using it would
+      # mis-attribute base classes (+ApplicationRecord+) and any
+      # other external constant to whichever package happens to
+      # reference them first.
+      def groups_for(edges)
+        node_paths = {}
+        edges.each do |edge|
+          node_paths[edge.from] ||= edge.path
+        end
+        node_paths.each_with_object({}) do |(name, path), acc|
+          pkg = package_for(path)
+          acc[name] = pkg.name if pkg
+        end
+      end
+    end
+  end
+end

data/lib/rigor/module_graph/plugin/rigor_plugin.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "json"
+require "prism"
+
+module Rigor
+  module ModuleGraph
+    # Rigor plugin: declares the node rules that emit class/module/
+    # constant dependency edges as `:info` diagnostics. Loaded only
+    # when `rigortype` is available (see `plugin.rb`).
+    class Plugin < ::Rigor::Plugin::Base
+      EDGE_RULE = "edge"
+      NODE_RULE = "node"
+      private_constant :EDGE_RULE, :NODE_RULE
+
+      manifest(
+        id: "module-graph",
+        version: Rigor::ModuleGraph::VERSION,
+        description: "Extract Ruby class/module/constant dependency graph as :info diagnostics.",
+        config_schema: {
+          "autoload_paths" => {
+            kind: :array,
+            default: ZeitwerkResolver::DEFAULT_AUTOLOAD_PATHS
+          },
+          "concern_dirs" => {
+            kind: :array,
+            default: ZeitwerkResolver::DEFAULT_CONCERN_DIRS
+          },
+          "rails_zeitwerk" => { kind: :boolean, default: true },
+          "include_constant_refs" => { kind: :boolean, default: false },
+          "emit_node_metadata" => { kind: :boolean, default: true },
+          "emit_associations" => { kind: :boolean, default: true }
+        }
+      )
+
+      # Pre-walk each file once to record per-DefNode visibility.
+      # Shared across all node_rule invocations for the same file.
+      node_file_context do |root, _scope|
+        VisibilityMap.build(root)
+      end
+
+      node_rule Prism::ClassNode do |node, scope, path, file_context, context|
+        analyzer = analyzer_for(scope, path, context, file_context)
+        diagnostics = analyzer.class_edges(node).map { |edge| edge_diagnostic(edge, node) }
+        if config["emit_node_metadata"]
+          if (meta = analyzer.class_node_metadata(node))
+            diagnostics << node_diagnostic(meta, node)
+          end
+        end
+        diagnostics
+      end
+
+      node_rule Prism::ModuleNode do |node, scope, path, file_context, context|
+        analyzer = analyzer_for(scope, path, context, file_context)
+        diagnostics = []
+        if config["emit_node_metadata"]
+          if (meta = analyzer.module_node_metadata(node))
+            diagnostics << node_diagnostic(meta, node)
+          end
+        end
+        diagnostics
+      end
+
+      node_rule Prism::CallNode do |node, scope, path, file_context, context|
+        analyzer = analyzer_for(scope, path, context, file_context)
+        diagnostics = analyzer.call_edges(node).map { |edge| edge_diagnostic(edge, node) }
+        if config["emit_associations"]
+          analyzer.association_edges(node).each do |edge|
+            diagnostics << edge_diagnostic(edge, node)
+          end
+        end
+        if config["emit_node_metadata"]
+          analyzer.attribute_nodes(node).each do |meta|
+            diagnostics << node_diagnostic(meta, node)
+          end
+        end
+        diagnostics
+      end
+
+      node_rule Prism::DefNode do |node, scope, path, file_context, context|
+        next [] unless config["emit_node_metadata"]
+
+        analyzer = analyzer_for(scope, path, context, file_context)
+        if (meta = analyzer.method_node_metadata(node))
+          [node_diagnostic(meta, node)]
+        else
+          []
+        end
+      end
+
+      node_rule Prism::ConstantReadNode do |node, scope, path, file_context, context|
+        next [] unless config["include_constant_refs"]
+
+        analyzer = analyzer_for(scope, path, context, file_context)
+        analyzer.constant_read_edges(node).map { |edge| edge_diagnostic(edge, node) }
+      end
+
+      node_rule Prism::ConstantPathNode do |node, scope, path, file_context, context|
+        next [] unless config["include_constant_refs"]
+
+        analyzer = analyzer_for(scope, path, context, file_context)
+        analyzer.constant_path_edges(node).map { |edge| edge_diagnostic(edge, node) }
+      end
+
+      def analyzer_for(scope, path, context, visibility_map)
+        Analyzer.new(
+          path: path,
+          context: context,
+          scope: scope,
+          zeitwerk: zeitwerk_resolver,
+          visibility_map: visibility_map
+        )
+      end
+
+      def zeitwerk_resolver
+        return @zeitwerk_resolver if defined?(@zeitwerk_resolver)
+
+        @zeitwerk_resolver =
+          if config["rails_zeitwerk"]
+            ZeitwerkResolver.new(
+              autoload_paths: config["autoload_paths"],
+              concern_dirs: config["concern_dirs"]
+            )
+          end
+      end
+
+      def edge_diagnostic(edge, node)
+        diagnostic(
+          node,
+          path: edge.path,
+          message: JSON.generate(edge.to_message_payload),
+          severity: :info,
+          rule: EDGE_RULE
+        )
+      end
+
+      def node_diagnostic(meta, ast_node)
+        diagnostic(
+          ast_node,
+          path: meta.path,
+          message: JSON.generate(meta.to_message_payload),
+          severity: :info,
+          rule: NODE_RULE
+        )
+      end
+    end
+
+    ::Rigor::Plugin.register(Plugin)
+  end
+end

data/lib/rigor/module_graph/plugin.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Lazy plugin entry point.
+#
+# This file is `require`d by `lib/rigor-module-graph.rb`, which itself
+# is `require`d two distinct ways:
+#
+# 1. From `Rigor::Plugin::Loader` when a host project's `.rigor.yml`
+#    lists `rigor-module-graph` under `plugins:` — the host gem has
+#    `rigortype` already loaded, so we want to subclass
+#    `Rigor::Plugin::Base` and register at require-time.
+# 2. From the `rigor-module-graph` CLI when the user only wants the
+#    converter subcommands (`dot`, `mermaid`, `cycles`) — `rigortype`
+#    may not be available and we must NOT crash.
+#
+# We detect which mode we're in and defer the Rigor wiring to the
+# concrete subclass file when appropriate.
+
+require_relative "edge"
+require_relative "analyzer"
+require_relative "constant_name"
+
+if defined?(Rigor::Plugin::Base)
+  require_relative "plugin/rigor_plugin"
+end