@drawnagency/primitives 0.1.115 → 0.1.116

package/src/lib/section-check.ts

@@ -0,0 +1,166 @@
+import { decodeHTMLStrict } from "entities";
+import type { ZodError } from "zod";
+import { blockDepth, MAX_BLOCK_DEPTH, LayoutEnvelopeSchema } from "../schemas/block";
+import { getSchema, getRichTextFields } from "./registry";
+import { REFERENCE_TYPE } from "./reference-type";
+
+/**
+ * The first thing wrong with one section body: schema, then layout envelope,
+ * then nesting depth, then a Reference nested in a container. Only ever one — a
+ * body failing its schema is not also judged on its layout — so the write
+ * path's `errors[0]` stays the first failure it has always reported.
+ */
+export type SectionCheckError =
+  | { code: "schema"; zodError: ZodError }
+  | { code: "layout"; zodError: ZodError }
+  | { code: "depth" }
+  | { code: "reference-in-container" };
+
+/** HTML entities found in one plain-text field, by path relative to the section. */
+export interface EntityFinding {
+  path: string;
+  entities: string[];
+}
+
+export interface SectionCheck {
+  /**
+   * No schema is registered for the type, so only the nesting bound was
+   * checked. Whether that is acceptable (a site-local type) or an unknown type
+   * is the caller's call.
+   */
+  unregistered: boolean;
+  error: SectionCheckError | null;
+  /** Empty whenever `error` is set. */
+  entities: EntityFinding[];
+}
+
+/**
+ * Judge one section body against `type`'s registered schema — the write path's
+ * (`validateContent`) per-section rules, kept here so the site validators can
+ * apply the same ones.
+ * Reads the schema registry only: callers register the schemas first.
+ */
+export function checkSection(type: string, body: unknown): SectionCheck {
+  const schema = getSchema(type);
+  if (!schema) {
+    // Nesting is still bounded: MAX_BLOCK_DEPTH guards the renderer, and an
+    // unvalidated type can still carry a `children` tree.
+    return { unregistered: true, error: blockDepth(body) > MAX_BLOCK_DEPTH ? { code: "depth" } : null, entities: [] };
+  }
+  const fail = (error: SectionCheckError): SectionCheck => ({ unregistered: false, error, entities: [] });
+
+  const result = schema.safeParse(body);
+  if (!result.success) return fail({ code: "schema", zodError: result.error });
+  // The per-type schema doesn't declare the top-level `layout` envelope (it
+  // lives beside `type`/`content`/`options` in the section file), so validate
+  // it separately — the write path preserves it.
+  const rawLayout = (body as { layout?: unknown } | null)?.layout;
+  if (rawLayout !== undefined) {
+    const layoutResult = LayoutEnvelopeSchema.safeParse(rawLayout);
+    if (!layoutResult.success) return fail({ code: "layout", zodError: layoutResult.error });
+  }
+  if (blockDepth(result.data) > MAX_BLOCK_DEPTH) return fail({ code: "depth" });
+  // A Reference is expanded into its sources only at the top level of a page;
+  // as a container child it would silently render nothing.
+  const children = (result.data as { content?: { children?: unknown } }).content?.children;
+  if (Array.isArray(children) && children.some((child) => (child as { type?: unknown })?.type === REFERENCE_TYPE)) {
+    return fail({ code: "reference-in-container" });
+  }
+
+  const entities: EntityFinding[] = [];
+  walkSectionForEntities(type, result.data as { content?: unknown; options?: unknown }, "", (path, tokens) => {
+    entities.push({ path, entities: tokens });
+  });
+  return { unregistered: false, error: null, entities };
+}
+
+// Plain-text fields render HTML entities LITERALLY (only registry-declared
+// rich-text fields are HTML) — an agent pasting "’" into a heading ships
+// it verbatim to viewers. A token counts as an entity when it is a numeric
+// character reference or when the HTML5 strict decoder recognizes it — strict
+// decoding requires an exact known name + semicolon, so legitimate text like
+// "R&D;" never matches.
+const ENTITY_RE = /&(#\d{1,7}|#[xX][0-9a-fA-F]{1,6}|[a-zA-Z][a-zA-Z0-9]{1,31});/g;
+
+function entitiesIn(value: string): string[] {
+  const found: string[] = [];
+  for (const m of value.matchAll(ENTITY_RE)) {
+    const token = m[0];
+    if ((m[1].startsWith("#") || decodeHTMLStrict(token) !== token) && !found.includes(token)) {
+      found.push(token);
+    }
+  }
+  return found;
+}
+
+function visitPlainLeaf(value: unknown, path: string, report: (path: string, entities: string[]) => void): void {
+  if (typeof value === "string") {
+    const tokens = entitiesIn(value);
+    if (tokens.length > 0) report(path, tokens);
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((v, i) => visitPlainLeaf(v, `${path}[${i}]`, report));
+    return;
+  }
+  if (typeof value === "object" && value !== null) {
+    for (const [k, v] of Object.entries(value)) visitPlainLeaf(v, `${path}.${k}`, report);
+  }
+}
+
+// Mirrors sanitizeSectionContent's traversal: rich-text fields are top-level
+// keys of a block's `content` (per type), and `content.children` holds nested
+// blocks that carry their own type. Everything else — including the whole
+// `options` subtree (plain-text config like the colors section's label) — is
+// plain text. Reported paths are relative to the section object itself
+// ("content.heading", "options.label", "content.children[0].content.heading").
+function walkSectionForEntities(
+  type: string,
+  block: { content?: unknown; options?: unknown },
+  prefix: string,
+  report: (path: string, entities: string[]) => void,
+): void {
+  const { content, options } = block;
+  if (typeof content === "object" && content !== null) {
+    const rich = new Set(getRichTextFields(type));
+    for (const [key, value] of Object.entries(content as Record<string, unknown>)) {
+      if (rich.has(key)) continue;
+      if (key === "children" && Array.isArray(value)) {
+        value.forEach((child, i) => {
+          const c = child as { type?: unknown } | null;
+          if (c && typeof c === "object" && typeof c.type === "string") {
+            walkSectionForEntities(c.type, c as { content?: unknown; options?: unknown }, `${prefix}content.children[${i}].`, report);
+          }
+        });
+        continue;
+      }
+      visitPlainLeaf(value, `${prefix}content.${key}`, report);
+    }
+  }
+  if (typeof options === "object" && options !== null) {
+    visitPlainLeaf(options, `${prefix}options`, report);
+  }
+}
+
+/**
+ * The write path's sentence for a section check's error, shared with
+ * validate_site so a dry run words a failure exactly as the save it predicts.
+ */
+export function sectionCheckMessage(sectionId: string, type: string, code: SectionCheckError["code"]): string {
+  switch (code) {
+    case "schema":
+      return `Validation failed: section "${sectionId}" (${type})`;
+    case "layout":
+      return `Validation failed: section "${sectionId}" has an invalid layout envelope`;
+    case "depth":
+      return `Validation failed: section "${sectionId}" exceeds max nesting depth (${MAX_BLOCK_DEPTH})`;
+    case "reference-in-container":
+      return `Validation failed: section "${sectionId}" holds a Reference, which can only sit at the top level of a page, not inside a container`;
+  }
+}
+
+/** The write path's warning for one entity finding, shared with validate_site. */
+export function entityWarning(sectionId: string, { path, entities }: EntityFinding): string {
+  const noun = entities.length > 1 ? "entities" : "entity";
+  return `section "${sectionId}": "${path}" contains HTML ${noun} ${entities.join(", ")} — this is a plain-text field, so entities render literally; if a character was intended, use the character itself.`;
+}

package/src/lib/site-validation.ts

@@ -0,0 +1,269 @@
+import type { ZodType } from "zod";
+import { IndexSchema, SiteConfigSchema, type SiteIndex } from "../schemas/site-config";
+import { ImageManifestSchema } from "../schemas/media";
+import { DOCUMENT_MANIFEST_PATH, DocumentManifestSchema } from "../schemas/documents";
+import { NAV, TAGS, readSidecarText, type SidecarDefinition, type SidecarDiagnostic } from "./sidecars";
+import { checkSection } from "./section-check";
+import { upgradeLegacySection } from "./migrate-sections-transform";
+import { collectImageIds } from "./image-refs";
+import { collectDocumentIds } from "./document-refs";
+import { referenceProblems, type ReferenceProblem } from "./reference-validation";
+
+const INDEX_PATH = "src/content/index.json";
+const SITE_CONFIG_PATH = "src/content/site-config.json";
+const IMAGE_MANIFEST_PATH = "src/content/image-manifest.json";
+const sectionPath = (id: string): string => `src/content/sections/${id}.json`;
+
+/** What the caller can vouch for. Never how severe anything is — that is SEVERITY. */
+export interface SiteValidationPolicy {
+  /**
+   * A section type with no registered schema: `trust` reads it as a real type
+   * this caller cannot check (the connector, whose branch index is the proof; a
+   * CLI whose site sections module failed to load), `reject` as an unknown type.
+   */
+  unregisteredTypes: "trust" | "reject";
+}
+
+export interface SchemaIssue {
+  path: readonly PropertyKey[];
+  message: string;
+}
+
+type ProblemBody =
+  | { code: "index-missing" }
+  | { code: "index-invalid"; detail: string }
+  | { code: "site-id-empty" }
+  | { code: "site-config-missing" }
+  | { code: "site-config-invalid"; detail: string }
+  | { code: "sidecar-degraded"; sidecar: "nav" | "tags" }
+  | { code: "sidecar-repaired"; sidecar: "nav" | "tags"; diagnostic: SidecarDiagnostic }
+  | { code: "image-manifest-invalid"; detail: string }
+  | { code: "document-manifest-invalid"; detail: string }
+  | { code: "section-missing"; sectionId: string }
+  | { code: "section-unparseable"; sectionId: string; detail: string }
+  | { code: "section-id-mismatch"; sectionId: string; fileId: unknown }
+  | { code: "section-type-mismatch"; sectionId: string; fileType: unknown; indexType: string }
+  | { code: "unknown-type"; sectionId: string; type: string }
+  | { code: "unvalidated-type"; sectionId: string; type: string }
+  | { code: "section-invalid"; sectionId: string; type: string; issues: SchemaIssue[] }
+  | { code: "layout-invalid"; sectionId: string; issues: SchemaIssue[] }
+  | { code: "too-deep"; sectionId: string }
+  | { code: "reference-in-container"; sectionId: string }
+  | { code: "html-entities"; sectionId: string; path: string; entities: string[] }
+  | { code: "dangling-image"; sectionId: string; imageId: string }
+  | { code: "dangling-document"; sectionId: string; documentId: string }
+  | { code: "reference-problem"; problem: ReferenceProblem };
+
+export type SiteProblemCode = ProblemBody["code"];
+export type Severity = "error" | "warning";
+export type SiteProblem = ProblemBody & { severity: Severity };
+
+/**
+ * The one severity table every caller shares. An ERROR is something the site
+ * cannot load, or authored content it silently loses or rejects. A WARNING is
+ * something the site renders through — dropping or repairing it itself — and
+ * that is fixable in-product, so it must not fail a build.
+ */
+export const SEVERITY: Readonly<Record<SiteProblemCode, Severity>> = {
+  "index-missing": "error",
+  "index-invalid": "error",
+  "site-id-empty": "error",
+  "site-config-missing": "error",
+  "site-config-invalid": "error",
+  // The loader drops what it cannot read, so authored grouping or tags vanish.
+  "sidecar-degraded": "error",
+  // What reconcile repairs on every load: the runtime has already fixed it.
+  "sidecar-repaired": "warning",
+  "image-manifest-invalid": "error",
+  "document-manifest-invalid": "error",
+  "section-missing": "error",
+  "section-unparseable": "error",
+  "section-id-mismatch": "error",
+  "section-type-mismatch": "error",
+  "unknown-type": "error",
+  "unvalidated-type": "warning",
+  "section-invalid": "error",
+  "layout-invalid": "error",
+  "too-deep": "error",
+  "reference-in-container": "error",
+  "html-entities": "warning",
+  "dangling-image": "warning",
+  "dangling-document": "warning",
+  "reference-problem": "warning",
+};
+
+export interface SiteValidation {
+  problems: SiteProblem[];
+  /** The section ids the index places on pages; null when the index could not be read. */
+  placedIds: string[] | null;
+}
+
+function parseJson(text: string): { ok: true; value: unknown } | { ok: false; detail: string } {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch (e) {
+    return { ok: false, detail: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+/** The text parsed and schema-checked, or why it could not be. */
+function parseFile<T>(text: string, schema: ZodType<T>): { ok: true; data: T } | { ok: false; detail: string } {
+  const json = parseJson(text);
+  if (!json.ok) return json;
+  const parsed = schema.safeParse(json.value);
+  return parsed.success ? { ok: true, data: parsed.data } : { ok: false, detail: parsed.error.message };
+}
+
+/**
+ * Validate a site's committed content. `files` maps repo paths under
+ * `src/content/` to their text; an absent path is an absent file. Pure: it reads
+ * the schema registry, so callers register built-in (and any site-local)
+ * schemas first. Only sections the index places on a page are judged — orphan
+ * files are the caller's concern.
+ */
+export function validateSite(files: Readonly<Record<string, string>>, policy: SiteValidationPolicy): SiteValidation {
+  const problems: SiteProblem[] = [];
+  const report = (body: ProblemBody) => problems.push({ ...body, severity: SEVERITY[body.code] });
+
+  const indexText = files[INDEX_PATH];
+  if (indexText === undefined) {
+    report({ code: "index-missing" });
+    return { problems, placedIds: null };
+  }
+  const indexRead = parseFile(indexText, IndexSchema);
+  if (!indexRead.ok) {
+    report({ code: "index-invalid", detail: indexRead.detail });
+    return { problems, placedIds: null };
+  }
+  const index: SiteIndex = indexRead.data;
+  const placedIds = [...new Set(index.pages.flatMap((p) => p.order))];
+
+  if (!index.siteId) report({ code: "site-id-empty" });
+
+  const configText = files[SITE_CONFIG_PATH];
+  if (configText === undefined) {
+    report({ code: "site-config-missing" });
+  } else {
+    const configRead = parseFile(configText, SiteConfigSchema);
+    if (!configRead.ok) report({ code: "site-config-invalid", detail: configRead.detail });
+  }
+
+  const checkSidecar = <E>(def: SidecarDefinition<E>): E[] | null => {
+    const text = files[def.path];
+    if (text === undefined) return [];
+    const read = readSidecarText(def, text);
+    if (read.degraded) {
+      report({ code: "sidecar-degraded", sidecar: def.name });
+      return null;
+    }
+    for (const diagnostic of def.reconcile(read.entries, index).diagnostics) {
+      report({ code: "sidecar-repaired", sidecar: def.name, diagnostic });
+    }
+    return read.entries;
+  };
+  checkSidecar(NAV);
+  // The tag ids a Reference may name: none when the file is absent, unknown
+  // (null, so tag ids go unchecked) when it cannot be read in full.
+  const tags = checkSidecar(TAGS);
+  const tagIds = tags === null ? null : new Set(tags.map((t) => t.id));
+
+  // The ids in each manifest; null when it is present but unreadable — nothing
+  // can be judged against a manifest we could not read, and reporting every
+  // reference as dangling would bury the one diagnostic that matters. Absent is
+  // the normal state of a site with nothing uploaded: an empty manifest.
+  let imageIds: Set<string> | null = new Set();
+  const imageText = files[IMAGE_MANIFEST_PATH];
+  if (imageText !== undefined) {
+    const read = parseFile(imageText, ImageManifestSchema);
+    if (read.ok) imageIds = new Set(Object.keys(read.data.images));
+    else {
+      report({ code: "image-manifest-invalid", detail: read.detail });
+      imageIds = null;
+    }
+  }
+  let documentIds: Set<string> | null = new Set();
+  const documentText = files[DOCUMENT_MANIFEST_PATH];
+  if (documentText !== undefined) {
+    const read = parseFile(documentText, DocumentManifestSchema);
+    if (read.ok) documentIds = new Set(Object.keys(read.data));
+    else {
+      report({ code: "document-manifest-invalid", detail: read.detail });
+      documentIds = null;
+    }
+  }
+
+  const bodies: { id: string; content: unknown }[] = [];
+  for (const id of placedIds) {
+    const text = files[sectionPath(id)];
+    if (text === undefined) {
+      report({ code: "section-missing", sectionId: id });
+      continue;
+    }
+    const json = parseJson(text);
+    if (!json.ok) {
+      report({ code: "section-unparseable", sectionId: id, detail: json.detail });
+      continue;
+    }
+    const onDisk = (typeof json.value === "object" && json.value !== null ? json.value : {}) as Record<string, unknown>;
+    if (onDisk.id !== id) report({ code: "section-id-mismatch", sectionId: id, fileId: onDisk.id });
+    // Retired types are rewritten at every load before the site validates them,
+    // so validate what the site runs, by the type it runs as.
+    const body = upgradeLegacySection(json.value);
+    bodies.push({ id, content: body });
+    const upgradedType = typeof body === "object" && body !== null ? (body as { type?: unknown }).type : undefined;
+    const type = typeof upgradedType === "string" ? upgradedType : "";
+
+    // The index may name either form of a legacy section: the retired type
+    // both still hold, or the type it upgrades to once a writer has reconciled
+    // the index. Either renders; only an index type matching neither is wrong.
+    const indexType = index.sections[id].type;
+    if (indexType !== onDisk.type && indexType !== upgradedType) {
+      report({ code: "section-type-mismatch", sectionId: id, fileType: onDisk.type, indexType });
+    }
+    // A body with no type has just been reported as a mismatch; there is no
+    // type to judge it by, and "unknown type \"\"" would say nothing more.
+    if (type === "") continue;
+
+    const check = checkSection(type, body);
+    if (check.unregistered) {
+      if (policy.unregisteredTypes === "reject") {
+        report({ code: "unknown-type", sectionId: id, type });
+      } else {
+        report({ code: "unvalidated-type", sectionId: id, type });
+        if (check.error?.code === "depth") report({ code: "too-deep", sectionId: id });
+      }
+    } else if (check.error) {
+      const error = check.error;
+      switch (error.code) {
+        case "schema":
+          report({ code: "section-invalid", sectionId: id, type, issues: error.zodError.issues });
+          break;
+        case "layout":
+          report({ code: "layout-invalid", sectionId: id, issues: error.zodError.issues });
+          break;
+        case "depth":
+          report({ code: "too-deep", sectionId: id });
+          break;
+        case "reference-in-container":
+          report({ code: "reference-in-container", sectionId: id });
+          break;
+      }
+    }
+    for (const { path, entities } of check.entities) report({ code: "html-entities", sectionId: id, path, entities });
+
+    if (imageIds) {
+      for (const imageId of collectImageIds(body)) {
+        if (!imageIds.has(imageId)) report({ code: "dangling-image", sectionId: id, imageId });
+      }
+    }
+    if (documentIds) {
+      for (const documentId of collectDocumentIds(body)) {
+        if (!documentIds.has(documentId)) report({ code: "dangling-document", sectionId: id, documentId });
+      }
+    }
+  }
+
+  for (const problem of referenceProblems(bodies, index, tagIds)) report({ code: "reference-problem", problem });
+
+  return { problems, placedIds };
+}

package/dist/{chunk-NX7TFHA4.js → chunk-CEFFP3CH.js}

@@ -1,10 +1,3 @@
-import {
-  Kbd,
-  Tooltip
-} from "./chunk-JCDZAFX2.js";
-import {
-  Button
-} from "./chunk-GGYY3JQJ.js";
 import {
   Checkbox,
   Tabs
@@ -18,6 +11,13 @@ import {
   useMediaLibrary,
   useResolvedMedia
 } from "./chunk-RIITGTV3.js";
+import {
+  Kbd,
+  Tooltip
+} from "./chunk-JCDZAFX2.js";
+import {
+  Button
+} from "./chunk-GGYY3JQJ.js";
 import {
   IconButton
 } from "./chunk-IIDKW7AV.js";

package/dist/{chunk-YV3YSZEB.js → chunk-L7WTERU5.js}

@@ -1,12 +1,12 @@
-import {
-  computeReorderTarget
-} from "./chunk-DIMDRBFK.js";
 import {
   DragHandle,
   DropEdgeIndicator,
   useMediaLibrary,
   useResolvedMedia
 } from "./chunk-RIITGTV3.js";
+import {
+  computeReorderTarget
+} from "./chunk-DIMDRBFK.js";
 import {
   IconButton
 } from "./chunk-IIDKW7AV.js";

package/dist/{chunk-WYOFQHKI.js → chunk-W72BPGR3.js}

@@ -1,9 +1,9 @@
-import {
-  getContainerChildren
-} from "./chunk-L45X7DKX.js";
 import {
   audiencePasses
 } from "./chunk-VY3IFGE3.js";
+import {
+  getContainerChildren
+} from "./chunk-L45X7DKX.js";
 import {
   pagesInNavOrder
 } from "./chunk-DJOGPSRU.js";