rubylens 0.1.0.pre.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a68f44779cf227639060ec998c28dca42887c018c1840acb9cb052f11b1fc308
-  data.tar.gz: 0aa7d34a9b43f8796052d1a8a4106a424ae074ebd3785ff90abc718734b510e8
+  metadata.gz: 59011e25213524d532e90ea20c237e82e8e3d615c37767bdf1d46038c64921be
+  data.tar.gz: feddff17e812a22b342c9e6c8ff65f06a58b45531e41b900e60dd984a31f3efc
 SHA512:
-  metadata.gz: a58596bc4b75bcff08991750258d18d3deae534fc21d78e505b098091986c32a3226a962a4c102cc9b0eb518efaf0258b131338a065b3845f89ea3a8db9fb01a
-  data.tar.gz: cc8321d3b96900926f4d6cfaf7d24b18660eb5f1d597b00056b3b3383f2d02050af5fc8bafd22276cb7063d7ba9633c3bfb8ced2f8a52229291641f0d22789d8
+  metadata.gz: 17d770ab8bbb1b651c1e7c6680ad27b6db38b4614d438c3ffb0b85c1919cec1e51c7fb2be447d61004c54ca23d4df7292ffc006bdcabd6fc04eaba9efcd2f433
+  data.tar.gz: f36f788b765f4cc60037b251574f9c22da8e65f4a4b78702a317e0443fcc4e832fd1572863731ab0d9f1593e751b749fd4e07cf9ea0cd37bc04dc18cef615ed1

data/README.md

@@ -1,67 +1,190 @@
 # 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.
+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.
 
-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 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)
 
-## Generate a report
+*Five galaxy families rendered from the same synthetic codebase data.*
 
-Add RubyLens to the bundle of the project you want to visualize, then run:
+> [!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`:
+
+```ruby
+gem "rubylens", require: false
+```
+
+Install the bundle, then generate an Explorer:
 
 ```sh
-bundle exec rubylens report .
+bundle install
+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 a browser with WebGL2. No server is required.
 
-Ruby API:
+RubyLens uses the current directory when you omit `TARGET`. To visualize a subdirectory while using the current project's bundle and root lockfile, run:
 
-```ruby
-result = RubyLens.generate_report(path: ".")
-puts result.output_path
-puts result.counts
-puts result.warnings
+```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.
+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.generate` remains a thin alias for `RubyLens.generate_report`.
+But the HTML still describes your project:
 
-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.
+- 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.
 
-## Generate a Showcase
+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.
 
-Showcase is a standalone artistic presentation: it opens directly, rotates once per minute, and contains no Explorer controls or interactions.
+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`.
+
+RubyLens updates its own existing default output, but refuses to overwrite a tracked file or an unrelated file at that path.
+
+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.
+
+## Using Explorer
+
+Explorer lets you search and move through Core code, Tests, and Gems while the galaxy continues to drift.
+
+- 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 unavailable or its context is lost, RubyLens stops the artwork and shows an explicit warning instead of silently presenting a sampled or incomplete galaxy.
+
+## Using Showcase
+
+Showcase is autonomous 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 .
+bundle exec rubylens showcase
 ```
 
-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.
+Use `--details` when you want aggregate statistics and one-at-a-time 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.
+```sh
+bundle exec rubylens showcase --details
+```
 
-Ruby API:
+Showcase also requires WebGL2. A browser with `prefers-reduced-motion` enabled receives one stable frame with no cinematic labels.
 
-```ruby
-result = RubyLens.generate_showcase(path: ".")
-puts result.output_path
+## 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. It does not claim that references form a complete call graph, and it 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.
+
+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.
+
+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 showcase [OPTIONS] [TARGET]
 ```
 
-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.
+Both 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`.
+
+## Ruby API
 
-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).
+```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
+```
+
+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).