@iterant/site-runtime 3.6.0 → 3.6.1

package/docs/runtime-contract.md

@@ -50,7 +50,7 @@ runtime and says so.
 
 <!-- generated: available libraries -->
 
-_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.6.0._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.6.1._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterant/site-runtime",
-  "version": "3.6.0",
+  "version": "3.6.1",
   "type": "module",
   "description": "The platform layer every Iterant brand site runs on: content grammar, collection schemas, SEO head and JSON-LD, layout core, Astro config preset, dev integrations and the verify gates.",
   "scripts": {

package/scripts/scan-bespoke-siblings.mjs

@@ -19,12 +19,29 @@
  *      the shape the catch-all's pickPageExport (src/lib/bespoke-pages.ts)
  *      resolves.
  *
- * For every NON-DRAFT bespoke base entry, this asserts (1) against the built
- * manifest and (2) by importing the built client entry itself. Draft bespoke
- * pages are exempt: drafts never publish, their siblings are never advertised
- * (hreflang/sitemap), and the stock `not-found` page is a draft that
- * deliberately lives outside the `<base>/page.tsx` convention (404.astro
- * renders it). Publishing a bespoke page puts it in scope on the next verify.
+ * For every NON-DRAFT bespoke base entry THAT HAS a locale sibling file
+ * (`<base>.<locale>.json`, draft or not: a draft sibling still renders in a
+ * preview), this asserts (1) against the built manifest and (2) by importing
+ * the built client entry itself. Draft bespoke pages are exempt: drafts never
+ * publish, their siblings are never advertised (hreflang/sitemap), and the
+ * stock `not-found` page is a draft that deliberately lives outside the
+ * `<base>/page.tsx` convention (404.astro renders it). Publishing a bespoke
+ * page puts it in scope on the next verify.
+ *
+ * Scoping to bases-with-siblings (3.6.1) loses nothing: the hazard cannot
+ * materialize without a sibling, a sibling only comes into existence through
+ * a save, and every save runs this gate, so a base picks up the full check
+ * the moment its first sibling lands. Before that, a pre-convention bespoke
+ * page (every pre-3.6 blog) must not block a same-major runtime bump over a
+ * feature the repo does not use.
+ *
+ * A base whose sibling route is SHADOWED is also out of scope (3.6.1): when
+ * `src/pages/[locale]/<base>.astro` exists (`index.astro` for the `home`
+ * base), Astro's route priority sends `/es` to that explicit route, never to
+ * the catch-all, so the catch-all hydration contract this gate asserts does
+ * not serve the sibling at all. Replica-era repos localize exactly this way.
+ * The shadowing route's own hydration is `astro build`'s concern, like every
+ * other explicit route.
  *
  * It also pins the Astro runtime contract the catch-all relies on: the island
  * renderer must keep accepting `client:component-path` /
@@ -37,7 +54,7 @@
  * weaken this script.
  */
 
-import { readdir, readFile } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { exit } from "node:process";
@@ -51,41 +68,34 @@ const CONVENTIONS =
 /** @type {string[]} */
 const problems = [];
 
-// ---- SF-pin: the Astro runtime directive contract --------------------------
-
-const hydrationJs = join(
-  process.cwd(),
-  "node_modules/astro/dist/runtime/server/hydration.js",
-);
-const hydrationSrc = await readFile(hydrationJs, "utf8").catch(() => "");
-for (const directive of ["client:component-path", "client:component-export"]) {
-  if (!hydrationSrc.includes(`case "${directive}"`)) {
-    problems.push(
-      `astro runtime contract changed: ${hydrationJs} no longer handles ` +
-        `"${directive}" as a prop. Bespoke locale siblings hydrate through ` +
-        `exactly that escape hatch (src/pages/[...slug].astro) — re-verify ` +
-        `sibling hydration against this Astro version before shipping.`,
-    );
-  }
-}
-
-// ---- SF1+SF2: every non-draft bespoke base ---------------------------------
+// ---- SF1+SF2: every non-draft bespoke base with a sibling ------------------
 
-/** Non-draft bespoke base entry ids (`home`), never locale siblings. */
-async function bespokeBases() {
+/**
+ * Non-draft bespoke base entry ids (`home`), never locale siblings, plus the
+ * set of base ids that have at least one sibling file. Sibling presence
+ * counts by filename alone (`home.es.json` -> `home`): a sibling's own draft
+ * flag or parse failure does not excuse its base, because the sibling still
+ * renders in a preview.
+ */
+async function bespokeInventory() {
   const pagesDir = join(process.cwd(), "src/content/pages");
   /** @type {string[]} */
   const bases = [];
+  /** @type {Set<string>} */
+  const siblingBases = new Set();
   /** @type {string[]} */
   let names = [];
   try {
     names = await readdir(pagesDir);
   } catch {
-    return bases; // no pages dir — astro check owns that failure
+    return { bases, siblingBases }; // no pages dir: astro check owns that failure
   }
   for (const name of names.filter((n) => n.endsWith(".json")).sort()) {
     const id = name.replace(/\.json$/, "");
-    if (id.includes(".")) continue; // locale sibling — guarded via its base
+    if (id.includes(".")) {
+      siblingBases.add(id.slice(0, id.indexOf(".")));
+      continue; // locale sibling: guarded via its base
+    }
     /** @type {{ mode?: string; draft?: boolean }} */
     let entry;
     try {
@@ -95,7 +105,21 @@ async function bespokeBases() {
     }
     if (entry.mode === "bespoke" && entry.draft !== true) bases.push(id);
   }
-  return bases;
+  return { bases, siblingBases };
+}
+
+/**
+ * Whether an explicit locale route shadows this base's siblings. Astro sends
+ * `/es` (and `/es/<base>`) to `src/pages/[locale]/index.astro` (respectively
+ * `[locale]/<base>.astro`) before any rest-param catch-all, so when that file
+ * exists the sibling never renders through the catch-all this gate asserts.
+ */
+async function siblingRouteShadowed(base) {
+  const file = base === "home" ? "index.astro" : `${base}.astro`;
+  return stat(join(process.cwd(), "src/pages/[locale]", file)).then(
+    (s) => s.isFile(),
+    () => false,
+  );
 }
 
 /**
@@ -133,8 +157,37 @@ async function builtEntryModules() {
   return null;
 }
 
-const bases = await bespokeBases();
-if (bases.length > 0 && problems.length === 0) {
+const inventory = await bespokeInventory();
+/** @type {string[]} */
+const bases = [];
+for (const base of inventory.bases) {
+  if (!inventory.siblingBases.has(base)) continue;
+  if (await siblingRouteShadowed(base)) continue;
+  bases.push(base);
+}
+// Nothing can hydrate through the escape hatch: the first sibling arrives via
+// a save, and every save re-runs this gate, so exiting here defers nothing.
+if (bases.length === 0) exit(0);
+
+// ---- SF-pin: the Astro runtime directive contract --------------------------
+
+const hydrationJs = join(
+  process.cwd(),
+  "node_modules/astro/dist/runtime/server/hydration.js",
+);
+const hydrationSrc = await readFile(hydrationJs, "utf8").catch(() => "");
+for (const directive of ["client:component-path", "client:component-export"]) {
+  if (!hydrationSrc.includes(`case "${directive}"`)) {
+    problems.push(
+      `astro runtime contract changed: ${hydrationJs} no longer handles ` +
+        `"${directive}" as a prop. Bespoke locale siblings hydrate through ` +
+        `exactly that escape hatch (src/pages/[...slug].astro): re-verify ` +
+        `sibling hydration against this Astro version before shipping.`,
+    );
+  }
+}
+
+if (problems.length === 0) {
   const entryModules = await builtEntryModules();
   if (!entryModules) {
     problems.push(