@clossys/writer 0.3.9 → 0.5.0

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/treatment-word-budget.ts

@@ -0,0 +1,100 @@
+/**
+ * Treatment-level word budgets for registry entries — display headings,
+ * eyebrows, button labels, and other short treatments that are not body
+ * measure. Pure gate: takes an already-validated `CopyRegistry`, never I/O.
+ */
+
+import type { CopyEntryId, CopyRegistry, CopyRegistryEntry } from "./types.js";
+
+/** Known slot treatments with a default maximum word count when the entry omits `maxWords`. */
+export const DEFAULT_TREATMENT_WORD_BUDGETS: Readonly<Record<string, number>> = {
+  "display-heading": 12,
+  eyebrow: 8,
+  button: 6,
+};
+
+export type TreatmentWordBudgetRule = "word-budget-exceeded" | "unknown-treatment";
+
+export interface TreatmentWordBudgetFinding {
+  rule: TreatmentWordBudgetRule;
+  severity: "error";
+  entryId: CopyEntryId;
+  treatment: string;
+  maxWords: number;
+  actualWords: number;
+  message: string;
+}
+
+export interface TreatmentWordBudgetResult {
+  entriesChecked: number;
+  findings: TreatmentWordBudgetFinding[];
+}
+
+/** Counts words in resolved copy text (whitespace-separated tokens). */
+export function countCopyWords(text: string): number {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) return 0;
+  return trimmed.split(/\s+/u).length;
+}
+
+function budgetForEntry(entry: CopyRegistryEntry): { treatment: string; maxWords: number } | undefined {
+  const treatment = entry.treatment;
+  if (typeof treatment !== "string" || treatment.trim().length === 0) return undefined;
+  const normalized = treatment.trim();
+  if (entry.maxWords !== undefined) {
+    if (typeof entry.maxWords !== "number" || !Number.isFinite(entry.maxWords) || entry.maxWords < 1) {
+      return undefined;
+    }
+    return { treatment: normalized, maxWords: Math.floor(entry.maxWords) };
+  }
+  const defaultMax = DEFAULT_TREATMENT_WORD_BUDGETS[normalized];
+  if (defaultMax === undefined) return undefined;
+  return { treatment: normalized, maxWords: defaultMax };
+}
+
+/**
+ * Fails when an approved entry declares a `treatment` (or `maxWords`) and
+ * its `text` exceeds the applicable budget. Draft and retired entries are
+ * skipped — only copy that can resolve at render is measured.
+ */
+export function checkTreatmentWordBudgets(registry: CopyRegistry): TreatmentWordBudgetResult {
+  const findings: TreatmentWordBudgetFinding[] = [];
+  let entriesChecked = 0;
+
+  for (const entry of registry.entries) {
+    if (entry.status !== "approved") continue;
+    const budget = budgetForEntry(entry);
+    if (!budget) {
+      if (typeof entry.treatment === "string" && entry.treatment.trim().length > 0) {
+        const normalized = entry.treatment.trim();
+        if (entry.maxWords === undefined && DEFAULT_TREATMENT_WORD_BUDGETS[normalized] === undefined) {
+          findings.push({
+            rule: "unknown-treatment",
+            severity: "error",
+            entryId: entry.id,
+            treatment: normalized,
+            maxWords: 0,
+            actualWords: countCopyWords(entry.text),
+            message: `Entry "${entry.id}" declares treatment "${normalized}" with no maxWords and no built-in default — add maxWords or use a known treatment (${Object.keys(DEFAULT_TREATMENT_WORD_BUDGETS).join(", ")}).`,
+          });
+        }
+      }
+      continue;
+    }
+    entriesChecked++;
+    const actualWords = countCopyWords(entry.text);
+    if (actualWords > budget.maxWords) {
+      findings.push({
+        rule: "word-budget-exceeded",
+        severity: "error",
+        entryId: entry.id,
+        treatment: budget.treatment,
+        maxWords: budget.maxWords,
+        actualWords,
+        message: `Entry "${entry.id}" (${budget.treatment}) has ${actualWords} word(s) but the budget is ${budget.maxWords}.`,
+      });
+    }
+  }
+
+  return { entriesChecked, findings };
+}

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.
  */
 
 // ---------------------------------------------------------------------------
@@ -166,6 +168,17 @@ export interface CopyEntry {
    * same seam, one layer over).
    */
   factRef?: string;
+  /**
+   * Named slot treatment for word-budget governance — e.g. `display-heading`,
+   * `eyebrow`, `button`. When set on an approved registry entry, `writer-check`
+   * applies `maxWords` or the built-in default for that treatment.
+   */
+  treatment?: string;
+  /**
+   * Maximum word count for this entry's `text` when `treatment` is set.
+   * Overrides the built-in default table when present.
+   */
+  maxWords?: number;
 }
 
 /**
@@ -211,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;
@@ -227,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;
 }
 
 // ---------------------------------------------------------------------------
@@ -257,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;
@@ -266,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. */