@clossys/writer 0.4.0 → 0.5.0

package/src/schema.ts

@@ -34,6 +34,8 @@ import type {
   CopyRecord,
   CopySource,
 } from "./types.js";
+import { COPY_FINGERPRINT_ALGORITHM } from "./fingerprint.js";
+import { isDelegateScopeItem, isEntryInDelegateScope } from "./approval.js";
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -383,6 +385,207 @@ function validateTranslationShape(value: unknown, path: string): CopyFinding[] {
   return findings;
 }
 
+/**
+ * `YYYY-MM-DDTHH:MM:SS(.sss)?Z` — the one ISO 8601 UTC shape this package
+ * accepts for `approvedAt`/`expiresAt`. Also requires `Date.parse` to
+ * actually accept it, so a string that merely matches the pattern but names
+ * an impossible date (e.g. a bad month) is still rejected.
+ */
+const ISO_UTC_TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/;
+
+export function isIsoUtcTimestamp(value: unknown): value is string {
+  if (typeof value !== "string" || !ISO_UTC_TIMESTAMP_RE.test(value)) return false;
+  const year = Number(value.slice(0, 4));
+  const month = Number(value.slice(5, 7));
+  const day = Number(value.slice(8, 10));
+  const parsed = Date.parse(value);
+  if (Number.isNaN(parsed)) return false;
+  const utc = new Date(parsed);
+  return utc.getUTCFullYear() === year && utc.getUTCMonth() + 1 === month && utc.getUTCDate() === day;
+}
+
+/** `textFingerprint` shape: a `sha256` hex digest — 64 lowercase hex characters. */
+const COPY_FINGERPRINT_RE = /^[0-9a-f]{64}$/;
+
+/**
+ * Validates a `CopyRegistryEntry.approval` field, when present. `undefined`
+ * is always valid, on any entry — an entry with no approval record keeps
+ * resolving exactly as it did before this field existed. Staleness (does
+ * `textFingerprint` still match the entry's current `text`) and expiry
+ * against "now" are runtime concerns for the resolver (`resolve.ts`) and
+ * `assessCopyApprovals` (`approval.ts`), never shape findings here: a
+ * registry with a stale or expired record is still a well-formed
+ * `CopyRegistry`.
+ */
+function validateApprovalShape(value: unknown, entryStatus: unknown, entryId: unknown, path: string): CopyFinding[] {
+  if (value === undefined) return [];
+  if (!isPlainObject(value)) {
+    return [
+      {
+        rule: "approval-shape",
+        severity: "error",
+        message: `${path} must be an object when present, got ${JSON.stringify(value)}.`,
+        path,
+      },
+    ];
+  }
+
+  const approvedBy = value.approvedBy;
+  const approvedAt = value.approvedAt;
+  const textFingerprint = value.textFingerprint;
+  const fingerprintAlgorithm = value.fingerprintAlgorithm;
+  const delegate = value.delegate;
+  const pendingOwnerReview = value.pendingOwnerReview;
+  const expiresAt = value.expiresAt;
+
+  const findings: CopyFinding[] = [];
+
+  if (entryStatus !== "approved") {
+    findings.push({
+      rule: "approval-status-mismatch",
+      severity: "error",
+      message: `${path} is present but the entry's status is ${JSON.stringify(entryStatus)}, not "approved".`,
+      path,
+    });
+  }
+
+  const isDelegateRecord = approvedBy === "delegate";
+
+  if (approvedBy !== "owner" && approvedBy !== "delegate") {
+    findings.push({
+      rule: "approval-approved-by",
+      severity: "error",
+      message: `${path}.approvedBy must be "owner" or "delegate", got ${JSON.stringify(approvedBy)}.`,
+      path: `${path}.approvedBy`,
+    });
+  }
+
+  if (!isIsoUtcTimestamp(approvedAt)) {
+    findings.push({
+      rule: "approval-approved-at-shape",
+      severity: "error",
+      message: `${path}.approvedAt must be an ISO 8601 UTC timestamp, got ${JSON.stringify(approvedAt)}.`,
+      path: `${path}.approvedAt`,
+    });
+  }
+
+  if (typeof textFingerprint !== "string" || !COPY_FINGERPRINT_RE.test(textFingerprint)) {
+    findings.push({
+      rule: "approval-fingerprint-shape",
+      severity: "error",
+      message: `${path}.textFingerprint must be a 64-character lowercase hex string, got ${JSON.stringify(textFingerprint)}.`,
+      path: `${path}.textFingerprint`,
+    });
+  }
+
+  if (fingerprintAlgorithm !== COPY_FINGERPRINT_ALGORITHM) {
+    findings.push({
+      rule: "approval-fingerprint-shape",
+      severity: "error",
+      message: `${path}.fingerprintAlgorithm must be ${JSON.stringify(COPY_FINGERPRINT_ALGORITHM)}, got ${JSON.stringify(fingerprintAlgorithm)}.`,
+      path: `${path}.fingerprintAlgorithm`,
+    });
+  }
+
+  if (isDelegateRecord && delegate === undefined) {
+    findings.push({
+      rule: "approval-delegate-required",
+      severity: "error",
+      message: `${path}.delegate is required when approvedBy is "delegate".`,
+      path: `${path}.delegate`,
+    });
+  }
+
+  if (approvedBy === "owner") {
+    (["delegate", "pendingOwnerReview", "expiresAt"] as const).forEach((field) => {
+      if (value[field] !== undefined) {
+        findings.push({
+          rule: "approval-delegate-forbidden",
+          severity: "error",
+          message: `${path}.${field} is forbidden when approvedBy is "owner".`,
+          path: `${path}.${field}`,
+        });
+      }
+    });
+  }
+
+  // The remaining checks (scope shape, scope membership, pendingOwnerReview,
+  // expiresAt) only make sense on an actual delegate record — on an owner
+  // record any of these fields is already reported above as forbidden, and
+  // shape-checking a field that should not exist would only add noise.
+  if (!isDelegateRecord) return findings;
+
+  let scopeIsValid = false;
+  if (!isPlainObject(delegate)) {
+    if (delegate !== undefined) {
+      findings.push({
+        rule: "approval-delegate-scope-shape",
+        severity: "error",
+        message: `${path}.delegate must be an object, got ${JSON.stringify(delegate)}.`,
+        path: `${path}.delegate`,
+      });
+    }
+  } else {
+    const delegateId = delegate.id;
+    const scope = delegate.scope;
+    const idIsValid = isNonEmptyString(delegateId);
+    const scopeIsArrayOfItems = Array.isArray(scope) && scope.length > 0 && scope.every((item) => isDelegateScopeItem(item));
+    if (!idIsValid || !scopeIsArrayOfItems) {
+      findings.push({
+        rule: "approval-delegate-scope-shape",
+        severity: "error",
+        message: `${path}.delegate must have a non-empty string id and a non-empty array scope of well-formed namespace items, got ${JSON.stringify(delegate)}.`,
+        path: `${path}.delegate`,
+      });
+    } else {
+      scopeIsValid = true;
+    }
+
+    if (scopeIsValid && typeof entryId === "string" && !isEntryInDelegateScope(entryId, scope as string[])) {
+      findings.push({
+        rule: "approval-outside-delegate-scope",
+        severity: "error",
+        message: `${path}.delegate scope ${JSON.stringify(scope)} does not cover entry id ${JSON.stringify(entryId)}.`,
+        path: `${path}.delegate`,
+      });
+    }
+  }
+
+  if (typeof pendingOwnerReview !== "boolean") {
+    findings.push({
+      rule: "approval-pending-review-shape",
+      severity: "error",
+      message: `${path}.pendingOwnerReview must be a boolean when approvedBy is "delegate", got ${JSON.stringify(pendingOwnerReview)}.`,
+      path: `${path}.pendingOwnerReview`,
+    });
+  }
+
+  let expiresAtIsValid = false;
+  if (expiresAt !== undefined) {
+    if (!isIsoUtcTimestamp(expiresAt)) {
+      findings.push({
+        rule: "approval-expires-at-shape",
+        severity: "error",
+        message: `${path}.expiresAt must be an ISO 8601 UTC timestamp when present, got ${JSON.stringify(expiresAt)}.`,
+        path: `${path}.expiresAt`,
+      });
+    } else {
+      expiresAtIsValid = true;
+    }
+  }
+
+  if (expiresAtIsValid && isIsoUtcTimestamp(approvedAt) && Date.parse(expiresAt as string) <= Date.parse(approvedAt)) {
+    findings.push({
+      rule: "approval-expires-before-approved",
+      severity: "error",
+      message: `${path}.expiresAt ${JSON.stringify(expiresAt)} must be strictly after ${path}.approvedAt ${JSON.stringify(approvedAt)}.`,
+      path: `${path}.expiresAt`,
+    });
+  }
+
+  return findings;
+}
+
 /**
  * Validates the stronger registry shape used to resolve `CopyRef`s. A plain
  * `CopyRecord` deliberately remains valid for source scanning and voice
@@ -456,6 +659,7 @@ export function validateCopyRegistryShape(value: unknown): CopyFinding[] {
         });
       }
       findings.push(...validateTranslationShape(entry.translation, `entries.${i}.translation`));
+      findings.push(...validateApprovalShape(entry.approval, entry.status, entry.id, `entries.${i}.approval`));
     });
   }
 
@@ -496,11 +700,25 @@ function buildCopyRecord(value: Record<string, unknown>): CopyRecord {
 
 function buildCopyRegistry(value: Record<string, unknown>): CopyRegistry {
   const record = buildCopyRecord(value);
-  const entries = (value.entries as Array<Record<string, unknown>>).map((entry) => ({
-    ...record.entries.find((item) => item.id === entry.id)!,
-    status: entry.status as CopyEntryStatus,
-    translation: entry.translation as CopyRegistryEntry["translation"],
-  })) as CopyRegistryEntry[];
+  const entries = (value.entries as Array<Record<string, unknown>>).map((entry) => {
+    const built: CopyRegistryEntry = {
+      ...record.entries.find((item) => item.id === entry.id)!,
+      status: entry.status as CopyEntryStatus,
+      translation: entry.translation as CopyRegistryEntry["translation"],
+    };
+    // Only copy `approval` when the input entry actually has one — an
+    // `approval: undefined` key would still make `"approval" in entry` true,
+    // breaking the "no record at all" case `resolve.ts` and `approval.ts`
+    // both depend on. Copied defensively (a fresh `delegate.scope` array) so
+    // the parsed registry never aliases the caller's own input object.
+    if (entry.approval !== undefined) {
+      const approval = entry.approval as CopyRegistryEntry["approval"];
+      built.approval = approval?.delegate
+        ? { ...approval, delegate: { ...approval.delegate, scope: [...approval.delegate.scope] } }
+        : { ...approval! };
+    }
+    return built;
+  });
 
   return {
     ...record,

package/src/site-identity.ts

@@ -0,0 +1,125 @@
+/**
+ * The site-identity copy kind: a site's name and tagline, resolved from a
+ * `CopyRegistry` under two reserved entry ids.
+ *
+ * A page-metadata consumer needs exactly two short strings — what the site
+ * is called and one line about it — and needs them to carry the same
+ * approval evidence as any other rendered copy. This module does not add a
+ * second approval path for them. It asks `resolveCopyRef` for
+ * `"site.name"` and `"site.tagline"`, so whatever that resolver refuses
+ * (a draft entry, an approval record that no longer matches its text, an
+ * expired delegate approval, a delegate approval on `"production"` without
+ * the caller's opt-in, a locale mismatch, an unknown id, an invalid
+ * registry or options object) is refused here for the same reason.
+ *
+ * On top of that resolver this module adds two refusals of its own,
+ * because a name and a tagline are literal text rather than templates: an
+ * entry that declares placeholders (or whose text the resolver would
+ * rewrite), and a resolved text that is blank after trimming.
+ *
+ * The result is all-or-nothing. Both fields are always attempted so a
+ * caller sees every problem at once, but `identity` and `resolutions` are
+ * present only when both fields resolved — there is no partial identity.
+ * Nothing here throws for any input; malformed input yields a result with
+ * `complete: false` and an issue. Nothing here reads a brand-facts record
+ * or consumes the result; wiring it into a page-metadata builder is a
+ * separate change.
+ *
+ * No real copy ships here. The ids are reserved names; the words are the
+ * consumer's own.
+ */
+
+import { prepareOptions, resolveField } from "./field-options.js";
+import type { FieldLabels } from "./field-options.js";
+import type { CopyResolveIssue, CopyResolveIssueReason, CopyResolveOptions } from "./resolve.js";
+import type { CopyRegistry, CopyResolution } from "./types.js";
+
+/** Reserved copy id for the site's name. */
+export const SITE_NAME_COPY_ID = "site.name";
+
+/** Reserved copy id for the site's tagline. */
+export const SITE_TAGLINE_COPY_ID = "site.tagline";
+
+/** Both reserved site-identity copy ids, name first. */
+export const SITE_IDENTITY_COPY_IDS = [SITE_NAME_COPY_ID, SITE_TAGLINE_COPY_ID] as const;
+
+/** Which half of the site identity an issue is about. */
+export type SiteIdentityField = "name" | "tagline";
+
+/**
+ * Every reason `resolveSiteIdentity` can report: whatever `resolveCopyRef`
+ * refuses, plus the two refusals specific to site identity.
+ * `"site-identity-blank"` means the resolved text was empty after trimming;
+ * `"site-identity-placeholder"` means the entry declares placeholders or
+ * its text is one the resolver would rewrite.
+ */
+export type SiteIdentityIssueReason = CopyResolveIssueReason | "site-identity-blank" | "site-identity-placeholder";
+
+/** One reason a site identity could not be resolved, tagged with its field. */
+export interface SiteIdentityIssue extends Omit<CopyResolveIssue, "reason"> {
+  reason: SiteIdentityIssueReason;
+  field: SiteIdentityField;
+}
+
+/**
+ * The outcome of `resolveSiteIdentity`. `identity` and `resolutions` are
+ * present only when `complete` is `true`; `issues` is empty exactly then.
+ */
+export interface SiteIdentityResolution {
+  complete: boolean;
+  identity?: { name: string; tagline: string };
+  resolutions?: { name: CopyResolution; tagline: CopyResolution };
+  issues: SiteIdentityIssue[];
+}
+
+/** `CopyResolveOptions` plus the requested locale, which is a ref field for the underlying resolver. */
+export type SiteIdentityOptions = CopyResolveOptions & { locale?: string };
+
+const FIELDS: readonly { field: SiteIdentityField; id: string }[] = [
+  { field: "name", id: SITE_NAME_COPY_ID },
+  { field: "tagline", id: SITE_TAGLINE_COPY_ID },
+];
+
+const LABELS: FieldLabels<"site-identity-placeholder" | "site-identity-blank"> = {
+  optionsSubject: "Site identity",
+  entrySubject: (id) => `Site identity "${id}"`,
+  placeholderReason: "site-identity-placeholder",
+  blankReason: "site-identity-blank",
+};
+
+/**
+ * Resolves the site's name and tagline from `registry`, under
+ * `"site.name"` and `"site.tagline"`. Both are attempted on every call and
+ * every issue is reported, tagged with its `field`; `identity` and
+ * `resolutions` are returned only when both resolved.
+ *
+ * `options` are `resolveCopyRef`'s (`target`, `acceptDelegateInProduction`,
+ * `now`) plus an optional `locale`, which is forwarded as the ref's locale
+ * rather than as an option. Malformed options (including a blank or
+ * non-string `locale`) produce an `"invalid-options"` issue per field. Pure
+ * apart from the clock read that `now` defaults to; the registry is not
+ * modified and no input makes this throw.
+ */
+export function resolveSiteIdentity(
+  registry: CopyRegistry | unknown,
+  options?: SiteIdentityOptions | unknown,
+): SiteIdentityResolution {
+  const prepared = prepareOptions(options);
+  const issues: SiteIdentityIssue[] = [];
+  const resolved: Partial<Record<SiteIdentityField, CopyResolution>> = {};
+  for (const { field, id } of FIELDS) {
+    const outcome = resolveField(registry, field, id, prepared, LABELS);
+    issues.push(...outcome.issues);
+    if (outcome.resolution) resolved[field] = outcome.resolution;
+  }
+
+  const name = resolved.name;
+  const tagline = resolved.tagline;
+  if (issues.length > 0 || !name || !tagline) return { complete: false, issues };
+  return {
+    complete: true,
+    identity: { name: name.text, tagline: tagline.text },
+    resolutions: { name, tagline },
+    issues: [],
+  };
+}

package/src/types.ts

@@ -28,13 +28,15 @@
  * This file ships no example content of anyone's real copy. Every field
  * here is either required-and-generic or a structural placeholder —
  * filling in an actual product's actual sentences is a consumer's job.
- * See "The single most important constraint" in the README: this package
- * is to `@clossys/writer/voice` what `@example/ui` is to
- * `@example/ui/tokens` — a vocabulary layer over a contract layer,
- * never a source of real words. If a doc comment, a test fixture, or a
- * README example in this package ever reads like something a product
- * would actually show a user, that is a bug in this package, not a
- * feature of it.
+ * The one exemption is the shipped US English front-door defaults
+ * (`front-door.ts`, `FRONT_DOOR_COPY_EN`, and the README's "Front-door
+ * copy" section): a closed, reserved set of ids, owned by this package, whose
+ * words ship as data so every sign-in surface need not carry its own. Outside
+ * that set this package is to `@clossys/writer/voice` what `@example/ui` is
+ * to `@example/ui/tokens` — a vocabulary layer over a contract layer, never a
+ * source of real words. If a doc comment, a test fixture, or a README example
+ * outside the front-door set ever reads like something a product would
+ * actually show a user, that is a bug in this package, not a feature of it.
  */
 
 // ---------------------------------------------------------------------------
@@ -222,6 +224,47 @@ export interface CopyTranslationProvenance {
   reviewedBy?: string;
 }
 
+// ---------------------------------------------------------------------------
+// CopyApproval — who approved an entry, and exactly which text they approved
+// ---------------------------------------------------------------------------
+
+/** Who recorded an approval: the copy owner, or a delegate acting for them. */
+export type CopyApprover = "owner" | "delegate";
+
+/**
+ * The delegate an approval was recorded by, and the entry-id namespaces they
+ * may approve. `id` is an opaque identifier, never a personal name. Each
+ * `scope` item is a dot-separated namespace with no wildcard; an entry is in
+ * scope when its id equals an item or starts with `item + "."`.
+ */
+export interface CopyDelegateScope {
+  id: string;
+  scope: string[];
+}
+
+/**
+ * The recorded approval of one registry entry, written by
+ * `writer-check approve` rather than by hand. `textFingerprint` pins the
+ * approval to the exact text that was approved: once `text` changes, the
+ * record no longer matches and the resolver refuses the entry
+ * (`approval-stale`) until it is approved again.
+ */
+export interface CopyApproval {
+  approvedBy: CopyApprover;
+  /** ISO 8601 UTC timestamp of the approval. */
+  approvedAt: string;
+  /** `computeCopyFingerprint(entry.text)` at the moment of approval. */
+  textFingerprint: string;
+  /** The algorithm `textFingerprint` was computed with — `COPY_FINGERPRINT_ALGORITHM`. */
+  fingerprintAlgorithm: string;
+  /** Required when `approvedBy` is `"delegate"`; forbidden for `"owner"`. */
+  delegate?: CopyDelegateScope;
+  /** Required when `approvedBy` is `"delegate"`; forbidden for `"owner"`. */
+  pendingOwnerReview?: boolean;
+  /** Delegate records only: ISO 8601 UTC expiry, strictly after `approvedAt`. */
+  expiresAt?: string;
+}
+
 /** A `CopyEntry` that is eligible to participate in a rendered registry. */
 export interface CopyRegistryEntry extends CopyEntry {
   status: CopyEntryStatus;
@@ -238,6 +281,12 @@ export interface CopyRegistryEntry extends CopyEntry {
    * never collapsed into one signal.
    */
   translation?: CopyTranslationProvenance;
+  /**
+   * The approval record, present only on an `approved` entry that has one.
+   * Optional: an `approved` entry without a record keeps resolving exactly
+   * as it did before this field existed. See `CopyApproval`.
+   */
+  approval?: CopyApproval;
 }
 
 // ---------------------------------------------------------------------------
@@ -268,6 +317,20 @@ export interface CopyRegistry extends CopyRecord {
   entries: CopyRegistryEntry[];
 }
 
+/** The approval facts a resolution carries (`CopyResolution.approval`). */
+export type CopyResolutionApproval =
+  | { approvedBy: "owner"; pendingOwnerReview: false }
+  | {
+      approvedBy: "delegate";
+      pendingOwnerReview: boolean;
+      /**
+       * Present only when this delegate-approved entry resolved on "production"
+       * because the `approvalPlan` authorized it: that plan's canonical digest.
+       * Absent when `acceptDelegateInProduction` authorized it, and on "preview".
+       */
+      authorizingPlanDigest?: string;
+    };
+
 /** A successful, fully traced resolution of one copy reference. */
 export interface CopyResolution {
   ref: CopyRef;
@@ -277,6 +340,8 @@ export interface CopyResolution {
   locale: CopyLocale;
   source: CopySource;
   entryId: CopyEntryId;
+  /** Present only when the resolved entry carries an approval record. */
+  approval?: CopyResolutionApproval;
 }
 
 /** Resolver shape for callers that need rendered audience text. */