@webpieces/nx-webpieces-rules 0.4.529 → 0.4.531

package/src/lib/runtime-viz-theme.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The runtime graph's VISUAL VOCABULARY, and the legend that explains it.
+ *
+ * Every colour, shape and fill the drawing uses lives here, next to the legend swatches that teach
+ * the reader what each one means. They are one unit on purpose: the legend's job is to be a true
+ * account of the picture, and the fastest way for a legend to start lying is for it to sit in a
+ * different file from the constants it describes and drift as those change.
+ *
+ * Imported by runtime-visualizer.ts, which owns the DRAWING (which nodes and edges to emit). This
+ * module knows nothing about the graph model, which is what keeps the dependency one-way and
+ * cycle-free.
+ */
+export declare const LEVEL_COLORS: Record<number, string>;
+export declare const QUEUE_FILL = "#FFF3E0";
+/**
+ * The queue node is an `Mrecord` whose FIRST field is empty, which draws a rounded outline with a
+ * vertical cap line near one end — a cylinder lying on its side, distinguishing a queue from the
+ * upright cylinder that now means a database.
+ *
+ * Two things here are load-bearing and easy to break:
+ *
+ * 1. NO surrounding `{}`. Record fields lay out along the rank direction, and this graph is
+ *    `rankdir=TB` (see {@link generateRuntimeDot}), where the default is horizontal — which is what
+ *    we want. Adding braces TOGGLES that, turning the cap line into a band across the top.
+ * 2. The leading space is the empty field. The record parser trims it to nothing, which is the
+ *    point; it must survive as its own field, so the `|` cannot be dropped.
+ *
+ * Graphviz has no sideways cylinder and never has: `orientation=` is documented as rotating POLYGON
+ * shapes, and `cylinder` is drawn with beziers, so it silently ignores the attribute (graphviz issue
+ * #2244, open since 2022 and still reproducible on 13.0.0). This is the closest native shape.
+ */
+export declare const QUEUE_SHAPE = "Mrecord";
+export declare const QUEUE_LABEL_PREFIX = " |";
+/**
+ * Marker class stamped on every queue node. Graphviz copies `class` straight into the rendered
+ * `<g class="node wp_queue">`, which is how runtime-visualizer.client.js finds these nodes and
+ * redraws them as true horizontal cylinders in the browser.
+ *
+ * A CLASS rather than an id prefix, because queue-kind EXTERNAL systems are queues too and share the
+ * `system__` id space with databases — which must stay upright. Underscored, not hyphenated: DOT
+ * emits a hyphen as `&#45;`, which is harmless but needlessly surprising to anyone reading the SVG.
+ */
+export declare const QUEUE_CLASS = "wp_queue";
+/** Fill for the upright cylinder standing for an external DATASTORE (firestore, postgres, ...). */
+export declare const DATABASE_FILL = "#E1F5FE";
+/** Shape per external-system kind. Anything unrecognised falls back to the generic dashed box. */
+export declare const EXTERNAL_SHAPES: Record<string, string>;
+/** Fill per external-system kind, paired with {@link EXTERNAL_SHAPES}. */
+export declare const EXTERNAL_FILLS: Record<string, string>;
+/** Fill + border for the dashed terminal node standing for a system outside this repo. */
+export declare const EXTERNAL_FILL = "#FAFAFA";
+export declare const EXTERNAL_BORDER = "#9E9E9E";
+/** Fill + border for the clock node standing for a scheduler-driven endpoint. */
+export declare const CRON_FILL = "#FFF9C4";
+export declare const CRON_BORDER = "#F9A825";
+/**
+ * The legend. Three columns — what a box IS, what a line MEANS, how to read a box — replacing the
+ * three paragraphs of prose that used to restate the picture in words. Styled after
+ * {@link GraphVisualizer}'s legend so the two graphs in this repo look like one tool.
+ */
+export declare function legendHtml(): string;

package/src/lib/runtime-viz-theme.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * The runtime graph's VISUAL VOCABULARY, and the legend that explains it.
+ *
+ * Every colour, shape and fill the drawing uses lives here, next to the legend swatches that teach
+ * the reader what each one means. They are one unit on purpose: the legend's job is to be a true
+ * account of the picture, and the fastest way for a legend to start lying is for it to sit in a
+ * different file from the constants it describes and drift as those change.
+ *
+ * Imported by runtime-visualizer.ts, which owns the DRAWING (which nodes and edges to emit). This
+ * module knows nothing about the graph model, which is what keeps the dependency one-way and
+ * cycle-free.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CRON_BORDER = exports.CRON_FILL = exports.EXTERNAL_BORDER = exports.EXTERNAL_FILL = exports.EXTERNAL_FILLS = exports.EXTERNAL_SHAPES = exports.DATABASE_FILL = exports.QUEUE_CLASS = exports.QUEUE_LABEL_PREFIX = exports.QUEUE_SHAPE = exports.QUEUE_FILL = exports.LEVEL_COLORS = void 0;
+exports.legendHtml = legendHtml;
+exports.LEVEL_COLORS = {
+    0: '#E8F5E9',
+    1: '#E3F2FD',
+    2: '#FFF3E0',
+    3: '#FCE4EC',
+};
+exports.QUEUE_FILL = '#FFF3E0';
+/**
+ * The queue node is an `Mrecord` whose FIRST field is empty, which draws a rounded outline with a
+ * vertical cap line near one end — a cylinder lying on its side, distinguishing a queue from the
+ * upright cylinder that now means a database.
+ *
+ * Two things here are load-bearing and easy to break:
+ *
+ * 1. NO surrounding `{}`. Record fields lay out along the rank direction, and this graph is
+ *    `rankdir=TB` (see {@link generateRuntimeDot}), where the default is horizontal — which is what
+ *    we want. Adding braces TOGGLES that, turning the cap line into a band across the top.
+ * 2. The leading space is the empty field. The record parser trims it to nothing, which is the
+ *    point; it must survive as its own field, so the `|` cannot be dropped.
+ *
+ * Graphviz has no sideways cylinder and never has: `orientation=` is documented as rotating POLYGON
+ * shapes, and `cylinder` is drawn with beziers, so it silently ignores the attribute (graphviz issue
+ * #2244, open since 2022 and still reproducible on 13.0.0). This is the closest native shape.
+ */
+exports.QUEUE_SHAPE = 'Mrecord';
+exports.QUEUE_LABEL_PREFIX = ' |';
+/**
+ * Marker class stamped on every queue node. Graphviz copies `class` straight into the rendered
+ * `<g class="node wp_queue">`, which is how runtime-visualizer.client.js finds these nodes and
+ * redraws them as true horizontal cylinders in the browser.
+ *
+ * A CLASS rather than an id prefix, because queue-kind EXTERNAL systems are queues too and share the
+ * `system__` id space with databases — which must stay upright. Underscored, not hyphenated: DOT
+ * emits a hyphen as `&#45;`, which is harmless but needlessly surprising to anyone reading the SVG.
+ */
+exports.QUEUE_CLASS = 'wp_queue';
+/** Fill for the upright cylinder standing for an external DATASTORE (firestore, postgres, ...). */
+exports.DATABASE_FILL = '#E1F5FE';
+/** Shape per external-system kind. Anything unrecognised falls back to the generic dashed box. */
+exports.EXTERNAL_SHAPES = {
+    database: 'cylinder',
+    cache: 'cylinder',
+    queue: 'Mrecord',
+    storage: 'folder',
+};
+/** Fill per external-system kind, paired with {@link EXTERNAL_SHAPES}. */
+exports.EXTERNAL_FILLS = {
+    database: exports.DATABASE_FILL,
+    cache: exports.DATABASE_FILL,
+    queue: exports.QUEUE_FILL,
+    storage: '#F3E5F5',
+};
+/** Fill + border for the dashed terminal node standing for a system outside this repo. */
+exports.EXTERNAL_FILL = '#FAFAFA';
+exports.EXTERNAL_BORDER = '#9E9E9E';
+/** Fill + border for the clock node standing for a scheduler-driven endpoint. */
+exports.CRON_FILL = '#FFF9C4';
+exports.CRON_BORDER = '#F9A825';
+class LegendSwatches {
+    service = '<svg width="46" height="26"><rect x="1" y="3" width="44" height="20" rx="7" fill="#E8F5E9" stroke="#333"/></svg>';
+    /**
+     * A cylinder on its side — the SAME geometry runtime-visualizer.client.js draws on the real
+     * node, so the legend cannot drift from the picture it explains.
+     */
+    queue = `<svg width="46" height="26"><path d="M9,5 H37 A8,8 0 0 1 37,21 H9 A8,8 0 0 1 9,5 Z" fill="${exports.QUEUE_FILL}" stroke="#333"/>` +
+        '<path d="M9,5 A8,8 0 0 1 9,21" fill="none" stroke="#333"/></svg>';
+    database = `<svg width="46" height="26"><path d="M8,7 a15,4 0 0 1 30,0 v12 a15,4 0 0 1 -30,0 z" fill="${exports.DATABASE_FILL}" stroke="#333"/>` +
+        '<path d="M8,7 a15,4 0 0 0 30,0" fill="none" stroke="#333"/></svg>';
+    storage = '<svg width="46" height="26"><path d="M2,22 V6 H16 l3,3 H44 V22 Z" fill="#F3E5F5" stroke="#333"/></svg>';
+    external = `<svg width="46" height="26"><rect x="1" y="3" width="44" height="20" fill="${exports.EXTERNAL_FILL}" ` +
+        `stroke="${exports.EXTERNAL_BORDER}" stroke-dasharray="4,3"/></svg>`;
+    cron = `<svg width="46" height="26"><circle cx="23" cy="13" r="11" fill="${exports.CRON_FILL}" stroke="${exports.CRON_BORDER}"/>` +
+        '<text x="23" y="18" font-size="12" text-anchor="middle">&#9200;</text></svg>';
+    solid = '<svg width="60" height="20"><line x1="2" y1="10" x2="48" y2="10" stroke="#333" stroke-width="1.5"/>' +
+        '<path d="M48,6 L57,10 L48,14 Z" fill="#333"/></svg>';
+    dashed = '<svg width="60" height="20"><line x1="2" y1="10" x2="48" y2="10" stroke="#333" stroke-width="1.5" ' +
+        'stroke-dasharray="5,4"/><path d="M48,6 L57,10 L48,14 Z" fill="#333"/></svg>';
+    scheduled = `<svg width="60" height="20"><line x1="2" y1="10" x2="48" y2="10" stroke="${exports.CRON_BORDER}" stroke-width="1.5"/>` +
+        `<path d="M48,6 L57,10 L48,14 Z" fill="${exports.CRON_BORDER}"/></svg>`;
+}
+/**
+ * The legend. Three columns — what a box IS, what a line MEANS, how to read a box — replacing the
+ * three paragraphs of prose that used to restate the picture in words. Styled after
+ * {@link GraphVisualizer}'s legend so the two graphs in this repo look like one tool.
+ */
+// webpieces-disable no-function-outside-class -- HTML builder, matching the sibling builders in this file
+function legendHtml() {
+    const sw = new LegendSwatches();
+    const item = (swatch, text) => `<div class="legend-item"><span class="sw">${swatch}</span><span>${text}</span></div>`;
+    return `<div class="legend">
+        <h2>Legend</h2>
+        <div class="legend-columns">
+            <div class="legend-col">
+                <h3>Node shapes &mdash; <em>what a box is</em></h3>
+                ${item(sw.service, '<strong>service</strong> &mdash; a deployable in this repo; fill is its dependency level')}
+                ${item(sw.queue, '<strong>queue</strong> &mdash; each <em>line</em> in the box is one Cloud Tasks queue, the unit Terraform actually creates. Queues of one contract that flow between the <em>same</em> producer and consumer share a box; every one is still named, so you can always see <em>which</em> queue is stuck.')}
+                ${item(sw.database, '<strong>database</strong> &mdash; a datastore outside this repo')}
+                ${item(sw.storage, '<strong>object storage</strong> &mdash; a bucket outside this repo')}
+                ${item(sw.external, '<strong>external system</strong> &mdash; outside this repo; nothing here implements it. Pointing <strong>OUT</strong> = a system this repo calls (firestore, gmail). Pointing <strong>IN</strong> = an endpoint driven from outside, and the box names the <strong>CALLER</strong> (<code>twilio</code>), not our contract &mdash; the contract and method are on the arrow. One vendor is ONE box however many endpoints it posts to, and the same box whether we call it or it calls us. A dotted box labelled <code>? unknown caller</code> means the endpoint never declared one.')}
+                ${item(sw.cron, '<strong>cron</strong> &mdash; a scheduler fires this endpoint')}
+            </div>
+            <div class="legend-col">
+                <h3>Lines &mdash; <em>what a call is</em></h3>
+                ${item(sw.solid, '<strong>solid = rpc</strong> &mdash; the request follows the arrow, the response flows back')}
+                ${item(sw.dashed, '<strong>dashed = event</strong> &mdash; asynchronous: the event flows in the direction of the arrow and returns once it is in the queue')}
+                ${item(sw.scheduled, '<strong>scheduled</strong> &mdash; a cron invocation')}
+                <div class="legend-note"><em>Every line is labeled with the contract the call flows over. A service that enqueues to itself loops through its own queue &mdash; a queue decouples the two sides, so it is not a dependency cycle.</em></div>
+            </div>
+            <div class="legend-col">
+                <h3>Reading a box</h3>
+                <pre class="legend-box-anatomy">name
+(server|client, L#)
+implements: &lt;contracts it serves&gt;
+</pre>
+                <div class="legend-note">A box lists only what it <strong>serves</strong>. What it <em>calls</em> is on its outgoing arrows.</div>
+                <div class="legend-note"><code>(via &lt;lib&gt;)</code> = served through an embedded library, not its own source.</div>
+            </div>
+        </div>
+    </div>`;
+}
+//# sourceMappingURL=runtime-viz-theme.js.map

package/src/lib/runtime-viz-theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-viz-theme.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-viz-theme.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AA2GH,gCAkCC;AA3IY,QAAA,YAAY,GAA2B;IAChD,CAAC,EAAE,SAAS;IACZ,CAAC,EAAE,SAAS;IACZ,CAAC,EAAE,SAAS;IACZ,CAAC,EAAE,SAAS;CACf,CAAC;AAEW,QAAA,UAAU,GAAG,SAAS,CAAC;AAEpC;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,WAAW,GAAG,SAAS,CAAC;AACxB,QAAA,kBAAkB,GAAG,IAAI,CAAC;AAEvC;;;;;;;;GAQG;AACU,QAAA,WAAW,GAAG,UAAU,CAAC;AAEtC,mGAAmG;AACtF,QAAA,aAAa,GAAG,SAAS,CAAC;AAEvC,kGAAkG;AACrF,QAAA,eAAe,GAA2B;IACnD,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,UAAU;IACjB,KAAK,EAAE,SAAS;IAChB,OAAO,EAAE,QAAQ;CACpB,CAAC;AAEF,0EAA0E;AAC7D,QAAA,cAAc,GAA2B;IAClD,QAAQ,EAAE,qBAAa;IACvB,KAAK,EAAE,qBAAa;IACpB,KAAK,EAAE,kBAAU;IACjB,OAAO,EAAE,SAAS;CACrB,CAAC;AAEF,0FAA0F;AAC7E,QAAA,aAAa,GAAG,SAAS,CAAC;AAC1B,QAAA,eAAe,GAAG,SAAS,CAAC;AAEzC,iFAAiF;AACpE,QAAA,SAAS,GAAG,SAAS,CAAC;AACtB,QAAA,WAAW,GAAG,SAAS,CAAC;AAErC,MAAM,cAAc;IACP,OAAO,GACZ,kHAAkH,CAAC;IACvH;;;OAGG;IACM,KAAK,GACV,6FAA6F,kBAAU,mBAAmB;QAC1H,kEAAkE,CAAC;IAC9D,QAAQ,GACb,6FAA6F,qBAAa,mBAAmB;QAC7H,mEAAmE,CAAC;IAC/D,OAAO,GACZ,wGAAwG,CAAC;IACpG,QAAQ,GACb,8EAA8E,qBAAa,IAAI;QAC/F,WAAW,uBAAe,kCAAkC,CAAC;IACxD,IAAI,GACT,oEAAoE,iBAAS,aAAa,mBAAW,KAAK;QAC1G,8EAA8E,CAAC;IAC1E,KAAK,GACV,qGAAqG;QACrG,qDAAqD,CAAC;IACjD,MAAM,GACX,oGAAoG;QACpG,6EAA6E,CAAC;IACzE,SAAS,GACd,4EAA4E,mBAAW,wBAAwB;QAC/G,yCAAyC,mBAAW,WAAW,CAAC;CACvE;AAED;;;;GAIG;AACH,0GAA0G;AAC1G,SAAgB,UAAU;IACtB,MAAM,EAAE,GAAG,IAAI,cAAc,EAAE,CAAC;IAChC,MAAM,IAAI,GAAG,CAAC,MAAc,EAAE,IAAY,EAAU,EAAE,CAClD,6CAA6C,MAAM,gBAAgB,IAAI,eAAe,CAAC;IAC3F,OAAO;;;;;kBAKO,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,0FAA0F,CAAC;kBAC5G,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,0SAA0S,CAAC;kBAC1T,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,iEAAiE,CAAC;kBACpF,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,oEAAoE,CAAC;kBACtF,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,ujBAAujB,CAAC;kBAC1kB,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,+DAA+D,CAAC;;;;kBAI9E,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,6FAA6F,CAAC;kBAC7G,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,yIAAyI,CAAC;kBAC1J,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,sDAAsD,CAAC;;;;;;;;;;;;;WAajF,CAAC;AACZ,CAAC","sourcesContent":["/**\n * The runtime graph's VISUAL VOCABULARY, and the legend that explains it.\n *\n * Every colour, shape and fill the drawing uses lives here, next to the legend swatches that teach\n * the reader what each one means. They are one unit on purpose: the legend's job is to be a true\n * account of the picture, and the fastest way for a legend to start lying is for it to sit in a\n * different file from the constants it describes and drift as those change.\n *\n * Imported by runtime-visualizer.ts, which owns the DRAWING (which nodes and edges to emit). This\n * module knows nothing about the graph model, which is what keeps the dependency one-way and\n * cycle-free.\n */\n\nexport const LEVEL_COLORS: Record<number, string> = {\n    0: '#E8F5E9',\n    1: '#E3F2FD',\n    2: '#FFF3E0',\n    3: '#FCE4EC',\n};\n\nexport const QUEUE_FILL = '#FFF3E0';\n\n/**\n * The queue node is an `Mrecord` whose FIRST field is empty, which draws a rounded outline with a\n * vertical cap line near one end — a cylinder lying on its side, distinguishing a queue from the\n * upright cylinder that now means a database.\n *\n * Two things here are load-bearing and easy to break:\n *\n * 1. NO surrounding `{}`. Record fields lay out along the rank direction, and this graph is\n *    `rankdir=TB` (see {@link generateRuntimeDot}), where the default is horizontal — which is what\n *    we want. Adding braces TOGGLES that, turning the cap line into a band across the top.\n * 2. The leading space is the empty field. The record parser trims it to nothing, which is the\n *    point; it must survive as its own field, so the `|` cannot be dropped.\n *\n * Graphviz has no sideways cylinder and never has: `orientation=` is documented as rotating POLYGON\n * shapes, and `cylinder` is drawn with beziers, so it silently ignores the attribute (graphviz issue\n * #2244, open since 2022 and still reproducible on 13.0.0). This is the closest native shape.\n */\nexport const QUEUE_SHAPE = 'Mrecord';\nexport const QUEUE_LABEL_PREFIX = ' |';\n\n/**\n * Marker class stamped on every queue node. Graphviz copies `class` straight into the rendered\n * `<g class=\"node wp_queue\">`, which is how runtime-visualizer.client.js finds these nodes and\n * redraws them as true horizontal cylinders in the browser.\n *\n * A CLASS rather than an id prefix, because queue-kind EXTERNAL systems are queues too and share the\n * `system__` id space with databases — which must stay upright. Underscored, not hyphenated: DOT\n * emits a hyphen as `&#45;`, which is harmless but needlessly surprising to anyone reading the SVG.\n */\nexport const QUEUE_CLASS = 'wp_queue';\n\n/** Fill for the upright cylinder standing for an external DATASTORE (firestore, postgres, ...). */\nexport const DATABASE_FILL = '#E1F5FE';\n\n/** Shape per external-system kind. Anything unrecognised falls back to the generic dashed box. */\nexport const EXTERNAL_SHAPES: Record<string, string> = {\n    database: 'cylinder',\n    cache: 'cylinder',\n    queue: 'Mrecord',\n    storage: 'folder',\n};\n\n/** Fill per external-system kind, paired with {@link EXTERNAL_SHAPES}. */\nexport const EXTERNAL_FILLS: Record<string, string> = {\n    database: DATABASE_FILL,\n    cache: DATABASE_FILL,\n    queue: QUEUE_FILL,\n    storage: '#F3E5F5',\n};\n\n/** Fill + border for the dashed terminal node standing for a system outside this repo. */\nexport const EXTERNAL_FILL = '#FAFAFA';\nexport const EXTERNAL_BORDER = '#9E9E9E';\n\n/** Fill + border for the clock node standing for a scheduler-driven endpoint. */\nexport const CRON_FILL = '#FFF9C4';\nexport const CRON_BORDER = '#F9A825';\n\nclass LegendSwatches {\n    readonly service =\n        '<svg width=\"46\" height=\"26\"><rect x=\"1\" y=\"3\" width=\"44\" height=\"20\" rx=\"7\" fill=\"#E8F5E9\" stroke=\"#333\"/></svg>';\n    /**\n     * A cylinder on its side — the SAME geometry runtime-visualizer.client.js draws on the real\n     * node, so the legend cannot drift from the picture it explains.\n     */\n    readonly queue =\n        `<svg width=\"46\" height=\"26\"><path d=\"M9,5 H37 A8,8 0 0 1 37,21 H9 A8,8 0 0 1 9,5 Z\" fill=\"${QUEUE_FILL}\" stroke=\"#333\"/>` +\n        '<path d=\"M9,5 A8,8 0 0 1 9,21\" fill=\"none\" stroke=\"#333\"/></svg>';\n    readonly database =\n        `<svg width=\"46\" height=\"26\"><path d=\"M8,7 a15,4 0 0 1 30,0 v12 a15,4 0 0 1 -30,0 z\" fill=\"${DATABASE_FILL}\" stroke=\"#333\"/>` +\n        '<path d=\"M8,7 a15,4 0 0 0 30,0\" fill=\"none\" stroke=\"#333\"/></svg>';\n    readonly storage =\n        '<svg width=\"46\" height=\"26\"><path d=\"M2,22 V6 H16 l3,3 H44 V22 Z\" fill=\"#F3E5F5\" stroke=\"#333\"/></svg>';\n    readonly external =\n        `<svg width=\"46\" height=\"26\"><rect x=\"1\" y=\"3\" width=\"44\" height=\"20\" fill=\"${EXTERNAL_FILL}\" ` +\n        `stroke=\"${EXTERNAL_BORDER}\" stroke-dasharray=\"4,3\"/></svg>`;\n    readonly cron =\n        `<svg width=\"46\" height=\"26\"><circle cx=\"23\" cy=\"13\" r=\"11\" fill=\"${CRON_FILL}\" stroke=\"${CRON_BORDER}\"/>` +\n        '<text x=\"23\" y=\"18\" font-size=\"12\" text-anchor=\"middle\">&#9200;</text></svg>';\n    readonly solid =\n        '<svg width=\"60\" height=\"20\"><line x1=\"2\" y1=\"10\" x2=\"48\" y2=\"10\" stroke=\"#333\" stroke-width=\"1.5\"/>' +\n        '<path d=\"M48,6 L57,10 L48,14 Z\" fill=\"#333\"/></svg>';\n    readonly dashed =\n        '<svg width=\"60\" height=\"20\"><line x1=\"2\" y1=\"10\" x2=\"48\" y2=\"10\" stroke=\"#333\" stroke-width=\"1.5\" ' +\n        'stroke-dasharray=\"5,4\"/><path d=\"M48,6 L57,10 L48,14 Z\" fill=\"#333\"/></svg>';\n    readonly scheduled =\n        `<svg width=\"60\" height=\"20\"><line x1=\"2\" y1=\"10\" x2=\"48\" y2=\"10\" stroke=\"${CRON_BORDER}\" stroke-width=\"1.5\"/>` +\n        `<path d=\"M48,6 L57,10 L48,14 Z\" fill=\"${CRON_BORDER}\"/></svg>`;\n}\n\n/**\n * The legend. Three columns — what a box IS, what a line MEANS, how to read a box — replacing the\n * three paragraphs of prose that used to restate the picture in words. Styled after\n * {@link GraphVisualizer}'s legend so the two graphs in this repo look like one tool.\n */\n// webpieces-disable no-function-outside-class -- HTML builder, matching the sibling builders in this file\nexport function legendHtml(): string {\n    const sw = new LegendSwatches();\n    const item = (swatch: string, text: string): string =>\n        `<div class=\"legend-item\"><span class=\"sw\">${swatch}</span><span>${text}</span></div>`;\n    return `<div class=\"legend\">\n        <h2>Legend</h2>\n        <div class=\"legend-columns\">\n            <div class=\"legend-col\">\n                <h3>Node shapes &mdash; <em>what a box is</em></h3>\n                ${item(sw.service, '<strong>service</strong> &mdash; a deployable in this repo; fill is its dependency level')}\n                ${item(sw.queue, '<strong>queue</strong> &mdash; each <em>line</em> in the box is one Cloud Tasks queue, the unit Terraform actually creates. Queues of one contract that flow between the <em>same</em> producer and consumer share a box; every one is still named, so you can always see <em>which</em> queue is stuck.')}\n                ${item(sw.database, '<strong>database</strong> &mdash; a datastore outside this repo')}\n                ${item(sw.storage, '<strong>object storage</strong> &mdash; a bucket outside this repo')}\n                ${item(sw.external, '<strong>external system</strong> &mdash; outside this repo; nothing here implements it. Pointing <strong>OUT</strong> = a system this repo calls (firestore, gmail). Pointing <strong>IN</strong> = an endpoint driven from outside, and the box names the <strong>CALLER</strong> (<code>twilio</code>), not our contract &mdash; the contract and method are on the arrow. One vendor is ONE box however many endpoints it posts to, and the same box whether we call it or it calls us. A dotted box labelled <code>? unknown caller</code> means the endpoint never declared one.')}\n                ${item(sw.cron, '<strong>cron</strong> &mdash; a scheduler fires this endpoint')}\n            </div>\n            <div class=\"legend-col\">\n                <h3>Lines &mdash; <em>what a call is</em></h3>\n                ${item(sw.solid, '<strong>solid = rpc</strong> &mdash; the request follows the arrow, the response flows back')}\n                ${item(sw.dashed, '<strong>dashed = event</strong> &mdash; asynchronous: the event flows in the direction of the arrow and returns once it is in the queue')}\n                ${item(sw.scheduled, '<strong>scheduled</strong> &mdash; a cron invocation')}\n                <div class=\"legend-note\"><em>Every line is labeled with the contract the call flows over. A service that enqueues to itself loops through its own queue &mdash; a queue decouples the two sides, so it is not a dependency cycle.</em></div>\n            </div>\n            <div class=\"legend-col\">\n                <h3>Reading a box</h3>\n                <pre class=\"legend-box-anatomy\">name\n(server|client, L#)\nimplements: &lt;contracts it serves&gt;\n</pre>\n                <div class=\"legend-note\">A box lists only what it <strong>serves</strong>. What it <em>calls</em> is on its outgoing arrows.</div>\n                <div class=\"legend-note\"><code>(via &lt;lib&gt;)</code> = served through an embedded library, not its own source.</div>\n            </div>\n        </div>\n    </div>`;\n}\n"]}