@taprootio/site-authoring 0.15.0 → 0.18.0

package/src/verbs/validate.js

@@ -5,6 +5,7 @@ import { NAVIGATION_MAXIMUM_DEPTH } from "../api.js";
 import { loadSiteConfig } from "../config.js";
 import { VERB_VALIDATE } from "../constants.js";
 import { freeFormRootPresentation } from "../content/free-form-sections.js";
+import { autolinkWarnings } from "../content/link-warnings.js";
 import { isCanonicalUuid, SiteAuthoringError } from "../errors.js";
 import {
   FIXTURE_CONTRACT_VERSION,
@@ -17,12 +18,14 @@ import {
 import { initializeFixture } from "../fixture-init.js";
 import { appearanceManifestEntry, footerManifestEntry } from "../footer-workspace.js";
 import { FORMS_DIRECTORY } from "../forms-contract.js";
+import { authorWarnings, descriptionWarnings } from "../page-metadata.js";
 import { CHECK_AREA, collectProblems, refuseProblems } from "../problems.js";
 import { isRedirectMapRevision, REDIRECT_KIND_GONE, REDIRECTS_FILE_NAME } from "../redirects-contract.js";
 import { boundedList, successResult } from "../session.js";
 import { SETTINGS_GROUPS } from "../settings-catalog.js";
 import { checkWorkspace } from "../workspace-check.js";
 import {
+  displayPagePath,
   MANIFEST_FILE_NAME,
   MANIFEST_VERSION,
   MEDIA_MANIFEST_FILE_NAME,
@@ -30,6 +33,7 @@ import {
   normalizePagePath,
   PAGE_SOURCE_EXTENSIONS,
   PAGE_WORKSPACE_MODE_EDITABLE,
+  PAGE_WORKSPACE_MODE_METADATA_ONLY,
   PAGES_DIRECTORY,
   pageSourceFormat,
   readManifest,
@@ -39,6 +43,7 @@ import {
   walkWorkspaceFiles,
   WORKSPACE_LIMITS,
   workspaceFileExists,
+  SYSTEM_PAGE_NOT_FOUND_PATH,
 } from "../workspace.js";
 import { documentImageIds, isAuthorableTemplateType, placedVideoIds } from "../typed-pages.js";
 
@@ -289,6 +294,29 @@ function validateFixtureManifest(manifest) {
   for (const [index, entry] of manifest.pages.entries()) {
     const field = `pages[${index}]`;
     const pagePath = normalizePagePath(entry?.path);
+    // A page the fixture only names, such as a generated page navigation
+    // points at: it has identities and a path, and no source (TR01198).
+    if (isPlainObject(entry) && entry.workspaceMode === PAGE_WORKSPACE_MODE_METADATA_ONLY) {
+      // The home page and the 404 page are always editable sources.
+      if (
+        !isCanonicalUuid(entry.pageId) || !isCanonicalUuid(entry.resourceId) || pagePath === undefined
+        || Object.hasOwn(entry, "file") || pagePath === "" || pagePath === SYSTEM_PAGE_NOT_FOUND_PATH
+      ) {
+        fail(
+          "fixture.page_invalid",
+          `${field} is metadata-only, so it needs deterministic page/resource identities, a usable path other than `
+            + "the home page or the 404 page, and no file.",
+          field,
+        );
+      }
+      if (pageIds.has(entry.pageId) || resourceIds.has(entry.resourceId) || paths.has(pagePath)) {
+        fail("fixture.page_duplicate", `${field} duplicates a pageId, resourceId, or page path.`, field);
+      }
+      pageIds.add(entry.pageId);
+      resourceIds.add(entry.resourceId);
+      paths.add(pagePath);
+      continue;
+    }
     const extension = typeof entry?.file === "string"
       ? PAGE_SOURCE_EXTENSIONS.find((candidate) => entry.file.toLowerCase().endsWith(candidate))
       : undefined;
@@ -333,6 +361,9 @@ function validateFixtureManifest(manifest) {
     files.add(entry.file);
     paths.add(pagePath);
   }
+  if (files.size === 0) {
+    fail("fixture.pages_invalid", "The fixture manifest must bind one or more editable pages.", "pages");
+  }
   return { manifest, imageIds, videoIds, deliveryOrigins, pageIds, resourceIds, files, settingsEntityIds };
 }
 
@@ -691,7 +722,7 @@ export async function validateFixture(invocation = {}) {
       requireFixturePageBound(page, manifestByFile.get(page.file), { imageIds, videoIds, deliveryOrigins });
       return true;
     });
-    if (bound) validatedPages.push({ file: page.file, path: page.pagePath });
+    if (bound) validatedPages.push({ file: page.file, path: displayPagePath(page.pagePath) });
   }
   await collectProblems(problems, { area: "fixture", file: FIXTURE_MANIFEST_FILE_NAME }, () => {
     requireFixtureRecordsMatch(manifest, checked);
@@ -701,6 +732,11 @@ export async function validateFixture(invocation = {}) {
   refuseProblems(problems, "validate found problems in the fixture");
 
   const hints = pageHints(checked, onProgress);
+  const warnings = {
+    ...autolinkWarnings(checked.pages?.planned, onProgress),
+    ...descriptionWarnings(checked.pages?.planned, onProgress),
+    ...authorWarnings(checked.pages?.planned, onProgress),
+  };
   onProgress(
     `Validated ${validatedPages.length} page(s), ${checked.navigation.items} navigation item(s), two themes, appearance, and footer without credentials or mutation.`,
   );
@@ -715,6 +751,7 @@ export async function validateFixture(invocation = {}) {
     },
     ...validatedSummary(checked, validatedPages),
     hints,
+    ...warnings,
     proves: [
       "fixture structure and bounded files",
       "page content and named theme contexts",
@@ -756,8 +793,15 @@ async function validatePulledWorkspace(workspaceDir, siteId, invocation, onProgr
 
   const pages = checked.settingsOnly
     ? []
-    : checked.pages.planned.map((page) => ({ file: page.file, path: page.pagePath }));
+    : checked.pages.planned.map((page) => ({ file: page.file, path: displayPagePath(page.pagePath) }));
   const hints = pageHints(checked, onProgress);
+  const warnings = checked.settingsOnly
+    ? {}
+    : {
+      ...autolinkWarnings(checked.pages.planned, onProgress),
+      ...descriptionWarnings(checked.pages.planned, onProgress),
+      ...authorWarnings(checked.pages.planned, onProgress),
+    };
   onProgress(
     checked.settingsOnly
       ? "Validated the workspace's two themes, appearance, and footer without credentials or mutation."
@@ -769,6 +813,7 @@ async function validatePulledWorkspace(workspaceDir, siteId, invocation, onProgr
     workspace: { manifest: MANIFEST_FILE_NAME, settingsOnly: checked.settingsOnly },
     ...validatedSummary(checked, pages),
     hints,
+    ...warnings,
     proves: [
       "every page source: metadata, Markdown conversion, media references, content vocabulary, and section contexts",
       "page paths, templates, and system pages against the pages the pull recorded",

package/src/workspace.js

@@ -4,6 +4,7 @@ import { lstat, mkdir, open, readdir, unlink } from "node:fs/promises";
 import path from "node:path";
 
 import { atomicWriteFile } from "./atomic-file.js";
+import { parseAuthorReference } from "./authors-contract.js";
 import { hasAsciiControl, sanitizeDiagnostic, SiteAuthoringError } from "./errors.js";
 import {
   noteEntry,
@@ -290,6 +291,9 @@ export const WORKSPACE_LIMITS = Object.freeze({
   // untouched. Generous for any real authoring workspace, and an explicit
   // refusal rather than an unbounded buffer for one that is not.
   pulledBodyBytes: 64 * 1024 * 1024,
+  // The site's authors and the members a page can name: a few hundred people
+  // at most, but written by the site and read back, so bounded by bytes.
+  authorsBytes: 1024 * 1024,
   files: 5_000,
   directoryDepth: 12,
   relativePathBytes: 1_024,
@@ -341,17 +345,31 @@ export function canonicalDocumentHash(document_) {
 
 /**
  * What a push would send for a page, as one hash: the source's bytes plus the
- * title, path and description that travel with it (for a `.pm.json` source they
- * come from the manifest, not the file). `pages push` skips a page whose key
+ * title, path, description and author that travel with it (for a `.pm.json`
+ * source they come from the manifest, not the file). `pages push` skips a page whose key
  * equals the one recorded when the workspace last agreed with the site, so an
  * unedited page is never re-sent (an update would turn an approved page back
  * into a draft). A Markdown source also folds in the hash of the document it
  * converts to, because its media references resolve through the media manifest:
  * re-uploading an image changes what is sent without changing the file.
  */
-export function pageContentKey(sourceHash, { title, path, description }, documentHash = "") {
+export function pageContentKey(sourceHash, { title, path, description, author }, documentHash = "") {
+  // The author joins the key only when there is one (TR01196). Every page
+  // without an author keeps the key it has always had, so an existing workspace
+  // does not see each of its pages as changed and resend them all, which would
+  // turn approved pages back into drafts.
   return workspaceContentHash(
-    Buffer.from(JSON.stringify([sourceHash, title ?? "", path ?? "", description ?? "", documentHash]), "utf8"),
+    Buffer.from(
+      JSON.stringify([
+        sourceHash,
+        title ?? "",
+        path ?? "",
+        description ?? "",
+        documentHash,
+        ...(typeof author === "string" && author !== "" ? [author] : []),
+      ]),
+      "utf8",
+    ),
   );
 }
 
@@ -359,6 +377,12 @@ function normalizeBaselineHash(value) {
   return typeof value === "string" && WORKSPACE_CONTENT_HASH.test(value) ? value : undefined;
 }
 
+// A folded author reference or "" (no author); anything else is a damaged member.
+function normalizeAuthorValue(value) {
+  if (value === undefined || value === "") return value;
+  return parseAuthorReference(value)?.value;
+}
+
 // A calendar date or "" (no date). Anything else is a damaged baseline member.
 function normalizeBaselineDisplayDate(value) {
   return typeof value === "string" && (value === "" || /^\d{4}-\d{2}-\d{2}$/u.test(value)) ? value : undefined;
@@ -375,7 +399,7 @@ function normalizeBaselineDisplayDate(value) {
  * dropped here instead of becoming a path refusal inside the verb that exists
  * to repair the manifest.
  */
-function isDiscoverablePageSource(file) {
+export function isDiscoverablePageSource(file) {
   if (typeof file !== "string" || !file.startsWith(`${PAGES_DIRECTORY}/`)) return false;
   const segments = file.split("/");
   return segments.length > 1
@@ -434,9 +458,10 @@ export function pageSourceRegistry(manifest) {
     const contentKey = normalizeBaselineHash(declared?.contentKey);
     const revision = normalizePageBodyRevision(declared?.revision);
     const displayDate = normalizeBaselineDisplayDate(declared?.displayDate);
+    const author = normalizeAuthorValue(declared?.author);
     const baseline =
       remoteHash === undefined && sourceHash === undefined && revision === undefined && displayDate === undefined
-        && contentKey === undefined
+        && contentKey === undefined && author === undefined
         ? undefined
         : {
           ...(remoteHash === undefined ? {} : { remoteHash }),
@@ -444,12 +469,31 @@ export function pageSourceRegistry(manifest) {
           ...(contentKey === undefined ? {} : { contentKey }),
           ...(revision === undefined ? {} : { revision }),
           ...(displayDate === undefined ? {} : { displayDate }),
+          // The author the site held for the page when this workspace last
+          // reconciled with it: what a page's own author reference is
+          // compared with before anything is sent (TR01196).
+          ...(author === undefined || author === "" ? {} : { author }),
         };
     const record = {
       pageId: entry.pageId,
       file: entry.file,
       sourceFormat,
       baseline,
+      // What a generated page was when this workspace last pulled it, kept so a
+      // pull that cannot read its body does not forget it (TR01195).
+      ...(entry.generated !== null && typeof entry.generated === "object" && !Array.isArray(entry.generated)
+        ? { generated: entry.generated }
+        : {}),
+      // What this workspace says the page's metadata is; a .pm.json page's only
+      // record of it (TR01194).
+      metadata: {
+        title: typeof entry.title === "string" ? entry.title : "",
+        path: typeof entry.path === "string" ? entry.path : "",
+        description: typeof entry.description === "string" ? entry.description : "",
+        // The author reference the site holds for the page, or the one a
+        // `pages meta set --author` is waiting to send (TR01196).
+        author: normalizeAuthorValue(entry.author) ?? "",
+      },
       baselineDiscarded: declared !== undefined && baseline === undefined,
       formatMismatch: entry.sourceFormat !== undefined && entry.sourceFormat !== sourceFormat,
       duplicateSource: false,
@@ -1150,6 +1194,14 @@ export function normalizePagePath(value) {
   return trimmed;
 }
 
+/**
+ * A page path as results show it: the home page is '/', everything else as
+ * stored. The manifest and the wire keep the empty root path.
+ */
+export function displayPagePath(value) {
+  return (normalizePagePath(value) ?? value) || "/";
+}
+
 /**
  * Chooses the workspace file name for a pulled page. The server's path is
  * preferred because it is what an author recognizes, but it is server data