@taprootio/site-authoring 0.14.1 → 0.15.0

package/src/content/vocabulary.js

@@ -75,6 +75,30 @@ export const MARK_TYPES = Object.freeze([
   "link",
 ]);
 
+// The renderer's `LINK_REL_TOKENS` and `LINK_TARGETS` (TR01190): every HTML
+// link type valid on `<a>` except `opener`. The renderer publishes only these
+// and ignores the rest, so the CLI refuses the rest. The parity test reads
+// both lists from the copied renderer.
+export const LINK_REL_TOKENS = Object.freeze([
+  "nofollow",
+  "sponsored",
+  "ugc",
+  "me",
+  "noopener",
+  "noreferrer",
+  "external",
+  "author",
+  "license",
+  "tag",
+  "bookmark",
+  "help",
+  "prev",
+  "next",
+  "privacy-policy",
+  "terms-of-service",
+]);
+export const LINK_TARGETS = Object.freeze(["_blank", "_self"]);
+
 export const NODE_TYPE_SET = Object.freeze(new Set(NODE_TYPES));
 export const MARK_TYPE_SET = Object.freeze(new Set(MARK_TYPES));
 
@@ -108,6 +132,8 @@ export const CONTENT_ERROR_CODES = Object.freeze({
   markMisplaced: "content.mark_misplaced",
   unknownMark: "content.unknown_mark",
   linkHref: "content.link_href",
+  linkRel: "content.link_rel",
+  linkTarget: "content.link_target",
   // Attributes
   attrsInvalid: "content.attrs_invalid",
   attrUnknown: "content.attr_unknown",

package/src/errors.js

@@ -91,6 +91,8 @@ export function sanitizeDiagnostic(value, fallback = "The operation failed.") {
   return [...clean].slice(0, LIMITS.diagnosticScalars).join("") || fallback;
 }
 
+const MAXIMUM_PROBLEMS = 5_000;
+
 /**
  * The fixed wording every `theme.setting_missing` detail carries. A required
  * key that is absent is exactly that: absence alone says nothing about when
@@ -175,6 +177,26 @@ export class SiteAuthoringError extends Error {
     return this;
   }
 
+  /**
+   * Attach every problem a whole-workspace check found (TR01002). The JSON
+   * result carries a bounded prefix and the count; stderr lists them all.
+   */
+  withProblems(problems) {
+    const list = Array.isArray(problems) ? problems : [];
+    this.problems = list
+      .slice(0, MAXIMUM_PROBLEMS)
+      .filter((problem) => typeof problem?.code === "string")
+      .map((problem) => ({
+        ...(typeof problem.area === "string" ? { area: sanitizeDiagnostic(problem.area, "") } : {}),
+        ...(typeof problem.file === "string" ? { file: sanitizeDiagnostic(problem.file, "") } : {}),
+        code: /^[a-z0-9_.-]+$/u.test(problem.code) ? problem.code : "site.failed",
+        ...(typeof problem.field === "string" ? { field: sanitizeDiagnostic(problem.field, "") } : {}),
+        message: sanitizeDiagnostic(problem.message),
+      }));
+    this.problemCount = list.length;
+    return this;
+  }
+
   /** Attach the non-secret identity needed to inspect or revoke a created preview. */
   withPreviewRecovery(preview) {
     const recovery = normalizePreviewRecovery(preview);

package/src/espalier-shared.js

@@ -0,0 +1,11 @@
+/**
+ * An Espalier module that sits beside the exported theme module but is not
+ * exported itself (the fit report, the color engine). Its package root
+ * re-exports every component module, which registers custom elements as it
+ * loads, so these are loaded from beside the theme module instead, sharing its
+ * instance. The exact Espalier pin and this package's tests catch a release
+ * that moves them.
+ */
+export function loadEspalierShared(file) {
+  return import(new URL(`./${file}`, import.meta.resolve("@taprootio/espalier/shared/theme")).href);
+}

package/src/font-catalog.js

@@ -0,0 +1,87 @@
+import definitions from "@taprootio/espalier/css/fonts/font-definitions.json" with { type: "json" };
+
+import { CLI_BINARY_NAME } from "./constants.js";
+
+/**
+ * `help fonts` (TR01188): the font families a published site can load, read
+ * from the catalog Espalier ships with the CLI. A theme's font fields name a
+ * family from it; the generator fetches that family's faces at publish time.
+ *
+ * The whole catalog is larger than one result may be, so the topic lists the
+ * categories and `help fonts <category>` lists one category's families.
+ */
+
+/** A catalog variant is `regular`, `italic`, or a weight with an optional `italic`. */
+function variantWeight(variant) {
+  return variant === "regular" || variant === "italic" ? 400 : Number.parseInt(variant, 10);
+}
+
+// Only upright weights: a publish loads one upright face per font field, and
+// the browser slants it for italics.
+const FAMILIES = Object.freeze(definitions.map((definition) => Object.freeze({
+  family: definition.family,
+  category: definition.category,
+  weights: Object.freeze(definition.variants.filter((variant) => !variant.endsWith("italic")).map(variantWeight)),
+})));
+
+export const FONT_CATEGORIES = Object.freeze([...new Set(FAMILIES.map((entry) => entry.category))]);
+
+const DETAILS = Object.freeze([
+  "Set fontBody, fontHeadings, fontBrand, fontMonospace or fontMenu in settings/taproot-styles.json to a CSS "
+  + "font-family list that starts with a family from this catalog, spelled exactly as listed (the match is "
+  + "case-sensitive), such as \"Inter, sans-serif\". Finish with a CSS generic family: sans-serif, serif or "
+  + "monospace, or cursive for a handwriting family. A first family that is not listed is not loaded: the page "
+  + "falls back to the rest of the list, so a misspelled name publishes quietly in a fallback font.",
+  "Each font field's weight (fontWeightBody and the others) must be one of that family's weights; normal means 400 "
+  + "and bold 700. Any other weight, or lighter or bolder, would fail the publish for a catalog family, so validate "
+  + "and theme push refuse it and name the nearest weight the family has. An unset weight "
+  + "takes the default: 400 for body and monospace, 700 for headings, brand and menu (brand also inherits the "
+  + "headings family). So when a family lacks the default weight for its field, set that field's weight.",
+  "A publish loads one upright face per font field and serves it from the site itself; visitors never contact a "
+  + "font service. Italic text is the browser slanting that face. A family with no weights offers only italics and "
+  + "cannot be used.",
+]);
+
+/** The catalog's categories, or one category's families. */
+export function getFontCatalogReference(category) {
+  const base = {
+    title: "Font catalog",
+    summary: "The font families a published site can load, by category, with the weights each offers.",
+    usage: `${CLI_BINARY_NAME} help fonts [category] [--json]`,
+    details: DETAILS,
+  };
+  if (category === undefined) {
+    return Object.freeze({
+      ...base,
+      familyCount: FAMILIES.length,
+      categories: Object.freeze(FONT_CATEGORIES.map((name) => Object.freeze({
+        category: name,
+        familyCount: FAMILIES.filter((entry) => entry.category === name).length,
+        helpCommand: `${CLI_BINARY_NAME} help fonts ${name}`,
+      }))),
+    });
+  }
+  if (!FONT_CATEGORIES.includes(category)) return undefined;
+  const families = FAMILIES.filter((entry) => entry.category === category)
+    .map(({ family, weights }) => Object.freeze({ family, weights }));
+  return Object.freeze({ ...base, category, familyCount: families.length, families: Object.freeze(families) });
+}
+
+export function formatFontCatalog(reference) {
+  const header = `${reference.title}\n${reference.summary}\n\nUsage: ${reference.usage}\n\n${
+    reference.details.map((detail) => `- ${detail}`).join("\n")
+  }\n\n`;
+  if (reference.families === undefined) {
+    return `${header}${reference.familyCount} families:\n${
+      reference.categories.map((entry) =>
+        `  ${entry.category.padEnd(14)}${String(entry.familyCount).padStart(4)}  ${entry.helpCommand}`
+      ).join("\n")
+    }\n\nAdd --json for stable machine-readable output.\n`;
+  }
+  const width = Math.max(...reference.families.map(({ family }) => family.length)) + 2;
+  return `${header}${reference.familyCount} ${reference.category} families and their weights:\n${
+    reference.families.map(({ family, weights }) =>
+      `  ${family.padEnd(width)}${weights.length > 0 ? weights.join(" ") : "none (italic only; cannot be used)"}`
+    ).join("\n")
+  }\n\nAdd --json for the same list as stable machine-readable output.\n`;
+}

package/src/footer-contract.js

@@ -235,7 +235,7 @@ function target(value, path, knownPageResourceIds, tolerateStoredValues) {
     if (knownPageResourceIds && !knownPageResourceIds.has(value.pageResourceId)) {
       fail(
         "footer.page_reference_unknown",
-        `${path}.pageResourceId must identify a page tracked by the pull manifest.`,
+        `${path}.pageResourceId must identify a page tracked by the pull manifest that the site still holds.`,
         `${path}.pageResourceId`,
       );
     }

package/src/output.js

@@ -19,6 +19,7 @@ import {
   sanitizeDiagnostic,
   SiteAuthoringError,
 } from "./errors.js";
+import { problemsWithinBudget } from "./problems.js";
 
 const SAFE_SCALAR = /^[a-z][a-z0-9]*(?: [a-z][a-z0-9]*)?$/u;
 const MAXIMUM_OUTPUT_PATH_LENGTH = 4_096;
@@ -53,6 +54,13 @@ export function failureResult(error) {
   if (Array.isArray(error.differences)) {
     result.error.differences = error.differences;
   }
+  if (Array.isArray(error.problems) && error.problems.length > 0) {
+    const problems = problemsWithinBudget(error.problems);
+    const count = Math.max(error.problemCount ?? 0, error.problems.length);
+    result.error.problems = problems;
+    result.error.problemCount = count;
+    if (problems.length < count) result.error.problemsTruncated = true;
+  }
   const previewDiagnostic = normalizePreviewDiagnostic(error.previewDiagnostic);
   if (previewDiagnostic) result.error.diagnostic = previewDiagnostic;
   const previewRecovery = normalizePreviewRecovery(error.previewRecovery);
@@ -159,6 +167,12 @@ export async function writeGithubActionsOutput(outputPath, result) {
   await appendInspectedGithubOutput(outputPath, stats, `${lines.join("\n")}\n`);
 }
 
+function problemLocation(problem) {
+  if (problem.file === undefined) return problem.field ?? problem.area ?? "-";
+  if (problem.field === undefined || problem.field.startsWith(problem.file)) return problem.field ?? problem.file;
+  return `${problem.file} ${problem.field}`;
+}
+
 export function humanFailure(error) {
   const field = error.field ? ` field=${sanitizeDiagnostic(error.field, "unknown")}` : "";
   const status = error.status ? ` status=${sanitizeDiagnostic(error.status, "unknown")}` : "";
@@ -167,8 +181,12 @@ export function humanFailure(error) {
     ? ` refusal=${sanitizeDiagnostic(kind, "unknown")}`
     : "";
   const details = error.details?.map((item) => `${item.field}: ${item.message}`).join("\n");
+  const problems = error.problems?.length > 1
+    ? error.problems.map((problem) => `  ${problemLocation(problem)} [${problem.code}]: ${problem.message}`).join("\n")
+    : undefined;
   return `${CLI_BINARY_NAME} failed [${error.code}]${field}${status}${refusal}: ${sanitizeDiagnostic(error.message)}`
-    + (details ? `\n${details}` : "");
+    + (details ? `\n${details}` : "")
+    + (problems ? `\n${problems}` : "");
 }
 
 export function serializeResult(result) {

package/src/presentation-reference.js

@@ -227,14 +227,25 @@ const THEME_GROUPS = Object.freeze([
     summary: "Choose families and weights, then tune type, spacing, radius, and fluid viewport scales together.",
     fields: Object.freeze([
       ...["fontBody", "fontHeadings", "fontBrand", "fontMonospace"].map((name) =>
-        themeField(name, "CSS font-family; empty inherits the consuming surface's fallback.")
+        themeField(
+          name,
+          "CSS font-family starting with a family from 'help fonts'; an unlisted family is not loaded. Empty "
+            + "inherits the consuming surface's fallback.",
+        )
       ),
       themeField(
         "fontMenu",
-        "CSS font-family for navigation menu items and group labels; empty falls back to fontBody, never to headings.",
+        "CSS font-family for navigation menu items and group labels, starting with a family from 'help fonts'; "
+          + "empty falls back to fontBody, never to headings.",
       ),
       ...["fontWeightBody", "fontWeightHeadings", "fontWeightBrand", "fontWeightMonospace", "fontWeightMenu"].map(
-        (name) => themeField(name, "CSS font-weight: 1–1000, normal/bold/lighter/bolder, or a CSS-wide keyword."),
+        (name) =>
+          themeField(
+            name,
+            "CSS font-weight. For a catalog family it must be one of the family's weights in 'help fonts' "
+              + "(normal is 400, bold 700); validate and theme push refuse any other value, which would fail the "
+              + "publish. Unset, it defaults to 400 for body and monospace and 700 for headings, brand and menu.",
+          ),
       ),
       themeField("rootFontSize", "Root font size in px.", { minimum: 1, warningMaximum: 100 }),
       themeField("typeRatio", "Modular type-scale ratio.", { exclusiveMinimum: 1, warningMaximum: 1.3 }),
@@ -323,11 +334,14 @@ export const ROLE_RESOLUTION = Object.freeze({
     + "makes a mapping a pin: the resolver recompiles every token the marker leaves out, so a mapping it does not "
     + "name is a cached value that is never applied. To pin a token, set the mapping and add the token to the "
     + "marker; to let a role reach it, drop the token from the marker or delete the mapping. A document that "
-    + "carries no explicitMappingTokens at all predates the marker, and every mapping in it is still a pin.",
+    + "carries no explicitMappingTokens at all predates the marker, and every mapping in it is still a pin. The "
+    + "marker is the root's alone: a mapping in a context's semanticMappings is a pin by itself, needs no marker, "
+    + "and a context cannot carry one.",
     "Otherwise the token is compiled from the roles, and an APCA contrast check may nudge an action or ink stop so "
     + "the pair stays readable.",
     "Otherwise the Espalier default mapping applies.",
-    "A context rebinds roles, lightness, tones and pins for one zone with the same precedence inside that zone.",
+    "A context rebinds roles, lightness, tones and pins for one zone with the same precedence inside that zone; its "
+    + "pins need no explicitMappingTokens.",
   ]),
 });
 
@@ -392,12 +406,12 @@ export function getThemeReference() {
       "Check the filled action before anything else looks finished. Its ramp stop is chosen by the engine near a mid-band target rather than named by the theme, so seating the ramp — the remedy for every other anchored token — cannot move it, and declaring an action role does not either. The only lever is pinning semanticMappings.actionBackground.",
       "A brand colour between roughly L 0.55 and L 0.83 cannot be a button surface at its own lightness: across that band no ink, not even pure black, reaches the Lc 75 APCA asks of a button label. Espalier then walks the label to the far end of the ramp and the button renders inverted — a dark surface carrying a pale label where the swatch wanted the opposite. Pin the stop just past the band instead. A gold at L 0.81 pinned to a tone at L 0.85 carries a dark label at Lc 76; the same gold left to the engine compiles to a brown one.",
       "Name a tone as a lowercase slug — gold-band, not goldBand. theme push refuses any other name, and refuses a mapping that names a tone its theme or context never declares.",
-      "theme push runs Espalier's fit report over the root and every context in both schemes and lists each finding as a warning reading 'fit lint <id>'; theme push --dry-run does the same and writes nothing, and validate does it for an offline fixture. Read the lints before calling a theme done: action-anchor-inversion names a filled action that rendered the opposite way round from the swatches it declares, apca-target-unmet names a pair enforcement could not rescue, and action-canvas-separation and link-hover-ordering cover an action lost in its canvas and a hover weaker than its link. A lint is a warning, not a refusal, so a push still goes through with one — the lints are what tell an agent the design did not survive the compile.",
+      "theme push runs Espalier's fit report over the root and every context in both schemes and lists each finding as a warning reading 'fit lint <id>'; theme push --dry-run does the same and writes nothing, and validate does it for an offline fixture. Read the lints before calling a theme done: action-anchor-inversion names a filled action that rendered the opposite way round from the swatches it declares, apca-target-unmet names a pair enforcement could not rescue, and action-canvas-separation and link-hover-ordering cover an action lost in its canvas and a hover weaker than its link. A lint is a warning, not a refusal, so a push still goes through with one — the lints are what tell an agent the design did not survive the compile. Contrast and status-color warnings end with 'Nearest passing value: …' when the CLI finds one: it applied that value to a copy of the theme and checked that the warning clears without raising another, so start there and check again. validate and theme push refuse a font weight a catalog family has no face for (theme.font_weight_unavailable), because the publish would fail, and name the nearest weight it has.",
       "Add named contexts for whole zones, including inverted zones, and rebind lightness when the zone changes brightness. A context that declares its own action needs its own actionBackground pin: without one it compiles at the engine's mid-band stop, and where the root is pinned it carries the root's pin instead, whatever action colour the context declares.",
       "Tune typography, type/space ratios, radii, and viewport interpolation as one layout system.",
       "Typography is per scheme on purpose: light and dark set their own moods, so a heading, body, or brand face that differs between them is a design choice, and theme push never warns about it.",
       "Retune danger/success/warning/info through intents without changing their meanings; design data palettes separately.",
-      "Use semanticMappings only for meanings roles and contexts cannot express; scattered pins shadow the coherent model. pull keeps only authored pins there and lists them in explicitMappingTokens; a mapping the marker does not name is never applied, so a hand-added pin needs its token added to the marker or theme push reports it as inert.",
+      "Use semanticMappings only for meanings roles and contexts cannot express; scattered pins shadow the coherent model. pull keeps only authored pins there and lists them in explicitMappingTokens; a mapping the marker does not name is never applied, so a hand-added pin at the root needs its token added to the marker or theme push reports it as inert. A pin inside a context needs no marker.",
       "Run theme push --dry-run and clear its warnings, fit lints included; then run theme push and verify text, actions, focus states, and both schemes in authoring previews.",
     ],
     example: THEME_EXAMPLE,

package/src/problems.js

@@ -0,0 +1,116 @@
+import { SiteAuthoringError } from "./errors.js";
+
+/**
+ * Collecting problems instead of stopping at the first (TR01002, TR00823).
+ *
+ * A check that runs over a whole workspace reports every refusal it finds, so
+ * an importer fixing hundreds of converted pages learns them all in one run.
+ * Only `SiteAuthoringError`s are collected: anything else is a defect, and
+ * hiding it inside a list would turn a crash into a refusal.
+ */
+
+/** The parts of a workspace a check reports a problem against. */
+export const CHECK_AREA = Object.freeze({
+  media: "media",
+  pages: "pages",
+  presentation: "presentation",
+  footer: "footer",
+  navigation: "navigation",
+  redirects: "redirects",
+  forms: "forms",
+});
+
+// Kept off the JSON so a problem serializes as plain data, but remembered so a
+// single refusal can be rethrown exactly as it was raised.
+const SOURCE = Symbol("source error");
+
+function withContext(problem, context, error) {
+  const located = {
+    ...(context.area === undefined ? {} : { area: context.area }),
+    ...(context.file === undefined || problem.file !== undefined ? {} : { file: context.file }),
+    ...problem,
+  };
+  if (located.field === located.file) delete located.field;
+  Object.defineProperty(located, SOURCE, { value: error });
+  return located;
+}
+
+/** The problems one refusal stands for: its own list when it carries one, otherwise itself. */
+export function problemsOf(error, context = {}) {
+  const own = Array.isArray(error.problems) && error.problems.length > 0
+    ? error.problems
+    : [{ code: error.code, ...(error.field === undefined ? {} : { field: error.field }), message: error.message }];
+  return own.map((problem) => withContext(problem, context, error));
+}
+
+/**
+ * Runs `action`, adding its refusal to `problems` instead of throwing. Returns
+ * the action's value, or undefined when it refused.
+ */
+export async function collectProblems(problems, context, action) {
+  try {
+    return await action();
+  } catch (error) {
+    if (!(error instanceof SiteAuthoringError)) throw error;
+    problems.push(...problemsOf(error, context));
+    return undefined;
+  }
+}
+
+/**
+ * One refusal for a list of problems. When they all came from one refusal it
+ * is rethrown as raised, alternatives and differences included, so a check
+ * that finds one problem fails exactly as it did before problems were
+ * collected. Otherwise the code, message and field are the first refusal's and
+ * `error.problems` lists every problem.
+ */
+export function problemsError(problems, summary) {
+  const [first] = problems;
+  if (problems.every((problem) => problem[SOURCE] !== undefined && problem[SOURCE] === first[SOURCE])) {
+    return first[SOURCE];
+  }
+  return new SiteAuthoringError(
+    first[SOURCE]?.code ?? first.code,
+    `${summary}: ${problems.length} problems. First: ${first[SOURCE]?.message ?? first.message}`,
+    { field: first[SOURCE]?.field ?? first.field ?? first.file },
+  ).withProblems(problems);
+}
+
+// A whole-workspace check can find thousands of problems. A JSON result keeps
+// as many as fit well inside its 64 KiB bound; stderr lists them all.
+const PROBLEM_BUDGET_BYTES = 40 * 1024;
+
+/** The leading items whose JSON fits `budget` bytes. */
+export function withinByteBudget(items, budget) {
+  const kept = [];
+  let bytes = 0;
+  for (const item of items) {
+    bytes += Buffer.byteLength(JSON.stringify(item), "utf8") + 1;
+    if (bytes > budget) break;
+    kept.push(item);
+  }
+  return kept;
+}
+
+/** The leading problems that fit the result's byte budget, or a smaller one. */
+export function problemsWithinBudget(problems, budget = PROBLEM_BUDGET_BYTES) {
+  return withinByteBudget(problems, Math.min(budget, PROBLEM_BUDGET_BYTES));
+}
+
+/**
+ * Under `apply`, a step refuses to send what its plan did not list: an input
+ * edited, or a site state changed, while an earlier step ran was never reviewed.
+ */
+export function planStale(subject, field) {
+  return new SiteAuthoringError(
+    "apply.plan_stale",
+    `${subject} changed after the plan was made, so this step stopped before sending it. Run 'taproot-site plan' again and `
+      + "apply the new planHash.",
+    { field },
+  );
+}
+
+/** Throws when `problems` is not empty. */
+export function refuseProblems(problems, summary) {
+  if (problems.length > 0) throw problemsError(problems, summary);
+}