ruact 0.0.4 → 0.0.6

data/vendor/javascript/vite-plugin-ruact/manifest-contract.test.mjs

@@ -0,0 +1,182 @@
+// Story 13.5 (FR100) — buildManifest contract extraction.
+//
+// A component opts into a call-site contract by exporting `__ruactContract`.
+// The scanner extracts it NAMES-ONLY into an optional `contract` field on the
+// manifest entry. A component without the export emits NO `contract` field
+// (byte-additive). A malformed declaration is warned + skipped (fail open).
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { buildManifest, extractContract } from "./index.js";
+
+let dir;
+beforeEach(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), "ruact-13-5-"));
+});
+afterEach(() => {
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function writeComponent(name, body) {
+  fs.writeFileSync(path.join(dir, name), body);
+}
+
+describe("buildManifest — contract extraction (Story 13.5)", () => {
+  it("attaches a `contract` field when the component exports __ruactContract", () => {
+    writeComponent(
+      "LikeButton.tsx",
+      [
+        '"use client";',
+        "export const __ruactContract = {",
+        '  props: { postId: "required", initialCount: "optional" },',
+        "};",
+        "export function LikeButton() { return null; }",
+      ].join("\n")
+    );
+
+    const manifest = buildManifest(dir);
+
+    expect(manifest.LikeButton.contract).toEqual({
+      props: { postId: "required", initialCount: "optional" },
+    });
+    // The base entry shape is untouched.
+    expect(manifest.LikeButton.id).toBe("/LikeButton.tsx");
+    expect(manifest.LikeButton.name).toBe("LikeButton");
+  });
+
+  it("emits NO `contract` field when the component declares none (byte-additive)", () => {
+    writeComponent(
+      "Plain.tsx",
+      ['"use client";', "export function Plain() { return null; }"].join("\n")
+    );
+
+    const manifest = buildManifest(dir);
+
+    expect(manifest.Plain).toBeDefined();
+    expect("contract" in manifest.Plain).toBe(false);
+  });
+
+  it("extracts slots (object form) and passthrough", () => {
+    writeComponent(
+      "Card.tsx",
+      [
+        '"use client";',
+        "export const __ruactContract = {",
+        '  props: { title: "required" },',
+        '  slots: { header: "optional", footer: "required" },',
+        "  passthrough: true,",
+        "};",
+        "export const Card = () => null;",
+      ].join("\n")
+    );
+
+    const manifest = buildManifest(dir);
+
+    expect(manifest.Card.contract).toEqual({
+      props: { title: "required" },
+      slots: { header: "optional", footer: "required" },
+      passthrough: true,
+    });
+  });
+
+  it("extracts slots in array form (all optional)", () => {
+    const c = extractContract(
+      [
+        "export const __ruactContract = {",
+        '  props: { title: "required" },',
+        '  slots: ["header", "footer"],',
+        "};",
+      ].join("\n"),
+      "Card.tsx"
+    );
+    expect(c).toEqual({
+      props: { title: "required" },
+      slots: { header: "optional", footer: "optional" },
+    });
+  });
+
+  it("handles nested braces in prop values without breaking balance", () => {
+    const c = extractContract(
+      [
+        "export const __ruactContract = {",
+        "  props: { a: { required: true }, b: { required: false } },",
+        "};",
+      ].join("\n"),
+      "Nested.tsx"
+    );
+    expect(c).toEqual({ props: { a: "required", b: "optional" } });
+  });
+
+  it("ignores braces inside comments and strings when balancing", () => {
+    const c = extractContract(
+      [
+        "export const __ruactContract = {",
+        "  // a stray brace in a comment { should not break balance",
+        '  props: { label: "required" }, // trailing }',
+        '  slots: ["a-}-slot"],',
+        "};",
+        "export const X = () => null;",
+      ].join("\n"),
+      "Commented.tsx"
+    );
+    expect(c).toEqual({
+      props: { label: "required" },
+      slots: { "a-}-slot": "optional" },
+    });
+  });
+
+  it("skips the contract for a multi-component file (warn) — cannot attribute it", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    writeComponent(
+      "Pair.tsx",
+      [
+        '"use client";',
+        'export const __ruactContract = { props: { x: "required" } };',
+        "export function Primary() { return null; }",
+        "export function Secondary() { return null; }",
+      ].join("\n")
+    );
+    const manifest = buildManifest(dir);
+    expect("contract" in manifest.Primary).toBe(false);
+    expect("contract" in manifest.Secondary).toBe(false);
+    expect(warn).toHaveBeenCalledOnce();
+    warn.mockRestore();
+  });
+
+  it("warns and skips a malformed declaration (unbalanced braces) → null", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const c = extractContract(
+      "export const __ruactContract = { props: { a: 'required' ",
+      "Broken.tsx"
+    );
+    expect(c).toBeNull();
+    expect(warn).toHaveBeenCalledOnce();
+    warn.mockRestore();
+  });
+
+  it("warns and skips an information-less declaration → null", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const c = extractContract("export const __ruactContract = {};", "Empty.tsx");
+    expect(c).toBeNull();
+    warn.mockRestore();
+  });
+
+  it("returns null when there is no __ruactContract export", () => {
+    expect(extractContract("export const Foo = 1;", "None.tsx")).toBeNull();
+  });
+
+  it("does not treat __ruactContract itself as a component export", () => {
+    writeComponent(
+      "Widget.tsx",
+      [
+        '"use client";',
+        'export const __ruactContract = { props: { x: "required" } };',
+        "export function Widget() { return null; }",
+      ].join("\n")
+    );
+    const manifest = buildManifest(dir);
+    expect(Object.keys(manifest)).toEqual(["Widget"]);
+  });
+});

data/vendor/javascript/vite-plugin-ruact/package-lock.json

@@ -9,6 +9,7 @@
       "version": "0.0.0-bundled",
       "license": "MIT",
       "devDependencies": {
+        "typescript": "^5.5.0",
         "vitest": "^2.0.0"
       }
     },
@@ -1259,12 +1260,27 @@
         "node": ">=14.0.0"
       }
     },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
     "node_modules/vite": {
       "version": "5.4.21",
       "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.21.tgz",
       "integrity": "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "esbuild": "^0.21.3",
         "postcss": "^8.4.43",

data/vendor/javascript/vite-plugin-ruact/package.json

@@ -5,9 +5,11 @@
   "type": "module",
   "main": "index.js",
   "scripts": {
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.scaffold.json && tsc --noEmit -p tsconfig.scaffold-agnostic.json"
   },
   "devDependencies": {
+    "typescript": "^5.5.0",
     "vitest": "^2.0.0"
   },
   "license": "MIT",

data/vendor/javascript/vite-plugin-ruact/registry.test.mjs

@@ -0,0 +1,199 @@
+// Story 10.1b (component auto-registry) — the build emits MODULE_REGISTRY.
+//
+// vite-plugin-ruact exposes a virtual module (`virtual:ruact/registry`) whose
+// default export is `{ [manifest id]: moduleExports }`, derived from the SAME
+// scan that writes react-client-manifest.json. This file covers:
+//
+//   1. generateRegistrySource — the pure renderer (keys == manifest ids,
+//      one import per source file, membership == manifest membership).
+//   2. dev id-match — registry keys equal the manifest `id` the gem serializes
+//      as the Flight moduleId (source-relative in dev).
+//   3. prod id-match (LOAD-BEARING, AC2/NFR16) — a REAL `vite build` through the
+//      plugin: the emitted manifest ids equal the built registry keys, proving
+//      dev/prod parity (the eager registry inlines components, so the
+//      hashed-URL rewrite never fires and the id stays source-relative in prod).
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { build } from "vite";
+import {
+  buildManifest,
+  generateRegistrySource,
+  REGISTRY_VIRTUAL_ID,
+} from "./index.js";
+import ruact from "./index.js";
+
+let dir;
+beforeEach(() => {
+  // realpath so the dir matches Rollup's symlink-resolved `facadeModuleId`
+  // (macOS /tmp → /private/tmp); the build's id-rewrite match keys off it.
+  dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "ruact-10-1b-")));
+});
+afterEach(() => {
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function write(rel, body) {
+  const full = path.join(dir, rel);
+  fs.mkdirSync(path.dirname(full), { recursive: true });
+  fs.writeFileSync(full, body);
+}
+
+const USE_CLIENT = '"use client";';
+
+describe("generateRegistrySource (Story 10.1b)", () => {
+  it("keys the registry on the manifest `id` and imports the source file", () => {
+    write("PostList.jsx", [USE_CLIENT, "export function PostList() { return null; }"].join("\n"));
+    const manifest = buildManifest(dir);
+    const src = generateRegistrySource(manifest);
+
+    // Key == the manifest id the gem serializes as the Flight moduleId.
+    expect(manifest.PostList.id).toBe("/PostList.jsx");
+    expect(src).toContain('"/PostList.jsx":');
+    // Imports the absolute source file (forward-slashed specifier).
+    expect(src).toContain(`import * as __ruact_m0 from "${path.join(dir, "PostList.jsx").replace(/\\/g, "/")}"`);
+    expect(src).toContain("export default MODULE_REGISTRY;");
+  });
+
+  it("emits exactly one import per source file even with multiple exports", () => {
+    write(
+      "Pair.jsx",
+      [USE_CLIENT, "export function Primary() { return null; }", "export function Secondary() { return null; }"].join("\n")
+    );
+    const src = generateRegistrySource(buildManifest(dir));
+    // Both exports share the same id ("/Pair.jsx") → one import, one entry.
+    expect((src.match(/import \* as/g) || []).length).toBe(1);
+    expect((src.match(/"\/Pair\.jsx":/g) || []).length).toBe(1);
+  });
+
+  it("registry membership equals manifest membership (use-client only, .jsx/.tsx, nested)", () => {
+    write("Client.jsx", [USE_CLIENT, "export function Client() { return null; }"].join("\n"));
+    write("Typed.tsx", [USE_CLIENT, "export function Typed() { return null; }"].join("\n"));
+    write("ui/Button.jsx", [USE_CLIENT, "export function Button() { return null; }"].join("\n"));
+    // NOT registered: no "use client" directive.
+    write("ServerOnly.jsx", ["export function ServerOnly() { return null; }"].join("\n"));
+
+    const manifest = buildManifest(dir);
+    const src = generateRegistrySource(manifest);
+
+    expect(src).toContain('"/Client.jsx":');
+    expect(src).toContain('"/Typed.tsx":');
+    expect(src).toContain('"/ui/Button.jsx":'); // nested path preserved
+    expect(src).not.toContain("ServerOnly");
+    // Exactly the manifest ids, nothing more.
+    const ids = new Set(Object.values(manifest).map((e) => e.id));
+    for (const id of ids) expect(src).toContain(`${JSON.stringify(id)}:`);
+  });
+
+  it("renders an empty registry for a manifest with no components", () => {
+    const src = generateRegistrySource({});
+    expect(src).toContain("const MODULE_REGISTRY = {");
+    expect(src).toContain("export default MODULE_REGISTRY;");
+    expect(src).not.toContain("import * as");
+  });
+});
+
+describe("dev id-match invariant (Story 10.1b AC2)", () => {
+  it("registry keys equal the source-relative manifest ids (dev form)", () => {
+    write("PostList.jsx", [USE_CLIENT, "export function PostList() { return null; }"].join("\n"));
+    write("ui/Button.tsx", [USE_CLIENT, "export function Button() { return null; }"].join("\n"));
+    const manifest = buildManifest(dir);
+    const src = generateRegistrySource(manifest);
+
+    for (const entry of Object.values(manifest)) {
+      // entry.id is what client_manifest.rb serializes as moduleId; the registry
+      // MUST carry that exact key so moduleRegistry[moduleId] resolves.
+      expect(src).toContain(`${JSON.stringify(entry.id)}:`);
+    }
+    expect(manifest.PostList.id).toBe("/PostList.jsx");
+    expect(manifest.Button.id).toBe("/ui/Button.tsx");
+  });
+});
+
+describe("prod id-match invariant — real vite build (Story 10.1b AC2, LOAD-BEARING)", () => {
+  it("a built bundle resolves every manifest id through the emitted registry", async () => {
+    // Plain-JS components (no JSX/react) so the built bundle is self-contained
+    // and importable in node — the invariant under test is id↔key parity, not
+    // rendering. The eager registry inlines these into the entry chunk.
+    write("components/PostList.js", [USE_CLIENT, "export function PostList() { return 'PostList'; }"].join("\n"));
+    write("components/PostForm.js", [USE_CLIENT, "export function PostForm() { return 'PostForm'; }"].join("\n"));
+    write("components/ui/Button.js", [USE_CLIENT, "export function Button() { return 'Button'; }"].join("\n"));
+    // Entry re-exports the auto-registry so we can inspect it post-build.
+    write("entry.js", `export { default as registry } from ${JSON.stringify(REGISTRY_VIRTUAL_ID)};`);
+
+    await build({
+      root: dir,
+      logLevel: "silent",
+      plugins: [ruact({ componentsDir: "components" })],
+      build: {
+        outDir: "dist",
+        write: true,
+        minify: false,
+        rollupOptions: {
+          input: path.join(dir, "entry.js"),
+          // Keep the entry's `registry` export (a Vite app build otherwise
+          // tree-shakes unused entry exports, emptying the chunk).
+          preserveEntrySignatures: "strict",
+          output: { entryFileNames: "entry.js", format: "es" },
+        },
+      },
+    });
+
+    // The manifest the gem will read (ids === Flight moduleIds).
+    const manifest = JSON.parse(
+      fs.readFileSync(path.join(dir, "public/react-client-manifest.json"), "utf8")
+    );
+    const manifestIds = new Set(Object.values(manifest).map((e) => e.id));
+
+    // Prod ids stay source-relative (eager-inlined components → no facade chunk
+    // → generateBundle's hashed-URL rewrite never fires). This is the dev/prod
+    // parity guarantee (NFR16).
+    expect(manifestIds).toEqual(new Set(["/PostList.js", "/PostForm.js", "/ui/Button.js"]));
+
+    // The built registry's keys equal the manifest ids exactly, and each value
+    // exposes the component export the Flight client looks up (mod[exportName]).
+    const built = await import(pathToFileURL(path.join(dir, "dist/entry.js")).href);
+    const registry = built.registry;
+    expect(new Set(Object.keys(registry))).toEqual(manifestIds);
+    for (const [name, entry] of Object.entries(manifest)) {
+      // moduleRegistry[moduleId][exportName] must be defined for every manifest entry.
+      expect(registry[entry.id][entry.name]).toBeTypeOf("function");
+      expect(registry[entry.id][entry.name]()).toBe(name);
+    }
+  }, 30000);
+
+  it("FAILS the build loudly if a component becomes a hashed facade chunk (no silent miss)", async () => {
+    // The hazardous branch: a component is ALSO a Rollup entry → it gets its own
+    // hashed facade chunk → generateBundle would rewrite its manifest id to the
+    // hashed URL while the registry still keys it by source path. The id-match
+    // guard must turn that into a build error, not a silent prod hydration miss.
+    write("components/PostList.js", [USE_CLIENT, "export function PostList() { return 'PostList'; }"].join("\n"));
+    write("entry.js", `export { default as registry } from ${JSON.stringify(REGISTRY_VIRTUAL_ID)};`);
+
+    await expect(
+      build({
+        root: dir,
+        logLevel: "silent",
+        plugins: [ruact({ componentsDir: "components" })],
+        build: {
+          outDir: "dist",
+          write: false,
+          minify: false,
+          rollupOptions: {
+            // Force the component to be its own entry → hashed facade chunk.
+            input: {
+              entry: path.join(dir, "entry.js"),
+              PostList: path.join(dir, "components/PostList.js"),
+            },
+            preserveEntrySignatures: "strict",
+            // Hashed names mirror a real prod build (the rewrite the guard catches).
+            output: { entryFileNames: "[name]-[hash].js", format: "es" },
+          },
+        },
+      })
+    ).rejects.toThrow(/silent hydration miss|standalone .* chunks/i);
+  }, 30000);
+});

data/vendor/javascript/vite-plugin-ruact/runtime/bootstrap.jsx

@@ -0,0 +1,68 @@
+// Ruact bootstrap entry — served to the app as the virtual module
+// `virtual:ruact/bootstrap` (Story 14.2, FR104). This source ships INSIDE the
+// gem so it never sits in the user's `app/javascript/` tree; the bundled
+// vite-plugin's resolveId/load serve it (mirroring `virtual:ruact/registry`).
+//
+// IMPORTANT — this file is loaded as VIRTUAL-MODULE TEXT, not from disk, so its
+// resolved id is `\0virtual:ruact/bootstrap`, which is NOT a filesystem path:
+//   • Relative imports (`./flight-client.js`) do NOT resolve from a `\0virtual:`
+//     id. The plugin's `load` hook rewrites the two runtime imports below to
+//     ABSOLUTE fs specifiers into the gem `runtime/` dir before serving them
+//     (see `generateBootstrapSource` in index.js).
+//   • Bare specifiers (`react`, `react-dom/client`) and the `virtual:` id DO
+//     resolve — Vite resolves them from the APP ROOT, so React/react-dom come
+//     from the USER's node_modules (a single React instance — non-negotiable).
+//   • No JSX syntax is used here (the inner App is built with `createElement`)
+//     so the virtual module loads through Vite's default loader exactly like
+//     `virtual:ruact/registry`, with no dependency on @vitejs/plugin-react
+//     transforming a `\0virtual:` id.
+import { createRoot } from 'react-dom/client';
+import { createElement, useState, useEffect } from 'react';
+import { createFromFlightPayload } from './flight-client.js';
+import { setupRouter, teardownRouter } from './ruact-router.js';
+
+// MODULE_REGISTRY maps react-client-manifest "id" values to component exports.
+// It is auto-derived by vite-plugin-ruact from the SAME scan that emits
+// public/react-client-manifest.json — every "use client" component under
+// app/javascript/components/ is registered automatically, so adding or removing
+// one needs ZERO edits here. (To opt a component out, place it outside
+// app/javascript/components/ or drop its "use client" directive.)
+import MODULE_REGISTRY from 'virtual:ruact/registry';
+
+// ---------------------------------------------------------------------------
+// Boot
+// ---------------------------------------------------------------------------
+const flightData = globalThis.__FLIGHT_DATA;
+
+if (!flightData || flightData.length === 0) {
+  // Non-RSC page or Rails server not running — skip hydration.
+  const root = document.getElementById('root');
+  if (root && root.childNodes.length === 0) {
+    root.textContent = '[ruact] No Flight data found — is the Rails server running?';
+  }
+} else {
+  const payload = flightData.join('');
+
+  let initialTree;
+  try {
+    initialTree = createFromFlightPayload(payload, MODULE_REGISTRY);
+  } catch (err) {
+    console.error('[ruact] Failed to parse Flight payload:', err);
+    const root = document.getElementById('root');
+    if (root) root.textContent = '[ruact] Error: ' + err.message;
+    throw err;
+  }
+
+  function App() {
+    const [tree, setTree] = useState(() => initialTree);
+
+    useEffect(() => {
+      setupRouter({ onNavigate: setTree, moduleRegistry: MODULE_REGISTRY });
+      return () => teardownRouter();
+    }, []);
+
+    return tree;
+  }
+
+  createRoot(document.getElementById('root')).render(createElement(App));
+}