@drawnagency/primitives 0.1.114 → 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/sidecar-diagnostics.ts

@@ -0,0 +1,29 @@
+/**
+ * What a Sidecar reconcile changed. Reconcile repairs silently on every read, so
+ * these are only ever warnings: a validator reports them, nothing rejects on them.
+ *  - dangling: ids of pages/sections the index does not have, dropped
+ *  - duplicate-id: a group/tag id used again, later uses dropped
+ *  - duplicate-member: a page placed twice / a section tagged twice, later placements dropped
+ *  - unlisted: pages missing from the nav, appended to its end (nav only)
+ *
+ * Its own leaf so nav-tree and tags can report without importing the Sidecar
+ * module that imports them.
+ */
+export type SidecarDiagnostic = {
+  code: "dangling" | "duplicate-id" | "duplicate-member" | "unlisted";
+  ids: string[];
+};
+
+export function diagnosticsCollector() {
+  const byCode = new Map<SidecarDiagnostic["code"], Set<string>>();
+  return {
+    add(code: SidecarDiagnostic["code"], id: string) {
+      const ids = byCode.get(code) ?? new Set<string>();
+      ids.add(id);
+      byCode.set(code, ids);
+    },
+    list(): SidecarDiagnostic[] {
+      return [...byCode].map(([code, ids]) => ({ code, ids: [...ids] }));
+    },
+  };
+}

package/src/lib/sidecars.ts

@@ -0,0 +1,221 @@
+import type { ZodType } from "zod";
+import { NavEntrySchema, NavFileSchema, type NavEntry } from "../schemas/nav";
+import { TagEntrySchema, TagsFileSchema, type TagEntry } from "../schemas/tags";
+import type { SiteIndex } from "../schemas/site-config";
+import { reconcileNavReport } from "./nav-tree";
+import { mergeTags, reconcileTagsReport } from "./tags";
+import type { SidecarDiagnostic } from "./sidecar-diagnostics";
+
+export type { SidecarDiagnostic };
+
+/**
+ * One definition per Sidecar — a content file kept beside index.json rather than
+ * on it, so a writer that predates it cannot drop it (CONTEXT.md). Every rule a
+ * caller would otherwise re-implement per file lives behind these: lenient
+ * parse, lifting the wire key off an index before IndexSchema strips it, and the
+ * two places the Sidecars genuinely differ — how a list is repaired against the
+ * index, and how concurrent edits rebase. Pure and browser-safe: the editor uses
+ * it during hydration, and callers do their own I/O.
+ */
+export interface SidecarDefinition<E> {
+  /** Also the key the Sidecar travels under on the wire (`index.nav`, `index.tags`). */
+  name: "nav" | "tags";
+  path: string;
+  /** The key holding the entry list inside the file. */
+  fileKey: "entries" | "tags";
+  entrySchema: ZodType<E>;
+  fileSchema: ZodType<unknown>;
+  /** Total, pure and idempotent; also reports what it repaired. */
+  reconcile(entries: E[], index: SiteIndex): { entries: E[]; diagnostics: SidecarDiagnostic[] };
+  /** The list after a collab rebase; `undefined` when no side carries one. */
+  rebase(args: { base: E[] | undefined; local: E[] | undefined; remote: E[] | undefined }): E[] | undefined;
+  /** Words for a declined write's warning. */
+  words: {
+    /** What the file holds: "navigation entries". */
+    entries: string;
+    /** What did not land: "Page grouping changes". */
+    changes: string;
+    /** What a valid payload is: "a valid navigation tree". */
+    valid: string;
+    /** The expected wire shape, for an agent that sent the wrong one. */
+    shape: string;
+  };
+}
+
+export const NAV: SidecarDefinition<NavEntry> = {
+  name: "nav",
+  path: "src/content/nav.json",
+  fileKey: "entries",
+  entrySchema: NavEntrySchema,
+  fileSchema: NavFileSchema,
+  reconcile: (entries, index) => reconcileNavReport(entries, index.pages),
+  // Grouping is edited rarely and has no dirty tracking, so persisted remote
+  // state beats unsaved local edits. A remote without the Sidecar (an older
+  // server) keeps ours rather than flattening it.
+  rebase: ({ local, remote }) => (remote !== undefined ? remote : local),
+  words: {
+    entries: "navigation entries",
+    changes: "Page grouping changes",
+    valid: "a valid navigation tree",
+    shape: 'an array of {kind:"page",pageId} / {kind:"group",id,label,startCollapsed,pageIds} entries',
+  },
+};
+
+export const TAGS: SidecarDefinition<TagEntry> = {
+  name: "tags",
+  path: "src/content/tags.json",
+  fileKey: "tags",
+  entrySchema: TagEntrySchema,
+  fileSchema: TagsFileSchema,
+  reconcile: (entries, index) => reconcileTagsReport(entries, index.sections),
+  // Tagging is edited from every section's chrome, so remote-wins would drop
+  // unsaved tagging whenever a peer saved anything. See mergeTags.
+  rebase: mergeTags,
+  words: {
+    entries: "tag entries",
+    changes: "Tag changes",
+    valid: "a valid tag list",
+    shape: "an array of {id,label,sectionIds} entries",
+  },
+};
+
+// Widened once here: the definitions are invariant in their entry type, so a
+// loop over both needs the common type.
+export const SIDECARS: readonly SidecarDefinition<unknown>[] = [NAV, TAGS] as readonly SidecarDefinition<unknown>[];
+
+/**
+ * A Sidecar as read. `degraded` means the file was present but held something
+ * this package version could not represent, so `entries` is missing it: the read
+ * is a Degraded read, never to be cached, posted back, or written over the file.
+ */
+export type SidecarRead<E> = { entries: E[]; degraded: boolean };
+
+/**
+ * Tolerance is per entry: one unknown entry kind (a newer package's addition, an
+ * authoring typo) drops that entry alone, not every group or tag on the site.
+ */
+function readEntries<E>(def: SidecarDefinition<E>, raw: unknown): SidecarRead<E> {
+  if (!Array.isArray(raw)) {
+    console.warn(`[sidecars] ${def.name}: entry list is not a list; reading it as empty and degraded`);
+    return { entries: [], degraded: true };
+  }
+  const entries: E[] = [];
+  let dropped = 0;
+  for (const item of raw) {
+    const parsed = def.entrySchema.safeParse(item);
+    if (parsed.success) entries.push(parsed.data);
+    else dropped++;
+  }
+  if (dropped > 0) {
+    console.warn(`[sidecars] ${def.name}: dropped ${dropped} entr${dropped === 1 ? "y" : "ies"} this package version cannot represent; the read is degraded`);
+  }
+  return { entries, degraded: dropped > 0 };
+}
+
+/** Read a parsed Sidecar file. Absent (null/undefined) is an empty list, not degraded. */
+export function readSidecar<E>(def: SidecarDefinition<E>, file: unknown): SidecarRead<E> {
+  if (file === undefined || file === null) return { entries: [], degraded: false };
+  return readEntries(def, (file as Record<string, unknown>)[def.fileKey]);
+}
+
+/**
+ * Read a Sidecar file's raw text. Present-but-unparseable JSON is degraded, not
+ * absent: a site whose nav.json is corrupt still has groups, and treating it as
+ * "never had any" would let a writer replace them.
+ */
+export function readSidecarText<E>(def: SidecarDefinition<E>, text: string | undefined): SidecarRead<E> {
+  if (text === undefined) return { entries: [], degraded: false };
+  let file: unknown;
+  try {
+    file = JSON.parse(text);
+  } catch {
+    console.warn(`[sidecars] ${def.name}: ${def.path} is not valid JSON; the read is degraded`);
+    return { entries: [], degraded: true };
+  }
+  return readSidecar(def, file);
+}
+
+/**
+ * Lift the Sidecars off an index as it arrives on the wire, BEFORE anything
+ * parses it with IndexSchema — the parse strips unknown keys, and an index
+ * round-tripped through it has lost its Sidecars. A key the index does not carry
+ * is `undefined` (omitted: writers leave the file alone); a carried key is read
+ * with the file's per-entry leniency, into fresh objects that never alias the
+ * caller's.
+ */
+export function liftSidecars(rawIndex: unknown): { nav?: SidecarRead<NavEntry>; tags?: SidecarRead<TagEntry> } {
+  const raw = rawIndex !== null && typeof rawIndex === "object" ? (rawIndex as Record<string, unknown>) : {};
+  return {
+    ...(raw.nav !== undefined ? { nav: readEntries(NAV, raw.nav) } : {}),
+    ...(raw.tags !== undefined ? { tags: readEntries(TAGS, raw.tags) } : {}),
+  };
+}
+
+/** The Sidecar file on the branch a write lands on, as the writer read it. */
+export type SidecarFileState =
+  | { kind: "absent" }
+  | { kind: "present"; text: string }
+  /** The read itself failed, so nothing is known about the file. */
+  | { kind: "unreadable" };
+
+export type SidecarWritePlan =
+  | { action: "untouched" }
+  | { action: "write"; path: string; content: string }
+  /** Declined. The rest of the write still lands, so the warning is what tells the caller. */
+  | { action: "skip"; warning: string };
+
+/**
+ * What a write does to one Sidecar file, given what was posted (from
+ * liftSidecars) and the file on the branch. Every Sidecar write REPLACES the
+ * file, and the posted list was built from what this package version could
+ * READ — so a file holding anything this version cannot fully parse (an entry
+ * from a newer package, or a corrupt file) is read-only: replacing it would
+ * destroy those entries with a clean write. The same holds for a posted
+ * Degraded read.
+ *
+ * Emptiness is judged on the POSTED list, before reconcile: an empty list never
+ * creates a file (every editor save carries the Sidecars, and nav's reconcile
+ * would turn [] into the page list), while an empty list over an existing file
+ * replaces it wholesale. A written list is reconciled against the index being
+ * written, so it never names a page or section that write removed.
+ */
+export function planSidecarWrite<E>(
+  def: SidecarDefinition<E>,
+  posted: SidecarRead<E> | undefined,
+  branch: SidecarFileState,
+  index: SiteIndex,
+): SidecarWritePlan {
+  if (posted === undefined) return { action: "untouched" };
+  const skip = (reason: string): SidecarWritePlan => ({
+    action: "skip",
+    warning: `${def.path} was left unchanged: ${reason} ${def.words.changes} from this save did not land. Upgrade the site's @drawnagency packages (or repair ${def.path} directly in the repo), then retry.`,
+  });
+
+  if (posted.degraded) {
+    // Leaving the file alone is the right action; saying nothing is not — an
+    // agent that posted a malformed list would otherwise believe it landed.
+    return {
+      action: "skip",
+      warning: `${def.name} was not ${def.words.valid}, so ${def.path} was left unchanged (it held entries this package version cannot read). Expected ${def.words.shape}.`,
+    };
+  }
+  if (branch.kind === "unreadable") {
+    return skip("the current file could not be read to confirm the replacement loses nothing.");
+  }
+  if (branch.kind === "present") {
+    let existing: unknown;
+    try {
+      existing = JSON.parse(branch.text);
+    } catch {
+      return skip("the current file is not valid JSON, so this version cannot prove a replacement keeps its entries.");
+    }
+    if (!def.fileSchema.safeParse(existing).success) {
+      return skip(`the current file holds ${def.words.entries} this package version cannot represent (likely written by a newer version).`);
+    }
+  } else if (posted.entries.length === 0) {
+    return { action: "untouched" };
+  }
+
+  const { entries } = def.reconcile(posted.entries, index);
+  return { action: "write", path: def.path, content: JSON.stringify({ [def.fileKey]: entries }, null, 2) };
+}