@company-semantics/contracts 52.0.0 → 53.0.0

package/src/notifications/renderers/slack/__tests__/index.test.ts

@@ -21,7 +21,9 @@
 import { describe, expect, it } from "vitest";
 
 import type {
+  ChatUnitItem,
   NotificationContent,
+  NotificationElement,
   NotificationElementType,
 } from "../../../content";
 import type { RenderContext } from "../../../context";
@@ -76,6 +78,28 @@ const ALL_TYPES: NotificationElementType[] = [
   "heroImage",
 ];
 
+/** One of every element, so the exhaustiveness check has something to render. */
+const SPECIMENS: Record<NotificationElementType, NotificationElement> = {
+  greeting: { type: "greeting", recipientName: "Ada" },
+  body: { type: "body", text: "Acme uses Company Semantics." },
+  keyValueTable: {
+    type: "keyValueTable",
+    rows: [{ label: "Org", value: "Acme" }],
+  },
+  callToAction: { type: "callToAction", label: "JOIN", href: "https://e.test" },
+  list: { type: "list", items: ["Read"] },
+  divider: { type: "divider" },
+  warning: { type: "warning" },
+  metadata: { type: "metadata", rows: [{ label: "IP", value: "203.0.113.7" }] },
+  notice: { type: "notice", lines: ["Not expecting this?"] },
+  chatUnit: {
+    type: "chatUnit",
+    items: [{ type: "message", role: "user", text: "Hello?" }],
+  },
+  signature: { type: "signature" },
+  heroImage: { type: "heroImage", src: "https://e.test/h.png", alt: "Acme" },
+};
+
 /** One content carrying one element — the shape assertions read better alone. */
 function only(
   element: NotificationContent["sections"][number]["elements"][number],
@@ -87,6 +111,32 @@ function only(
   };
 }
 
+/**
+ * Every character of monospace text in a message, blocks joined by newline.
+ *
+ * Most assertions here are about WHAT THE READER SEES, and after coalescing that
+ * is spread across a `rich_text` → `rich_text_preformatted` → runs nesting that
+ * is noise in an expectation. Reading the block SHAPE is still done directly,
+ * where the shape is the point.
+ */
+function monospaceText(message: { blocks: unknown[] }): string {
+  return message.blocks
+    .map((raw) => {
+      const block = raw as { type: string; elements?: unknown[] };
+      if (block.type !== "rich_text") return "";
+      return (block.elements ?? [])
+        .map((rawElement) => {
+          const element = rawElement as { type: string; elements?: unknown[] };
+          if (element.type !== "rich_text_preformatted") return "";
+          return (element.elements ?? [])
+            .map((run) => (run as { text?: string }).text ?? "")
+            .join("");
+        })
+        .join("");
+    })
+    .join("\n");
+}
+
 describe("slackRenderer", () => {
   it("declares a stable channel id", () => {
     expect(slackRenderer.id).toBe("slack");
@@ -98,9 +148,13 @@ describe("slackRenderer", () => {
     }
   });
 
-  it("declines only chatUnit — Block Kit cannot depict turn-taking", () => {
+  it("depicts every element — nothing is declined any more", () => {
+    // `chatUnit` was the one decline, and it was costing real payloads: both
+    // `auth.otp` and `org.invite` nest theirs inside one, so the code and the
+    // accept button never reached Slack. A monospace drawing depicts the
+    // conversation, so there is nothing left to decline.
     for (const type of ALL_TYPES) {
-      expect(slackRenderer.supports(type), type).toBe(type !== "chatUnit");
+      expect(slackRenderer.supports(type), type).toBe(true);
     }
   });
 
@@ -108,32 +162,35 @@ describe("slackRenderer", () => {
     expect(() => slackRenderer.render(CONTENT, CONTEXT)).not.toThrow();
   });
 
-  it("omits the declined element rather than flattening it", () => {
+  it("delivers the chatUnit's content instead of dropping it", () => {
+    // The regression this pins is the one that motivated the rebuild: this
+    // assertion used to read `.not.toContain`, and a Slack notification whose
+    // conversation is silently missing is a notification with a hole in it.
     const rendered = slackRenderer.render(CONTENT, CONTEXT);
 
-    expect(JSON.stringify(rendered)).not.toContain("Hello?");
+    expect(JSON.stringify(rendered)).toContain("Hello?");
   });
 
   it("returns its natural type — a Block Kit record, not a string", () => {
     const rendered = slackRenderer.render(CONTENT, CONTEXT);
 
-    // `text` is the fallback Slack shows where blocks cannot render. It is
-    // metadata.title — the same field email spends as its subject, and this
-    // channel ALSO leads with as a header.
+    // `text` is the fallback Slack shows where blocks cannot render — a push
+    // notification, a screen reader. It is `metadata.title`, the same field
+    // email spends as its subject.
     expect(rendered.text).toBe("Join Acme");
+
+    // Contiguous monospace coalesces into ONE block; the run breaks only where a
+    // native primitive genuinely interrupts it. One block per element would stack
+    // a bordered grey box per element, which is not what a message looks like.
     expect(rendered.blocks.map((block) => block.type)).toEqual([
-      "header",
-      "image",
-      "section",
-      "section",
-      "section",
-      "rich_text",
+      "rich_text", // title + its rule
+      "image", // heroImage — breaks the run
+      "rich_text", // greeting + body + keyValueTable
+      "rich_text", // list — a rich_text_list is NOT folded into a code box
       "divider",
-      "section",
-      "context",
-      "context",
-      "actions",
-      "context",
+      "rich_text", // warning + chatUnit + metadata + notice
+      "actions", // the linked CTA — a native button
+      "rich_text", // signature
     ]);
   });
 
@@ -141,51 +198,60 @@ describe("slackRenderer", () => {
   // The header — metadata.title's third spend
   // ===========================================================================
 
-  it("leads with a header block carrying the title", () => {
-    expect(slackRenderer.render(CONTENT, CONTEXT).blocks[0]).toEqual({
-      type: "header",
-      text: { type: "plain_text", text: "Join Acme" },
-    });
+  it("leads with the title in the monospace body, not a header block", () => {
+    // A `header` block is `plain_text` and Slack owns its typography entirely:
+    // `HeaderBlock` is `{ type, text }`, with no font, size, weight or colour
+    // anywhere in the schema. Putting the title in the body is what makes it
+    // monospace in a real workspace rather than only under a gallery stylesheet.
+    const rendered = slackRenderer.render(CONTENT, CONTEXT);
+
+    expect(rendered.blocks.some((block) => block.type === "header")).toBe(
+      false,
+    );
+    expect(monospaceText(rendered).startsWith("Join Acme\n─")).toBe(true);
   });
 
-  it("spends the title on BOTH the header and the fallback", () => {
-    // Neither use replaces the other: `text` is what a push notification and a
-    // screen reader get, the header is what the message looks like.
+  it("spends the title on BOTH the body and the fallback", () => {
+    // Dropping the header block cost the in-channel headline treatment and
+    // nothing else: the fallback was never carried by that block.
     const rendered = slackRenderer.render(CONTENT, CONTEXT);
 
     expect(rendered.text).toBe("Join Acme");
-    expect(JSON.stringify(rendered.blocks[0])).toContain("Join Acme");
+    expect(monospaceText(rendered)).toContain("Join Acme");
   });
 
-  it("truncates a header at Slack's documented 150 characters", () => {
+  it("keeps the whole title — the 150-char cap left with the header block", () => {
+    const long = "A".repeat(200);
     const rendered = slackRenderer.render(
-      only({ type: "body", text: "x" }, "A".repeat(200)),
+      only({ type: "body", text: "x" }, long),
       CONTEXT,
     );
-    const header = rendered.blocks[0];
 
-    expect(header.type).toBe("header");
-    expect(header).toMatchObject({
-      text: { text: `${"A".repeat(149)}…` },
-    });
-    // The FALLBACK is not truncated — only the block has the limit.
     expect(rendered.text).toHaveLength(200);
+    // Wrapped across monospace lines rather than cut, and no ellipsis anywhere.
+    expect(monospaceText(rendered)).not.toContain("…");
+    expect(monospaceText(rendered).replace(/\n/g, "")).toContain(long);
   });
 
-  it("emits no header when the title is empty — not an empty block", () => {
+  it("emits no title lines when the title is empty — not an empty rule", () => {
     const rendered = slackRenderer.render(
       only({ type: "body", text: "x" }, "   "),
       CONTEXT,
     );
 
-    expect(rendered.blocks.map((block) => block.type)).toEqual(["section"]);
+    expect(rendered.blocks.map((block) => block.type)).toEqual(["rich_text"]);
+    expect(monospaceText(rendered)).toBe("x");
   });
 
   // ===========================================================================
   // Shape — each element reaches its real Block Kit primitive
   // ===========================================================================
 
-  it("renders a keyValueTable as section fields, Slack's two-column device", () => {
+  it("says a keyValueTable as `Label: value` lines in the monospace flow", () => {
+    // A `table` block was tried here and removed. It draws its own bordered
+    // grid, so every key/value pair cut the message into another container and a
+    // two-fact notification arrived as five stacked boxes. The email states
+    // these as plain lines and reads as one thing.
     const rendered = slackRenderer.render(
       only({
         type: "keyValueTable",
@@ -197,25 +263,28 @@ describe("slackRenderer", () => {
       CONTEXT,
     );
 
-    expect(rendered.blocks[1]).toEqual({
-      type: "section",
-      fields: [
-        { type: "mrkdwn", text: "*Status*\nValid" },
-        { type: "mrkdwn", text: "*Expires in*\n10 minutes" },
-      ],
-    });
+    expect(rendered.blocks.some((block) => block.type === "table")).toBe(false);
+    expect(monospaceText(rendered)).toContain(
+      "Status: Valid\nExpires in: 10 minutes",
+    );
   });
 
-  it("chunks a keyValueTable at ten fields — Slack rejects an eleventh", () => {
+  it("keeps a long keyValueTable whole — the ten-field cap is gone", () => {
+    // `section.fields` capped at ten, so a 23-row table used to become three
+    // stacked sections and stopped reading as one table. Lines have no cap.
     const rows = Array.from({ length: 23 }, (_, index) => ({
       label: `L${index}`,
       value: `V${index}`,
     }));
-    const blocks = slackRenderer
-      .render(only({ type: "keyValueTable", rows }), CONTEXT)
-      .blocks.filter((block) => block.type === "section");
+    const rendered = slackRenderer.render(
+      only({ type: "keyValueTable", rows }),
+      CONTEXT,
+    );
 
-    expect(blocks.map((block) => block.fields?.length)).toEqual([10, 10, 3]);
+    const text = monospaceText(rendered);
+    for (const row of rows) {
+      expect(text).toContain(`${row.label}: ${row.value}`);
+    }
   });
 
   it("renders a list as a real rich_text_list, not bullet characters", () => {
@@ -279,54 +348,48 @@ describe("slackRenderer", () => {
     });
   });
 
-  it("renders a call to action without an href as a code block, not a button", () => {
+  it("draws a hrefless call to action as the `>> LABEL <<` box, not a button", () => {
     // `href` absent means the label IS the payload (an OTP code). A button with
-    // no destination would be a lie about what the notification is asking for;
-    // `rich_text_preformatted` is Slack's own device for a selectable code.
+    // no destination would be a lie about what the notification is asking for.
+    // The box is drawn by `../../ascii`, so it is the same box the email draws.
     const otp: NotificationContent = {
       metadata: { kind: "auth.otp", title: "Your code" },
       sections: [{ elements: [{ type: "callToAction", label: "123456" }] }],
     };
+    const rendered = slackRenderer.render(otp, CONTEXT);
 
-    expect(slackRenderer.render(otp, CONTEXT).blocks[1]).toEqual({
-      type: "rich_text",
-      elements: [
-        {
-          type: "rich_text_preformatted",
-          elements: [{ type: "text", text: "123456" }],
-        },
-      ],
-    });
+    expect(rendered.blocks.some((block) => block.type === "actions")).toBe(
+      false,
+    );
+    expect(monospaceText(rendered)).toContain(">> 123456 <<");
   });
 
   // ===========================================================================
   // Escaping — the rule follows the SURFACE, not the string
   // ===========================================================================
 
-  it("escapes Slack's reserved characters on an mrkdwn surface", () => {
-    const rendered = slackRenderer.render(
-      only({ type: "body", text: "a & b <c> <!channel>" }),
-      CONTEXT,
-    );
+  it("emits no mrkdwn surface at all — so nothing needs escaping", () => {
+    // The structural version of the old escaping rule. `mrkdwn` parses
+    // `&`/`<`/`>` and had to be escaped; `plain_text` and `rich_text` are
+    // literal and had to NOT be. Both mistakes were possible and neither was a
+    // type error, because both surfaces are `string`. Moving the body to
+    // `rich_text_preformatted` retired the last mrkdwn emitter, so the bug class
+    // is now impossible rather than merely avoided.
+    const rendered = slackRenderer.render(CONTENT, CONTEXT);
 
-    expect(rendered.blocks[1]).toEqual({
-      type: "section",
-      text: { type: "mrkdwn", text: "a &amp; b &lt;c&gt; &lt;!channel&gt;" },
-    });
+    expect(JSON.stringify(rendered)).not.toContain('"mrkdwn"');
   });
 
-  it("does NOT escape a plain_text surface — a header is literal", () => {
-    // Escaping here is a real defect, not belt-and-braces: `plain_text` does not
-    // parse the entities, so the reader would see `Acme &amp; Co`.
+  it("passes user text through literally — `&`, `<` and `>` are not entities", () => {
+    // Escaping here is a real defect, not belt-and-braces: a literal surface
+    // does not parse the entities, so the reader would see `Acme &amp; Co`.
     const rendered = slackRenderer.render(
-      only({ type: "body", text: "x" }, "Acme & Co <the org>"),
+      only({ type: "body", text: "Acme & Co <the org>" }),
       CONTEXT,
     );
 
-    expect(rendered.blocks[0]).toEqual({
-      type: "header",
-      text: { type: "plain_text", text: "Acme & Co <the org>" },
-    });
+    expect(monospaceText(rendered)).toContain("Acme & Co <the org>");
+    expect(JSON.stringify(rendered)).not.toContain("&amp;");
   });
 
   it("does NOT escape a plain_text surface — a button label is literal", () => {
@@ -350,14 +413,7 @@ describe("slackRenderer", () => {
       CONTEXT,
     );
 
-    expect(rendered.blocks[1]).toMatchObject({
-      elements: [
-        {
-          type: "rich_text_preformatted",
-          elements: [{ type: "text", text: "a&b<c>" }],
-        },
-      ],
-    });
+    expect(monospaceText(rendered)).toContain(">> a&b<c> <<");
   });
 
   it("does NOT escape a rich_text surface — list items are literal", () => {
@@ -384,8 +440,9 @@ describe("slackRenderer", () => {
     const pinned: RenderContext = {
       brand: { name: "Acme", copyrightYear: 1999 },
     };
-    expect(JSON.stringify(slackRenderer.render(CONTENT, pinned))).toContain(
-      "© 1999 Acme",
+
+    expect(monospaceText(slackRenderer.render(CONTENT, pinned))).toContain(
+      "ⓒ 1999 • Acme",
     );
   });
 
@@ -395,10 +452,93 @@ describe("slackRenderer", () => {
       CONTEXT,
     );
 
-    expect(rendered.blocks[1]).toEqual({
-      type: "context",
-      elements: [{ type: "mrkdwn", text: "© 2026 Grace" }],
-    });
+    // The same sign-off email draws, from the same function.
+    expect(monospaceText(rendered)).toContain("ⓒ 2026 • Grace");
+    expect(monospaceText(rendered)).toContain("https://companysemantics.ai");
+  });
+
+  // ===========================================================================
+  // chatUnit segmentation — where the drawing is cut for a native button
+  // ===========================================================================
+
+  function chat(items: ChatUnitItem[]) {
+    return slackRenderer.render(only({ type: "chatUnit", items }, ""), CONTEXT)
+      .blocks;
+  }
+
+  const LINKED: ChatUnitItem = {
+    type: "callToAction",
+    label: "GO",
+    href: "https://example.test/g",
+  };
+  const SAID: ChatUnitItem = { type: "message", role: "user", text: "hi" };
+
+  it("cuts the drawing where a linked CTA breaks out, keeping both halves", () => {
+    expect(chat([SAID, LINKED, SAID]).map((block) => block.type)).toEqual([
+      "rich_text",
+      "actions",
+      "rich_text",
+    ]);
+  });
+
+  it("emits NO empty code box when the unit opens on a button", () => {
+    // Slack draws an empty `rich_text_preformatted` as a visible empty
+    // rectangle, so a zero-line block beside the button is a drawing bug rather
+    // than a tidiness question.
+    expect(chat([LINKED, SAID]).map((block) => block.type)).toEqual([
+      "actions",
+      "rich_text",
+    ]);
+  });
+
+  it("emits NO empty code box when the unit closes on a button", () => {
+    expect(chat([SAID, LINKED]).map((block) => block.type)).toEqual([
+      "rich_text",
+      "actions",
+    ]);
+  });
+
+  it("emits only the button for a unit that is nothing but one", () => {
+    expect(chat([LINKED]).map((block) => block.type)).toEqual(["actions"]);
+  });
+
+  it("coalesces adjacent linked CTAs into ONE actions block", () => {
+    // Two buttons in one `actions` sit side by side, the way a reader expects a
+    // choice to be offered; two `actions` blocks stack them and read as two
+    // unrelated prompts.
+    const blocks = chat([SAID, LINKED, LINKED]);
+
+    expect(blocks.map((block) => block.type)).toEqual(["rich_text", "actions"]);
+    const actions = blocks[1];
+    if (actions.type !== "actions") throw new Error("expected actions");
+    expect(actions.elements).toHaveLength(2);
+  });
+
+  it("keeps a hrefless CTA INSIDE the drawing — the box is the payload", () => {
+    const blocks = chat([SAID, { type: "callToAction", label: "123456" }]);
+
+    expect(blocks.map((block) => block.type)).toEqual(["rich_text"]);
+  });
+
+  // ===========================================================================
+  // Exhaustiveness — the guard that replaced `supports` returning false
+  // ===========================================================================
+
+  it("gives every element type a representation, never a silent nothing", () => {
+    // `supports` is now total-true, so it can no longer be what makes a new
+    // element safe: an unmapped thirteenth would fall through and post a message
+    // with a hole in it — the `chatUnit` bug under a new name, and harder to see
+    // because there would be no `supports` returning false to point at.
+    //
+    // `renderElement` has no `default` arm and ends in `assertNever`, so adding a
+    // variant fails COMPILATION. This is the runtime half: every type that exists
+    // today actually draws something.
+    for (const type of ALL_TYPES) {
+      const element = SPECIMENS[type];
+      const blocks = slackRenderer.render(only(element, ""), CONTEXT).blocks;
+
+      expect(blocks.length, `${type} produced no blocks`).toBeGreaterThan(0);
+    }
   });
 
   it("is pure — same inputs, same output", () => {

package/src/notifications/renderers/slack/blocks.ts

@@ -0,0 +1,149 @@
+/**
+ * Slack's surfaces, and the bridge from `../ascii` onto them.
+ *
+ * **This channel no longer has an mrkdwn surface, and that is a safety property
+ * rather than a coincidence.** Escaping used to be a rule someone had to apply
+ * correctly per call site: `mrkdwn` parses `&`/`<`/`>` and must be escaped,
+ * while `plain_text` and `rich_text` are literal and must NOT be — escaping one
+ * of those is a defect that shows the reader `Acme &amp; Co`. Both mistakes were
+ * possible and neither was a type error, because both surfaces are `string`.
+ *
+ * Moving the body to `rich_text_preformatted` retired the last mrkdwn emitter.
+ * Every user-controlled string now reaches a LITERAL surface — a `plain_text`
+ * button label, or `rich_text` for everything else — so there is nothing left to
+ * escape and no call site that could get it wrong. `escapeMrkdwn`, `mrkdwn`,
+ * `section` and `context` were deleted rather than kept "in case": a helper that
+ * exists is a helper someone will reach for, and reaching for that one is now
+ * always the bug.
+ */
+
+import type {
+  KnownBlock,
+  PlainTextElement,
+  RichTextBlock,
+  RichTextLink,
+  RichTextText,
+} from "@slack/types";
+
+import type { MonospaceLine } from "../ascii";
+
+/** Elements per `actions` block. Adjacent CTAs coalesce up to this, then split. */
+export const ACTIONS_MAX_ELEMENTS = 25;
+
+/** A literal text object. Never escaped — see `escapeMrkdwn`. */
+export function plainText(text: string): PlainTextElement {
+  return { type: "plain_text", text };
+}
+
+/** Split into chunks of at most `size`. Slack caps several collections. */
+export function chunk<T>(items: T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let index = 0; index < items.length; index += size) {
+    chunks.push(items.slice(index, index + size));
+  }
+  return chunks;
+}
+
+/**
+ * A monospace drawing as a Slack code block.
+ *
+ * This is where `../ascii`'s runs earn their existence. `rich_text_preformatted`
+ * takes `(RichTextText | RichTextLink)[]`, so a `link` run survives as a LINK
+ * rather than being dissolved into characters. Slack decides what it does with
+ * one inside a code block — we have not verified that it renders as an anchor —
+ * but the destination is legible either way, and passing the structure through
+ * is strictly better than throwing it away here.
+ *
+ * Lines are rejoined with `\n` into one run-stream because a preformatted block
+ * has no line elements of its own; the newlines ARE the layout.
+ *
+ * Returns no block for an empty drawing. An empty `rich_text` is not neutral —
+ * Slack renders it as a stray empty code box, which is how a break-out in
+ * `./chat.ts` would otherwise leave a visible hole in the message.
+ */
+export function preformatted(lines: MonospaceLine[]): RichTextBlock[] {
+  const elements: (RichTextText | RichTextLink)[] = [];
+
+  lines.forEach((line, index) => {
+    if (index > 0) elements.push({ type: "text", text: "\n" });
+    for (const run of line) {
+      elements.push(
+        run.type === "link"
+          ? { type: "link", text: run.text, url: run.href }
+          : { type: "text", text: run.text },
+      );
+    }
+  });
+
+  if (elements.length === 0) return [];
+  return [
+    {
+      type: "rich_text",
+      elements: [{ type: "rich_text_preformatted", elements }],
+    },
+  ];
+}
+
+/**
+ * Merge neighbouring monospace blocks into one.
+ *
+ * Slack draws every `rich_text_preformatted` as its own bordered box. Rendering
+ * each element independently therefore turns a five-element notification into
+ * five stacked grey rectangles — which is not what the email looks like and not
+ * what anyone means by a message. Email's `text/plain` body is ONE continuous
+ * surface with blank lines between its elements, so Slack's is too.
+ *
+ * The run is broken only by a block that genuinely interrupts it: a table, a
+ * button, a divider, an image, a list. Those are the native primitives the
+ * monospace rule already exempts, and a break there is a real change of
+ * material rather than an artefact of how many elements happened to compose.
+ *
+ * Blocks are joined with a blank line, matching `textShell`'s `normal` spacing.
+ */
+export function coalescePreformatted(blocks: KnownBlock[]): KnownBlock[] {
+  const merged: KnownBlock[] = [];
+
+  for (const block of blocks) {
+    const previous = merged.at(-1);
+    const runs = onlyPreformatted(block);
+    const previousRuns = previous ? onlyPreformatted(previous) : undefined;
+
+    if (runs && previousRuns) {
+      merged[merged.length - 1] = {
+        type: "rich_text",
+        elements: [
+          {
+            type: "rich_text_preformatted",
+            elements: [
+              ...previousRuns,
+              { type: "text", text: "\n\n" },
+              ...runs,
+            ],
+          },
+        ],
+      };
+      continue;
+    }
+    merged.push(block);
+  }
+
+  return merged;
+}
+
+/**
+ * The runs of a block that is nothing but one preformatted element, else
+ * undefined.
+ *
+ * A `rich_text` holding a LIST is deliberately not a match: a list is Slack
+ * drawing its own markers and indentation, and folding it into a code box would
+ * throw that away to gain a merge nobody asked for.
+ */
+function onlyPreformatted(
+  block: KnownBlock,
+): (RichTextText | RichTextLink)[] | undefined {
+  if (block.type !== "rich_text" || block.elements.length !== 1)
+    return undefined;
+  const [element] = block.elements;
+  if (element.type !== "rich_text_preformatted") return undefined;
+  return element.elements;
+}