Tighten RSC peer guardrails

justin808 · justin808 · commit 5f511deed720 · 2026-06-13T12:44:21.000-10:00
diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml
@@ -59,7 +59,7 @@ on:
       - 'AGENTS_USER_GUIDE.md'
       - 'docs/**'
       - 'llms.txt'
-      - 'llms-full.txt'
+      - 'llms-full*.txt'
       - '.lychee.toml'
 # Cancel stale PR benchmark runs when new commits are pushed.
 # Main runs are never cancelled so every merge is measured.
diff --git a/.github/workflows/check-llms-full.yml b/.github/workflows/check-llms-full.yml
@@ -15,6 +15,8 @@ on:
       - 'docs/.llms-known-redirects'
       - 'llms.txt'
       - 'llms-full.txt'
+      - 'llms-full-oss.txt'
+      - 'llms-full-pro.txt'
       - 'script/generate-llms-full.mjs'
       - 'script/generate-llms-full-test.bash'
       - '.github/workflows/check-llms-full.yml'
@@ -28,6 +30,8 @@ on:
       - 'docs/.llms-known-redirects'
       - 'llms.txt'
       - 'llms-full.txt'
+      - 'llms-full-oss.txt'
+      - 'llms-full-pro.txt'
       - 'script/generate-llms-full.mjs'
       - 'script/generate-llms-full-test.bash'
       - '.github/workflows/check-llms-full.yml'
diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml
@@ -14,14 +14,14 @@ on:
     paths-ignore:
       - 'AGENTS_USER_GUIDE.md'
       - 'llms.txt'
-      - 'llms-full.txt'
+      - 'llms-full*.txt'
   pull_request:
     paths-ignore:
       - '**.md'
       - 'AGENTS_USER_GUIDE.md'
       - 'docs/**'
       - 'llms.txt'
-      - 'llms-full.txt'
+      - 'llms-full*.txt'
       - '.lychee.toml'
   workflow_dispatch:
     inputs:
diff --git a/.github/workflows/gem-tests.yml b/.github/workflows/gem-tests.yml
@@ -18,7 +18,7 @@ on:
       - 'AGENTS_USER_GUIDE.md'
       - 'docs/**'
       - 'llms.txt'
-      - 'llms-full.txt'
+      - 'llms-full*.txt'
       - '.lychee.toml'
       - 'packages/**'
       - 'react_on_rails_pro/**'
diff --git a/.github/workflows/integration-tests.yml b/.github/workflows/integration-tests.yml
@@ -18,7 +18,7 @@ on:
       - 'AGENTS_USER_GUIDE.md'
       - 'docs/**'
       - 'llms.txt'
-      - 'llms-full.txt'
+      - 'llms-full*.txt'
       - '.lychee.toml'
       - 'react_on_rails_pro/**'
   workflow_dispatch:
diff --git a/.github/workflows/lint-js-and-ruby.yml b/.github/workflows/lint-js-and-ruby.yml
@@ -12,7 +12,7 @@ on:
     paths-ignore:
       - 'AGENTS_USER_GUIDE.md'
       - 'llms.txt'
-      - 'llms-full.txt'
+      - 'llms-full*.txt'
       - '.lychee.toml'
   workflow_dispatch:
     inputs:
diff --git a/.github/workflows/package-js-tests.yml b/.github/workflows/package-js-tests.yml
@@ -14,7 +14,7 @@ on:
       - 'AGENTS_USER_GUIDE.md'
       - 'docs/**'
       - 'llms.txt'
-      - 'llms-full.txt'
+      - 'llms-full*.txt'
       - '.lychee.toml'
       - 'react_on_rails/lib/**'
       - 'react_on_rails/spec/react_on_rails/**'
diff --git a/.github/workflows/precompile-check.yml b/.github/workflows/precompile-check.yml
@@ -14,7 +14,7 @@ on:
       - 'AGENTS_USER_GUIDE.md'
       - 'docs/**'
       - 'llms.txt'
-      - 'llms-full.txt'
+      - 'llms-full*.txt'
       - '.lychee.toml'
       - 'react_on_rails_pro/**'
   workflow_dispatch:
diff --git a/.github/workflows/pro-integration-tests.yml b/.github/workflows/pro-integration-tests.yml
@@ -14,7 +14,7 @@ on:
       - 'AGENTS_USER_GUIDE.md'
       - 'docs/**'
       - 'llms.txt'
-      - 'llms-full.txt'
+      - 'llms-full*.txt'
       - '.lychee.toml'
       - 'react_on_rails/lib/**'
       - 'react_on_rails/spec/**'
diff --git a/.github/workflows/pro-test-package-and-gem.yml b/.github/workflows/pro-test-package-and-gem.yml
@@ -14,7 +14,7 @@ on:
       - 'AGENTS_USER_GUIDE.md'
       - 'docs/**'
       - 'llms.txt'
-      - 'llms-full.txt'
+      - 'llms-full*.txt'
       - '.lychee.toml'
       - 'react_on_rails/lib/**'
       - 'react_on_rails/spec/**'
diff --git a/packages/react-on-rails-pro-node-renderer/src/shared/checkRscPeerCompatibility.ts b/packages/react-on-rails-pro-node-renderer/src/shared/checkRscPeerCompatibility.ts
@@ -75,6 +75,16 @@ const supportedReactRange = ({
 }: typeof RSC_PEER_SUPPORT.react): string =>
   `${supportedMajor}.${supportedMinor}.x with patch >= ${supportedMajor}.${supportedMinor}.${minPatch}`;
 
+const supportedRscRange = ({
+  allowedPrereleases,
+  recommendedMin,
+  supportedMajor,
+  supportedMinor,
+}: typeof RSC_PEER_SUPPORT.reactOnRailsRsc): string =>
+  `${supportedMajor}.${supportedMinor}.x stable >= ${recommendedMin}, or ${allowedPrereleases.join(
+    ' / ',
+  )} while upgrading from the RC line`;
+
 const isSupportedReactTuple = (
   [major, minor, patch]: VersionTuple,
   { supportedMajor, supportedMinor, minPatch }: typeof RSC_PEER_SUPPORT.react,
@@ -98,6 +108,13 @@ const warnMessage = (found: string, recommendedMin: string, proVersion?: string)
     `  Upgrade react-on-rails-rsc to ${recommendedMin} or newer.`,
   ].join('\n');
 
+const prereleaseWarnMessage = (found: string, recommendedMin: string, proVersion?: string) =>
+  [
+    `[ReactOnRails] react-on-rails-rsc ${found} is a prerelease of the recommended minimum ${recommendedMin}.`,
+    `  ${proLabel(proVersion)} may behave incorrectly until the stable RSC package is installed.`,
+    `  Upgrade react-on-rails-rsc to the stable ${recommendedMin} release or newer.`,
+  ].join('\n');
+
 export function checkRscPeerCompatibility(input: RscPeerCheckInput): RscPeerCheckResult {
   const { rscVersion, reactVersion, reactDomVersion, proVersion } = input;
 
@@ -107,17 +124,24 @@ export function checkRscPeerCompatibility(input: RscPeerCheckInput): RscPeerChec
 
   const { reactOnRailsRsc, react } = RSC_PEER_SUPPORT;
   const rscTuple = parseTuple(rscVersion);
-  const [rscMajor] = rscTuple;
+  const [rscMajor, rscMinor] = rscTuple;
+
+  if (rscMajor !== reactOnRailsRsc.supportedMajor || rscMinor !== reactOnRailsRsc.supportedMinor) {
+    return {
+      level: 'error',
+      message: errorMessage('react-on-rails-rsc', rscVersion, supportedRscRange(reactOnRailsRsc), proVersion),
+    };
+  }
 
-  if (rscMajor !== reactOnRailsRsc.supportedMajor) {
+  const normalizedRscVersion = stripVersionPrefixAndBuild(rscVersion);
+  const isPrerelease = isPrereleaseVersion(rscVersion);
+  const isAllowedPrerelease = reactOnRailsRsc.allowedPrereleases.some(
+    (allowedVersion) => allowedVersion === normalizedRscVersion,
+  );
+  if (isPrerelease && !isAllowedPrerelease) {
     return {
       level: 'error',
-      message: errorMessage(
-        'react-on-rails-rsc',
-        rscVersion,
-        `${reactOnRailsRsc.supportedMajor}.x`,
-        proVersion,
-      ),
+      message: errorMessage('react-on-rails-rsc', rscVersion, supportedRscRange(reactOnRailsRsc), proVersion),
     };
   }
 
@@ -152,13 +176,12 @@ export function checkRscPeerCompatibility(input: RscPeerCheckInput): RscPeerChec
   }
 
   const recommendedMinTuple = parseTuple(reactOnRailsRsc.recommendedMin);
-  if (
-    !isAtLeast(rscTuple, recommendedMinTuple) ||
-    // Warn only when the installed RSC is a prerelease at the exact stable floor, e.g. 19.0.5-rc.7
-    // when 19.0.5 stable is available. Higher prerelease tuples are outside this upgrade nudge.
-    (sameTuple(rscTuple, recommendedMinTuple) && isPrereleaseVersion(rscVersion))
-  ) {
-    return { level: 'warn', message: warnMessage(rscVersion, reactOnRailsRsc.recommendedMin, proVersion) };
+  const isPrereleaseAtRecommendedMin = sameTuple(rscTuple, recommendedMinTuple) && isPrerelease;
+  if (!isAtLeast(rscTuple, recommendedMinTuple) || isPrereleaseAtRecommendedMin) {
+    const message = isPrereleaseAtRecommendedMin
+      ? prereleaseWarnMessage(rscVersion, reactOnRailsRsc.recommendedMin, proVersion)
+      : warnMessage(rscVersion, reactOnRailsRsc.recommendedMin, proVersion);
+    return { level: 'warn', message };
   }
 
   return { level: 'ok' };
diff --git a/packages/react-on-rails-pro-node-renderer/src/shared/rscPeerSupport.ts b/packages/react-on-rails-pro-node-renderer/src/shared/rscPeerSupport.ts
@@ -19,6 +19,11 @@
 // `recommendedMin` deliberately starts at the stable floor we currently recommend.
 // Raise it only after Pro validates a newer `react-on-rails-rsc` release.
 export const RSC_PEER_SUPPORT = {
-  reactOnRailsRsc: { recommendedMin: '19.0.5', supportedMajor: 19 },
+  reactOnRailsRsc: {
+    recommendedMin: '19.0.5',
+    supportedMajor: 19,
+    supportedMinor: 0,
+    allowedPrereleases: ['19.0.5-rc.6', '19.0.5-rc.7'],
+  },
   react: { supportedMajor: 19, supportedMinor: 0, minPatch: 4 },
 } as const;
diff --git a/packages/react-on-rails-pro-node-renderer/tests/checkRscPeerCompatibility.test.ts b/packages/react-on-rails-pro-node-renderer/tests/checkRscPeerCompatibility.test.ts
@@ -34,21 +34,31 @@ describe('checkRscPeerCompatibility', () => {
 
   it('returns ok for a supported stable rsc + react', () => {
     expect(checkRscPeerCompatibility({ rscVersion: '19.0.5', reactVersion: '19.0.4' }).level).toBe('ok');
+    expect(checkRscPeerCompatibility({ rscVersion: '19.0.6', reactVersion: '19.0.4' }).level).toBe('ok');
   });
 
   it('warns for a prerelease at the stable recommended minimum', () => {
-    expect(checkRscPeerCompatibility({ rscVersion: '19.0.5-rc.6', reactVersion: '19.0.4' }).level).toBe(
-      'warn',
-    );
-    expect(checkRscPeerCompatibility({ rscVersion: '19.0.5-rc.7', reactVersion: '19.0.4' }).level).toBe(
-      'warn',
-    );
+    const rc6 = checkRscPeerCompatibility({ rscVersion: '19.0.5-rc.6', reactVersion: '19.0.4' });
+    expect(rc6.level).toBe('warn');
+    expect(rc6.message).toContain('19.0.5-rc.6');
+    expect(rc6.message).toContain('prerelease of the recommended minimum 19.0.5');
+
+    const rc7 = checkRscPeerCompatibility({ rscVersion: '19.0.5-rc.7', reactVersion: '19.0.4' });
+    expect(rc7.level).toBe('warn');
+    expect(rc7.message).toContain('19.0.5-rc.7');
   });
 
   it('returns ok for a version with a leading v (prefix stripped for comparison)', () => {
     expect(checkRscPeerCompatibility({ rscVersion: 'v19.0.5', reactVersion: '19.0.4' }).level).toBe('ok');
   });
 
+  it('errors for an unlisted prerelease above the stable recommended minimum', () => {
+    const result = checkRscPeerCompatibility({ rscVersion: '19.0.6-rc.1', reactVersion: '19.0.4' });
+    expect(result.level).toBe('error');
+    expect(result.message).toContain('19.0.6-rc.1');
+    expect(result.message).toContain('19.0.5-rc.6 / 19.0.5-rc.7');
+  });
+
   it('errors when rsc major is above the supported major', () => {
     const r = checkRscPeerCompatibility({ rscVersion: '20.0.0', reactVersion: '19.0.4' });
     expect(r.level).toBe('error');
@@ -60,6 +70,13 @@ describe('checkRscPeerCompatibility', () => {
     expect(checkRscPeerCompatibility({ rscVersion: '18.3.1', reactVersion: '19.0.4' }).level).toBe('error');
   });
 
+  it('errors when rsc minor is outside the supported line', () => {
+    const r = checkRscPeerCompatibility({ rscVersion: '19.1.0', reactVersion: '19.0.4' });
+    expect(r.level).toBe('error');
+    expect(r.message).toContain('19.1.0');
+    expect(r.message).toContain('19.0.x stable >= 19.0.5');
+  });
+
   it('errors when React major is below the RSC minimum', () => {
     const r = checkRscPeerCompatibility({ rscVersion: '19.0.4', reactVersion: '18.3.1' });
     expect(r.level).toBe('error');
diff --git a/react_on_rails/lib/generators/react_on_rails/js_dependency_manager.rb b/react_on_rails/lib/generators/react_on_rails/js_dependency_manager.rb
@@ -486,14 +486,14 @@ def rsc_packages_with_pin
       def rsc_dependency_pin_info
         "React Server Components package pin: all --rsc installs use " \
           "react-on-rails-rsc@#{RSC_PACKAGE_VERSION_PIN}, including Webpack projects. " \
-          "This pin keeps react-on-rails-rsc/WebpackPlugin compatible while adding " \
-          "react-on-rails-rsc/RspackPlugin."
+          "This pin keeps react-on-rails-rsc/WebpackPlugin and react-on-rails-rsc/RspackPlugin " \
+          "on the tested version."
       end
 
       def rsc_dependency_pin_failed_warning
         "Warning: Could not install the pinned react-on-rails-rsc@#{RSC_PACKAGE_VERSION_PIN}. " \
           "All RSC projects are pinned to that tested version: the package keeps " \
-          "react-on-rails-rsc/WebpackPlugin compatible while adding react-on-rails-rsc/RspackPlugin, " \
+          "react-on-rails-rsc/WebpackPlugin and react-on-rails-rsc/RspackPlugin aligned, " \
           "so the generator left the version pin in package.json rather than install a potentially " \
           "incompatible version."
       end
diff --git a/script/generate-llms-full.mjs b/script/generate-llms-full.mjs
@@ -432,11 +432,6 @@ function generatedOutputs(docs, orderedIds) {
   const combinedSizeKib = outputSizeKib(combinedOutput);
 
   if (combinedSizeKib <= SPLIT_THRESHOLD_KIB) {
-    validateSplitThreshold(
-      path.basename(OUTPUT_FILE),
-      combinedOutput,
-      'Split the generated reference into OSS and Pro files before shipping this size.',
-    );
     return {
       mode: 'single',
       combinedSizeKib,
