@webpieces/nx-webpieces-rules 0.3.346 → 0.3.348

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.js). 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            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":";AAAA;;;;;;;;;;;;GAYG;;;;AAEH,+CAAyB;AACzB,mDAA6B;AAE7B,+CAA2C;AAE3C;;;;GAIG;AACH,MAAM,iBAAiB;IACnB,MAAM,GAAG,KAAK,CAAC;CAClB;AAED,MAAa,wBAAwB;IAChB,KAAK,GAAG,IAAI,wBAAU,EAAE,CAAC;IAE1C;;;;OAIG;IACH,eAAe,CAAC,KAAoB,EAAE,aAAqB;QACvD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAS,EAAE,CAAS,EAAU,EAAE;YAC3C,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;YAClD,IAAI,SAAS,KAAK,CAAC;gBAAE,OAAO,SAAS,CAAC;YACtC,OAAO,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;QAC9B,CAAC,CAAC,CAAC;QAEH,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC7B,qEAAqE;YACrE,4CAA4C;YAC5C,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,WAAW,KAAK,KAAK;gBAAE,SAAS;YACnD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC;QACxE,CAAC;QAED,OAAO,CACH,oCAAoC;YACpC,8CAA8C;YAC9C,+FAA+F;YAC/F,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;YAChB,YAAY,CACf,CAAC;IACN,CAAC;IAEO,UAAU,CAAC,OAAe,EAAE,KAAiB,EAAE,aAAqB;QACxE,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QACnD,MAAM,OAAO,GAAG,KAAK,CAAC,gBAAgB,IAAI,EAAE,CAAC;QAC7C,MAAM,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;QACjD,OAAO,CACH,4CAA4C,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI;YAC1E,yCAAyC,KAAK,CAAC,KAAK,UAAU;YAC9D,WAAW,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,YAAY,WAAW,YAAY;YACxE,6BAA6B,IAAI,QAAQ;YACzC,YAAY,CACf,CAAC;IACN,CAAC;IAED;;;;OAIG;IACK,QAAQ,CAAC,KAAiB,EAAE,aAAqB;QACrD,MAAM,IAAI,GAAG,KAAK,CAAC,oBAAoB,CAAC;QACxC,IAAI,CAAC,IAAI;YAAE,OAAO,kEAAkE,CAAC;QACrF,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;QACpD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YAC/B,OAAO,kBAAkB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,YAAY,CAAC;QAC/D,CAAC;QACD,OAAO,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC;IACvE,CAAC;IAED;;;;;;OAMG;IACK,cAAc,CAAC,QAAgB;QACnC,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,IAAI,iBAAiB,EAAE,CAAC;QACtC,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACzC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QAChD,CAAC;QACD,IAAI,KAAK,CAAC,MAAM;YAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpC,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAEO,UAAU,CAAC,IAAY,EAAE,GAAa,EAAE,KAAwB;QACpE,MAAM,OAAO,GAAG,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpB,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;gBAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAAC,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC;YAAC,CAAC;YAC9D,OAAO;QACX,CAAC;QACD,IAAI,OAAO,EAAE,CAAC;YACV,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;gBAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAAC,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC;YAAC,CAAC;YAC9D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,+BAA+B;YACjF,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC;YACrF,OAAO;QACX,CAAC;QACD,IAAI,MAAM,EAAE,CAAC;YACT,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;gBAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;YAAC,CAAC;YAC7D,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YACtE,OAAO;QACX,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAAC,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC;QAAC,CAAC;QAC9D,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC;IACnE,CAAC;IAED;;;OAGG;IACK,YAAY,CAAC,OAAe;QAChC,OAAO,OAAO;aACT,OAAO,CAAC,YAAY,EAAE,iBAAiB,CAAC;aACxC,OAAO,CAAC,kBAAkB,EAAE,qBAAqB,CAAC;aAClD,OAAO,CAAC,sBAAsB,EAAE,eAAe,CAAC,CAAC;IAC1D,CAAC;IAED;;OAEG;IACK,UAAU,CAAC,IAAY;QAC3B,OAAO,IAAI;aACN,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;aACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;aACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;aACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACjC,CAAC;CACJ;AA1HD,4DA0HC","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.js). 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"]}

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

@@ -27,6 +27,13 @@ export interface GraphEntry {
     dependsOn: string[];
     framework?: string[];
     role?: string;
+    /**
+     * When false, the project is hidden from the rendered architecture graphs
+     * (its box AND every edge touching it are omitted from dependencies.html and
+     * the runtime graph). It stays in this JSON so the data view is complete.
+     * Absent means drawn (the default). From the project's `drawOnGraph:` nx tag.
+     */
+    drawOnGraph?: boolean;
     shortDescription?: string;
     responsibilitiesFile?: string;
     designFile?: string;

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":";AAAA;;;;;;;GAOG;;AA4CH,4DA2CC;AA8CD,wDAgBC;AAlHD;;;;;;;;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,kDAAkD;YAClD,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAE/D,4BAA4B;YAC5B,MAAM,SAAS,GAAG,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YAE9C,MAAM,IAAI,KAAK,CACX,uCAAuC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;gBAC3D,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,SAAS,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC1C,yDAAyD,CAChE,CAAC;QACN,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;;GAEG;AACH,SAAS,SAAS,CAAC,KAA+B,EAAE,SAAmB;IACnE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,MAAM,IAAI,GAAa,EAAE,CAAC;IAE1B,SAAS,GAAG,CAAC,IAAY;QACrB,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACtC,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1D,CAAC;QACD,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAEnC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEhB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACrB,IAAI,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC1B,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;gBACxB,IAAI,MAAM;oBAAE,OAAO,MAAM,CAAC;YAC9B,CAAC;QACL,CAAC;QAED,IAAI,CAAC,GAAG,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;IAC5B,CAAC;IAED,OAAO,IAAI,CAAC;AAChB,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';\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    shortDescription?: string;\n    responsibilitiesFile?: string;\n    designFile?: string;\n    apiRelations?: ProjectApiRelations;\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":"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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     * 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\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"]}

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

@@ -17,6 +17,12 @@ export declare class VisualizationPaths {
 export declare class GraphVisualizer {
     private readonly names;
     private readonly responsibilities;
+    /**
+     * A project tagged `drawOnGraph:false` is hidden from the rendered graph —
+     * its node, its rank placement, its dropdown option, its responsibilities
+     * card, and every edge touching it are all omitted. It stays in the JSON.
+     */
+    private isHidden;
     /**
      * Fill color for an env set — the color of the first env in the set that has
      * a known color, else the default.

package/src/lib/graph-visualizer.js

@@ -48,6 +48,14 @@ exports.VisualizationPaths = VisualizationPaths;
 class GraphVisualizer {
     names = new graph_names_1.GraphNames();
     responsibilities = new graph_responsibilities_1.ResponsibilitiesRenderer();
+    /**
+     * A project tagged `drawOnGraph:false` is hidden from the rendered graph —
+     * its node, its rank placement, its dropdown option, its responsibilities
+     * card, and every edge touching it are all omitted. It stays in the JSON.
+     */
+    isHidden(entry) {
+        return entry.drawOnGraph === false;
+    }
     /**
      * Fill color for an env set — the color of the first env in the set that has
      * a known color, else the default.
@@ -116,9 +124,12 @@ class GraphVisualizer {
         dot += '  rankdir=TB;\n';
         dot += '  node [shape=box, style=filled, fontname="Arial"];\n';
         dot += '  edge [fontname="Arial"];\n\n';
-        // Group projects by level
+        // Group projects by level (hidden projects are omitted from the ranks so
+        // no stray rank=same name is emitted for an absent node).
         const levels = {};
         for (const project of Object.keys(graph)) {
+            if (this.isHidden(graph[project]))
+                continue;
             const level = graph[project].level;
             if (!levels[level])
                 levels[level] = [];
@@ -150,6 +161,8 @@ class GraphVisualizer {
         let dot = '';
         for (const project of Object.keys(graph)) {
             const info = graph[project];
+            if (this.isHidden(info))
+                continue;
             const shortName = this.names.getShortName(project);
             const frameworks = info.framework ?? [];
             const role = info.role ?? 'lib';
@@ -169,9 +182,15 @@ class GraphVisualizer {
     dotEdges(graph) {
         let dot = '';
         for (const project of Object.keys(graph)) {
-            const shortName = this.names.getShortName(project);
             const info = graph[project];
+            if (this.isHidden(info))
+                continue;
+            const shortName = this.names.getShortName(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;
                 const attrs = this.edgeAttrs(info.apiRelations?.[dep]?.kind);
                 dot += `  "${shortName}" -> "${this.names.getShortName(dep)}"${attrs};\n`;
             }
@@ -226,6 +245,8 @@ class GraphVisualizer {
         });
         let options = '';
         for (const project of projects) {
+            if (this.isHidden(graph[project]))
+                continue;
             const shortName = this.names.getShortName(project);
             options += `<option value="${shortName}">L${graph[project].level} · ${shortName}</option>`;
         }

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

@@ -1 +1 @@
-{"version":3,"file":"graph-visualizer.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-visualizer.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Graph Visualizer\n *\n * Generates visual representations of the architecture graph:\n * - DOT format (for Graphviz)\n * - Interactive HTML (using viz.js)\n *\n * All behavior lives on the injectable GraphVisualizer class so webpieces DI +\n * @DocumentDesign can wire it — module-scope functions are a dead end the DI\n * graph can't reach.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { execSync } from 'child_process';\nimport type { EnhancedGraph } from './graph-sorter';\nimport type { ApiRelationKind } from './api-usage/api-relations';\nimport { GraphNames } from './graph-names';\nimport { ResponsibilitiesRenderer } from './graph-responsibilities';\nimport { toError } from '../toError';\n\n/**\n * Framework (libType) colors for visualization — nodes are filled by the FIRST\n * env in their set that has a color, so it is obvious at a glance which side a\n * project targets. A project's full env set is shown in the label.\n */\nconst FRAMEWORK_COLORS: Record<string, string> = {\n    angular: '#FCE4EC', // pink   - Angular front-end\n    react: '#E3F2FD', // blue   - React front-end\n    browser: '#EDE7F6', // purple - browser (front-end base env)\n    express: '#E8F5E9', // green  - Express / server side\n    node: '#FFF9C4', // yellow - node (server base env)\n};\n\nconst DEFAULT_FRAMEWORK_COLOR = '#F5F5F5'; // grey - unknown/empty env set\n\n/**\n * Directory (repo-relative) that the committed architecture HTML lives in.\n * Node click-through links are computed relative to this so they resolve when\n * the file is opened straight from the checkout.\n */\nconst ARCH_OUTPUT_DIR = 'architecture';\n\nexport class VisualizationPaths {\n    htmlPath: string;\n\n    constructor(htmlPath: string) {\n        this.htmlPath = htmlPath;\n    }\n}\n\nexport class GraphVisualizer {\n    private readonly names = new GraphNames();\n    private readonly responsibilities = new ResponsibilitiesRenderer();\n\n    /**\n     * Fill color for an env set — the color of the first env in the set that has\n     * a known color, else the default.\n     */\n    private frameworkColor(frameworks: string[]): string {\n        for (const env of frameworks) {\n            const color = FRAMEWORK_COLORS[env];\n            if (color !== undefined) return color;\n        }\n        return DEFAULT_FRAMEWORK_COLOR;\n    }\n\n    /**\n     * Role border styling — fill stays keyed on framework; the border shows a\n     * project's ROLE at a glance. Server and client are the top-level runnable\n     * nodes, so they get bold, colored borders to stand out:\n     *   server       → thick GREEN border (a runnable server app)\n     *   client       → thick RED border   (a client app, e.g. angular)\n     *   designed-lib → bold border        (a library with a generated @DocumentDesign design)\n     *   lib / other  → plain thin border\n     */\n    private roleBorderAttrs(role: string): string {\n        if (role === 'server') return ', color=\"green\", penwidth=3';\n        if (role === 'client') return ', color=\"red\", penwidth=3';\n        if (role === 'api-lib') return ', color=\"#EF6C00\", penwidth=2';\n        if (role === 'designed-lib') return ', penwidth=2';\n        return '';\n    }\n\n    /**\n     * Edge styling by API-relation kind (why the edge exists):\n     *   implements       → BLACK dashed (a controller serves this api-lib's contract)\n     *   uses             → BLACK solid (a generated client calls it) — same as a\n     *                      plain library import, since a plain dependency IS a use.\n     *   uses-implements  → BLUE dashed, thicker (does both — implements some\n     *                      contracts of the api-lib, uses others)\n     *   plain lib (none) → the default thin black solid arrow, unchanged.\n     * `kind` is undefined for every non-api-lib dependency edge.\n     */\n    private edgeAttrs(kind: ApiRelationKind | undefined): string {\n        if (kind === 'implements') return ' [style=dashed]';\n        if (kind === 'uses-implements') return ' [style=dashed, color=\"#1976d2\", penwidth=2]';\n        return '';\n    }\n\n    /**\n     * Click-through href for a node: the project's committed design.html, made\n     * relative to architecture/dependencies.html. Returns null when the project\n     * has no generated DI design (no design.json → no clickable design page).\n     */\n    private designHtmlHref(designFile: string | undefined): string | null {\n        if (!designFile) return null;\n        const designHtml = designFile.replace(/design\\.json$/, 'design.html');\n        return path.posix.relative(ARCH_OUTPUT_DIR, designHtml);\n    }\n\n    /**\n     * Generate Graphviz DOT format from the graph\n     */\n    generateDot(graph: EnhancedGraph, title: string = 'Monorepo Dependency Architecture'): string {\n        let dot = 'digraph Architecture {\\n';\n        dot += '  rankdir=TB;\\n';\n        dot += '  node [shape=box, style=filled, fontname=\"Arial\"];\\n';\n        dot += '  edge [fontname=\"Arial\"];\\n\\n';\n\n        // Group projects by level\n        const levels: Record<number, string[]> = {};\n        for (const project of Object.keys(graph)) {\n            const level = graph[project].level;\n            if (!levels[level]) levels[level] = [];\n            levels[level].push(project);\n        }\n\n        dot += this.dotNodes(graph);\n        dot += '\\n';\n\n        // Create same-rank subgraphs for each level\n        for (const projects of Object.values(levels)) {\n            dot += `  { rank=same; `;\n            for (const p of projects) {\n                dot += `\"${this.names.getShortName(p)}\"; `;\n            }\n            dot += '}\\n';\n        }\n\n        dot += '\\n';\n        dot += this.dotEdges(graph);\n\n        dot += '\\n  labelloc=\"t\";\\n';\n        dot += `  label=\"${title}\\\\n(from architecture/dependencies.json)\";\\n`;\n        dot += '  fontsize=20;\\n';\n        dot += '}\\n';\n\n        return dot;\n    }\n\n    // Node lines: fill colored by framework env set (libType), border shaped by\n    // role; the label shows the env set + role (e.g. [browser, node] · server). A\n    // node with a generated DI design also gets a URL so the rendered SVG box is\n    // clickable — it opens that project's committed design.html in a new tab.\n    private dotNodes(graph: EnhancedGraph): string {\n        let dot = '';\n        for (const project of Object.keys(graph)) {\n            const info = graph[project];\n            const shortName = this.names.getShortName(project);\n            const frameworks = info.framework ?? [];\n            const role = info.role ?? 'lib';\n            const color = this.frameworkColor(frameworks);\n            const border = this.roleBorderAttrs(role);\n            const href = this.designHtmlHref(info.designFile);\n            const link = href ? `, URL=\"${href}\", target=\"_blank\"` : '';\n            const envSet = `[${frameworks.join(', ')}]`;\n            const labelMeta = `L${info.level} · ${envSet} · ${role}`;\n            dot += `  \"${shortName}\" [fillcolor=\"${color}\"${border}${link}, label=\"${shortName}\\\\n(${labelMeta})\"];\\n`;\n        }\n        return dot;\n    }\n\n    // Edge lines (dependencies). An edge to an api-lib is styled by WHY it exists\n    // (implements/uses/uses-implements, from apiRelations); every other dependency\n    // keeps the default plain arrow.\n    private dotEdges(graph: EnhancedGraph): string {\n        let dot = '';\n        for (const project of Object.keys(graph)) {\n            const shortName = this.names.getShortName(project);\n            const info = graph[project];\n            for (const dep of info.dependsOn || []) {\n                const attrs = this.edgeAttrs(info.apiRelations?.[dep]?.kind);\n                dot += `  \"${shortName}\" -> \"${this.names.getShortName(dep)}\"${attrs};\\n`;\n            }\n        }\n        return dot;\n    }\n\n    /**\n     * Generate interactive HTML with embedded SVG using viz.js\n     */\n    generateHTML(\n        dot: string,\n        title: string = 'Monorepo Dependency Architecture',\n        lockControl: string = '',\n        responsibilitiesHtml: string = ''\n    ): string {\n        const styles = this.styles();\n        const legend = this.legend();\n        const script = this.script(dot);\n\n        return `<!DOCTYPE html>\n<html>\n<head>\n    <meta charset=\"utf-8\">\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>${styles}</style>\n</head>\n<body>\n    <h1>${title}</h1>\n    <p class=\"hint\">💡 Click any box with a generated DI design to open its <strong>design.html</strong> (what the AI sees inside that project).</p>\n    <p class=\"hint\">🔦 <strong>Hover any box</strong> to trace its <em>entire</em> dependency chain — every ancestor above it (all the way up) <em>and</em> every dependency below it (all the way down), with all the boxes and lines between — while the rest of the graph dims so you can follow one box at a glance.</p>\n    ${legend}\n    ${lockControl}\n    <div id=\"graph\"></div>\n    ${responsibilitiesHtml}\n    <script>${script}</script>\n</body>\n</html>`;\n    }\n\n    /**\n     * The lock control (a single-select dropdown, rendered below the legend).\n     * Picking a module LOCKS the graph into that box's hover view — its full\n     * ancestor + descendant chain stays lit while everything else stays dimmed —\n     * and narrows the responsibilities list below the graph to just that chain.\n     * The first option, \"All\", is the default and clears the lock. Hover still\n     * works on top of a lock; leaving a box returns to the locked view.\n     *\n     * Options are ordered by level DESCENDING to match the responsibilities cards.\n     */\n    lockControl(graph: EnhancedGraph): 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        let options = '';\n        for (const project of projects) {\n            const shortName = this.names.getShortName(project);\n            options += `<option value=\"${shortName}\">L${graph[project].level} · ${shortName}</option>`;\n        }\n        return `<div class=\"wp-lock-control\">\n        <label for=\"wp-lock\">🔒 Lock a box (dim the rest &amp; filter responsibilities):</label>\n        <select id=\"wp-lock\"><option value=\"\">All (no lock)</option>${options}</select>\n    </div>`;\n    }\n\n    private styles(): string {\n        return `\n        body { margin: 0; padding: 20px; font-family: Arial, sans-serif; background: #f5f5f5; }\n        h1 { text-align: center; color: #333; }\n        .hint { text-align: center; color: #555; margin: 0 0 16px; }\n        /* viz.js renders node URLs as <a> — only boxes with a design.html get\n         * one, so a:hover is a clickable-only signal. Make it pop clearly: a\n         * thicker border PLUS a blue glow lift the box off the page, so it is\n         * obvious which boxes you can click into vs. which you cannot. (A plain\n         * stroke bump is invisible on server/client boxes, whose resting border\n         * is already thick.) */\n        #graph a { cursor: pointer; }\n        #graph a polygon,\n        #graph a ellipse { transition: stroke-width 0.12s ease, filter 0.12s ease; }\n        #graph a:hover polygon,\n        #graph a:hover ellipse {\n            stroke: #1976d2;\n            stroke-width: 5;\n            filter: drop-shadow(0 0 6px rgba(25, 118, 210, 0.85));\n        }\n        /* Hover-highlight (wired up in JS after viz.js renders). Hovering a node\n         * adds .wp-dim to the <svg> and .wp-focus/.wp-neighbor/.wp-hl to the\n         * connected box, its neighbors, and its edges. We ONLY dim: the connected\n         * subgraph keeps its exact normal look (full opacity), the rest recedes.\n         * The un-dim rules repeat \"svg.wp-dim\" so they out-specify the dim rule\n         * (which has an extra type selector) — else the subgraph stays dimmed. */\n        #graph .node, #graph .edge { transition: opacity 0.12s ease; }\n        #graph svg.wp-dim .node,\n        #graph svg.wp-dim .edge { opacity: 0.15; }\n        #graph svg.wp-dim .node.wp-focus,\n        #graph svg.wp-dim .node.wp-neighbor,\n        #graph svg.wp-dim .edge.wp-hl { opacity: 1; }\n        #graph {\n            text-align: center;\n            background: white;\n            padding: 20px;\n            border-radius: 8px;\n            box-shadow: 0 2px 4px rgba(0,0,0,0.1);\n        }\n        .legend {\n            margin: 20px auto;\n            max-width: 1100px;\n            padding: 15px;\n            background: white;\n            border-radius: 8px;\n            box-shadow: 0 2px 4px rgba(0,0,0,0.1);\n        }\n        .legend h2 { margin-top: 0; }\n        .legend-item { margin: 8px 0; }\n        .legend-box {\n            display: inline-block;\n            width: 20px;\n            height: 20px;\n            border: 1px solid #ccc;\n            margin-right: 10px;\n            vertical-align: middle;\n        }\n        ${this.componentStyles()}\n    `;\n    }\n\n    // Styles for the lock dropdown and the responsibilities card list below the\n    // graph. Split out of styles() to keep each method within the line limit.\n    private componentStyles(): string {\n        return `\n        /* The architecture graph is very wide, so lay the legend out as three\n         * side-by-side columns (fill / border / edge) instead of one tall\n         * column — it keeps the legend short next to the wide graph, and\n         * collapses back to a single column on narrow viewports. */\n        .legend-columns {\n            display: grid;\n            grid-template-columns: repeat(3, 1fr);\n            gap: 28px;\n            align-items: start;\n        }\n        .legend-col h3 { margin: 0 0 8px; color: #333; font-size: 15px; }\n        @media (max-width: 800px) { .legend-columns { grid-template-columns: 1fr; } }\n        .wp-lock-control {\n            max-width: 600px;\n            margin: 0 auto 16px;\n            padding: 12px 15px;\n            background: white;\n            border-radius: 8px;\n            box-shadow: 0 2px 4px rgba(0,0,0,0.1);\n            text-align: center;\n        }\n        .wp-lock-control label { font-weight: bold; color: #333; margin-right: 8px; }\n        .wp-lock-control select { font-size: 14px; padding: 4px 8px; }\n        #wp-responsibilities { max-width: 900px; margin: 24px auto 0; }\n        #wp-responsibilities h2 { color: #333; }\n        .wp-resp-card {\n            background: white;\n            border-radius: 8px;\n            box-shadow: 0 2px 4px rgba(0,0,0,0.1);\n            margin: 10px 0;\n            padding: 10px 15px;\n        }\n        .wp-resp-card > summary { cursor: pointer; color: #333; }\n        .wp-resp-level {\n            display: inline-block;\n            min-width: 26px;\n            padding: 1px 6px;\n            margin-right: 6px;\n            border-radius: 4px;\n            background: #eef;\n            font-size: 12px;\n            font-weight: bold;\n            text-align: center;\n        }\n        .wp-resp-body { margin-top: 8px; color: #444; }\n        .wp-resp-body code {\n            background: #f2f2f2;\n            padding: 1px 4px;\n            border-radius: 3px;\n            font-family: monospace;\n        }\n        .wp-hidden { display: none; }`;\n    }\n\n    // The legend is laid out in three side-by-side columns (fill / border /\n    // edge) so it stays short next to the very wide architecture graph. Each\n    // column's rows come from a helper below to keep this method within the line\n    // limit; the footnote spans the full width beneath the columns.\n    private legend(): string {\n        return `<div class=\"legend\">\n        <h2>Legend</h2>\n        <div class=\"legend-columns\">\n            <div class=\"legend-col\">\n                <h3>Fill = framework (libType)</h3>\n                ${this.fillItems()}\n            </div>\n            <div class=\"legend-col\">\n                <h3>Border = role</h3>\n                ${this.borderItems()}\n            </div>\n            <div class=\"legend-col\">\n                <h3>Edge lines — <em>why</em> a project depends on an api-lib</h3>\n                ${this.edgeItems()}\n            </div>\n        </div>\n        <div class=\"legend-item\" style=\"margin-top: 15px;\">\n            <em>Each node label shows its dependency level (L#), its framework env set (e.g. [browser, node]), and its role. Rows are laid out by level (top = no dependencies), with the deepest libraries at the bottom. Transitive dependencies are allowed but not shown.</em>\n        </div>\n    </div>`;\n    }\n\n    // Column 1 — fill color keyed on the project's framework (libType) env set.\n    private fillItems(): string {\n        return `<div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"background: #FCE4EC;\"></span>\n            <strong>angular:</strong> Angular front-end\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"background: #E3F2FD;\"></span>\n            <strong>react:</strong> React front-end\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"background: #EDE7F6;\"></span>\n            <strong>browser:</strong> browser front-end base env\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"background: #E8F5E9;\"></span>\n            <strong>express:</strong> Express / server side\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"background: #FFF9C4;\"></span>\n            <strong>node:</strong> node server base env\n        </div>`;\n    }\n\n    // Column 2 — border style keyed on the project's role.\n    private borderItems(): string {\n        return `<div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"border: 3px solid green;\"></span>\n            <strong>server:</strong> runnable server app (thick green border)\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"border: 3px solid red;\"></span>\n            <strong>client:</strong> client app, e.g. angular (thick red border)\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"border: 2px solid #333;\"></span>\n            <strong>designed-lib:</strong> library with a generated @DocumentDesign design (bold border)\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"border: 1px solid #ccc;\"></span>\n            <strong>lib:</strong> plain library, no generated design (thin border)\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"border: 2px solid #EF6C00;\"></span>\n            <strong>api-lib:</strong> API-contract library (defines <code>@ApiPath</code>/<code>@Rpc</code>/<code>@PubSub</code> <code>*Api</code> classes)\n        </div>`;\n    }\n\n    // Column 3 — edge line style keyed on WHY a project depends on an api-lib.\n    private edgeItems(): string {\n        return `<div class=\"legend-item\">\n            <svg width=\"42\" height=\"12\" style=\"vertical-align: middle; margin-right: 10px;\"><line x1=\"0\" y1=\"6\" x2=\"42\" y2=\"6\" stroke=\"#333\" stroke-width=\"2\"/></svg>\n            <strong>uses:</strong> calls the API (generates an rpc/pubsub client via <code>createRpcClient</code>/<code>createPubSubClient</code>) — also covers a plain library import, since a plain dependency is just a use.\n        </div>\n        <div class=\"legend-item\">\n            <svg width=\"42\" height=\"12\" style=\"vertical-align: middle; margin-right: 10px;\"><line x1=\"0\" y1=\"6\" x2=\"42\" y2=\"6\" stroke=\"#333\" stroke-width=\"2\" stroke-dasharray=\"5,3\"/></svg>\n            <strong>implements:</strong> serves the API — NOTE: this is a build-dependency diagram, so a UML <em>implements</em> arrow can't be used; we use a dashed line to signal a build dep, because this server implements the api and the api is built first, then this server after.\n        </div>\n        <div class=\"legend-item\">\n            <svg width=\"42\" height=\"12\" style=\"vertical-align: middle; margin-right: 10px;\"><line x1=\"0\" y1=\"6\" x2=\"42\" y2=\"6\" stroke=\"#1976d2\" stroke-width=\"2\" stroke-dasharray=\"5,3\"/></svg>\n            <strong>uses/implements:</strong> both — implements some of the api-lib's contracts, uses others\n        </div>`;\n    }\n\n    /**\n     * The page script. The browser code lives in graph-visualizer.client.js (a\n     * plain .js asset, NOT a TS template literal) so its dim/highlight/lock\n     * functions can be ordinary browser functions — the TS lint rules that scan\n     * .ts template strings would otherwise forbid them, and browser JS cannot\n     * carry TS return annotations. We inline it and substitute the DOT.\n     */\n    private script(dot: string): string {\n        const clientJs = fs.readFileSync(path.join(__dirname, 'graph-visualizer.client.js'), 'utf-8');\n        return clientJs.split('__DOT__').join(JSON.stringify(dot));\n    }\n\n    /**\n     * Write the committed architecture visualization to\n     * architecture/dependencies.html, next to dependencies.json.\n     *\n     * This is a checked-in artifact, regenerated deterministically by\n     * architecture:generate so the boxes stay clickable into each project's\n     * design.html. The DOT is embedded in the HTML (rendered client-side by\n     * viz.js). Output is deterministic (sorted graph in → same bytes out) so git\n     * only shows a diff when the architecture actually changed.\n     */\n    writeVisualization(\n        graph: EnhancedGraph,\n        workspaceRoot: string,\n        title: string = 'Monorepo Dependency Architecture'\n    ): VisualizationPaths {\n        const outputDir = path.join(workspaceRoot, ARCH_OUTPUT_DIR);\n\n        if (!fs.existsSync(outputDir)) {\n            fs.mkdirSync(outputDir, { recursive: true });\n        }\n\n        const lockControl = this.lockControl(graph);\n        const responsibilities = this.responsibilities.generateSection(graph, workspaceRoot);\n        const html = this.generateHTML(this.generateDot(graph, title), title, lockControl, responsibilities);\n        const htmlPath = path.join(outputDir, 'dependencies.html');\n        fs.writeFileSync(htmlPath, html, 'utf-8');\n\n        return new VisualizationPaths(htmlPath);\n    }\n\n    /**\n     * Open the HTML visualization in the default browser\n     */\n    openVisualization(htmlPath: string): boolean {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const platform = process.platform;\n            let openCommand: string;\n\n            if (platform === 'darwin') {\n                openCommand = `open \"${htmlPath}\"`;\n            } else if (platform === 'win32') {\n                openCommand = `start \"\" \"${htmlPath}\"`;\n            } else {\n                openCommand = `xdg-open \"${htmlPath}\"`;\n            }\n\n            execSync(openCommand, { stdio: 'ignore' });\n            return true;\n        } catch (err: unknown) {\n            const error = toError(err);\n            console.warn(`⚠️  Could not open browser: ${error.message}`);\n            return false;\n        }\n    }\n}\n"]}
+{"version":3,"file":"graph-visualizer.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-visualizer.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Graph Visualizer\n *\n * Generates visual representations of the architecture graph:\n * - DOT format (for Graphviz)\n * - Interactive HTML (using viz.js)\n *\n * All behavior lives on the injectable GraphVisualizer class so webpieces DI +\n * @DocumentDesign can wire it — module-scope functions are a dead end the DI\n * graph can't reach.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { execSync } from 'child_process';\nimport type { EnhancedGraph } from './graph-sorter';\nimport type { ApiRelationKind } from './api-usage/api-relations';\nimport { GraphNames } from './graph-names';\nimport { ResponsibilitiesRenderer } from './graph-responsibilities';\nimport { toError } from '../toError';\n\n/**\n * Framework (libType) colors for visualization — nodes are filled by the FIRST\n * env in their set that has a color, so it is obvious at a glance which side a\n * project targets. A project's full env set is shown in the label.\n */\nconst FRAMEWORK_COLORS: Record<string, string> = {\n    angular: '#FCE4EC', // pink   - Angular front-end\n    react: '#E3F2FD', // blue   - React front-end\n    browser: '#EDE7F6', // purple - browser (front-end base env)\n    express: '#E8F5E9', // green  - Express / server side\n    node: '#FFF9C4', // yellow - node (server base env)\n};\n\nconst DEFAULT_FRAMEWORK_COLOR = '#F5F5F5'; // grey - unknown/empty env set\n\n/**\n * Directory (repo-relative) that the committed architecture HTML lives in.\n * Node click-through links are computed relative to this so they resolve when\n * the file is opened straight from the checkout.\n */\nconst ARCH_OUTPUT_DIR = 'architecture';\n\nexport class VisualizationPaths {\n    htmlPath: string;\n\n    constructor(htmlPath: string) {\n        this.htmlPath = htmlPath;\n    }\n}\n\nexport class GraphVisualizer {\n    private readonly names = new GraphNames();\n    private readonly responsibilities = new ResponsibilitiesRenderer();\n\n    /**\n     * A project tagged `drawOnGraph:false` is hidden from the rendered graph —\n     * its node, its rank placement, its dropdown option, its responsibilities\n     * card, and every edge touching it are all omitted. It stays in the JSON.\n     */\n    private isHidden(entry: EnhancedGraph[string]): boolean {\n        return entry.drawOnGraph === false;\n    }\n\n    /**\n     * Fill color for an env set — the color of the first env in the set that has\n     * a known color, else the default.\n     */\n    private frameworkColor(frameworks: string[]): string {\n        for (const env of frameworks) {\n            const color = FRAMEWORK_COLORS[env];\n            if (color !== undefined) return color;\n        }\n        return DEFAULT_FRAMEWORK_COLOR;\n    }\n\n    /**\n     * Role border styling — fill stays keyed on framework; the border shows a\n     * project's ROLE at a glance. Server and client are the top-level runnable\n     * nodes, so they get bold, colored borders to stand out:\n     *   server       → thick GREEN border (a runnable server app)\n     *   client       → thick RED border   (a client app, e.g. angular)\n     *   designed-lib → bold border        (a library with a generated @DocumentDesign design)\n     *   lib / other  → plain thin border\n     */\n    private roleBorderAttrs(role: string): string {\n        if (role === 'server') return ', color=\"green\", penwidth=3';\n        if (role === 'client') return ', color=\"red\", penwidth=3';\n        if (role === 'api-lib') return ', color=\"#EF6C00\", penwidth=2';\n        if (role === 'designed-lib') return ', penwidth=2';\n        return '';\n    }\n\n    /**\n     * Edge styling by API-relation kind (why the edge exists):\n     *   implements       → BLACK dashed (a controller serves this api-lib's contract)\n     *   uses             → BLACK solid (a generated client calls it) — same as a\n     *                      plain library import, since a plain dependency IS a use.\n     *   uses-implements  → BLUE dashed, thicker (does both — implements some\n     *                      contracts of the api-lib, uses others)\n     *   plain lib (none) → the default thin black solid arrow, unchanged.\n     * `kind` is undefined for every non-api-lib dependency edge.\n     */\n    private edgeAttrs(kind: ApiRelationKind | undefined): string {\n        if (kind === 'implements') return ' [style=dashed]';\n        if (kind === 'uses-implements') return ' [style=dashed, color=\"#1976d2\", penwidth=2]';\n        return '';\n    }\n\n    /**\n     * Click-through href for a node: the project's committed design.html, made\n     * relative to architecture/dependencies.html. Returns null when the project\n     * has no generated DI design (no design.json → no clickable design page).\n     */\n    private designHtmlHref(designFile: string | undefined): string | null {\n        if (!designFile) return null;\n        const designHtml = designFile.replace(/design\\.json$/, 'design.html');\n        return path.posix.relative(ARCH_OUTPUT_DIR, designHtml);\n    }\n\n    /**\n     * Generate Graphviz DOT format from the graph\n     */\n    generateDot(graph: EnhancedGraph, title: string = 'Monorepo Dependency Architecture'): string {\n        let dot = 'digraph Architecture {\\n';\n        dot += '  rankdir=TB;\\n';\n        dot += '  node [shape=box, style=filled, fontname=\"Arial\"];\\n';\n        dot += '  edge [fontname=\"Arial\"];\\n\\n';\n\n        // Group projects by level (hidden projects are omitted from the ranks so\n        // no stray rank=same name is emitted for an absent node).\n        const levels: Record<number, string[]> = {};\n        for (const project of Object.keys(graph)) {\n            if (this.isHidden(graph[project])) continue;\n            const level = graph[project].level;\n            if (!levels[level]) levels[level] = [];\n            levels[level].push(project);\n        }\n\n        dot += this.dotNodes(graph);\n        dot += '\\n';\n\n        // Create same-rank subgraphs for each level\n        for (const projects of Object.values(levels)) {\n            dot += `  { rank=same; `;\n            for (const p of projects) {\n                dot += `\"${this.names.getShortName(p)}\"; `;\n            }\n            dot += '}\\n';\n        }\n\n        dot += '\\n';\n        dot += this.dotEdges(graph);\n\n        dot += '\\n  labelloc=\"t\";\\n';\n        dot += `  label=\"${title}\\\\n(from architecture/dependencies.json)\";\\n`;\n        dot += '  fontsize=20;\\n';\n        dot += '}\\n';\n\n        return dot;\n    }\n\n    // Node lines: fill colored by framework env set (libType), border shaped by\n    // role; the label shows the env set + role (e.g. [browser, node] · server). A\n    // node with a generated DI design also gets a URL so the rendered SVG box is\n    // clickable — it opens that project's committed design.html in a new tab.\n    private dotNodes(graph: EnhancedGraph): string {\n        let dot = '';\n        for (const project of Object.keys(graph)) {\n            const info = graph[project];\n            if (this.isHidden(info)) continue;\n            const shortName = this.names.getShortName(project);\n            const frameworks = info.framework ?? [];\n            const role = info.role ?? 'lib';\n            const color = this.frameworkColor(frameworks);\n            const border = this.roleBorderAttrs(role);\n            const href = this.designHtmlHref(info.designFile);\n            const link = href ? `, URL=\"${href}\", target=\"_blank\"` : '';\n            const envSet = `[${frameworks.join(', ')}]`;\n            const labelMeta = `L${info.level} · ${envSet} · ${role}`;\n            dot += `  \"${shortName}\" [fillcolor=\"${color}\"${border}${link}, label=\"${shortName}\\\\n(${labelMeta})\"];\\n`;\n        }\n        return dot;\n    }\n\n    // Edge lines (dependencies). An edge to an api-lib is styled by WHY it exists\n    // (implements/uses/uses-implements, from apiRelations); every other dependency\n    // keeps the default plain arrow.\n    private dotEdges(graph: EnhancedGraph): string {\n        let dot = '';\n        for (const project of Object.keys(graph)) {\n            const info = graph[project];\n            if (this.isHidden(info)) continue;\n            const shortName = this.names.getShortName(project);\n            for (const dep of info.dependsOn || []) {\n                // Both endpoints must be visible — an edge to/from a hidden box\n                // is dropped so no connection dangles into empty space.\n                if (graph[dep] !== undefined && this.isHidden(graph[dep])) continue;\n                const attrs = this.edgeAttrs(info.apiRelations?.[dep]?.kind);\n                dot += `  \"${shortName}\" -> \"${this.names.getShortName(dep)}\"${attrs};\\n`;\n            }\n        }\n        return dot;\n    }\n\n    /**\n     * Generate interactive HTML with embedded SVG using viz.js\n     */\n    generateHTML(\n        dot: string,\n        title: string = 'Monorepo Dependency Architecture',\n        lockControl: string = '',\n        responsibilitiesHtml: string = ''\n    ): string {\n        const styles = this.styles();\n        const legend = this.legend();\n        const script = this.script(dot);\n\n        return `<!DOCTYPE html>\n<html>\n<head>\n    <meta charset=\"utf-8\">\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>${styles}</style>\n</head>\n<body>\n    <h1>${title}</h1>\n    <p class=\"hint\">💡 Click any box with a generated DI design to open its <strong>design.html</strong> (what the AI sees inside that project).</p>\n    <p class=\"hint\">🔦 <strong>Hover any box</strong> to trace its <em>entire</em> dependency chain — every ancestor above it (all the way up) <em>and</em> every dependency below it (all the way down), with all the boxes and lines between — while the rest of the graph dims so you can follow one box at a glance.</p>\n    ${legend}\n    ${lockControl}\n    <div id=\"graph\"></div>\n    ${responsibilitiesHtml}\n    <script>${script}</script>\n</body>\n</html>`;\n    }\n\n    /**\n     * The lock control (a single-select dropdown, rendered below the legend).\n     * Picking a module LOCKS the graph into that box's hover view — its full\n     * ancestor + descendant chain stays lit while everything else stays dimmed —\n     * and narrows the responsibilities list below the graph to just that chain.\n     * The first option, \"All\", is the default and clears the lock. Hover still\n     * works on top of a lock; leaving a box returns to the locked view.\n     *\n     * Options are ordered by level DESCENDING to match the responsibilities cards.\n     */\n    lockControl(graph: EnhancedGraph): 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        let options = '';\n        for (const project of projects) {\n            if (this.isHidden(graph[project])) continue;\n            const shortName = this.names.getShortName(project);\n            options += `<option value=\"${shortName}\">L${graph[project].level} · ${shortName}</option>`;\n        }\n        return `<div class=\"wp-lock-control\">\n        <label for=\"wp-lock\">🔒 Lock a box (dim the rest &amp; filter responsibilities):</label>\n        <select id=\"wp-lock\"><option value=\"\">All (no lock)</option>${options}</select>\n    </div>`;\n    }\n\n    private styles(): string {\n        return `\n        body { margin: 0; padding: 20px; font-family: Arial, sans-serif; background: #f5f5f5; }\n        h1 { text-align: center; color: #333; }\n        .hint { text-align: center; color: #555; margin: 0 0 16px; }\n        /* viz.js renders node URLs as <a> — only boxes with a design.html get\n         * one, so a:hover is a clickable-only signal. Make it pop clearly: a\n         * thicker border PLUS a blue glow lift the box off the page, so it is\n         * obvious which boxes you can click into vs. which you cannot. (A plain\n         * stroke bump is invisible on server/client boxes, whose resting border\n         * is already thick.) */\n        #graph a { cursor: pointer; }\n        #graph a polygon,\n        #graph a ellipse { transition: stroke-width 0.12s ease, filter 0.12s ease; }\n        #graph a:hover polygon,\n        #graph a:hover ellipse {\n            stroke: #1976d2;\n            stroke-width: 5;\n            filter: drop-shadow(0 0 6px rgba(25, 118, 210, 0.85));\n        }\n        /* Hover-highlight (wired up in JS after viz.js renders). Hovering a node\n         * adds .wp-dim to the <svg> and .wp-focus/.wp-neighbor/.wp-hl to the\n         * connected box, its neighbors, and its edges. We ONLY dim: the connected\n         * subgraph keeps its exact normal look (full opacity), the rest recedes.\n         * The un-dim rules repeat \"svg.wp-dim\" so they out-specify the dim rule\n         * (which has an extra type selector) — else the subgraph stays dimmed. */\n        #graph .node, #graph .edge { transition: opacity 0.12s ease; }\n        #graph svg.wp-dim .node,\n        #graph svg.wp-dim .edge { opacity: 0.15; }\n        #graph svg.wp-dim .node.wp-focus,\n        #graph svg.wp-dim .node.wp-neighbor,\n        #graph svg.wp-dim .edge.wp-hl { opacity: 1; }\n        #graph {\n            text-align: center;\n            background: white;\n            padding: 20px;\n            border-radius: 8px;\n            box-shadow: 0 2px 4px rgba(0,0,0,0.1);\n        }\n        .legend {\n            margin: 20px auto;\n            max-width: 1100px;\n            padding: 15px;\n            background: white;\n            border-radius: 8px;\n            box-shadow: 0 2px 4px rgba(0,0,0,0.1);\n        }\n        .legend h2 { margin-top: 0; }\n        .legend-item { margin: 8px 0; }\n        .legend-box {\n            display: inline-block;\n            width: 20px;\n            height: 20px;\n            border: 1px solid #ccc;\n            margin-right: 10px;\n            vertical-align: middle;\n        }\n        ${this.componentStyles()}\n    `;\n    }\n\n    // Styles for the lock dropdown and the responsibilities card list below the\n    // graph. Split out of styles() to keep each method within the line limit.\n    private componentStyles(): string {\n        return `\n        /* The architecture graph is very wide, so lay the legend out as three\n         * side-by-side columns (fill / border / edge) instead of one tall\n         * column — it keeps the legend short next to the wide graph, and\n         * collapses back to a single column on narrow viewports. */\n        .legend-columns {\n            display: grid;\n            grid-template-columns: repeat(3, 1fr);\n            gap: 28px;\n            align-items: start;\n        }\n        .legend-col h3 { margin: 0 0 8px; color: #333; font-size: 15px; }\n        @media (max-width: 800px) { .legend-columns { grid-template-columns: 1fr; } }\n        .wp-lock-control {\n            max-width: 600px;\n            margin: 0 auto 16px;\n            padding: 12px 15px;\n            background: white;\n            border-radius: 8px;\n            box-shadow: 0 2px 4px rgba(0,0,0,0.1);\n            text-align: center;\n        }\n        .wp-lock-control label { font-weight: bold; color: #333; margin-right: 8px; }\n        .wp-lock-control select { font-size: 14px; padding: 4px 8px; }\n        #wp-responsibilities { max-width: 900px; margin: 24px auto 0; }\n        #wp-responsibilities h2 { color: #333; }\n        .wp-resp-card {\n            background: white;\n            border-radius: 8px;\n            box-shadow: 0 2px 4px rgba(0,0,0,0.1);\n            margin: 10px 0;\n            padding: 10px 15px;\n        }\n        .wp-resp-card > summary { cursor: pointer; color: #333; }\n        .wp-resp-level {\n            display: inline-block;\n            min-width: 26px;\n            padding: 1px 6px;\n            margin-right: 6px;\n            border-radius: 4px;\n            background: #eef;\n            font-size: 12px;\n            font-weight: bold;\n            text-align: center;\n        }\n        .wp-resp-body { margin-top: 8px; color: #444; }\n        .wp-resp-body code {\n            background: #f2f2f2;\n            padding: 1px 4px;\n            border-radius: 3px;\n            font-family: monospace;\n        }\n        .wp-hidden { display: none; }`;\n    }\n\n    // The legend is laid out in three side-by-side columns (fill / border /\n    // edge) so it stays short next to the very wide architecture graph. Each\n    // column's rows come from a helper below to keep this method within the line\n    // limit; the footnote spans the full width beneath the columns.\n    private legend(): string {\n        return `<div class=\"legend\">\n        <h2>Legend</h2>\n        <div class=\"legend-columns\">\n            <div class=\"legend-col\">\n                <h3>Fill = framework (libType)</h3>\n                ${this.fillItems()}\n            </div>\n            <div class=\"legend-col\">\n                <h3>Border = role</h3>\n                ${this.borderItems()}\n            </div>\n            <div class=\"legend-col\">\n                <h3>Edge lines — <em>why</em> a project depends on an api-lib</h3>\n                ${this.edgeItems()}\n            </div>\n        </div>\n        <div class=\"legend-item\" style=\"margin-top: 15px;\">\n            <em>Each node label shows its dependency level (L#), its framework env set (e.g. [browser, node]), and its role. Rows are laid out by level (top = no dependencies), with the deepest libraries at the bottom. Transitive dependencies are allowed but not shown.</em>\n        </div>\n    </div>`;\n    }\n\n    // Column 1 — fill color keyed on the project's framework (libType) env set.\n    private fillItems(): string {\n        return `<div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"background: #FCE4EC;\"></span>\n            <strong>angular:</strong> Angular front-end\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"background: #E3F2FD;\"></span>\n            <strong>react:</strong> React front-end\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"background: #EDE7F6;\"></span>\n            <strong>browser:</strong> browser front-end base env\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"background: #E8F5E9;\"></span>\n            <strong>express:</strong> Express / server side\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"background: #FFF9C4;\"></span>\n            <strong>node:</strong> node server base env\n        </div>`;\n    }\n\n    // Column 2 — border style keyed on the project's role.\n    private borderItems(): string {\n        return `<div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"border: 3px solid green;\"></span>\n            <strong>server:</strong> runnable server app (thick green border)\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"border: 3px solid red;\"></span>\n            <strong>client:</strong> client app, e.g. angular (thick red border)\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"border: 2px solid #333;\"></span>\n            <strong>designed-lib:</strong> library with a generated @DocumentDesign design (bold border)\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"border: 1px solid #ccc;\"></span>\n            <strong>lib:</strong> plain library, no generated design (thin border)\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"border: 2px solid #EF6C00;\"></span>\n            <strong>api-lib:</strong> API-contract library (defines <code>@ApiPath</code>/<code>@Rpc</code>/<code>@PubSub</code> <code>*Api</code> classes)\n        </div>`;\n    }\n\n    // Column 3 — edge line style keyed on WHY a project depends on an api-lib.\n    private edgeItems(): string {\n        return `<div class=\"legend-item\">\n            <svg width=\"42\" height=\"12\" style=\"vertical-align: middle; margin-right: 10px;\"><line x1=\"0\" y1=\"6\" x2=\"42\" y2=\"6\" stroke=\"#333\" stroke-width=\"2\"/></svg>\n            <strong>uses:</strong> calls the API (generates an rpc/pubsub client via <code>createRpcClient</code>/<code>createPubSubClient</code>) — also covers a plain library import, since a plain dependency is just a use.\n        </div>\n        <div class=\"legend-item\">\n            <svg width=\"42\" height=\"12\" style=\"vertical-align: middle; margin-right: 10px;\"><line x1=\"0\" y1=\"6\" x2=\"42\" y2=\"6\" stroke=\"#333\" stroke-width=\"2\" stroke-dasharray=\"5,3\"/></svg>\n            <strong>implements:</strong> serves the API — NOTE: this is a build-dependency diagram, so a UML <em>implements</em> arrow can't be used; we use a dashed line to signal a build dep, because this server implements the api and the api is built first, then this server after.\n        </div>\n        <div class=\"legend-item\">\n            <svg width=\"42\" height=\"12\" style=\"vertical-align: middle; margin-right: 10px;\"><line x1=\"0\" y1=\"6\" x2=\"42\" y2=\"6\" stroke=\"#1976d2\" stroke-width=\"2\" stroke-dasharray=\"5,3\"/></svg>\n            <strong>uses/implements:</strong> both — implements some of the api-lib's contracts, uses others\n        </div>`;\n    }\n\n    /**\n     * The page script. The browser code lives in graph-visualizer.client.js (a\n     * plain .js asset, NOT a TS template literal) so its dim/highlight/lock\n     * functions can be ordinary browser functions — the TS lint rules that scan\n     * .ts template strings would otherwise forbid them, and browser JS cannot\n     * carry TS return annotations. We inline it and substitute the DOT.\n     */\n    private script(dot: string): string {\n        const clientJs = fs.readFileSync(path.join(__dirname, 'graph-visualizer.client.js'), 'utf-8');\n        return clientJs.split('__DOT__').join(JSON.stringify(dot));\n    }\n\n    /**\n     * Write the committed architecture visualization to\n     * architecture/dependencies.html, next to dependencies.json.\n     *\n     * This is a checked-in artifact, regenerated deterministically by\n     * architecture:generate so the boxes stay clickable into each project's\n     * design.html. The DOT is embedded in the HTML (rendered client-side by\n     * viz.js). Output is deterministic (sorted graph in → same bytes out) so git\n     * only shows a diff when the architecture actually changed.\n     */\n    writeVisualization(\n        graph: EnhancedGraph,\n        workspaceRoot: string,\n        title: string = 'Monorepo Dependency Architecture'\n    ): VisualizationPaths {\n        const outputDir = path.join(workspaceRoot, ARCH_OUTPUT_DIR);\n\n        if (!fs.existsSync(outputDir)) {\n            fs.mkdirSync(outputDir, { recursive: true });\n        }\n\n        const lockControl = this.lockControl(graph);\n        const responsibilities = this.responsibilities.generateSection(graph, workspaceRoot);\n        const html = this.generateHTML(this.generateDot(graph, title), title, lockControl, responsibilities);\n        const htmlPath = path.join(outputDir, 'dependencies.html');\n        fs.writeFileSync(htmlPath, html, 'utf-8');\n\n        return new VisualizationPaths(htmlPath);\n    }\n\n    /**\n     * Open the HTML visualization in the default browser\n     */\n    openVisualization(htmlPath: string): boolean {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const platform = process.platform;\n            let openCommand: string;\n\n            if (platform === 'darwin') {\n                openCommand = `open \"${htmlPath}\"`;\n            } else if (platform === 'win32') {\n                openCommand = `start \"\" \"${htmlPath}\"`;\n            } else {\n                openCommand = `xdg-open \"${htmlPath}\"`;\n            }\n\n            execSync(openCommand, { stdio: 'ignore' });\n            return true;\n        } catch (err: unknown) {\n            const error = toError(err);\n            console.warn(`⚠️  Could not open browser: ${error.message}`);\n            return false;\n        }\n    }\n}\n"]}

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

@@ -6,7 +6,6 @@
  *
  *   "runtime-architecture": {
  *     "mode": "ON",                          // "OFF" disables the whole feature
- *     "apiProjectPaths": ["libraries/apis/*"],
  *     "ignoreModifiedUntilEpoch": 0,         // whole-rule punt (epoch seconds)
  *     "allowedCycles": [ { "services": ["a","b"], "reason": "...", "until": 1771931925 } ]
  *   }
@@ -20,8 +19,6 @@ export interface AllowedCycle {
 }
 export interface RuntimeRuleConfig {
     off: boolean;
-    apiProjectPaths: string[];
-    servicePaths: string[];
     ignoreModifiedUntilEpoch?: number;
     ignoreRuleWhileOnBranch?: string;
     allowedCycles: AllowedCycle[];

package/src/lib/runtime-config.js

@@ -7,7 +7,6 @@
  *
  *   "runtime-architecture": {
  *     "mode": "ON",                          // "OFF" disables the whole feature
- *     "apiProjectPaths": ["libraries/apis/*"],
  *     "ignoreModifiedUntilEpoch": 0,         // whole-rule punt (epoch seconds)
  *     "allowedCycles": [ { "services": ["a","b"], "reason": "...", "until": 1771931925 } ]
  *   }
@@ -30,8 +29,6 @@ function loadRuntimeConfig(workspaceRoot) {
     const raw = (rule?.options ?? {});
     return {
         off: rule?.isOff ?? false,
-        apiProjectPaths: Array.isArray(raw.apiProjectPaths) ? raw.apiProjectPaths : [],
-        servicePaths: Array.isArray(raw.servicePaths) ? raw.servicePaths : [],
         ignoreModifiedUntilEpoch: typeof raw.ignoreModifiedUntilEpoch === 'number' ? raw.ignoreModifiedUntilEpoch : undefined,
         ignoreRuleWhileOnBranch: typeof raw.ignoreRuleWhileOnBranch === 'string' ? raw.ignoreRuleWhileOnBranch : undefined,
         allowedCycles: Array.isArray(raw.allowedCycles) ? raw.allowedCycles.filter(isUsableCycle) : [],

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

@@ -1 +1 @@
-{"version":3,"file":"runtime-config.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-config.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAuCH,8CAcC;AAQD,8CAEC;AAMD,sCAGC;AAGD,8BAEC;AA3ED,0DAA0F;AAE7E,QAAA,iBAAiB,GAAG,sBAAsB,CAAC;AA8BxD,SAAS,aAAa,CAAC,KAAmB;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;AACtE,CAAC;AAED,sEAAsE;AACtE,SAAgB,iBAAiB,CAAC,aAAqB;IACnD,MAAM,MAAM,GAAG,IAAA,8BAAe,EAAC,aAAa,CAAC,CAAC,QAAQ,CAAC;IACvD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,yBAAiB,CAAC,CAAC;IACjD,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE,CAAmB,CAAC;IACpD,OAAO;QACH,GAAG,EAAE,IAAI,EAAE,KAAK,IAAI,KAAK;QACzB,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE;QAC9E,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE;QACrE,wBAAwB,EACpB,OAAO,GAAG,CAAC,wBAAwB,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC,CAAC,SAAS;QAC/F,uBAAuB,EACnB,OAAO,GAAG,CAAC,uBAAuB,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC,CAAC,SAAS;QAC7F,aAAa,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE;KACjG,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,MAAyB;IACvD,OAAO,IAAA,6BAAc,EAAC,MAAM,CAAC,wBAAwB,EAAE,MAAM,CAAC,uBAAuB,CAAC,CAAC;AAC3F,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAC,KAAyB;IACnD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,KAAK,CAAC;AACrC,CAAC;AAED,wDAAwD;AACxD,SAAgB,SAAS,CAAC,KAAa;IACnC,OAAO,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC","sourcesContent":["/**\n * Runtime Config\n *\n * Loads the `runtime-architecture` rule from webpieces.config.json and exposes\n * typed accessors shared by the generate + validate + visualize executors.\n *\n *   \"runtime-architecture\": {\n *     \"mode\": \"ON\",                          // \"OFF\" disables the whole feature\n *     \"apiProjectPaths\": [\"libraries/apis/*\"],\n *     \"ignoreModifiedUntilEpoch\": 0,         // whole-rule punt (epoch seconds)\n *     \"allowedCycles\": [ { \"services\": [\"a\",\"b\"], \"reason\": \"...\", \"until\": 1771931925 } ]\n *   }\n */\n\nimport { loadAndValidate, shouldSkipRule, SkipRuleResult } from '@webpieces/rules-config';\n\nexport const RUNTIME_RULE_NAME = 'runtime-architecture';\n\nexport interface AllowedCycle {\n    services: string[];\n    reason?: string;\n    until?: number;\n}\n\nexport interface RuntimeRuleConfig {\n    off: boolean;\n    apiProjectPaths: string[];\n    servicePaths: string[];\n    ignoreModifiedUntilEpoch?: number;\n    ignoreRuleWhileOnBranch?: string;\n    allowedCycles: AllowedCycle[];\n}\n\n/**\n * Typed view of the opaque webpieces.config.json option bag for this rule. The\n * config is trusted (it is the workspace's own file), so we cast once here and\n * defensively narrow arrays/numbers rather than threading `unknown` everywhere.\n */\ninterface RuntimeRuleRaw {\n    apiProjectPaths?: string[];\n    servicePaths?: string[];\n    ignoreModifiedUntilEpoch?: number;\n    ignoreRuleWhileOnBranch?: string;\n    allowedCycles?: AllowedCycle[];\n}\n\nfunction isUsableCycle(cycle: AllowedCycle): boolean {\n    return Array.isArray(cycle.services) && cycle.services.length > 0;\n}\n\n/** Load the runtime-architecture rule config (with safe defaults). */\nexport function loadRuntimeConfig(workspaceRoot: string): RuntimeRuleConfig {\n    const shared = loadAndValidate(workspaceRoot).resolved;\n    const rule = shared.rules.get(RUNTIME_RULE_NAME);\n    const raw = (rule?.options ?? {}) as RuntimeRuleRaw;\n    return {\n        off: rule?.isOff ?? false,\n        apiProjectPaths: Array.isArray(raw.apiProjectPaths) ? raw.apiProjectPaths : [],\n        servicePaths: Array.isArray(raw.servicePaths) ? raw.servicePaths : [],\n        ignoreModifiedUntilEpoch:\n            typeof raw.ignoreModifiedUntilEpoch === 'number' ? raw.ignoreModifiedUntilEpoch : undefined,\n        ignoreRuleWhileOnBranch:\n            typeof raw.ignoreRuleWhileOnBranch === 'string' ? raw.ignoreRuleWhileOnBranch : undefined,\n        allowedCycles: Array.isArray(raw.allowedCycles) ? raw.allowedCycles.filter(isUsableCycle) : [],\n    };\n}\n\n/**\n * Whole-rule report-only window honoring BOTH escape hatches: skip while on the\n * named branch (ignoreRuleWhileOnBranch) or until the epoch passes\n * (ignoreModifiedUntilEpoch). When `.skip` is true, problems are reported but\n * the build is not failed.\n */\nexport function runtimeReportOnly(config: RuntimeRuleConfig): SkipRuleResult {\n    return shouldSkipRule(config.ignoreModifiedUntilEpoch, config.ignoreRuleWhileOnBranch);\n}\n\n/**\n * Whole-rule grace window: while now < epoch, failures are reported but do not\n * fail the build (warn). Mirrors the other webpieces rules.\n */\nexport function isGraceActive(epoch: number | undefined): boolean {\n    if (epoch === undefined) return false;\n    return Date.now() / 1000 < epoch;\n}\n\n/** Format the epoch as an ISO date for log messages. */\nexport function epochDate(epoch: number): string {\n    return new Date(epoch * 1000).toISOString().split('T')[0];\n}\n"]}
+{"version":3,"file":"runtime-config.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-config.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAmCH,8CAYC;AAQD,8CAEC;AAMD,sCAGC;AAGD,8BAEC;AArED,0DAA0F;AAE7E,QAAA,iBAAiB,GAAG,sBAAsB,CAAC;AA0BxD,SAAS,aAAa,CAAC,KAAmB;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;AACtE,CAAC;AAED,sEAAsE;AACtE,SAAgB,iBAAiB,CAAC,aAAqB;IACnD,MAAM,MAAM,GAAG,IAAA,8BAAe,EAAC,aAAa,CAAC,CAAC,QAAQ,CAAC;IACvD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,yBAAiB,CAAC,CAAC;IACjD,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE,CAAmB,CAAC;IACpD,OAAO;QACH,GAAG,EAAE,IAAI,EAAE,KAAK,IAAI,KAAK;QACzB,wBAAwB,EACpB,OAAO,GAAG,CAAC,wBAAwB,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC,CAAC,SAAS;QAC/F,uBAAuB,EACnB,OAAO,GAAG,CAAC,uBAAuB,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC,CAAC,SAAS;QAC7F,aAAa,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE;KACjG,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,MAAyB;IACvD,OAAO,IAAA,6BAAc,EAAC,MAAM,CAAC,wBAAwB,EAAE,MAAM,CAAC,uBAAuB,CAAC,CAAC;AAC3F,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAC,KAAyB;IACnD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,KAAK,CAAC;AACrC,CAAC;AAED,wDAAwD;AACxD,SAAgB,SAAS,CAAC,KAAa;IACnC,OAAO,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC","sourcesContent":["/**\n * Runtime Config\n *\n * Loads the `runtime-architecture` rule from webpieces.config.json and exposes\n * typed accessors shared by the generate + validate + visualize executors.\n *\n *   \"runtime-architecture\": {\n *     \"mode\": \"ON\",                          // \"OFF\" disables the whole feature\n *     \"ignoreModifiedUntilEpoch\": 0,         // whole-rule punt (epoch seconds)\n *     \"allowedCycles\": [ { \"services\": [\"a\",\"b\"], \"reason\": \"...\", \"until\": 1771931925 } ]\n *   }\n */\n\nimport { loadAndValidate, shouldSkipRule, SkipRuleResult } from '@webpieces/rules-config';\n\nexport const RUNTIME_RULE_NAME = 'runtime-architecture';\n\nexport interface AllowedCycle {\n    services: string[];\n    reason?: string;\n    until?: number;\n}\n\nexport interface RuntimeRuleConfig {\n    off: boolean;\n    ignoreModifiedUntilEpoch?: number;\n    ignoreRuleWhileOnBranch?: string;\n    allowedCycles: AllowedCycle[];\n}\n\n/**\n * Typed view of the opaque webpieces.config.json option bag for this rule. The\n * config is trusted (it is the workspace's own file), so we cast once here and\n * defensively narrow arrays/numbers rather than threading `unknown` everywhere.\n */\ninterface RuntimeRuleRaw {\n    ignoreModifiedUntilEpoch?: number;\n    ignoreRuleWhileOnBranch?: string;\n    allowedCycles?: AllowedCycle[];\n}\n\nfunction isUsableCycle(cycle: AllowedCycle): boolean {\n    return Array.isArray(cycle.services) && cycle.services.length > 0;\n}\n\n/** Load the runtime-architecture rule config (with safe defaults). */\nexport function loadRuntimeConfig(workspaceRoot: string): RuntimeRuleConfig {\n    const shared = loadAndValidate(workspaceRoot).resolved;\n    const rule = shared.rules.get(RUNTIME_RULE_NAME);\n    const raw = (rule?.options ?? {}) as RuntimeRuleRaw;\n    return {\n        off: rule?.isOff ?? false,\n        ignoreModifiedUntilEpoch:\n            typeof raw.ignoreModifiedUntilEpoch === 'number' ? raw.ignoreModifiedUntilEpoch : undefined,\n        ignoreRuleWhileOnBranch:\n            typeof raw.ignoreRuleWhileOnBranch === 'string' ? raw.ignoreRuleWhileOnBranch : undefined,\n        allowedCycles: Array.isArray(raw.allowedCycles) ? raw.allowedCycles.filter(isUsableCycle) : [],\n    };\n}\n\n/**\n * Whole-rule report-only window honoring BOTH escape hatches: skip while on the\n * named branch (ignoreRuleWhileOnBranch) or until the epoch passes\n * (ignoreModifiedUntilEpoch). When `.skip` is true, problems are reported but\n * the build is not failed.\n */\nexport function runtimeReportOnly(config: RuntimeRuleConfig): SkipRuleResult {\n    return shouldSkipRule(config.ignoreModifiedUntilEpoch, config.ignoreRuleWhileOnBranch);\n}\n\n/**\n * Whole-rule grace window: while now < epoch, failures are reported but do not\n * fail the build (warn). Mirrors the other webpieces rules.\n */\nexport function isGraceActive(epoch: number | undefined): boolean {\n    if (epoch === undefined) return false;\n    return Date.now() / 1000 < epoch;\n}\n\n/** Format the epoch as an ISO date for log messages. */\nexport function epochDate(epoch: number): string {\n    return new Date(epoch * 1000).toISOString().split('T')[0];\n}\n"]}

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

@@ -1,16 +1,18 @@
 /**
  * Runtime Graph
  *
- * Assembles the runtime microservice graph from the per-service
- * `service-contract.json` files, and saves/loads the committed
- * `architecture/runtime-dependencies.json`.
+ * Derives the runtime microservice graph SOLELY from architecture/dependencies.json
+ * (the single source of truth): each project's `apiRelations` carry which api
+ * classes it implements/uses and their transport (rpc | pubsub). Both
+ * `architecture:generate` and `architecture:validate-runtime-architecture` call
+ * the SAME `deriveRuntimeGraph`, so the committed graph and the validated graph
+ * can never diverge.
  *
  * The runtime edge Z -> X (Z depends on X at runtime) is INFERRED: Z `uses` api
  * Y and X `implements` api Y. This edge does not exist in the compile-time
  * dependencies.json (both Z and X only compile-depend on the api library Y).
  */
-import type { WorkspaceModel } from './runtime-markers';
-import type { ApiScanResult } from './api-usage/api-scanner';
+import type { EnhancedGraph } from './graph-sorter';
 import type { ApiTransport } from './api-usage/api-relations';
 export declare const DEFAULT_RUNTIME_GRAPH_PATH = "architecture/runtime-dependencies.json";
 export interface RuntimeService {
@@ -18,6 +20,14 @@ export interface RuntimeService {
     implements: string[];
     uses: string[];
     dependsOn: string[];
+    /**
+     * When false, this service is hidden from the rendered runtime graph (its
+     * node AND every edge touching it are omitted from the HTML/DOT). It stays
+     * in runtime-dependencies.json so the data view is complete. Absent means
+     * drawn (the default). Mirrors GraphEntry.drawOnGraph from the `drawOnGraph:`
+     * nx tag.
+     */
+    drawOnGraph?: boolean;
 }
 export interface RuntimeApi {
     implementedBy: string[];
@@ -48,10 +58,13 @@ export interface RuntimeGraph {
 }
 /** Adjacency (service -> [targets]) from a loaded runtime graph. */
 export declare function runtimeAdjacency(graph: RuntimeGraph): Record<string, string[]>;
-/** Assemble the full runtime graph from the workspace model + service contracts. */
-export declare function assembleRuntimeGraph(model: WorkspaceModel, workspaceRoot: string): RuntimeGraph;
-/** Assemble the runtime graph from the source scan (the derived apiRelations). */
-export declare function assembleRuntimeGraphFromScan(scan: ApiScanResult): RuntimeGraph;
+/**
+ * Derive the runtime graph from dependencies.json's project `apiRelations` — the
+ * single source of truth shared by generate + validate. `hiddenProjects`
+ * (drawOnGraph:false, defaults to none) are kept in the graph but flagged so the
+ * runtime visualizer omits their nodes + edges.
+ */
+export declare function deriveRuntimeGraph(projects: EnhancedGraph, hiddenProjects?: Set<string>): RuntimeGraph;
 export declare function saveRuntimeGraph(graph: RuntimeGraph, workspaceRoot: string, graphPath?: string): void;
 export declare function runtimeGraphFileExists(workspaceRoot: string, graphPath?: string): boolean;
 export declare function loadRuntimeGraph(workspaceRoot: string, graphPath?: string): RuntimeGraph | null;

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

@@ -1 +1 @@
-{"version":3,"file":"runtime-graph.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-graph.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Runtime Graph\n *\n * Assembles the runtime microservice graph from the per-service\n * `service-contract.json` files, and saves/loads the committed\n * `architecture/runtime-dependencies.json`.\n *\n * The runtime edge Z -> X (Z depends on X at runtime) is INFERRED: Z `uses` api\n * Y and X `implements` api Y. This edge does not exist in the compile-time\n * dependencies.json (both Z and X only compile-depend on the api library Y).\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { sortGraphTopologically } from './graph-sorter';\nimport { readServiceContract, resolvePackageNames } from './runtime-markers';\nimport type { WorkspaceModel } from './runtime-markers';\nimport type { ApiScanResult } from './api-usage/api-scanner';\nimport type { ApiRef, ApiTransport } from './api-usage/api-relations';\nimport { sortApiRefs } from './api-usage/api-relations';\nimport { toError } from '../toError';\n\nexport const DEFAULT_RUNTIME_GRAPH_PATH = 'architecture/runtime-dependencies.json';\n\nexport interface RuntimeService {\n    level: number;\n    implements: string[];\n    uses: string[];\n    dependsOn: string[];\n}\n\nexport interface RuntimeApi {\n    implementedBy: string[];\n    usedBy: string[];\n    /** Transport of this API — 'rpc' (direct call) or 'pubsub' (delivered through a queue). */\n    type?: ApiTransport;\n}\n\nexport interface RuntimeEdge {\n    from: string;\n    to: string;\n    via: string[];\n    /**\n     * Transport of this edge. 'rpc' → a direct call arrow. 'pubsub' → the producer enqueues and the\n     * consumer is delivered later, so the runtime viz draws it as producer → QUEUE → consumer.\n     * Edges are split by transport, so every edge is a single kind.\n     */\n    type?: ApiTransport;\n}\n\nexport interface RuntimeUnresolved {\n    service: string;\n    api: string;\n}\n\nexport interface RuntimeGraph {\n    services: Record<string, RuntimeService>;\n    apis: Record<string, RuntimeApi>;\n    runtimeEdges: RuntimeEdge[];\n    unresolvedUses: RuntimeUnresolved[];\n}\n\n/** One service's declared relationships, resolved to workspace project names. */\ninterface ServiceDecl {\n    name: string;\n    implements: string[];\n    uses: string[];\n}\n\ninterface EdgeResult {\n    edges: RuntimeEdge[];\n    unresolved: RuntimeUnresolved[];\n}\n\n/** Collect every service project (servicePaths), with its declarations resolved to projects. */\nfunction collectServiceDecls(model: WorkspaceModel, workspaceRoot: string): ServiceDecl[] {\n    const decls: ServiceDecl[] = [];\n    for (const info of model.projects.values()) {\n        if (!info.isService) continue;\n        // A service missing its contract still appears as a node (empty edges);\n        // validate-runtime-markers fails it separately for the missing file.\n        const contract = readServiceContract(workspaceRoot, info.root);\n        const implementsPkgs = contract ? contract.implements : [];\n        const usesPkgs = contract ? contract.uses : [];\n        decls.push({\n            name: info.name,\n            implements: resolvePackageNames(model, implementsPkgs).projects.sort(),\n            uses: resolvePackageNames(model, usesPkgs).projects.sort(),\n        });\n    }\n    return decls.sort((a: ServiceDecl, b: ServiceDecl) => a.name.localeCompare(b.name));\n}\n\nfunction buildApiIndex(decls: ServiceDecl[]): Map<string, RuntimeApi> {\n    const apis = new Map<string, RuntimeApi>();\n    const ensure = (api: string): RuntimeApi => {\n        let entry = apis.get(api);\n        if (!entry) {\n            entry = { implementedBy: [], usedBy: [] };\n            apis.set(api, entry);\n        }\n        return entry;\n    };\n    for (const decl of decls) {\n        for (const api of decl.implements) ensure(api).implementedBy.push(decl.name);\n        for (const api of decl.uses) ensure(api).usedBy.push(decl.name);\n    }\n    for (const entry of apis.values()) {\n        entry.implementedBy.sort();\n        entry.usedBy.sort();\n    }\n    return apis;\n}\n\n/** Build inferred runtime edges (Z -> X via Y) and the unresolved-uses list. */\nfunction buildEdges(decls: ServiceDecl[], apis: Map<string, RuntimeApi>): EdgeResult {\n    const viaByEdge = new Map<string, Set<string>>();\n    const unresolved: RuntimeUnresolved[] = [];\n\n    for (const decl of decls) {\n        for (const api of decl.uses) {\n            const implementers = apis.get(api)?.implementedBy ?? [];\n            if (implementers.length === 0) {\n                unresolved.push({ service: decl.name, api });\n                continue;\n            }\n            for (const target of implementers) {\n                if (target === decl.name) continue;\n                const key = `${decl.name} ${target}`;\n                if (!viaByEdge.has(key)) viaByEdge.set(key, new Set());\n                viaByEdge.get(key)!.add(api);\n            }\n        }\n    }\n\n    const edges: RuntimeEdge[] = [];\n    for (const key of viaByEdge.keys()) {\n        const parts = key.split(' ');\n        edges.push({ from: parts[0], to: parts[1], via: Array.from(viaByEdge.get(key)!).sort() });\n    }\n    edges.sort((a: RuntimeEdge, b: RuntimeEdge) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to));\n    unresolved.sort(\n        (a: RuntimeUnresolved, b: RuntimeUnresolved) =>\n            a.service.localeCompare(b.service) || a.api.localeCompare(b.api),\n    );\n    return { edges, unresolved };\n}\n\n/** Adjacency (service -> [targets]) used for leveling + cycle checks. */\nfunction adjacencyFromEdges(serviceNames: string[], edges: RuntimeEdge[]): Record<string, string[]> {\n    const adj: Record<string, string[]> = {};\n    for (const name of serviceNames) adj[name] = [];\n    for (const edge of edges) {\n        if (!adj[edge.from]) adj[edge.from] = [];\n        adj[edge.from].push(edge.to);\n    }\n    return adj;\n}\n\n/** Adjacency (service -> [targets]) from a loaded runtime graph. */\nexport function runtimeAdjacency(graph: RuntimeGraph): Record<string, string[]> {\n    return adjacencyFromEdges(Object.keys(graph.services), graph.runtimeEdges);\n}\n\n/** Assign levels via topological sort; falls back to level 0 when a cycle exists. */\nfunction assignLevels(adjacency: Record<string, string[]>): Record<string, number> {\n    const levels: Record<string, number> = {};\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const sorted = sortGraphTopologically(adjacency);\n        for (const name of Object.keys(sorted)) levels[name] = sorted[name].level;\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error;\n        for (const name of Object.keys(adjacency)) levels[name] = 0;\n    }\n    return levels;\n}\n\n/** Assemble the full runtime graph from the workspace model + service contracts. */\nexport function assembleRuntimeGraph(model: WorkspaceModel, workspaceRoot: string): RuntimeGraph {\n    const decls = collectServiceDecls(model, workspaceRoot);\n    const apis = buildApiIndex(decls);\n    const edgeResult = buildEdges(decls, apis);\n\n    const services: Record<string, RuntimeService> = {};\n    for (const decl of decls) {\n        const dependsOn = Array.from(\n            new Set(edgeResult.edges.filter((e: RuntimeEdge) => e.from === decl.name).map((e: RuntimeEdge) => e.to)),\n        ).sort();\n        services[decl.name] = { level: 0, implements: decl.implements, uses: decl.uses, dependsOn };\n    }\n\n    const levels = assignLevels(adjacencyFromEdges(Object.keys(services), edgeResult.edges));\n    for (const name of Object.keys(services)) services[name].level = levels[name] ?? 0;\n\n    const apisObj: Record<string, RuntimeApi> = {};\n    for (const api of Array.from(apis.keys()).sort()) apisObj[api] = apis.get(api)!;\n\n    return {\n        services,\n        apis: apisObj,\n        runtimeEdges: edgeResult.edges,\n        unresolvedUses: edgeResult.unresolved,\n    };\n}\n\n/** One project's implements/uses at api-CLASS granularity, from the source scan. */\ninterface ScanDecl {\n    name: string;\n    implementsApis: ApiRef[];\n    usesApis: ApiRef[];\n}\n\n/**\n * Assembles the runtime microservice graph from the SOURCE SCAN (apiRelations) instead of\n * service-contract.json: implementers × users per API, split by transport. An rpc edge is a direct\n * call; a pubsub edge flows through a queue (drawn producer → queue → consumer by the visualizer).\n */\nclass ScanRuntimeAssembler {\n    constructor(private readonly scan: ApiScanResult) {}\n\n    assemble(): RuntimeGraph {\n        const decls = this.collectDecls();\n        const apis = this.buildApis(decls);\n        const edgeResult = this.buildEdges(decls, apis);\n        const services = this.buildServices(decls, edgeResult.edges);\n        const apisObj: Record<string, RuntimeApi> = {};\n        for (const api of Array.from(apis.keys()).sort()) apisObj[api] = apis.get(api)!;\n        return { services, apis: apisObj, runtimeEdges: edgeResult.edges, unresolvedUses: edgeResult.unresolved };\n    }\n\n    /** Flatten each project's api-lib relations into implements/uses ApiRef lists. */\n    private collectDecls(): ScanDecl[] {\n        const decls: ScanDecl[] = [];\n        for (const name of Array.from(this.scan.relationsByProject.keys()).sort()) {\n            const relations = this.scan.relationsByProject.get(name)!;\n            const implementsApis: ApiRef[] = [];\n            const usesApis: ApiRef[] = [];\n            for (const owner of Object.keys(relations)) {\n                implementsApis.push(...relations[owner].implements);\n                usesApis.push(...relations[owner].uses);\n            }\n            if (implementsApis.length > 0 || usesApis.length > 0) {\n                decls.push({ name, implementsApis: sortApiRefs(implementsApis), usesApis: sortApiRefs(usesApis) });\n            }\n        }\n        return decls;\n    }\n\n    /** apiClassName -> { implementedBy, usedBy, type }. */\n    private buildApis(decls: ScanDecl[]): Map<string, RuntimeApi> {\n        const apis = new Map<string, RuntimeApi>();\n        const ensure = (api: string, type: ApiTransport): RuntimeApi => {\n            let entry = apis.get(api);\n            if (!entry) {\n                entry = { implementedBy: [], usedBy: [], type };\n                apis.set(api, entry);\n            }\n            return entry;\n        };\n        for (const decl of decls) {\n            for (const ref of decl.implementsApis) ensure(ref.api, ref.type).implementedBy.push(decl.name);\n            for (const ref of decl.usesApis) ensure(ref.api, ref.type).usedBy.push(decl.name);\n        }\n        for (const entry of apis.values()) {\n            entry.implementedBy.sort();\n            entry.usedBy.sort();\n        }\n        return apis;\n    }\n\n    /** Inferred edges U -> I via api A, split by transport; plus uses with no implementer. */\n    private buildEdges(decls: ScanDecl[], apis: Map<string, RuntimeApi>): EdgeResult {\n        const viaByKey = new Map<string, Set<string>>();\n        const unresolved: RuntimeUnresolved[] = [];\n        for (const decl of decls) {\n            for (const ref of decl.usesApis) {\n                const implementers = apis.get(ref.api)?.implementedBy ?? [];\n                if (implementers.length === 0) {\n                    unresolved.push({ service: decl.name, api: ref.api });\n                    continue;\n                }\n                for (const target of implementers) {\n                    if (target === decl.name) continue;\n                    const key = `${decl.name}\u0000${target}\u0000${ref.type}`;\n                    if (!viaByKey.has(key)) viaByKey.set(key, new Set());\n                    viaByKey.get(key)!.add(ref.api);\n                }\n            }\n        }\n        return { edges: this.edgesFromKeys(viaByKey), unresolved: sortUnresolved(unresolved) };\n    }\n\n    private edgesFromKeys(viaByKey: Map<string, Set<string>>): RuntimeEdge[] {\n        const edges: RuntimeEdge[] = [];\n        for (const key of viaByKey.keys()) {\n            const parts = key.split('\u0000');\n            edges.push({ from: parts[0], to: parts[1], via: Array.from(viaByKey.get(key)!).sort(), type: parts[2] as ApiTransport });\n        }\n        edges.sort(\n            (a: RuntimeEdge, b: RuntimeEdge) =>\n                a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || (a.type ?? '').localeCompare(b.type ?? ''),\n        );\n        return edges;\n    }\n\n    private buildServices(decls: ScanDecl[], edges: RuntimeEdge[]): Record<string, RuntimeService> {\n        const services: Record<string, RuntimeService> = {};\n        for (const decl of decls) {\n            const dependsOn = Array.from(\n                new Set(edges.filter((e: RuntimeEdge) => e.from === decl.name).map((e: RuntimeEdge) => e.to)),\n            ).sort();\n            services[decl.name] = {\n                level: 0,\n                implements: decl.implementsApis.map((r: ApiRef) => r.api),\n                uses: decl.usesApis.map((r: ApiRef) => r.api),\n                dependsOn,\n            };\n        }\n        const levels = assignLevels(adjacencyFromEdges(Object.keys(services), edges));\n        for (const name of Object.keys(services)) services[name].level = levels[name] ?? 0;\n        return services;\n    }\n}\n\n/** Assemble the runtime graph from the source scan (the derived apiRelations). */\n// webpieces-disable no-function-outside-class -- module entry point, mirrors assembleRuntimeGraph\nexport function assembleRuntimeGraphFromScan(scan: ApiScanResult): RuntimeGraph {\n    return new ScanRuntimeAssembler(scan).assemble();\n}\n\n// webpieces-disable no-function-outside-class -- pure sort helper, matches the sibling helpers in this file\nfunction sortUnresolved(unresolved: RuntimeUnresolved[]): RuntimeUnresolved[] {\n    return [...unresolved].sort(\n        (a: RuntimeUnresolved, b: RuntimeUnresolved) => a.service.localeCompare(b.service) || a.api.localeCompare(b.api),\n    );\n}\n\n/** Deterministic JSON (sorted keys + arrays already sorted during assembly). */\nfunction formatRuntimeJson(graph: RuntimeGraph): string {\n    return JSON.stringify(graph, null, 4) + '\\n';\n}\n\nexport function saveRuntimeGraph(\n    graph: RuntimeGraph,\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): void {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    const dir = path.dirname(fullPath);\n    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });\n    fs.writeFileSync(fullPath, formatRuntimeJson(graph), 'utf-8');\n}\n\nexport function runtimeGraphFileExists(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): boolean {\n    return fs.existsSync(path.join(workspaceRoot, graphPath));\n}\n\nexport function loadRuntimeGraph(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): RuntimeGraph | null {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    if (!fs.existsSync(fullPath)) return null;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        return JSON.parse(fs.readFileSync(fullPath, 'utf-8')) as RuntimeGraph;\n    } catch (err: unknown) {\n        const error = toError(err);\n        throw new Error(`Failed to load runtime graph from ${fullPath}`, { cause: error });\n    }\n}\n\n/** Serialize for an in-memory equality check (matches the on-disk format). */\nexport function serializeRuntimeGraph(graph: RuntimeGraph): string {\n    return formatRuntimeJson(graph);\n}\n"]}
+{"version":3,"file":"runtime-graph.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-graph.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Runtime Graph\n *\n * Derives the runtime microservice graph SOLELY from architecture/dependencies.json\n * (the single source of truth): each project's `apiRelations` carry which api\n * classes it implements/uses and their transport (rpc | pubsub). Both\n * `architecture:generate` and `architecture:validate-runtime-architecture` call\n * the SAME `deriveRuntimeGraph`, so the committed graph and the validated graph\n * can never diverge.\n *\n * The runtime edge Z -> X (Z depends on X at runtime) is INFERRED: Z `uses` api\n * Y and X `implements` api Y. This edge does not exist in the compile-time\n * dependencies.json (both Z and X only compile-depend on the api library Y).\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { sortGraphTopologically } from './graph-sorter';\nimport type { EnhancedGraph } from './graph-sorter';\nimport type { ApiRef, ApiTransport } from './api-usage/api-relations';\nimport { sortApiRefs } from './api-usage/api-relations';\nimport { toError } from '../toError';\n\nexport const DEFAULT_RUNTIME_GRAPH_PATH = 'architecture/runtime-dependencies.json';\n\nexport interface RuntimeService {\n    level: number;\n    implements: string[];\n    uses: string[];\n    dependsOn: string[];\n    /**\n     * When false, this service is hidden from the rendered runtime graph (its\n     * node AND every edge touching it are omitted from the HTML/DOT). It stays\n     * in runtime-dependencies.json so the data view is complete. Absent means\n     * drawn (the default). Mirrors GraphEntry.drawOnGraph from the `drawOnGraph:`\n     * nx tag.\n     */\n    drawOnGraph?: boolean;\n}\n\nexport interface RuntimeApi {\n    implementedBy: string[];\n    usedBy: string[];\n    /** Transport of this API — 'rpc' (direct call) or 'pubsub' (delivered through a queue). */\n    type?: ApiTransport;\n}\n\nexport interface RuntimeEdge {\n    from: string;\n    to: string;\n    via: string[];\n    /**\n     * Transport of this edge. 'rpc' → a direct call arrow. 'pubsub' → the producer enqueues and the\n     * consumer is delivered later, so the runtime viz draws it as producer → QUEUE → consumer.\n     * Edges are split by transport, so every edge is a single kind.\n     */\n    type?: ApiTransport;\n}\n\nexport interface RuntimeUnresolved {\n    service: string;\n    api: string;\n}\n\nexport interface RuntimeGraph {\n    services: Record<string, RuntimeService>;\n    apis: Record<string, RuntimeApi>;\n    runtimeEdges: RuntimeEdge[];\n    unresolvedUses: RuntimeUnresolved[];\n}\n\ninterface EdgeResult {\n    edges: RuntimeEdge[];\n    unresolved: RuntimeUnresolved[];\n}\n\n/** Adjacency (service -> [targets]) used for leveling + cycle checks. */\nfunction adjacencyFromEdges(serviceNames: string[], edges: RuntimeEdge[]): Record<string, string[]> {\n    const adj: Record<string, string[]> = {};\n    for (const name of serviceNames) adj[name] = [];\n    for (const edge of edges) {\n        if (!adj[edge.from]) adj[edge.from] = [];\n        adj[edge.from].push(edge.to);\n    }\n    return adj;\n}\n\n/** Adjacency (service -> [targets]) from a loaded runtime graph. */\nexport function runtimeAdjacency(graph: RuntimeGraph): Record<string, string[]> {\n    return adjacencyFromEdges(Object.keys(graph.services), graph.runtimeEdges);\n}\n\n/** Assign levels via topological sort; falls back to level 0 when a cycle exists. */\nfunction assignLevels(adjacency: Record<string, string[]>): Record<string, number> {\n    const levels: Record<string, number> = {};\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const sorted = sortGraphTopologically(adjacency);\n        for (const name of Object.keys(sorted)) levels[name] = sorted[name].level;\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error;\n        for (const name of Object.keys(adjacency)) levels[name] = 0;\n    }\n    return levels;\n}\n\n/** One project's implements/uses at api-CLASS granularity, from dependencies.json apiRelations. */\ninterface ScanDecl {\n    name: string;\n    implementsApis: ApiRef[];\n    usesApis: ApiRef[];\n}\n\n/**\n * Derives the runtime microservice graph from architecture/dependencies.json `apiRelations`:\n * implementers × users per API, split by transport. An rpc edge is a direct call; a pubsub edge flows\n * through a queue (drawn producer → queue → consumer by the visualizer).\n */\nclass RuntimeGraphDeriver {\n    constructor(\n        private readonly projects: EnhancedGraph,\n        /** Project names tagged drawOnGraph:false — kept in the JSON but flagged so the viz omits them. */\n        private readonly hiddenProjects: Set<string>\n    ) {}\n\n    assemble(): RuntimeGraph {\n        const decls = this.collectDecls();\n        const apis = this.buildApis(decls);\n        const edgeResult = this.buildEdges(decls, apis);\n        const services = this.buildServices(decls, edgeResult.edges);\n        const apisObj: Record<string, RuntimeApi> = {};\n        for (const api of Array.from(apis.keys()).sort()) apisObj[api] = apis.get(api)!;\n        return { services, apis: apisObj, runtimeEdges: edgeResult.edges, unresolvedUses: edgeResult.unresolved };\n    }\n\n    /** Flatten each project's api-lib relations into implements/uses ApiRef lists. */\n    private collectDecls(): ScanDecl[] {\n        const decls: ScanDecl[] = [];\n        for (const name of Object.keys(this.projects).sort()) {\n            const relations = this.projects[name].apiRelations;\n            if (relations === undefined) continue;\n            const implementsApis: ApiRef[] = [];\n            const usesApis: ApiRef[] = [];\n            for (const owner of Object.keys(relations)) {\n                implementsApis.push(...relations[owner].implements);\n                usesApis.push(...relations[owner].uses);\n            }\n            if (implementsApis.length > 0 || usesApis.length > 0) {\n                decls.push({ name, implementsApis: sortApiRefs(implementsApis), usesApis: sortApiRefs(usesApis) });\n            }\n        }\n        return decls;\n    }\n\n    /** apiClassName -> { implementedBy, usedBy, type }. */\n    private buildApis(decls: ScanDecl[]): Map<string, RuntimeApi> {\n        const apis = new Map<string, RuntimeApi>();\n        const ensure = (api: string, type: ApiTransport): RuntimeApi => {\n            let entry = apis.get(api);\n            if (!entry) {\n                entry = { implementedBy: [], usedBy: [], type };\n                apis.set(api, entry);\n            }\n            return entry;\n        };\n        for (const decl of decls) {\n            for (const ref of decl.implementsApis) ensure(ref.api, ref.type).implementedBy.push(decl.name);\n            for (const ref of decl.usesApis) ensure(ref.api, ref.type).usedBy.push(decl.name);\n        }\n        for (const entry of apis.values()) {\n            entry.implementedBy.sort();\n            entry.usedBy.sort();\n        }\n        return apis;\n    }\n\n    /** Inferred edges U -> I via api A, split by transport; plus uses with no implementer. */\n    private buildEdges(decls: ScanDecl[], apis: Map<string, RuntimeApi>): EdgeResult {\n        const viaByKey = new Map<string, Set<string>>();\n        const unresolved: RuntimeUnresolved[] = [];\n        for (const decl of decls) {\n            for (const ref of decl.usesApis) {\n                const implementers = apis.get(ref.api)?.implementedBy ?? [];\n                if (implementers.length === 0) {\n                    unresolved.push({ service: decl.name, api: ref.api });\n                    continue;\n                }\n                for (const target of implementers) {\n                    if (target === decl.name) continue;\n                    const key = `${decl.name}\u0000${target}\u0000${ref.type}`;\n                    if (!viaByKey.has(key)) viaByKey.set(key, new Set());\n                    viaByKey.get(key)!.add(ref.api);\n                }\n            }\n        }\n        return { edges: this.edgesFromKeys(viaByKey), unresolved: sortUnresolved(unresolved) };\n    }\n\n    private edgesFromKeys(viaByKey: Map<string, Set<string>>): RuntimeEdge[] {\n        const edges: RuntimeEdge[] = [];\n        for (const key of viaByKey.keys()) {\n            const parts = key.split('\u0000');\n            edges.push({ from: parts[0], to: parts[1], via: Array.from(viaByKey.get(key)!).sort(), type: parts[2] as ApiTransport });\n        }\n        edges.sort(\n            (a: RuntimeEdge, b: RuntimeEdge) =>\n                a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || (a.type ?? '').localeCompare(b.type ?? ''),\n        );\n        return edges;\n    }\n\n    private buildServices(decls: ScanDecl[], edges: RuntimeEdge[]): Record<string, RuntimeService> {\n        const services: Record<string, RuntimeService> = {};\n        for (const decl of decls) {\n            const dependsOn = Array.from(\n                new Set(edges.filter((e: RuntimeEdge) => e.from === decl.name).map((e: RuntimeEdge) => e.to)),\n            ).sort();\n            services[decl.name] = {\n                level: 0,\n                implements: decl.implementsApis.map((r: ApiRef) => r.api),\n                uses: decl.usesApis.map((r: ApiRef) => r.api),\n                dependsOn,\n            };\n            if (this.hiddenProjects.has(decl.name)) services[decl.name].drawOnGraph = false;\n        }\n        const levels = assignLevels(adjacencyFromEdges(Object.keys(services), edges));\n        for (const name of Object.keys(services)) services[name].level = levels[name] ?? 0;\n        return services;\n    }\n}\n\n/**\n * Derive the runtime graph from dependencies.json's project `apiRelations` — the\n * single source of truth shared by generate + validate. `hiddenProjects`\n * (drawOnGraph:false, defaults to none) are kept in the graph but flagged so the\n * runtime visualizer omits their nodes + edges.\n */\n// webpieces-disable no-function-outside-class -- module entry point for the runtime graph derivation\nexport function deriveRuntimeGraph(\n    projects: EnhancedGraph,\n    hiddenProjects: Set<string> = new Set<string>()\n): RuntimeGraph {\n    return new RuntimeGraphDeriver(projects, hiddenProjects).assemble();\n}\n\n// webpieces-disable no-function-outside-class -- pure sort helper, matches the sibling helpers in this file\nfunction sortUnresolved(unresolved: RuntimeUnresolved[]): RuntimeUnresolved[] {\n    return [...unresolved].sort(\n        (a: RuntimeUnresolved, b: RuntimeUnresolved) => a.service.localeCompare(b.service) || a.api.localeCompare(b.api),\n    );\n}\n\n/** Deterministic JSON (sorted keys + arrays already sorted during assembly). */\nfunction formatRuntimeJson(graph: RuntimeGraph): string {\n    return JSON.stringify(graph, null, 4) + '\\n';\n}\n\nexport function saveRuntimeGraph(\n    graph: RuntimeGraph,\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): void {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    const dir = path.dirname(fullPath);\n    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });\n    fs.writeFileSync(fullPath, formatRuntimeJson(graph), 'utf-8');\n}\n\nexport function runtimeGraphFileExists(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): boolean {\n    return fs.existsSync(path.join(workspaceRoot, graphPath));\n}\n\nexport function loadRuntimeGraph(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): RuntimeGraph | null {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    if (!fs.existsSync(fullPath)) return null;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        return JSON.parse(fs.readFileSync(fullPath, 'utf-8')) as RuntimeGraph;\n    } catch (err: unknown) {\n        const error = toError(err);\n        throw new Error(`Failed to load runtime graph from ${fullPath}`, { cause: error });\n    }\n}\n\n/** Serialize for an in-memory equality check (matches the on-disk format). */\nexport function serializeRuntimeGraph(graph: RuntimeGraph): string {\n    return formatRuntimeJson(graph);\n}\n"]}