@taprootio/site-authoring 0.30.0 → 0.31.0

package/src/content/free-form-section-registry.json

@@ -1,5 +1,16 @@
 {
-  "version": 14,
+  "version": 15,
+
+  "imageDescription": {
+    "fields": {
+      "descriptionMode": { "kind": "mode", "storage": "persisted" },
+      "defaultDescription": { "kind": "text", "storage": "hydratedReadOnly" },
+      "descriptionRevision": { "kind": "revision", "storage": "hydratedReadOnly" }
+    },
+    "modes": ["inherit", "custom", "decorative"],
+    "maxDefaultDescriptionScalars": 1000,
+    "maxRevision": "9223372036854775807"
+  },
   "section": {
     "nodeType": "section",
     "label": "Section",
@@ -84,7 +95,10 @@
             "optionalKeys": [
               "width",
               "height",
-              "alt"
+              "alt",
+              "descriptionMode",
+              "defaultDescription",
+              "descriptionRevision"
             ],
             "urls": {
               "minItems": 1,
@@ -124,7 +138,10 @@
             "optionalKeys": [
               "width",
               "height",
-              "alt"
+              "alt",
+              "descriptionMode",
+              "defaultDescription",
+              "descriptionRevision"
             ],
             "urls": {
               "minItems": 1,
@@ -237,7 +254,10 @@
             "optionalKeys": [
               "width",
               "height",
-              "alt"
+              "alt",
+              "descriptionMode",
+              "defaultDescription",
+              "descriptionRevision"
             ],
             "urls": {
               "minItems": 1,

package/src/content/free-form-sections.js

@@ -1,4 +1,5 @@
 import registry from "./free-form-section-registry.json" with { type: "json" };
+import { imageDescriptionIssues, pickImageDescriptionFields } from "./image-description-validation.js";
 
 import {
   CONTENT_ERROR_CODES as CODES,
@@ -45,6 +46,12 @@ function decorationDeliveryUrlIsSafe(value) {
   }
 }
 
+function validateImageDescription(image, path, label, report) {
+  for (const issue of imageDescriptionIssues(image)) {
+    report(`${path}/${issue.field}`, CODES.attrInvalid, `${label} ${issue.field} must ${issue.expected}.`);
+  }
+}
+
 function normalizeProcessedSectionImage(value, definition, path, label, report) {
   let valid = true;
   const reject = (errorPath, code, message) => {
@@ -170,6 +177,7 @@ function normalizeProcessedSectionImage(value, definition, path, label, report)
     reject(`${path}/alt`, CODES.attrInvalid, `${label} alt must be a string.`);
   }
 
+  validateImageDescription(value, path, label, reject);
   if (!valid) return undefined;
   return Object.freeze({
     imageId: value.imageId,
@@ -182,6 +190,7 @@ function normalizeProcessedSectionImage(value, definition, path, label, report)
     ...(Object.hasOwn(value, "width") ? { width: value.width } : {}),
     ...(Object.hasOwn(value, "height") ? { height: value.height } : {}),
     ...(Object.hasOwn(value, "alt") ? { alt: value.alt } : {}),
+    ...pickImageDescriptionFields(value),
   });
 }
 
@@ -457,6 +466,7 @@ export function normalizeFreeFormSectionDecoration(
     if (Object.hasOwn(image, "alt") && typeof image.alt !== "string") {
       report(`${imagePath}/alt`, CODES.attrInvalid, "Section decoration image alt must be a string.");
     }
+    validateImageDescription(image, imagePath, "Section decoration image", report);
   }
 
   for (const [name, definition] of Object.entries(fields)) {
@@ -500,6 +510,7 @@ export function normalizeFreeFormSectionDecoration(
     ...(Object.hasOwn(image, "width") ? { width: image.width } : {}),
     ...(Object.hasOwn(image, "height") ? { height: image.height } : {}),
     ...(Object.hasOwn(image, "alt") ? { alt: image.alt } : {}),
+    ...pickImageDescriptionFields(image),
   };
   const normalized = { image: Object.freeze(normalizedImage) };
   for (const [name, definition] of Object.entries(fields)) {

package/src/content/image-description-document.js

@@ -0,0 +1,108 @@
+// Generated from shared/image-description-document.ts by scripts/sync-field-validation.mjs. Do not edit.
+import { IMAGE_DESCRIPTION_HYDRATED_KEYS, resolveImageDescription } from "./image-description-validation.js";
+export function imageDescriptionImageId(image) {
+    return typeof image.imageId === "string"
+        ? image.imageId
+        : typeof image.id === "string" && "caption" in image
+            ? image.id
+            : undefined;
+}
+/** Component data may be serialized inside a structured document. Keep unchanged bytes intact. */
+export function visitImageDescriptionObjects(value, transform, seen = new WeakSet()) {
+    if (!value || typeof value !== "object" || seen.has(value))
+        return;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const child of value)
+            visitImageDescriptionObjects(child, transform, seen);
+        return;
+    }
+    const record = value;
+    transform(record);
+    for (const [key, child] of Object.entries(record)) {
+        if (key === "componentData" && typeof child === "string") {
+            try {
+                const data = JSON.parse(child);
+                const before = JSON.stringify(data);
+                visitImageDescriptionObjects(data, transform, seen);
+                const after = JSON.stringify(data);
+                if (before !== after)
+                    record[key] = after;
+            }
+            catch { /* Existing content validation owns malformed component data. */ }
+        }
+        else
+            visitImageDescriptionObjects(child, transform, seen);
+    }
+}
+export function referencedImageDescriptionIds(value) {
+    const ids = new Set();
+    visitImageDescriptionObjects(value, image => {
+        const id = imageDescriptionImageId(image);
+        if (id)
+            ids.add(id);
+    });
+    return ids;
+}
+/** API delivery state does not belong in authored documents or workspace hashes. */
+export function stripImageDescriptionHydration(value) {
+    const copy = structuredClone(value);
+    visitImageDescriptionObjects(copy, image => {
+        for (const key of IMAGE_DESCRIPTION_HYDRATED_KEYS)
+            delete image[key];
+        if (image.descriptionMode === "inherit") {
+            delete image.alt;
+            delete image.altText;
+        }
+        const nested = image.image;
+        if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+            const bannerImage = nested;
+            if ((image.descriptionMode ?? bannerImage.descriptionMode) === "inherit") {
+                delete image.altText;
+                delete bannerImage.alt;
+                delete bannerImage.altText;
+            }
+        }
+    });
+    return copy;
+}
+const text = (value) => typeof value === "string" ? value : undefined;
+const placementMode = (mode, contextual) => mode === undefined || mode === null || mode === "" ? contextual.trim() ? "custom" : "inherit" : mode;
+export function hydrateImageDescriptions(value, source) {
+    const copy = structuredClone(value);
+    const metadata = (image, delivery) => {
+        image.defaultDescription = delivery.defaultDescription ?? null;
+        image.descriptionRevision = delivery.descriptionRevision;
+    };
+    visitImageDescriptionObjects(copy, image => {
+        const id = imageDescriptionImageId(image);
+        const delivery = id ? source(id) : undefined;
+        if (delivery) {
+            const album = "caption" in image && "urls" in image;
+            const field = "altText" in image || album ? "altText" : "alt";
+            const contextual = text(image[field])
+                ?? (album && image.descriptionMode == null ? text(image.caption) : undefined) ?? "";
+            const mode = placementMode(text(image.descriptionMode), contextual);
+            image.descriptionMode = mode;
+            image[field] = resolveImageDescription(mode, contextual, delivery.defaultDescription ?? "");
+            metadata(image, delivery);
+        }
+        const nested = image.image;
+        if (!("altText" in image || "descriptionMode" in image || "overlayText" in image)
+            || !nested || typeof nested !== "object" || Array.isArray(nested))
+            return;
+        const bannerImage = nested;
+        const bannerId = imageDescriptionImageId(bannerImage);
+        const bannerSource = bannerId ? source(bannerId) : undefined;
+        if (!bannerSource)
+            return;
+        const contextual = text(image.altText) ?? "";
+        const mode = placementMode(text(image.descriptionMode) ?? text(bannerImage.descriptionMode), contextual);
+        image.descriptionMode = mode;
+        image.altText = resolveImageDescription(mode, contextual, bannerSource.defaultDescription ?? "");
+        metadata(image, bannerSource);
+        bannerImage.descriptionMode = mode;
+        bannerImage.alt = image.altText;
+    });
+    return copy;
+}

package/src/content/image-description-validation.js

@@ -0,0 +1,70 @@
+// Generated from shared/image-description-validation.ts by scripts/sync-field-validation.mjs. Do not edit.
+import registry from "./free-form-section-registry.json" with { type: "json" };
+const definition = registry.imageDescription;
+export const IMAGE_DESCRIPTION_MODES = Object.freeze([...definition.modes]);
+export const IMAGE_DESCRIPTION_KEYS = Object.freeze(Object.keys(definition.fields));
+const fields = Object.entries(definition.fields);
+export const IMAGE_DESCRIPTION_PERSISTED_KEYS = Object.freeze(fields.filter(([, field]) => field.storage === "persisted").map(([key]) => key));
+export const IMAGE_DESCRIPTION_HYDRATED_KEYS = Object.freeze(fields.filter(([, field]) => field.storage === "hydratedReadOnly").map(([key]) => key));
+export function isImageDescriptionMode(value) {
+    return value === undefined || value === null || IMAGE_DESCRIPTION_MODES.includes(value);
+}
+export function isImageDefaultDescription(value) {
+    return value === undefined || value === null || typeof value === "string"
+        && !/[\uD800-\uDFFF]/u.test(value) && [...value].length <= definition.maxDefaultDescriptionScalars;
+}
+/** Decimal strings retain int64 precision across JSON and JavaScript. */
+export function normalizeImageDescriptionRevision(value) {
+    if (typeof value === "number")
+        return Number.isSafeInteger(value) && value >= 0 ? String(value) : undefined;
+    if (typeof value !== "string" || !/^(?:0|[1-9][0-9]*)$/u.test(value))
+        return undefined;
+    const maximum = definition.maxRevision;
+    return value.length < maximum.length || value.length === maximum.length && value <= maximum ? value : undefined;
+}
+export function isImageDescriptionRevision(value) {
+    return value === undefined || value === null || normalizeImageDescriptionRevision(value) !== undefined;
+}
+/** Editor controls repair unknown choices; delivery validation reports them instead. */
+export function imageDescriptionMode(mode, contextual) {
+    return typeof mode === "string" && IMAGE_DESCRIPTION_MODES.includes(mode)
+        ? mode
+        : contextual?.trim()
+            ? "custom"
+            : "inherit";
+}
+export function resolveImageDescription(mode, contextual, fallback) {
+    switch (mode) {
+        case "decorative":
+            return "";
+        case "inherit":
+            return fallback;
+        case "custom":
+            return contextual;
+        default:
+            return contextual.trim() ? contextual : fallback;
+    }
+}
+const validators = {
+    mode: { accepts: isImageDescriptionMode, expected: `be ${IMAGE_DESCRIPTION_MODES.join(", ")}, or null` },
+    text: {
+        accepts: isImageDefaultDescription,
+        expected: "be valid Unicode text within the registry's scalar limit, or null",
+    },
+    revision: {
+        accepts: isImageDescriptionRevision,
+        expected: "be a nonnegative safe integer or canonical int64 decimal string, or null",
+    },
+};
+export function imageDescriptionIssues(value) {
+    return fields.flatMap(([field, contract]) => {
+        const validator = validators[contract.kind];
+        return validator.accepts(value[field])
+            ? []
+            : [{ field, storage: contract.storage, expected: validator.expected }];
+    });
+}
+export function pickImageDescriptionFields(value, storage) {
+    return Object.fromEntries(fields.filter(([key, field]) => (!storage || field.storage === storage)
+        && Object.prototype.hasOwnProperty.call(value, key)).map(([key]) => [key, value[key]]));
+}

package/src/content/tiptap-prosemirror.ts

@@ -8,6 +8,7 @@
  */
 
 import freeFormSectionRegistry from "./free-form-section-registry.json" with { type: "json" };
+import { imageDescriptionIssues } from "./image-description-validation.js";
 import {
   explicitImageMaxHeight,
   mediaOverrideStyleParts,
@@ -820,11 +821,15 @@ function renderSection(
 }
 
 type NormalizedSectionImage = {
+  imageId: string;
   src: string;
   urls: Array<{ minWidth: number; url: string }>;
   width?: number;
   height?: number;
   alt?: string;
+  descriptionMode?: string | null;
+  defaultDescription?: string | null;
+  descriptionRevision?: number | string | null;
 };
 
 type NormalizedSectionBackground = {
@@ -912,12 +917,17 @@ function normalizeSectionImage(
     || (hasOwn(value, "height") && !isPositiveInteger(value.height))
     || (hasOwn(value, "alt") && typeof value.alt !== "string")
   ) return undefined;
+  if (imageDescriptionIssues(value).length > 0) return undefined;
   return {
+    imageId: value.imageId as string,
     src,
     urls: candidates,
     width: isPositiveInteger(value.width) ? value.width : undefined,
     height: isPositiveInteger(value.height) ? value.height : undefined,
     alt: typeof value.alt === "string" ? value.alt : undefined,
+    descriptionMode: value.descriptionMode as string | null | undefined,
+    defaultDescription: value.defaultDescription as string | null | undefined,
+    descriptionRevision: value.descriptionRevision as number | string | null | undefined,
   };
 }
 

package/src/content/validate-document.js

@@ -1,3 +1,4 @@
+import { IMAGE_DESCRIPTION_MODES } from "./image-description-validation.js";
 import { validateComponentBlock } from "./components.js";
 import {
   FREE_FORM_SECTION_REGISTRY,
@@ -180,6 +181,7 @@ const IMAGE_ATTRS = Object.freeze({
   ),
   urls: URLS_SPEC,
   alt: optionalString(),
+  descriptionMode: optionalEnum(IMAGE_DESCRIPTION_MODES),
   width: optionalPositiveInteger(),
   height: optionalPositiveInteger(),
   crop: CROP_SPEC,

package/src/image-description-contract.js

@@ -0,0 +1,84 @@
+import { normalizeImageDescriptionRevision } from "./content/image-description-validation.js";
+import { LIMITS } from "./constants.js";
+import { hasControlCharacter, SiteAuthoringError } from "./errors.js";
+
+export const IMAGE_LIST_DEFAULT_PAGE_SIZE = 25;
+export const IMAGE_LIST_MAXIMUM_PAGE_SIZE = 100;
+const IMAGE_ID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/u;
+
+export function isImageId(value) {
+  return typeof value === "string" && IMAGE_ID.test(value) && value !== "00000000-0000-0000-0000-000000000000";
+}
+
+export function requireImageId(value) {
+  if (!isImageId(value)) {
+    throw new SiteAuthoringError("media.image_id_invalid", "Name exactly one canonical lowercase image UUID.", {
+      field: "imageId", exitCode: 2,
+    });
+  }
+  return value;
+}
+
+export { normalizeImageDescriptionRevision as imageDescriptionRevision } from "./content/image-description-validation.js";
+
+export function imageListOptions(invocation = {}) {
+  const pageSize = invocation.pageSize === undefined ? IMAGE_LIST_DEFAULT_PAGE_SIZE : Number(invocation.pageSize);
+  if ((invocation.pageSize !== undefined && !["number", "string"].includes(typeof invocation.pageSize))
+    || !Number.isInteger(pageSize) || pageSize < 1 || pageSize > IMAGE_LIST_MAXIMUM_PAGE_SIZE
+    || (typeof invocation.pageSize === "string" && !/^[1-9][0-9]*$/u.test(invocation.pageSize))) {
+    throw new SiteAuthoringError("media.image_page_size_invalid", "--page-size must be a whole number from 1 to 100.", {
+      field: "pageSize", exitCode: 2,
+    });
+  }
+  const pageToken = invocation.pageToken ?? "";
+  if (typeof pageToken !== "string" || !pageToken.isWellFormed()
+    || Buffer.byteLength(pageToken, "utf8") > LIMITS.configPathBytes) {
+    throw new SiteAuthoringError("media.image_page_token_invalid", "--page-token must be the cursor from the previous result.", {
+      field: "pageToken", exitCode: 2,
+    });
+  }
+  return { pageSize, pageToken, missingDescription: invocation.missingDescription === true };
+}
+
+export function imageDescriptionOptions(invocation = {}) {
+  const hasDescription = invocation.imageDescription !== undefined;
+  const clear = invocation.clearDescription === true;
+  if (hasDescription === clear) {
+    throw new SiteAuthoringError("media.image_description_choice", "Supply exactly one of --description or --clear.", {
+      field: "description", exitCode: 2,
+    });
+  }
+  const description = clear ? "" : invocation.imageDescription;
+  if (typeof description !== "string" || !description.isWellFormed()
+    || Buffer.byteLength(description, "utf8") > LIMITS.configBytes) {
+    throw new SiteAuthoringError("media.image_description_invalid", "--description needs bounded, valid Unicode text.", {
+      field: "description", exitCode: 2,
+    });
+  }
+  const expectedRevision = normalizeImageDescriptionRevision(invocation.expectedRevision);
+  if (expectedRevision === undefined) {
+    throw new SiteAuthoringError("media.image_revision_required",
+      "Supply --expected-revision from the image's list/get result, as a nonnegative int64 decimal integer.", {
+        field: "expectedRevision", exitCode: 2,
+      });
+  }
+  const onlyIfMissing = invocation.onlyIfMissing === true;
+  if (onlyIfMissing && description.trim() === "") {
+    throw new SiteAuthoringError("media.image_condition_clear", "--if-missing cannot clear a description.", {
+      field: "onlyIfMissing", exitCode: 2,
+    });
+  }
+  return { defaultDescription: description, expectedRevision, onlyIfMissing };
+}
+
+export function safeImagePreviewUrl(value) {
+  if (typeof value !== "string" || !value.isWellFormed() || value.length > LIMITS.configPathBytes
+    || hasControlCharacter(value) || /[\s\\]/u.test(value)) return "";
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && url.username === "" && url.password === ""
+        && url.search === "" && url.hash === "" ? url.href : "";
+  } catch {
+    return "";
+  }
+}

package/src/navigation-readiness.js

@@ -0,0 +1,47 @@
+const READY = "NAVIGATION_PUBLISHING_READINESS_STATE_READY";
+const BLOCKED = "NAVIGATION_PUBLISHING_READINESS_STATE_BLOCKED";
+const UNKNOWN = "NAVIGATION_PUBLISHING_READINESS_STATE_UNKNOWN";
+const REASON_PREFIX = "NAVIGATION_PUBLISHING_READINESS_BLOCKER_REASON_";
+const MESSAGES = {
+  PAGE_NOT_INCLUDED: "Include this approved page in the release.",
+  PAGE_NOT_APPROVED: "Approve this page and include it in the release.",
+  FOLDER_NEEDS_RELEASED_CONTENT: "Publish a qualifying page under this path, or approve and include one in this release.",
+  TARGET_UNAVAILABLE: "Remove or replace this unavailable navigation target.",
+};
+
+export function normalizeNavigationReadiness(value) {
+  return {
+    state: [READY, BLOCKED].includes(value?.state) ? value.state : UNKNOWN,
+    blockers: (Array.isArray(value?.blockers) ? value.blockers : []).map((blocker) => ({
+      resourceId: typeof blocker?.resourceId === "string" ? blocker.resourceId : "",
+      pageId: typeof blocker?.pageId === "string" ? blocker.pageId : "",
+      title: typeof blocker?.title === "string" ? blocker.title : "",
+      path: typeof blocker?.path === "string" ? blocker.path : "",
+      reason: typeof blocker?.reason === "string" ? blocker.reason : "",
+    })),
+  };
+}
+
+export function isNavigationReady(navigation) {
+  return navigation.state === READY;
+}
+
+export function describeNavigationReadiness(navigation) {
+  if (isNavigationReady(navigation)) return "Navigation is ready.";
+  if (navigation.state !== BLOCKED) return "Navigation could not be checked. Try the readiness check again.";
+  const details = navigation.blockers.slice(0, 20).map((blocker) => {
+    const target = blocker.title || "Unavailable page";
+    const path = blocker.pageId ? ` (/${blocker.path.replace(/^\/+/, "")})` : "";
+    const message = MESSAGES[blocker.reason.replace(REASON_PREFIX, "")] || MESSAGES.TARGET_UNAVAILABLE;
+    return `${target}${path}: ${message}`;
+  });
+  return details.length ? `Navigation is blocked. ${details.join(" ")}` : "Navigation cannot be published with this set.";
+}
+
+export function reportNavigationReadiness(navigation) {
+  return {
+    state: navigation.state,
+    blockers: navigation.blockers.slice(0, 20),
+    ...(navigation.blockers.length > 20 ? { blockersTruncated: true } : {}),
+  };
+}

package/src/output.js

@@ -159,6 +159,14 @@ export async function writeGithubActionsOutput(outputPath, result) {
   const safeResult = structuredClone(result);
   if (safeResult.verb === "preview page") delete safeResult.url;
   if (safeResult.stagingPreview) delete safeResult.stagingPreview.url;
+  if (["media images list", "media images get", "media images describe"].includes(safeResult.verb)) {
+    const images = safeResult.image ? [safeResult.image] : safeResult.images?.items ?? [];
+    for (const image of images) {
+      delete image.previewUrl;
+      delete image.responsivePreviewUrls;
+    }
+  }
+  for (const image of safeResult.siteHealth?.imageFindings ?? []) delete image.previewUrl;
   const json = requireBoundedJson(safeResult);
   const delimiter = githubDelimiter(json);
   const lines = [

package/src/page-metadata.js

@@ -4,9 +4,9 @@ import { boundedByBytes } from "./session.js";
 import { displayPagePath } from "./workspace.js";
 
 /**
- * A page description is what search results and link previews show. Past about
- * 160 characters search engines cut it off, so it is warned about; past 1000 it
- * is refused, here and by the API (TR01194).
+ * Description length advice is shared with the document rules. The separate
+ * descriptionWarnings output stays compatible; the 1000-character storage
+ * maximum is still enforced here and by the API (TR01194).
  */
 export { DESCRIPTION_WARN_LENGTH };
 export const DESCRIPTION_MAXIMUM_LENGTH = 1000;
@@ -20,27 +20,27 @@ export function requireDescriptionLength(description, field = "description") {
     throw new SiteAuthoringError(
       "pages.description_too_long",
       `The description is ${length(description)} characters; it may be at most ${DESCRIPTION_MAXIMUM_LENGTH} `
-        + `(search results show about ${DESCRIPTION_WARN_LENGTH}).`,
+        + `(the writing guidance is at most ${DESCRIPTION_WARN_LENGTH}).`,
       { field },
     );
   }
 }
 
-/** Warnings for descriptions search results will cut off, named per page. */
+/** The compatible length-warning output for known author-entered descriptions. */
 export function descriptionWarnings(pages, onProgress) {
   const items = [];
   for (const page of pages ?? []) {
-    const description = page.declaredDescription ?? page.description;
-    if (typeof description !== "string" || length(description) <= DESCRIPTION_WARN_LENGTH) continue;
+    const description = page.metadataDescriptionKnown === false ? undefined : page.declaredDescription ?? page.description;
+    if (typeof description !== "string" || length(description.trim()) <= DESCRIPTION_WARN_LENGTH) continue;
     const item = {
       code: PAGE_DESCRIPTION_LONG,
       file: page.file,
       path: displayPagePath(page.pagePath ?? page.path),
-      length: length(description),
+      length: length(description.trim()),
     };
     onProgress(
-      `Warning: ${item.file}'s description is ${item.length} characters; search results show about `
-        + `${DESCRIPTION_WARN_LENGTH}.`,
+      `Warning: ${item.file}'s description is ${item.length} characters; consider shortening it `
+        + `(guidance: at most ${DESCRIPTION_WARN_LENGTH}).`,
     );
     items.push(item);
   }