@company-semantics/contracts 35.0.0 → 36.0.0

package/src/notifications/renderers/email/__tests__/colors.test.ts

@@ -0,0 +1,227 @@
+/**
+ * The rules that keep `../colors.ts` the only place colour lives
+ * (ADR-CONTRACTS-088).
+ *
+ * The markup is not asserted here — `../../../__tests__/render-snapshot.test.ts`
+ * locks that. These are the claims a snapshot cannot make, because a snapshot
+ * records what the output IS and every one of these is about what it must never
+ * become:
+ *
+ * - A dark stylesheet is invisible to the snapshot's reviewer in the sense that
+ *   matters: you can read the `<style>` block in a diff and still not notice that
+ *   a role is missing from it, because the light bytes look perfect either way.
+ *   Dark mode fails silently. These tests are the alarm.
+ * - `DARK_STYLE` is a hand-written template, deliberately (it reads as the CSS it
+ *   is). The cost of a template over generated output is that it can forget a
+ *   role; this is where that cost is paid back.
+ */
+
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import type {
+  NotificationContent,
+  NotificationElement,
+} from "../../../content";
+import type { RenderContext } from "../../../context";
+import {
+  BASE_STYLE,
+  CLASS_ROLES,
+  DARK_STYLE,
+  HOVER_ROLES,
+  palette,
+  ROLES,
+  roleClass,
+} from "../colors";
+import { emailRenderer } from "../index";
+
+const CONTEXT: RenderContext = {
+  brand: { name: "Company Semantics", copyrightYear: 2026 },
+};
+
+/** The class name inside a role's attribute — `cs-meta` from `class="cs-meta"`. */
+function classNameOf(role: (typeof ROLES)[number]): string {
+  const match = roleClass(role).match(/class="([^"]+)"/);
+  if (!match) throw new Error(`roleClass(${role}) is not a class attribute`);
+  return match[1];
+}
+
+/**
+ * One notification exercising every colour-bearing element. The chat unit carries
+ * both continuation shapes on purpose: dots followed by a CTA fold into it, and
+ * dots followed by nothing render standalone — two different emitters, two
+ * chances to forget a class.
+ */
+const EVERY_COLOURED_ELEMENT: NotificationContent = {
+  metadata: { kind: "chat.shared", title: "Colour coverage" },
+  sections: [
+    {
+      elements: [
+        { type: "warning" },
+        { type: "divider" },
+        { type: "callToAction", label: "Open", href: "https://example.com/a" },
+        {
+          type: "chatUnit",
+          items: [
+            { type: "message", role: "user", text: "Hello", from: "Sam Chen" },
+            { type: "continuation" },
+            {
+              type: "callToAction",
+              label: "Reply",
+              href: "https://example.com/b",
+            },
+            { type: "message", role: "assistant", text: "Hi back" },
+            { type: "continuation" },
+          ],
+        },
+        { type: "signature" },
+      ],
+    },
+  ],
+};
+
+describe("email colours", () => {
+  it("gives every role a dark answer that reaches the stylesheet", () => {
+    const dark = palette("dark");
+    for (const role of ROLES) {
+      expect(DARK_STYLE, `role "${role}" is absent from DARK_STYLE`).toContain(
+        dark[role],
+      );
+    }
+  });
+
+  it("writes a rule for every class-bearing role", () => {
+    for (const role of CLASS_ROLES) {
+      // `:hover` roles are selected as `.cs-x:hover {`, resting ones as `.cs-x {`.
+      const selector = new RegExp(`\\.${classNameOf(role)}(:[a-z-]+)? \\{`);
+      expect(DARK_STYLE, `role "${role}" has a class but no dark rule`).toMatch(
+        selector,
+      );
+    }
+  });
+
+  it("states every hover role in BOTH schemes, since :hover cannot be inline", () => {
+    // Every other role is inline-light + dark override. A hover role has no inline
+    // form, so a light answer that never reaches BASE_STYLE is simply lost — and
+    // nothing else in this file would notice.
+    for (const role of HOVER_ROLES) {
+      const selector = new RegExp(`\\.${classNameOf(role)}:hover \\{`);
+      expect(BASE_STYLE, `hover role "${role}" has no light rule`).toMatch(
+        selector,
+      );
+      expect(BASE_STYLE, `hover role "${role}" light value`).toContain(
+        palette("light")[role],
+      );
+      expect(DARK_STYLE, `hover role "${role}" has no dark rule`).toMatch(
+        selector,
+      );
+    }
+  });
+
+  it("marks every declaration !important, in both blocks", () => {
+    // Load-bearing, not defensive: the light colour is inline, inline beats a
+    // stylesheet on specificity, and a rule that loses that fight does nothing
+    // at all while looking entirely correct.
+    const rules = `${BASE_STYLE}\n${DARK_STYLE}`.split("\n").filter((line) => {
+      const start = line.trimStart();
+      return start.startsWith(".") || start.startsWith("body");
+    });
+    // Guards the filter above: a reformat that matches no lines would turn the
+    // loop below into a vacuous pass. `body` is the +1; BASE_STYLE contributes
+    // one line per hover role.
+    expect(rules).toHaveLength(CLASS_ROLES.length + 1 + HOVER_ROLES.length);
+
+    for (const rule of rules) {
+      const body = rule.slice(rule.indexOf("{") + 1, rule.lastIndexOf("}"));
+      const declarations = body
+        .split(";")
+        .map((d) => d.trim())
+        .filter(Boolean);
+      expect(declarations.length).toBeGreaterThan(0);
+      for (const declaration of declarations) {
+        expect(
+          declaration,
+          `"${declaration}" would lose to the inline style`,
+        ).toContain("!important");
+      }
+    }
+  });
+
+  it("styles every class the renderer actually emits", () => {
+    // The end-to-end direction: the tests above start from the palette, this one
+    // starts from the output, so a class hook added to a tag without a matching
+    // rule is caught from the side the palette cannot see.
+    const { html } = emailRenderer.render(EVERY_COLOURED_ELEMENT, CONTEXT);
+    // One attribute can carry several classes (`class="cs-cta cs-cta-hover"`).
+    const emitted = new Set(
+      [...html.matchAll(/class="([^"]+)"/g)].flatMap((match) =>
+        match[1].split(/\s+/),
+      ),
+    );
+    expect(emitted.size).toBeGreaterThan(0);
+    const stylesheet = `${BASE_STYLE}\n${DARK_STYLE}`;
+    for (const className of emitted) {
+      expect(stylesheet, `${className} is emitted but never styled`).toMatch(
+        new RegExp(`\\.${className}(:[a-z-]+)? \\{`),
+      );
+    }
+  });
+
+  it("puts the hover hook on a CTA that links, and never on one that does not", () => {
+    // The invariant `./cta.ts` already carried — an unlinked label is a payload,
+    // not a button — extended to hover. Lighting up an OTP code under the pointer
+    // promises a click that does not exist.
+    const hoverClass = classNameOf("ctaHover");
+    // The classes the markup APPLIES, not every mention in the document — the
+    // stylesheet names `.cs-cta-hover` too, and matching that would pass whether
+    // or not any element wears it.
+    const applied = (cta: NotificationElement) => {
+      const { html } = emailRenderer.render(
+        {
+          metadata: { kind: "auth.otp", title: "t" },
+          sections: [{ elements: [cta] }],
+        },
+        CONTEXT,
+      );
+      return [...html.matchAll(/class="([^"]+)"/g)].flatMap((match) =>
+        match[1].split(/\s+/),
+      );
+    };
+
+    const linked = applied({
+      type: "callToAction",
+      label: "Open",
+      href: "https://example.com/a",
+    });
+    const payload = applied({ type: "callToAction", label: "123456" });
+
+    expect(linked).toContain(hoverClass);
+    expect(payload).not.toContain(hoverClass);
+    // Both still wear the resting edge.
+    expect(payload).toContain(classNameOf("cta"));
+  });
+
+  it("leaves no raw colour anywhere else in the channel", () => {
+    // What stops `style="color:#888"` reappearing in chat.ts in six months. A
+    // test rather than a CI guard: guards live in company-semantics-ci and adding
+    // one is cross-repo plus its own ADR — revisit if this earns it.
+    const dir = dirname(dirname(fileURLToPath(import.meta.url)));
+    const hex = /#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{3})\b/;
+
+    const sources = readdirSync(dir).filter(
+      (file) => file.endsWith(".ts") && file !== "colors.ts",
+    );
+    expect(sources.length).toBeGreaterThan(0);
+
+    for (const file of sources) {
+      const found = readFileSync(join(dir, file), "utf8").match(hex);
+      expect(
+        found?.[0],
+        `${file} states ${found?.[0]} directly — give it a role in colors.ts`,
+      ).toBeUndefined();
+    }
+  });
+});

package/src/notifications/renderers/email/__tests__/render.test.ts

@@ -1,48 +1,46 @@
 /**
- * The email renderer's correctness proof (ADR-CONTRACTS-086).
+ * The email renderer's behavioural rules (ADR-CONTRACTS-086) — the claims that
+ * hold no matter how the email is styled: it supports every element type, takes
+ * the subject from the content's title, takes the year and signer from context
+ * rather than a clock, restores the `:` the content model does not carry, and
+ * escapes user-controlled text.
  *
- * The renderer has exactly one hard requirement: compose a kind, render it
- * through this channel, and get the bytes the old `src/email/render` produced.
- * So that is what this asserts — every fixture in the frozen output-parity
- * golden, composed via `NOTIFICATION_DEFINITIONS` and rendered through
- * `emailRenderer`, character-for-character.
- *
- * This does NOT replace `../../../__tests__/output-parity.test.ts`. That one
- * pins the ENTRY POINT (`renderToChannel`, the whole pipeline) against the same
- * golden; this pins the RENDERER alone, so a failure here says the markup moved
- * rather than that the wiring did. Two levels, one golden: either drifting is a
- * failure.
+ * The MARKUP is not asserted here. `../../../__tests__/render-snapshot.test.ts`
+ * locks that, as a reviewable regenerable diff. Until ADR-CONTRACTS-087 this
+ * file also asserted every fixture byte-for-byte against the 32.0.0 golden, to
+ * prove the multi-channel generalisation moved no bytes; that proof shipped in
+ * 35.0.0 and was retired with the golden, because email design is now allowed to
+ * change and byte-equality to a deleted layer cannot survive it being exercised.
  *
  * There is no fake timer here, and that is the improvement being locked in: the
- * year comes from `RenderContext`, so the golden's clock is just a number.
+ * year comes from `RenderContext`, so the fixtures' clock is just a number.
  */
 
 import { describe, expect, it } from "vitest";
 
 import type {
   NotificationContent,
+  NotificationElement,
   NotificationElementType,
 } from "../../../content";
 import type { RenderContext } from "../../../context";
 import { NOTIFICATION_DEFINITIONS } from "../../../registry";
 import {
-  OUTPUT_PARITY_CLOCK,
-  OUTPUT_PARITY_FIXTURES,
-  OUTPUT_PARITY_GOLDEN,
+  FIXTURE_CLOCK,
+  NOTIFICATION_FIXTURES,
   fixtureKey,
-} from "../../../__tests__/output-parity.golden";
+} from "../../../__tests__/fixtures";
 import { emailRenderer } from "../index";
 
 /**
- * The golden's context, stated rather than ticked. The old layer reached for
+ * The fixtures' context, stated rather than ticked. The old layer reached for
  * `new Date().getFullYear()` mid-render, which is why every render test had to
- * freeze the clock; here the year the golden was captured under is simply a
- * value.
+ * freeze the clock; here the year is simply a value.
  */
-const GOLDEN_CONTEXT: RenderContext = {
+const FIXTURE_CONTEXT: RenderContext = {
   brand: {
     name: "Company Semantics",
-    copyrightYear: new Date(OUTPUT_PARITY_CLOCK).getUTCFullYear(),
+    copyrightYear: new Date(FIXTURE_CLOCK).getUTCFullYear(),
   },
 };
 
@@ -77,7 +75,7 @@ describe("emailRenderer", () => {
       metadata: { kind: "org.invite", title: "Join Acme" },
       sections: [{ elements: [{ type: "body", text: "Hello." }] }],
     };
-    expect(emailRenderer.render(content, GOLDEN_CONTEXT).subject).toBe(
+    expect(emailRenderer.render(content, FIXTURE_CONTEXT).subject).toBe(
       "Join Acme",
     );
   });
@@ -100,7 +98,7 @@ describe("emailRenderer", () => {
       metadata: { kind: "org.invite", title: "t" },
       sections: [{ elements: [{ type: "signature", signer: "Grace" }] }],
     };
-    expect(emailRenderer.render(content, GOLDEN_CONTEXT).text).toContain(
+    expect(emailRenderer.render(content, FIXTURE_CONTEXT).text).toContain(
       "• Grace",
     );
   });
@@ -126,7 +124,7 @@ describe("emailRenderer", () => {
         },
       ],
     };
-    const { text } = emailRenderer.render(content, GOLDEN_CONTEXT);
+    const { text } = emailRenderer.render(content, FIXTURE_CONTEXT);
     expect(text).toContain("Status: Valid");
     expect(text).toContain("Request details:");
     expect(text).toContain("IP address: 203.0.113.1");
@@ -141,11 +139,96 @@ describe("emailRenderer", () => {
         },
       ],
     };
-    const { html } = emailRenderer.render(content, GOLDEN_CONTEXT);
+    const { html } = emailRenderer.render(content, FIXTURE_CONTEXT);
     expect(html).toContain("<script>");
     expect(html).not.toContain("<script>");
   });
 
+  it("escapes a URL, so it cannot close its attribute and forge another", () => {
+    // `href` and `src` are the two values that reach the markup as a URL rather
+    // than as text, and they used to be interpolated raw — an HTML injection on
+    // its own, and since ADR-CONTRACTS-089 a style injection too: `inlineStyles`
+    // rewrites class attributes, so a URL that can write `class="csr-body"` can
+    // write any declaration in the registry into someone else's element.
+    const html = (element: NotificationElement) =>
+      emailRenderer.render(
+        {
+          metadata: { kind: "auth.otp", title: "t" },
+          sections: [{ elements: [element] }],
+        },
+        FIXTURE_CONTEXT,
+      ).html;
+
+    const cta = html({
+      type: "callToAction",
+      label: "Open",
+      href: 'https://x.test/" data-forged="1',
+    });
+    // The quote survives as text, so the forged attribute never becomes one.
+    // Asserted against `data-forged="` — the ATTRIBUTE form — because the escaped
+    // payload still contains the string `data-forged=`, and a looser match would
+    // pass whether or not the fix is present.
+    expect(cta).toContain("&quot;");
+    expect(cta).not.toMatch(/data-forged="/);
+
+    const hero = html({
+      type: "heroImage",
+      src: '/x.png" onerror="alert(1)',
+      alt: "x",
+    });
+    expect(hero).not.toMatch(/onerror="/);
+  });
+
+  it("makes a linked CTA's whole box the click target, an unlinked one not clickable", () => {
+    // The click target is the anchor, so it must fill the box — `display: block` +
+    // the padding on the `<a>` itself, not the cell. An OTP code has no href: it
+    // must not become an anchor at all, which is what keeps it uncopiable-as-a-link
+    // and unclickable.
+    const box = (cta: NotificationElement) =>
+      emailRenderer.render(
+        {
+          metadata: { kind: "auth.otp", title: "t" },
+          sections: [{ elements: [cta] }],
+        },
+        FIXTURE_CONTEXT,
+      ).html;
+
+    const linked = box({
+      type: "callToAction",
+      label: "Open",
+      href: "https://example.com/x",
+    });
+    expect(linked).toMatch(
+      /<a [^>]*href="https:\/\/example\.com\/x"[^>]*style="display: block; padding:/,
+    );
+
+    const payload = box({ type: "callToAction", label: "123456" });
+    expect(payload).not.toContain("<a ");
+    // The cell carries the padding instead, so the code is still a padded box.
+    expect(payload).toMatch(/<td style="padding: /);
+  });
+
+  it("restores the CTA's cell padding for Outlook, which cannot fill the anchor", () => {
+    // Outlook's Word engine ignores `display: block`, so the full-box target
+    // degrades to today's text click there. The MSO block must put the padding
+    // back on the cell, or Outlook renders the button cramped.
+    const { html } = emailRenderer.render(
+      {
+        metadata: { kind: "org.invite", title: "t" },
+        sections: [
+          {
+            elements: [
+              { type: "callToAction", label: "Join", href: "https://x.test" },
+            ],
+          },
+        ],
+      },
+      FIXTURE_CONTEXT,
+    );
+    expect(html).toContain("<!--[if mso]>");
+    expect(html).toMatch(/\[if mso\]>.*\.cs-cta td \{ padding: .* \}/s);
+  });
+
   it("is pure — same inputs, same bytes", () => {
     const content = NOTIFICATION_DEFINITIONS["security.alert"].compose(
       {
@@ -153,27 +236,38 @@ describe("emailRenderer", () => {
         details: "5 codes in 2 minutes",
         timestamp: "2026-07-15T00:00:00.000Z",
       },
-      GOLDEN_CONTEXT,
+      FIXTURE_CONTEXT,
     );
-    expect(emailRenderer.render(content, GOLDEN_CONTEXT)).toEqual(
-      emailRenderer.render(content, GOLDEN_CONTEXT),
+    expect(emailRenderer.render(content, FIXTURE_CONTEXT)).toEqual(
+      emailRenderer.render(content, FIXTURE_CONTEXT),
     );
   });
 
-  describe("output parity with the email layer at 32.0.0", () => {
-    for (const fixture of OUTPUT_PARITY_FIXTURES) {
+  describe("renders every fixture", () => {
+    // Was a byte-for-byte assertion against the 32.0.0 golden until
+    // ADR-CONTRACTS-087 retired it. The markup itself is locked by
+    // `../../../__tests__/render-snapshot.test.ts`; what is worth proving HERE
+    // is narrower and survives a redesign — that every kind in the registry
+    // composes and renders through this channel at all, on both surfaces. A kind
+    // whose `compose` reaches for a field its payload lacks fails here, at the
+    // renderer, rather than in whichever consumer sends it first.
+    for (const fixture of NOTIFICATION_FIXTURES) {
       const key = fixtureKey(fixture.kind, fixture.name);
-      it(`${key} renders byte-for-byte`, () => {
+      it(`${key}`, () => {
         const definition = NOTIFICATION_DEFINITIONS[fixture.kind];
         // `payload as never`: the fixture call sites are type-checked in the
-        // golden module; this only bridges compose's per-kind payload.
+        // fixtures module; this only bridges compose's per-kind payload.
         const content = definition.compose(
           fixture.payload as never,
-          GOLDEN_CONTEXT,
+          FIXTURE_CONTEXT,
         );
-        expect(emailRenderer.render(content, GOLDEN_CONTEXT)).toEqual(
-          OUTPUT_PARITY_GOLDEN[key],
+        const { subject, text, html } = emailRenderer.render(
+          content,
+          FIXTURE_CONTEXT,
         );
+        expect(subject).toBeTruthy();
+        expect(text).toBeTruthy();
+        expect(html).toContain("<!DOCTYPE html>");
       });
     }
   });

package/src/notifications/renderers/email/__tests__/styles.test.ts

@@ -0,0 +1,111 @@
+/**
+ * The style registry's contract (ADR-CONTRACTS-089).
+ *
+ * `../../__tests__/render-snapshot.test.ts` already proves the html surface's
+ * bytes, and it is the authority on what the email LOOKS like. What it cannot say
+ * is WHY those bytes are safe to derive, because a snapshot passes just as happily
+ * over markup that leaks a recipe class or drops a role hook. This file asserts the
+ * two properties the derivation rests on:
+ *
+ * - a `cs-` role hook SHIPS, because `darkStyle` needs it in the markup;
+ * - a `csr-` recipe class DOES NOT, because it is spent and dropped.
+ *
+ * Get either backwards and the snapshot still passes while dark mode silently
+ * stops working, or the shipped email carries dead classes nothing styles.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type { NotificationContent } from "../../../content";
+import type { RenderContext } from "../../../context";
+import { emailRenderer } from "../index";
+import { inlineOf, inlineStyles, ruleOf, STYLE_NAMES } from "../styles";
+
+const CONTEXT: RenderContext = {
+  brand: { name: "Company Semantics", copyrightYear: 2026 },
+};
+
+/** One of everything that carries a class, so the scan below has something to see. */
+const CONTENT: NotificationContent = {
+  metadata: { kind: "auth.otp", title: "t" },
+  sections: [
+    {
+      elements: [
+        { type: "greeting", recipientName: "Sam" },
+        { type: "warning" },
+        { type: "divider" },
+        { type: "callToAction", label: "Open", href: "https://x.test/a" },
+        { type: "callToAction", label: "123456" },
+        {
+          type: "chatUnit",
+          items: [
+            { type: "message", role: "user", text: "hi", from: "Sam" },
+            { type: "message", role: "assistant", text: "hello" },
+            { type: "continuation" },
+            { type: "callToAction", label: "Read", href: "https://x.test/b" },
+          ],
+        },
+        { type: "signature" },
+      ],
+    },
+  ],
+};
+
+/** Every class the shipped markup actually applies. */
+function shippedClasses(html: string): string[] {
+  return [...html.matchAll(/class="([^"]+)"/g)].flatMap((m) =>
+    m[1].split(/\s+/),
+  );
+}
+
+describe("the style registry", () => {
+  it("ships no recipe class — they are spent by the inliner, not delivered", () => {
+    const { html } = emailRenderer.render(CONTENT, CONTEXT);
+    // The whole document, not just the class attributes: a recipe class must not
+    // survive anywhere, including in a stylesheet the html surface never wants.
+    expect(html).not.toContain("csr-");
+  });
+
+  it("ships every role hook, because the dark stylesheet needs it there", () => {
+    const { html } = emailRenderer.render(CONTENT, CONTEXT);
+    const shipped = shippedClasses(html);
+    expect(shipped.length).toBeGreaterThan(0);
+    // A sample across the roles this content exercises. `cs-cta-hover` is the
+    // interesting one: it is the only reason `.cs-cta` and the hover state are
+    // separate roles, and it rides on the linked CTA above.
+    for (const hook of ["cs-link", "cs-cta", "cs-cta-hover", "cs-bubble"]) {
+      expect(shipped, `${hook} never reached the markup`).toContain(hook);
+    }
+  });
+
+  it("turns a recipe-only class attribute into a style, leaving no class behind", () => {
+    // The collapse that makes `<p class="csr-p-none">` render as the `<p style="…">`
+    // the channel shipped before this registry existed. A leftover `class=""` would
+    // be invisible in a client and a permanent diff in the snapshot.
+    expect(inlineStyles(`<p class="csr-p-none">x</p>`)).toBe(
+      `<p style="${inlineOf("p-none")}">x</p>`,
+    );
+  });
+
+  it("keeps role hooks and appends the style, in that order", () => {
+    // Order is not cosmetic: it is what makes the inliner reproduce the previous
+    // markup byte-for-byte rather than merely equivalently.
+    expect(inlineStyles(`<td class="cs-bubble csr-bubble-user">x</td>`)).toBe(
+      `<td class="cs-bubble" style="${inlineOf("bubble-user")}">x</td>`,
+    );
+  });
+
+  it("leaves markup with no classes untouched", () => {
+    const plain = `<tr><td></td></tr>`;
+    expect(inlineStyles(plain)).toBe(plain);
+  });
+
+  it("states each recipe as a rule and as an inline style, from one source", () => {
+    // The two surfaces' only difference is the shape, never the content — which is
+    // the claim that lets `ampShell` and `htmlShell` share this registry.
+    for (const name of STYLE_NAMES) {
+      expect(ruleOf(name)).toBe(`.csr-${name} { ${inlineOf(name)} }`);
+      expect(inlineOf(name).endsWith(";")).toBe(true);
+    }
+  });
+});