rigor-module-graph 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b9be2e8029422795b2b8b9e8f13998f6aefc16923e11e166f7692910637eb81
-  data.tar.gz: a723c08c549cb5368166de5971712f12d1cd5d06c142d176d842b43bd9ec6816
+  metadata.gz: cea3ca68d705ecbe0f3534c5b3374e7e1dfd0f01edb6a0b9e64ed4c775cb166d
+  data.tar.gz: 70d09cd49d66f118948f2ec142d4f7a6c068a6ce098cddf97b3dd7d997a507d9
 SHA512:
-  metadata.gz: e0ea19766f2fa753a0b41fe6dd7eb9b7840b3ce70ca10a8b1b153e2d04633f7cb0a04d1b24f6481104b038ab240e6d26fa56d6a4a990f404e565ce0ddfa21cdf
-  data.tar.gz: 82153c88b36de25bad1250d5f33c10b88d4a7c049d17112c750e4cf2596739407429f730048543e9c2bc7d0fe3551d877d6c6ee5275df780dceb4f1415742304
+  metadata.gz: 5fec0afc7142600d308187afb293484818e545e63d5e21c08221412e0bcbca98db5cbf6e1e30c3b45ad46a30459779dcfe816459b9009494c5fbd4d0265a0dea
+  data.tar.gz: 1795a811ff1b184945dc55fb6a5451d09f895b85b778d1d98145f5fae2ad5f5aa0822dbafed51fad143ae3c32a8b75a5f3beec55cefdd3e9164658aa6e25e019

data/CHANGELOG.md

@@ -17,6 +17,65 @@ Categories:
 
 ## [Unreleased]
 
+## [0.1.2] — 2026-06-20
+
+First release that exercises the full automated pipeline end
+to end — Trusted Publishing + GitHub Release + asset upload
+all drive off a single `gh workflow run release.yml` after the
+tag is pushed.
+
+### Added
+
+- `view` and `collect` now emit step-level progress on stderr:
+  `==> Running rigor check ...`, post-step counts (`18 edge(s),
+  16 node(s)`), and inline elapsed time (`done (428ms)`).
+  TTY-aware — the start / done halves render inline on a
+  terminal, on separate lines for redirected output, so logs
+  stay grep-friendly. `-q` / `--quiet` suppresses the progress
+  output for scripted use; the final `wrote N edge(s) to ...`
+  summary line stays. Driven by a new `StatusReporter` class
+  pinned by `test/rigor/module_graph/status_reporter_test.rb`.
+
+### Changed
+
+- README restructured along the install → getting started →
+  usage → configuration flow. The "How it works" walkthrough
+  (pipeline diagram + the "not a call graph" framing) moves to
+  `docs/how-it-works.md` so the README stays focused on
+  "what do I type". Configuration section now notes that
+  `.rigor.yml` is required (rigor reads it to discover the
+  plugin), with a two-line minimum example up top and the
+  fully-elaborated default form below.
+
+### Fixed
+
+- RDoc generation now parses Markdown instead of RDoc syntax,
+  so `![alt](path)` images in `README.md` / `CHANGELOG.md` /
+  `docs/*.md` actually render. `Rake::Task[:rdoc]` is enhanced
+  to copy `examples/billing/graph.svg` (and any future
+  `RDOC_ASSET_PATHS` entries) into `doc/` so the generated site
+  resolves the relative image references the README uses.
+
+## [0.1.1] — 2026-06-20
+
+First Action-driven publish. The 0.1.0 release happened via the
+CLI fallback before the rubygems.org Trusted Publisher
+registration was in place; 0.1.1 is the first version to land
+through `release.yml`.
+
+The user-visible code surface is intentionally tiny: the major
+correctness fix (namespaced association resolution), the
+Stats / Reachability / Edge perf rewrites, the SHA-pinned
+workflows, the docs split, and the MIT `LICENSE.txt` all
+already shipped in 0.1.0.
+
+### Changed
+
+- `--version` / `-v` / `version` now prints
+  `rigor-module-graph X.Y.Z` instead of a bare `X.Y.Z`.
+  Matches the convention `bundler --version` and `gh --version`
+  use; bug reports pasted into chat are self-identifying.
+
 ## [0.1.0] — 2026-06-20
 
 Initial release. Baseline shipping everything from the Phase 0
@@ -114,5 +173,7 @@ spike through Phase 5 (UML class diagram).
   baseline and YJIT, and trailed baseline on Stats and
   CycleDetector — recommendation stays YJIT.
 
-[Unreleased]: https://github.com/nozomemein/rigor-module-graph/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/nozomemein/rigor-module-graph/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/nozomemein/rigor-module-graph/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/nozomemein/rigor-module-graph/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/nozomemein/rigor-module-graph/releases/tag/v0.1.0

data/README.md

@@ -1,5 +1,10 @@
 # rigor-module-graph
 
+[![Gem Version](https://img.shields.io/gem/v/rigor-module-graph.svg)](https://rubygems.org/gems/rigor-module-graph)
+[![License: MIT](https://img.shields.io/github/license/nozomemein/rigor-module-graph.svg)](LICENSE.txt)
+[![CI](https://github.com/nozomemein/rigor-module-graph/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/nozomemein/rigor-module-graph/actions/workflows/ci.yml)
+[![Docs](https://github.com/nozomemein/rigor-module-graph/actions/workflows/docs.yml/badge.svg?branch=main)](https://github.com/nozomemein/rigor-module-graph/actions/workflows/docs.yml)
+
 Class/module/constant dependency graph for Ruby projects, built on
 [Rigor](https://rigor.typedduck.fail/). The class-level counterpart
 to Packwerk/Graphwerk: where those look at package boundaries, this
@@ -11,54 +16,7 @@ looks at the Ruby nominal graph — inheritance, `include`/`prepend`/
 The screenshot above is from `examples/billing/`. Open
 `examples/billing/index.html` for the live Mermaid version.
 
-## What this actually does
-
-In principle this is a static-analysis tool that turns Ruby source
-into a graph whose **nodes are classes / modules / constants** and
-whose **edges are the references the language itself spells out**.
-
-The pipeline:
-
-1. Rigor parses Ruby into an AST with Prism.
-2. The plugin's `node_rule`s pick up `ClassNode` / `CallNode` /
-   `ConstantReadNode` and friends.
-3. Each interesting node becomes one or more edges:
-   - `class A < B` → `A -> B / inherits`
-   - `include M` → `A -> M / include`
-   - a `Money` constant reference → `A -> Money / const_ref`
-     (Phase 2 and later)
-4. `from` is the lexical owner, assembled by walking
-   `context.ancestors` — so `class Billing::Invoice` produces
-   `Billing::Invoice`, not just `Invoice`.
-5. `to` is resolved through a confidence ladder: syntax →
-   Zeitwerk convention → Rigor type information. Whatever we
-   couldn't pin down stays visible in the `confidence` field
-   rather than being dropped.
-6. Every edge ships as a Rigor `:info` diagnostic. The `collect`
-   subcommand filters them on `rule == "edge"` and writes JSONL.
-7. DOT, SVG, Mermaid, and cycle detection are all derived from
-   that JSONL.
-
-So we are not watching what Ruby *does at runtime*. We're reading
-Ruby's *named structure* and reconstructing, approximately, "which
-constants depend on which other constants".
-
-### This is not a call graph
-
-We do not track who `foo.bar` resolves to at runtime. We track
-the fact that the `Billing::Invoice` name depends on the
-`ApplicationRecord` / `Auditable` / `Money` names. That is a
-**nominal dependency graph** — a compiler-front-end-style view
-of the project's syntactic and lexical structure, projected into
-edges with explicit confidence.
-
-Not re-implementing Ruby constant lookup is deliberate. For
-understanding a Rails codebase's shape, it's more useful to leave
-each edge tagged `syntax` / `zeitwerk` / `rigor_type` /
-`unresolved` than to fake a `resolved` answer and silently get it
-wrong.
-
-## Installation
+## Install
 
 Via Bundler:
 
@@ -71,65 +29,61 @@ gem "rigor-module-graph"
 bundle install
 ```
 
-Or globally:
+Or system-wide:
 
 ```sh
 gem install rigor-module-graph
 ```
 
-Both paths pull in `rigortype` and `rbs ~> 4.0` transitively. The
-`rbs ~> 4.0` constraint is the key one: rigortype 0.2.x calls
-`RBS::Environment::ClassEntry#each_decl`, which only exists in
-rbs 4.x. The Ruby 4.0 stdlib bundles rbs 3.10 as a default gem,
-so installing `rigor-module-graph` (which depends on rbs 4.x)
-makes RubyGems activate the 4.x gem at run time and the
-analyzer stays alive.
-
-## Configuration
+Both paths pull in `rigortype` and `rbs ~> 4.0` transitively.
+The `rbs ~> 4.0` constraint is the one that matters: rigortype
+0.2.x calls `RBS::Environment::ClassEntry#each_decl`, which
+only exists in rbs 4.x. The Ruby 4.0 stdlib bundles rbs 3.10
+as a default gem, so installing `rigor-module-graph` (which
+depends on rbs 4.x) makes RubyGems activate the 4.x gem at
+run time and the analyzer stays alive.
 
-Add the plugin to your project's `.rigor.yml`:
+For the full pipeline you also want `graphviz` installed so
+`view --output svg` and `dot -Tsvg` can render PNG / SVG from
+the generated DOT:
 
-```yaml
-target_ruby: '4.0'
-paths:
-  - app
-  - lib
-plugins:
-  - gem: rigor-module-graph
-    config:
-      rails_zeitwerk: true
-      autoload_paths:
-        - app/models
-        - app/controllers
-        - app/services
-        - app/jobs
-        - lib
-      concern_dirs:
-        - app/models/concerns
-        - app/controllers/concerns
-      include_constant_refs: false
+```sh
+brew install graphviz       # macOS
+apt-get install graphviz    # Debian / Ubuntu
 ```
 
-Every key shown is the default. Set `include_constant_refs: true`
-to emit `const_ref` edges from constant references inside method
-bodies. Set `rails_zeitwerk: false` to keep every edge at
-`confidence: "syntax"` and skip path-based owner inference.
+A working `dot` on `$PATH` is optional — text / Mermaid / HTML
+output paths don't need it. See [How it works](docs/how-it-works.md)
+for the pipeline overview.
 
-## Usage
-
-### One-shot: `view`
+## Getting started
 
-The default subcommand analyses the current directory, writes a
-self-contained Mermaid HTML report under `.rigor/module_graph/`,
-and opens it in your browser. No flags needed for a Rails-shaped
-project.
+The default subcommand analyses the current directory, writes
+a self-contained Mermaid HTML report under
+`.rigor/module_graph/`, and opens it in a browser:
 
 ```sh
 cd path/to/your/project
 bundle exec rigor-module-graph         # same as: rigor-module-graph view
 ```
 
-Useful flags:
+A `.rigor.yml` must exist in the project root — that's how
+`rigor` knows to load this plugin. The minimal version is two
+lines:
+
+```yaml
+plugins:
+  - gem: rigor-module-graph
+```
+
+That's enough for `view` to run with all defaults. Everything
+else (`paths:`, `autoload_paths:`, …) goes in the
+[Configuration](#configuration) section below, and every key
+defaults to a sensible Rails-shaped value.
+
+## Usage
+
+### `view` — one-shot HTML / SVG / Mermaid
 
 ```sh
 # Don't open the browser (just write the HTML)
@@ -164,7 +118,7 @@ rigor-module-graph view --package
 rigor-module-graph view --package-root /path/to/repo
 ```
 
-`--direction` controls how the +--from+ walk follows edges:
+`--direction` controls how the `--from` walk follows edges:
 
 | direction | meaning                                |
 |-----------|----------------------------------------|
@@ -179,17 +133,19 @@ rigor-module-graph view --package-root /path/to/repo
 | `cluster`  | keep every edge whose endpoints both fall in the reachable set (default — good for "show me the Article neighbourhood as a cluster") |
 | `walk`     | keep only the edges the BFS actually traversed (good for "show me what depends on Article and nothing else"; drops sibling edges like `Foo inherits ApplicationRecord` that just happen to share a base class with reachable nodes) |
 
-A 1-hop `--from Article --direction out --edge-scope walk` returns
-exactly the edges whose `from` is `Article`, never the sibling
-`inherits ApplicationRecord` of a reached node.
+A 1-hop `--from Article --direction out --edge-scope walk`
+returns exactly the edges whose `from` is `Article`, never the
+sibling `inherits ApplicationRecord` of a reached node.
 
 ### Lower-level pipeline
 
-The pipeline `view` runs is also exposed as discrete subcommands
-when you want JSONL on disk or a pipeable text output:
+The pipeline `view` runs is also exposed as discrete
+subcommands when you want JSONL on disk or a pipeable text
+output:
 
 ```sh
-# Run `rigor check` and write edges JSONL (default: .rigor/module_graph/edges.jsonl)
+# Run `rigor check` and write edges JSONL
+# (default: .rigor/module_graph/edges.jsonl)
 bundle exec rigor-module-graph collect
 
 # Render the graph
@@ -210,18 +166,19 @@ bundle exec rigor-module-graph class-diagram .rigor/module_graph/edges.jsonl > c
 bundle exec rigor-module-graph class-diagram --no-private --no-attributes edges.jsonl
 ```
 
-`collect` shells out to `rigor check --format json --no-cache` and
-filters diagnostics on `source_family == "plugin.module-graph"` +
-`rule == "edge"`, so re-running is deterministic and there's no
-on-disk side-effect from the plugin itself.
+`collect` shells out to `rigor check --format json --no-cache`
+and filters diagnostics on
+`source_family == "plugin.module-graph"` + `rule == "edge"`,
+so re-running is deterministic and there's no on-disk
+side-effect from the plugin itself.
 
 `dot` / `mermaid` / `cycles` accept a file argument or read stdin.
 
 ### Filters and collapse
 
-All three reader subcommands accept the same filter flags. They
-prune the edge set before rendering / detecting; the JSONL on
-disk is untouched.
+All reader subcommands accept the same filter flags. They prune
+the edge set before rendering / detecting; the JSONL on disk is
+untouched.
 
 ```sh
 # Drop noisy const_ref / unresolved edges
@@ -230,7 +187,8 @@ bundle exec rigor-module-graph dot --kind inherits,include,prepend,extend edges.
 # Only the edges we're sure about
 bundle exec rigor-module-graph dot --confidence syntax,zeitwerk,rigor_type edges.jsonl
 
-# Fold every Billing::* node into one cluster (Dot subgraph_cluster_; Mermaid subgraph)
+# Fold every Billing::* node into one cluster
+# (Dot: subgraph_cluster_; Mermaid: subgraph)
 bundle exec rigor-module-graph dot     --collapse Billing,Auth edges.jsonl
 bundle exec rigor-module-graph mermaid --collapse Billing edges.jsonl
 
@@ -247,6 +205,46 @@ bundle exec rigor-module-graph mermaid --package-root /path/to/repo edges.jsonl
 bundle exec rigor-module-graph cycles --kind inherits,include edges.jsonl
 ```
 
+## Configuration
+
+`.rigor.yml` lives in the project root and is **required** —
+`rigor` reads it to discover this plugin. `rigor init` scaffolds
+a `.rigor.dist.yml` you can rename, or write it by hand. The
+two-line minimum from [Getting started](#getting-started) is
+enough; the full form below is for tuning.
+
+```yaml
+target_ruby: '4.0'
+paths:
+  - app
+  - lib
+plugins:
+  - gem: rigor-module-graph
+    config:
+      rails_zeitwerk: true
+      autoload_paths:
+        - app/models
+        - app/controllers
+        - app/services
+        - app/jobs
+        - lib
+      concern_dirs:
+        - app/models/concerns
+        - app/controllers/concerns
+      include_constant_refs: false
+```
+
+Every key shown is the default. Two switches worth knowing:
+
+- `include_constant_refs: true` — emit `const_ref` edges from
+  bare constant references inside method bodies. Off by default
+  because the volume of edges grows fast on a typical Rails app
+  and the noise can drown the structural picture.
+- `rails_zeitwerk: false` — keep every edge at
+  `confidence: "syntax"` and skip the path-based owner
+  inference. Useful when the project doesn't follow Zeitwerk's
+  autoload convention.
+
 ## Edge format
 
 Each edge in the JSONL file looks like:
@@ -279,6 +277,10 @@ published to GitHub Pages on every push to `main`.
   built from `main`, mirrors the current source.
 - [API reference (RubyGems)](https://rubydoc.info/gems/rigor-module-graph) —
   the last released gem on rubydoc.info.
+- [How it works](docs/how-it-works.md) — the static-analysis
+  pipeline (Prism → node rules → confidence ladder → JSONL →
+  renderers), and why this is a nominal dependency graph and
+  not a call graph.
 - [Development guide](docs/development.md) — local setup, git
   hooks, CI / Release workflows, test suite layout.
 - [Design plan](docs/plan.md) — the decisions still

data/lib/rigor/module_graph/cli.rb

@@ -16,6 +16,7 @@ require_relative "reachability"
 require_relative "stats"
 require_relative "packwerk_overlay"
 require_relative "html_view"
+require_relative "status_reporter"
 require_relative "uml/class_diagram"
 
 module Rigor
@@ -66,7 +67,7 @@ module Rigor
           stdout.puts USAGE
           0
         when "version", "-v", "--version"
-          stdout.puts Rigor::ModuleGraph::VERSION
+          stdout.puts "rigor-module-graph #{Rigor::ModuleGraph::VERSION}"
           0
         else
           stderr.puts "rigor-module-graph: unknown command #{command.inspect}"
@@ -255,6 +256,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 +265,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 +285,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 +311,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
@@ -365,6 +381,7 @@ module Rigor
             format: "html",
             output: nil,
             cache: false,
+            quiet: false,
             rigor_cmd: ENV.fetch("RIGOR_CMD", "rigor"),
             open: true,
             collapse: nil,
@@ -385,22 +402,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 +439,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
@@ -475,7 +518,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 +531,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
@@ -563,6 +613,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
             add_filter_options(opts, @options)
             opts.on("-h", "--help") do
               @stdout.puts opts

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/version.rb

@@ -5,6 +5,6 @@ module Rigor
   # an overview and Rigor::ModuleGraph::CLI for the CLI surface.
   module ModuleGraph
     # The installed gem version.
-    VERSION = "0.1.0"
+    VERSION = "0.1.2"
   end
 end

data/lib/rigor-module-graph.rb

@@ -29,4 +29,5 @@ require_relative "rigor/module_graph/stats"
 require_relative "rigor/module_graph/packwerk_overlay"
 require_relative "rigor/module_graph/uml/class_diagram"
 require_relative "rigor/module_graph/html_view"
+require_relative "rigor/module_graph/status_reporter"
 require_relative "rigor/module_graph/plugin"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rigor-module-graph
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Nozomi Hijikata
@@ -70,6 +70,7 @@ files:
 - lib/rigor/module_graph/plugin/rigor_plugin.rb
 - lib/rigor/module_graph/reachability.rb
 - lib/rigor/module_graph/stats.rb
+- lib/rigor/module_graph/status_reporter.rb
 - lib/rigor/module_graph/templates/view.html.erb
 - lib/rigor/module_graph/uml/class_diagram.rb
 - lib/rigor/module_graph/version.rb