@oneuptime/common 12.0.33 → 13.0.0

package/Tests/Server/Types/Database/QueryUtilIncludesAnyOfGroups.test.ts

@@ -0,0 +1,169 @@
+import Monitor from "../../../../Models/DatabaseModels/Monitor";
+import QueryUtil from "../../../../Server/Types/Database/QueryUtil";
+import IncludesAnyOfGroups from "../../../../Types/BaseDatabase/IncludesAnyOfGroups";
+import Includes from "../../../../Types/BaseDatabase/Includes";
+import BadDataException from "../../../../Types/Exception/BadDataException";
+import ObjectID from "../../../../Types/ObjectID";
+import { FindOperator, In } from "typeorm";
+
+const relation: {
+  joinTableName: string;
+  ownerColumnName: string;
+  relationColumnName: string;
+} = {
+  joinTableName: "MonitorLabel",
+  ownerColumnName: "monitorId",
+  relationColumnName: "labelId",
+};
+
+describe("QueryUtil — grouped relation membership", () => {
+  beforeEach(() => {
+    jest
+      .spyOn(QueryUtil, "getManyToManyRelationMetadata")
+      .mockReturnValue(relation);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  test("ANDs independent ANY groups without joining the relation into the row set", () => {
+    const result: Record<string, any> = QueryUtil.serializeQuery(Monitor, {
+      labels: new IncludesAnyOfGroups([
+        ["network", "router"],
+        ["0660", "0661"],
+      ]),
+    });
+    expect(result["labels"]).toBeUndefined();
+    const filter: FindOperator<FindOperator<unknown>[]> = result["_id"];
+    expect(filter.type).toBe("and");
+    expect(filter.value).toHaveLength(2);
+    expect(
+      filter.value.map((child: FindOperator<unknown>) => {
+        return Object.values(child.objectLiteralParameters || {});
+      }),
+    ).toEqual([[["network", "router"]], [["0660", "0661"]]]);
+    for (const child of filter.value) {
+      expect(child.getSql?.("Monitor._id")).toContain(
+        'Monitor._id IN (SELECT "MonitorLabel"."monitorId"',
+      );
+    }
+    const parameterNames: Array<string> = filter.value.flatMap(
+      (child: FindOperator<unknown>) => {
+        return Object.keys(child.objectLiteralParameters || {});
+      },
+    );
+    expect(new Set(parameterNames).size).toBe(2);
+  });
+
+  test("an empty group contributes a false condition", () => {
+    const result: Record<string, any> = QueryUtil.serializeQuery(Monitor, {
+      labels: new IncludesAnyOfGroups([["network"], []]),
+    });
+    expect(result["_id"].value[1].getSql("Monitor._id")).toBe("TRUE = FALSE");
+  });
+
+  test.each(["before", "after"])(
+    "preserves an ObjectID filter placed %s the relation key",
+    (position: string) => {
+      const id: ObjectID = ObjectID.generate();
+      const labels: IncludesAnyOfGroups = new IncludesAnyOfGroups([
+        ["network"],
+        ["0660"],
+      ]);
+      const query: Record<string, unknown> =
+        position === "before" ? { _id: id, labels } : { labels, _id: id };
+      const result: Record<string, any> = QueryUtil.serializeQuery(
+        Monitor,
+        query as any,
+      );
+      expect(result["_id"].type).toBe("and");
+      expect(result["_id"].value).toHaveLength(3);
+      expect(
+        Object.values(result["_id"].value[0].objectLiteralParameters),
+      ).toEqual([id.toString()]);
+    },
+  );
+
+  test.each(["before", "after"])(
+    "preserves an Includes id filter placed %s the relation key",
+    (position: string) => {
+      const ids: Array<string> = [
+        ObjectID.generate().toString(),
+        ObjectID.generate().toString(),
+      ];
+      const labels: IncludesAnyOfGroups = new IncludesAnyOfGroups([
+        ["network"],
+        ["0660"],
+      ]);
+      const query: Record<string, unknown> =
+        position === "before"
+          ? { _id: new Includes(ids), labels }
+          : { labels, _id: new Includes(ids) };
+      const result: Record<string, any> = QueryUtil.serializeQuery(
+        Monitor,
+        query as any,
+      );
+      expect(result["_id"].value[0].type).toBe("raw");
+      expect(
+        Object.values(result["_id"].value[0].objectLiteralParameters),
+      ).toEqual([ids]);
+    },
+  );
+
+  test("preserves existing string and TypeORM id conditions", () => {
+    const id: string = ObjectID.generate().toString();
+    const stringResult: Record<string, any> = QueryUtil.serializeQuery(
+      Monitor,
+      {
+        _id: id,
+        labels: new IncludesAnyOfGroups([["network"], ["0660"]]),
+      },
+    );
+    expect(
+      Object.values(stringResult["_id"].value[0].objectLiteralParameters),
+    ).toEqual([id]);
+    const idFilter: FindOperator<string> = In([id]);
+    const operatorResult: Record<string, any> = QueryUtil.serializeQuery(
+      Monitor,
+      {
+        _id: idFilter as any,
+        labels: new IncludesAnyOfGroups([["network"], ["0660"]]),
+      },
+    );
+    expect(operatorResult["_id"].value[0]).toBe(idFilter);
+  });
+
+  test("retains the project and other widget conditions", () => {
+    const projectId: ObjectID = ObjectID.generate();
+    const result: Record<string, any> = QueryUtil.serializeQuery(Monitor, {
+      projectId,
+      disableActiveMonitoring: false,
+      labels: new IncludesAnyOfGroups([["network"], ["0660"]]),
+    });
+    expect(Object.values(result["projectId"].objectLiteralParameters)).toEqual([
+      projectId.toString(),
+    ]);
+    expect(result["disableActiveMonitoring"]).toBe(false);
+  });
+
+  test.each(["name", "customFields", "project", "missingColumn"])(
+    "rejects the operator on the unsupported %s column",
+    (column: string) => {
+      expect(() => {
+        return QueryUtil.serializeQuery(Monitor, {
+          [column]: new IncludesAnyOfGroups([["network"]]),
+        });
+      }).toThrow(BadDataException);
+    },
+  );
+
+  test("fails clearly when the many-to-many relation cannot be resolved", () => {
+    jest.mocked(QueryUtil.getManyToManyRelationMetadata).mockReturnValue(null);
+    expect(() => {
+      return QueryUtil.serializeQuery(Monitor, {
+        labels: new IncludesAnyOfGroups([["network"], ["0660"]]),
+      });
+    }).toThrow("available many-to-many relation metadata");
+  });
+});

package/Tests/Server/Types/Database/QueryUtilIncludesAnyOfGroupsPostgres.test.ts

@@ -0,0 +1,297 @@
+import Entities from "../../../../Models/DatabaseModels/Index";
+import Monitor from "../../../../Models/DatabaseModels/Monitor";
+import PostgresAppInstance from "../../../../Server/Infrastructure/PostgresDatabase";
+import Query from "../../../../Server/Types/Database/Query";
+import QueryUtil from "../../../../Server/Types/Database/QueryUtil";
+import Includes from "../../../../Types/BaseDatabase/Includes";
+import IncludesAnyOfGroups from "../../../../Types/BaseDatabase/IncludesAnyOfGroups";
+import { JSONObject } from "../../../../Types/JSON";
+import JSONFunctions from "../../../../Types/JSONFunctions";
+import ObjectID from "../../../../Types/ObjectID";
+import { DataSource, FindOptionsWhere } from "typeorm";
+
+/*
+ * Run with RUN_POSTGRES_DASHBOARD_LABEL_TESTS=true and config.env loaded.
+ * All rows and cloned production tables live in a unique temporary schema.
+ * Uses the local development database on port 5400 unless overridden below.
+ */
+const describePostgres: typeof describe =
+  process.env["RUN_POSTGRES_DASHBOARD_LABEL_TESTS"] === "true"
+    ? describe
+    : describe.skip;
+
+describePostgres("dashboard label groups against Postgres", () => {
+  const schema: string = `dashboard_labels_${ObjectID.generate().toString().replace(/-/g, "")}`;
+  const projectId: string = ObjectID.generate().toString();
+  const otherProjectId: string = ObjectID.generate().toString();
+  const statusId: string = ObjectID.generate().toString();
+  const network: string = ObjectID.generate().toString();
+  const router: string = ObjectID.generate().toString();
+  const unit0660: string = ObjectID.generate().toString();
+  const unit0661: string = ObjectID.generate().toString();
+  const monitorIds: Record<string, string> = {};
+  let database: DataSource;
+
+  beforeAll(async () => {
+    database = new DataSource({
+      type: "postgres",
+      host: process.env["DASHBOARD_LABEL_TEST_DATABASE_HOST"] || "localhost",
+      port: Number(process.env["DASHBOARD_LABEL_TEST_DATABASE_PORT"] || "5400"),
+      username: process.env["DATABASE_USERNAME"] || "postgres",
+      password: process.env["DATABASE_PASSWORD"] || "password",
+      database: process.env["DATABASE_NAME"] || "oneuptimedb",
+      entities: Entities,
+      schema,
+      synchronize: false,
+      extra: { options: `-c search_path=${schema},public` },
+    });
+    await database.initialize();
+    await database.query(`CREATE SCHEMA "${schema}"`);
+    for (const table of ["Monitor", "Label", "MonitorLabel"]) {
+      await database.query(
+        `CREATE TABLE "${schema}"."${table}" (LIKE public."${table}" INCLUDING ALL)`,
+      );
+    }
+    /*
+     * LIKE does not copy foreign keys. Retain the production relation's
+     * cascade behavior so deleting a label exercises the real join lifecycle.
+     */
+    await database.query(
+      `ALTER TABLE "${schema}"."MonitorLabel" ADD FOREIGN KEY ("labelId") REFERENCES "${schema}"."Label" ("_id") ON UPDATE CASCADE ON DELETE CASCADE`,
+    );
+    await database.query(
+      `ALTER TABLE "${schema}"."MonitorLabel" ADD FOREIGN KEY ("monitorId") REFERENCES "${schema}"."Monitor" ("_id") ON UPDATE CASCADE ON DELETE CASCADE`,
+    );
+    expect(
+      (await database.query("SELECT current_schema()"))[0].current_schema,
+    ).toBe(schema);
+    jest.spyOn(PostgresAppInstance, "isConnected").mockReturnValue(true);
+    jest.spyOn(PostgresAppInstance, "getDataSource").mockReturnValue(database);
+
+    for (const [id, name] of [
+      [network, "network"],
+      [router, "router"],
+      [unit0660, "0660"],
+      [unit0661, "0661"],
+    ]) {
+      await database.query(
+        `INSERT INTO "Label" ("_id", "version", "projectId", "name", "slug", "color") VALUES ($1, 1, $2, $3, $3, '#000000')`,
+        [id, projectId, name],
+      );
+    }
+    await seedMonitor("network-0660", [network, unit0660]);
+    await seedMonitor("network-0661", [network, unit0661]);
+    await seedMonitor("router-0661", [router, unit0661]);
+    await seedMonitor("both-units", [network, router, unit0660, unit0661]);
+    await seedMonitor("network-no-unit", [network]);
+    await seedMonitor("unit-only", [unit0660]);
+    await seedMonitor("no-labels", []);
+    await seedMonitor("other-project", [network, unit0660], otherProjectId);
+  });
+
+  afterAll(async () => {
+    jest.restoreAllMocks();
+    if (database?.isInitialized) {
+      await database.query(`DROP SCHEMA IF EXISTS "${schema}" CASCADE`);
+      await database.destroy();
+    }
+  });
+
+  async function seedMonitor(
+    name: string,
+    labels: Array<string>,
+    monitorProjectId: string = projectId,
+  ): Promise<void> {
+    const id: string = ObjectID.generate().toString();
+    monitorIds[name] = id;
+    await database.query(
+      `INSERT INTO "Monitor" ("_id", "version", "projectId", "name", "slug", "monitorType", "currentMonitorStatusId") VALUES ($1, 1, $2, $3, $3, 'Manual', $4)`,
+      [id, monitorProjectId, name, statusId],
+    );
+    for (const labelId of labels) {
+      await database.query(
+        `INSERT INTO "MonitorLabel" ("monitorId", "labelId") VALUES ($1, $2)`,
+        [id, labelId],
+      );
+    }
+  }
+
+  async function findNames(query: Query<Monitor>): Promise<Array<string>> {
+    const serialized: Query<Monitor> = QueryUtil.serializeQuery(Monitor, {
+      projectId: new ObjectID(projectId),
+      ...query,
+    });
+    const monitors: Array<Monitor> = await database
+      .getRepository(Monitor)
+      .find({
+        select: { _id: true, name: true },
+        where: serialized as unknown as FindOptionsWhere<Monitor>,
+        order: { name: "ASC" },
+      });
+    return monitors.map((monitor: Monitor) => {
+      return monitor.name!;
+    });
+  }
+
+  test("requires a category label and the selected unit on the same monitor", async () => {
+    expect(
+      await findNames({
+        labels: new IncludesAnyOfGroups([[network, router], [unit0660]]),
+      }),
+    ).toEqual(["both-units", "network-0660"]);
+  });
+
+  test("switching the selected unit changes the actual matching rows", async () => {
+    expect(
+      await findNames({
+        labels: new IncludesAnyOfGroups([[network, router], [unit0661]]),
+      }),
+    ).toEqual(["both-units", "network-0661", "router-0661"]);
+  });
+
+  test("matches any selected unit without duplicating monitors carrying both", async () => {
+    expect(
+      await findNames({
+        labels: new IncludesAnyOfGroups([[network], [unit0660, unit0661]]),
+      }),
+    ).toEqual(["both-units", "network-0660", "network-0661"]);
+  });
+
+  test("three independent conditions remain conjunctive", async () => {
+    expect(
+      await findNames({
+        labels: new IncludesAnyOfGroups([
+          [network],
+          [router],
+          [unit0660, unit0661],
+        ]),
+      }),
+    ).toEqual(["both-units"]);
+  });
+
+  test("All can omit just the unit condition while retaining the fixed labels", async () => {
+    expect(
+      await findNames({ labels: new Includes([network, router]) }),
+    ).toEqual([
+      "both-units",
+      "network-0660",
+      "network-0661",
+      "network-no-unit",
+      "router-0661",
+    ]);
+  });
+
+  test("empty and missing-label groups return no monitors", async () => {
+    expect(
+      await findNames({ labels: new IncludesAnyOfGroups([[network], []]) }),
+    ).toEqual([]);
+    expect(
+      await findNames({
+        labels: new IncludesAnyOfGroups([
+          [network],
+          [ObjectID.generate().toString()],
+        ]),
+      }),
+    ).toEqual([]);
+  });
+
+  test.each(["before", "after"])(
+    "retains the explicit monitor id %s labels",
+    async (position: string) => {
+      const id: ObjectID = new ObjectID(monitorIds["network-0660"]!);
+      const labels: IncludesAnyOfGroups = new IncludesAnyOfGroups([
+        [network],
+        [unit0660],
+      ]);
+      expect(
+        await findNames(
+          position === "before" ? { _id: id, labels } : { labels, _id: id },
+        ),
+      ).toEqual(["network-0660"]);
+      expect(
+        await findNames({
+          labels: new IncludesAnyOfGroups([[network], [unit0661]]),
+          _id: id,
+        }),
+      ).toEqual([]);
+    },
+  );
+
+  test("retains other widget filters", async () => {
+    expect(
+      await findNames({
+        currentMonitorStatusId: new ObjectID(ObjectID.generate().toString()),
+        labels: new IncludesAnyOfGroups([[network], [unit0660]]),
+      }),
+    ).toEqual([]);
+  });
+
+  test("API serialization keeps the same database behavior", async () => {
+    const payload: JSONObject = JSON.parse(
+      JSON.stringify(
+        JSONFunctions.serialize({
+          labels: new IncludesAnyOfGroups([[network, router], [unit0661]]),
+        }),
+      ),
+    );
+    expect(
+      await findNames(JSONFunctions.deserialize(payload) as Query<Monitor>),
+    ).toEqual(["both-units", "network-0661", "router-0661"]);
+  });
+
+  test("count and pagination operate on unique monitors", async () => {
+    const where: FindOptionsWhere<Monitor> = QueryUtil.serializeQuery(Monitor, {
+      projectId: new ObjectID(projectId),
+      labels: new IncludesAnyOfGroups([
+        [network, router],
+        [unit0660, unit0661],
+      ]),
+    }) as unknown as FindOptionsWhere<Monitor>;
+    const [rows, count]: [Array<Monitor>, number] = await database
+      .getRepository(Monitor)
+      .findAndCount({
+        where,
+        select: { _id: true, name: true },
+        order: { name: "ASC" },
+        skip: 1,
+        take: 2,
+      });
+    expect(count).toBe(4);
+    expect(
+      rows.map((monitor: Monitor) => {
+        return monitor.name;
+      }),
+    ).toEqual(["network-0660", "network-0661"]);
+  });
+
+  test("a deleted selected label produces no results while retaining the fixed condition", async () => {
+    const deletedLabel: string = ObjectID.generate().toString();
+    await database.query(
+      `INSERT INTO "Label" ("_id", "version", "projectId", "name", "slug", "color") VALUES ($1, 1, $2, 'removed-unit', 'removed-unit', '#000000')`,
+      [deletedLabel, projectId],
+    );
+    await seedMonitor("deleted-label-monitor", [network, deletedLabel]);
+    try {
+      expect(
+        await findNames({
+          labels: new IncludesAnyOfGroups([[network], [deletedLabel]]),
+        }),
+      ).toEqual(["deleted-label-monitor"]);
+      await database.query(`DELETE FROM "Label" WHERE "_id" = $1`, [
+        deletedLabel,
+      ]);
+      expect(
+        await findNames({
+          labels: new IncludesAnyOfGroups([[network], [deletedLabel]]),
+        }),
+      ).toEqual([]);
+    } finally {
+      await database.query(`DELETE FROM "Monitor" WHERE "_id" = $1`, [
+        monitorIds["deleted-label-monitor"],
+      ]);
+      await database.query(`DELETE FROM "Label" WHERE "_id" = $1`, [
+        deletedLabel,
+      ]);
+    }
+  });
+});

package/Tests/Server/Types/Markdown.test.ts

@@ -1,4 +1,4 @@
-import Markdown from "../../../Server/Types/Markdown";
+import Markdown, { MarkdownContentType } from "../../../Server/Types/Markdown";
 
 /*
  * slugify turns a heading into the `id` the docs renderer emits, and therefore
@@ -104,3 +104,196 @@ describe("Markdown.slugify", () => {
     });
   });
 });
+
+/*
+ * THE EMAIL RENDERER.
+ *
+ * Until this suite existed there was no coverage of convertToHTML at all,
+ * for any content type — and the email renderer was a bare `new Renderer()`,
+ * so marked's stock output went straight into the message. That mattered
+ * most for the alert and incident root cause, which carries a
+ * GitHub-flavoured table of breaching samples: it arrived as a naked
+ * <table> with no borders and no padding, every row running into the next.
+ *
+ * Two properties are load-bearing and easy to break:
+ *
+ *  - the styling must be INLINE. MailService compiles the Handlebars
+ *    template and hands the string to nodemailer with no CSS-inlining step
+ *    anywhere in the pipeline, and Gmail strips <style> from the head, so a
+ *    class name reaches the reader as nothing at all.
+ *  - raw HTML a user typed must still be escaped. convertToHTML overrides
+ *    `renderer.html` for exactly that, on a renderer every email shares.
+ */
+describe("Markdown.convertToHTML - email renderer", () => {
+  const TABLE_MARKDOWN: string = [
+    "| Timestamp | Value |",
+    "| --- | --- |",
+    "| `2026-08-14T10:30:00.000Z` | 1.07 GB |",
+  ].join("\n");
+
+  test("renders a GFM table with inline styles, not class names", async () => {
+    const html: string = await Markdown.convertToHTML(
+      TABLE_MARKDOWN,
+      MarkdownContentType.Email,
+    );
+
+    expect(html).toContain("<table");
+    expect(html).toContain("<th");
+    expect(html).toContain("<td");
+    expect(html).toContain("border-collapse:collapse");
+    expect(html).toContain("padding:8px 10px");
+
+    /*
+     * A class would be dead weight: nothing inlines CSS before send and
+     * Gmail drops the <style> block Style.hbs emits.
+     */
+    expect(html).not.toContain('class="');
+  });
+
+  test("the table carries the legacy attributes Outlook honours over CSS", async () => {
+    const html: string = await Markdown.convertToHTML(
+      TABLE_MARKDOWN,
+      MarkdownContentType.Email,
+    );
+
+    expect(html).toContain('cellpadding="0"');
+    expect(html).toContain('cellspacing="0"');
+    expect(html).toContain('border="0"');
+    expect(html).toContain('width="100%"');
+  });
+
+  /*
+   * The DetailBox card leaves roughly 416px of usable width and a
+   * root-cause table routinely runs to four or more columns, so a long
+   * metric name has to wrap inside its column rather than push the table
+   * past the body width. Email clients ignore overflow, so there is no
+   * scrollbar to fall back on.
+   */
+  test("cells wrap long words rather than overflowing the card", async () => {
+    const html: string = await Markdown.convertToHTML(
+      TABLE_MARKDOWN,
+      MarkdownContentType.Email,
+    );
+
+    expect(html).toContain("word-break:break-word");
+    expect(html).not.toContain("overflow-x");
+  });
+
+  test("header cells are distinguishable from body cells", async () => {
+    const html: string = await Markdown.convertToHTML(
+      TABLE_MARKDOWN,
+      MarkdownContentType.Email,
+    );
+
+    const header: string = html.slice(
+      html.indexOf("<thead>"),
+      html.indexOf("</thead>"),
+    );
+    const body: string = html.slice(html.indexOf("<tbody>"));
+
+    expect(header).toContain("font-weight:600");
+    expect(header).toContain("background-color:#f8fafc");
+    expect(body).not.toContain("background-color:#f8fafc");
+  });
+
+  test("column alignment from the markdown survives", async () => {
+    const html: string = await Markdown.convertToHTML(
+      ["| A | B |", "| ---: | :--- |", "| 1 | 2 |"].join("\n"),
+      MarkdownContentType.Email,
+    );
+
+    expect(html).toContain("text-align:right");
+    expect(html).toContain("text-align:left");
+  });
+
+  // The root cause backticks every metric name, alias and timestamp.
+  test("inline code is styled and its content preserved", async () => {
+    const html: string = await Markdown.convertToHTML(
+      "Metric `k8s.pod.memory.usage` breached",
+      MarkdownContentType.Email,
+    );
+
+    expect(html).toContain("<code");
+    expect(html).toContain("background-color:#f1f5f9");
+    expect(html).toContain("k8s.pod.memory.usage");
+  });
+
+  test("code content is escaped rather than left live", async () => {
+    const html: string = await Markdown.convertToHTML(
+      "Metric `<img src=x onerror=alert(1)>` breached",
+      MarkdownContentType.Email,
+    );
+
+    expect(html).not.toContain("<img src=x");
+    expect(html).toContain("&lt;img");
+  });
+
+  /*
+   * The reason the DetailBoxField contract permits this output on a raw
+   * slot at all: convertToHTML escapes the raw-HTML tokens a user typed
+   * while letting the renderer's own tags through.
+   */
+  test("raw HTML typed into the markdown source is escaped", async () => {
+    const html: string = await Markdown.convertToHTML(
+      'Hello <img src=x onerror="alert(1)"> world',
+      MarkdownContentType.Email,
+    );
+
+    expect(html).not.toContain('onerror="alert(1)"');
+    expect(html).toContain("&lt;img");
+  });
+
+  test("bold and links still render, so the rest of the email is unchanged", async () => {
+    const html: string = await Markdown.convertToHTML(
+      "**Filter Conditions Met**: see [the dashboard](https://example.com)",
+      MarkdownContentType.Email,
+    );
+
+    expect(html).toContain("<strong>Filter Conditions Met</strong>");
+    expect(html).toContain('href="https://example.com"');
+  });
+
+  /*
+   * The renderer is memoised in a static field and convertToHTML reassigns
+   * `renderer.html` on it for every call, so any per-call state would leak
+   * between emails. Rendering twice must be identical.
+   */
+  test("repeated renders are identical", async () => {
+    const first: string = await Markdown.convertToHTML(
+      TABLE_MARKDOWN,
+      MarkdownContentType.Email,
+    );
+    const second: string = await Markdown.convertToHTML(
+      TABLE_MARKDOWN,
+      MarkdownContentType.Email,
+    );
+
+    expect(second).toBe(first);
+  });
+
+  test("an empty root cause does not throw", async () => {
+    await expect(
+      Markdown.convertToHTML("", MarkdownContentType.Email),
+    ).resolves.toBe("");
+  });
+});
+
+describe("Markdown.escapeHtml", () => {
+  /*
+   * Public so that code hand-building an email fragment by string
+   * interpolation escapes the same way marked's own path does.
+   */
+  test("escapes the five characters that break out of HTML", () => {
+    expect(Markdown.escapeHtml(`<a href="x" title='y'>&</a>`)).toBe(
+      "&lt;a href=&quot;x&quot; title=&#39;y&#39;&gt;&amp;&lt;/a&gt;",
+    );
+  });
+
+  test("escapes the ampersand first, so entities are not double-encoded wrongly", () => {
+    expect(Markdown.escapeHtml("&lt;")).toBe("&amp;lt;");
+  });
+
+  test("leaves ordinary text alone", () => {
+    expect(Markdown.escapeHtml("web-7d9f / prod")).toBe("web-7d9f / prod");
+  });
+});