rigor-module-graph 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cea3ca68d705ecbe0f3534c5b3374e7e1dfd0f01edb6a0b9e64ed4c775cb166d
-  data.tar.gz: 70d09cd49d66f118948f2ec142d4f7a6c068a6ce098cddf97b3dd7d997a507d9
+  metadata.gz: 0ed5f8fe6226376ad089b013b8ad16cecc453da2202cbaf6b3a590e6b64d0c85
+  data.tar.gz: 47bdbc75a44a9887a58246783fcc3f57b5f1ad119b3c336c6673e72799678fe2
 SHA512:
-  metadata.gz: 5fec0afc7142600d308187afb293484818e545e63d5e21c08221412e0bcbca98db5cbf6e1e30c3b45ad46a30459779dcfe816459b9009494c5fbd4d0265a0dea
-  data.tar.gz: 1795a811ff1b184945dc55fb6a5451d09f895b85b778d1d98145f5fae2ad5f5aa0822dbafed51fad143ae3c32a8b75a5f3beec55cefdd3e9164658aa6e25e019
+  metadata.gz: ae0a36d5c2107420b5a3577a2030c5417789f52ed0732f5d67669ac31444e73131135273d067e7f3fb6dfd7cafde845a7ef5183f4abd414bfae8ff446688d68d
+  data.tar.gz: 43ad7597db1d1fd945159afb81ee36339450b2ffa487bd94d21fc0da8ed0ae044af02a5b6c482044b510ee1ce0df56c2e215f72707307c8aef803ff0a9eab42e

data/CHANGELOG.md

@@ -17,6 +17,83 @@ Categories:
 
 ## [Unreleased]
 
+## [0.1.3] — 2026-06-20
+
+The first release that pairs the published gem with the
+[interactive viewer](docs/how-it-works.md) the README has been
+showcasing, plus the supply-chain hardening that justifies
+shipping a vendored third-party JS file inside the gem.
+
+### Added
+
+- **Interactive `view --output html` viewer.** Replaces the
+  static Mermaid embed with a [Cytoscape.js](https://js.cytoscape.org/)-based
+  page that renders 5k+ nodes, filters live by `kind` /
+  `confidence`, supports a name-substring search, and copies
+  `path:line` to the clipboard on node click. The Cytoscape
+  library is vendored into the gem at a sha256-pinned version
+  (`lib/rigor/module_graph/templates/vendor/cytoscape.min.js`);
+  no CDN, no npm, no Dependabot auto-bump.
+  See [`docs/plan.md`](docs/plan.md) "2D interactive viewer"
+  for the supply-chain rationale.
+- `--path-mode {relative,absolute,none}` flag on `view` —
+  controls how node paths reach the viewer's click-through
+  metadata. `none` strips paths from the HTML artefact, which
+  is the right setting when sharing the file outside the
+  project (PR comment, gist, …).
+- `--open-with vscode` flag on `view` — flips the node-click
+  action from clipboard copy to `vscode://file/<path>:<line>`
+  so the editor jumps straight to the source location.
+- `bundle exec rake vendor:verify` task — recomputes sha256
+  for every file in `vendor/CHECKSUMS` and fails on mismatch.
+  Wired into pre-commit on any staged file under
+  `lib/**/templates/vendor/**`.
+- `.github/dependabot.yml` — weekly Bundler + GitHub Actions
+  bumps; `vendor/**` is explicitly excluded so vendored
+  third-party JS never auto-updates.
+- `bundle exec rake vendor:audit` — 4-source cross-check
+  (local sha256 / npm tarball `dist.integrity` /
+  tarball-internal copy / GitHub raw / every CDN). Reads
+  `lib/rigor/module_graph/templates/vendor/MANIFEST.yml` for
+  the provenance metadata. Use on bump PRs; not part of the
+  regular CI pipeline (network-using).
+- CI now runs `rake vendor:verify` independently of
+  pre-commit so an unaudited bump can't land on `main` even
+  if local hooks were skipped.
+- CI now regenerates `examples/billing/` via `script/
+  check_billing_drift.rb` and fails on drift between the
+  freshly-built artefacts and the committed copies.
+  Normalises the graphviz version banner so the runner's
+  apt-shipped version doesn't trigger a false positive.
+- New `docs/security.md` consolidates the supply-chain story
+  (Bundler / Dependabot cooldown, vendored-JS sha256 +
+  4-source audit, action SHA pinning, OIDC trusted
+  publishing).
+
+### Changed
+
+- **`view --output html` semantics.** The flag now produces
+  the interactive viewer. The previous static Mermaid HTML
+  moves behind `--output mermaid-html` (still loads Mermaid
+  from a CDN, kept for back-compat).
+- CI workflows read Ruby from `.ruby-version` instead of
+  pinning `"4.0.0"` inline, so future `.ruby-version` bumps
+  no longer need a `.github/workflows/` chase.
+- RDoc dependency bumped from `~> 6.0` to `~> 7.0` (resolves
+  to 7.2.0). `gemspec.rdoc_options` corrected to `--markup
+  markdown` to match `.rdoc_options` and the Rakefile, fixing
+  the silent inconsistency left when the README rendering
+  fix landed in [0.1.2]. No code change; `rake rdoc` emits no
+  warnings under 7.x.
+- README hero leads with the Cytoscape viewer screenshot
+  (the default output) and the Graphviz SVG follows.
+  `examples/billing/preview.png` resized from 1280x860 to
+  720x483 so it fits the RDoc darkfish content pane on the
+  GitHub Pages site without overflow.
+- README Documentation index re-ordered along the natural
+  reading flow: how-it-works → security → limitation →
+  development → plan.
+
 ## [0.1.2] — 2026-06-20
 
 First release that exercises the full automated pipeline end
@@ -173,7 +250,8 @@ 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.2...HEAD
+[Unreleased]: https://github.com/nozomemein/rigor-module-graph/compare/v0.1.3...HEAD
+[0.1.3]: https://github.com/nozomemein/rigor-module-graph/compare/v0.1.2...v0.1.3
 [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

@@ -11,10 +11,25 @@ to Packwerk/Graphwerk: where those look at package boundaries, this
 looks at the Ruby nominal graph — inheritance, `include`/`prepend`/
 `extend`, and (later) constant references.
 
-![billing example](examples/billing/graph.svg)
+**Two ways to look at the same graph.** Static SVG via
+Graphviz for committing into PRs and docs; interactive HTML
+via Cytoscape.js for actually exploring a 1000+-node Rails
+codebase. Both rendered from the same `edges.jsonl` —
+no second analysis pass.
 
-The screenshot above is from `examples/billing/`. Open
-`examples/billing/index.html` for the live Mermaid version.
+### Cytoscape (`--output html`, the default)
+
+![billing graph via Cytoscape](examples/billing/preview.png)
+
+### Graphviz (`--output svg`)
+
+![billing graph via Graphviz](examples/billing/graph.svg)
+
+Both screenshots are from `examples/billing/`. Open
+`examples/billing/index.html` directly to try the
+interactive version — pan, zoom, filter by `kind` /
+`confidence`, search by name, click a node to copy
+`path:line`.
 
 ## Install
 
@@ -85,27 +100,45 @@ defaults to a sensible Rails-shaped value.
 
 ### `view` — one-shot HTML / SVG / Mermaid
 
+The default `html` output is an interactive
+[Cytoscape.js](https://js.cytoscape.org/)-based viewer:
+filter checkboxes for `kind` and `confidence`, live name
+search, `fit` button, and node-click → copy `path:line` to
+the clipboard. The Cytoscape library is vendored into the gem
+at a sha256-pinned version, so the generated HTML opens
+offline with no network round-trip.
+
 ```sh
 # Don't open the browser (just write the HTML)
 rigor-module-graph view --no-open
 
-# Pick a different output format — html (default) opens a viewer
-# in the browser; everything else streams to stdout unless `-o`
-# is given.
+# Pick a different output format. `html` is the interactive
+# viewer; `mermaid-html` is the legacy static-Mermaid embed
+# (loads Mermaid from a CDN, kept for back-compat). Everything
+# else streams to stdout unless `-o` is given.
+rigor-module-graph view --no-open --output mermaid-html  > graph.html
 rigor-module-graph view --no-open --output mermaid       > graph.mmd
 rigor-module-graph view --no-open --output dot           > graph.dot
 rigor-module-graph view --no-open --output svg           > graph.svg
 rigor-module-graph view --no-open --output class-diagram > class.mmd
 rigor-module-graph view --output svg -o graph.svg
 
-# Focus on what's around one or a few constants (Mermaid can't
-# render 1000+-node graphs cleanly — this is the escape hatch)
+# Click on a node opens the file in VSCode rather than copying
+# path:line to the clipboard. `--path-mode none` strips the
+# path metadata entirely — useful when sharing the HTML
+# artefact outside the project.
+rigor-module-graph view --open-with vscode
+rigor-module-graph view --path-mode none      # share-safe
+rigor-module-graph view --path-mode absolute  # cwd-resolved
+
+# Focus on what's around one or a few constants
 rigor-module-graph view --from Article --depth 5
 rigor-module-graph view --from Article --depth 5 --direction out
 rigor-module-graph view --from Billing::Invoice,Billing::Payment --depth 2
 
 # Pick your own collapse list (default: auto-detect top-level
-# namespaces with ≥ 3 members)
+# namespaces with ≥ 3 members; applies to mermaid / dot / svg
+# outputs — the interactive html viewer ignores it).
 rigor-module-graph view --collapse Billing,Auth
 rigor-module-graph view --no-collapse
 
@@ -245,22 +278,6 @@ Every key shown is the default. Two switches worth knowing:
   inference. Useful when the project doesn't follow Zeitwerk's
   autoload convention.
 
-## Edge format
-
-Each edge in the JSONL file looks like:
-
-```json
-{"from":"Billing::Invoice","to":"ApplicationRecord","kind":"inherits","path":"app/models/billing/invoice.rb","line":2,"column":3,"confidence":"syntax"}
-```
-
-- `kind`: `inherits` / `include` / `prepend` / `extend` /
-  `const_ref` (the last one is reserved for Phase 2).
-- `confidence`: `syntax` / `zeitwerk` / `rigor_type` /
-  `unresolved`. MVP only emits `syntax`.
-
-The renderers dedup by `(from, to, kind, confidence)` so two
-`include Foo` on the same class across files collapse to one edge.
-
 ## Compatibility
 
 - Ruby `>= 4.0.0, < 4.1`
@@ -281,14 +298,18 @@ published to GitHub Pages on every push to `main`.
   pipeline (Prism → node rules → confidence ladder → JSONL →
   renderers), and why this is a nominal dependency graph and
   not a call graph.
+- [Security](docs/security.md) — supply-chain controls
+  (Bundler cooldown, vendored-JS sha256 + 4-source audit,
+  action SHA pinning, trusted publishing) and the layered
+  pre-commit / CI gates that enforce them.
+- [Known limitations](docs/limitation.md) — rough edges shipped
+  with the current release (visibility tracker gaps, the
+  bundled inflector, Mermaid 10.x quirks).
 - [Development guide](docs/development.md) — local setup, git
   hooks, CI / Release workflows, test suite layout.
 - [Design plan](docs/plan.md) — the decisions still
   load-bearing for the code (edge model, confidence ladder,
   output channel, owner resolution, architecture map).
-- [Known limitations](docs/limitation.md) — rough edges shipped
-  with the current release (visibility tracker gaps, the
-  bundled inflector, Mermaid 10.x quirks).
 - [Changelog](CHANGELOG.md) — per-version changes, formatted
   per [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
   with [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

data/lib/rigor/module_graph/cli.rb

@@ -18,6 +18,7 @@ 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
@@ -365,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
@@ -394,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
 
@@ -461,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)}",
@@ -554,7 +581,7 @@ module Rigor
         end
 
         def html?
-          @options[:format] == "html"
+          %w[html mermaid-html].include?(@options[:format])
         end
 
         def build_parser
@@ -616,6 +643,7 @@ module Rigor
             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
@@ -624,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/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