@webpieces/nx-webpieces-rules 0.4.460 → 0.4.461

package/src/lib/runtime-visualizer.d.ts

@@ -4,13 +4,40 @@
  * Renders the runtime microservice graph (services + inferred Z -> X edges,
  * each labeled with the api(s) they flow over) to DOT + interactive HTML in
  * tmp/webpieces/runtime-architecture.{dot,html}.
+ *
+ * Each service node names the contracts it IMPLEMENTS and USES. That list is the
+ * single most important fact in a microservice architecture, and it used to be
+ * collapsed into a server/client boolean and thrown away — leaving an api that a
+ * server serves but nothing in-repo calls completely invisible, and making a
+ * correct api design look like a detection failure.
+ *
+ * Calls that leave the repo (a contract NOTHING in-repo implements — firestore,
+ * gmail, ...) are drawn as dashed terminal nodes, so the vendor systems that
+ * actually page you at 3am stop being missing from the picture. They are
+ * RENDER-ONLY: derivation, levels and cycle detection never see them.
  */
 import type { RuntimeGraph } from './runtime-graph';
+/** Render options for the runtime graph. */
+export declare class RuntimeVizOptions {
+    /**
+     * Draw the dashed terminal nodes for contracts nothing in-repo implements. On by default;
+     * a repo whose external surface is noisy can turn them off in webpieces.config.json
+     * (runtime-architecture.showExternalNodes).
+     */
+    readonly showExternalNodes: boolean;
+    constructor(
+    /**
+     * Draw the dashed terminal nodes for contracts nothing in-repo implements. On by default;
+     * a repo whose external surface is noisy can turn them off in webpieces.config.json
+     * (runtime-architecture.showExternalNodes).
+     */
+    showExternalNodes?: boolean);
+}
 /** Build the Graphviz DOT for the runtime service graph. */
-export declare function generateRuntimeDot(graph: RuntimeGraph, title?: string): string;
+export declare function generateRuntimeDot(graph: RuntimeGraph, title?: string, options?: RuntimeVizOptions): string;
 export interface RuntimeVisualizationPaths {
     dotPath: string;
     htmlPath: string;
 }
 /** Write the DOT + HTML renderings to tmp/webpieces/. */
-export declare function writeRuntimeVisualization(graph: RuntimeGraph, workspaceRoot: string, title?: string): RuntimeVisualizationPaths;
+export declare function writeRuntimeVisualization(graph: RuntimeGraph, workspaceRoot: string, title?: string, options?: RuntimeVizOptions): RuntimeVisualizationPaths;

package/src/lib/runtime-visualizer.js

@@ -5,8 +5,20 @@
  * Renders the runtime microservice graph (services + inferred Z -> X edges,
  * each labeled with the api(s) they flow over) to DOT + interactive HTML in
  * tmp/webpieces/runtime-architecture.{dot,html}.
+ *
+ * Each service node names the contracts it IMPLEMENTS and USES. That list is the
+ * single most important fact in a microservice architecture, and it used to be
+ * collapsed into a server/client boolean and thrown away — leaving an api that a
+ * server serves but nothing in-repo calls completely invisible, and making a
+ * correct api design look like a detection failure.
+ *
+ * Calls that leave the repo (a contract NOTHING in-repo implements — firestore,
+ * gmail, ...) are drawn as dashed terminal nodes, so the vendor systems that
+ * actually page you at 3am stop being missing from the picture. They are
+ * RENDER-ONLY: derivation, levels and cycle detection never see them.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeVizOptions = void 0;
 exports.generateRuntimeDot = generateRuntimeDot;
 exports.writeRuntimeVisualization = writeRuntimeVisualization;
 const tslib_1 = require("tslib");
@@ -19,9 +31,66 @@ const LEVEL_COLORS = {
     3: '#FCE4EC',
 };
 const QUEUE_FILL = '#FFF3E0';
+/** Fill + border for the dashed terminal node standing for a system outside this repo. */
+const EXTERNAL_FILL = '#FAFAFA';
+const EXTERNAL_BORDER = '#9E9E9E';
+/** Apis per line inside a node label — beyond this the box grows wider than it is readable. */
+const APIS_PER_LABEL_LINE = 3;
+/** Separator for the (service, external-library) grouping key; illegal in both project names. */
+const PAIR_SEP = '|';
+/** Render options for the runtime graph. */
+class RuntimeVizOptions {
+    showExternalNodes;
+    constructor(
+    /**
+     * Draw the dashed terminal nodes for contracts nothing in-repo implements. On by default;
+     * a repo whose external surface is noisy can turn them off in webpieces.config.json
+     * (runtime-architecture.showExternalNodes).
+     */
+    showExternalNodes = true) {
+        this.showExternalNodes = showExternalNodes;
+    }
+}
+exports.RuntimeVizOptions = RuntimeVizOptions;
 function getShortName(name) {
     return name.includes('/') ? name.split('/').pop() : name;
 }
+/** Chunk a list into `\n`-separated label lines of at most APIS_PER_LABEL_LINE entries. */
+// webpieces-disable no-function-outside-class -- DOT label builder, matching getShortName in this file
+function labelList(entries) {
+    const lines = [];
+    for (let i = 0; i < entries.length; i += APIS_PER_LABEL_LINE) {
+        lines.push(entries.slice(i, i + APIS_PER_LABEL_LINE).join(', '));
+    }
+    return lines.join('\\n');
+}
+/**
+ * The implemented-api entries for a node label. An api served through an EMBEDDED LIBRARY is
+ * annotated with that library, because "who implements WarmupApi?" otherwise requires knowing that
+ * the derivation walks the dependsOn closure and then walking it by hand.
+ */
+// webpieces-disable no-function-outside-class -- DOT label builder, matching getShortName in this file
+function implementsEntries(svc) {
+    return svc.implements.map((api) => {
+        const via = svc.implementsVia?.[api];
+        return via === undefined ? api : `${api} (via ${getShortName(via)})`;
+    });
+}
+/**
+ * The full node label: name, role/level/declared service name, then the contracts it serves and
+ * the contracts it calls. A node with neither reads exactly as before.
+ */
+// webpieces-disable no-function-outside-class -- DOT label builder, matching getShortName in this file
+function nodeLabel(name, svc) {
+    const role = svc.implements.length > 0 ? 'server' : 'client';
+    const declared = svc.serviceName === undefined ? '' : `, "${svc.serviceName}"`;
+    let label = `${getShortName(name)}\\n(${role}, L${svc.level}${declared})`;
+    if (svc.implements.length > 0)
+        label += `\\nimplements: ${labelList(implementsEntries(svc))}`;
+    if (svc.uses.length > 0)
+        label += `\\nuses: ${labelList(svc.uses)}`;
+    return label;
+}
 /**
  * DOT for ONE runtime edge. rpc → a direct labeled arrow (producer calls consumer). pubsub → the
  * producer enqueues and the consumer is delivered later, so we draw producer → QUEUE → consumer
@@ -40,8 +109,53 @@ function edgeDot(edge) {
         `  "${from}" -> "${queueId}" [label="enqueue", style=dashed];\n` +
         `  "${queueId}" -> "${to}" [label="deliver", style=dashed];\n`);
 }
+/**
+ * The dashed terminal nodes + edges for calls that LEAVE the repo. Built from `unresolvedUses` —
+ * a contract used by a node and implemented by nobody in-repo — which the derivation already
+ * computes and which was, until now, only ever printed as a warning.
+ *
+ * Grouped by the api-lib that owns the contracts, so a service reaching three firestore contracts
+ * draws ONE `lib-firestore (external)` box rather than three. These are drawn, never derived: they
+ * are absent from levels, cycle detection and the transitive implements attribution.
+ */
+// webpieces-disable no-function-outside-class -- DOT string builder, matching getShortName in this file
+function externalDot(graph, hidden) {
+    // "service|externalName" -> the apis flowing over it.
+    const apisByPair = new Map();
+    for (const use of graph.unresolvedUses) {
+        if (hidden.has(use.service))
+            continue;
+        const external = getShortName(graph.apis[use.api]?.owner ?? use.api);
+        const key = `${use.service}${PAIR_SEP}${external}`;
+        if (!apisByPair.has(key))
+            apisByPair.set(key, []);
+        apisByPair.get(key).push(use.api);
+    }
+    if (apisByPair.size === 0)
+        return '';
+    let dot = '\n  // Systems outside this repo — no in-repo service implements these contracts.\n';
+    // The node ID is prefixed so an external library can never collide with a service of the same
+    // short name; only the label carries the bare name.
+    const externals = new Set([...apisByPair.keys()].map((key) => key.split(PAIR_SEP)[1]));
+    for (const external of [...externals].sort()) {
+        dot +=
+            `  "external__${external}" [shape=box, style="dashed,filled", fillcolor="${EXTERNAL_FILL}", ` +
+                `color="${EXTERNAL_BORDER}", label="${external}\\n(external)"];\n`;
+    }
+    for (const key of [...apisByPair.keys()].sort()) {
+        const parts = key.split(PAIR_SEP);
+        const service = parts[0];
+        const external = parts[1];
+        const via = labelList(apisByPair.get(key).sort());
+        dot +=
+            `  "${getShortName(service)}" -> "external__${external}" ` +
+                `[label="${via}", style=dashed, color="${EXTERNAL_BORDER}"];\n`;
+    }
+    return dot;
+}
 /** Build the Graphviz DOT for the runtime service graph. */
-function generateRuntimeDot(graph, title = 'WebPieces Runtime Architecture') {
+// webpieces-disable no-function-outside-class -- module entry point, matching the sibling builders here
+function generateRuntimeDot(graph, title = 'WebPieces Runtime Architecture', options = new RuntimeVizOptions()) {
     let dot = 'digraph RuntimeArchitecture {\n';
     dot += '  rankdir=TB;\n';
     dot += '  node [shape=box, style="filled,rounded", fontname="Arial"];\n';
@@ -54,8 +168,7 @@ function generateRuntimeDot(graph, title = 'WebPieces Runtime Architecture') {
             continue;
         const svc = graph.services[name];
         const color = LEVEL_COLORS[svc.level] || '#F5F5F5';
-        const role = svc.implements.length > 0 ? 'server' : 'client';
-        dot += `  "${getShortName(name)}" [fillcolor="${color}", label="${getShortName(name)}\\n(${role}, L${svc.level})"];\n`;
+        dot += `  "${getShortName(name)}" [fillcolor="${color}", label="${nodeLabel(name, svc)}"];\n`;
     }
     dot += '\n';
     for (const edge of graph.runtimeEdges) {
@@ -63,6 +176,8 @@ function generateRuntimeDot(graph, title = 'WebPieces Runtime Architecture') {
             continue;
         dot += edgeDot(edge);
     }
+    if (options.showExternalNodes)
+        dot += externalDot(graph, hidden);
     dot += '\n  labelloc="t";\n';
     dot += `  label="${title}\\n(from architecture/runtime-dependencies.json)";\n`;
     dot += '  fontsize=20;\n';
@@ -93,17 +208,18 @@ function generateRuntimeHtml(dot, title) {
 <body>
     <h1>${title}</h1>
     <div class="note">Runtime calls between services. <strong>rpc</strong> = a direct arrow (synchronous call, labeled with the api). <strong>pubsub</strong> = producer &rarr; <em>queue</em> (cylinder) &rarr; consumer: the producer enqueues a Cloud Task and the consumer is delivered it later.</div>
+    <div class="note">Each box lists the contracts it <strong>implements</strong> (serves) and <strong>uses</strong> (calls) — so an api a service serves is visible even when nothing in this repo calls it. <em>(via &lt;lib&gt;)</em> means the service serves that contract through an embedded library rather than its own source. A <strong>dashed box</strong> is a system OUTSIDE this repo (firestore, gmail, ...): a contract this repo calls and nothing here implements.</div>
     <div id="graph"></div>
     <script>${script}</script>
 </body>
 </html>`;
 }
 /** Write the DOT + HTML renderings to tmp/webpieces/. */
-function writeRuntimeVisualization(graph, workspaceRoot, title = 'WebPieces Runtime Architecture') {
+function writeRuntimeVisualization(graph, workspaceRoot, title = 'WebPieces Runtime Architecture', options = new RuntimeVizOptions()) {
     const outputDir = path.join(workspaceRoot, 'tmp', 'webpieces');
     if (!fs.existsSync(outputDir))
         fs.mkdirSync(outputDir, { recursive: true });
-    const dot = generateRuntimeDot(graph, title);
+    const dot = generateRuntimeDot(graph, title, options);
     const dotPath = path.join(outputDir, 'runtime-architecture.dot');
     fs.writeFileSync(dotPath, dot, 'utf-8');
     const htmlPath = path.join(outputDir, 'runtime-architecture.html');

package/src/lib/runtime-visualizer.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-visualizer.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-visualizer.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Runtime Visualizer\n *\n * Renders the runtime microservice graph (services + inferred Z -> X edges,\n * each labeled with the api(s) they flow over) to DOT + interactive HTML in\n * tmp/webpieces/runtime-architecture.{dot,html}.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport type { RuntimeGraph, RuntimeEdge } from './runtime-graph';\n\nconst LEVEL_COLORS: Record<number, string> = {\n    0: '#E8F5E9',\n    1: '#E3F2FD',\n    2: '#FFF3E0',\n    3: '#FCE4EC',\n};\n\nconst QUEUE_FILL = '#FFF3E0';\n\nfunction getShortName(name: string): string {\n    return name.includes('/') ? name.split('/').pop()! : name;\n}\n\n/**\n * DOT for ONE runtime edge. rpc → a direct labeled arrow (producer calls consumer). pubsub → the\n * producer enqueues and the consumer is delivered later, so we draw producer → QUEUE → consumer\n * with a cylinder queue node and dashed enqueue/deliver arrows.\n */\n// webpieces-disable no-function-outside-class -- DOT string builder, matching getShortName in this file\nfunction edgeDot(edge: RuntimeEdge): string {\n    const from = getShortName(edge.from);\n    const to = getShortName(edge.to);\n    const via = edge.via.map((v: string) => getShortName(v)).join(', ');\n    if (edge.type !== 'pubsub') {\n        return `  \"${from}\" -> \"${to}\" [label=\"${via}\"];\\n`;\n    }\n    const queueId = `queue__${from}__${to}`;\n    return (\n        `  \"${queueId}\" [shape=cylinder, style=\"filled\", fillcolor=\"${QUEUE_FILL}\", label=\"${via}\\\\nqueue\"];\\n` +\n        `  \"${from}\" -> \"${queueId}\" [label=\"enqueue\", style=dashed];\\n` +\n        `  \"${queueId}\" -> \"${to}\" [label=\"deliver\", style=dashed];\\n`\n    );\n}\n\n/** Build the Graphviz DOT for the runtime service graph. */\nexport function generateRuntimeDot(graph: RuntimeGraph, title: string = 'WebPieces Runtime Architecture'): string {\n    let dot = 'digraph RuntimeArchitecture {\\n';\n    dot += '  rankdir=TB;\\n';\n    dot += '  node [shape=box, style=\"filled,rounded\", fontname=\"Arial\"];\\n';\n    dot += '  edge [fontname=\"Arial\", fontsize=10];\\n\\n';\n\n    // Services tagged drawOnGraph:false stay in the JSON but are omitted here —\n    // both their node and any edge touching them are dropped from the render.\n    const hidden = new Set(\n        Object.keys(graph.services).filter((name: string) => graph.services[name].drawOnGraph === false)\n    );\n\n    for (const name of Object.keys(graph.services)) {\n        if (hidden.has(name)) continue;\n        const svc = graph.services[name];\n        const color = LEVEL_COLORS[svc.level] || '#F5F5F5';\n        const role = svc.implements.length > 0 ? 'server' : 'client';\n        dot += `  \"${getShortName(name)}\" [fillcolor=\"${color}\", label=\"${getShortName(name)}\\\\n(${role}, L${svc.level})\"];\\n`;\n    }\n\n    dot += '\\n';\n\n    for (const edge of graph.runtimeEdges) {\n        if (hidden.has(edge.from) || hidden.has(edge.to)) continue;\n        dot += edgeDot(edge);\n    }\n\n    dot += '\\n  labelloc=\"t\";\\n';\n    dot += `  label=\"${title}\\\\n(from architecture/runtime-dependencies.json)\";\\n`;\n    dot += '  fontsize=20;\\n';\n    dot += '}\\n';\n    return dot;\n}\n\nfunction generateRuntimeHtml(dot: string, title: string): string {\n    const script = `\n        const dot = ${JSON.stringify(dot)};\n        const viz = new Viz();\n        viz.renderSVGElement(dot)\n            .then(el => document.getElementById('graph').appendChild(el))\n            .catch(err => { document.getElementById('graph').innerHTML = '<pre>' + err + '</pre>'; });\n    `;\n    return `<!DOCTYPE html>\n<html>\n<head>\n    <title>${title}</title>\n    <script src=\"https://cdn.jsdelivr.net/npm/viz.js@2.1.2/viz.js\"></script>\n    <script src=\"https://cdn.jsdelivr.net/npm/viz.js@2.1.2/full.render.js\"></script>\n    <style>\n        body { margin: 0; padding: 20px; font-family: Arial, sans-serif; background: #f5f5f5; }\n        h1 { text-align: center; color: #333; }\n        #graph { text-align: center; background: white; padding: 20px; border-radius: 8px; }\n        .note { max-width: 700px; margin: 12px auto; color: #555; text-align: center; }\n    </style>\n</head>\n<body>\n    <h1>${title}</h1>\n    <div class=\"note\">Runtime calls between services. <strong>rpc</strong> = a direct arrow (synchronous call, labeled with the api). <strong>pubsub</strong> = producer &rarr; <em>queue</em> (cylinder) &rarr; consumer: the producer enqueues a Cloud Task and the consumer is delivered it later.</div>\n    <div id=\"graph\"></div>\n    <script>${script}</script>\n</body>\n</html>`;\n}\n\nexport interface RuntimeVisualizationPaths {\n    dotPath: string;\n    htmlPath: string;\n}\n\n/** Write the DOT + HTML renderings to tmp/webpieces/. */\nexport function writeRuntimeVisualization(\n    graph: RuntimeGraph,\n    workspaceRoot: string,\n    title: string = 'WebPieces Runtime Architecture',\n): RuntimeVisualizationPaths {\n    const outputDir = path.join(workspaceRoot, 'tmp', 'webpieces');\n    if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });\n\n    const dot = generateRuntimeDot(graph, title);\n    const dotPath = path.join(outputDir, 'runtime-architecture.dot');\n    fs.writeFileSync(dotPath, dot, 'utf-8');\n\n    const htmlPath = path.join(outputDir, 'runtime-architecture.html');\n    fs.writeFileSync(htmlPath, generateRuntimeHtml(dot, title), 'utf-8');\n\n    return { dotPath, htmlPath };\n}\n"]}
+{"version":3,"file":"runtime-visualizer.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-visualizer.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Runtime Visualizer\n *\n * Renders the runtime microservice graph (services + inferred Z -> X edges,\n * each labeled with the api(s) they flow over) to DOT + interactive HTML in\n * tmp/webpieces/runtime-architecture.{dot,html}.\n *\n * Each service node names the contracts it IMPLEMENTS and USES. That list is the\n * single most important fact in a microservice architecture, and it used to be\n * collapsed into a server/client boolean and thrown away — leaving an api that a\n * server serves but nothing in-repo calls completely invisible, and making a\n * correct api design look like a detection failure.\n *\n * Calls that leave the repo (a contract NOTHING in-repo implements — firestore,\n * gmail, ...) are drawn as dashed terminal nodes, so the vendor systems that\n * actually page you at 3am stop being missing from the picture. They are\n * RENDER-ONLY: derivation, levels and cycle detection never see them.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport type { RuntimeGraph, RuntimeEdge, RuntimeService } from './runtime-graph';\n\nconst LEVEL_COLORS: Record<number, string> = {\n    0: '#E8F5E9',\n    1: '#E3F2FD',\n    2: '#FFF3E0',\n    3: '#FCE4EC',\n};\n\nconst QUEUE_FILL = '#FFF3E0';\n\n/** Fill + border for the dashed terminal node standing for a system outside this repo. */\nconst EXTERNAL_FILL = '#FAFAFA';\nconst EXTERNAL_BORDER = '#9E9E9E';\n\n/** Apis per line inside a node label — beyond this the box grows wider than it is readable. */\nconst APIS_PER_LABEL_LINE = 3;\n\n/** Separator for the (service, external-library) grouping key; illegal in both project names. */\nconst PAIR_SEP = '|';\n\n/** Render options for the runtime graph. */\nexport class RuntimeVizOptions {\n    constructor(\n        /**\n         * Draw the dashed terminal nodes for contracts nothing in-repo implements. On by default;\n         * a repo whose external surface is noisy can turn them off in webpieces.config.json\n         * (runtime-architecture.showExternalNodes).\n         */\n        public readonly showExternalNodes: boolean = true,\n    ) {}\n}\n\nfunction getShortName(name: string): string {\n    return name.includes('/') ? name.split('/').pop()! : name;\n}\n\n/** Chunk a list into `\\n`-separated label lines of at most APIS_PER_LABEL_LINE entries. */\n// webpieces-disable no-function-outside-class -- DOT label builder, matching getShortName in this file\nfunction labelList(entries: string[]): string {\n    const lines: string[] = [];\n    for (let i = 0; i < entries.length; i += APIS_PER_LABEL_LINE) {\n        lines.push(entries.slice(i, i + APIS_PER_LABEL_LINE).join(', '));\n    }\n    return lines.join('\\\\n');\n}\n\n/**\n * The implemented-api entries for a node label. An api served through an EMBEDDED LIBRARY is\n * annotated with that library, because \"who implements WarmupApi?\" otherwise requires knowing that\n * the derivation walks the dependsOn closure and then walking it by hand.\n */\n// webpieces-disable no-function-outside-class -- DOT label builder, matching getShortName in this file\nfunction implementsEntries(svc: RuntimeService): string[] {\n    return svc.implements.map((api: string) => {\n        const via = svc.implementsVia?.[api];\n        return via === undefined ? api : `${api} (via ${getShortName(via)})`;\n    });\n}\n\n/**\n * The full node label: name, role/level/declared service name, then the contracts it serves and\n * the contracts it calls. A node with neither reads exactly as before.\n */\n// webpieces-disable no-function-outside-class -- DOT label builder, matching getShortName in this file\nfunction nodeLabel(name: string, svc: RuntimeService): string {\n    const role = svc.implements.length > 0 ? 'server' : 'client';\n    const declared = svc.serviceName === undefined ? '' : `, \"${svc.serviceName}\"`;\n    let label = `${getShortName(name)}\\\\n(${role}, L${svc.level}${declared})`;\n    if (svc.implements.length > 0) label += `\\\\nimplements: ${labelList(implementsEntries(svc))}`;\n    if (svc.uses.length > 0) label += `\\\\nuses: ${labelList(svc.uses)}`;\n    return label;\n}\n\n/**\n * DOT for ONE runtime edge. rpc → a direct labeled arrow (producer calls consumer). pubsub → the\n * producer enqueues and the consumer is delivered later, so we draw producer → QUEUE → consumer\n * with a cylinder queue node and dashed enqueue/deliver arrows.\n */\n// webpieces-disable no-function-outside-class -- DOT string builder, matching getShortName in this file\nfunction edgeDot(edge: RuntimeEdge): string {\n    const from = getShortName(edge.from);\n    const to = getShortName(edge.to);\n    const via = edge.via.map((v: string) => getShortName(v)).join(', ');\n    if (edge.type !== 'pubsub') {\n        return `  \"${from}\" -> \"${to}\" [label=\"${via}\"];\\n`;\n    }\n    const queueId = `queue__${from}__${to}`;\n    return (\n        `  \"${queueId}\" [shape=cylinder, style=\"filled\", fillcolor=\"${QUEUE_FILL}\", label=\"${via}\\\\nqueue\"];\\n` +\n        `  \"${from}\" -> \"${queueId}\" [label=\"enqueue\", style=dashed];\\n` +\n        `  \"${queueId}\" -> \"${to}\" [label=\"deliver\", style=dashed];\\n`\n    );\n}\n\n/**\n * The dashed terminal nodes + edges for calls that LEAVE the repo. Built from `unresolvedUses` —\n * a contract used by a node and implemented by nobody in-repo — which the derivation already\n * computes and which was, until now, only ever printed as a warning.\n *\n * Grouped by the api-lib that owns the contracts, so a service reaching three firestore contracts\n * draws ONE `lib-firestore (external)` box rather than three. These are drawn, never derived: they\n * are absent from levels, cycle detection and the transitive implements attribution.\n */\n// webpieces-disable no-function-outside-class -- DOT string builder, matching getShortName in this file\nfunction externalDot(graph: RuntimeGraph, hidden: Set<string>): string {\n    // \"service|externalName\" -> the apis flowing over it.\n    const apisByPair = new Map<string, string[]>();\n    for (const use of graph.unresolvedUses) {\n        if (hidden.has(use.service)) continue;\n        const external = getShortName(graph.apis[use.api]?.owner ?? use.api);\n        const key = `${use.service}${PAIR_SEP}${external}`;\n        if (!apisByPair.has(key)) apisByPair.set(key, []);\n        apisByPair.get(key)!.push(use.api);\n    }\n    if (apisByPair.size === 0) return '';\n\n    let dot = '\\n  // Systems outside this repo — no in-repo service implements these contracts.\\n';\n    // The node ID is prefixed so an external library can never collide with a service of the same\n    // short name; only the label carries the bare name.\n    const externals = new Set([...apisByPair.keys()].map((key: string) => key.split(PAIR_SEP)[1]));\n    for (const external of [...externals].sort()) {\n        dot +=\n            `  \"external__${external}\" [shape=box, style=\"dashed,filled\", fillcolor=\"${EXTERNAL_FILL}\", ` +\n            `color=\"${EXTERNAL_BORDER}\", label=\"${external}\\\\n(external)\"];\\n`;\n    }\n    for (const key of [...apisByPair.keys()].sort()) {\n        const parts = key.split(PAIR_SEP);\n        const service = parts[0];\n        const external = parts[1];\n        const via = labelList(apisByPair.get(key)!.sort());\n        dot +=\n            `  \"${getShortName(service)}\" -> \"external__${external}\" ` +\n            `[label=\"${via}\", style=dashed, color=\"${EXTERNAL_BORDER}\"];\\n`;\n    }\n    return dot;\n}\n\n/** Build the Graphviz DOT for the runtime service graph. */\n// webpieces-disable no-function-outside-class -- module entry point, matching the sibling builders here\nexport function generateRuntimeDot(\n    graph: RuntimeGraph,\n    title: string = 'WebPieces Runtime Architecture',\n    options: RuntimeVizOptions = new RuntimeVizOptions(),\n): string {\n    let dot = 'digraph RuntimeArchitecture {\\n';\n    dot += '  rankdir=TB;\\n';\n    dot += '  node [shape=box, style=\"filled,rounded\", fontname=\"Arial\"];\\n';\n    dot += '  edge [fontname=\"Arial\", fontsize=10];\\n\\n';\n\n    // Services tagged drawOnGraph:false stay in the JSON but are omitted here —\n    // both their node and any edge touching them are dropped from the render.\n    const hidden = new Set(\n        Object.keys(graph.services).filter((name: string) => graph.services[name].drawOnGraph === false)\n    );\n\n    for (const name of Object.keys(graph.services)) {\n        if (hidden.has(name)) continue;\n        const svc = graph.services[name];\n        const color = LEVEL_COLORS[svc.level] || '#F5F5F5';\n        dot += `  \"${getShortName(name)}\" [fillcolor=\"${color}\", label=\"${nodeLabel(name, svc)}\"];\\n`;\n    }\n\n    dot += '\\n';\n\n    for (const edge of graph.runtimeEdges) {\n        if (hidden.has(edge.from) || hidden.has(edge.to)) continue;\n        dot += edgeDot(edge);\n    }\n\n    if (options.showExternalNodes) dot += externalDot(graph, hidden);\n\n    dot += '\\n  labelloc=\"t\";\\n';\n    dot += `  label=\"${title}\\\\n(from architecture/runtime-dependencies.json)\";\\n`;\n    dot += '  fontsize=20;\\n';\n    dot += '}\\n';\n    return dot;\n}\n\nfunction generateRuntimeHtml(dot: string, title: string): string {\n    const script = `\n        const dot = ${JSON.stringify(dot)};\n        const viz = new Viz();\n        viz.renderSVGElement(dot)\n            .then(el => document.getElementById('graph').appendChild(el))\n            .catch(err => { document.getElementById('graph').innerHTML = '<pre>' + err + '</pre>'; });\n    `;\n    return `<!DOCTYPE html>\n<html>\n<head>\n    <title>${title}</title>\n    <script src=\"https://cdn.jsdelivr.net/npm/viz.js@2.1.2/viz.js\"></script>\n    <script src=\"https://cdn.jsdelivr.net/npm/viz.js@2.1.2/full.render.js\"></script>\n    <style>\n        body { margin: 0; padding: 20px; font-family: Arial, sans-serif; background: #f5f5f5; }\n        h1 { text-align: center; color: #333; }\n        #graph { text-align: center; background: white; padding: 20px; border-radius: 8px; }\n        .note { max-width: 700px; margin: 12px auto; color: #555; text-align: center; }\n    </style>\n</head>\n<body>\n    <h1>${title}</h1>\n    <div class=\"note\">Runtime calls between services. <strong>rpc</strong> = a direct arrow (synchronous call, labeled with the api). <strong>pubsub</strong> = producer &rarr; <em>queue</em> (cylinder) &rarr; consumer: the producer enqueues a Cloud Task and the consumer is delivered it later.</div>\n    <div class=\"note\">Each box lists the contracts it <strong>implements</strong> (serves) and <strong>uses</strong> (calls) — so an api a service serves is visible even when nothing in this repo calls it. <em>(via &lt;lib&gt;)</em> means the service serves that contract through an embedded library rather than its own source. A <strong>dashed box</strong> is a system OUTSIDE this repo (firestore, gmail, ...): a contract this repo calls and nothing here implements.</div>\n    <div id=\"graph\"></div>\n    <script>${script}</script>\n</body>\n</html>`;\n}\n\nexport interface RuntimeVisualizationPaths {\n    dotPath: string;\n    htmlPath: string;\n}\n\n/** Write the DOT + HTML renderings to tmp/webpieces/. */\nexport function writeRuntimeVisualization(\n    graph: RuntimeGraph,\n    workspaceRoot: string,\n    title: string = 'WebPieces Runtime Architecture',\n    options: RuntimeVizOptions = new RuntimeVizOptions(),\n): RuntimeVisualizationPaths {\n    const outputDir = path.join(workspaceRoot, 'tmp', 'webpieces');\n    if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });\n\n    const dot = generateRuntimeDot(graph, title, options);\n    const dotPath = path.join(outputDir, 'runtime-architecture.dot');\n    fs.writeFileSync(dotPath, dot, 'utf-8');\n\n    const htmlPath = path.join(outputDir, 'runtime-architecture.html');\n    fs.writeFileSync(htmlPath, generateRuntimeHtml(dot, title), 'utf-8');\n\n    return { dotPath, htmlPath };\n}\n"]}

package/src/lib/service-name-resolver.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Service Name Resolver
+ *
+ * Resolves the `serviceName` field written per project into
+ * architecture/dependencies.json — the name a CLIENT uses to address this app at
+ * runtime (`new ClientConfig('helper-fsdb')`), i.e. its deployed Cloud Run
+ * service name, NOT its nx project name.
+ *
+ * It is DECLARED, never derived. The three naming spaces have no mechanical
+ * relationship, and any strip-the-suffix rule gets it wrong somewhere:
+ *
+ *   nx project      | serviceName    | Cloud Run
+ *   helper-svr      | helper-portal  | helper-portal
+ *   helper-fsdb-svr | helper-fsdb    | helper-fsdb
+ *   lang-server     | lang           | lang
+ *
+ * Declared in the project's own project.json, next to the code it names:
+ *
+ *   { "metadata": { "webpieces": { "serviceName": "helper-fsdb" } } }
+ *
+ * Absent is legal and common — a library or a browser app is never addressed by
+ * name. A node WITHOUT one simply cannot be the resolved target of a targeted
+ * client call, and the runtime graph says so out loud rather than guessing.
+ */
+import { ProjectInfo } from './project-info';
+/** The project.json key path holding the declared name: metadata.webpieces.serviceName. */
+export declare const SERVICE_NAME_METADATA_PATH = "metadata.webpieces.serviceName";
+export declare class ServiceNameResolution {
+    /** Declared service name, or null when none is declared (or resolution failed). */
+    readonly serviceName: string | null;
+    /** Problem description when the declaration is present but unusable, otherwise null. */
+    readonly problem: string | null;
+    constructor(
+    /** Declared service name, or null when none is declared (or resolution failed). */
+    serviceName: string | null, 
+    /** Problem description when the declaration is present but unusable, otherwise null. */
+    problem: string | null);
+}
+/**
+ * Read `metadata.webpieces.serviceName` from the project's project.json. A missing file, a missing
+ * key, or an unparseable file all resolve to "not declared" — only a PRESENT-but-wrong value (empty
+ * or not a string) is a problem, because that is a typo the author wants told about.
+ */
+export declare function resolveServiceName(info: ProjectInfo, workspaceRoot: string): ServiceNameResolution;
+/**
+ * Two projects claiming the same service name make every targeted client edge ambiguous, so the
+ * graph would have to guess. Reported as a metadata problem instead. Appends to `problems`.
+ */
+export declare function validateUniqueServiceNames(names: Map<string, string>, problems: string[]): void;

package/src/lib/service-name-resolver.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Service Name Resolver
+ *
+ * Resolves the `serviceName` field written per project into
+ * architecture/dependencies.json — the name a CLIENT uses to address this app at
+ * runtime (`new ClientConfig('helper-fsdb')`), i.e. its deployed Cloud Run
+ * service name, NOT its nx project name.
+ *
+ * It is DECLARED, never derived. The three naming spaces have no mechanical
+ * relationship, and any strip-the-suffix rule gets it wrong somewhere:
+ *
+ *   nx project      | serviceName    | Cloud Run
+ *   helper-svr      | helper-portal  | helper-portal
+ *   helper-fsdb-svr | helper-fsdb    | helper-fsdb
+ *   lang-server     | lang           | lang
+ *
+ * Declared in the project's own project.json, next to the code it names:
+ *
+ *   { "metadata": { "webpieces": { "serviceName": "helper-fsdb" } } }
+ *
+ * Absent is legal and common — a library or a browser app is never addressed by
+ * name. A node WITHOUT one simply cannot be the resolved target of a targeted
+ * client call, and the runtime graph says so out loud rather than guessing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceNameResolution = exports.SERVICE_NAME_METADATA_PATH = void 0;
+exports.resolveServiceName = resolveServiceName;
+exports.validateUniqueServiceNames = validateUniqueServiceNames;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const toError_1 = require("../toError");
+/** The project.json key path holding the declared name: metadata.webpieces.serviceName. */
+exports.SERVICE_NAME_METADATA_PATH = 'metadata.webpieces.serviceName';
+class ServiceNameResolution {
+    serviceName;
+    problem;
+    constructor(
+    /** Declared service name, or null when none is declared (or resolution failed). */
+    serviceName, 
+    /** Problem description when the declaration is present but unusable, otherwise null. */
+    problem) {
+        this.serviceName = serviceName;
+        this.problem = problem;
+    }
+}
+exports.ServiceNameResolution = ServiceNameResolution;
+/**
+ * Read `metadata.webpieces.serviceName` from the project's project.json. A missing file, a missing
+ * key, or an unparseable file all resolve to "not declared" — only a PRESENT-but-wrong value (empty
+ * or not a string) is a problem, because that is a typo the author wants told about.
+ */
+// webpieces-disable no-function-outside-class -- pure resolver, mirrors resolveRole/resolveDrawOnGraph
+function resolveServiceName(info, workspaceRoot) {
+    const raw = readServiceNameField(path.join(workspaceRoot, info.root, 'project.json'));
+    if (raw === undefined)
+        return new ServiceNameResolution(null, null);
+    if (typeof raw !== 'string' || raw.trim().length === 0) {
+        return new ServiceNameResolution(null, `${info.name}: ${exports.SERVICE_NAME_METADATA_PATH} in project.json must be a non-empty string`);
+    }
+    return new ServiceNameResolution(raw.trim(), null);
+}
+/**
+ * Two projects claiming the same service name make every targeted client edge ambiguous, so the
+ * graph would have to guess. Reported as a metadata problem instead. Appends to `problems`.
+ */
+// webpieces-disable no-function-outside-class -- pure validator, mirrors validateRoleDependencies
+function validateUniqueServiceNames(names, problems) {
+    const projectsByName = new Map();
+    for (const project of [...names.keys()].sort()) {
+        const serviceName = names.get(project);
+        const claimants = projectsByName.get(serviceName) ?? [];
+        claimants.push(project);
+        projectsByName.set(serviceName, claimants);
+    }
+    for (const serviceName of [...projectsByName.keys()].sort()) {
+        const claimants = projectsByName.get(serviceName);
+        if (claimants.length < 2)
+            continue;
+        problems.push(`serviceName '${serviceName}' is declared by ${claimants.length} projects ` +
+            `(${claimants.join(', ')}) — a client naming it could not be routed to one of them. ` +
+            `Give each project a distinct ${exports.SERVICE_NAME_METADATA_PATH}.`);
+    }
+}
+/** The raw `metadata.webpieces.serviceName` value, or undefined when not present at all. */
+// webpieces-disable no-any-unknown -- project.json is opaque consumer JSON until narrowed here
+// webpieces-disable no-function-outside-class -- pure file accessor, matches the sibling resolvers
+function readServiceNameField(projectJsonPath) {
+    if (!fs.existsSync(projectJsonPath))
+        return undefined;
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        const parsed = JSON.parse(fs.readFileSync(projectJsonPath, 'utf-8'));
+        return parsed?.metadata?.webpieces?.serviceName;
+    }
+    catch (err) {
+        const error = (0, toError_1.toError)(err);
+        console.warn(`⚠️  Skipping unparseable ${projectJsonPath}: ${error.message}`);
+        return undefined;
+    }
+}
+//# sourceMappingURL=service-name-resolver.js.map

package/src/lib/service-name-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-name-resolver.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/service-name-resolver.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;;;AAyBH,gDAUC;AAOD,gEAiBC;;AAzDD,+CAAyB;AACzB,mDAA6B;AAE7B,wCAAqC;AAErC,2FAA2F;AAC9E,QAAA,0BAA0B,GAAG,gCAAgC,CAAC;AAE3E,MAAa,qBAAqB;IAGV;IAEA;IAJpB;IACI,mFAAmF;IACnE,WAA0B;IAC1C,wFAAwF;IACxE,OAAsB;QAFtB,gBAAW,GAAX,WAAW,CAAe;QAE1B,YAAO,GAAP,OAAO,CAAe;IACvC,CAAC;CACP;AAPD,sDAOC;AAED;;;;GAIG;AACH,uGAAuG;AACvG,SAAgB,kBAAkB,CAAC,IAAiB,EAAE,aAAqB;IACvE,MAAM,GAAG,GAAG,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC;IACtF,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,IAAI,qBAAqB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACpE,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrD,OAAO,IAAI,qBAAqB,CAC5B,IAAI,EACJ,GAAG,IAAI,CAAC,IAAI,KAAK,kCAA0B,6CAA6C,CAC3F,CAAC;IACN,CAAC;IACD,OAAO,IAAI,qBAAqB,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;AACvD,CAAC;AAED;;;GAGG;AACH,kGAAkG;AAClG,SAAgB,0BAA0B,CAAC,KAA0B,EAAE,QAAkB;IACrF,MAAM,cAAc,GAAG,IAAI,GAAG,EAAoB,CAAC;IACnD,KAAK,MAAM,OAAO,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC7C,MAAM,WAAW,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAE,CAAC;QACxC,MAAM,SAAS,GAAG,cAAc,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;QACxD,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxB,cAAc,CAAC,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAC/C,CAAC;IACD,KAAK,MAAM,WAAW,IAAI,CAAC,GAAG,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC1D,MAAM,SAAS,GAAG,cAAc,CAAC,GAAG,CAAC,WAAW,CAAE,CAAC;QACnD,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;YAAE,SAAS;QACnC,QAAQ,CAAC,IAAI,CACT,gBAAgB,WAAW,oBAAoB,SAAS,CAAC,MAAM,YAAY;YACvE,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,6DAA6D;YACrF,gCAAgC,kCAA0B,GAAG,CACpE,CAAC;IACN,CAAC;AACL,CAAC;AAED,4FAA4F;AAC5F,+FAA+F;AAC/F,mGAAmG;AACnG,SAAS,oBAAoB,CAAC,eAAuB;IACjD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC;QAAE,OAAO,SAAS,CAAC;IACtD,8DAA8D;IAC9D,IAAI,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC;QACrE,OAAO,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,CAAC;IACpD,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,IAAI,CAAC,4BAA4B,eAAe,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAC9E,OAAO,SAAS,CAAC;IACrB,CAAC;AACL,CAAC","sourcesContent":["/**\n * Service Name Resolver\n *\n * Resolves the `serviceName` field written per project into\n * architecture/dependencies.json — the name a CLIENT uses to address this app at\n * runtime (`new ClientConfig('helper-fsdb')`), i.e. its deployed Cloud Run\n * service name, NOT its nx project name.\n *\n * It is DECLARED, never derived. The three naming spaces have no mechanical\n * relationship, and any strip-the-suffix rule gets it wrong somewhere:\n *\n *   nx project      | serviceName    | Cloud Run\n *   helper-svr      | helper-portal  | helper-portal\n *   helper-fsdb-svr | helper-fsdb    | helper-fsdb\n *   lang-server     | lang           | lang\n *\n * Declared in the project's own project.json, next to the code it names:\n *\n *   { \"metadata\": { \"webpieces\": { \"serviceName\": \"helper-fsdb\" } } }\n *\n * Absent is legal and common — a library or a browser app is never addressed by\n * name. A node WITHOUT one simply cannot be the resolved target of a targeted\n * client call, and the runtime graph says so out loud rather than guessing.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { ProjectInfo } from './project-info';\nimport { toError } from '../toError';\n\n/** The project.json key path holding the declared name: metadata.webpieces.serviceName. */\nexport const SERVICE_NAME_METADATA_PATH = 'metadata.webpieces.serviceName';\n\nexport class ServiceNameResolution {\n    constructor(\n        /** Declared service name, or null when none is declared (or resolution failed). */\n        public readonly serviceName: string | null,\n        /** Problem description when the declaration is present but unusable, otherwise null. */\n        public readonly problem: string | null,\n    ) {}\n}\n\n/**\n * Read `metadata.webpieces.serviceName` from the project's project.json. A missing file, a missing\n * key, or an unparseable file all resolve to \"not declared\" — only a PRESENT-but-wrong value (empty\n * or not a string) is a problem, because that is a typo the author wants told about.\n */\n// webpieces-disable no-function-outside-class -- pure resolver, mirrors resolveRole/resolveDrawOnGraph\nexport function resolveServiceName(info: ProjectInfo, workspaceRoot: string): ServiceNameResolution {\n    const raw = readServiceNameField(path.join(workspaceRoot, info.root, 'project.json'));\n    if (raw === undefined) return new ServiceNameResolution(null, null);\n    if (typeof raw !== 'string' || raw.trim().length === 0) {\n        return new ServiceNameResolution(\n            null,\n            `${info.name}: ${SERVICE_NAME_METADATA_PATH} in project.json must be a non-empty string`,\n        );\n    }\n    return new ServiceNameResolution(raw.trim(), null);\n}\n\n/**\n * Two projects claiming the same service name make every targeted client edge ambiguous, so the\n * graph would have to guess. Reported as a metadata problem instead. Appends to `problems`.\n */\n// webpieces-disable no-function-outside-class -- pure validator, mirrors validateRoleDependencies\nexport function validateUniqueServiceNames(names: Map<string, string>, problems: string[]): void {\n    const projectsByName = new Map<string, string[]>();\n    for (const project of [...names.keys()].sort()) {\n        const serviceName = names.get(project)!;\n        const claimants = projectsByName.get(serviceName) ?? [];\n        claimants.push(project);\n        projectsByName.set(serviceName, claimants);\n    }\n    for (const serviceName of [...projectsByName.keys()].sort()) {\n        const claimants = projectsByName.get(serviceName)!;\n        if (claimants.length < 2) continue;\n        problems.push(\n            `serviceName '${serviceName}' is declared by ${claimants.length} projects ` +\n                `(${claimants.join(', ')}) — a client naming it could not be routed to one of them. ` +\n                `Give each project a distinct ${SERVICE_NAME_METADATA_PATH}.`,\n        );\n    }\n}\n\n/** The raw `metadata.webpieces.serviceName` value, or undefined when not present at all. */\n// webpieces-disable no-any-unknown -- project.json is opaque consumer JSON until narrowed here\n// webpieces-disable no-function-outside-class -- pure file accessor, matches the sibling resolvers\nfunction readServiceNameField(projectJsonPath: string): unknown {\n    if (!fs.existsSync(projectJsonPath)) return undefined;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const parsed = JSON.parse(fs.readFileSync(projectJsonPath, 'utf-8'));\n        return parsed?.metadata?.webpieces?.serviceName;\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.warn(`⚠️  Skipping unparseable ${projectJsonPath}: ${error.message}`);\n        return undefined;\n    }\n}\n"]}