rigor-module-graph 0.1.1 → 0.1.3

data/lib/rigor/module_graph/cli.rb

@@ -16,7 +16,9 @@ require_relative "reachability"
 require_relative "stats"
 require_relative "packwerk_overlay"
 require_relative "html_view"
+require_relative "status_reporter"
 require_relative "uml/class_diagram"
+require_relative "viewer/html"
 
 module Rigor
   module ModuleGraph
@@ -255,6 +257,7 @@ module Rigor
             output: DEFAULT_EDGES_PATH,
             nodes_output: DEFAULT_NODES_PATH,
             cache: false,
+            quiet: false,
             rigor_cmd: ENV.fetch("RIGOR_CMD", "rigor")
           }
         end
@@ -263,11 +266,15 @@ module Rigor
           parser = build_parser
           paths = parser.parse(argv)
 
+          status = Rigor::ModuleGraph::StatusReporter.new(stderr: @stderr, quiet: @options[:quiet])
+
           ensure_output_dirs
           runner = RigorRunner.new(rigor_cmd: @options[:rigor_cmd], cache: @options[:cache])
-          edges, nodes = runner.analyse(paths)
-          write_edges(edges)
-          write_nodes(nodes)
+          edges, nodes = status.step(rigor_step_label(paths)) { runner.analyse(paths) }
+          status.info "#{edges.size} edge(s), #{nodes.size} node(s)"
+          status.step("Writing #{@options[:output]}") { write_edges(edges) }
+          status.step("Writing #{@options[:nodes_output]}") { write_nodes(nodes) }
+
           @stderr.puts "rigor-module-graph: wrote #{edges.size} edge(s) to #{@options[:output]}, " \
                        "#{nodes.size} node(s) to #{@options[:nodes_output]}"
           0
@@ -279,6 +286,13 @@ module Rigor
           1
         end
 
+        # Path-aware label so the user can see which paths Rigor
+        # is being pointed at when the step is slow.
+        def rigor_step_label(paths)
+          target = paths.empty? ? "configured paths" : paths.join(", ")
+          "Running rigor check on #{target}"
+        end
+
         def build_parser
           OptionParser.new do |opts|
             opts.banner = "Usage: rigor-module-graph collect [options] [PATHS...]"
@@ -298,6 +312,9 @@ module Rigor
                     "Override the rigor binary (default: rigor or $RIGOR_CMD)") do |cmd|
               @options[:rigor_cmd] = cmd
             end
+            opts.on("-q", "--quiet", "Suppress step-level progress on stderr") do
+              @options[:quiet] = true
+            end
             opts.on("-h", "--help") do
               @stdout.puts opts
               exit 0
@@ -349,9 +366,23 @@ module Rigor
         SUBTITLE_COLLAPSE_PREVIEW = 6
 
         # The supported output formats, in roughly increasing
-        # "wrapping" order: html embeds mermaid; svg embeds dot;
+        # "wrapping" order. `html` is the interactive Cytoscape
+        # viewer (vendored, self-contained); `mermaid-html` is
+        # the older static-Mermaid-via-CDN page kept for
+        # backwards compatibility; `svg` embeds the dot layout;
         # the rest are raw text.
-        FORMATS = %w[html mermaid dot svg class-diagram].freeze
+        FORMATS = %w[html mermaid-html mermaid dot svg class-diagram].freeze
+
+        # `--path-mode` controls how the click-through metadata
+        # `data.path` is reported on every node. See
+        # `Viewer::Html#path_for` for what each mode emits.
+        PATH_MODES = %i[relative absolute none].freeze
+
+        # `--open-with` flips the node-click action from
+        # clipboard copy to opening the file in an editor via
+        # a custom URL scheme. `vscode` is the only supported
+        # editor today.
+        OPEN_WITH = %i[vscode].freeze
 
         # Default file destination when format is html and the
         # user didn't override with -o. Non-html formats default to
@@ -365,6 +396,7 @@ module Rigor
             format: "html",
             output: nil,
             cache: false,
+            quiet: false,
             rigor_cmd: ENV.fetch("RIGOR_CMD", "rigor"),
             open: true,
             collapse: nil,
@@ -377,7 +409,9 @@ module Rigor
             package: nil,
             include_methods: true,
             include_attributes: true,
-            visibilities: %w[public protected private]
+            visibilities: %w[public protected private],
+            path_mode: :relative,
+            open_with: nil
           }
         end
 
@@ -385,22 +419,34 @@ module Rigor
           parser = build_parser
           paths = parser.parse(argv)
 
+          status = Rigor::ModuleGraph::StatusReporter.new(stderr: @stderr, quiet: @options[:quiet])
+
           runner = RigorRunner.new(rigor_cmd: @options[:rigor_cmd], cache: @options[:cache])
-          edges, nodes = runner.analyse(paths)
-          edges = apply_filters(
-            edges,
-            kinds: @options[:kinds],
-            confidences: @options[:confidences],
-            from: @options[:from],
-            depth: @options[:depth],
-            direction: @options[:direction],
-            edge_scope: @options[:edge_scope]
-          )
+          edges, nodes = status.step(rigor_step_label(paths)) { runner.analyse(paths) }
+          status.info "#{edges.size} edge(s), #{nodes.size} node(s)"
+
+          if any_filter_active?
+            edges = status.step("Applying filters") do
+              apply_filters(
+                edges,
+                kinds: @options[:kinds],
+                confidences: @options[:confidences],
+                from: @options[:from],
+                depth: @options[:depth],
+                direction: @options[:direction],
+                edge_scope: @options[:edge_scope]
+              )
+            end
+            status.info "#{edges.size} edge(s) after filters"
+          end
+
           groups = package_groups(edges)
           collapse = groups ? [] : effective_collapse(edges)
 
-          payload, binary = render_payload(edges, nodes, collapse, groups)
-          deliver(payload, binary: binary, edges: edges)
+          payload, binary = status.step("Rendering #{@options[:format]}") do
+            render_payload(edges, nodes, collapse, groups)
+          end
+          deliver(payload, binary: binary, edges: edges, status: status)
           0
         rescue OptionParser::ParseError => e
           @stderr.puts "rigor-module-graph view: #{e.message}"
@@ -410,6 +456,20 @@ module Rigor
           1
         end
 
+        def rigor_step_label(paths)
+          target = paths.empty? ? "configured paths" : paths.join(", ")
+          "Running rigor check on #{target}"
+        end
+
+        def any_filter_active?
+          @options[:kinds] || @options[:confidences] ||
+            @options[:from] || @options[:depth]
+        end
+
+        def silent_status
+          Rigor::ModuleGraph::StatusReporter.new(stderr: @stderr, quiet: true)
+        end
+
         class RenderError < StandardError; end
 
         # Builds the rendered payload for the chosen format and
@@ -418,6 +478,16 @@ module Rigor
         def render_payload(edges, nodes, collapse, groups)
           case @options[:format]
           when "html"
+            html = Viewer::Html.render(
+              edges: edges,
+              nodes: restrict_nodes_to_edges(nodes, edges),
+              title: "rigor-module-graph: #{File.basename(Dir.pwd)}",
+              subtitle: render_subtitle(edges, collapse, groups),
+              path_mode: @options[:path_mode],
+              open_with: @options[:open_with]
+            )
+            [html, false]
+          when "mermaid-html"
             mermaid = Mermaid.render(edges, collapse: collapse, groups: groups)
             html = HtmlView.render(
               title: "rigor-module-graph: #{File.basename(Dir.pwd)}",
@@ -475,7 +545,10 @@ module Rigor
 
         # Writes the payload to the configured destination and
         # opens the browser when the html-default flow applies.
-        def deliver(payload, binary:, edges:)
+        # `status:` defaults to a silent reporter so the existing
+        # test surface (which exercises `deliver` directly) keeps
+        # working without threading a reporter through.
+        def deliver(payload, binary:, edges:, status: silent_status)
           destination = effective_output_path
           if destination.nil?
             if binary
@@ -485,12 +558,16 @@ module Rigor
             return
           end
 
-          dir = File.dirname(destination)
-          FileUtils.mkdir_p(dir) unless dir.empty? || dir == "."
-          mode = binary ? "wb" : "w"
-          File.open(destination, mode) { |io| io.write(payload) }
+          status.step("Writing #{destination}") do
+            dir = File.dirname(destination)
+            FileUtils.mkdir_p(dir) unless dir.empty? || dir == "."
+            mode = binary ? "wb" : "w"
+            File.open(destination, mode) { |io| io.write(payload) }
+          end
           @stderr.puts "rigor-module-graph: wrote #{edges.size} edge(s) to #{destination}"
-          open_in_browser(destination) if html? && @options[:open]
+          return unless html? && @options[:open]
+
+          status.step("Opening #{destination} in browser") { open_in_browser(destination) }
         end
 
         # Resolve the output path. `-o PATH` always wins. With no
@@ -504,7 +581,7 @@ module Rigor
         end
 
         def html?
-          @options[:format] == "html"
+          %w[html mermaid-html].include?(@options[:format])
         end
 
         def build_parser
@@ -563,6 +640,10 @@ module Rigor
                     "Override the rigor binary (default: rigor or $RIGOR_CMD)") do |cmd|
               @options[:rigor_cmd] = cmd
             end
+            opts.on("-q", "--quiet", "Suppress step-level progress on stderr") do
+              @options[:quiet] = true
+            end
+            add_viewer_options(opts)
             add_filter_options(opts, @options)
             opts.on("-h", "--help") do
               @stdout.puts opts
@@ -571,6 +652,22 @@ module Rigor
           end
         end
 
+        def add_viewer_options(opts)
+          opts.on("--path-mode MODE", PATH_MODES,
+                  "How to report node paths in the html viewer: " \
+                  "#{PATH_MODES.join(" / ")} (default: relative). " \
+                  "`none` strips path metadata entirely — useful when " \
+                  "sharing the html artefact outside the project.") do |mode|
+            @options[:path_mode] = mode
+          end
+          opts.on("--open-with EDITOR", OPEN_WITH,
+                  "Make node clicks open the file in EDITOR instead of " \
+                  "copying path:line to the clipboard. " \
+                  "Supported: #{OPEN_WITH.join(" / ")}.") do |editor|
+            @options[:open_with] = editor
+          end
+        end
+
         # Choose collapse prefixes. Explicit `--collapse` wins;
         # otherwise we auto-pick top-level namespaces that have at
         # least AUTO_COLLAPSE_THRESHOLD distinct nodes under them,

data/lib/rigor/module_graph/status_reporter.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Rigor
+  module ModuleGraph
+    # Step-level progress reporter that prints to stderr.
+    #
+    # On a TTY the message + elapsed time render inline on a
+    # single line ("==> Running rigor check... done (4.32s)").
+    # When stderr is redirected (CI logs, piping into another
+    # command, `tee` to a file) both halves print on separate
+    # lines so the output stays line-oriented and grep-friendly.
+    #
+    # `quiet: true` silences every method; callers can wire a
+    # `--quiet` CLI flag through without litterring conditionals
+    # at each call site.
+    #
+    # Usage:
+    #
+    #   status = StatusReporter.new(stderr: $stderr)
+    #   edges = status.step("Running rigor check") do
+    #     runner.edges_for(paths)
+    #   end
+    #   status.info "#{edges.size} edges"
+    class StatusReporter
+      def initialize(stderr:, quiet: false)
+        @stderr = stderr
+        @quiet = quiet
+        @tty = stderr.respond_to?(:tty?) && stderr.tty?
+      end
+
+      # Print a "==> message..." line, yield, then print the
+      # outcome ("done (Xms)" or "failed") with elapsed time.
+      # Returns whatever the block returns; re-raises on
+      # exception after printing the failure tail so callers can
+      # still rescue normally.
+      def step(message)
+        return yield if @quiet
+
+        start_step(message)
+        started_at = monotonic
+        begin
+          result = yield
+        rescue StandardError
+          finish_step("failed", monotonic - started_at)
+          raise
+        end
+        finish_step("done", monotonic - started_at)
+        result
+      end
+
+      # Print an informational line indented under the most
+      # recent step. Used for "2016 edges, 87 nodes" style
+      # post-step counts.
+      def info(message)
+        return if @quiet
+
+        @stderr.puts "    #{message}"
+      end
+
+      private
+
+      def start_step(message)
+        prefix = "==> #{message}"
+        if @tty
+          @stderr.print "#{prefix}... "
+          @stderr.flush
+        else
+          @stderr.puts prefix
+        end
+      end
+
+      def finish_step(verb, elapsed)
+        duration = format_duration(elapsed)
+        if @tty
+          @stderr.puts "#{verb} #{duration}"
+        else
+          @stderr.puts "    #{verb} #{duration}"
+        end
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def format_duration(seconds)
+        if seconds < 1
+          "(#{(seconds * 1000).round}ms)"
+        else
+          "(#{seconds.round(2)}s)"
+        end
+      end
+    end
+  end
+end

data/lib/rigor/module_graph/templates/vendor/CHECKSUMS

@@ -0,0 +1,59 @@
+# Vendored third-party assets — sha256 manifest.
+#
+# This file is the local integrity gate: `rake vendor:verify`
+# re-computes sha256 for every row below and aborts on
+# mismatch. Pre-commit and CI both run it. Per-file
+# provenance (upstream URLs, npm `dist.integrity`, license,
+# release date) lives next door in `MANIFEST.yml`; the audit
+# task reads that.
+#
+# What this catches: bytes on disk no longer matching what we
+# committed.
+# What this does NOT catch on its own: bytes that were
+# silently wrong at commit time (TOFU). For that, the bump
+# SOP below requires `rake vendor:audit`, which cross-checks
+# against four independent sources (npm tarball + npm
+# `dist.integrity` + GitHub raw + every CDN listed in
+# MANIFEST).
+#
+# ---
+# Bumping a vendored asset (SOP):
+#
+#   1. Edit `MANIFEST.yml`: bump `release_tag`, `release_date`,
+#      `npm.version`, `tarball_url`, `github_raw_url`, and
+#      each CDN URL to the new version.
+#   2. Look up the new `npm.integrity` from
+#      `https://registry.npmjs.org/<package>/<version>`
+#      (`dist.integrity` field) and paste it into
+#      `MANIFEST.yml`.
+#   3. Download the new asset locally; replace the file under
+#      `vendor/`.
+#   4. `shasum -a 256 vendor/<filename>` → update the sha256
+#      row in this file.
+#   5. `bundle exec rake vendor:audit` — this fetches the new
+#      version from npm + GitHub + every CDN and asserts they
+#      all agree with the recorded sha256, and that the npm
+#      tarball's sha512 matches the recorded `dist.integrity`.
+#      Any mismatch means at least one source disagrees — do
+#      NOT proceed.
+#   6. Update `last_audited:` in `MANIFEST.yml` to today's date.
+#   7. Open a manual PR. Reviewer checks:
+#      - the diff touches only `vendor/<filename>`,
+#        `CHECKSUMS`, and `MANIFEST.yml`
+#      - release tag / date / license / source URLs match the
+#        new version
+#      - CI `vendor:verify` step passes
+#      - the audit step output was attached to the PR (paste
+#        `rake vendor:audit` output into the PR description)
+#      - `npm audit signatures cytoscape@<new>` clean (when
+#        npm CLI is available locally)
+#
+# Format: sha256 (64 hex chars)  two spaces  filename
+# Lines starting with `#` and blank lines are ignored.
+#
+# ---
+# cytoscape.min.js
+#   See MANIFEST.yml for the full provenance.
+#   release:  v3.34.0 (2026-06-02), MIT
+#   npm:      cytoscape@3.34.0
+9c2a3bf2592e0b14a1f7bec07c03a54f16dedf32af9cd0af155c716aa6c87bc3  cytoscape.min.js