@company-semantics/contracts 33.0.0 → 35.0.0

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

@@ -0,0 +1,222 @@
+/**
+ * `compose` is where the whole layer's purity claim lives (ADR-CONTRACTS-085):
+ * everything above it is fact, everything below is one channel's opinion. These
+ * tests hold it to the four promises a type cannot express.
+ *
+ * PURITY — the same `(payload, context)` composes the same content, twice, with
+ * the clock moved between. The old `blocks.signature()` read
+ * `new Date().getFullYear()` mid-render, which is why every render test used to
+ * freeze time; the point of `RenderContext` is that these tests do not have to.
+ * Moving the clock and getting identical content is the proof that the ambient
+ * read is really gone.
+ *
+ * THE BRAND SEAM — the ten kinds that footer "sent via Company Semantics" must
+ * read that name from `context.brand.name`, not from an imported constant. A
+ * test that only ever renders the default context cannot tell the difference, so
+ * these override the brand and assert the override lands.
+ *
+ * THE PII GATE — the old `renderAuthOtp` took an `includeRequestMetadata` option
+ * and the backend passed an env flag. `compose` has no such parameter: the gate
+ * is whether the payload carries the fields. That relocation is a
+ * privacy-relevant behaviour change and is pinned here rather than left to the
+ * email wiring to discover.
+ *
+ * CONTENT, NOT MARKUP — the elements carry no HTML. The cheapest possible check
+ * for the mistake this layer exists to prevent.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type { NotificationContent, NotificationElement } from "../content";
+import { createRenderContext } from "../context";
+import type { NotificationKind } from "../kinds";
+import { NOTIFICATION_DEFINITIONS } from "../registry";
+import { OUTPUT_PARITY_FIXTURES } from "./output-parity.golden";
+
+const CONTEXT = createRenderContext({ brand: { copyrightYear: 2026 } });
+
+/** Compose a kind against its first parity fixture. */
+function compose(
+  kind: NotificationKind,
+  context = CONTEXT,
+): NotificationContent {
+  const fixture = OUTPUT_PARITY_FIXTURES.find((f) => f.kind === kind);
+  if (!fixture) throw new Error(`No parity fixture for kind: ${kind}`);
+  const fn = NOTIFICATION_DEFINITIONS[kind].compose as (
+    p: unknown,
+    c: typeof context,
+  ) => NotificationContent;
+  return fn(fixture.payload, context);
+}
+
+const KINDS = Object.keys(NOTIFICATION_DEFINITIONS) as NotificationKind[];
+
+/** Every element of a composed notification, flattened across its sections. */
+function elementsOf(content: NotificationContent): NotificationElement[] {
+  return content.sections.flatMap((s) => s.elements);
+}
+
+describe("compose purity", () => {
+  it("is deterministic for the same payload and context", () => {
+    for (const kind of KINDS) {
+      expect(compose(kind)).toEqual(compose(kind));
+    }
+  });
+
+  it("does not read the clock", () => {
+    // The impurity this layer retired: the old `blocks.signature()` called
+    // `new Date().getFullYear()` mid-render, so its render tests had to freeze
+    // time to stay stable. These deliberately do not.
+    //
+    // The stub fakes ONLY the argless `new Date()` and `Date.now()` — the clock.
+    // `new Date(iso)` is left alone because parsing a timestamp the PAYLOAD
+    // carries is pure, and two composes rely on it: `formatExpiry` and
+    // security.alert's `Time` row. Faking those too would fail the honest code.
+    const realDate = Date;
+    const before = KINDS.map((kind) => compose(kind));
+    try {
+      globalThis.Date = class extends realDate {
+        constructor(...args: ConstructorParameters<DateConstructor>) {
+          if (args.length === 0) super("2099-01-01T00:00:00.000Z");
+          else super(...args);
+        }
+        static now(): number {
+          return new realDate("2099-01-01T00:00:00.000Z").getTime();
+        }
+      } as DateConstructor;
+
+      expect(KINDS.map((kind) => compose(kind))).toEqual(before);
+    } finally {
+      globalThis.Date = realDate;
+    }
+  });
+
+  it("emits no year — the copyright year is the renderer's, from the context", () => {
+    // The old `signature()` baked the year into its bytes. Here `signature` is a
+    // fieldless element and the year arrives at render time, which is what makes
+    // a composed notification safe to cache, log or compare across a New Year.
+    for (const kind of KINDS) {
+      const signatures = elementsOf(compose(kind)).filter(
+        (e) => e.type === "signature",
+      );
+      expect(signatures).toEqual([{ type: "signature" }]);
+    }
+  });
+});
+
+describe("compose reads ambient state from the context", () => {
+  it("takes the brand name from context.brand, not an imported constant", () => {
+    const context = createRenderContext({
+      brand: { name: "Umbrella Corp", copyrightYear: 2026 },
+    });
+
+    // Ten of the eleven kinds footer "sent via <brand>"; security.alert has no
+    // notice at all, on purpose.
+    const branded = KINDS.filter((kind) => kind !== "security.alert");
+    expect(branded).toHaveLength(10);
+
+    for (const kind of branded) {
+      const notices = elementsOf(compose(kind, context)).filter(
+        (e) => e.type === "notice",
+      );
+
+      expect(notices).toHaveLength(1);
+      expect(notices[0].lines[0]).toContain("Umbrella Corp");
+      expect(notices[0].lines[0]).not.toContain("Company Semantics");
+    }
+  });
+
+  it("still says Company Semantics under an un-overridden context", () => {
+    // The default must reproduce today's bytes, or the parity proof moves.
+    const notice = elementsOf(compose("org.invite")).find(
+      (e) => e.type === "notice",
+    );
+    expect(notice?.lines).toEqual([
+      "This invitation was sent via Company Semantics.",
+      "If you weren't expecting this, no action is required.",
+    ]);
+  });
+});
+
+describe("compose gates PII on the payload, not on an option", () => {
+  const otpCompose = NOTIFICATION_DEFINITIONS["auth.otp"].compose;
+
+  it("omits request details when the payload carries none", () => {
+    const content = otpCompose(
+      { otp: "123456", expiresInMinutes: 10 },
+      CONTEXT,
+    );
+
+    expect(elementsOf(content).map((e) => e.type)).not.toContain("metadata");
+  });
+
+  it("shows request details when the payload carries them", () => {
+    const content = otpCompose(
+      {
+        otp: "246810",
+        expiresInMinutes: 5,
+        requestIp: "203.0.113.4",
+        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
+      },
+      CONTEXT,
+    );
+
+    const metadata = elementsOf(content).find((e) => e.type === "metadata");
+    expect(metadata).toEqual({
+      type: "metadata",
+      label: "Request details",
+      rows: [
+        { label: "IP address", value: "203.0.113.4" },
+        {
+          label: "Device",
+          value: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
+        },
+      ],
+    });
+  });
+
+  it("truncates an overlong user agent, as the email layer did", () => {
+    const content = otpCompose(
+      { otp: "246810", expiresInMinutes: 5, userAgent: "U".repeat(120) },
+      CONTEXT,
+    );
+
+    const metadata = elementsOf(content).find((e) => e.type === "metadata");
+    expect(metadata).toEqual({
+      type: "metadata",
+      label: "Request details",
+      rows: [{ label: "Device", value: `${"U".repeat(77)}...` }],
+    });
+  });
+
+  it("shows the code itself as a call to action with no href", () => {
+    // `href` absent means the label IS the payload. A renderer must not
+    // fabricate a destination for an OTP.
+    const chatUnit = elementsOf(
+      otpCompose({ otp: "123456", expiresInMinutes: 10 }, CONTEXT),
+    ).find((e) => e.type === "chatUnit");
+
+    expect(chatUnit?.items).toContainEqual({
+      type: "callToAction",
+      label: "123456",
+    });
+  });
+});
+
+describe("compose emits content, not markup", () => {
+  it("puts no HTML in any element of any kind", () => {
+    for (const kind of KINDS) {
+      const serialized = JSON.stringify(compose(kind));
+      expect(serialized).not.toMatch(/<\/?[a-z]+[\s>]/i);
+      expect(serialized).not.toContain("&#39;");
+    }
+  });
+
+  it("carries no spacing — that is a channel's answer, not the notification's", () => {
+    for (const kind of KINDS) {
+      for (const element of elementsOf(compose(kind))) {
+        expect(element).not.toHaveProperty("spacing");
+      }
+    }
+  });
+});

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

@@ -0,0 +1,81 @@
+/**
+ * `NotificationKind` is the migration's central claim: that the eleven things
+ * the email layer could actually SAY are notifications, not emails
+ * (ADR-CONTRACTS-085).
+ *
+ * WHAT THESE TESTS USED TO DO, AND WHY THEY NO LONGER DO IT. Membership was
+ * asserted against `IMPLEMENTED_EMAIL_KINDS`, and the union's deliberate
+ * divergence against `EmailKind` — one live union checked against another. Both
+ * sides of both comparisons were `src/email/`'s, and that directory is now
+ * deleted (ADR-CONTRACTS-086). Those assertions were not rewired, because there
+ * is nothing to rewire them to: an assertion with one side left is not a weaker
+ * version of itself, it is a tautology that reads like coverage. They were
+ * removed rather than allowed to pass vacuously.
+ *
+ * What still holds the membership claim, in the order it bites:
+ * - the `Record<NotificationKind, true>` below, which fails to COMPILE if a
+ *   union member is added without being named here;
+ * - the frozen list in the first test, which fails at runtime if one is removed;
+ * - `./registry.test.ts`, which pins a definition for every member;
+ * - `./output-parity.test.ts`, which pins golden bytes — captured from the old
+ *   layer — for every member. That is what now carries "these are exactly the
+ *   kinds email could render": every kind here has bytes that layer produced.
+ *
+ * The DIVERGENCE is the easiest thing in this change to mistake for an omission,
+ * so it keeps a test of its own. `auth.magic_link` was a registered subject with
+ * no template: the old `renderEmail` accepted it and threw. Excluding it is what
+ * makes the notification registry total, so its absence is asserted on purpose —
+ * restoring it "for symmetry" would put the runtime hole back.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type { NotificationKind } from "../kinds";
+
+/**
+ * Every notification kind, exhaustively. The `Record` type documents the lock; a
+ * new union member must be named here. The assertions below are what enforce it
+ * at runtime — `src/tsconfig.json` excludes test files, so the type alone would
+ * not fail a build.
+ */
+const ALL_NOTIFICATION_KINDS: Record<NotificationKind, true> = {
+  "auth.otp": true,
+  "org.invite": true,
+  "org.unit_owner_granted": true,
+  "org.ownership_transfer": true,
+  "org.ownership_transfer_completed": true,
+  "security.alert": true,
+  "chat.shared": true,
+  "share.granted": true,
+  "companyMd.access_requested": true,
+  "companyMd.access_request_approved": true,
+  "companyMd.access_request_denied": true,
+};
+
+const KINDS = Object.keys(ALL_NOTIFICATION_KINDS).sort();
+
+describe("NotificationKind", () => {
+  it("has exactly the eleven kinds with something to say", () => {
+    expect(KINDS).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("excludes auth.magic_link, the one kind email registered without implementing", () => {
+    // Deliberate, not an oversight: `renderEmail("auth.magic_link", …)`
+    // type-checked and threw. A kind earns membership by having something to
+    // say, not by having a subject reserved for it. `./registry.test.ts` asserts
+    // `isValidNotificationKind` rejects it at the runtime boundary too.
+    expect(KINDS).not.toContain("auth.magic_link");
+  });
+});