refactor(client): inline the ANSI conversion, drop a dependency

.changeset/refactor-inline-ansi-html.md

@@ -0,0 +1,34 @@
+---
+"webpack-dev-middleware": patch
+---
+
+Dropped the `ansi-html-community` dependency. The overlay's ANSI-to-HTML
+conversion is `client-src/utils/ansi-html.js` now, which is the third of that
+package this project used — the rest was surface it never touched, and it
+shipped into every consumer's browser bundle. Four production dependencies
+instead of five, and one fewer unmaintained package in the supply chain (its
+last release was 0.0.8 in April 2022, itself a fork of the abandoned
+`ansi-html`).
+
+Output is byte-identical for the sequences a build actually produces. Four
+things it got wrong are fixed:
+
+- A palette entry of `"transparent"`, which is how the overlay says to leave
+  the page's own colour alone, became `color:#transparent`. That is not a
+  colour, so the reset worked only because browsers drop an invalid
+  declaration, and the inverse sequence did nothing at all.
+- A sequence carrying more than one parameter (`\u001b[1;31m`) matched nothing,
+  so the escape stayed in the output as text for the reader to see.
+- `\u001b[m`, which is `\u001b[0m` written short, was left in the output the
+  same way.
+- A closing sequence with nothing open emitted an unmatched `</span>`. The
+  highlighters wrap their own spans around this output, so a stray close could
+  end one of theirs early.
+- Every closing tag was a `</span>`, whatever was open. `\u001b[3m` opens an
+  `<i>`, so an unclosed italic came out as `<i>x</span>`, and an interleaved
+  sequence crossed its tags: `<i><span>x</i></span>`. Each open element now
+  carries its own closing tag, so the markup nests whatever the sequences do.
+
+The conversion had no test of its own while it was a dependency. It has 25 now,
+one of which walks every three-sequence combination and checks the result
+nests.

client-src/overlay.js

@@ -1,7 +1,6 @@
-import ansiHTML from "ansi-html-community";
-
 import { problemLine } from "./problem.js";
 import theme from "./theme.js";
+import ansiHTML, { setColors } from "./utils/ansi-html.js";
 
 // Re-exported so a consumer that shows problems in the console as well as in
 // the overlay has one import for both. `./client/problem` is the same thing
@@ -137,6 +136,11 @@ const colors = {
   darkgrey: "6d7891",
 };
 
+// At load, the way the package this replaced initialised itself: a message can
+// carry colours before anyone has configured anything, and `ansiColors` below
+// only re-reads the palette when it has changed it.
+setColors(colors);
+
 /**
  * @typedef {object} OverlayState
  * @property {HTMLIFrameElement | null} frame overlay iframe
@@ -1000,7 +1004,7 @@ export default function configureOverlay(options) {
         colors[color] = options.ansiColors[color];
       }
     }
-    ansiHTML.setColors(colors);
+    setColors(colors);
   }
 
   if (options.overlayStyles) {

client-src/utils/ansi-html.js

@@ -0,0 +1,272 @@
+// ANSI colours to HTML, for the overlay.
+//
+// Inlined from `ansi-html-community`, whose last release was 0.0.8 in April
+// 2022 and which is itself a fork of the abandoned `ansi-html`. A third of it
+// was surface this project never touched — the `tags` getters, a `reset()`
+// nobody called, and the validation branches that a fixed palette cannot
+// reach — and it shipped into every consumer's browser bundle.
+//
+// Two things are different from that package, both deliberate, both covered by
+// `test/ansi-html.test.js`:
+//
+//   * A palette entry of `"transparent"` leaves the declaration out rather
+//     than writing `color:#transparent`, which is not a colour. Browsers drop
+//     an invalid declaration, so the reset worked by accident; it now says
+//     what it means.
+//   * A sequence carrying more than one parameter (`\u001b[1;31m`) is applied
+//     parameter by parameter. It used to match nothing, so the escape stayed
+//     in the output as text for the reader to see.
+//
+// Compiled to an ES5 baseline like the rest of the browser runtime.
+
+// One SGR sequence: `\u001b[`, the parameters, then `m`. Other escapes (cursor
+// moves, screen clears) are left exactly as they came, the way they were
+// before.
+// eslint-disable-next-line no-control-regex
+const SGR = /\u001B\[([0-9;]*)m/g;
+
+// Which colour each foreground parameter names. The background parameter is
+// this plus ten, which is what the loop below relies on.
+/** @type {Record<string, string>} */
+const FOREGROUND = {
+  30: "black",
+  31: "red",
+  32: "green",
+  33: "yellow",
+  34: "blue",
+  35: "magenta",
+  36: "cyan",
+  37: "lightgrey",
+};
+
+// What each parameter opens, where it is not a colour.
+/** @type {Record<string, string>} */
+const STATIC_OPEN = {
+  1: "font-weight:bold",
+  2: "opacity:0.5",
+  3: "<i>",
+  4: "<u>",
+  8: "display:none",
+  9: "<del>",
+};
+
+// ... and what closes one. The rest close whatever span is open.
+/** @type {Record<string, string>} */
+const STATIC_CLOSE = {
+  23: "</i>",
+  24: "</u>",
+  29: "</del>",
+};
+
+const CLOSES_SPAN = [0, 21, 22, 27, 28, 39, 49];
+
+/** @type {Record<string, string>} */
+let openTags = {};
+/** @type {Record<string, string>} */
+let closeTags = {};
+
+/**
+ * One colour declaration, or nothing at all.
+ *
+ * A palette carries a hex colour without its `#`, so one is added back. Any
+ * other value is used as it is, and `"transparent"` — which is how a palette
+ * says to leave the page's own colour alone — produces no declaration rather
+ * than an invalid one.
+ * @param {string} property `color` or `background`
+ * @param {string | undefined} value the palette's value
+ * @returns {string} the declaration, or an empty string
+ */
+function colorDeclaration(property, value) {
+  if (!value || value === "transparent") {
+    return "";
+  }
+
+  return `${property}:${/^[\da-f]{3,8}$/i.test(value) ? `#${value}` : value}`;
+}
+
+/**
+ * Join the declarations that have something in them.
+ * @param {string[]} declarations css declarations
+ * @returns {string} the style
+ */
+function style(declarations) {
+  const kept = [];
+
+  for (let index = 0; index < declarations.length; index++) {
+    if (declarations[index]) {
+      kept.push(declarations[index]);
+    }
+  }
+
+  return kept.join(";");
+}
+
+/**
+ * Build the tag tables from a palette.
+ * @param {Record<string, string | string[]>} colors palette, hex without `#`
+ */
+export function setColors(colors) {
+  /** @type {Record<string, string>} */
+  const open = {};
+  /** @type {Record<string, string>} */
+  const close = {};
+
+  for (const parameter of Object.keys(STATIC_OPEN)) {
+    open[parameter] = STATIC_OPEN[parameter];
+  }
+
+  for (const parameter of Object.keys(STATIC_CLOSE)) {
+    close[parameter] = STATIC_CLOSE[parameter];
+  }
+
+  for (let index = 0; index < CLOSES_SPAN.length; index++) {
+    close[CLOSES_SPAN[index]] = "</span>";
+  }
+
+  const reset = Array.isArray(colors.reset)
+    ? colors.reset
+    : [/** @type {string} */ (colors.reset)];
+  const [foreground, background] = reset;
+
+  // Reset: back to the page's weight and opacity, and to whichever colours the
+  // palette names for it.
+  open[0] = style([
+    "font-weight:normal",
+    "opacity:1",
+    colorDeclaration("color", foreground),
+    colorDeclaration("background", background),
+  ]);
+
+  // Inverse: the reset pair, the other way round.
+  open[7] = style([
+    colorDeclaration("color", background),
+    colorDeclaration("background", foreground),
+  ]);
+
+  open[90] = style([
+    colorDeclaration("color", /** @type {string} */ (colors.darkgrey)),
+  ]);
+
+  for (const parameter of Object.keys(FOREGROUND)) {
+    const color = /** @type {string} */ (
+      colors[FOREGROUND[parameter]] || "000"
+    );
+
+    open[parameter] = style([colorDeclaration("color", color)]);
+    open[Number(parameter) + 10] = style([
+      colorDeclaration("background", color),
+    ]);
+  }
+
+  openTags = open;
+  closeTags = close;
+}
+
+/**
+ * One element this opened, and the tag that closes it.
+ * @typedef {object} Open
+ * @property {string} parameter the parameter that opened it
+ * @property {string} closing the tag that closes it
+ */
+
+/**
+ * Apply one SGR parameter.
+ *
+ * The stack carries each open element's own closing tag. The package this
+ * replaced stacked the parameters instead and closed with a hardcoded
+ * `</span>`, so a `<i>` opened by `\u001b[3m` was closed with `</span>` and an
+ * interleaved sequence crossed its tags — `<i><span>x</i></span>`. Whatever
+ * this produces nests, because the highlighters wrap their own spans around
+ * it afterwards and crossed tags there take the card's markup with them.
+ * @param {string} parameter the parameter, as it was written
+ * @param {Open[]} stack elements still open, outermost first
+ * @returns {string} what it becomes
+ */
+function applyParameter(parameter, stack) {
+  const open = openTags[parameter];
+
+  if (typeof open !== "undefined") {
+    // The same parameter again closes what it opened — what the package did,
+    // kept — and with it everything opened inside, so the nesting holds.
+    for (let index = stack.length - 1; index >= 0; index--) {
+      if (stack[index].parameter === parameter) {
+        let out = "";
+
+        while (stack.length > index) {
+          out += /** @type {Open} */ (stack.pop()).closing;
+        }
+
+        return out;
+      }
+    }
+
+    const isTag = open.charAt(0) === "<";
+
+    stack.push({
+      parameter,
+      closing: isTag ? `</${open.slice(1)}` : "</span>",
+    });
+
+    if (isTag) {
+      return open;
+    }
+
+    // A palette can leave a parameter with nothing to declare — inverse, with
+    // a reset pair of `"transparent"`. The span still opens, to keep the stack
+    // balanced, but without an empty style attribute to carry.
+    return open === "" ? "<span>" : `<span style="${open};">`;
+  }
+
+  if (typeof closeTags[parameter] !== "undefined") {
+    // Nothing open is nothing to close. The package emitted the tag anyway,
+    // which put an unmatched `</span>` into the card — and a stray close can
+    // end a span one of the highlighters opened around this.
+    if (stack.length === 0) {
+      return "";
+    }
+
+    // The innermost element closes, with its own tag. Which parameter a closer
+    // belongs to is not tracked: `\u001b[3m\u001b[31mx\u001b[23m` cannot close
+    // the italic without crossing the colour span, so the italic runs to the
+    // end of the message instead. Reading further than the sequence asked is
+    // the lesser of the two.
+    return /** @type {Open} */ (stack.pop()).closing;
+  }
+
+  return "";
+}
+
+/**
+ * Turn the ANSI colours in some text into HTML.
+ * @param {string} text text that may carry SGR sequences
+ * @returns {string} the text, with its colours as markup
+ */
+export default function ansiHTML(text) {
+  // Nothing to do, and nothing to scan: a message without an escape in it is
+  // most messages.
+  if (text.indexOf("\u001B") === -1) {
+    return text;
+  }
+
+  /** @type {Open[]} */
+  const stack = [];
+  let result = text.replace(SGR, (match, parameters) => {
+    // `\u001b[m` is `\u001b[0m` written short.
+    const each = (parameters === "" ? "0" : parameters).split(";");
+    let out = "";
+
+    for (let index = 0; index < each.length; index++) {
+      out += applyParameter(each[index], stack);
+    }
+
+    return out;
+  });
+
+  // Whatever is still open, closed with its own tag and innermost first, so
+  // the markup cannot leak into the rest of the card.
+  while (stack.length > 0) {
+    result += /** @type {Open} */ (stack.pop()).closing;
+  }
+
+  return result;
+}

package.json

@@ -84,7 +84,6 @@
     "fix:schema-check": "node ./scripts/generate-schema-check.mjs"
   },
   "dependencies": {
-    "ansi-html-community": "^0.0.8",
     "memfs": "^4.68.2",
     "mime-types": "^3.0.2",
     "range-parser": "^1.3.0",