rubylens 0.1.0.pre.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a68f44779cf227639060ec998c28dca42887c018c1840acb9cb052f11b1fc308
-  data.tar.gz: 0aa7d34a9b43f8796052d1a8a4106a424ae074ebd3785ff90abc718734b510e8
+  metadata.gz: d79e23df4b2738a967167958385f2ef8b6c8dd6bd333f70a96690ed3c6f35823
+  data.tar.gz: '09f0c64309ee0427d3b3cf326187d9aaf9e6cf3d3b6766fd7951c3ba4fccd5e0'
 SHA512:
-  metadata.gz: a58596bc4b75bcff08991750258d18d3deae534fc21d78e505b098091986c32a3226a962a4c102cc9b0eb518efaf0258b131338a065b3845f89ea3a8db9fb01a
-  data.tar.gz: cc8321d3b96900926f4d6cfaf7d24b18660eb5f1d597b00056b3b3383f2d02050af5fc8bafd22276cb7063d7ba9633c3bfb8ced2f8a52229291641f0d22789d8
+  metadata.gz: e1edf50d830b80dd72f9d033f6d1f9a74a51a90a559c6cc37329701b3762891145fe2e86a4b9f412224af2092a3c4b5c128473b0d453a19d83a689ff9c0570b0
+  data.tar.gz: 22e667b3baec097b8bb30c48ba9aa1c8fcd4817993479c0680b45f1605880ff8351f8ee0355e9ac3e06a3a3cc588471a0fd8953ea1561628e3fa411880d0961b

data/README.md

@@ -1,67 +1,218 @@
 # RubyLens
 
-RubyLens turns a Ruby codebase into self-contained stellar HTML. It uses Rubydex internally to map Ruby code, then generates either a private interactive report or a privacy-reduced autonomous Showcase.
+Your Ruby codebase, as a galaxy.
 
-This is an early local prototype. RubyLens 0.1 supports Ruby 3.2 through 4.0 and pins Rubydex 0.2.9 while its API is pre-1.0.
+[![Five galaxy families rendered by RubyLens: elliptical, lenticular, spiral, barred spiral, irregular.](docs/images/galaxy-morphology-families.jpg)](docs/images/galaxy-morphology-families.jpg)
 
-## Generate a report
+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.
 
-Add RubyLens to the bundle of the project you want to visualize, then run:
+```ruby
+# Gemfile
+gem "rubylens", require: false
+```
 
 ```sh
-bundle exec rubylens report .
+bundle exec rubylens report
 ```
 
-The default report is `rubylens-report.html` in the project root. It contains fully qualified class, module, and gem names for local hover details, but no source text, comments, or paths. Dependency stars remain anonymous and are summarized at the gem level. RubyLens adds that exact default path to Git's local exclude file and writes the report with owner-only permissions, so it stays out of commits without changing the project's `.gitignore`. The model reveals private codebase structure, so keep it local unless you intend to share it.
+Open `rubylens-report.html` in your browser. No server needed.
 
-Ruby API:
+Three levels of disclosure:
 
-```ruby
-result = RubyLens.generate_report(path: ".")
-puts result.output_path
-puts result.counts
-puts result.warnings
+| 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:
+
+```sh
+bundle exec rubylens report components/payments --lockfile Gemfile.lock
 ```
 
-Passing `output:` selects a custom path. Custom paths are written exactly where requested and are not added to Git's local excludes, so the caller is responsible for keeping them private.
+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.
+
+## Privacy and sharing
+
+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 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, 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. Relationship topology is information too: a travel line means that one rendered namespace contains a resolved reference to another rendered declaration.
 
-`RubyLens.generate` remains a thin alias for `RubyLens.generate_report`.
+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`.
 
-The report is fully local: it makes no network requests and needs neither Node nor a server to open. Drag to orbit, zoom toward the cursor, Shift-drag or use Pan mode to traverse dense clouds, or use the arrow keys to move the view. Show or focus core code, tests, and gems independently; sidebar highlights fly to a top-down view of the relevant star or system. Double-clicking a gem cloud pauses drift and expands that one existing system for a sharper, more separated view without loading another model.
+RubyLens updates its own existing default output, but refuses to overwrite a tracked file or an unrelated file at that path.
 
-## Generate a Showcase
+Custom output paths are written exactly where requested, may replace an existing file there, and are not added to Git's local excludes. Choose the path carefully and review the HTML before sharing it.
 
-Showcase is a standalone artistic presentation: it opens directly, rotates once per minute, and contains no Explorer controls or interactions.
+## Using Explorer
+
+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.
+- Search for classes, modules, and gems from the side panel.
+- Select a class, module, or dependency system to fly to a top-down comparison that keeps Core visible for scale.
+- Double-click a gem cloud to expand its existing stars.
+- 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 missing or the browser loses the context, RubyLens shows a warning rather than quietly drawing a partial galaxy.
+
+## Using Showcase
+
+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:
+
+```sh
+bundle exec rubylens showcase
+```
+
+Use `--details` when you want aggregate statistics and one-at-a-time cinematic labels:
 
 ```sh
-bundle exec rubylens showcase .
+bundle exec rubylens showcase --details
 ```
 
-The default output is `rubylens-showcase.html` in the project root. It is self-contained, offline, atomically written with mode `0600`, and locally excludes only that exact default path and its atomic temporary-file pattern. Explicit custom outputs remain unmanaged. RubyLens refuses to replace a tracked default or an unrelated existing file.
+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.
 
-The Showcase payload intentionally includes the project name, aggregate Ruby statistics, and numeric visual structure. It does not serialize declaration names, gem names, source text, comments, or paths. Its deterministic renderer prioritizes gem hubs and bounds large scenes to 50,000 plotted points, sampling hubs only if they alone exceed that budget. `prefers-reduced-motion` produces one stable frame instead of a continuous orbit.
+## Using Clip
 
-Ruby API:
+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.
 
-```ruby
-result = RubyLens.generate_showcase(path: ".")
-puts result.output_path
+```sh
+bundle exec rubylens clip
+bundle exec rubylens clip --details
 ```
 
-Showcase generation and viewing need no Chrome, Chromium, Ferrum, FFmpeg, Node, or HTTP server. The HTML discloses enough aggregate structure to characterize a codebase, so review it before sharing.
+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
+
+- **Core** is magenta. Its stars represent classes and modules from the project's main Ruby code.
+- **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. 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.
 
-The configurable multi-system design for repositories with many first-class applications or components is documented in [`docs/MONOREPO_BOUNDARIES.md`](docs/MONOREPO_BOUNDARIES.md). Reference-route experiments are paused and preserved in [`docs/REFERENCE_ROUTES_FUTURE.md`](docs/REFERENCE_ROUTES_FUTURE.md).
+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.
+
+RubyLens is not a type checker, whole-program call graph, source browser, route explorer, or per-dependency-star inspector.
+
+## Galaxy morphology
+
+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)
+
+*Representative endpoints inside the elliptical, spiral, and barred-spiral families.*
+
+Read the [accepted morphology design](docs/specs/2026-07-14-galaxy-morphology-design.md) or [stellar design research](docs/STELLAR_DESIGN_RESEARCH.md) for the full visual model.
+
+## CLI reference
+
+```text
+rubylens report [OPTIONS] [TARGET]
+rubylens clip [OPTIONS] [TARGET]
+rubylens showcase [OPTIONS] [TARGET]
+```
+
+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 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
+
+```ruby
+require "rubylens"
+
+report = RubyLens.generate_report(path: ".")
+puts report.output_path
+puts report.counts
+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.
 
 ## Development
 
-RubyLens supports Ruby 3.2 through 4.0. Contributors can activate the repository's pinned development Ruby before every Ruby command:
+RubyLens supports Ruby 3.2 through 4.0. The repository's `.ruby-version` and `.node-version` select the development runtimes. Activate Ruby with your version manager, then install the Ruby and JavaScript dependencies:
 
 ```sh
-source /opt/homebrew/share/chruby/chruby.sh
-chruby ruby-4.0.5
 bundle install
+npm ci
+```
+
+Run the Ruby and JavaScript unit tests:
+
+```sh
 bundle exec rake test
+npm run test:unit
+```
+
+Run the browser tests:
+
+```sh
+npx playwright install chromium
+npm run test:browser
+```
+
+Build the gem:
+
+```sh
 gem build rubylens.gemspec
 ```
 
-The TypeScript/Three.js visual study remains under `prototype/codebase-cosmos`. It is a design lab rather than a runtime dependency of the gem.
+The product and design contracts live in [PRODUCT.md](PRODUCT.md) and [DESIGN.md](DESIGN.md). Scale and benchmark notes live in [docs/PERFORMANCE.md](docs/PERFORMANCE.md).
+
+## License
+
+RubyLens is available under the [MIT License](LICENSE.txt).