rigor-module-graph 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5b9be2e8029422795b2b8b9e8f13998f6aefc16923e11e166f7692910637eb81
+  data.tar.gz: a723c08c549cb5368166de5971712f12d1cd5d06c142d176d842b43bd9ec6816
+SHA512:
+  metadata.gz: e0ea19766f2fa753a0b41fe6dd7eb9b7840b3ce70ca10a8b1b153e2d04633f7cb0a04d1b24f6481104b038ab240e6d26fa56d6a4a990f404e565ce0ddfa21cdf
+  data.tar.gz: 82153c88b36de25bad1250d5f33c10b88d4a7c049d17112c750e4cf2596739407429f730048543e9c2bc7d0fe3551d877d6c6ee5275df780dceb4f1415742304

data/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Categories:
+
+- **Added** — new functionality
+- **Changed** — behaviour of existing functionality
+- **Deprecated** — scheduled for removal
+- **Removed** — gone
+- **Fixed** — bug fixes
+- **Security** — security fixes
+- **Performance** — user-visible performance improvements
+
+## [Unreleased]
+
+## [0.1.0] — 2026-06-20
+
+Initial release. Baseline shipping everything from the Phase 0
+spike through Phase 5 (UML class diagram).
+
+### Added
+
+- **Phase 0**: Rigor plugin API spike against `rigortype 0.2.1`
+  + `rbs ~> 4.0`, validating that `node_rule(Prism::ClassNode)`
+  and friends work and locking in the `:info` diagnostic output
+  channel.
+- **Phase 1 (MVP)**: extraction of `inherits` / `include` /
+  `prepend` / `extend` edges. `Rigor::ModuleGraph::Edge` (a
+  `Data` subclass) with a JSONL writer, Graphviz DOT and Mermaid
+  flowchart renderers, and cycle detection via an iterative
+  Tarjan SCC.
+- **Phase 2**: Zeitwerk-style path → constant inference
+  (`ZeitwerkResolver`), namespace collapse in both renderers
+  (DOT `subgraph cluster_*` and Mermaid `subgraph`), and
+  `const_ref` edges from constant references inside method
+  bodies (gated on `include_constant_refs`). Confidence promotes
+  from `syntax` → `zeitwerk` when the path-inferred name agrees
+  with the lexical owner.
+- **Phase 3**: indirect mixin resolution via `scope.type_of`. A
+  `Rigor::Type::Singleton` carrier lifts the edge to
+  `confidence: "rigor_type"`; everything else degrades to
+  `"unresolved"` with the source slice preserved in `raw`. CLI
+  gains `--kind` and `--confidence` filters.
+- **Phase 4**: `stats` subcommand reporting per-namespace
+  fan-in / fan-out / internal / nodes (text and JSON, with
+  `--grouping-depth N` and `--limit N`). Packwerk overlay
+  (`--package` / `--package-root PATH`) discovers `package.yml`
+  files recursively and uses them as the cluster boundary. The
+  Dot / Mermaid renderers accept an explicit `groups:` mapping
+  for arbitrary node → cluster assignments.
+- **Phase 5**: UML-style class diagram. `collect` writes a
+  sibling `nodes.jsonl` covering class / module declarations,
+  method definitions, and `attr_*` attributes — with visibility
+  tracked via the `VisibilityMap`'s bare `private` / `protected`
+  / `public` keyword walk. Rails associations land as edges
+  (`has_many` / `belongs_to` / `has_one` /
+  `has_and_belongs_to_many`, with cardinality and a tiny
+  Rails-style inflector that maps `:invoices → Invoice`). A new
+  `Uml::ClassDiagram` renderer and `class-diagram` subcommand
+  emit Mermaid `classDiagram` syntax; filters `--no-methods`,
+  `--no-attributes`, `--public-only`, `--no-private`.
+- **`view` one-shot subcommand**: `rigor-module-graph` with no
+  args (or `view` explicitly) analyses the current directory,
+  writes a self-contained HTML report under
+  `.rigor/module_graph/`, and opens it in a browser. The
+  `--output html|mermaid|dot|svg|class-diagram` flag switches
+  format; non-html streams to stdout unless `-o PATH` is given.
+- **Reachability filter** (`--from NAMES`, `--depth N`,
+  `--direction in/out/both`) shared by every reader subcommand.
+  Subsequent `--edge-scope cluster|walk` flag distinguishes
+  "show the neighbourhood as a cluster" (default) from "show
+  only the edges the BFS actually traversed" (Codex review
+  confirmed naming and direction-both semantics).
+- **Billing example** (`examples/billing/`): Customer /
+  Invoice / Payment / LineItem + concerns. `build.rb` runs the
+  same `view --output` pipeline that ships in the CLI, and
+  commits `index.html`, `class-diagram.html`, `graph.svg`, and
+  a `preview.png` so the GitHub view of the repo shows the
+  rendered output directly.
+- **RDoc** support via `rake rdoc` / `rake rdoc:preview` /
+  `rake rdoc:server`.
+- **minitest + minitest-snapshot** test harness. Snapshots
+  refresh with `UPDATE_SNAPSHOTS=1 rake test`.
+- **SimpleCov C2 (branch) coverage** measurement via
+  `COVERAGE=1 rake test` or `rake coverage`. Baseline is 91.19%
+  branch coverage (445 / 488 branches).
+- **lefthook** wiring rubocop / betterleaks / rigor / zizmor on
+  pre-commit and minitest on pre-push.
+- **GitHub Actions**: `ci.yml` (test, lint, workflow-lint) and
+  `release.yml` (`workflow_dispatch`-only, uses RubyGems trusted
+  publishing — no long-lived API token).
+
+### Performance
+
+- `Stats.compute` rewritten as a single pass with a mutable
+  per-namespace counter array instead of a `Data#with` cascade
+  per edge. On 2016 edges this took the call from **139 ms to
+  47 ms (3.0×)**.
+- `Reachability.walk` swaps `Set` for `Hash<name, true>` +
+  `Array` frontier, builds only the adjacency direction it
+  actually needs, and the `:both`-direction `walked_edge_indexes`
+  shares one pair of indexed adjacencies between its out-walk
+  and in-walk. Cluster depth-3 outbound: **27 ms → 14 ms (1.9×)**;
+  both direction: **35 ms → 19 ms (1.8×)**.
+- `Edge#dedup_key` is now a generated Data member set once in
+  `Edge.build` as a `-`-frozen joined string. Renderer dedup
+  Hashes go from `Hash<Array,_>` to `Hash<String,_>`, which
+  drove the **1.2×** Dot / Mermaid render gain.
+- YJIT (`--yjit`) adds another ~1.5×. ZJIT measured between
+  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
+[0.1.0]: https://github.com/nozomemein/rigor-module-graph/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nozomi Hijikata
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,294 @@
+# rigor-module-graph
+
+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
+looks at the Ruby nominal graph — inheritance, `include`/`prepend`/
+`extend`, and (later) constant references.
+
+![billing example](examples/billing/graph.svg)
+
+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
+
+Via Bundler:
+
+```ruby
+# Gemfile
+gem "rigor-module-graph"
+```
+
+```sh
+bundle install
+```
+
+Or globally:
+
+```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
+
+Add the plugin to your project's `.rigor.yml`:
+
+```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. 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.
+
+## Usage
+
+### One-shot: `view`
+
+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.
+
+```sh
+cd path/to/your/project
+bundle exec rigor-module-graph         # same as: rigor-module-graph view
+```
+
+Useful flags:
+
+```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.
+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)
+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)
+rigor-module-graph view --collapse Billing,Auth
+rigor-module-graph view --no-collapse
+
+# Same kind / confidence filters as the lower-level commands
+rigor-module-graph view --kind inherits,include
+rigor-module-graph view --confidence syntax,zeitwerk
+
+# Cluster by Packwerk packages (auto-detects package.yml under cwd)
+rigor-module-graph view --package
+rigor-module-graph view --package-root /path/to/repo
+```
+
+`--direction` controls how the +--from+ walk follows edges:
+
+| direction | meaning                                |
+|-----------|----------------------------------------|
+| `out`     | only "what does Article depend on"     |
+| `in`      | only "what depends on Article"         |
+| `both`    | both (default)                         |
+
+`--edge-scope` controls which edges survive once the BFS finishes:
+
+| edge-scope | meaning                                                    |
+|------------|------------------------------------------------------------|
+| `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.
+
+### Lower-level pipeline
+
+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)
+bundle exec rigor-module-graph collect
+
+# Render the graph
+bundle exec rigor-module-graph dot     .rigor/module_graph/edges.jsonl > graph.dot
+bundle exec rigor-module-graph mermaid .rigor/module_graph/edges.jsonl > graph.mmd
+dot -Tsvg graph.dot -o graph.svg
+
+# Detect cycles (exit 1 if any are found)
+bundle exec rigor-module-graph cycles  .rigor/module_graph/edges.jsonl
+
+# Per-namespace fan-in / fan-out report
+bundle exec rigor-module-graph stats   .rigor/module_graph/edges.jsonl
+bundle exec rigor-module-graph stats --format json --limit 10 edges.jsonl
+
+# UML class diagram (Mermaid classDiagram). Reads edges + the
+# sibling nodes.jsonl that `collect` writes.
+bundle exec rigor-module-graph class-diagram .rigor/module_graph/edges.jsonl > class.mmd
+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.
+
+`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.
+
+```sh
+# Drop noisy const_ref / unresolved edges
+bundle exec rigor-module-graph dot --kind inherits,include,prepend,extend edges.jsonl
+
+# 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)
+bundle exec rigor-module-graph dot     --collapse Billing,Auth edges.jsonl
+bundle exec rigor-module-graph mermaid --collapse Billing edges.jsonl
+
+# Restrict the graph to the neighbourhood of one or a few
+# constants (works on dot / mermaid / cycles too)
+bundle exec rigor-module-graph dot     --from Article --depth 5 edges.jsonl
+bundle exec rigor-module-graph mermaid --from Article --depth 5 --direction out edges.jsonl
+
+# Cluster by Packwerk packages instead of by namespace
+bundle exec rigor-module-graph dot     --package edges.jsonl  # cwd
+bundle exec rigor-module-graph mermaid --package-root /path/to/repo edges.jsonl
+
+# Cycles that stay within structural edges only
+bundle exec rigor-module-graph cycles --kind inherits,include edges.jsonl
+```
+
+## 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`
+- rigortype `~> 0.2.1`
+- rbs `~> 4.0`
+
+## Documentation
+
+The public RDoc API is generated locally via `rake rdoc`,
+served on `http://localhost:8808` via `rake rdoc:server`, and
+published to GitHub Pages on every push to `main`.
+
+- [API reference (GitHub Pages)](https://nozomemein.github.io/rigor-module-graph/) —
+  built from `main`, mirrors the current source.
+- [API reference (RubyGems)](https://rubydoc.info/gems/rigor-module-graph) —
+  the last released gem on rubydoc.info.
+- [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).
+  The release workflow gates on a `## [VERSION]` entry being
+  present before pushing to RubyGems.

data/exe/rigor-module-graph

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rigor/module_graph/version"
+require "rigor/module_graph/cli"
+
+exit(Rigor::ModuleGraph::CLI.run(ARGV.dup))