@company-semantics/contracts 34.0.0 → 35.1.0

package/src/notifications/__tests__/registry.test.ts

@@ -0,0 +1,184 @@
+/**
+ * `NOTIFICATION_DEFINITIONS` replaces `EMAIL_KINDS` as the place a caller starts
+ * from (ADR-CONTRACTS-085), so these tests hold it to the invariants that
+ * registry earned — and to the ones it did not.
+ *
+ * The inherited invariants: exhaustive over the union, keys agreeing with
+ * `definition.kind`, lookup returning the identical object.
+ *
+ * The new one is TOTALITY. `getEmailKindDefinition` could hand back a definition
+ * whose kind then threw at render; `getNotificationKindDefinition` cannot,
+ * because a kind with no `compose` cannot reach the union. That is the whole
+ * reason `NotificationKind` has eleven members where `EmailKind` had twelve, and
+ * it is only true as long as every definition here actually composes — which the
+ * last test checks by calling all of them rather than trusting the type.
+ *
+ * And the ABSENCES: `subject`, `plainTextRequired` and `htmlSupported` are gone.
+ * Asserting a field is missing looks pedantic until someone re-adds `subject`
+ * "just for the registry test" and re-fuses the two layers ADR-CONTRACTS-086
+ * split.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { createRenderContext } from "../context";
+import type { NotificationKind } from "../kinds";
+import {
+  getNotificationKindDefinition,
+  isValidNotificationKind,
+  NOTIFICATION_DEFINITIONS,
+} from "../registry";
+import { fixtureKey, NOTIFICATION_FIXTURES } from "./fixtures";
+
+const KINDS = Object.keys(NOTIFICATION_DEFINITIONS) as NotificationKind[];
+
+/** Pinned so no wall-clock year can reach an assertion. */
+const CONTEXT = createRenderContext({ brand: { copyrightYear: 2026 } });
+
+/**
+ * A representative payload per kind, taken from the parity fixtures rather than
+ * written afresh — these definitions exist to say what those exact payloads say,
+ * so a second set of inputs would be a second thing to keep true.
+ */
+function payloadFor(kind: NotificationKind): unknown {
+  const fixture = NOTIFICATION_FIXTURES.find((f) => f.kind === kind);
+  if (!fixture) throw new Error(`No parity fixture for kind: ${kind}`);
+  return fixture.payload;
+}
+
+describe("NOTIFICATION_DEFINITIONS", () => {
+  it("has an entry for every notification kind", () => {
+    expect([...KINDS].sort()).toEqual([
+      "auth.otp",
+      "chat.shared",
+      "companyMd.access_request_approved",
+      "companyMd.access_request_denied",
+      "companyMd.access_requested",
+      "org.invite",
+      "org.ownership_transfer",
+      "org.ownership_transfer_completed",
+      "org.unit_owner_granted",
+      "security.alert",
+      "share.granted",
+    ]);
+  });
+
+  it("keys its entries by their own kind", () => {
+    for (const [key, definition] of Object.entries(NOTIFICATION_DEFINITIONS)) {
+      expect(definition.kind).toBe(key);
+    }
+  });
+
+  it("carries no subject — a title is content, and belongs to compose", () => {
+    for (const definition of Object.values(NOTIFICATION_DEFINITIONS)) {
+      expect(definition).not.toHaveProperty("subject");
+    }
+  });
+
+  it("carries no rendering capability — that is the renderer's to answer", () => {
+    // `plainTextRequired` / `htmlSupported` put capability on the kind. A kind is
+    // not what can or cannot draw an image; `Renderer.supports` is.
+    for (const definition of Object.values(NOTIFICATION_DEFINITIONS)) {
+      expect(definition).not.toHaveProperty("plainTextRequired");
+      expect(definition).not.toHaveProperty("htmlSupported");
+    }
+  });
+
+  it("names no destination for any kind", () => {
+    // Capability is asked of a renderer, never declared on a definition —
+    // otherwise every new surface is a rewrite of all eleven definitions.
+    for (const definition of Object.values(NOTIFICATION_DEFINITIONS)) {
+      expect(Object.keys(definition).sort()).toEqual(["compose", "kind"]);
+    }
+  });
+
+  it("composes for every kind, so the registry is total in practice and not just in type", () => {
+    // The claim that makes `getNotificationKindDefinition` safe where
+    // `getEmailKindDefinition` was not. Calling all eleven is the only way to
+    // know it: a type says a `compose` exists, not that it returns content.
+    for (const kind of KINDS) {
+      const compose = NOTIFICATION_DEFINITIONS[kind].compose as (
+        p: unknown,
+        c: typeof CONTEXT,
+      ) => { metadata: { kind: string; title: string } };
+      const content = compose(payloadFor(kind), CONTEXT);
+
+      expect(content.metadata.kind).toBe(kind);
+      expect(content.metadata.title).not.toBe("");
+    }
+  });
+
+  it("titles every kind", () => {
+    // The title is what the email channel turns into a subject, and the
+    // interpolation `compose` does (the `{orgName}` fill, and
+    // unit_owner_granted's derived `roleWord`) is easy to break silently — a
+    // template literal that stops filling yields a plausible-looking title with
+    // a hole in it. Snapshotting every fixture's title makes that a reviewable
+    // diff, and isolates the claim at COMPOSE: `./render-snapshot.test.ts`
+    // covers the same titles once the renderer has had them.
+    //
+    // These titles were asserted against the frozen 32.0.0 golden's subjects
+    // until ADR-CONTRACTS-087 retired it — the values below are those subjects,
+    // recaptured here as an ordinary snapshot. The migration proof they served
+    // was discharged in 35.0.0.
+    const titles = Object.fromEntries(
+      NOTIFICATION_FIXTURES.map((fixture) => {
+        const compose = NOTIFICATION_DEFINITIONS[fixture.kind].compose as (
+          p: unknown,
+          c: typeof CONTEXT,
+        ) => { metadata: { title: string } };
+        return [
+          fixtureKey(fixture.kind, fixture.name),
+          compose(fixture.payload, CONTEXT).metadata.title,
+        ];
+      }),
+    );
+    expect(titles).toMatchSnapshot();
+  });
+});
+
+describe("getNotificationKindDefinition", () => {
+  it("returns the definition for a kind", () => {
+    expect(getNotificationKindDefinition("org.invite").kind).toBe("org.invite");
+  });
+
+  it("returns the identical registry object, not a copy", () => {
+    expect(getNotificationKindDefinition("auth.otp")).toBe(
+      NOTIFICATION_DEFINITIONS["auth.otp"],
+    );
+  });
+
+  it("cannot fail for any kind in the union", () => {
+    // The improvement on getEmailKindDefinition, which returned a definition for
+    // auth.magic_link that then threw when rendered.
+    for (const kind of KINDS) {
+      expect(getNotificationKindDefinition(kind)).toBeDefined();
+    }
+  });
+});
+
+describe("isValidNotificationKind", () => {
+  it("accepts every kind in the registry", () => {
+    for (const kind of KINDS) {
+      expect(isValidNotificationKind(kind)).toBe(true);
+    }
+  });
+
+  it("rejects unknown, empty and partial kinds", () => {
+    expect(isValidNotificationKind("org.nope")).toBe(false);
+    expect(isValidNotificationKind("")).toBe(false);
+    expect(isValidNotificationKind("org.")).toBe(false);
+    expect(isValidNotificationKind("invite")).toBe(false);
+  });
+
+  it("rejects auth.magic_link, which email registered but never implemented", () => {
+    expect(isValidNotificationKind("auth.magic_link")).toBe(false);
+  });
+
+  it("rejects inherited Object properties", () => {
+    // `kind in NOTIFICATION_DEFINITIONS` walks the prototype chain, so this is
+    // the one input shape the implementation could get wrong at an API boundary.
+    expect(isValidNotificationKind("toString")).toBe(false);
+    expect(isValidNotificationKind("constructor")).toBe(false);
+  });
+});

package/src/{email/render → notifications}/__tests__/render-snapshot.test.ts

@@ -1,39 +1,66 @@
 /**
- * Locks the rendered output (subject / text / html) of every email kind ×
+ * Locks the rendered output (subject / text / html) of every notification kind ×
  * representative variant. This is production-parity email markup — a snapshot
  * change means a real sent email changed. Review the diff, then `vitest -u`.
+ *
+ * MOVED (ADR-CONTRACTS-086) from the old `src/email/render/__tests__/`, and
+ * rewired from that layer's `renderEmail` onto this one's. The snapshot suite
+ * documents the email markup and moved with it; the markup now lives behind the
+ * channel seam at `../renderers/email`, reached through `../render`.
+ *
+ * The recorded VALUES did not change — the `.snap` moved verbatim, and the
+ * describe label ("email render") and case labels are deliberately unchanged so
+ * every snapshot key still resolves. That is the whole claim of the move: the
+ * keys still match, so the bytes are still the bytes.
+ *
+ * This file used to be the reviewable companion to `./output-parity.test.ts`,
+ * which was the load-bearing one: a snapshot can be regenerated with a
+ * keystroke, a committed golden cannot, so the golden was the proof and this was
+ * the documentation. ADR-CONTRACTS-087 retired that golden once its migration
+ * proof shipped in 35.0.0 — so this file is now BOTH. There is no longer a
+ * second oracle to catch a snapshot refreshed on autopilot; the diff you read
+ * before typing `vitest -u` is the control.
+ *
+ * The clock is pinned to `FIXTURE_CLOCK`'s year rather than left to run.
+ * These snapshots used to be captured under the wall clock — with the copyright
+ * year baked into every one of them — so they were due to fail on the next New
+ * Year's Day for calendar reasons alone. The year is a value in `RenderContext`
+ * now, so it is simply stated.
  */
 
 import { describe, expect, it } from "vitest";
 
-import type { EmailPayloads } from "../../types";
-import {
-  IMPLEMENTED_EMAIL_KINDS,
-  type ImplementedEmailKind,
-  type RenderEmailOptions,
-  type RenderedEmail,
-  renderEmail,
-} from "../index";
+import type { RenderContextOverrides } from "../context";
+import type { NotificationKind } from "../kinds";
+import type { NotificationPayloads } from "../payloads";
+import { renderEmail } from "../render";
+import { NOTIFICATION_DEFINITIONS } from "../registry";
+import type { RenderedEmail } from "../renderers/email";
+import { FIXTURE_CLOCK } from "./fixtures";
+
+/** Pinned so no wall-clock year can reach a snapshot. */
+const CONTEXT: RenderContextOverrides = {
+  brand: { copyrightYear: new Date(FIXTURE_CLOCK).getUTCFullYear() },
+};
 
 interface Fixture {
-  kind: ImplementedEmailKind;
+  kind: NotificationKind;
   name: string;
   render: () => RenderedEmail;
 }
 
 const fixtures: Fixture[] = [];
-function add<K extends ImplementedEmailKind>(
+function add<K extends NotificationKind>(
   kind: K,
   name: string,
-  payload: EmailPayloads[K],
-  options?: RenderEmailOptions,
+  payload: NotificationPayloads[K],
 ): void {
   // `payload as never`: the add() call sites are type-checked (payload:
-  // EmailPayloads[K]); this only bridges the generic conditional in renderEmail.
+  // NotificationPayloads[K]); this only bridges compose's per-kind payload.
   fixtures.push({
     kind,
     name,
-    render: () => renderEmail(kind, payload as never, options),
+    render: () => renderEmail(kind, payload as never, CONTEXT),
   });
 }
 
@@ -41,17 +68,15 @@ const APP = "https://app.companysemantics.ai";
 
 add("auth.otp", "Default", { otp: "123456", expiresInMinutes: 10 });
 add("auth.otp", "Short expiry", { otp: "902413", expiresInMinutes: 1 });
-add(
-  "auth.otp",
-  "With request metadata",
-  {
-    otp: "246810",
-    expiresInMinutes: 5,
-    requestIp: "203.0.113.4",
-    userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
-  },
-  { includeRequestMetadata: true },
-);
+// No `includeRequestMetadata` any more: `compose` gates request details on
+// whether the payload carries them, and this payload does. The unchanged
+// snapshot is what proves the gate still opens.
+add("auth.otp", "With request metadata", {
+  otp: "246810",
+  expiresInMinutes: 5,
+  requestIp: "203.0.113.4",
+  userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
+});
 
 add("org.invite", "Admin", {
   inviterName: "Alex Rivera",
@@ -204,11 +229,19 @@ add("companyMd.access_request_denied", "No reason", {
   docTitle: "Engineering Handbook",
 });
 
+// "email render", not "notification render": the snapshot keys are
+// `email render > {kind} · {name} 1`, and renaming the describe would orphan
+// every one of them — regenerating the whole .snap to prove nothing changed is
+// exactly the move ADR-CONTRACTS-086 exists to prevent.
 describe("email render", () => {
-  it("has a fixture for every implemented kind", () => {
+  it("has a fixture for every kind", () => {
+    // Sourced from the registry rather than the old `IMPLEMENTED_EMAIL_KINDS`:
+    // the registry is what a caller starts from now, and it is total.
     const covered = new Set(fixtures.map((f) => f.kind));
-    for (const kind of IMPLEMENTED_EMAIL_KINDS) {
-      expect(covered.has(kind), `missing fixture for ${kind}`).toBe(true);
+    for (const kind of Object.keys(NOTIFICATION_DEFINITIONS)) {
+      expect(covered.has(kind as NotificationKind), `missing ${kind}`).toBe(
+        true,
+      );
     }
   });
 

package/src/notifications/__tests__/renderer.test.ts

@@ -0,0 +1,181 @@
+/**
+ * `Renderer<Out>` is the channel seam (ADR-CONTRACTS-086). It is a type, so what
+ * is worth proving is that the seam actually holds the two properties it was
+ * shaped for — using real conforming renderers rather than assertions about the
+ * type itself.
+ *
+ * 1. Capability lives on the renderer. Two channels with DIFFERENT `supports`
+ *    consume the SAME content and each drop what they cannot depict — with no
+ *    channel tag anywhere in the content.
+ * 2. Each channel returns its natural type. `Out` is a string here and a record
+ *    there; neither is coerced into a shared shape.
+ *
+ * Plus the purity invariant: `render` reads the year from `RenderContext`, so
+ * these tests need no fake timer — which is the improvement being locked in.
+ *
+ * `../renderers/sms` and `../renderers/slack` now assert both properties too, with
+ * real modules, and they are the load-bearing proof — a claim about the seam is
+ * worth more when a shipped channel makes it. The doubles below STAY, and stay
+ * local, on purpose: this file tests the TYPE, and pointing it at the stubs would
+ * make the seam's proof hostage to their fidelity choices. The first Slack kind
+ * that rewrites `slackRenderer`'s wording must not be able to fail the test that
+ * says capability lives on the renderer. Two channels answering `supports`
+ * differently is all this file needs, and inventing them here is cheaper than
+ * coupling to modules whose copy is explicitly provisional.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type { NotificationContent, NotificationElementType } from "../content";
+import type { RenderContext } from "../context";
+import type { Renderer } from "../renderer";
+
+const CONTEXT: RenderContext = {
+  brand: { name: "Company Semantics", copyrightYear: 2026 },
+};
+
+const CONTENT: NotificationContent = {
+  metadata: { kind: "org.invite", title: "Join Acme" },
+  sections: [
+    {
+      elements: [
+        { type: "heroImage", src: "https://example.test/h.png", alt: "Acme" },
+        { type: "greeting", recipientName: "Ada" },
+        { type: "body", text: "Acme uses Company Semantics." },
+        { type: "callToAction", label: "JOIN", href: "https://example.test/j" },
+        { type: "signature" },
+      ],
+    },
+  ],
+};
+
+/** A text-only channel: no images. Returns a plain string. */
+const TEXT_RENDERER: Renderer<string> = {
+  id: "text",
+  supports: (elementType) => elementType !== "heroImage",
+  render: (content, context) =>
+    content.sections
+      .flatMap((section) => section.elements)
+      .filter((element) => TEXT_RENDERER.supports(element.type))
+      .map((element) => {
+        switch (element.type) {
+          case "greeting":
+            return `Hi ${element.recipientName ?? "there"},`;
+          case "body":
+            return element.text;
+          case "callToAction":
+            return element.href
+              ? `>> ${element.label} << ${element.href}`
+              : `>> ${element.label} <<`;
+          case "signature":
+            return `(c) ${context.brand.copyrightYear} - ${element.signer ?? context.brand.name}`;
+          default:
+            return "";
+        }
+      })
+      .filter(Boolean)
+      .join("\n"),
+};
+
+/** A rich channel: images fine, no conversations. Returns a record, not a string. */
+const CARD_RENDERER: Renderer<{ title: string; blocks: string[] }> = {
+  id: "card",
+  supports: (elementType) => elementType !== "chatUnit",
+  render: (content) => ({
+    title: content.metadata.title,
+    blocks: content.sections
+      .flatMap((section) => section.elements)
+      .filter((element) => CARD_RENDERER.supports(element.type))
+      .map((element) => element.type),
+  }),
+};
+
+const ALL_TYPES: NotificationElementType[] = [
+  "greeting",
+  "body",
+  "keyValueTable",
+  "callToAction",
+  "list",
+  "divider",
+  "warning",
+  "metadata",
+  "notice",
+  "chatUnit",
+  "signature",
+  "heroImage",
+];
+
+describe("Renderer", () => {
+  it("declares a stable channel id", () => {
+    expect(TEXT_RENDERER.id).toBe("text");
+    expect(CARD_RENDERER.id).toBe("card");
+  });
+
+  it("answers supports() for every element type — the predicate is total", () => {
+    for (const type of ALL_TYPES) {
+      expect(typeof TEXT_RENDERER.supports(type), type).toBe("boolean");
+      expect(typeof CARD_RENDERER.supports(type), type).toBe("boolean");
+    }
+  });
+
+  it("omits unsupported elements rather than throwing or approximating them", () => {
+    // heroImage is in CONTENT and unsupported by the text channel. The contract
+    // is that render() drops it silently — supports() and render() must agree.
+    expect(TEXT_RENDERER.supports("heroImage")).toBe(false);
+    expect(TEXT_RENDERER.render(CONTENT, CONTEXT)).toBe(
+      [
+        "Hi Ada,",
+        "Acme uses Company Semantics.",
+        ">> JOIN << https://example.test/j",
+        "(c) 2026 - Company Semantics",
+      ].join("\n"),
+    );
+  });
+
+  it("renders one content through channels of differing capability", () => {
+    // Same CONTENT object, no channel tags on it: each renderer keeps what it
+    // can depict. The card channel takes the hero image the text channel drops.
+    expect(CARD_RENDERER.render(CONTENT, CONTEXT).blocks).toContain(
+      "heroImage",
+    );
+    expect(CARD_RENDERER.render(CONTENT, CONTEXT).blocks).toEqual([
+      "heroImage",
+      "greeting",
+      "body",
+      "callToAction",
+      "signature",
+    ]);
+  });
+
+  it("lets each channel return its natural output type", () => {
+    // No common Out shape: a string on one channel, a record on the other.
+    expect(typeof TEXT_RENDERER.render(CONTENT, CONTEXT)).toBe("string");
+    expect(CARD_RENDERER.render(CONTENT, CONTEXT)).toEqual({
+      title: "Join Acme",
+      blocks: ["heroImage", "greeting", "body", "callToAction", "signature"],
+    });
+  });
+
+  it("reads the brand and year from context, never from a clock", () => {
+    // The whole reason RenderContext exists: no fake timer in this file, and
+    // swapping the context is enough to move the copyright line.
+    const pinned: RenderContext = {
+      brand: { name: "Acme", copyrightYear: 1999 },
+    };
+    expect(TEXT_RENDERER.render(CONTENT, pinned)).toContain("(c) 1999 - Acme");
+  });
+
+  it("is pure — same inputs, same bytes", () => {
+    expect(TEXT_RENDERER.render(CONTENT, CONTEXT)).toBe(
+      TEXT_RENDERER.render(CONTENT, CONTEXT),
+    );
+  });
+
+  it("lets an element's signer override the context brand", () => {
+    const onBehalf: NotificationContent = {
+      metadata: { kind: "org.invite", title: "Join Acme" },
+      sections: [{ elements: [{ type: "signature", signer: "Grace" }] }],
+    };
+    expect(TEXT_RENDERER.render(onBehalf, CONTEXT)).toBe("(c) 2026 - Grace");
+  });
+});