rigor-module-graph 0.1.0

data/lib/rigor/module_graph/constant_name.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module ModuleGraph
+    # Resolves a fully-qualified constant name from Prism AST nodes
+    # and lexical ancestor chains.
+    #
+    # Three things this module handles that the bare Prism API does
+    # not give you in one place:
+    #
+    # - Owner from lexical nesting. `node.constant_path.full_name`
+    #   on a `class Billing::Invoice` only returns `"Invoice"`; the
+    #   outer `module Billing` does not enter unless we walk
+    #   ancestors ourselves.
+    # - Absolute paths (`::Foo::Bar`). Prism encodes the leading
+    #   `::` as an empty-symbol `:""` in `full_name_parts`; we
+    #   render it as `"::Foo::Bar"`.
+    # - Mixed AST shapes. `ClassNode#constant_path` is either a
+    #   `ConstantReadNode` (single name) or a `ConstantPathNode`
+    #   (dotted path); same for `superclass` and `include` args.
+    module ConstantName
+      module_function
+
+      # Render a single Prism constant node into a string like
+      # `"Foo"`, `"Foo::Bar"`, or `"::Foo::Bar"`. Returns nil when
+      # the node is not a constant carrier (e.g. `include SOME_VAR`
+      # where the arg is a `CallNode`).
+      def render(node)
+        case node
+        when Prism::ConstantReadNode
+          node.name.to_s
+        when Prism::ConstantPathNode
+          full_name_for_path(node)
+        end
+      end
+
+      # Build the lexical-nesting owner string for a node, by
+      # walking `context.ancestors` from outer to inner and joining
+      # every enclosing `ClassNode`/`ModuleNode` constant path with
+      # `::`. Returns nil when no class/module encloses the node.
+      def lexical_owner(context)
+        parts = lexical_parts(context.ancestors)
+        return nil if parts.empty?
+
+        parts.join("::")
+      end
+
+      # Same as `#lexical_owner`, but with `extra` appended as the
+      # innermost element. Used to build the owner of a class or
+      # module decl itself: pass `context.ancestors` (which does NOT
+      # include the node itself) plus the node's own constant path.
+      def lexical_owner_with(context, extra)
+        parts = lexical_parts(context.ancestors)
+        parts << extra unless extra.nil? || extra.empty?
+        return nil if parts.empty?
+
+        parts.join("::")
+      end
+
+      def lexical_parts(ancestors)
+        ancestors.flat_map do |ancestor|
+          case ancestor
+          when Prism::ClassNode, Prism::ModuleNode
+            name = render(ancestor.constant_path)
+            name ? [name] : []
+          else
+            []
+          end
+        end
+      end
+
+      def full_name_for_path(node)
+        parts = node.full_name_parts
+        # Prism encodes a leading `::` as an empty-symbol first
+        # part. Render it as a literal `"::"` prefix.
+        if parts.first == :""
+          "::" + parts.drop(1).join("::")
+        else
+          parts.join("::")
+        end
+      end
+    end
+  end
+end

data/lib/rigor/module_graph/cycle_detector.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Rigor
+  module ModuleGraph
+    # Finds dependency cycles in an Edge list.
+    #
+    # Tarjan's strongly-connected-components, sized ≥ 2 (a SCC of
+    # 1 is a single node with no self-loop and represents no cycle).
+    # We also surface single-node self-loops if any edge points a
+    # constant at itself.
+    #
+    # Returns an array of Cycle, where each Cycle carries the list
+    # of node names in the cycle in a canonical rotation: smallest
+    # name first. The actual edge instances making up each cycle
+    # are not surfaced — for visualisation we only need the node
+    # set — but a kind filter is offered so callers can ask "do
+    # these edges form a cycle using only `include` / `inherits`?"
+    module CycleDetector
+      module_function
+
+      # One detected cycle, expressed as the list of node names
+      # along it. Always rotated so the lexicographically smallest
+      # name comes first, so the rendered output is stable across
+      # runs.
+      class Cycle < Data.define(:nodes)
+        # Render the cycle as +A -> B -> C -> A+ (note the closing
+        # repeat of the first node so the round-trip is obvious).
+        def to_s
+          nodes.join(" -> ") + " -> " + nodes.first
+        end
+      end
+
+      # @param edges [Array<Edge>]
+      # @param kinds [Array<String>, nil] when given, only edges
+      #   whose `kind` is in the list participate in cycle detection.
+      def detect(edges, kinds: nil)
+        graph = build_adjacency(edges, kinds)
+        sccs = tarjan(graph)
+        cycles = sccs.select { |scc| scc.size >= 2 }.map { |scc| canonicalize(scc, graph) }
+        self_loops = collect_self_loops(graph)
+        (cycles + self_loops).sort_by { |c| c.nodes.first }
+      end
+
+      def build_adjacency(edges, kinds)
+        graph = Hash.new { |h, k| h[k] = [] }
+        edges.each do |edge|
+          next if kinds && !kinds.include?(edge.kind)
+
+          graph[edge.from] << edge.to
+          graph[edge.to] # ensure target appears even with no outgoing edges
+        end
+        graph.each_value(&:uniq!)
+        graph
+      end
+
+      # Iterative Tarjan to avoid blowing the Ruby stack on a wide
+      # graph. Returns SCCs as arrays of node names.
+      def tarjan(graph)
+        index = 0
+        indices = {}
+        lowlink = {}
+        on_stack = {}
+        stack = []
+        sccs = []
+
+        graph.each_key do |start|
+          next if indices.key?(start)
+
+          work = [[start, 0]]
+          indices[start] = index
+          lowlink[start] = index
+          index += 1
+          stack.push(start)
+          on_stack[start] = true
+
+          until work.empty?
+            node, i = work.last
+            neighbours = graph[node]
+            if i < neighbours.size
+              work[-1] = [node, i + 1]
+              succ = neighbours[i]
+              if !indices.key?(succ)
+                indices[succ] = index
+                lowlink[succ] = index
+                index += 1
+                stack.push(succ)
+                on_stack[succ] = true
+                work.push([succ, 0])
+              elsif on_stack[succ]
+                lowlink[node] = [lowlink[node], indices[succ]].min
+              end
+            else
+              if lowlink[node] == indices[node]
+                scc = []
+                loop do
+                  w = stack.pop
+                  on_stack.delete(w)
+                  scc << w
+                  break if w == node
+                end
+                sccs << scc
+              end
+              work.pop
+              parent = work.last&.first
+              lowlink[parent] = [lowlink[parent], lowlink[node]].min if parent
+            end
+          end
+        end
+        sccs
+      end
+
+      def canonicalize(scc, graph)
+        nodes = walk_cycle(scc, graph)
+        nodes = rotate_to_smallest(nodes)
+        Cycle.new(nodes: nodes)
+      end
+
+      # Walk a single trip around the SCC starting from its
+      # smallest-named node, following outgoing edges that stay
+      # in the SCC. Falls back to sorted membership if the cycle
+      # is degenerate (should not happen for a real SCC ≥ 2).
+      def walk_cycle(scc, graph)
+        set = scc.to_set
+        start = scc.min
+        path = [start]
+        current = start
+        loop do
+          next_node = graph[current].find { |n| set.include?(n) && !path.include?(n) }
+          break unless next_node
+
+          path << next_node
+          current = next_node
+        end
+        # If we couldn't visit everyone (rare: SCC with parallel
+        # branches), fall back to sorted order so output stays
+        # deterministic.
+        path.size == scc.size ? path : scc.sort
+      end
+
+      def rotate_to_smallest(nodes)
+        i = nodes.each_with_index.min_by { |name, _| name }[1]
+        nodes.rotate(i)
+      end
+
+      def collect_self_loops(graph)
+        graph.each_with_object([]) do |(node, targets), acc|
+          acc << Cycle.new(nodes: [node]) if targets.include?(node)
+        end
+      end
+    end
+  end
+end

data/lib/rigor/module_graph/dot.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Rigor
+  module ModuleGraph
+    # Renders an array of Edges as a Graphviz DOT document.
+    #
+    # Style decisions (per docs/plan.md "グラフモデル"):
+    # - rankdir=LR for readability of inheritance towers
+    # - inherits: thick solid
+    # - include: solid
+    # - prepend: solid, distinct color
+    # - extend: dashed
+    # - const_ref: faded dotted
+    #
+    # When `collapse:` is given, every node whose fully-qualified
+    # name sits under one of the listed prefixes is wrapped in a
+    # `subgraph cluster_<prefix>` block, and the prefix is stripped
+    # from the visible label. Edges across clusters render normally;
+    # Graphviz routes them between the cluster boundaries.
+    module Dot
+      module_function
+
+      KIND_STYLE = {
+        "inherits" => 'color="#0f172a", penwidth=2.0',
+        "include" => 'color="#1d4ed8"',
+        "prepend" => 'color="#9333ea"',
+        "extend" => 'color="#0f766e", style="dashed"',
+        "const_ref" => 'color="#94a3b8", style="dotted"'
+      }.freeze
+
+      CONFIDENCE_STYLE = {
+        "unresolved" => 'style="dashed", color="#94a3b8"'
+      }.freeze
+
+      HEADER = <<~DOT
+        digraph ruby_modules {
+          rankdir=LR;
+          graph [compound=true, overlap=false, splines=true];
+          node [shape=box, style="rounded,filled", fillcolor="#f8fafc", color="#94a3b8", fontname="Helvetica"];
+          edge [color="#64748b", arrowsize=0.7, fontname="Helvetica"];
+      DOT
+
+      # @param edges [Array<Edge>]
+      # @param collapse [Array<String>] namespace prefixes to
+      #   fold into clusters (mutually exclusive with +groups+)
+      # @param groups [Hash{String=>String}, nil] explicit
+      #   +{node_name => cluster_label}+ mapping. Takes precedence
+      #   over +collapse+ when given. Used by the +--package+
+      #   overlay where the cluster boundary is something other
+      #   than a +::+ namespace prefix.
+      def render(edges, collapse: [], groups: nil)
+        edges = dedup(edges)
+        nodes = collect_nodes(edges)
+        clusters, ungrouped = build_groups(nodes, collapse, groups)
+
+        out = +HEADER
+        clusters.each do |label, members|
+          out << render_cluster(label, members, use_namespace_prefix: groups.nil?)
+        end
+        ungrouped.each do |name|
+          out << "  #{quote(name)};\n"
+        end
+        out << "\n" unless nodes.empty?
+        edges.each do |edge|
+          out << render_edge(edge)
+        end
+        out << "}\n"
+      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 collect_nodes(edges)
+        names = edges.flat_map { |edge| [edge.from, edge.to] }
+        names.uniq.sort
+      end
+
+      # Build the cluster partition. When +groups+ is given we
+      # use it verbatim; otherwise fall back to prefix-matching
+      # against +collapse+ (the legacy namespace-collapse path).
+      def build_groups(nodes, collapse, groups)
+        if groups && !groups.empty?
+          clusters = Hash.new { |h, k| h[k] = [] }
+          ungrouped = []
+          nodes.each do |name|
+            if (label = groups[name])
+              clusters[label] << name
+            else
+              ungrouped << name
+            end
+          end
+          [clusters, ungrouped]
+        else
+          group_by_prefix(nodes, collapse)
+        end
+      end
+
+      def group_by_prefix(nodes, collapse)
+        prefixes = Array(collapse).map(&:to_s).reject(&:empty?)
+        return [{}, nodes] if prefixes.empty?
+
+        sorted = prefixes.sort_by { |p| -p.length }
+        clusters = Hash.new { |h, k| h[k] = [] }
+        ungrouped = []
+        nodes.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, use_namespace_prefix: true)
+        out = +"  subgraph #{quote("cluster_" + cluster_id(label))} {\n"
+        out << "    label=#{quote(label)};\n"
+        out << "    style=\"rounded,filled\";\n"
+        out << "    color=\"#cbd5e1\";\n"
+        out << "    fillcolor=\"#f1f5f9\";\n"
+        members.each do |name|
+          short = use_namespace_prefix ? name.sub(/\A#{Regexp.escape(label)}::/, "") : name
+          out << "    #{quote(name)} [label=#{quote(short)}];\n"
+        end
+        out << "  }\n"
+      end
+
+      # Cluster identifiers in DOT must match `[A-Za-z_][A-Za-z0-9_]*`
+      # — package names like `packages/billing` would otherwise
+      # break Graphviz's parser even inside quotes. Squash every
+      # non-id character to `_` so the prefix `cluster_` still
+      # triggers Graphviz's cluster handling.
+      def cluster_id(prefix)
+        prefix.gsub(/[^A-Za-z0-9_]+/, "_")
+      end
+
+      def render_edge(edge)
+        attrs = +"label=\"#{edge.kind}\""
+        if (style = KIND_STYLE[edge.kind])
+          attrs << ", " << style
+        end
+        if (style = CONFIDENCE_STYLE[edge.confidence])
+          attrs << ", " << style
+        end
+        "  #{quote(edge.from)} -> #{quote(edge.to)} [#{attrs}];\n"
+      end
+
+      def quote(name)
+        # DOT identifiers that contain `::` or quotes must be
+        # double-quoted; escape embedded double quotes.
+        '"' + name.gsub('"', '\"') + '"'
+      end
+    end
+  end
+end

data/lib/rigor/module_graph/edge.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rigor
+  module ModuleGraph
+    # The list of valid +kind+ values for an Edge.
+    EDGE_KINDS = %w[
+      inherits
+      include
+      prepend
+      extend
+      const_ref
+      has_many
+      belongs_to
+      has_one
+      has_and_belongs_to_many
+    ].freeze
+
+    # Subset of EDGE_KINDS that represent Rails ActiveRecord
+    # associations. Used by the class diagram renderer to attach
+    # cardinality labels, and by callers that want to filter the
+    # set as a group.
+    ASSOCIATION_KINDS = %w[has_many belongs_to has_one has_and_belongs_to_many].freeze
+
+    # The structural / mixin kinds — the "first class" relations
+    # of a typical dependency graph. const_ref and associations
+    # sit outside this set.
+    STRUCTURAL_KINDS = %w[inherits include prepend extend].freeze
+
+    # The list of valid +confidence+ values for an Edge.
+    EDGE_CONFIDENCES = %w[syntax zeitwerk rigor_type unresolved].freeze
+
+    # A single dependency edge between two constants.
+    #
+    # Carries the dependency itself (+from+, +to+, +kind+,
+    # +confidence+), the source position it was extracted from
+    # (+path+, +line+, +column+), and the raw source slice (+raw+)
+    # when the resolution went through a fallback path. Edge is a
+    # +Data+ subclass — every instance is immutable.
+    #
+    # == Two serialisation shapes
+    #
+    # +to_message_payload+::
+    #   What the plugin embeds in a diagnostic's +message+ field.
+    #   The collector reconstructs an Edge from this payload plus
+    #   the diagnostic's own +path+/+line+/+column+, so the payload
+    #   omits position to keep the message compact.
+    # +to_h+::
+    #   What the JSONL writer dumps to disk. Full row, with
+    #   +path+/+line+/+column+ included.
+    #
+    # == Dedup key
+    #
+    # +dedup_key+ ignores +path+ and +line+ so the same logical
+    # edge declared in two files (or surfaced by two re-runs of
+    # +rigor check+) collapses to one row.
+    # The +dedup_key+ member at the end is internal: it's the
+    # cached +"\\x00"+-joined key string the renderers' dedup
+    # loops use for Hash lookups. Storing it on the value pays
+    # for itself once a few hundred edges flow through any
+    # rendering / IO path.
+    class Edge < Data.define(:from, :to, :kind, :path, :line, :column, :confidence, :raw, :dedup_key)
+      # Same as Rigor::ModuleGraph::EDGE_KINDS; exposed on the
+      # class so callers can write +Edge::KINDS+.
+      KINDS = EDGE_KINDS
+
+      # Same as Rigor::ModuleGraph::EDGE_CONFIDENCES; exposed on
+      # the class so callers can write +Edge::CONFIDENCES+.
+      CONFIDENCES = EDGE_CONFIDENCES
+
+      # Build an Edge, validating +kind+ and +confidence+ against
+      # the canonical lists and frozen-stringifying +from+ / +to+.
+      # Raises +ArgumentError+ on unknown values.
+      def self.build(from:, to:, kind:, path: nil, line: nil, column: nil, confidence: "syntax", raw: nil)
+        from = from.to_s.freeze
+        to = to.to_s.freeze
+        kind = validate_kind!(kind)
+        confidence = validate_confidence!(confidence)
+        new(
+          from: from,
+          to: to,
+          kind: kind,
+          path: path,
+          line: line,
+          column: column,
+          confidence: confidence,
+          raw: raw,
+          dedup_key: -"#{from}\x00#{to}\x00#{kind}\x00#{confidence}"
+        )
+      end
+
+      def self.validate_kind!(kind) # :nodoc:
+        kind = kind.to_s
+        return kind if KINDS.include?(kind)
+
+        raise ArgumentError, "unknown edge kind #{kind.inspect}; expected one of #{KINDS.inspect}"
+      end
+
+      def self.validate_confidence!(confidence) # :nodoc:
+        confidence = confidence.to_s
+        return confidence if CONFIDENCES.include?(confidence)
+
+        raise ArgumentError, "unknown confidence #{confidence.inspect}; expected one of #{CONFIDENCES.inspect}"
+      end
+
+      # The on-disk JSONL row. Nil-valued positional fields are
+      # omitted so a stand-alone edge (e.g. constructed in a test
+      # without a path) does not leak +"path":null+ noise.
+      def to_h
+        h = { "from" => from, "to" => to, "kind" => kind }
+        h["path"] = path if path
+        h["line"] = line if line
+        h["column"] = column if column
+        h["confidence"] = confidence
+        h["raw"] = raw if raw
+        h
+      end
+
+      # The payload embedded in a +:info+ diagnostic's message.
+      # Position is intentionally absent — the diagnostic carries
+      # its own +path+/+line+/+column+, so duplicating them here
+      # would just bloat output.
+      def to_message_payload
+        h = { "from" => from, "to" => to, "kind" => kind, "confidence" => confidence }
+        h["raw"] = raw if raw
+        h
+      end
+
+      def to_json(*args)
+        JSON.generate(to_h, *args)
+      end
+
+      # +dedup_key+ is a generated Data accessor; no override
+      # needed. See the class header for the rationale.
+    end
+
+    # JSONL reader / writer for Edge rows. Used by the plugin
+    # collector and the +rigor-module-graph+ renderer subcommands.
+    module EdgeIO
+      module_function
+
+      # Stream +edges+ to +io+ as JSONL, deduping by Edge#dedup_key
+      # so re-runs don't accumulate duplicate rows.
+      def write(edges, io)
+        seen = {}
+        edges.each do |edge|
+          key = edge.dedup_key
+          next if seen[key]
+
+          seen[key] = true
+          io.puts(JSON.generate(edge.to_h))
+        end
+      end
+
+      # Parse JSONL from +io+ into Edge instances. Blank lines are
+      # skipped. Missing +confidence+ defaults to +"syntax"+ so the
+      # format stays backwards-compatible with earlier outputs.
+      def read(io)
+        edges = []
+        io.each_line do |line|
+          line = line.strip
+          next if line.empty?
+
+          row = JSON.parse(line)
+          edges << Edge.build(
+            from: row.fetch("from"),
+            to: row.fetch("to"),
+            kind: row.fetch("kind"),
+            path: row["path"],
+            line: row["line"],
+            column: row["column"],
+            confidence: row.fetch("confidence", "syntax"),
+            raw: row["raw"]
+          )
+        end
+        edges
+      end
+    end
+  end
+end

data/lib/rigor/module_graph/html_view.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Rigor
+  module ModuleGraph
+    # Self-contained HTML document that embeds Mermaid output
+    # inline so it renders without any local server (works over
+    # +file://+, no fetch).
+    #
+    # The view loads +mermaid@10+ from a CDN at render time. The
+    # only network access is that one CDN URL; if a project needs
+    # to ship a fully offline page, render the SVG via Graphviz
+    # and embed that instead.
+    #
+    # The HTML body lives in
+    # +lib/rigor/module_graph/templates/view.html.erb+; bumping
+    # styling or Mermaid init options is an edit of that file
+    # alone.
+    module HtmlView
+      module_function
+
+      TEMPLATE_PATH = File.expand_path("templates/view.html.erb", __dir__)
+
+      # @param title [String] page <title> and <h1> text
+      # @param mermaid_source [String] the mermaid flowchart body
+      # @param subtitle [String, nil] one-line caption under the H1
+      # @return [String] the rendered HTML document
+      def render(title:, mermaid_source:, subtitle: nil)
+        indented = mermaid_source.strip.gsub("\n", "\n  ")
+        template.result_with_hash(
+          title: title,
+          subtitle: subtitle,
+          indented_mermaid: indented
+        )
+      end
+
+      def template
+        @template ||= ERB.new(File.read(TEMPLATE_PATH), trim_mode: "-")
+      end
+    end
+  end
+end

data/lib/rigor/module_graph/inflector.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Rigor
+  module ModuleGraph
+    # Minimal Rails-style inflection helpers. Used to infer a class
+    # name from a Rails association argument (+has_many :invoices+
+    # → +Invoice+).
+    #
+    # Deliberately tiny — we don't ship +ActiveSupport::Inflector+
+    # and its irregular-noun table; the plugin records its guess
+    # at +confidence: "syntax"+ so a downstream reviewer can spot
+    # mis-singularised plurals in the graph. Apps that need exact
+    # association class names should rely on +class_name:+ overrides
+    # in the source, which the Analyzer reads verbatim.
+    module Inflector
+      module_function
+
+      IRREGULAR_PLURALS = {
+        "people" => "person",
+        "men" => "man",
+        "women" => "woman",
+        "children" => "child",
+        "feet" => "foot",
+        "teeth" => "tooth",
+        "geese" => "goose",
+        "mice" => "mouse",
+        "lice" => "louse"
+      }.freeze
+
+      # @param word [String]
+      # @return [String] best-effort singular form
+      def singularize(word)
+        downcased = word.downcase
+        return word.dup if word.empty?
+        return preserve_case(IRREGULAR_PLURALS[downcased], word) if IRREGULAR_PLURALS.key?(downcased)
+        return word[0..-4] + "y" if word =~ /ies\z/i && word.size > 3
+        return word[0..-3] if word =~ /ses\z/i # buses → bus, classes → clas... we accept loss
+        return word[0..-2] if word.end_with?("s") && !word.end_with?("ss")
+
+        word.dup
+      end
+
+      # +"foo_bar_baz" → "FooBarBaz"+. Plain Rails camelize without
+      # acronym handling.
+      def camelize(word)
+        word.to_s.split("_").map { |seg| seg.empty? ? seg : seg[0].upcase + seg[1..] }.join
+      end
+
+      # +"invoices" → "Invoice"+ — the common Rails association
+      # argument to class-name path.
+      def class_name_for(symbol_or_string)
+        camelize(singularize(symbol_or_string.to_s))
+      end
+
+      def preserve_case(replacement, original)
+        # The irregular table is lower-case; preserve a leading
+        # capital from the source so +People+ → +Person+.
+        return replacement.capitalize if original[0] =~ /[A-Z]/
+
+        replacement.dup
+      end
+    end
+  end
+end