@webpieces/nx-webpieces-rules 0.4.653 → 0.4.655

package/src/lib/graph-names.d.ts

@@ -1,17 +1,60 @@
 /**
  * Graph Names
  *
- * Shared helper for turning a scoped project name into the short display name
- * used everywhere in the visualization (graph box titles, the lock-control
- * options, and the responsibilities cards). Kept in its own class so both
- * GraphVisualizer and ResponsibilitiesRenderer can depend on it without a
- * circular dependency between them.
+ * The two names a project has in the visualization, kept apart on purpose:
+ *
+ *  - its NODE ID — the identity every DOT node, edge endpoint, `rank=same` member, lock-dropdown
+ *    value and responsibilities `data-node` attribute is keyed on. It is the project KEY, verbatim.
+ *  - its SHORT NAME — the human-facing label, with the `@scope/` prefix stripped.
+ *
+ * They used to be the same string, and that was a silent, badly-wrong-picture bug. A workspace may
+ * legitimately hold `@scope/public-api` (an L0 contract lib) AND `public-api` (the L6 server that
+ * serves it) — two DISTINCT projects that strip to the same short name. Keying the DOT on the short
+ * name fused them into one node, and graphviz UNIONS any two `rank=same` sets sharing a node, so
+ * L0's rank and L6's rank became one rank: the entire L0 band rendered on the L6 row, the invisible
+ * anchor chain that pins level order became unsatisfiable (it demands L0 strictly below L6 while the
+ * union says they are equal) and was discarded, and the server's dependency on the contract lib drew
+ * as a self-loop on the fused box.
+ *
+ * So identity is the project key and nothing else — collision is structurally impossible now rather
+ * than merely unlikely — and {@link GraphNames.assertUniqueNodeIds} asserts that, so a future change
+ * that reintroduces a lossy id fails generation loudly instead of drawing a wrong graph in silence.
+ *
+ * Kept in its own class so GraphVisualizer and ResponsibilitiesRenderer can both depend on it
+ * without a circular dependency between them.
  */
+/** One project key and the level it sits on — what a collision report has to name. */
+export declare class NodeIdOwner {
+    readonly projectKey: string;
+    readonly level: number;
+    constructor(projectKey: string, level: number);
+}
+/** Thrown when two distinct project keys would be drawn as the same DOT node. */
+export declare class NodeIdCollisionError extends Error {
+    constructor(message: string);
+}
 export declare class GraphNames {
     /**
-     * Remove scope from name for display
+     * The DOT/DOM identity of a project: its project KEY, unchanged.
+     *
+     * This is deliberately a named method rather than an inlined `project` at ten call sites — the
+     * node id is one decision, and it has to be made in one place or the DOT, the lock dropdown and
+     * the responsibilities cards drift apart and the hover/lock wiring silently stops matching.
+     */
+    getNodeId(projectKey: string): string;
+    /**
+     * The human-facing display name: scope stripped.
      * '@scope/name' → 'name'
      * 'name' → 'name'
+     *
+     * LABELS ONLY. Never use this as an identity — see this file's header for what that cost.
      */
     getShortName(name: string): string;
+    /**
+     * Assert that every project draws as its own node.
+     *
+     * Fails LOUDLY, naming both colliding project keys and their levels, because the failure mode it
+     * guards is a graph that renders happily and says something false.
+     */
+    assertUniqueNodeIds(owners: NodeIdOwner[]): void;
 }

package/src/lib/graph-names.js

@@ -2,23 +2,104 @@
 /**
  * Graph Names
  *
- * Shared helper for turning a scoped project name into the short display name
- * used everywhere in the visualization (graph box titles, the lock-control
- * options, and the responsibilities cards). Kept in its own class so both
- * GraphVisualizer and ResponsibilitiesRenderer can depend on it without a
- * circular dependency between them.
+ * The two names a project has in the visualization, kept apart on purpose:
+ *
+ *  - its NODE ID — the identity every DOT node, edge endpoint, `rank=same` member, lock-dropdown
+ *    value and responsibilities `data-node` attribute is keyed on. It is the project KEY, verbatim.
+ *  - its SHORT NAME — the human-facing label, with the `@scope/` prefix stripped.
+ *
+ * They used to be the same string, and that was a silent, badly-wrong-picture bug. A workspace may
+ * legitimately hold `@scope/public-api` (an L0 contract lib) AND `public-api` (the L6 server that
+ * serves it) — two DISTINCT projects that strip to the same short name. Keying the DOT on the short
+ * name fused them into one node, and graphviz UNIONS any two `rank=same` sets sharing a node, so
+ * L0's rank and L6's rank became one rank: the entire L0 band rendered on the L6 row, the invisible
+ * anchor chain that pins level order became unsatisfiable (it demands L0 strictly below L6 while the
+ * union says they are equal) and was discarded, and the server's dependency on the contract lib drew
+ * as a self-loop on the fused box.
+ *
+ * So identity is the project key and nothing else — collision is structurally impossible now rather
+ * than merely unlikely — and {@link GraphNames.assertUniqueNodeIds} asserts that, so a future change
+ * that reintroduces a lossy id fails generation loudly instead of drawing a wrong graph in silence.
+ *
+ * Kept in its own class so GraphVisualizer and ResponsibilitiesRenderer can both depend on it
+ * without a circular dependency between them.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GraphNames = void 0;
+exports.GraphNames = exports.NodeIdCollisionError = exports.NodeIdOwner = void 0;
+/** One project key and the level it sits on — what a collision report has to name. */
+class NodeIdOwner {
+    projectKey;
+    level;
+    constructor(projectKey, level) {
+        this.projectKey = projectKey;
+        this.level = level;
+    }
+}
+exports.NodeIdOwner = NodeIdOwner;
+/** Thrown when two distinct project keys would be drawn as the same DOT node. */
+class NodeIdCollisionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NodeIdCollisionError';
+    }
+}
+exports.NodeIdCollisionError = NodeIdCollisionError;
 class GraphNames {
     /**
-     * Remove scope from name for display
+     * The DOT/DOM identity of a project: its project KEY, unchanged.
+     *
+     * This is deliberately a named method rather than an inlined `project` at ten call sites — the
+     * node id is one decision, and it has to be made in one place or the DOT, the lock dropdown and
+     * the responsibilities cards drift apart and the hover/lock wiring silently stops matching.
+     */
+    getNodeId(projectKey) {
+        return projectKey;
+    }
+    /**
+     * The human-facing display name: scope stripped.
      * '@scope/name' → 'name'
      * 'name' → 'name'
+     *
+     * LABELS ONLY. Never use this as an identity — see this file's header for what that cost.
      */
     getShortName(name) {
         return name.includes('/') ? name.split('/').pop() : name;
     }
+    /**
+     * Assert that every project draws as its own node.
+     *
+     * Fails LOUDLY, naming both colliding project keys and their levels, because the failure mode it
+     * guards is a graph that renders happily and says something false.
+     */
+    assertUniqueNodeIds(owners) {
+        const byNodeId = new Map();
+        for (const owner of owners) {
+            const nodeId = this.getNodeId(owner.projectKey);
+            const existing = byNodeId.get(nodeId);
+            if (existing === undefined)
+                byNodeId.set(nodeId, [owner]);
+            else
+                existing.push(owner);
+        }
+        const collisions = [];
+        for (const nodeId of [...byNodeId.keys()].sort()) {
+            const sharers = byNodeId.get(nodeId);
+            if (sharers.length < 2)
+                continue;
+            const named = sharers
+                .map((owner) => `"${owner.projectKey}" (L${owner.level})`)
+                .sort()
+                .join(' and ');
+            collisions.push(`  node "${nodeId}" would be drawn for ${named}`);
+        }
+        if (collisions.length === 0)
+            return;
+        throw new NodeIdCollisionError('Two distinct projects map to the same graph node, so the rendered architecture graph '
+            + 'would fuse them (and fuse their dependency levels into one row):\n'
+            + collisions.sort().join('\n')
+            + '\nFix: getNodeId() must stay a 1:1 function of the project key — it is the project '
+            + 'key verbatim. Only getShortName() may drop the scope, and only for LABELS.');
+    }
 }
 exports.GraphNames = GraphNames;
 //# sourceMappingURL=graph-names.js.map

package/src/lib/graph-names.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph-names.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-names.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAEH,MAAa,UAAU;IACnB;;;;OAIG;IACH,YAAY,CAAC,IAAY;QACrB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9D,CAAC;CACJ;AATD,gCASC","sourcesContent":["/**\n * Graph Names\n *\n * Shared helper for turning a scoped project name into the short display name\n * used everywhere in the visualization (graph box titles, the lock-control\n * options, and the responsibilities cards). Kept in its own class so both\n * GraphVisualizer and ResponsibilitiesRenderer can depend on it without a\n * circular dependency between them.\n */\n\nexport class GraphNames {\n    /**\n     * Remove scope from name for display\n     * '@scope/name' → 'name'\n     * 'name' → 'name'\n     */\n    getShortName(name: string): string {\n        return name.includes('/') ? name.split('/').pop()! : name;\n    }\n}\n"]}
+{"version":3,"file":"graph-names.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-names.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;;;AAEH,sFAAsF;AACtF,MAAa,WAAW;IAEA;IACA;IAFpB,YACoB,UAAkB,EAClB,KAAa;QADb,eAAU,GAAV,UAAU,CAAQ;QAClB,UAAK,GAAL,KAAK,CAAQ;IAC9B,CAAC;CACP;AALD,kCAKC;AAED,iFAAiF;AACjF,MAAa,oBAAqB,SAAQ,KAAK;IAC3C,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACvC,CAAC;CACJ;AALD,oDAKC;AAED,MAAa,UAAU;IACnB;;;;;;OAMG;IACH,SAAS,CAAC,UAAkB;QACxB,OAAO,UAAU,CAAC;IACtB,CAAC;IAED;;;;;;OAMG;IACH,YAAY,CAAC,IAAY;QACrB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9D,CAAC;IAED;;;;;OAKG;IACH,mBAAmB,CAAC,MAAqB;QACrC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAyB,CAAC;QAClD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAChD,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACtC,IAAI,QAAQ,KAAK,SAAS;gBAAE,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;;gBACrD,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9B,CAAC;QACD,MAAM,UAAU,GAAa,EAAE,CAAC;QAChC,KAAK,MAAM,MAAM,IAAI,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YAC/C,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAkB,CAAC;YACtD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;gBAAE,SAAS;YACjC,MAAM,KAAK,GAAG,OAAO;iBAChB,GAAG,CAAC,CAAC,KAAkB,EAAU,EAAE,CAAC,IAAI,KAAK,CAAC,UAAU,OAAO,KAAK,CAAC,KAAK,GAAG,CAAC;iBAC9E,IAAI,EAAE;iBACN,IAAI,CAAC,OAAO,CAAC,CAAC;YACnB,UAAU,CAAC,IAAI,CAAC,WAAW,MAAM,wBAAwB,KAAK,EAAE,CAAC,CAAC;QACtE,CAAC;QACD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACpC,MAAM,IAAI,oBAAoB,CAC1B,uFAAuF;cACrF,oEAAoE;cACpE,UAAU,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;cAC5B,qFAAqF;cACrF,4EAA4E,CAAC,CAAC;IACxF,CAAC;CACJ;AAvDD,gCAuDC","sourcesContent":["/**\n * Graph Names\n *\n * The two names a project has in the visualization, kept apart on purpose:\n *\n *  - its NODE ID — the identity every DOT node, edge endpoint, `rank=same` member, lock-dropdown\n *    value and responsibilities `data-node` attribute is keyed on. It is the project KEY, verbatim.\n *  - its SHORT NAME — the human-facing label, with the `@scope/` prefix stripped.\n *\n * They used to be the same string, and that was a silent, badly-wrong-picture bug. A workspace may\n * legitimately hold `@scope/public-api` (an L0 contract lib) AND `public-api` (the L6 server that\n * serves it) — two DISTINCT projects that strip to the same short name. Keying the DOT on the short\n * name fused them into one node, and graphviz UNIONS any two `rank=same` sets sharing a node, so\n * L0's rank and L6's rank became one rank: the entire L0 band rendered on the L6 row, the invisible\n * anchor chain that pins level order became unsatisfiable (it demands L0 strictly below L6 while the\n * union says they are equal) and was discarded, and the server's dependency on the contract lib drew\n * as a self-loop on the fused box.\n *\n * So identity is the project key and nothing else — collision is structurally impossible now rather\n * than merely unlikely — and {@link GraphNames.assertUniqueNodeIds} asserts that, so a future change\n * that reintroduces a lossy id fails generation loudly instead of drawing a wrong graph in silence.\n *\n * Kept in its own class so GraphVisualizer and ResponsibilitiesRenderer can both depend on it\n * without a circular dependency between them.\n */\n\n/** One project key and the level it sits on — what a collision report has to name. */\nexport class NodeIdOwner {\n    constructor(\n        public readonly projectKey: string,\n        public readonly level: number,\n    ) {}\n}\n\n/** Thrown when two distinct project keys would be drawn as the same DOT node. */\nexport class NodeIdCollisionError extends Error {\n    constructor(message: string) {\n        super(message);\n        this.name = 'NodeIdCollisionError';\n    }\n}\n\nexport class GraphNames {\n    /**\n     * The DOT/DOM identity of a project: its project KEY, unchanged.\n     *\n     * This is deliberately a named method rather than an inlined `project` at ten call sites — the\n     * node id is one decision, and it has to be made in one place or the DOT, the lock dropdown and\n     * the responsibilities cards drift apart and the hover/lock wiring silently stops matching.\n     */\n    getNodeId(projectKey: string): string {\n        return projectKey;\n    }\n\n    /**\n     * The human-facing display name: scope stripped.\n     * '@scope/name' → 'name'\n     * 'name' → 'name'\n     *\n     * LABELS ONLY. Never use this as an identity — see this file's header for what that cost.\n     */\n    getShortName(name: string): string {\n        return name.includes('/') ? name.split('/').pop()! : name;\n    }\n\n    /**\n     * Assert that every project draws as its own node.\n     *\n     * Fails LOUDLY, naming both colliding project keys and their levels, because the failure mode it\n     * guards is a graph that renders happily and says something false.\n     */\n    assertUniqueNodeIds(owners: NodeIdOwner[]): void {\n        const byNodeId = new Map<string, NodeIdOwner[]>();\n        for (const owner of owners) {\n            const nodeId = this.getNodeId(owner.projectKey);\n            const existing = byNodeId.get(nodeId);\n            if (existing === undefined) byNodeId.set(nodeId, [owner]);\n            else existing.push(owner);\n        }\n        const collisions: string[] = [];\n        for (const nodeId of [...byNodeId.keys()].sort()) {\n            const sharers = byNodeId.get(nodeId) as NodeIdOwner[];\n            if (sharers.length < 2) continue;\n            const named = sharers\n                .map((owner: NodeIdOwner): string => `\"${owner.projectKey}\" (L${owner.level})`)\n                .sort()\n                .join(' and ');\n            collisions.push(`  node \"${nodeId}\" would be drawn for ${named}`);\n        }\n        if (collisions.length === 0) return;\n        throw new NodeIdCollisionError(\n            'Two distinct projects map to the same graph node, so the rendered architecture graph '\n            + 'would fuse them (and fuse their dependency levels into one row):\\n'\n            + collisions.sort().join('\\n')\n            + '\\nFix: getNodeId() must stay a 1:1 function of the project key — it is the project '\n            + 'key verbatim. Only getShortName() may drop the scope, and only for LABELS.');\n    }\n}\n"]}

package/src/lib/graph-responsibilities.d.ts

@@ -6,7 +6,7 @@
  * dependency level HIGH → LOW (top-level apps first, deepest libs last) so a
  * reader scrolls from the runnable servers/clients down into the libraries.
  *
- * Each card carries `data-node="<shortName>"` matching the graph box's title, so
+ * Each card carries `data-node="<projectKey>"` matching the graph box's title, so
  * the page script can filter the list to just the locked box's chain (see
  * graph-visualizer.client.ts). The summary paragraph is the `shortDescription`
  * already on each graph entry; the expanded body is the rendered markdown file.

package/src/lib/graph-responsibilities.js

@@ -7,7 +7,7 @@
  * dependency level HIGH → LOW (top-level apps first, deepest libs last) so a
  * reader scrolls from the runnable servers/clients down into the libraries.
  *
- * Each card carries `data-node="<shortName>"` matching the graph box's title, so
+ * Each card carries `data-node="<projectKey>"` matching the graph box's title, so
  * the page script can filter the list to just the locked box's chain (see
  * graph-visualizer.client.ts). The summary paragraph is the `shortDescription`
  * already on each graph entry; the expanded body is the rendered markdown file.
@@ -56,11 +56,15 @@ class ResponsibilitiesRenderer {
             `</section>`);
     }
     renderCard(project, entry, workspaceRoot) {
+        // data-node is the graph box's IDENTITY (the project key, matching the SVG <title>); the
+        // heading stays the pretty short name. Keying the attribute on the short name is what let
+        // two same-named projects share one card's visibility — see graph-names.ts.
+        const nodeId = this.names.getNodeId(project);
         const shortName = this.names.getShortName(project);
         const summary = entry.shortDescription ?? '';
         const summaryHtml = summary ? ` — ${this.escapeHtml(summary)}` : '';
         const body = this.readBody(entry, workspaceRoot);
-        return (`<details class="wp-resp-card" data-node="${this.escapeHtml(shortName)}">` +
+        return (`<details class="wp-resp-card" data-node="${this.escapeHtml(nodeId)}">` +
             `<summary><span class="wp-resp-level">L${entry.level}</span> ` +
             `<strong>${this.escapeHtml(shortName)}</strong>${summaryHtml}</summary>` +
             `<div class="wp-resp-body">${body}</div>` +

package/src/lib/graph-responsibilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph-responsibilities.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-responsibilities.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Responsibilities Section\n *\n * Renders every module's full `responsibilities.md` as a collapsible card below\n * the dependency graph in architecture/dependencies.html. Cards are ordered by\n * dependency level HIGH → LOW (top-level apps first, deepest libs last) so a\n * reader scrolls from the runnable servers/clients down into the libraries.\n *\n * Each card carries `data-node=\"<shortName>\"` matching the graph box's title, so\n * the page script can filter the list to just the locked box's chain (see\n * graph-visualizer.client.ts). The summary paragraph is the `shortDescription`\n * already on each graph entry; the expanded body is the rendered markdown file.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport type { EnhancedGraph, GraphEntry } from './graph-sorter';\nimport { GraphNames } from './graph-names';\n\n/**\n * Mutable cursor state threaded through the markdown line renderer: whether we\n * are currently inside an open `<ul>` (so the next blank line / heading / non-\n * bullet closes it).\n */\nclass MarkdownListState {\n    inList = false;\n}\n\nexport class ResponsibilitiesRenderer {\n    private readonly names = new GraphNames();\n\n    /**\n     * Build the responsibilities section HTML: one collapsible card per module,\n     * sorted by level descending (tie-break by name ascending). Returned as a\n     * <section> that GraphVisualizer injects below the graph.\n     */\n    generateSection(graph: EnhancedGraph, workspaceRoot: string): string {\n        const projects = Object.keys(graph);\n        projects.sort((a: string, b: string): number => {\n            const levelDiff = graph[b].level - graph[a].level;\n            if (levelDiff !== 0) return levelDiff;\n            return a.localeCompare(b);\n        });\n\n        const cards: string[] = [];\n        for (const project of projects) {\n            // Hidden projects (drawOnGraph:false) are omitted from the graph, so\n            // they get no responsibilities card either.\n            if (graph[project].drawOnGraph === false) continue;\n            cards.push(this.renderCard(project, graph[project], workspaceRoot));\n        }\n\n        return (\n            `<section id=\"wp-responsibilities\">` +\n            `<h2>Responsibilities (level high → low)</h2>` +\n            `<p class=\"hint\">Lock a box above to narrow this list to just that box's dependency chain.</p>` +\n            cards.join('\\n') +\n            `</section>`\n        );\n    }\n\n    private renderCard(project: string, entry: GraphEntry, workspaceRoot: string): string {\n        const shortName = this.names.getShortName(project);\n        const summary = entry.shortDescription ?? '';\n        const summaryHtml = summary ? ` — ${this.escapeHtml(summary)}` : '';\n        const body = this.readBody(entry, workspaceRoot);\n        return (\n            `<details class=\"wp-resp-card\" data-node=\"${this.escapeHtml(shortName)}\">` +\n            `<summary><span class=\"wp-resp-level\">L${entry.level}</span> ` +\n            `<strong>${this.escapeHtml(shortName)}</strong>${summaryHtml}</summary>` +\n            `<div class=\"wp-resp-body\">${body}</div>` +\n            `</details>`\n        );\n    }\n\n    /**\n     * Read a module's responsibilities.md body. Generation already guarantees the\n     * file exists (metadata validation throws otherwise); a fallback line guards\n     * the edge case where the graph JSON is stale relative to disk.\n     */\n    private readBody(entry: GraphEntry, workspaceRoot: string): string {\n        const file = entry.responsibilitiesFile;\n        if (!file) return '<p><em>No responsibilities.md recorded for this module.</em></p>';\n        const absolutePath = path.join(workspaceRoot, file);\n        if (!fs.existsSync(absolutePath)) {\n            return `<p><em>Missing ${this.escapeHtml(file)}.</em></p>`;\n        }\n        return this.renderMarkdown(fs.readFileSync(absolutePath, 'utf-8'));\n    }\n\n    /**\n     * Minimal markdown → HTML for a responsibilities.md body. Handles ATX headings\n     * (`#`..`######`), `-`/`*` bullet lists, and blank-line-separated paragraphs.\n     * Everything is HTML-escaped first; only a small inline set is re-marked. This\n     * is deliberately tiny — responsibilities.md files are short and structured,\n     * and the repo has no markdown dependency.\n     */\n    private renderMarkdown(markdown: string): string {\n        const out: string[] = [];\n        const state = new MarkdownListState();\n        for (const rawLine of markdown.split('\\n')) {\n            this.renderLine(rawLine.trim(), out, state);\n        }\n        if (state.inList) out.push('</ul>');\n        return out.join('\\n');\n    }\n\n    private renderLine(line: string, out: string[], state: MarkdownListState): void {\n        const heading = /^(#{1,6})\\s+(.*)$/.exec(line);\n        const bullet = /^[-*]\\s+(.*)$/.exec(line);\n        if (line.length === 0) {\n            if (state.inList) { out.push('</ul>'); state.inList = false; }\n            return;\n        }\n        if (heading) {\n            if (state.inList) { out.push('</ul>'); state.inList = false; }\n            const level = Math.min(heading[1].length + 3, 6); // # → h4, ## → h5, deeper → h6\n            out.push(`<h${level}>${this.renderInline(this.escapeHtml(heading[2]))}</h${level}>`);\n            return;\n        }\n        if (bullet) {\n            if (!state.inList) { out.push('<ul>'); state.inList = true; }\n            out.push(`<li>${this.renderInline(this.escapeHtml(bullet[1]))}</li>`);\n            return;\n        }\n        if (state.inList) { out.push('</ul>'); state.inList = false; }\n        out.push(`<p>${this.renderInline(this.escapeHtml(line))}</p>`);\n    }\n\n    /**\n     * Render inline markdown spans within an already HTML-escaped line: `code` →\n     * <code>, **bold** → <strong>, *italic* → <em>.\n     */\n    private renderInline(escaped: string): string {\n        return escaped\n            .replace(/`([^`]+)`/g, '<code>$1</code>')\n            .replace(/\\*\\*([^*]+)\\*\\*/g, '<strong>$1</strong>')\n            .replace(/(^|[^*])\\*([^*]+)\\*/g, '$1<em>$2</em>');\n    }\n\n    /**\n     * Escape a string for safe embedding in HTML text/attributes.\n     */\n    private escapeHtml(text: string): string {\n        return text\n            .replace(/&/g, '&amp;')\n            .replace(/</g, '&lt;')\n            .replace(/>/g, '&gt;')\n            .replace(/\"/g, '&quot;');\n    }\n}\n"]}
+{"version":3,"file":"graph-responsibilities.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-responsibilities.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Responsibilities Section\n *\n * Renders every module's full `responsibilities.md` as a collapsible card below\n * the dependency graph in architecture/dependencies.html. Cards are ordered by\n * dependency level HIGH → LOW (top-level apps first, deepest libs last) so a\n * reader scrolls from the runnable servers/clients down into the libraries.\n *\n * Each card carries `data-node=\"<projectKey>\"` matching the graph box's title, so\n * the page script can filter the list to just the locked box's chain (see\n * graph-visualizer.client.ts). The summary paragraph is the `shortDescription`\n * already on each graph entry; the expanded body is the rendered markdown file.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport type { EnhancedGraph, GraphEntry } from './graph-sorter';\nimport { GraphNames } from './graph-names';\n\n/**\n * Mutable cursor state threaded through the markdown line renderer: whether we\n * are currently inside an open `<ul>` (so the next blank line / heading / non-\n * bullet closes it).\n */\nclass MarkdownListState {\n    inList = false;\n}\n\nexport class ResponsibilitiesRenderer {\n    private readonly names = new GraphNames();\n\n    /**\n     * Build the responsibilities section HTML: one collapsible card per module,\n     * sorted by level descending (tie-break by name ascending). Returned as a\n     * <section> that GraphVisualizer injects below the graph.\n     */\n    generateSection(graph: EnhancedGraph, workspaceRoot: string): string {\n        const projects = Object.keys(graph);\n        projects.sort((a: string, b: string): number => {\n            const levelDiff = graph[b].level - graph[a].level;\n            if (levelDiff !== 0) return levelDiff;\n            return a.localeCompare(b);\n        });\n\n        const cards: string[] = [];\n        for (const project of projects) {\n            // Hidden projects (drawOnGraph:false) are omitted from the graph, so\n            // they get no responsibilities card either.\n            if (graph[project].drawOnGraph === false) continue;\n            cards.push(this.renderCard(project, graph[project], workspaceRoot));\n        }\n\n        return (\n            `<section id=\"wp-responsibilities\">` +\n            `<h2>Responsibilities (level high → low)</h2>` +\n            `<p class=\"hint\">Lock a box above to narrow this list to just that box's dependency chain.</p>` +\n            cards.join('\\n') +\n            `</section>`\n        );\n    }\n\n    private renderCard(project: string, entry: GraphEntry, workspaceRoot: string): string {\n        // data-node is the graph box's IDENTITY (the project key, matching the SVG <title>); the\n        // heading stays the pretty short name. Keying the attribute on the short name is what let\n        // two same-named projects share one card's visibility — see graph-names.ts.\n        const nodeId = this.names.getNodeId(project);\n        const shortName = this.names.getShortName(project);\n        const summary = entry.shortDescription ?? '';\n        const summaryHtml = summary ? ` — ${this.escapeHtml(summary)}` : '';\n        const body = this.readBody(entry, workspaceRoot);\n        return (\n            `<details class=\"wp-resp-card\" data-node=\"${this.escapeHtml(nodeId)}\">` +\n            `<summary><span class=\"wp-resp-level\">L${entry.level}</span> ` +\n            `<strong>${this.escapeHtml(shortName)}</strong>${summaryHtml}</summary>` +\n            `<div class=\"wp-resp-body\">${body}</div>` +\n            `</details>`\n        );\n    }\n\n    /**\n     * Read a module's responsibilities.md body. Generation already guarantees the\n     * file exists (metadata validation throws otherwise); a fallback line guards\n     * the edge case where the graph JSON is stale relative to disk.\n     */\n    private readBody(entry: GraphEntry, workspaceRoot: string): string {\n        const file = entry.responsibilitiesFile;\n        if (!file) return '<p><em>No responsibilities.md recorded for this module.</em></p>';\n        const absolutePath = path.join(workspaceRoot, file);\n        if (!fs.existsSync(absolutePath)) {\n            return `<p><em>Missing ${this.escapeHtml(file)}.</em></p>`;\n        }\n        return this.renderMarkdown(fs.readFileSync(absolutePath, 'utf-8'));\n    }\n\n    /**\n     * Minimal markdown → HTML for a responsibilities.md body. Handles ATX headings\n     * (`#`..`######`), `-`/`*` bullet lists, and blank-line-separated paragraphs.\n     * Everything is HTML-escaped first; only a small inline set is re-marked. This\n     * is deliberately tiny — responsibilities.md files are short and structured,\n     * and the repo has no markdown dependency.\n     */\n    private renderMarkdown(markdown: string): string {\n        const out: string[] = [];\n        const state = new MarkdownListState();\n        for (const rawLine of markdown.split('\\n')) {\n            this.renderLine(rawLine.trim(), out, state);\n        }\n        if (state.inList) out.push('</ul>');\n        return out.join('\\n');\n    }\n\n    private renderLine(line: string, out: string[], state: MarkdownListState): void {\n        const heading = /^(#{1,6})\\s+(.*)$/.exec(line);\n        const bullet = /^[-*]\\s+(.*)$/.exec(line);\n        if (line.length === 0) {\n            if (state.inList) { out.push('</ul>'); state.inList = false; }\n            return;\n        }\n        if (heading) {\n            if (state.inList) { out.push('</ul>'); state.inList = false; }\n            const level = Math.min(heading[1].length + 3, 6); // # → h4, ## → h5, deeper → h6\n            out.push(`<h${level}>${this.renderInline(this.escapeHtml(heading[2]))}</h${level}>`);\n            return;\n        }\n        if (bullet) {\n            if (!state.inList) { out.push('<ul>'); state.inList = true; }\n            out.push(`<li>${this.renderInline(this.escapeHtml(bullet[1]))}</li>`);\n            return;\n        }\n        if (state.inList) { out.push('</ul>'); state.inList = false; }\n        out.push(`<p>${this.renderInline(this.escapeHtml(line))}</p>`);\n    }\n\n    /**\n     * Render inline markdown spans within an already HTML-escaped line: `code` →\n     * <code>, **bold** → <strong>, *italic* → <em>.\n     */\n    private renderInline(escaped: string): string {\n        return escaped\n            .replace(/`([^`]+)`/g, '<code>$1</code>')\n            .replace(/\\*\\*([^*]+)\\*\\*/g, '<strong>$1</strong>')\n            .replace(/(^|[^*])\\*([^*]+)\\*/g, '$1<em>$2</em>');\n    }\n\n    /**\n     * Escape a string for safe embedding in HTML text/attributes.\n     */\n    private escapeHtml(text: string): string {\n        return text\n            .replace(/&/g, '&amp;')\n            .replace(/</g, '&lt;')\n            .replace(/>/g, '&gt;')\n            .replace(/\"/g, '&quot;');\n    }\n}\n"]}

package/src/lib/graph-sorter.js

@@ -10,6 +10,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.computeTopologicalLayers = computeTopologicalLayers;
 exports.sortGraphTopologically = sortGraphTopologically;
+const graph_cycles_1 = require("./graph-cycles");
 /**
  * Compute topological layers for dependency graph using Kahn's algorithm
  *
@@ -36,13 +37,13 @@ function computeTopologicalLayers(graph) {
             }
         }
         if (currentLayer.length === 0) {
-            // No progress made = circular dependency detected
+            // No progress made = circular dependency. ProjectCycleDetector is the ONE cycle
+            // implementation in this package — it names every chain, in project keys, with the
+            // fix — so this reports through it rather than keeping a second, weaker DFS here.
+            new graph_cycles_1.ProjectCycleDetector().assertAcyclic(graph, 'the project graph');
+            // Unreachable: Kahn only stalls on a cycle, and the assert above throws on every one.
             const remaining = allProjects.filter((p) => !processed.has(p));
-            // Try to identify the cycle
-            const cycleInfo = findCycle(graph, remaining);
-            throw new Error(`Circular dependency detected among: ${remaining.join(', ')}\n` +
-                (cycleInfo ? `Cycle: ${cycleInfo}\n` : '') +
-                'Fix: Remove one of the dependencies to break the cycle.');
+            throw new Error(`Topological sort stalled with no cycle to report — projects left unlayered: ${remaining.join(', ')}`);
         }
         // Sort alphabetically within layer for deterministic output
         currentLayer.sort();
@@ -52,39 +53,6 @@ function computeTopologicalLayers(graph) {
     }
     return layers;
 }
-/**
- * Try to find and describe a cycle in the graph
- */
-function findCycle(graph, remaining) {
-    const visited = new Set();
-    const path = [];
-    function dfs(node) {
-        if (path.includes(node)) {
-            const cycleStart = path.indexOf(node);
-            return [...path.slice(cycleStart), node].join(' -> ');
-        }
-        if (visited.has(node))
-            return null;
-        visited.add(node);
-        path.push(node);
-        const deps = graph[node] || [];
-        for (const dep of deps) {
-            if (remaining.includes(dep)) {
-                const result = dfs(dep);
-                if (result)
-                    return result;
-            }
-        }
-        path.pop();
-        return null;
-    }
-    for (const node of remaining) {
-        const cycle = dfs(node);
-        if (cycle)
-            return cycle;
-    }
-    return null;
-}
 /**
  * Sort graph in topological order with alphabetical sorting within layers
  * Returns enhanced format with level metadata

package/src/lib/graph-sorter.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph-sorter.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-sorter.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Graph Sorter\n *\n * Performs topological sorting on the dependency graph to:\n * 1. Detect circular dependencies (fails if cycle found)\n * 2. Assign level numbers to each project (level 0 = no deps, level 1 = depends on level 0, etc.)\n * 3. Group projects into layers for deterministic ordering\n */\n\nimport type { ProjectApiRelations } from './api-usage/api-relations';\n\n/**\n * Graph entry with level metadata plus AI-oriented metadata filled in by\n * enrichGraph() (lib/graph-metadata.ts) before the graph is saved:\n *  - framework: the project's libType — the SET of runtime environments it is\n *    validated to run in, drawn from browser | react | angular | node | express\n *    (e.g. [\"browser\",\"node\"]); from its `framework:` nx tags (source of truth)\n *    or inferred from package.json deps\n *  - shortDescription: summary extracted from the project's responsibilities.md\n *  - responsibilitiesFile: repo-relative path to the FULL responsibilities doc\n *  - designFile: repo-relative path to the generated DI design.json (only for\n *    project.json projects)\n *  - apiRelations: for each api-lib in `dependsOn`, WHY the edge exists — the\n *    APIs this project implements (serves) and/or uses (calls), each with its\n *    transport (rpc | pubsub). Derived by scanning source (see api-usage/).\n */\nexport interface GraphEntry {\n    level: number;\n    dependsOn: string[];\n    framework?: string[];\n    role?: string;\n    /**\n     * The name CLIENTS address this app by at runtime (`new ClientConfig('helper-fsdb')`) — its\n     * deployed service name, DECLARED in project.json as metadata.webpieces.serviceName. Absent for\n     * anything nothing calls by name (libraries, browser apps). See service-name-resolver.ts.\n     */\n    serviceName?: string;\n    /**\n     * The service(s) this project's clients call when the call site cannot carry a literal\n     * `ClientConfig` — the symmetric half of `serviceName`. DECLARED in project.json as\n     * metadata.webpieces.callsService, either a single service name (every untargeted `uses` aims\n     * there) or an `{ apiClassName: serviceName }` map (a client that calls several). Absent for a\n     * project that never calls anything, or one whose call sites all carry literals.\n     * See service-name-resolver.ts.\n     */\n    callsService?: string | Record<string, string>;\n    /**\n     * When false, the project is hidden from the rendered architecture graphs\n     * (its box AND every edge touching it are omitted from dependencies.html and\n     * the runtime graph). It stays in this JSON so the data view is complete.\n     * Absent means drawn (the default). From the project's `drawOnGraph:` nx tag.\n     */\n    drawOnGraph?: boolean;\n    shortDescription?: string;\n    responsibilitiesFile?: string;\n    designFile?: string;\n    apiRelations?: ProjectApiRelations;\n    /**\n     * The @webpieces runtime packages this project's OWN package.json declares — http-routing,\n     * http-server, http-client-node, http-client-browser, cloudtasks-client. Omitted when it\n     * declares none, so TOTAL absence across the file means the file predates this field and\n     * nothing is auto-hidden (see runtime-graph.ts). Core/util/logging packages are deliberately\n     * not markers; see runtime-participant-resolver.ts for why.\n     *\n     * The runtime graph ORs this over a node's library closure: a server whose whole webpieces\n     * stack comes from a shared bootstrap lib participates even though it declares nothing itself.\n     */\n    webpiecesRuntime?: string[];\n}\n\n/**\n * Enhanced graph format with level information\n */\nexport type EnhancedGraph = Record<string, GraphEntry>;\n\n/**\n * Compute topological layers for dependency graph using Kahn's algorithm\n *\n * Projects are grouped into layers where each layer only depends on previous layers.\n * Throws an error if a circular dependency is detected.\n *\n * @param graph - Dependency graph { project: [deps] }\n * @returns Array of layers, each containing sorted project names\n */\nexport function computeTopologicalLayers(graph: Record<string, string[]>): string[][] {\n    const layers: string[][] = [];\n    const processed = new Set<string>();\n    const allProjects = Object.keys(graph);\n\n    while (processed.size < allProjects.length) {\n        const currentLayer: string[] = [];\n\n        for (const project of allProjects) {\n            if (processed.has(project)) continue;\n\n            const deps = graph[project] || [];\n            // Check if all dependencies are in previous layers (already processed)\n            const allDepsInPrevLayers = deps.every((dep) => processed.has(dep));\n\n            if (allDepsInPrevLayers) {\n                currentLayer.push(project);\n            }\n        }\n\n        if (currentLayer.length === 0) {\n            // No progress made = circular dependency detected\n            const remaining = allProjects.filter((p) => !processed.has(p));\n\n            // Try to identify the cycle\n            const cycleInfo = findCycle(graph, remaining);\n\n            throw new Error(\n                `Circular dependency detected among: ${remaining.join(', ')}\\n` +\n                    (cycleInfo ? `Cycle: ${cycleInfo}\\n` : '') +\n                    'Fix: Remove one of the dependencies to break the cycle.'\n            );\n        }\n\n        // Sort alphabetically within layer for deterministic output\n        currentLayer.sort();\n        layers.push(currentLayer);\n\n        // Mark as processed\n        currentLayer.forEach((p) => processed.add(p));\n    }\n\n    return layers;\n}\n\n/**\n * Try to find and describe a cycle in the graph\n */\nfunction findCycle(graph: Record<string, string[]>, remaining: string[]): string | null {\n    const visited = new Set<string>();\n    const path: string[] = [];\n\n    function dfs(node: string): string | null {\n        if (path.includes(node)) {\n            const cycleStart = path.indexOf(node);\n            return [...path.slice(cycleStart), node].join(' -> ');\n        }\n        if (visited.has(node)) return null;\n\n        visited.add(node);\n        path.push(node);\n\n        const deps = graph[node] || [];\n        for (const dep of deps) {\n            if (remaining.includes(dep)) {\n                const result = dfs(dep);\n                if (result) return result;\n            }\n        }\n\n        path.pop();\n        return null;\n    }\n\n    for (const node of remaining) {\n        const cycle = dfs(node);\n        if (cycle) return cycle;\n    }\n\n    return null;\n}\n\n/**\n * Sort graph in topological order with alphabetical sorting within layers\n * Returns enhanced format with level metadata\n *\n * @param graph - Unsorted dependency graph { project: [deps] }\n * @returns Sorted graph with level metadata { project: { level: number, dependsOn: [deps] } }\n */\nexport function sortGraphTopologically(graph: Record<string, string[]>): EnhancedGraph {\n    const layers = computeTopologicalLayers(graph);\n    const result: EnhancedGraph = {};\n\n    // Add projects layer by layer (dependencies before dependents)\n    layers.forEach((layer, levelIndex) => {\n        for (const project of layer) {\n            // Already sorted alphabetically within layer\n            result[project] = {\n                level: levelIndex,\n                dependsOn: (graph[project] || []).sort(),\n            };\n        }\n    });\n\n    return result;\n}\n"]}
+{"version":3,"file":"graph-sorter.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-sorter.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AA8EH,4DAwCC;AASD,wDAgBC;AA5ID,iDAAsD;AAkEtD;;;;;;;;GAQG;AACH,SAAgB,wBAAwB,CAAC,KAA+B;IACpE,MAAM,MAAM,GAAe,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;IACpC,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAEvC,OAAO,SAAS,CAAC,IAAI,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC;QACzC,MAAM,YAAY,GAAa,EAAE,CAAC;QAElC,KAAK,MAAM,OAAO,IAAI,WAAW,EAAE,CAAC;YAChC,IAAI,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC;gBAAE,SAAS;YAErC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YAClC,uEAAuE;YACvE,MAAM,mBAAmB,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;YAEpE,IAAI,mBAAmB,EAAE,CAAC;gBACtB,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC/B,CAAC;QACL,CAAC;QAED,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,gFAAgF;YAChF,mFAAmF;YACnF,kFAAkF;YAClF,IAAI,mCAAoB,EAAE,CAAC,aAAa,CAAC,KAAK,EAAE,mBAAmB,CAAC,CAAC;YACrE,sFAAsF;YACtF,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAS,EAAW,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAChF,MAAM,IAAI,KAAK,CACX,+EAA+E,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC/G,CAAC;QAED,4DAA4D;QAC5D,YAAY,CAAC,IAAI,EAAE,CAAC;QACpB,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAE1B,oBAAoB;QACpB,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAClD,CAAC;IAED,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,sBAAsB,CAAC,KAA+B;IAClE,MAAM,MAAM,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAkB,EAAE,CAAC;IAEjC,+DAA+D;IAC/D,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE;QACjC,KAAK,MAAM,OAAO,IAAI,KAAK,EAAE,CAAC;YAC1B,6CAA6C;YAC7C,MAAM,CAAC,OAAO,CAAC,GAAG;gBACd,KAAK,EAAE,UAAU;gBACjB,SAAS,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;aAC3C,CAAC;QACN,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAClB,CAAC","sourcesContent":["/**\n * Graph Sorter\n *\n * Performs topological sorting on the dependency graph to:\n * 1. Detect circular dependencies (fails if cycle found)\n * 2. Assign level numbers to each project (level 0 = no deps, level 1 = depends on level 0, etc.)\n * 3. Group projects into layers for deterministic ordering\n */\n\nimport type { ProjectApiRelations } from './api-usage/api-relations';\nimport { ProjectCycleDetector } from './graph-cycles';\n\n/**\n * Graph entry with level metadata plus AI-oriented metadata filled in by\n * enrichGraph() (lib/graph-metadata.ts) before the graph is saved:\n *  - framework: the project's libType — the SET of runtime environments it is\n *    validated to run in, drawn from browser | react | angular | node | express\n *    (e.g. [\"browser\",\"node\"]); from its `framework:` nx tags (source of truth)\n *    or inferred from package.json deps\n *  - shortDescription: summary extracted from the project's responsibilities.md\n *  - responsibilitiesFile: repo-relative path to the FULL responsibilities doc\n *  - designFile: repo-relative path to the generated DI design.json (only for\n *    project.json projects)\n *  - apiRelations: for each api-lib in `dependsOn`, WHY the edge exists — the\n *    APIs this project implements (serves) and/or uses (calls), each with its\n *    transport (rpc | pubsub). Derived by scanning source (see api-usage/).\n */\nexport interface GraphEntry {\n    level: number;\n    dependsOn: string[];\n    framework?: string[];\n    role?: string;\n    /**\n     * The name CLIENTS address this app by at runtime (`new ClientConfig('helper-fsdb')`) — its\n     * deployed service name, DECLARED in project.json as metadata.webpieces.serviceName. Absent for\n     * anything nothing calls by name (libraries, browser apps). See service-name-resolver.ts.\n     */\n    serviceName?: string;\n    /**\n     * The service(s) this project's clients call when the call site cannot carry a literal\n     * `ClientConfig` — the symmetric half of `serviceName`. DECLARED in project.json as\n     * metadata.webpieces.callsService, either a single service name (every untargeted `uses` aims\n     * there) or an `{ apiClassName: serviceName }` map (a client that calls several). Absent for a\n     * project that never calls anything, or one whose call sites all carry literals.\n     * See service-name-resolver.ts.\n     */\n    callsService?: string | Record<string, string>;\n    /**\n     * When false, the project is hidden from the rendered architecture graphs\n     * (its box AND every edge touching it are omitted from dependencies.html and\n     * the runtime graph). It stays in this JSON so the data view is complete.\n     * Absent means drawn (the default). From the project's `drawOnGraph:` nx tag.\n     */\n    drawOnGraph?: boolean;\n    shortDescription?: string;\n    responsibilitiesFile?: string;\n    designFile?: string;\n    apiRelations?: ProjectApiRelations;\n    /**\n     * The @webpieces runtime packages this project's OWN package.json declares — http-routing,\n     * http-server, http-client-node, http-client-browser, cloudtasks-client. Omitted when it\n     * declares none, so TOTAL absence across the file means the file predates this field and\n     * nothing is auto-hidden (see runtime-graph.ts). Core/util/logging packages are deliberately\n     * not markers; see runtime-participant-resolver.ts for why.\n     *\n     * The runtime graph ORs this over a node's library closure: a server whose whole webpieces\n     * stack comes from a shared bootstrap lib participates even though it declares nothing itself.\n     */\n    webpiecesRuntime?: string[];\n}\n\n/**\n * Enhanced graph format with level information\n */\nexport type EnhancedGraph = Record<string, GraphEntry>;\n\n/**\n * Compute topological layers for dependency graph using Kahn's algorithm\n *\n * Projects are grouped into layers where each layer only depends on previous layers.\n * Throws an error if a circular dependency is detected.\n *\n * @param graph - Dependency graph { project: [deps] }\n * @returns Array of layers, each containing sorted project names\n */\nexport function computeTopologicalLayers(graph: Record<string, string[]>): string[][] {\n    const layers: string[][] = [];\n    const processed = new Set<string>();\n    const allProjects = Object.keys(graph);\n\n    while (processed.size < allProjects.length) {\n        const currentLayer: string[] = [];\n\n        for (const project of allProjects) {\n            if (processed.has(project)) continue;\n\n            const deps = graph[project] || [];\n            // Check if all dependencies are in previous layers (already processed)\n            const allDepsInPrevLayers = deps.every((dep) => processed.has(dep));\n\n            if (allDepsInPrevLayers) {\n                currentLayer.push(project);\n            }\n        }\n\n        if (currentLayer.length === 0) {\n            // No progress made = circular dependency. ProjectCycleDetector is the ONE cycle\n            // implementation in this package — it names every chain, in project keys, with the\n            // fix — so this reports through it rather than keeping a second, weaker DFS here.\n            new ProjectCycleDetector().assertAcyclic(graph, 'the project graph');\n            // Unreachable: Kahn only stalls on a cycle, and the assert above throws on every one.\n            const remaining = allProjects.filter((p: string): boolean => !processed.has(p));\n            throw new Error(\n                `Topological sort stalled with no cycle to report — projects left unlayered: ${remaining.join(', ')}`);\n        }\n\n        // Sort alphabetically within layer for deterministic output\n        currentLayer.sort();\n        layers.push(currentLayer);\n\n        // Mark as processed\n        currentLayer.forEach((p) => processed.add(p));\n    }\n\n    return layers;\n}\n\n/**\n * Sort graph in topological order with alphabetical sorting within layers\n * Returns enhanced format with level metadata\n *\n * @param graph - Unsorted dependency graph { project: [deps] }\n * @returns Sorted graph with level metadata { project: { level: number, dependsOn: [deps] } }\n */\nexport function sortGraphTopologically(graph: Record<string, string[]>): EnhancedGraph {\n    const layers = computeTopologicalLayers(graph);\n    const result: EnhancedGraph = {};\n\n    // Add projects layer by layer (dependencies before dependents)\n    layers.forEach((layer, levelIndex) => {\n        for (const project of layer) {\n            // Already sorted alphabetically within layer\n            result[project] = {\n                level: levelIndex,\n                dependsOn: (graph[project] || []).sort(),\n            };\n        }\n    });\n\n    return result;\n}\n"]}

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

@@ -33,6 +33,7 @@ export declare class GraphVisualizer {
     private readonly names;
     private readonly responsibilities;
     private readonly bandLayout;
+    private readonly cycles;
     /**
      * How to obtain the browser client's text. Injected so HTML generation does not depend on BUILD
      * ORDER: the default reads the compiled sibling, which exists in the tarball and in dist but NOT in
@@ -99,6 +100,15 @@ export declare class GraphVisualizer {
      * Generate Graphviz DOT format from the graph
      */
     generateDot(graph: EnhancedGraph, title?: string): string;
+    /**
+     * Refuse to draw a graph that would render something false.
+     *
+     * Two conditions, both of which produced a confidently-wrong picture with no warning at all:
+     *  - two projects sharing a node id fuse into one box, which UNIONS their two rank sets and
+     *    collapses two whole dependency levels onto one row (see graph-names.ts);
+     *  - a cycle makes the level numbers every row is keyed on meaningless (see graph-cycles.ts).
+     */
+    private assertDrawable;
     /**
      * The visible projects grouped into one band per dependency level, ordered HIGHEST LEVEL FIRST
      * so the emitted bands read top-to-bottom with L0 last (hidden projects are omitted, so no

package/src/lib/graph-visualizer.js

@@ -19,6 +19,7 @@ const path = tslib_1.__importStar(require("path"));
 const child_process_1 = require("child_process");
 const graph_names_1 = require("./graph-names");
 const graph_level_bands_1 = require("./graph-level-bands");
+const graph_cycles_1 = require("./graph-cycles");
 const graph_responsibilities_1 = require("./graph-responsibilities");
 const toError_1 = require("../toError");
 /**
@@ -76,6 +77,7 @@ class GraphVisualizer {
     names = new graph_names_1.GraphNames();
     responsibilities = new graph_responsibilities_1.ResponsibilitiesRenderer();
     bandLayout = new graph_level_bands_1.LevelBandLayout();
+    cycles = new graph_cycles_1.ProjectCycleDetector();
     /**
      * How to obtain the browser client's text. Injected so HTML generation does not depend on BUILD
      * ORDER: the default reads the compiled sibling, which exists in the tarball and in dist but NOT in
@@ -194,6 +196,7 @@ class GraphVisualizer {
      * Generate Graphviz DOT format from the graph
      */
     generateDot(graph, title = 'Monorepo Dependency Architecture') {
+        this.assertDrawable(graph);
         let dot = 'digraph Architecture {\n';
         dot += '  rankdir=TB;\n';
         dot += '  node [shape=box, style=filled, fontname="Arial"];\n';
@@ -210,6 +213,24 @@ class GraphVisualizer {
         dot += '}\n';
         return dot;
     }
+    /**
+     * Refuse to draw a graph that would render something false.
+     *
+     * Two conditions, both of which produced a confidently-wrong picture with no warning at all:
+     *  - two projects sharing a node id fuse into one box, which UNIONS their two rank sets and
+     *    collapses two whole dependency levels onto one row (see graph-names.ts);
+     *  - a cycle makes the level numbers every row is keyed on meaningless (see graph-cycles.ts).
+     */
+    assertDrawable(graph) {
+        const owners = [];
+        const adjacency = {};
+        for (const project of Object.keys(graph)) {
+            owners.push(new graph_names_1.NodeIdOwner(project, graph[project].level));
+            adjacency[project] = graph[project].dependsOn ?? [];
+        }
+        this.names.assertUniqueNodeIds(owners);
+        this.cycles.assertAcyclic(adjacency, 'architecture/dependencies.json');
+    }
     /**
      * The visible projects grouped into one band per dependency level, ordered HIGHEST LEVEL FIRST
      * so the emitted bands read top-to-bottom with L0 last (hidden projects are omitted, so no
@@ -223,11 +244,11 @@ class GraphVisualizer {
             if (this.isHidden(graph[project]))
                 continue;
             const level = graph[project].level;
-            const names = byLevel.get(level);
-            if (names === undefined)
-                byLevel.set(level, [this.names.getShortName(project)]);
+            const nodeIds = byLevel.get(level);
+            if (nodeIds === undefined)
+                byLevel.set(level, [this.names.getNodeId(project)]);
             else
-                names.push(this.names.getShortName(project));
+                nodeIds.push(this.names.getNodeId(project));
         }
         const levels = [...byLevel.keys()].sort((a, b) => b - a);
         return levels.map((level) => new graph_level_bands_1.LevelBand(level, [...byLevel.get(level)].sort()));
@@ -242,6 +263,7 @@ class GraphVisualizer {
             const info = graph[project];
             if (this.isHidden(info))
                 continue;
+            const nodeId = this.names.getNodeId(project);
             const shortName = this.names.getShortName(project);
             const frameworks = info.framework ?? [];
             const role = info.role ?? 'lib';
@@ -251,7 +273,8 @@ class GraphVisualizer {
             const link = href ? `, URL="${href}", target="_blank"` : '';
             const envSet = `[${frameworks.join(', ')}]`;
             const labelMeta = `L${info.level} · ${envSet} · ${role}`;
-            dot += `  "${shortName}" [fillcolor="${color}"${border}${link}, label="${shortName}\\n(${labelMeta})"];\n`;
+            // Identity is the project key; the LABEL is the pretty short name.
+            dot += `  "${nodeId}" [fillcolor="${color}"${border}${link}, label="${shortName}\\n(${labelMeta})"];\n`;
         }
         return dot;
     }
@@ -264,13 +287,13 @@ class GraphVisualizer {
             const info = graph[project];
             if (this.isHidden(info))
                 continue;
-            const shortName = this.names.getShortName(project);
+            const nodeId = this.names.getNodeId(project);
             for (const dep of info.dependsOn || []) {
                 // Both endpoints must be visible — an edge to/from a hidden box
                 // is dropped so no connection dangles into empty space.
                 if (graph[dep] !== undefined && this.isHidden(graph[dep]))
                     continue;
-                dot += this.edgeDot(shortName, this.names.getShortName(dep), info.apiRelations?.[dep]);
+                dot += this.edgeDot(nodeId, this.names.getNodeId(dep), info.apiRelations?.[dep]);
             }
         }
         return dot;
@@ -324,8 +347,10 @@ class GraphVisualizer {
         for (const project of projects) {
             if (this.isHidden(graph[project]))
                 continue;
+            // The VALUE is the node id the SVG is keyed on; the TEXT stays the pretty short name.
+            const nodeId = this.names.getNodeId(project);
             const shortName = this.names.getShortName(project);
-            options += `<option value="${shortName}">L${graph[project].level} · ${shortName}</option>`;
+            options += `<option value="${nodeId}">L${graph[project].level} · ${shortName}</option>`;
         }
         return `<div class="wp-lock-control">
         <label for="wp-lock">🔒 Lock a box (dim the rest &amp; filter responsibilities):</label>