@company-semantics/contracts 35.1.0 → 37.0.0

package/src/notifications/renderers/slack/README.md

@@ -2,8 +2,8 @@
 
 ## Purpose
 
-The Slack channel (ADR-CONTRACTS-086) — `slackRenderer: Renderer<SlackMessage>`. A
-**non-functional placeholder**.
+The Slack channel (ADR-CONTRACTS-086, ADR-CONTRACTS-090) —
+`slackRenderer: Renderer<SlackMessage>`.
 
 Where `../sms` proves the content model survives the poorest channel, this proves
 the other edge: a channel whose output is a tree of typed blocks — neither a
@@ -12,23 +12,52 @@ record, a string and a different record, which is `../../renderer.ts`'s "each
 renderer returns its natural type" held by real modules rather than asserted about
 the type itself.
 
-The whole channel is one `index.ts` — the Block Kit subset, the escaping, and the
-renderer. `../email` splits across seven modules because it carries real markup; a
-stub that sprawls is a stub pretending.
+The whole channel is one `index.ts` — the surfaces, the escaping, and the
+renderer. `../email` splits across seven modules because it carries real markup;
+this one composes blocks and has no markup to own.
 
-## What "placeholder" means here
+## The blocks are Slack's, not ours
 
-- **It does not send.** No token, no channel id, no `chat.postMessage`. A renderer
-  renders; delivery and the decision to deliver are the backend's.
-- **It is low fidelity.** `SlackBlock` is a minimal, hand-written subset of Block
-  Kit — enough to carry every element the channel admits, and no more. It is not
-  the Slack API's types and is not generated from them. The wording is invented
-  rather than relocated: there is no golden here, unlike `../email`.
+`SlackMessage.blocks` is `KnownBlock[]` from **`@slack/types`** — the published
+type package behind `node-slack-sdk`, so it is the same union Slack's API
+validates against. This channel used to hand-write a five-block approximation;
+ADR-CONTRACTS-090 retires it. A renderer whose output type is invented can drift
+from the wire format silently and nothing in this package would notice — the
+compiler is the only thing that can, and only if the types are theirs.
+
+`index.ts` re-exports the block types it uses, so a consumer can name them without
+taking its own dependency on `@slack/types`. Widen that list rather than
+redeclaring a shape.
 
 The field names are snake_case (`image_url`, `alt_text`) because Block Kit is a
 wire format and those are its names. That is deliberate, not a lapse in the
 repo's camelCase convention.
 
+## What is still non-functional
+
+- **It does not send.** No token, no channel id, no `chat.postMessage`. A renderer
+  renders; delivery and the decision to deliver are the backend's —
+  `SlackChannelDelivery` throws `ChannelNotImplementedError` by design.
+- **The copy is invented**, not relocated from a shipped Slack app. There is no
+  golden here the way `../email` has one. The SHAPE is legitimate Block Kit and
+  `__tests__/index.test.ts` pins it; the WORDING is expected to change when a kind
+  is actually posted to Slack.
+
+## Element → block
+
+| Element                           | Block                                                      |
+| --------------------------------- | ---------------------------------------------------------- |
+| `metadata.title`                  | `header` (+ the `text` fallback)                           |
+| `greeting`, `body`, `warning`     | `section` (mrkdwn)                                         |
+| `keyValueTable`                   | `section.fields` — Slack's two-column facts, chunked at 10 |
+| `callToAction` **with** `href`    | `actions` + `button`                                       |
+| `callToAction` **without** `href` | `rich_text` › `rich_text_preformatted`                     |
+| `list`                            | `rich_text` › `rich_text_list` (`bullet` / `ordered`)      |
+| `divider`                         | `divider`                                                  |
+| `metadata`, `notice`, `signature` | `context`                                                  |
+| `heroImage`                       | `image`                                                    |
+| `chatUnit`                        | _declined_                                                 |
+
 ## The one decline
 
 `supports` answers `false` for `chatUnit` alone. Block Kit has no vocabulary for
@@ -37,9 +66,9 @@ attribution that IS the meaning — which the content model names as the reason
 decline a whole element rather than approximate it.
 
 Everything else Slack genuinely depicts, **including the `heroImage` that `../sms`
-has no surface for**. That difference is the point of shipping two stubs rather
-than one: same `NotificationContent`, no channel tags on it, three channels of
-differing capability each keeping what they can show.
+has no surface for**. That difference is the point of shipping three channels
+rather than one: same `NotificationContent`, no channel tags on it, three channels
+of differing capability each keeping what they can show.
 
 `metadata` and `notice` become `context` blocks — Slack's own device for
 de-emphasised small print, which is exactly what `MetadataElement` exists to be.
@@ -52,20 +81,32 @@ de-emphasised small print, which is exactly what `MetadataElement` exists to be.
   nowhere to hide.
 - `supports` is total over `NotificationElementType` and AGREES with `render`:
   `chatUnit` is omitted, never approximated and never thrown on.
-- Every user-controlled string reaching an mrkdwn surface passes through
-  `escapeMrkdwn` first — the same rule `../email` applies with `escapeHtml`. This
-  is the one thing in a low-fidelity stub that would be a real defect rather than
-  a fidelity gap, so `__tests__/index.test.ts` pins it.
+- **Escaping follows the SURFACE, not the string.** Every user-controlled string
+  reaching an **mrkdwn** surface passes through `escapeMrkdwn` — the same rule
+  `../email` applies with `escapeHtml`. But `plain_text` (header, button label)
+  and `rich_text` (the OTP code, list items) are **literal**: escaping them is a
+  DEFECT, because those surfaces do not parse the entities and the reader sees
+  `Acme &amp; Co`. The old subset had no literal surface beyond a button label, so
+  the distinction only became load-bearing with `header` and `rich_text`. The
+  compiler cannot help — both surfaces are `string` — so
+  `__tests__/index.test.ts` pins both halves.
+- Slack's documented LIMITS are enforced here, not left to the API to reject: a
+  header truncates at 150 characters, `section.fields` chunks at 10. These are
+  400s from `chat.postMessage`, not fidelity gaps.
 - `renderElement` switches over all TWELVE element types, not the eleven
   `supports` admits. The declined arm is unreachable; writing it out is what makes
   the compiler prove the two lists agree. Do not collapse it into a `default` —
   that would silently swallow a thirteenth member of the union.
-- A `callToAction` with no `href` becomes text, never a button. `href` absent
-  means the label IS the payload (an OTP code); a button with no destination is a
-  lie about what the notification is asking for.
-- `SlackMessage.text` is `metadata.title` — the fallback Slack shows where blocks
-  cannot render. The same content-level fact email spends as its subject, which is
-  why it lives on the content rather than in a channel's registry.
+- A `callToAction` with no `href` becomes a code block, never a button. `href`
+  absent means the label IS the payload (an OTP code); a button with no
+  destination is a lie about what the notification is asking for.
+- `metadata.title` is spent TWICE and neither use replaces the other:
+  `SlackMessage.text` is the fallback Slack shows where blocks cannot render (a
+  push notification, a screen reader), and the `header` block is what the message
+  looks like. It is the same content-level fact email spends as its subject —
+  three channel uses of one fact, which is why it lives on the content rather than
+  in a channel's registry. Only the block carries the 150-char limit; the fallback
+  is untruncated.
 - Nothing here reads `metadata.kind`. A renderer that special-cases a kind has
   lost the model; the fix for a missing fact is upstream in `compose`.
 - This channel is unreachable from `../../render.ts`'s `renderEmail` and touches

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", () => {