ruact 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2178853f396d86e745518fafefe519f54ee2d941aefa956d14dce639567e0dc3
+  data.tar.gz: c48ae371e9ba39e90a4db67e6a815fc6e5b2a982d9fe87709b41b36e9b83ff6b
+SHA512:
+  metadata.gz: 3343bf04f0e4133aad881e65c97b1d701de33f00337a9eab1a98d9369d30dd2d355e7e566356505602a5041b575efc8547a142bc6ac997a8e36f753a919123bf
+  data.tar.gz: 328442e7e003bed71f9757805ad2620f89f57a49a8f5823b38a5082c7886618054dcfd0276bc68b59568514b2f1d6a69217e4213b5a947514f5a6d7e767b9324

data/.github/workflows/ci.yml

@@ -0,0 +1,166 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  rspec:
+    # Required status check — all 8 matrix combinations must pass to merge.
+    name: RSpec (Ruby ${{ matrix.ruby }} / Rails ${{ matrix.rails }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.2", "3.3"]
+        rails: ["7.0", "7.1", "7.2", "8.0"]
+    env:
+      RAILS_VERSION: ${{ matrix.rails }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+          working-directory: gem
+      - name: Run RSpec
+        working-directory: gem
+        run: bundle exec rspec --format progress
+
+  rubocop:
+    # Required status check.
+    name: RuboCop
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+          working-directory: gem
+      - name: Run RuboCop
+        working-directory: gem
+        run: bundle exec rubocop --format github
+
+  yard:
+    # Required status check — fails if any public method is missing YARD docs.
+    name: YARD Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+          working-directory: gem
+      - name: Validate YARD docs
+        working-directory: gem
+        run: bundle exec yard --fail-on-warning
+
+  benchmark:
+    # Required status check — fails if memory allocations exceed 120% of baseline.json.
+    name: Memory Benchmark
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+          working-directory: gem
+      - name: Run memory benchmark
+        working-directory: gem
+        run: bundle exec rake benchmark:memory
+
+  e2e:
+    # Required status check — both react@19.0.0 (pinned) and react@19.x (latest) must pass.
+    name: E2E (React ${{ matrix.react }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        react: ["19.0.0", "19.x"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+          working-directory: e2e
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: Install npm packages
+        working-directory: e2e
+        run: npm install
+      - name: Pin React version
+        working-directory: e2e
+        run: npm install react@${{ matrix.react }} react-dom@${{ matrix.react }}
+      - name: Build Vite assets
+        working-directory: e2e
+        run: npx vite build
+      - name: Run system tests
+        working-directory: e2e
+        env:
+          RAILS_ENV: test
+        run: bundle exec rails test:system
+      - name: Upload screenshots on failure
+        uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: e2e-screenshots-react-${{ matrix.react }}
+          path: e2e/tmp/screenshots
+          if-no-files-found: ignore
+
+  e2e-next:
+    # Non-blocking — failures open a GitHub issue with label react-next-compat.
+    # This job is NOT a required status check for branch protection.
+    name: E2E (React next — non-blocking)
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+          working-directory: e2e
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: Install npm packages
+        working-directory: e2e
+        run: npm install
+      - name: Pin React@next
+        working-directory: e2e
+        run: npm install react@next react-dom@next
+      - name: Build Vite assets
+        working-directory: e2e
+        run: npx vite build
+      - name: Run system tests
+        id: system-tests
+        working-directory: e2e
+        env:
+          RAILS_ENV: test
+        run: bundle exec rails test:system
+      - name: Upload screenshots on failure
+        uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: e2e-screenshots-react-next
+          path: e2e/tmp/screenshots
+          if-no-files-found: ignore
+      - name: Open compatibility issue on failure
+        if: failure()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: `react@next compatibility failure (run #${context.runNumber})`,
+              labels: ['react-next-compat'],
+              body: `CI run [#${context.runNumber}](${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}) failed against react@next on commit \`${context.sha}\`.\n\nTriaged within 2 weeks per NFR7. Does not block release.`
+            });

data/.rubocop.yml

@@ -0,0 +1,89 @@
+require:
+  - rubocop/cop/ruact
+
+plugins:
+  - rubocop-rspec
+  - rubocop-performance
+
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  Exclude:
+    - "vendor/**/*"
+    - "sig/**/*"
+
+# --- Layout ---
+Layout/LineLength:
+  Max: 120
+
+# --- Metrics ---
+Metrics/MethodLength:
+  Max: 30
+  CountAsOne: ["array", "hash", "heredoc"]
+  # Note: case/when chain in serializer.rb and converter is intentional by architecture decision
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "Gemfile"
+    - "lib/tasks/**/*.rake"
+
+Naming/VariableNumber:
+  Exclude:
+    - "lib/tasks/**/*.rake"
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/ModuleLength:
+  Max: 150
+  Exclude:
+    - "spec/**/*"
+
+Metrics/AbcSize:
+  Max: 50
+  # Note: PoC methods (rsc_render, each, convert_element) will be refactored
+  # in later stories. Current values reflect tech debt, not design intent.
+
+Metrics/CyclomaticComplexity:
+  Max: 20
+
+Metrics/PerceivedComplexity:
+  Max: 20
+
+# --- Style ---
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+# --- RSpec ---
+RSpec/MultipleExpectations:
+  Max: 5
+
+RSpec/ExampleLength:
+  Max: 25
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 7
+
+RSpec/NestedGroups:
+  Max: 4
+
+RSpec/DescribeClass:
+  Enabled: false
+
+# --- Custom Ruact Cops ---
+Ruact/NoIoInFlight:
+  Enabled: true
+
+Ruact/NoSharedState:
+  Enabled: true
+
+Ruact/NoExtendSelf:
+  Enabled: true

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-24
+
+### Added
+
+- **ERB preprocessor** — PascalCase RSC component tags (`<Button />`, `<LikeButton postId={@post.id} />`) are transformed to Flight placeholders in ERB templates before Ruby evaluation.
+- **`<Suspense>` support** — `<Suspense fallback="Loading...">` in ERB templates maps to React Suspense boundaries in the Flight payload.
+- **React Flight wire format serializer** — Full Ruby-to-Flight protocol implementation covering: nil, booleans, integers, floats (NaN/Infinity/-0), strings (with `$` escaping), arrays, hashes, `Time`/`DateTime`, large strings (T rows), `ReactElement`, `SuspenseElement`, and `ClientReference`.
+- **`Ruact::Controller` concern** — Include in `ApplicationController` to enable RSC rendering. Provides `rsc_render`, RSC request detection (`text/x-component` / `RSC-Request: 1` header), HTML shell generation with inline `__FLIGHT_DATA`, and Flight-aware `redirect_to`.
+- **Streaming mode** — When `ActionController::Live` is included, Flight rows are streamed to the client as they are produced (Suspense-aware).
+- **Client component resolution** — `Ruact::ClientManifest` reads `public/react-client-manifest.json` (generated by the Vite plugin) and resolves component names to `ClientReference` objects via a dual-path resolver.
+- **`Ruact::Serializable` mixin** — `rsc_props` DSL for declaring safe prop attributes on Ruby model objects.
+- **Install generator** — `rails generate ruact:install` scaffolds the initializer, Vite config patch, and JavaScript entry point.
+- **`rsc:doctor` Rake task** — Checks manifest presence, Vite server accessibility, controller setup, and streaming mode configuration.
+- **`vite-plugin-ruact`** — Vite plugin (npm package, co-versioned) that scans `"use client"` components and emits `public/react-client-manifest.json`.
+- **Client-side navigation** — JavaScript `rsc-router.js` intercepts same-origin link clicks and form submissions, fetches Flight payloads, and updates the React tree without full-page reloads.
+- **Error overlay** — Development-mode React error boundary with dismissible overlay for Flight parse and rendering errors.
+- **RSpec test suite** — 223 examples covering all modules: Flight serializer, ERB preprocessor, HTML converter, render pipeline, controller, client manifest, serializable, install generator, and `rsc:doctor`.
+- **Memory benchmark** — `rake benchmark:memory` enforces a 120% allocation regression gate against `spec/benchmarks/baseline.json`.
+- **CI matrix** — GitHub Actions: RSpec across Ruby 3.2 × 3.3 × Rails 7.0 × 7.1 × 7.2 × 8.0; RuboCop; YARD docs; memory benchmark; E2E system tests against React 19.0.0 and 19.x (Capybara + Cuprite); non-blocking React@next job with auto-issue on failure.
+- **E2E test app** — `e2e/` Rails app (no DB, in-memory Post model) with full CRUD system tests validating the complete request cycle.
+
+[Unreleased]: https://github.com/luizcg/ruact/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/luizcg/ruact/releases/tag/v0.1.0

data/README.md

@@ -0,0 +1,35 @@
+# Ruact
+
+TODO: Delete this and the text below, and describe your gem
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/ruact`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+## Installation
+
+TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/ruact.

data/RELEASING.md

@@ -0,0 +1,203 @@
+# Releasing ruact
+
+This document describes the complete release process for `ruact`. Following these steps in order enables any maintainer to cut a release independently.
+
+The gem and the `vite-plugin-ruact` npm package share the same version number and are **always released together** as a single operation.
+
+---
+
+## Pre-Release Checklist
+
+Before starting, confirm all of the following:
+
+- [ ] All CI jobs are green on `main` (rspec matrix, rubocop, yard, benchmark, e2e)
+- [ ] No open issues or PRs labelled `release-blocker`
+- [ ] `gem/ruact.gemspec` has no TODO placeholder values (`summary`, `homepage_uri`, `source_code_uri`, `allowed_push_host` must all be set to real values before `gem build` will succeed)
+- [ ] You have a RubyGems account with push access to `ruact` and an OTP authenticator configured (MFA is required — `rubygems_mfa_required: true`)
+- [ ] You have an npm account with publish access to `vite-plugin-ruact`
+- [ ] You have GPG or SSH commit signing configured (recommended)
+
+---
+
+## Version Decision (SemVer)
+
+Given the current version `X.Y.Z`, choose the next version:
+
+| Change type | Version bump | Example |
+|---|---|---|
+| Breaking change (see below) | Major: `X+1.0.0` | `0.1.0` → `1.0.0` |
+| New feature, backwards-compatible | Minor: `X.Y+1.0` | `0.1.0` → `0.2.0` |
+| Bug fix, patch | Patch: `X.Y.Z+1` | `0.1.0` → `0.1.1` |
+
+**What counts as a breaking change**: any change to the public API that requires consumers to update their code — e.g. renaming a public method, changing method signatures, removing a configuration option, or changing the Flight wire format in a non-backwards-compatible way.
+
+---
+
+## Release Steps
+
+### 1. Create a release branch
+
+```bash
+git checkout -b release/v{X.Y.Z}
+```
+
+### 2. Bump the gem version
+
+Edit `gem/lib/ruact/version.rb`:
+
+```ruby
+module Ruact
+  VERSION = "{X.Y.Z}"
+end
+```
+
+### 3. Bump the npm package version
+
+Edit `packages/vite-plugin-ruact/package.json`:
+
+```json
+{
+  "version": "{X.Y.Z}"
+}
+```
+
+### 4. Update `gem/CHANGELOG.md`
+
+1. Move all items under `## [Unreleased]` into a new section `## [{X.Y.Z}] - {YYYY-MM-DD}`.
+2. Add a new empty `## [Unreleased]` section at the very top (above the new release section).
+3. Add or update the link footer at the bottom:
+   ```
+   [Unreleased]: https://github.com/luizcg/ruact/compare/v{X.Y.Z}...HEAD
+   [{X.Y.Z}]: https://github.com/luizcg/ruact/compare/v{PREV}...v{X.Y.Z}
+   ```
+4. If this release contains breaking changes, ensure the section includes a `[BREAKING]` subsection with a **Migration Guide** (see "Breaking Changes" section below).
+
+### 5. Update `packages/vite-plugin-ruact/CHANGELOG.md`
+
+Same format as step 4 for the npm package changelog.
+
+### 6. Commit the release
+
+```bash
+git add gem/lib/ruact/version.rb \
+        packages/vite-plugin-ruact/package.json \
+        gem/CHANGELOG.md \
+        packages/vite-plugin-ruact/CHANGELOG.md
+git commit -m "Release v{X.Y.Z}"
+```
+
+### 7. Push the release branch and open a PR
+
+```bash
+git push origin release/v{X.Y.Z}
+```
+
+Open a PR from `release/v{X.Y.Z}` → `main`. Wait for CI to go green before continuing.
+
+### 8. Merge, verify CI, and tag
+
+Merge the PR. Confirm all CI jobs pass on the merge commit, then tag the verified merge commit:
+
+```bash
+git checkout main
+git pull origin main
+git tag v{X.Y.Z}
+git push origin v{X.Y.Z}
+```
+
+> **Why tag after merge?** Tagging after CI passes on the merge commit ensures the tag always points to a verified, releasable commit. Tagging the branch commit before merge risks tagging code that fails CI after merge.
+
+### 9. Publish the gem to RubyGems
+
+```bash
+cd gem
+gem build ruact.gemspec
+gem push ruact-{X.Y.Z}.gem
+# Enter OTP when prompted (MFA is required)
+rm ruact-{X.Y.Z}.gem
+```
+
+> **Note**: `spec.files` in the gemspec is populated via `git ls-files -z`. The files `CHANGELOG.md`, `RELEASING.md`, and `SECURITY.md` must be committed to git to appear in the gem tarball. Verify with:
+> ```bash
+> gem contents ruact-{X.Y.Z} | grep -E 'CHANGELOG|RELEASING|SECURITY'
+> ```
+
+### 10. Publish the npm package
+
+```bash
+cd packages/vite-plugin-ruact
+npm publish
+```
+
+### 11. Create a GitHub Release
+
+1. Go to [Releases](https://github.com/luizcg/ruact/releases/new)
+2. Select tag `v{X.Y.Z}`
+3. Title: `v{X.Y.Z}`
+4. Body: paste the `## [{X.Y.Z}]` section from `gem/CHANGELOG.md`
+5. Publish
+
+---
+
+## Breaking Changes
+
+When a release contains a breaking change:
+
+1. Bump the **major** version (e.g. `0.1.0` → `1.0.0`).
+2. Mark the CHANGELOG entry with `[BREAKING]` and include a **Migration Guide** sub-section:
+
+   ```markdown
+   ## [1.0.0] - YYYY-MM-DD
+
+   ### Changed
+   - [BREAKING] `rsc_render` now requires explicit `template:` keyword for non-standard action names
+
+   #### Migration Guide
+
+   **Before:**
+   ```ruby
+   render_rsc "posts/custom"
+   ```
+   **After:**
+   ```ruby
+   rsc_render template: "posts/custom"
+   ```
+   ```
+
+3. Announce the breaking change prominently in the GitHub Release body.
+
+---
+
+## Rollback
+
+If a release contains a critical defect and must be pulled:
+
+**RubyGems** (within 30 days):
+```bash
+gem yank ruact -v {X.Y.Z}
+```
+
+**npm** (within 72 hours):
+```bash
+npm unpublish vite-plugin-ruact@{X.Y.Z}
+```
+
+After yanking, cut a patch release (`{X.Y.Z+1}`) with the fix immediately. Do not leave the version yanked without a replacement.
+
+---
+
+## Troubleshooting
+
+**`gem push` fails with "MFA required"**: Run `gem signin` first and ensure your OTP authenticator is set up at https://rubygems.org/settings/edit.
+
+**Files missing from gem tarball**: The gemspec uses `git ls-files -z`. Ensure all new files (e.g. `CHANGELOG.md`) are committed to git before running `gem build`.
+
+**CI fails on release branch**: Fix the issue on the release branch and push the fix. Wait for CI to pass before tagging. If you already pushed a tag pointing to a broken commit, delete it and recreate after the fix:
+```bash
+git tag -d v{X.Y.Z}                        # delete local tag
+git push origin :refs/tags/v{X.Y.Z}        # delete remote tag
+# fix the issue, merge, then re-tag from the correct commit
+git checkout main && git pull origin main
+git tag v{X.Y.Z} && git push origin v{X.Y.Z}
+```
+Do not use `git push --force` on tags — force-pushing a tag rewrite history for anyone who has already fetched it.

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+Dir["lib/tasks/**/*.rake"].each { |f| load f }
+
+task default: :spec

data/SECURITY.md

@@ -0,0 +1,62 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest patch release of the current minor version is actively maintained for security fixes.
+
+| Version | Supported |
+|---------|-----------|
+| 0.1.x   | ✅ Yes    |
+
+Once a new minor version is released, the previous minor version receives security fixes for **90 days** after the new release, then it is no longer supported.
+
+---
+
+## Reporting a Vulnerability
+
+**Do not open a public GitHub issue for security vulnerabilities.**
+
+Please use [GitHub Security Advisories](https://github.com/luizcg/ruact/security/advisories/new) to report vulnerabilities privately. This keeps the report confidential until a fix is prepared and released.
+
+### What to include
+
+- A description of the vulnerability and its potential impact
+- Steps to reproduce (a minimal proof-of-concept if possible)
+- The version(s) of `ruact` you tested against
+- Any suggested mitigations or patches, if you have them
+
+### Response timeline
+
+| Milestone | Target |
+|-----------|--------|
+| Initial acknowledgement | **Within 14 days** of receiving the report |
+| Triage and severity assessment | Within 30 days |
+| Patch release for confirmed vulnerabilities | Within 90 days |
+
+If a reported vulnerability is accepted, you will be credited in the CHANGELOG and GitHub Security Advisory unless you prefer to remain anonymous.
+
+If a report is declined (e.g. the reported behaviour is by design or the impact is below our threshold), we will explain our reasoning.
+
+---
+
+## Disclosure Policy
+
+We follow [Coordinated Vulnerability Disclosure](https://vuls.cert.org/confluence/display/CVD): we ask that you give us a reasonable amount of time to fix the issue before publishing details publicly. We aim to meet the timelines above so that you are not kept waiting.
+
+---
+
+## Out of Scope
+
+The following are generally not considered security vulnerabilities for this gem:
+
+- Vulnerabilities in Rails, React, Nokogiri, or other dependencies — report those to the respective projects
+- Theoretical attacks with no practical exploitability
+- Denial-of-service via extremely large inputs (unless the gem has no guard and the impact is severe)
+
+---
+
+## Contact
+
+Primary channel: [GitHub Security Advisories](https://github.com/luizcg/ruact/security/advisories/new) (preferred — keeps reports private)
+
+Maintainer: Luiz Garcia — see GitHub profile for additional contact options.