@webpieces/nx-webpieces-rules 0.3.260 → 0.3.261

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/nx-webpieces-rules",
-  "version": "0.3.260",
+  "version": "0.3.261",
   "description": "Nx-specific webpieces validation rules and graph tooling. Bundles all @webpieces rule packages with Nx graph validators and an inference plugin.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -21,11 +21,11 @@
     "README.md"
   ],
   "dependencies": {
-    "@webpieces/ai-hook-rules": "0.3.260",
-    "@webpieces/code-rules": "0.3.260",
-    "@webpieces/eslint-rules": "0.3.260",
-    "@webpieces/pr-gate": "0.3.260",
-    "@webpieces/rules-config": "0.3.260",
+    "@webpieces/ai-hook-rules": "0.3.261",
+    "@webpieces/code-rules": "0.3.261",
+    "@webpieces/eslint-rules": "0.3.261",
+    "@webpieces/pr-gate": "0.3.261",
+    "@webpieces/rules-config": "0.3.261",
     "madge": "8.0.0"
   },
   "peerDependencies": {

package/src/lib/graph-visualizer.js

@@ -46,6 +46,18 @@ function roleBorderAttrs(role) {
         return ', penwidth=2';
     return '';
 }
+/**
+ * Server and client apps are graph ROOTS — nothing depends on them and they
+ * never depend on one another. So instead of scattering them across rows by
+ * dependency depth (a server whose deepest dep is L3 vs one at L5), we pin every
+ * server/client to a single top row above the whole library stack. This
+ * declutters the diagram: the top row reads as "all the runnable apps," and
+ * everything below is the shared libraries. Their outgoing edges still point
+ * down into the libs, so no dependency is violated.
+ */
+function isPromotedRole(role) {
+    return role === 'server' || role === 'client';
+}
 /**
  * Remove scope from name for display
  * '@scope/name' → 'name'
@@ -83,12 +95,18 @@ function generateDot(graph, title = 'Monorepo Dependency Architecture') {
     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 row rank. Libs sit on their computed topological level;
+    // servers/clients are all promoted to one synthetic top rank (maxLevel + 1)
+    // so they share a single row strictly above every library.
+    const maxLevel = Math.max(0, ...Object.values(graph).map((info) => info.level));
+    const topRank = maxLevel + 1;
+    const rankOf = (info) => isPromotedRole(info.role ?? 'lib') ? topRank : info.level;
     const levels = {};
     for (const [project, info] of Object.entries(graph)) {
-        if (!levels[info.level])
-            levels[info.level] = [];
-        levels[info.level].push(project);
+        const rank = rankOf(info);
+        if (!levels[rank])
+            levels[rank] = [];
+        levels[rank].push(project);
     }
     // Nodes: fill colored by framework (libType), border shaped by role; the
     // label shows the framework-role combo (e.g. express-server, all-lib).
@@ -102,7 +120,10 @@ function generateDot(graph, title = 'Monorepo Dependency Architecture') {
         const border = roleBorderAttrs(role);
         const href = designHtmlHref(info.designFile);
         const link = href ? `, URL="${href}", target="_blank"` : '';
-        dot += `  "${shortName}" [fillcolor="${color}"${border}${link}, label="${shortName}\\n(L${info.level} · ${framework}-${role})"];\n`;
+        // Promoted apps (server/client) drop the L# — they no longer sit on their
+        // dependency level, so a level number in the label would be misleading.
+        const labelMeta = isPromotedRole(role) ? `${framework}-${role}` : `L${info.level} · ${framework}-${role}`;
+        dot += `  "${shortName}" [fillcolor="${color}"${border}${link}, label="${shortName}\\n(${labelMeta})"];\n`;
     }
     dot += '\n';
     // Create same-rank subgraphs for each level
@@ -241,7 +262,7 @@ function generateHTMLLegend() {
             <strong>lib:</strong> plain library, no generated design (thin border)
         </div>
         <div class="legend-item" style="margin-top: 15px;">
-            <em>Each node label shows its dependency level (L#) and framework-role (e.g. express-server, all-lib). Rows are laid out by level (top = no dependencies). Transitive dependencies are allowed but not shown.</em>
+            <em>Library nodes show their dependency level (L#) and framework-role (e.g. all-lib) and are laid out by level, with the deepest libraries at the bottom. Server and client apps are roots (nothing depends on them), so they are all pinned to the single top row regardless of dependency depth — their labels omit the L#. Transitive dependencies are allowed but not shown.</em>
         </div>
     </div>`;
 }

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 * Output files go to tmp/webpieces/ for easy viewing without committing.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { execSync } from 'child_process';\nimport type { EnhancedGraph } from './graph-sorter';\nimport { toError } from '../toError';\n\n/**\n * Framework (libType) colors for visualization — nodes are colored by which\n * client side they target so it is obvious at a glance which projects are\n * Angular, which are Express, and which libraries are shared (\"all\").\n */\nconst FRAMEWORK_COLORS: Record<string, string> = {\n    angular: '#FCE4EC', // pink   - Angular front-end\n    react: '#E3F2FD', // blue   - React front-end\n    express: '#E8F5E9', // green  - Express / server side\n    all: '#F5F5F5', // grey   - library usable by any side\n};\n\nconst DEFAULT_FRAMEWORK_COLOR = '#FFF3E0'; // orange - unknown/other libType\n\n/**\n * Role border styling — fill stays keyed on framework; the border shape shows a\n * project's ROLE at a glance:\n *   server       → double border (a runnable server app)\n *   client       → dashed border (a client app, e.g. angular)\n *   designed-lib → bold border   (a library with a generated @ApiImplementation design)\n *   lib / other  → plain thin border\n */\nfunction roleBorderAttrs(role: string): string {\n    if (role === 'server') return ', peripheries=2';\n    if (role === 'client') return ', style=\"filled,dashed\"';\n    if (role === 'designed-lib') return ', penwidth=2';\n    return '';\n}\n\n/**\n * Remove scope from name for display\n * '@scope/name' → 'name'\n * 'name' → 'name'\n */\nfunction getShortName(name: string): string {\n    return name.includes('/') ? name.split('/').pop()! : name;\n}\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\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 has\n * no generated DI design (no design.json → no clickable design page).\n *\n * designFile is repo-relative posix (e.g. 'packages/http/http-api/design.json');\n * we swap the extension and re-root it at architecture/ so the browser resolves\n * '../packages/http/http-api/design.html' from the checkout.\n */\nfunction 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 */\nexport function 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, info] of Object.entries(graph)) {\n        if (!levels[info.level]) levels[info.level] = [];\n        levels[info.level].push(project);\n    }\n\n    // Nodes: fill colored by framework (libType), border shaped by role; the\n    // label shows the framework-role combo (e.g. express-server, all-lib).\n    // A node with a generated DI design gets a URL so the rendered SVG box is\n    // clickable — it opens that project's committed design.html in a new tab.\n    for (const [project, info] of Object.entries(graph)) {\n        const shortName = getShortName(project);\n        const framework = info.framework ?? 'all';\n        const role = info.role ?? 'lib';\n        const color = FRAMEWORK_COLORS[framework] ?? DEFAULT_FRAMEWORK_COLOR;\n        const border = roleBorderAttrs(role);\n        const href = designHtmlHref(info.designFile);\n        const link = href ? `, URL=\"${href}\", target=\"_blank\"` : '';\n        dot += `  \"${shortName}\" [fillcolor=\"${color}\"${border}${link}, label=\"${shortName}\\\\n(L${info.level} · ${framework}-${role})\"];\\n`;\n    }\n\n    dot += '\\n';\n\n    // Create same-rank subgraphs for each level\n    for (const [level, projects] of Object.entries(levels)) {\n        dot += `  { rank=same; `;\n        projects.forEach((p) => {\n            const shortName = getShortName(p);\n            dot += `\"${shortName}\"; `;\n        });\n        dot += '}\\n';\n    }\n\n    dot += '\\n';\n\n    // Create edges (dependencies)\n    for (const [project, info] of Object.entries(graph)) {\n        const shortName = getShortName(project);\n        for (const dep of info.dependsOn || []) {\n            const depShortName = getShortName(dep);\n            dot += `  \"${shortName}\" -> \"${depShortName}\";\\n`;\n        }\n    }\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/**\n * Generate interactive HTML with embedded SVG using viz.js\n */\nexport function generateHTML(dot: string, title: string = 'Monorepo Dependency Architecture'): string {\n    const styles = generateHTMLStyles();\n    const legend = generateHTMLLegend();\n    const script = generateHTMLScript(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    ${legend}\n    <div id=\"graph\"></div>\n    <script>${script}</script>\n</body>\n</html>`;\n}\n\nfunction generateHTMLStyles(): string {\n    return `\n        body {\n            margin: 0;\n            padding: 20px;\n            font-family: Arial, sans-serif;\n            background: #f5f5f5;\n        }\n        h1 {\n            text-align: center;\n            color: #333;\n        }\n        .hint {\n            text-align: center;\n            color: #555;\n            margin: 0 0 16px;\n        }\n        /* viz.js renders node URLs as <a> — show they are clickable. */\n        #graph a { cursor: pointer; }\n        #graph a:hover polygon { stroke-width: 2.5; }\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: 600px;\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 {\n            margin-top: 0;\n        }\n        .legend-item {\n            margin: 8px 0;\n        }\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    `;\n}\n\nfunction generateHTMLLegend(): string {\n    return `<div class=\"legend\">\n        <h2>Legend — fill = framework (libType), border = role</h2>\n        <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: #E8F5E9;\"></span>\n            <strong>express:</strong> Express / server side\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"background: #F5F5F5;\"></span>\n            <strong>all:</strong> Library usable by any side\n        </div>\n        <div class=\"legend-item\" style=\"margin-top: 12px;\">\n            <span class=\"legend-box\" style=\"border: 3px double #333;\"></span>\n            <strong>server:</strong> runnable server app (double border)\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"border: 1px dashed #333;\"></span>\n            <strong>client:</strong> client app, e.g. angular (dashed 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 @ApiImplementation 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\" style=\"margin-top: 15px;\">\n            <em>Each node label shows its dependency level (L#) and framework-role (e.g. express-server, all-lib). Rows are laid out by level (top = no dependencies). Transitive dependencies are allowed but not shown.</em>\n        </div>\n    </div>`;\n}\n\nfunction generateHTMLScript(dot: string): string {\n    return `\n        const dot = ${JSON.stringify(dot)};\n        const viz = new Viz();\n\n        viz.renderSVGElement(dot)\n            .then(element => {\n                document.getElementById('graph').appendChild(element);\n            })\n            .catch(err => {\n                console.error(err);\n                document.getElementById('graph').innerHTML = '<pre>' + err + '</pre>';\n            });\n    `;\n}\n\ninterface VisualizationPaths {\n    htmlPath: string;\n}\n\n/**\n * Write the committed architecture visualization to architecture/dependencies.html,\n * 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), so no separate .dot file is committed — same as design.html. Output\n * is deterministic (sorted graph in → same bytes out) so git only shows a diff\n * when the architecture actually changed.\n */\nexport function 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    // Ensure directory exists\n    if (!fs.existsSync(outputDir)) {\n        fs.mkdirSync(outputDir, { recursive: true });\n    }\n\n    const html = generateHTML(generateDot(graph, title), title);\n    const htmlPath = path.join(outputDir, 'dependencies.html');\n    fs.writeFileSync(htmlPath, html, 'utf-8');\n\n    return { htmlPath };\n}\n\n/**\n * Open the HTML visualization in the default browser\n */\nexport function 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        void err;\n        return false;\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 * Output files go to tmp/webpieces/ for easy viewing without committing.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { execSync } from 'child_process';\nimport type { EnhancedGraph, GraphEntry } from './graph-sorter';\nimport { toError } from '../toError';\n\n/**\n * Framework (libType) colors for visualization — nodes are colored by which\n * client side they target so it is obvious at a glance which projects are\n * Angular, which are Express, and which libraries are shared (\"all\").\n */\nconst FRAMEWORK_COLORS: Record<string, string> = {\n    angular: '#FCE4EC', // pink   - Angular front-end\n    react: '#E3F2FD', // blue   - React front-end\n    express: '#E8F5E9', // green  - Express / server side\n    all: '#F5F5F5', // grey   - library usable by any side\n};\n\nconst DEFAULT_FRAMEWORK_COLOR = '#FFF3E0'; // orange - unknown/other libType\n\n/**\n * Role border styling — fill stays keyed on framework; the border shape shows a\n * project's ROLE at a glance:\n *   server       → double border (a runnable server app)\n *   client       → dashed border (a client app, e.g. angular)\n *   designed-lib → bold border   (a library with a generated @ApiImplementation design)\n *   lib / other  → plain thin border\n */\nfunction roleBorderAttrs(role: string): string {\n    if (role === 'server') return ', peripheries=2';\n    if (role === 'client') return ', style=\"filled,dashed\"';\n    if (role === 'designed-lib') return ', penwidth=2';\n    return '';\n}\n\n/**\n * Server and client apps are graph ROOTS — nothing depends on them and they\n * never depend on one another. So instead of scattering them across rows by\n * dependency depth (a server whose deepest dep is L3 vs one at L5), we pin every\n * server/client to a single top row above the whole library stack. This\n * declutters the diagram: the top row reads as \"all the runnable apps,\" and\n * everything below is the shared libraries. Their outgoing edges still point\n * down into the libs, so no dependency is violated.\n */\nfunction isPromotedRole(role: string): boolean {\n    return role === 'server' || role === 'client';\n}\n\n/**\n * Remove scope from name for display\n * '@scope/name' → 'name'\n * 'name' → 'name'\n */\nfunction getShortName(name: string): string {\n    return name.includes('/') ? name.split('/').pop()! : name;\n}\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\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 has\n * no generated DI design (no design.json → no clickable design page).\n *\n * designFile is repo-relative posix (e.g. 'packages/http/http-api/design.json');\n * we swap the extension and re-root it at architecture/ so the browser resolves\n * '../packages/http/http-api/design.html' from the checkout.\n */\nfunction 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 */\nexport function 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 row rank. Libs sit on their computed topological level;\n    // servers/clients are all promoted to one synthetic top rank (maxLevel + 1)\n    // so they share a single row strictly above every library.\n    const maxLevel = Math.max(0, ...Object.values(graph).map((info: GraphEntry) => info.level));\n    const topRank = maxLevel + 1;\n    const rankOf = (info: GraphEntry): number =>\n        isPromotedRole(info.role ?? 'lib') ? topRank : info.level;\n\n    const levels: Record<number, string[]> = {};\n    for (const [project, info] of Object.entries(graph)) {\n        const rank = rankOf(info);\n        if (!levels[rank]) levels[rank] = [];\n        levels[rank].push(project);\n    }\n\n    // Nodes: fill colored by framework (libType), border shaped by role; the\n    // label shows the framework-role combo (e.g. express-server, all-lib).\n    // A node with a generated DI design gets a URL so the rendered SVG box is\n    // clickable — it opens that project's committed design.html in a new tab.\n    for (const [project, info] of Object.entries(graph)) {\n        const shortName = getShortName(project);\n        const framework = info.framework ?? 'all';\n        const role = info.role ?? 'lib';\n        const color = FRAMEWORK_COLORS[framework] ?? DEFAULT_FRAMEWORK_COLOR;\n        const border = roleBorderAttrs(role);\n        const href = designHtmlHref(info.designFile);\n        const link = href ? `, URL=\"${href}\", target=\"_blank\"` : '';\n        // Promoted apps (server/client) drop the L# — they no longer sit on their\n        // dependency level, so a level number in the label would be misleading.\n        const labelMeta = isPromotedRole(role) ? `${framework}-${role}` : `L${info.level} · ${framework}-${role}`;\n        dot += `  \"${shortName}\" [fillcolor=\"${color}\"${border}${link}, label=\"${shortName}\\\\n(${labelMeta})\"];\\n`;\n    }\n\n    dot += '\\n';\n\n    // Create same-rank subgraphs for each level\n    for (const [level, projects] of Object.entries(levels)) {\n        dot += `  { rank=same; `;\n        projects.forEach((p) => {\n            const shortName = getShortName(p);\n            dot += `\"${shortName}\"; `;\n        });\n        dot += '}\\n';\n    }\n\n    dot += '\\n';\n\n    // Create edges (dependencies)\n    for (const [project, info] of Object.entries(graph)) {\n        const shortName = getShortName(project);\n        for (const dep of info.dependsOn || []) {\n            const depShortName = getShortName(dep);\n            dot += `  \"${shortName}\" -> \"${depShortName}\";\\n`;\n        }\n    }\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/**\n * Generate interactive HTML with embedded SVG using viz.js\n */\nexport function generateHTML(dot: string, title: string = 'Monorepo Dependency Architecture'): string {\n    const styles = generateHTMLStyles();\n    const legend = generateHTMLLegend();\n    const script = generateHTMLScript(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    ${legend}\n    <div id=\"graph\"></div>\n    <script>${script}</script>\n</body>\n</html>`;\n}\n\nfunction generateHTMLStyles(): string {\n    return `\n        body {\n            margin: 0;\n            padding: 20px;\n            font-family: Arial, sans-serif;\n            background: #f5f5f5;\n        }\n        h1 {\n            text-align: center;\n            color: #333;\n        }\n        .hint {\n            text-align: center;\n            color: #555;\n            margin: 0 0 16px;\n        }\n        /* viz.js renders node URLs as <a> — show they are clickable. */\n        #graph a { cursor: pointer; }\n        #graph a:hover polygon { stroke-width: 2.5; }\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: 600px;\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 {\n            margin-top: 0;\n        }\n        .legend-item {\n            margin: 8px 0;\n        }\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    `;\n}\n\nfunction generateHTMLLegend(): string {\n    return `<div class=\"legend\">\n        <h2>Legend — fill = framework (libType), border = role</h2>\n        <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: #E8F5E9;\"></span>\n            <strong>express:</strong> Express / server side\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"background: #F5F5F5;\"></span>\n            <strong>all:</strong> Library usable by any side\n        </div>\n        <div class=\"legend-item\" style=\"margin-top: 12px;\">\n            <span class=\"legend-box\" style=\"border: 3px double #333;\"></span>\n            <strong>server:</strong> runnable server app (double border)\n        </div>\n        <div class=\"legend-item\">\n            <span class=\"legend-box\" style=\"border: 1px dashed #333;\"></span>\n            <strong>client:</strong> client app, e.g. angular (dashed 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 @ApiImplementation 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\" style=\"margin-top: 15px;\">\n            <em>Library nodes show their dependency level (L#) and framework-role (e.g. all-lib) and are laid out by level, with the deepest libraries at the bottom. Server and client apps are roots (nothing depends on them), so they are all pinned to the single top row regardless of dependency depth — their labels omit the L#. Transitive dependencies are allowed but not shown.</em>\n        </div>\n    </div>`;\n}\n\nfunction generateHTMLScript(dot: string): string {\n    return `\n        const dot = ${JSON.stringify(dot)};\n        const viz = new Viz();\n\n        viz.renderSVGElement(dot)\n            .then(element => {\n                document.getElementById('graph').appendChild(element);\n            })\n            .catch(err => {\n                console.error(err);\n                document.getElementById('graph').innerHTML = '<pre>' + err + '</pre>';\n            });\n    `;\n}\n\ninterface VisualizationPaths {\n    htmlPath: string;\n}\n\n/**\n * Write the committed architecture visualization to architecture/dependencies.html,\n * 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), so no separate .dot file is committed — same as design.html. Output\n * is deterministic (sorted graph in → same bytes out) so git only shows a diff\n * when the architecture actually changed.\n */\nexport function 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    // Ensure directory exists\n    if (!fs.existsSync(outputDir)) {\n        fs.mkdirSync(outputDir, { recursive: true });\n    }\n\n    const html = generateHTML(generateDot(graph, title), title);\n    const htmlPath = path.join(outputDir, 'dependencies.html');\n    fs.writeFileSync(htmlPath, html, 'utf-8');\n\n    return { htmlPath };\n}\n\n/**\n * Open the HTML visualization in the default browser\n */\nexport function 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        void err;\n        return false;\n    }\n}\n"]}