rubylens 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59011e25213524d532e90ea20c237e82e8e3d615c37767bdf1d46038c64921be
-  data.tar.gz: feddff17e812a22b342c9e6c8ff65f06a58b45531e41b900e60dd984a31f3efc
+  metadata.gz: d79e23df4b2738a967167958385f2ef8b6c8dd6bd333f70a96690ed3c6f35823
+  data.tar.gz: '09f0c64309ee0427d3b3cf326187d9aaf9e6cf3d3b6766fd7951c3ba4fccd5e0'
 SHA512:
-  metadata.gz: 17d770ab8bbb1b651c1e7c6680ad27b6db38b4614d438c3ffb0b85c1919cec1e51c7fb2be447d61004c54ca23d4df7292ffc006bdcabd6fc04eaba9efcd2f433
-  data.tar.gz: f36f788b765f4cc60037b251574f9c22da8e65f4a4b78702a317e0443fcc4e832fd1572863731ab0d9f1593e751b749fd4e07cf9ea0cd37bc04dc18cef615ed1
+  metadata.gz: e1edf50d830b80dd72f9d033f6d1f9a74a51a90a559c6cc37329701b3762891145fe2e86a4b9f412224af2092a3c4b5c128473b0d453a19d83a689ff9c0570b0
+  data.tar.gz: 22e667b3baec097b8bb30c48ba9aa1c8fcd4817993479c0680b45f1605880ff8351f8ee0355e9ac3e06a3a3cc588471a0fd8953ea1561628e3fa411880d0961b

data/README.md

@@ -1,32 +1,46 @@
 # RubyLens
 
-RubyLens turns a Ruby codebase into an interactive galaxy in one self-contained HTML file. It runs locally, keeps source text out of the generated HTML, and gives you two ways to see a project: explore it yourself or let it play as an autonomous presentation.
+Your Ruby codebase, as a galaxy.
 
-[![Five synthetic RubyLens renders showing elliptical, lenticular, spiral, barred spiral, and irregular galaxy shapes.](docs/images/galaxy-morphology-families.jpg)](docs/images/galaxy-morphology-families.jpg)
+[![Five galaxy families rendered by RubyLens: elliptical, lenticular, spiral, barred spiral, irregular.](docs/images/galaxy-morphology-families.jpg)](docs/images/galaxy-morphology-families.jpg)
 
-*Five galaxy families rendered from the same synthetic codebase data.*
-
-> [!NOTE]
-> RubyLens 0.1 is an early release. It supports Ruby 3.2 through 4.0 and pins [Rubydex 0.2.9](https://rubygems.org/gems/rubydex/versions/0.2.9) because Rubydex's API is still pre-1.0.
-
-## Quick start
-
-RubyLens works from inside an existing Ruby project's bundle. The project must be inside a Git repository.
-
-Add RubyLens to the project's `Gemfile`:
+RubyLens reads a Ruby project and writes one self-contained HTML file: classes and modules as magenta stars, tests as a cyan halo, gems as orbiting gold clouds. The galaxy's shape is derived from the code: spiral, elliptical, barred, lenticular, or irregular.
 
 ```ruby
+# Gemfile
 gem "rubylens", require: false
 ```
 
-Install the bundle, then generate an Explorer:
-
 ```sh
-bundle install
 bundle exec rubylens report
 ```
 
-Open `rubylens-report.html` in a browser with WebGL2. No server is required.
+Open `rubylens-report.html` in your browser. No server needed.
+
+Three levels of disclosure:
+
+| For | Command | Reveals |
+| --- | --- | --- |
+| Yourself | `rubylens report` | Real class, module, and gem names, sparse reference topology, and full interaction |
+| Your team or a talk | `rubylens clip --details` | Project name, shape, scale, sparse reference topology, stats, and selected names |
+| Anyone | `rubylens clip` | Project name, galaxy shape and scale, and sparse anonymous reference topology |
+
+> [!IMPORTANT]
+> Nothing is uploaded and no source code is embedded. Outputs still describe your project: they name it, can name classes and gems, and reveal some relationship topology. See [Privacy and sharing](#privacy-and-sharing).
+
+https://github.com/user-attachments/assets/43570623-6d98-46c9-9303-7faa4035b2a7
+
+*The Explorer on Rails: search, fly to a class, expand a gem cloud.*
+
+https://github.com/user-attachments/assets/bb266de5-bbd7-4ccd-814b-15961b45bd39
+
+*A `--details` clip: what your team sees.*
+
+## Setup notes
+
+RubyLens runs from inside an existing Ruby project's bundle, and the project must be inside a Git repository.
+
+`clip` needs Chrome (or Chromium) and ffmpeg; see [Using Clip](#using-clip). Swap in `rubylens showcase [--details]` for the self-playing HTML page alone.
 
 RubyLens uses the current directory when you omit `TARGET`. To visualize a subdirectory while using the current project's bundle and root lockfile, run:
 
@@ -34,31 +48,20 @@ RubyLens uses the current directory when you omit `TARGET`. To visualize a subdi
 bundle exec rubylens report components/payments --lockfile Gemfile.lock
 ```
 
-Run RubyLens from each separate project's own bundle.
-
 For complete gem clouds, generate from a project with a readable `Gemfile.lock` after `bundle install`. Without a lockfile, RubyLens still shows Core and Tests but omits Gems and reports a warning. It never fetches missing dependencies during generation.
 
-## Choose a view
-
-| Output | Command | Best for | What it reveals |
-| --- | --- | --- | --- |
-| **Explorer** | `bundle exec rubylens report` | Privately exploring a codebase | Class, module, and gem names, relationships, and aggregate Ruby statistics |
-| **Minimal Showcase** | `bundle exec rubylens showcase` | Sharing a visual with fewer details | Project name plus the galaxy's shape and scale |
-| **Details Showcase** | `bundle exec rubylens showcase --details` | A presentation with project-specific labels | Aggregate statistics and a capped selection of class, module, and dependency names |
-
-Explorer writes `rubylens-report.html`. Both Showcase commands write `rubylens-showcase.html`.
-
 ## Privacy and sharing
 
-RubyLens indexes and renders locally. Generated files contain their scripts, styles, fonts, and data, make no network requests, and open without Node or an HTTP server.
+RubyLens indexes and renders locally. Generated HTML files contain their scripts, styles, fonts, and data, make no network requests, and open without Node or an HTTP server. Clip rendering also stays local: it drives your own Chrome and ffmpeg over loopback and never uploads anything.
 
-But the HTML still describes your project:
+But the outputs still describe your project:
 
 - Explorer embeds fully qualified class, module, and gem names. It omits source text, comments, paths, and names for individual dependency stars.
-- Minimal Showcase omits code and gem names, but still reveals the project name plus the galaxy's shape and scale.
-- Details Showcase adds aggregate statistics and selected code/dependency names.
+- Minimal Showcase omits code and gem names, but still reveals the project name, the galaxy's shape and scale, and a sparse anonymous sample of constant-reference topology.
+- Details Showcase adds aggregate statistics and selected code/dependency names to the same topology.
+- Clip shows on screen exactly what the recorded Showcase shows, in a format anyone can replay.
 
-Galaxy shape is also information: a package's rendered shape can make the rough makeup of that gem easier to see, even though it reveals no source text.
+Galaxy shape is also information: a package's rendered shape can make the rough makeup of that gem easier to see, even though it reveals no source text. Relationship topology is information too: a travel line means that one rendered namespace contains a resolved reference to another rendered declaration.
 
 Default outputs are written atomically with owner-only `0600` permissions. RubyLens also adds the exact default output and its temporary-file pattern to the repository's local `.git/info/exclude`, so it does not change the shared `.gitignore`.
 
@@ -70,6 +73,8 @@ Custom output paths are written exactly where requested, may replace an existing
 
 Explorer lets you search and move through Core code, Tests, and Gems while the galaxy continues to drift.
 
+While drift runs, RubyLens scales traffic with the rendered project population: very small reports show one flight at a time, and larger reports show at most two simultaneous flights. Individual launches follow one seeded stream with varied gaps, and a finished flight frees capacity for another after a short randomized breath. There are no synchronized bursts or two-second pauses. Routes to exact Gem declaration stars are preferred three times out of four while workspace-only routes stay eligible. Admission skips very short or out-of-bounds guides and rejects capacity-conflicting or shared-endpoint routes. Each admitted 2.2-second flight follows one immutable world-space quadratic with a compact tapered wake whose thickest end overlaps one elongated same-hue drop. Admission checks a screen-space guide, then unprojects its control point; the live camera projects the resulting path throughout the flight. A rotating Gem star may move away after departure. Orbit, pan, zoom, and camera flights keep active paths visible; pausing drift or requesting reduced motion clears them.
+
 - Drag to orbit.
 - Scroll at the cursor to zoom.
 - Shift-drag, use Pan mode, or use the arrow keys to move across the galaxy.
@@ -79,11 +84,11 @@ Explorer lets you search and move through Core code, Tests, and Gems while the g
 - Press Space or use the toolbar to pause/resume drift.
 - Use Reset to restore the default camera without changing your drift choice.
 
-Explorer requires WebGL2 to render the complete galaxy. If WebGL2 is unavailable or its context is lost, RubyLens stops the artwork and shows an explicit warning instead of silently presenting a sampled or incomplete galaxy.
+Explorer requires WebGL2 to render the complete galaxy. If WebGL2 is missing or the browser loses the context, RubyLens shows a warning rather than quietly drawing a partial galaxy.
 
 ## Using Showcase
 
-Showcase is autonomous and noninteractive. It opens directly, rotates once per minute, and contains no Explorer controls, search, hover, or navigation.
+Showcase is self-playing and noninteractive. It opens directly, rotates once per minute, and contains no Explorer controls, search, hover, or navigation.
 
 Use the default Minimal mode when the visual shape is enough:
 
@@ -97,7 +102,23 @@ Use `--details` when you want aggregate statistics and one-at-a-time cinematic l
 bundle exec rubylens showcase --details
 ```
 
-Showcase also requires WebGL2. A browser with `prefers-reduced-motion` enabled receives one stable frame with no cinematic labels.
+Both Showcase modes include the same bounded, anonymous travel flights. Showcase also requires WebGL2. A browser with `prefers-reduced-motion` enabled receives one stable frame with no travel flights or cinematic labels.
+
+## Using Clip
+
+Clip records the Showcase into `rubylens-clip.mp4`: one full camera rotation at 1920×1080 and 30 frames per second, encoded as H.264 for compatibility with Slack, X, LinkedIn, and slide decks. The camera ends where it started, so the loop has no visible cut.
+
+```sh
+bundle exec rubylens clip
+bundle exec rubylens clip --details
+```
+
+Clip needs two locally installed tools and checks for them before doing any work:
+
+- **Chrome or Chromium** for headless WebGL2 rendering. Discovery checks `PATH` and common install locations; set `RUBYLENS_CHROME` to point at a specific binary.
+- **ffmpeg** for H.264 encoding (`brew install ffmpeg` or `apt install ffmpeg`); set `RUBYLENS_FFMPEG` to override discovery.
+
+Frames render deterministically off-screen, so nothing flashes across your display, and progress is reported as the 1,800 frames encode. Expect a few minutes on machines without GPU acceleration. The showcase HTML is always written next to the video, so a failed render still leaves you a shareable page.
 
 ## What the stars mean
 
@@ -105,7 +126,7 @@ Showcase also requires WebGL2. A browser with `prefers-reduced-motion` enabled r
 - **Tests** are cyan. They represent test classes and modules. RubyLens also adds class-like stars for RSpec `describe` and `context` calls under `spec/` or `specs/`.
 - **Gems** are warm gold. Each gem forms a cloud of anonymous stars. Related gems from the same materialized Git source can appear together as one dependency system.
 
-RubyLens uses Rubydex to find classes, modules, methods, constants, inheritance, reopenings, and references. It does not claim that references form a complete call graph, and it never executes the project or its tests.
+RubyLens uses Rubydex to find classes, modules, methods, constants, inheritance, reopenings, and references. Shuttle flights draw from resolved references whose occurrences belong to Core or Test namespaces; their targets may be another workspace namespace or an exact anonymous Gem declaration star. Core-to-Core, Core-to-Test, Test-to-Core, Test-to-Test, and workspace-to-Gem flights are included; top-level, ambiguous, exact-self, and non-workspace origins are omitted. Flights travel from the referenced declaration to the referrer and show a bounded visual sample, not call edges or a complete relationship graph. RubyLens never executes the project or its tests.
 
 RubyLens analyzes tracked `.rb`, `.rake`, `.rbs`, and `.ru` files inside the target, plus untracked files of those types that Git does not ignore. It reads dependency versions from `Gemfile.lock` and analyzes gem code already installed locally.
 
@@ -115,6 +136,8 @@ RubyLens is not a type checker, whole-program call graph, source browser, route
 
 RubyLens uses the [Hubble sequence](https://science.nasa.gov/asset/hubble/the-hubble-tuning-fork-classification-of-galaxies/) as a visual vocabulary. It uses broad code counts to choose a repeatable shape for the central Core/Test galaxy and each dependency package independently. A package never inherits the project's, host's, or dependency system's decision.
 
+Very large dependency packages that would otherwise render as smooth elliptical or lenticular clouds use a deterministic Spiral or Barred Spiral enrichment. This keeps their visual mass structured while smaller packages retain their aggregate-derived family.
+
 The morphology describes the rendered shape. It is not a claim about the project's architecture, purpose, quality, or correctness.
 
 [![Paired synthetic RubyLens renders comparing E2 with E6, Sa with Sc, and SBa with SBc.](docs/images/galaxy-morphology-variations.jpg)](docs/images/galaxy-morphology-variations.jpg)
@@ -127,16 +150,17 @@ Read the [accepted morphology design](docs/specs/2026-07-14-galaxy-morphology-de
 
 ```text
 rubylens report [OPTIONS] [TARGET]
+rubylens clip [OPTIONS] [TARGET]
 rubylens showcase [OPTIONS] [TARGET]
 ```
 
-Both commands accept:
+All commands accept:
 
 - `-o FILE` / `--output FILE` to choose an output path
 - `--lockfile FILE` to use a specific `Gemfile.lock`
 - `-h` / `--help` to show command help
 
-`rubylens showcase` also accepts `--details`.
+`rubylens clip` and `rubylens showcase` also accept `--details`. A custom `rubylens clip --output movie.mp4` writes the recorded showcase to `movie.html` next to it.
 
 ## Ruby API
 
@@ -150,6 +174,10 @@ puts report.warnings
 
 showcase = RubyLens.generate_showcase(path: ".", details: true)
 puts showcase.output_path
+
+clip = RubyLens.generate_clip(path: ".", progress: ->(done, total) { puts "#{done}/#{total}" })
+puts clip.output_path    # the MP4
+puts clip.showcase_path  # the showcase HTML it recorded
 ```
 
 Passing `output:` selects a custom path. The caller is responsible for keeping custom outputs private.