ruact 0.0.11 → 0.0.13

data/CONTRIBUTING.md

@@ -0,0 +1,233 @@
+# Contributing to ruact
+
+Thanks for wanting to change something here. This guide takes you from a fresh clone to an open pull
+request, and everything it asks you to run, you can run — with this repository and nothing else.
+
+## What this repository is
+
+`luizcg/ruact` is one repository holding three things that ship together:
+
+| Directory | What lives there |
+|---|---|
+| `lib/` | the Ruby library — the ERB preprocessor, the render pipeline, the Flight wire format, the Rails integration, the generators and the Rake tasks |
+| `vendor/javascript/vite-plugin-ruact/` | the Vite plugin — it scans for `"use client"`, emits the client manifest, and generates the typed server-function accessors |
+| `vendor/javascript/ruact-server-functions-runtime/` | the browser-side runtime those generated accessors call |
+
+The two JavaScript packages are **bundled, not published**. A host app never installs them from npm:
+`rails generate ruact:install` writes a `vite.config.js` that imports the plugin by absolute path off the
+installed gem. That has one consequence worth stating up front, because it is what makes the rest of this
+document short — **pointing a Rails app at your checkout of the gem points it at your checkout of the Vite
+plugin too.** There is nothing to link separately, and nothing else to clone. This repository has no
+submodules.
+
+## Prerequisites
+
+| Tool | Version | Why |
+|---|---|---|
+| Ruby | >= 3.2 | the floor in `ruact.gemspec`; CI runs 3.2 and 3.3 |
+| Node.js | 20 | the JavaScript suite and the asset build only — ruact runs no Node process in production |
+| Bundler | any recent | `gem install bundler` |
+
+You do not need a Rails **app** to work on this gem, and you do not install Rails by hand: the `Gemfile`
+pins it to `RAILS_VERSION`, defaulting to 8.0, so `bundle install` brings it. What keeps the suite fast is
+that `spec/support/rails_stub.rb` loads only Rails' core and adds test-only writers on top — the request
+cycle (`action_controller`, `action_view`) is loaded by the handful of specs that actually need it, and by
+nothing else.
+
+## Setup
+
+```bash
+git clone https://github.com/luizcg/ruact.git
+cd ruact
+bundle install
+```
+
+That is the whole setup for a Ruby-side change. If you are touching the Vite plugin or the browser
+runtime, install their dependencies too:
+
+```bash
+cd vendor/javascript/ruact-server-functions-runtime && npm install
+cd ../vite-plugin-ruact && npm ci
+```
+
+The first install is not decoration: the plugin's test run reaches into the runtime package, which keeps
+`react` in its own dependencies.
+
+## Running the checks
+
+These are the jobs in [`.github/workflows/ci.yml`](.github/workflows/ci.yml), which runs on every push and
+every pull request. Running them locally first is the difference between one round and four.
+
+<!-- ci-jobs:begin -->
+
+| CI job | What it checks |
+|---|---|
+| `rspec` | the Ruby suite, on Ruby 3.2/3.3 × Rails 7.0/7.1/7.2/8.0 — eight cells |
+| `rubocop` | style, plus the three custom cops below |
+| `yard` | every public method carries YARD documentation |
+| `js` | the Vite plugin's vitest suite, including its Ruby↔JS byte-parity cases, and a type-level test over the generated accessors |
+| `benchmark` | render-pipeline allocations against a recorded baseline |
+| `name-propagation` | greps the tree for names retired before v0.1.0 |
+| `gate` | that `CHANGELOG.md` gained something if this branch changed what the published gem contains, and that a version bump is one legal semver step to a version nothing has released |
+
+<!-- ci-jobs:end -->
+
+There is one more job, `release`, which publishes to RubyGems. It never runs on a pull request, and on a
+push to `main` it publishes only when `lib/ruact/version.rb` names a version that carries no tag — which is
+a thing a maintainer does deliberately, in a pull request of its own. See [RELEASING.md](RELEASING.md) for
+the release process itself — this document deliberately describes none of it, so the two cannot drift apart.
+
+Locally:
+
+```bash
+bundle exec rspec
+bundle exec rubocop --format github
+rm -rf .yardoc doc && bundle exec yard --fail-on-warning
+bundle exec rake benchmark:memory
+bin/release-gate origin/main HEAD
+```
+
+and, for the `js` job:
+
+```bash
+cd vendor/javascript/vite-plugin-ruact
+npm test
+npm run typecheck
+```
+
+To reproduce one matrix cell other than the default — `RAILS_VERSION` is what the eight `rspec` cells vary,
+and unset means 8.0:
+
+```bash
+RAILS_VERSION=7.2 bundle install && bundle exec rspec
+```
+
+## Trying your working tree in a real app
+
+The suite is fast and the gates are strict, and neither tells you whether your change works in a Rails
+app. This does, in about two minutes. `RUACT` is the absolute path to your clone.
+
+```bash
+export RUACT=/absolute/path/to/your/ruact
+
+rails new myapp --skip-javascript
+cd myapp
+printf '\ngem "ruact", path: "%s"\n' "$RUACT" >> Gemfile
+bundle install
+bin/rails generate ruact:install
+bin/dev
+```
+
+No published gem and no published npm package take part: the `path:` source points Bundler at your
+checkout, and the generated `vite.config.js` imports the Vite plugin from inside it. Both halves of your
+change are live.
+
+Give it something to render — a component in `app/javascript/components/`:
+
+```jsx
+"use client";
+import { useState } from "react";
+
+export function LikeButton({ likes }) {
+  const [count, setCount] = useState(likes);
+  return <button onClick={() => setCount(count + 1)}>{count} likes</button>;
+}
+```
+
+a controller action, and a view that uses the component by name:
+
+```erb
+<h1>Home</h1>
+<LikeButton likes={@likes} />
+```
+
+`bin/dev` runs Rails and Vite together. Load the page and the button counts up.
+
+## Four gates that fail for reasons your diff does not show
+
+Most of CI fails where you expect. These four do not, so they are worth knowing before they surprise you.
+
+1. **`spec/readme_spec.rb`** — `README.md` is pinned **byte for byte** in places: the quick-start block and
+   the demo image reference are compared against literals in the spec, the file is allowed exactly one raw
+   `<img>`, and a `path:` gem source is forbidden there because a reader who copies one installs nothing.
+   Edit the README casually and this goes red.
+
+   ⚠️ **One of its assertions is repository-wide despite living in a README spec.** It runs `git ls-files`
+   over the whole repository and fails if any tracked file is a `.gif`, `.mp4`, `.webm` or `.webp` — media
+   committed here would ship inside every built `.gem` and stay in the clone history forever. So **no
+   document in this repository can carry an image**, including this one. Media lives with the documentation
+   site and is referenced by absolute URL.
+
+   ⚠️ **YARD reads `README.md`.** Curly braces in its prose — `{@likes}`, `{Foo#bar}` — are link macros to
+   YARD, and an unresolvable one turns the `yard` job red for a README edit. Write them as `&#123;` and
+   `&#125;` there.
+
+2. **`spec/readme_demo_message_spec.rb`** — the second half of that pin, covering the demo's message.
+
+3. **`spec/benchmarks/render_pipeline_benchmark_spec.rb`** — an **allocation** baseline at ×1.20 tolerance
+   against `spec/benchmarks/baseline.json`, shared by matrix cells that legitimately differ by around 9%.
+   When it fails, read the header comment at the top of that file before doing anything: it explains how to
+   tell a real regression from accumulated drift, and how to regenerate the baseline if it is drift.
+
+4. **Three custom RuboCop cops**, in `lib/rubocop/cop/ruact/` and enabled in `.rubocop.yml` —
+   `Ruact/NoSharedState`, `Ruact/NoIoInFlight` and `Ruact/NoExtendSelf`. Between them they say that data
+   flows through explicit arguments rather than shared mutable state, that `lib/ruact/flight/**` stays a
+   pure value transformation, and that modules expose explicit class methods.
+
+   Custom cops are the least discoverable failure a newcomer can hit, which is why they are named here —
+   but **the cop source is the authority for what each one actually detects**, and each detects a subset of
+   the rule it is named for rather than the rule entire. `Ruact/NoExtendSelf` also rejects a bare
+   `module_function`, which its name does not suggest. Read the file before assuming a pattern is either
+   caught or allowed.
+
+And one habit rather than a gate: run `yard` after `rm -rf .yardoc doc`, as the block above does. A warm
+cache hides warnings that CI, which checks out fresh, still reports.
+
+## Where a change goes
+
+Every destination below is one you can reach.
+
+| Change | Where |
+|---|---|
+| anything under `lib/`, `app/`, `exe/`, `sig/`, `spec/` | **here** — `luizcg/ruact` |
+| a typo in `README.md`, `CHANGELOG.md` or this file | **here** |
+| the Vite plugin | **here**, at `vendor/javascript/vite-plugin-ruact/` — see the note below |
+| the browser runtime for server functions | **here**, at `vendor/javascript/ruact-server-functions-runtime/` |
+| the documentation site at `ruact.dev` | not in this repository — [open an issue](https://github.com/luizcg/ruact/issues) |
+| roadmap, architecture decisions, design | not in this repository — [open an issue](https://github.com/luizcg/ruact/issues) or a discussion |
+
+**About the Vite plugin.** There is a `vite-plugin-ruact` package on npm. It is **superseded**: nothing in
+ruact installs it, and the plugin that actually runs is the vendored one in this repository. Send plugin
+changes here.
+
+## Where the design work happens
+
+Roadmap, architecture decisions and story planning live in a private repository, so the reasoning behind a
+change is not always visible from here. That does not gate anything: open an issue or a discussion, and the
+outcome of that thinking comes back to you in the thread — you do not need access to propose a change,
+argue for one, or land one.
+
+## Opening the pull request
+
+Branch off `main`, keep one topic per pull request, and open it against `luizcg/ruact`. Before you do:
+
+- [ ] `bundle exec rspec` passes.
+- [ ] `bundle exec rubocop --format github` is clean.
+- [ ] `rm -rf .yardoc doc && bundle exec yard --fail-on-warning` passes, and every new public method has a
+      YARD comment with `@param` and `@return`.
+- [ ] `# frozen_string_literal: true` is the first line of every new Ruby file.
+- [ ] Nothing you added lives in `Ruact::`'s way: gem code stays under `Ruact::`, wire-format code under
+      `Ruact::Flight::`, and no Ruby or Rails core class is reopened.
+- [ ] No `extend self` and no bare `module_function` — explicit class methods or a class instead.
+- [ ] If you touched the Vite plugin or the runtime, `npm test` and `npm run typecheck` pass in
+      `vendor/javascript/vite-plugin-ruact`.
+- [ ] `bin/release-gate origin/main HEAD` passes. If your branch changes anything that goes inside the
+      published gem, it asks [CHANGELOG.md](CHANGELOG.md) for a new bullet under `[Unreleased]` — written
+      for a reader who did not see the diff.
+
+Describe what the change does and why in the pull request body. If it fixes a reported bug, link the issue.
+
+Security issues do **not** go in a pull request — see [SECURITY.md](SECURITY.md) for private reporting.
+
+By contributing you agree that your contribution is licensed under the MIT license in
+[LICENSE.txt](LICENSE.txt).

data/README.md

@@ -22,14 +22,14 @@ rails new myapp --skip-javascript && cd myapp
 # 2. Add the gem
 bundle add ruact
 
-# 3. Write the config, the layout wiring and an AGENTS.md — then run npm install
+# 3. Write the config and an AGENTS.md (no layout of yours is edited) — then run npm install
 rails generate ruact:install
 
 # 4. Rails + Vite, one command
 bin/dev
 ```
 
-That is the whole install. The [Getting Started guide](https://ruact.dev/docs/getting-started) picks it up from here — first component, first scaffold, `ruact:doctor`. Already have an app? Start at step 2, then read [Progressive migration](https://ruact.dev/docs/guides/progressive-migration) — ruact renders one action at a time and leaves the rest of your views alone.
+That is the whole install. The [Getting Started guide](https://ruact.dev/docs/getting-started) picks it up from here — first component, first scaffold, `ruact:doctor`. Already have an app? Start at step 2, then read [Progressive migration](https://ruact.dev/docs/guides/progressive-migration) — ruact renders only the controllers you include it in and leaves the rest of your views alone.
 
 ## How it works
 
@@ -58,7 +58,9 @@ export function PostCard({ post, author }) {
 }
 ```
 
-Rails serializes `@post` and `@author` as Ruby values, sends the component tree as a [Flight](https://ruact.dev/docs/concepts/flight-wire-format) payload, and React hydrates it in the browser. No JSON ceremony, no duplicate routes, no Node.js in production.
+Capitalized tag means React. Lowercase stays HTML. `"use client"` is the only directive you need to learn.
+
+Your ERB view renders on the server the way it always did, and ruact sends the result to the browser as a React tree — in the same [wire format](https://ruact.dev/docs/concepts/flight-wire-format) React uses for Server Components, implemented in Ruby. The data the view needs is inlined in the page, so React renders immediately, without a fetch. Node builds the bundle with Vite and is needed nowhere else.
 
 ## Call Rails from React
 
@@ -86,17 +88,17 @@ The verb decides — there is no per-action DSL and no second endpoint. The expo
 
 ## What you get
 
-Every item below is shipped in this gem at v0.0.9:
+Every item below is shipped in this gem at v0.0.11:
 
 - **ERB as server components** — `include Ruact::Controller`, then use your components by name in the views you already have: capitalized is React, lowercase stays HTML. [Docs](https://ruact.dev/docs/concepts/erb-as-server-components)
 - **`"use client"`** — the one directive that marks a file as client-side. The bundled Vite plugin scans for it and writes the manifest. [Docs](https://ruact.dev/docs/concepts/use-client)
-- **Server functions and queries** — `include Ruact::Server` and `Ruact::Query` + `useQuery`, both reachable through a typed module generated from your route table. [Docs](https://ruact.dev/docs/api/server-actions)
-- **Props are an allowlist** — `include Ruact::Serializable` + `ruact_props :id, :title`; other columns never cross. [Docs](https://ruact.dev/docs/api/serializable)
+- **Server functions and queries** — `include Ruact::Server` and `Ruact::Query` + `useQuery`, both reachable through a module generated from your route table. A query's declared keywords become an exact TypeScript signature; an action's accessor is typed to accept an object or a `FormData` and resolve whatever the action answers. [Docs](https://ruact.dev/docs/api/server-actions)
+- **An opt-in allowlist for props** — by default a model prop is serialized with `as_json`, so every attribute crosses and the log says so. `include Ruact::Serializable` + `ruact_props :id, :title` makes it an allowlist, and `strict_serialization` (on in production) turns the permissive path into an error rather than a warning. [Docs](https://ruact.dev/docs/api/serializable)
 - **Validation errors round-trip** — `ruact_errors(record)` hands React `{ title: ["can't be blank"] }` without a serializer. [Docs](https://ruact.dev/docs/api/server-actions)
 - **Signed record references** — `Ruact.signed_global_id(record, for:, expires_in:)` out, `Ruact.locate_signed(token, for:)` back in; a tampered token is a `400`, not a lookup. [Docs](https://ruact.dev/docs/api/server-actions)
 - **Client-side navigation** — link interception, scroll restoration and redirect-after-POST, derived from your Rails routes. [Docs](https://ruact.dev/docs/concepts/navigation)
 - **A CRUD generator** — `rails generate ruact:scaffold Post title:string body:text` delegates the model, migration and route to Rails' own `resource` generator, then adds the ruact layer. Plain semantic HTML by default; `--shadcn` opts into the Tailwind/shadcn path. It does not run migrations — `rails db:migrate` is still yours. [Docs](https://ruact.dev/docs/api/scaffold)
-- **`bin/rails ruact:doctor`** — eight checks over the manifest, Vite, the layout and streaming; exits `1` when one fails. [Docs](https://ruact.dev/docs/api/ruact-doctor)
+- **`bin/rails ruact:doctor`** — nine checks over the manifest, Vite, the layout, the client-component CSS and streaming; exits `1` when one fails. [Docs](https://ruact.dev/docs/api/ruact-doctor)
 - **One runtime dependency** — `nokogiri`. Rails itself is not a declared dependency of this gem.
 
 ## AI tools and coding agents
@@ -112,6 +114,12 @@ That is the whole adaptation, and it holds for any tool that outputs standard Re
 
 For agents driving the app rather than writing one component: `rails generate ruact:install` writes an `AGENTS.md` into your app, [ruact.dev/llms.txt](https://ruact.dev/llms.txt) serves the same context to tools that fetch from the web, and `bin/rails ruact:doctor -- --json` / `bin/rails ruact:routes -- --json` emit machine-readable output (experimental — `schema_version: 0`, and the `--` separator is required).
 
+## Where ruact fits
+
+**A good fit:** a Rails monolith that needs real React on real screens — dashboards, editors, admin tools, anything with interaction that ERB alone makes painful — with one team shipping both sides and no appetite for a second application to keep in sync.
+
+**Not a fit yet:** pages that must render without JavaScript, or content search engines need to read out of the HTML. ruact renders client-side from a payload inlined in the page; there is no server-rendered HTML for the React tree. That is a real gap, not a roadmap wink — if the page is your SEO surface, keep it in ERB (the two coexist in the same app, per-view) or use something that server-renders.
+
 ## Compatibility
 
 | | Version | Where that comes from |
@@ -128,7 +136,7 @@ Everything lives at [ruact.dev](https://ruact.dev):
 - [Getting Started](https://ruact.dev/docs/getting-started) — from `rails new` to a rendered component
 - [Why ruact?](https://ruact.dev/docs/why-ruact) — where it sits next to Hotwire and Inertia
 - [Server functions & queries](https://ruact.dev/docs/api/server-actions) — the full request/response contract
-- [Progressive migration](https://ruact.dev/docs/guides/progressive-migration) — adopting it one action at a time
+- [Progressive migration](https://ruact.dev/docs/guides/progressive-migration) — adopting it one controller at a time
 - [Testing](https://ruact.dev/docs/guides/testing) — render assertions on the server side
 - [Changelog](CHANGELOG.md) — also published at [ruact.dev/docs/changelog](https://ruact.dev/docs/changelog)
 
@@ -136,6 +144,8 @@ Everything lives at [ruact.dev](https://ruact.dev):
 
 Bug reports and pull requests are welcome at [github.com/luizcg/ruact/issues](https://github.com/luizcg/ruact/issues).
 
+Setup, the checks a PR runs, and how to try your working tree in a real Rails app: [CONTRIBUTING.md](CONTRIBUTING.md).
+
 Release process: [RELEASING.md](RELEASING.md). Security policy and private reporting: [SECURITY.md](SECURITY.md).
 
 ## License