@company-semantics/contracts 35.1.0 → 36.0.0

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

@@ -1,12 +1,21 @@
 /**
- * The Slack channel is a placeholder, so what is pinned here is the contract a
- * placeholder still owes — `supports` total and in agreement with `render`,
- * `render` pure and reading the brand and year from the context, every element
- * type rendering without throwing — and NOT the Block Kit wording, which is
- * invented and expected to change when a kind is actually posted to Slack.
+ * What this pins, now that the blocks are Slack's own vocabulary rather than a
+ * hand-written approximation (ADR-CONTRACTS-090):
  *
- * The mrkdwn escaping IS pinned. It is the one thing here that would be a real
- * defect rather than a fidelity gap.
+ * - the contract every renderer owes — `supports` total and in agreement with
+ *   `render`, `render` pure and reading the brand and year from the context,
+ *   every element type rendering without throwing;
+ * - the ESCAPING RULE, both halves. mrkdwn escapes; `plain_text` and `rich_text`
+ *   must not. This is the defect the new literal surfaces made possible, and the
+ *   compiler cannot catch it — both surfaces are `string`.
+ * - the SHAPE — that each element reaches the Block Kit primitive it claims to.
+ *   `@slack/types` proves a block is well-formed; only a test proves a `list`
+ *   became a `rich_text_list` rather than a section full of bullet characters.
+ * - Slack's documented LIMITS, which are rejections at the API rather than
+ *   fidelity gaps: header ≤150, section fields ≤10.
+ *
+ * Still NOT pinned: the wording. It is invented rather than relocated from a
+ * shipped Slack app, and it is expected to change when a kind is actually posted.
  */
 
 import { describe, expect, it } from "vitest";
@@ -67,6 +76,17 @@ const ALL_TYPES: NotificationElementType[] = [
   "heroImage",
 ];
 
+/** One content carrying one element — the shape assertions read better alone. */
+function only(
+  element: NotificationContent["sections"][number]["elements"][number],
+  title = "Untitled",
+): NotificationContent {
+  return {
+    metadata: { kind: "org.invite", title },
+    sections: [{ elements: [element] }],
+  };
+}
+
 describe("slackRenderer", () => {
   it("declares a stable channel id", () => {
     expect(slackRenderer.id).toBe("slack");
@@ -92,22 +112,22 @@ describe("slackRenderer", () => {
     const rendered = slackRenderer.render(CONTENT, CONTEXT);
 
     expect(JSON.stringify(rendered)).not.toContain("Hello?");
-    // Eleven admitted elements, each yielding exactly one block here.
-    expect(rendered.blocks).toHaveLength(11);
   });
 
   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.
+    // metadata.title — the same field email spends as its subject, and this
+    // channel ALSO leads with as a header.
     expect(rendered.text).toBe("Join Acme");
     expect(rendered.blocks.map((block) => block.type)).toEqual([
+      "header",
       "image",
       "section",
       "section",
       "section",
-      "section",
+      "rich_text",
       "divider",
       "section",
       "context",
@@ -117,8 +137,127 @@ 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("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.
+    const rendered = slackRenderer.render(CONTENT, CONTEXT);
+
+    expect(rendered.text).toBe("Join Acme");
+    expect(JSON.stringify(rendered.blocks[0])).toContain("Join Acme");
+  });
+
+  it("truncates a header at Slack's documented 150 characters", () => {
+    const rendered = slackRenderer.render(
+      only({ type: "body", text: "x" }, "A".repeat(200)),
+      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);
+  });
+
+  it("emits no header when the title is empty — not an empty block", () => {
+    const rendered = slackRenderer.render(
+      only({ type: "body", text: "x" }, "   "),
+      CONTEXT,
+    );
+
+    expect(rendered.blocks.map((block) => block.type)).toEqual(["section"]);
+  });
+
+  // ===========================================================================
+  // Shape — each element reaches its real Block Kit primitive
+  // ===========================================================================
+
+  it("renders a keyValueTable as section fields, Slack's two-column device", () => {
+    const rendered = slackRenderer.render(
+      only({
+        type: "keyValueTable",
+        rows: [
+          { label: "Status", value: "Valid" },
+          { label: "Expires in", value: "10 minutes" },
+        ],
+      }),
+      CONTEXT,
+    );
+
+    expect(rendered.blocks[1]).toEqual({
+      type: "section",
+      fields: [
+        { type: "mrkdwn", text: "*Status*\nValid" },
+        { type: "mrkdwn", text: "*Expires in*\n10 minutes" },
+      ],
+    });
+  });
+
+  it("chunks a keyValueTable at ten fields — Slack rejects an eleventh", () => {
+    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");
+
+    expect(blocks.map((block) => block.fields?.length)).toEqual([10, 10, 3]);
+  });
+
+  it("renders a list as a real rich_text_list, not bullet characters", () => {
+    const rendered = slackRenderer.render(
+      only({ type: "list", items: ["Read", "Write"] }),
+      CONTEXT,
+    );
+
+    expect(rendered.blocks[1]).toEqual({
+      type: "rich_text",
+      elements: [
+        {
+          type: "rich_text_list",
+          style: "bullet",
+          elements: [
+            {
+              type: "rich_text_section",
+              elements: [{ type: "text", text: "Read" }],
+            },
+            {
+              type: "rich_text_section",
+              elements: [{ type: "text", text: "Write" }],
+            },
+          ],
+        },
+      ],
+    });
+  });
+
+  it("maps an ordered list onto Slack's own ordered style", () => {
+    const rendered = slackRenderer.render(
+      only({ type: "list", items: ["First"], ordered: true }),
+      CONTEXT,
+    );
+
+    expect(rendered.blocks[1]).toMatchObject({
+      elements: [{ type: "rich_text_list", style: "ordered" }],
+    });
+  });
+
   it("takes the hero image the SMS channel has no surface for", () => {
-    // The two stubs exist to differ: same content, no channel tags on it, and
+    // The channels exist to differ: same content, no channel tags on it, and
     // each channel keeps what it can depict.
     expect(slackRenderer.render(CONTENT, CONTEXT).blocks).toContainEqual({
       type: "image",
@@ -140,36 +279,106 @@ describe("slackRenderer", () => {
     });
   });
 
-  it("renders a call to action without an href as text, not a button", () => {
+  it("renders a call to action without an href as a code block, 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.
+    // 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.
     const otp: NotificationContent = {
       metadata: { kind: "auth.otp", title: "Your code" },
       sections: [{ elements: [{ type: "callToAction", label: "123456" }] }],
     };
-    expect(slackRenderer.render(otp, CONTEXT).blocks).toEqual([
-      { type: "section", text: { type: "mrkdwn", text: "*123456*" } },
-    ]);
+
+    expect(slackRenderer.render(otp, CONTEXT).blocks[1]).toEqual({
+      type: "rich_text",
+      elements: [
+        {
+          type: "rich_text_preformatted",
+          elements: [{ type: "text", text: "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,
+    );
+
+    expect(rendered.blocks[1]).toEqual({
+      type: "section",
+      text: { type: "mrkdwn", text: "a &amp; b &lt;c&gt; &lt;!channel&gt;" },
+    });
+  });
+
+  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`.
+    const rendered = slackRenderer.render(
+      only({ type: "body", text: "x" }, "Acme & Co <the org>"),
+      CONTEXT,
+    );
+
+    expect(rendered.blocks[0]).toEqual({
+      type: "header",
+      text: { type: "plain_text", text: "Acme & Co <the org>" },
+    });
+  });
+
+  it("does NOT escape a plain_text surface — a button label is literal", () => {
+    const rendered = slackRenderer.render(
+      only({
+        type: "callToAction",
+        label: "Join Acme & Co",
+        href: "https://e.test",
+      }),
+      CONTEXT,
+    );
+
+    expect(rendered.blocks[1]).toMatchObject({
+      elements: [{ text: { type: "plain_text", text: "Join Acme & Co" } }],
+    });
   });
 
-  it("escapes Slack's reserved characters in user-controlled fields", () => {
-    const hostile: NotificationContent = {
-      metadata: { kind: "org.invite", title: "Join Acme" },
-      sections: [
-        { elements: [{ type: "body", text: "a & b <c> <!channel>" }] },
+  it("does NOT escape a rich_text surface — the OTP is literal", () => {
+    const rendered = slackRenderer.render(
+      only({ type: "callToAction", label: "a&b<c>" }),
+      CONTEXT,
+    );
+
+    expect(rendered.blocks[1]).toMatchObject({
+      elements: [
+        {
+          type: "rich_text_preformatted",
+          elements: [{ type: "text", text: "a&b<c>" }],
+        },
       ],
-    };
-    expect(slackRenderer.render(hostile, CONTEXT).blocks).toEqual([
-      {
-        type: "section",
-        text: {
-          type: "mrkdwn",
-          text: "a &amp; b &lt;c&gt; &lt;!channel&gt;",
+    });
+  });
+
+  it("does NOT escape a rich_text surface — list items are literal", () => {
+    const rendered = slackRenderer.render(
+      only({ type: "list", items: ["a & b"] }),
+      CONTEXT,
+    );
+
+    expect(rendered.blocks[1]).toMatchObject({
+      elements: [
+        {
+          elements: [{ elements: [{ type: "text", text: "a & b" }] }],
         },
-      },
-    ]);
+      ],
+    });
   });
 
+  // ===========================================================================
+  // The seam properties
+  // ===========================================================================
+
   it("reads the brand and year from context, never from a clock", () => {
     // No fake timer in this file: swapping the context moves the copyright line.
     const pinned: RenderContext = {
@@ -181,16 +390,15 @@ describe("slackRenderer", () => {
   });
 
   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(slackRenderer.render(onBehalf, CONTEXT).blocks).toEqual([
-      {
-        type: "context",
-        elements: [{ type: "mrkdwn", text: "© 2026 Grace" }],
-      },
-    ]);
+    const rendered = slackRenderer.render(
+      only({ type: "signature", signer: "Grace" }),
+      CONTEXT,
+    );
+
+    expect(rendered.blocks[1]).toEqual({
+      type: "context",
+      elements: [{ type: "mrkdwn", text: "© 2026 Grace" }],
+    });
   });
 
   it("is pure — same inputs, same output", () => {