@taprootio/site-authoring 0.1.1 → 0.3.0

package/src/verbs/validate.js

@@ -2,9 +2,17 @@ import { lstat, realpath } from "node:fs/promises";
 import path from "node:path";
 
 import { NAVIGATION_MAXIMUM_DEPTH, TEMPLATE_TYPE_FREE_FORM } from "../api.js";
-import { sharedThemeContextNames } from "../content/free-form-sections.js";
+import { freeFormRootPresentation, sharedThemeContextNames } from "../content/free-form-sections.js";
 import { VERB_VALIDATE } from "../constants.js";
 import { isCanonicalUuid, SiteAuthoringError } from "../errors.js";
+import {
+  FIXTURE_CONTRACT_VERSION,
+  FIXTURE_DELIVERY_ORIGIN_DOMAIN,
+  FIXTURE_MANIFEST_FILE_NAME,
+  FIXTURE_MAXIMUM_DELIVERY_ORIGINS,
+  FIXTURE_METADATA_FIELDS,
+  FIXTURE_ROOT_FIELDS,
+} from "../fixture-contract.js";
 import { FOOTER_SETTINGS_FILE } from "../footer-workspace.js";
 import { boundedList, successResult } from "../session.js";
 import { SETTINGS_GROUPS, SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES } from "../settings-catalog.js";
@@ -26,22 +34,9 @@ import {
   WORKSPACE_LIMITS,
 } from "../workspace.js";
 
-export const FIXTURE_MANIFEST_FILE_NAME = "manifest.fixture.json";
-export const FIXTURE_CONTRACT_VERSION = 1;
 const MAXIMUM_REPORTED = 200;
-const FIXTURE_ROOT_KEYS = new Set([
-  "manifestVersion",
-  "siteId",
-  "pulledAt",
-  "pages",
-  "pagesTruncated",
-  "navigation",
-  "settings",
-  "settingsSkipped",
-  "deployments",
-  "fixture",
-]);
-const FIXTURE_METADATA_KEYS = new Set(["contractVersion", "imageIds", "deliveryOrigins"]);
+const FIXTURE_ROOT_KEYS = new Set(FIXTURE_ROOT_FIELDS);
+const FIXTURE_METADATA_KEYS = new Set(FIXTURE_METADATA_FIELDS);
 
 function fail(code, message, field, exitCode) {
   throw new SiteAuthoringError(code, message, { field, exitCode });
@@ -163,7 +158,10 @@ function validateFixtureManifest(manifest) {
   if (imageIds.size !== manifest.fixture.imageIds.length) {
     fail("fixture.image_ids_invalid", "fixture.imageIds must not contain duplicates.", "fixture.imageIds");
   }
-  if (!Array.isArray(manifest.fixture.deliveryOrigins) || manifest.fixture.deliveryOrigins.length > 100) {
+  if (
+    !Array.isArray(manifest.fixture.deliveryOrigins)
+    || manifest.fixture.deliveryOrigins.length > FIXTURE_MAXIMUM_DELIVERY_ORIGINS
+  ) {
     fail(
       "fixture.delivery_origins_invalid",
       "fixture.deliveryOrigins must be a bounded list of reserved HTTPS example origins.",
@@ -186,11 +184,14 @@ function validateFixtureManifest(manifest) {
       || url.pathname !== "/"
       || url.search !== ""
       || url.hash !== ""
-      || !(url.hostname === "example.test" || url.hostname.endsWith(".example.test"))
+      || !(
+        url.hostname === FIXTURE_DELIVERY_ORIGIN_DOMAIN
+        || url.hostname.endsWith(`.${FIXTURE_DELIVERY_ORIGIN_DOMAIN}`)
+      )
     ) {
       fail(
         "fixture.delivery_origins_invalid",
-        "Every fixture delivery origin must be an origin-only HTTPS URL under the reserved example.test domain.",
+        `Every fixture delivery origin must be an origin-only HTTPS URL under the reserved ${FIXTURE_DELIVERY_ORIGIN_DOMAIN} domain.`,
         `fixture.deliveryOrigins[${index}]`,
       );
     }
@@ -340,6 +341,34 @@ function validatePageImageReferences(value, field, knownImageIds, deliveryOrigin
   }
 }
 
+/** Whether a validated page document places a root-band component at its root. */
+function pageUsesRootBand(document) {
+  return Array.isArray(document?.content)
+    && document.content.some((node) => freeFormRootPresentation(node)?.rootPlacement === "root-band");
+}
+
+/**
+ * Advisory only: a root-band component spans the viewport, so a header whose
+ * brand and buttons stop at the content edges usually reads as misaligned
+ * beside it. The wide header with the centered menu is the recommended pair,
+ * never a requirement, so this is a hint in the result and on stderr, not a
+ * failure (TR00697).
+ */
+function headerWidthHints(headerWidth, rootBandPages) {
+  if (rootBandPages.length === 0 || headerWidth === "wide") return [];
+  const pages = boundedList(rootBandPages, MAXIMUM_REPORTED);
+  return [{
+    code: "header.width_contained_with_root_band",
+    message: `${rootBandPages.length} page(s) use a full-bleed root-band component while site-header.headerWidth is `
+      + `'${headerWidth}'. Full-bleed designs usually read better with headerWidth 'wide' (brand and buttons at the `
+      + "viewport edges) paired with headerLayout 'centered-menu'.",
+    setting: "site-header.headerWidth",
+    suggested: { headerWidth: "wide", headerLayout: "centered-menu" },
+    pages: pages.items,
+    ...(pages.truncated ? { pagesTruncated: true } : {}),
+  }];
+}
+
 export async function validateFixture(invocation = {}) {
   const onProgress = typeof invocation.onProgress === "function" ? invocation.onProgress : () => {};
   const fixtureRoot = await resolveFixtureRoot(invocation.cwd ?? process.cwd(), invocation.fixturePath);
@@ -377,6 +406,7 @@ export async function validateFixture(invocation = {}) {
     fail("fixture.page_untracked", `Page source '${untracked}' is not bound by ${FIXTURE_MANIFEST_FILE_NAME}.`, untracked);
   }
   const validatedPages = [];
+  const rootBandPages = [];
   for (const file of pageFiles) {
     onProgress(`Validating '${file}'.`);
     const entry = manifestByFile.get(file);
@@ -404,7 +434,10 @@ export async function validateFixture(invocation = {}) {
     }
     validatePageImageReferences(page.document, file, imageIds, deliveryOrigins);
     validatedPages.push({ file, path: page.pagePath });
+    if (pageUsesRootBand(page.document)) rootBandPages.push(file);
   }
+  const hints = headerWidthHints(presentation.header.headerWidth, rootBandPages);
+  for (const hint of hints) onProgress(`Hint: ${hint.message}`);
 
   onProgress("Validating navigation shape and local PAGE targets.");
   const navigation = validateNavigationWorkspaceDocument(
@@ -459,6 +492,7 @@ export async function validateFixture(invocation = {}) {
       count: presentation.themes.warningCount,
       ...(presentation.themes.warningsTruncated ? { truncated: true } : {}),
     },
+    hints,
     proves: [
       "fixture structure and bounded files",
       "page content and named theme contexts",