@webpieces/nx-webpieces-rules 0.3.263 → 0.3.271

package/src/lib/graph-metadata.js

@@ -27,6 +27,7 @@ const project_info_1 = require("./project-info");
 const framework_resolver_1 = require("./framework-resolver");
 const role_resolver_1 = require("./role-resolver");
 const responsibilities_1 = require("./responsibilities");
+const toError_1 = require("../toError");
 exports.RESPONSIBILITIES_FILE_NAME = 'responsibilities.md';
 /**
  * Thrown when one or more projects fail metadata validation (missing/invalid
@@ -82,8 +83,12 @@ function enrichGraph(graph, infos, workspaceRoot) {
             entry.role = roleResolution.role;
         }
         enrichResponsibilities(entry, info, workspaceRoot, problems);
-        // Only project.json projects get a generated design.json (see di-graph-targets.ts)
-        if (fs.existsSync(path.join(workspaceRoot, info.root, 'project.json'))) {
+        // Set designFile ONLY when the project has a REAL generated design (a
+        // non-empty `designs[]`), i.e. it has a @DocumentDesign root. Every
+        // project.json project gets a design.json written, but plain libs get an
+        // empty `{ designs: [] }` — those must NOT become clickable in the arch
+        // viz (designHtmlHref keys off designFile). See graph-visualizer.ts.
+        if (hasGeneratedDesign(workspaceRoot, info.root)) {
             entry.designFile = toRepoRelative(info.root, 'design.json');
         }
     }
@@ -205,4 +210,26 @@ function enrichResponsibilities(entry, info, workspaceRoot, problems) {
 function toRepoRelative(projectRoot, fileName) {
     return [projectRoot.replace(/\\/g, '/').replace(/\/+$/, ''), fileName].join('/');
 }
+/**
+ * True when the project has a REAL generated DI design — a committed design.json
+ * whose `designs[]` is non-empty (i.e. it has ≥1 @DocumentDesign root). Plain
+ * libs get a `{ designs: [] }` file written, which must read as "no design" so
+ * the arch viz does not render them as clickable. A missing/unparseable file is
+ * treated as "no design".
+ */
+function hasGeneratedDesign(workspaceRoot, projectRoot) {
+    const designPath = path.join(workspaceRoot, projectRoot, 'design.json');
+    if (!fs.existsSync(designPath))
+        return false;
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        const parsed = JSON.parse(fs.readFileSync(designPath, 'utf-8'));
+        return Array.isArray(parsed.designs) && parsed.designs.length > 0;
+    }
+    catch (err) {
+        const error = (0, toError_1.toError)(err);
+        console.warn(`⚠️  Skipping unparseable ${designPath}: ${error.message}`);
+        return false;
+    }
+}
 //# sourceMappingURL=graph-metadata.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"graph-metadata.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-metadata.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Graph Metadata Enrichment\n *\n * Fills the AI-oriented fields on each architecture/dependencies.json entry:\n *   framework            — from `framework:<x>` nx tag or package.json inference\n *   shortDescription     — first paragraph of the project's responsibilities.md\n *   responsibilitiesFile — repo-relative path to the required responsibilities.md\n *   designFile           — repo-relative path to the generated DI design.json\n *\n * Validation is aggregated: ALL problems across ALL projects are collected and\n * thrown as one MetadataValidationError so a repo adopting this sees the full\n * seeding list in a single run. Callers must enrich BEFORE writing any file so\n * a failed run never clobbers dependencies.json.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { createProjectGraphAsync } from '@nx/devkit';\nimport type { EnhancedGraph } from './graph-sorter';\nimport { ProjectInfo } from './project-info';\nimport { resolveFramework } from './framework-resolver';\nimport { resolveRole } from './role-resolver';\nimport { extractShortDescription, validateShortDescription } from './responsibilities';\n\nexport const RESPONSIBILITIES_FILE_NAME = 'responsibilities.md';\n\n/**\n * Thrown when one or more projects fail metadata validation (missing/invalid\n * responsibilities.md, bad framework tags, ...). Executors catch this to point\n * AI at the webpieces.responsibilities.md instructions template.\n */\nexport class MetadataValidationError extends Error {\n    constructor(public readonly problems: string[]) {\n        super(\n            `Architecture metadata validation failed (${problems.length} problem(s)):\\n` +\n                problems.map((problem: string) => `  - ${problem}`).join('\\n')\n        );\n        this.name = 'MetadataValidationError';\n    }\n}\n\n/**\n * Read per-project root + tags from nx's project graph.\n */\nexport async function collectProjectInfo(): Promise<Map<string, ProjectInfo>> {\n    const projectGraph = await createProjectGraphAsync();\n    const infos = new Map<string, ProjectInfo>();\n    for (const [name, node] of Object.entries(projectGraph.nodes)) {\n        infos.set(name, new ProjectInfo(name, node.data.root, node.data.tags ?? []));\n    }\n    return infos;\n}\n\n/**\n * Enrich every graph entry in place with framework, shortDescription,\n * responsibilitiesFile and designFile. Throws MetadataValidationError listing\n * every problem when any project fails validation.\n */\nexport function enrichGraph(\n    graph: EnhancedGraph,\n    infos: Map<string, ProjectInfo>,\n    workspaceRoot: string\n): void {\n    const problems: string[] = [];\n\n    for (const [projectName, entry] of Object.entries(graph)) {\n        const info = infos.get(projectName);\n        if (!info) {\n            problems.push(`${projectName}: not found in nx project graph`);\n            continue;\n        }\n\n        const resolution = resolveFramework(info, workspaceRoot);\n        if (resolution.problem !== null) {\n            problems.push(resolution.problem);\n        } else if (resolution.frameworks !== null) {\n            entry.framework = resolution.frameworks;\n        }\n\n        const roleResolution = resolveRole(info);\n        if (roleResolution.problem !== null) {\n            problems.push(roleResolution.problem);\n        } else if (roleResolution.role !== null) {\n            entry.role = roleResolution.role;\n        }\n\n        enrichResponsibilities(entry, info, workspaceRoot, problems);\n\n        // Only project.json projects get a generated design.json (see di-graph-targets.ts)\n        if (fs.existsSync(path.join(workspaceRoot, info.root, 'project.json'))) {\n            entry.designFile = toRepoRelative(info.root, 'design.json');\n        }\n    }\n\n    validateLibraryTypesMatch(graph, problems);\n    validateRoleDependencies(graph, problems);\n\n    if (problems.length > 0) {\n        throw new MetadataValidationError(problems);\n    }\n}\n\n/**\n * Roles that are terminal APPS — nothing may depend on them. A server or a\n * client is a top-level runnable; being depended upon means it is really a\n * library and should be retagged `role:lib`/`role:designed-lib`.\n */\nexport const APP_ROLES: ReadonlyArray<string> = ['server', 'client'];\n\n/**\n * Compatibility lattice — the \"up-set\" of each atomic env is the env itself\n * PLUS every ancestor it can legally consume code from (specialization edges\n * child → parent: react → browser, angular → browser, express → node). A\n * consumer promising env `c` can be satisfied by any dependency env in `up(c)`.\n */\nexport const ENV_UP_SETS: Readonly<Record<string, ReadonlyArray<string>>> = {\n    react: ['react', 'browser'],\n    angular: ['angular', 'browser'],\n    browser: ['browser'],\n    express: ['express', 'node'],\n    node: ['node'],\n};\n\n/** The up-set of an env (env itself + ancestors); unknown envs map to just themselves. */\nfunction upSet(env: string): ReadonlyArray<string> {\n    return ENV_UP_SETS[env] ?? [env];\n}\n\n/**\n * `library-types-match-client` rule.\n *\n * A project's `framework` field is its libType — the SET of runtime\n * environments it is validated to run in (browser | react | angular | node |\n * express). For a dependency edge Consumer C → Library L, the edge is LEGAL iff\n * for EVERY env `c` in C's set, up(c) ∩ L's set ≠ ∅ — i.e. every environment\n * the consumer promises to run in can be satisfied by the dependency. This keeps\n * an express app from depending on a browser-only lib, and lets a `browser+node`\n * lib be consumed by both react and express projects. Every violation is\n * appended to `problems` so `arch:generate` fails with the full list.\n */\nexport function validateLibraryTypesMatch(graph: EnhancedGraph, problems: string[]): void {\n    for (const [projectName, entry] of Object.entries(graph)) {\n        const fromSet = entry.framework;\n        if (fromSet === undefined) continue; // framework resolution already flagged this project\n\n        for (const dep of entry.dependsOn) {\n            const depEntry = graph[dep];\n            const toSet = depEntry?.framework;\n            if (toSet === undefined) continue;\n\n            const unsatisfied = fromSet.filter(\n                (env: string) => !upSet(env).some((up: string) => toSet.includes(up))\n            );\n            if (unsatisfied.length === 0) continue;\n\n            problems.push(\n                `library-types-match-client: '${projectName}' [${fromSet.join(', ')}] must not depend on ` +\n                    `'${dep}' [${toSet.join(', ')}] — the consumer env(s) ${unsatisfied.join(', ')} cannot be ` +\n                    `satisfied by the dependency (each consumer env must resolve to itself or an ancestor it ` +\n                    `consumes from: react/angular→browser, express→node). Widen '${dep}' framework tags or ` +\n                    `remove the dependency.`\n            );\n        }\n    }\n}\n\n/**\n * `role-dependency` rule.\n *\n * A project's `role` is its function (server | designed-lib | lib | client).\n * Apps are terminal — libraries and clients consume them, never the reverse:\n *   - a `client` is fully terminal: NOTHING may depend on it.\n *   - a `server` may only be depended upon by another `server` — the one\n *     legitimate case is a server-side orchestrator/e2e harness that boots\n *     other servers. A `lib`/`designed-lib`/`client` depending on a `server`\n *     inverts the dependency direction and is a violation.\n */\nexport function validateRoleDependencies(graph: EnhancedGraph, problems: string[]): void {\n    for (const [projectName, entry] of Object.entries(graph)) {\n        const fromRole = entry.role;\n        for (const dep of entry.dependsOn) {\n            const toRole = graph[dep]?.role;\n            if (toRole === undefined) continue; // role resolution already flagged this project\n            if (!APP_ROLES.includes(toRole)) continue;\n            // A server may orchestrate/boot other servers (e.g. an e2e harness).\n            if (toRole === 'server' && fromRole === 'server') continue;\n\n            const why =\n                toRole === 'client'\n                    ? `a 'client' app is terminal and may never be depended upon`\n                    : `a 'server' may only be depended upon by another 'server' (an orchestrator/e2e harness)`;\n            problems.push(\n                `role-dependency: '${projectName}' (role:${fromRole ?? 'none'}) must not depend on ` +\n                    `'${dep}' (role:${toRole}) — ${why}. Retag '${dep}' role:lib/role:designed-lib if it ` +\n                    `is actually a library, or remove the dependency.`\n            );\n        }\n    }\n}\n\nfunction enrichResponsibilities(\n    entry: EnhancedGraph[string],\n    info: ProjectInfo,\n    workspaceRoot: string,\n    problems: string[]\n): void {\n    const responsibilitiesFile = toRepoRelative(info.root, RESPONSIBILITIES_FILE_NAME);\n    entry.responsibilitiesFile = responsibilitiesFile;\n\n    const absolutePath = path.join(workspaceRoot, info.root, RESPONSIBILITIES_FILE_NAME);\n    if (!fs.existsSync(absolutePath)) {\n        problems.push(\n            `${info.name}: missing required ${responsibilitiesFile} — create it with a heading, ` +\n                `one short summary paragraph, then the full responsibilities of the module`\n        );\n        return;\n    }\n\n    const summary = extractShortDescription(fs.readFileSync(absolutePath, 'utf-8'));\n    const summaryProblem = validateShortDescription(summary, responsibilitiesFile);\n    if (summaryProblem !== null) {\n        problems.push(`${info.name}: ${summaryProblem}`);\n        return;\n    }\n    entry.shortDescription = summary;\n}\n\n/**\n * Repo-relative path with forward slashes (stable across platforms in the\n * committed JSON).\n */\nfunction toRepoRelative(projectRoot: string, fileName: string): string {\n    return [projectRoot.replace(/\\\\/g, '/').replace(/\\/+$/, ''), fileName].join('/');\n}\n"]}
+{"version":3,"file":"graph-metadata.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-metadata.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAgCH,gDAOC;AAOD,kCA8CC;AAwCD,8DAwBC;AAaD,4DAqBC;;AA5LD,+CAAyB;AACzB,mDAA6B;AAC7B,uCAAqD;AAErD,iDAA6C;AAC7C,6DAAwD;AACxD,mDAA8C;AAC9C,yDAAuF;AACvF,wCAAqC;AAExB,QAAA,0BAA0B,GAAG,qBAAqB,CAAC;AAEhE;;;;GAIG;AACH,MAAa,uBAAwB,SAAQ,KAAK;IAClB;IAA5B,YAA4B,QAAkB;QAC1C,KAAK,CACD,4CAA4C,QAAQ,CAAC,MAAM,iBAAiB;YACxE,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CACrE,CAAC;QAJsB,aAAQ,GAAR,QAAQ,CAAU;QAK1C,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IAC1C,CAAC;CACJ;AARD,0DAQC;AAED;;GAEG;AACI,KAAK,UAAU,kBAAkB;IACpC,MAAM,YAAY,GAAG,MAAM,IAAA,gCAAuB,GAAE,CAAC;IACrD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC7C,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5D,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,0BAAW,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,SAAgB,WAAW,CACvB,KAAoB,EACpB,KAA+B,EAC/B,aAAqB;IAErB,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,KAAK,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,EAAE,CAAC;YACR,QAAQ,CAAC,IAAI,CAAC,GAAG,WAAW,iCAAiC,CAAC,CAAC;YAC/D,SAAS;QACb,CAAC;QAED,MAAM,UAAU,GAAG,IAAA,qCAAgB,EAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QACzD,IAAI,UAAU,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YAC9B,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACtC,CAAC;aAAM,IAAI,UAAU,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;YACxC,KAAK,CAAC,SAAS,GAAG,UAAU,CAAC,UAAU,CAAC;QAC5C,CAAC;QAED,MAAM,cAAc,GAAG,IAAA,2BAAW,EAAC,IAAI,CAAC,CAAC;QACzC,IAAI,cAAc,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YAClC,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;aAAM,IAAI,cAAc,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YACtC,KAAK,CAAC,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC;QACrC,CAAC;QAED,sBAAsB,CAAC,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC;QAE7D,sEAAsE;QACtE,oEAAoE;QACpE,yEAAyE;QACzE,wEAAwE;QACxE,qEAAqE;QACrE,IAAI,kBAAkB,CAAC,aAAa,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/C,KAAK,CAAC,UAAU,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QAChE,CAAC;IACL,CAAC;IAED,yBAAyB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC3C,wBAAwB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAE1C,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IAChD,CAAC;AACL,CAAC;AAED;;;;GAIG;AACU,QAAA,SAAS,GAA0B,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAErE;;;;;GAKG;AACU,QAAA,WAAW,GAAoD;IACxE,KAAK,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC;IAC3B,OAAO,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC;IAC/B,OAAO,EAAE,CAAC,SAAS,CAAC;IACpB,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,CAAC;IAC5B,IAAI,EAAE,CAAC,MAAM,CAAC;CACjB,CAAC;AAEF,0FAA0F;AAC1F,SAAS,KAAK,CAAC,GAAW;IACtB,OAAO,mBAAW,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,yBAAyB,CAAC,KAAoB,EAAE,QAAkB;IAC9E,KAAK,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvD,MAAM,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC;QAChC,IAAI,OAAO,KAAK,SAAS;YAAE,SAAS,CAAC,oDAAoD;QAEzF,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;YAChC,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;YAC5B,MAAM,KAAK,GAAG,QAAQ,EAAE,SAAS,CAAC;YAClC,IAAI,KAAK,KAAK,SAAS;gBAAE,SAAS;YAElC,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAC9B,CAAC,GAAW,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,EAAU,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CACxE,CAAC;YACF,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YAEvC,QAAQ,CAAC,IAAI,CACT,gCAAgC,WAAW,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,uBAAuB;gBACtF,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,2BAA2B,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa;gBAC3F,0FAA0F;gBAC1F,+DAA+D,GAAG,sBAAsB;gBACxF,wBAAwB,CAC/B,CAAC;QACN,CAAC;IACL,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,wBAAwB,CAAC,KAAoB,EAAE,QAAkB;IAC7E,KAAK,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvD,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC;QAC5B,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;YAChC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;YAChC,IAAI,MAAM,KAAK,SAAS;gBAAE,SAAS,CAAC,+CAA+C;YACnF,IAAI,CAAC,iBAAS,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAAE,SAAS;YAC1C,qEAAqE;YACrE,IAAI,MAAM,KAAK,QAAQ,IAAI,QAAQ,KAAK,QAAQ;gBAAE,SAAS;YAE3D,MAAM,GAAG,GACL,MAAM,KAAK,QAAQ;gBACf,CAAC,CAAC,2DAA2D;gBAC7D,CAAC,CAAC,wFAAwF,CAAC;YACnG,QAAQ,CAAC,IAAI,CACT,qBAAqB,WAAW,WAAW,QAAQ,IAAI,MAAM,uBAAuB;gBAChF,IAAI,GAAG,WAAW,MAAM,OAAO,GAAG,YAAY,GAAG,qCAAqC;gBACtF,kDAAkD,CACzD,CAAC;QACN,CAAC;IACL,CAAC;AACL,CAAC;AAED,SAAS,sBAAsB,CAC3B,KAA4B,EAC5B,IAAiB,EACjB,aAAqB,EACrB,QAAkB;IAElB,MAAM,oBAAoB,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,kCAA0B,CAAC,CAAC;IACnF,KAAK,CAAC,oBAAoB,GAAG,oBAAoB,CAAC;IAElD,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,IAAI,EAAE,kCAA0B,CAAC,CAAC;IACrF,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC/B,QAAQ,CAAC,IAAI,CACT,GAAG,IAAI,CAAC,IAAI,sBAAsB,oBAAoB,+BAA+B;YACjF,2EAA2E,CAClF,CAAC;QACF,OAAO;IACX,CAAC;IAED,MAAM,OAAO,GAAG,IAAA,0CAAuB,EAAC,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC;IAChF,MAAM,cAAc,GAAG,IAAA,2CAAwB,EAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;IAC/E,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;QAC1B,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC,CAAC;QACjD,OAAO;IACX,CAAC;IACD,KAAK,CAAC,gBAAgB,GAAG,OAAO,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,SAAS,cAAc,CAAC,WAAmB,EAAE,QAAgB;IACzD,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;GAMG;AACH,SAAS,kBAAkB,CAAC,aAAqB,EAAE,WAAmB;IAClE,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;IACxE,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7C,8DAA8D;IAC9D,IAAI,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;QAChE,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IACtE,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,IAAI,CAAC,4BAA4B,UAAU,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACzE,OAAO,KAAK,CAAC;IACjB,CAAC;AACL,CAAC","sourcesContent":["/**\n * Graph Metadata Enrichment\n *\n * Fills the AI-oriented fields on each architecture/dependencies.json entry:\n *   framework            — from `framework:<x>` nx tag or package.json inference\n *   shortDescription     — first paragraph of the project's responsibilities.md\n *   responsibilitiesFile — repo-relative path to the required responsibilities.md\n *   designFile           — repo-relative path to the generated DI design.json\n *\n * Validation is aggregated: ALL problems across ALL projects are collected and\n * thrown as one MetadataValidationError so a repo adopting this sees the full\n * seeding list in a single run. Callers must enrich BEFORE writing any file so\n * a failed run never clobbers dependencies.json.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { createProjectGraphAsync } from '@nx/devkit';\nimport type { EnhancedGraph } from './graph-sorter';\nimport { ProjectInfo } from './project-info';\nimport { resolveFramework } from './framework-resolver';\nimport { resolveRole } from './role-resolver';\nimport { extractShortDescription, validateShortDescription } from './responsibilities';\nimport { toError } from '../toError';\n\nexport const RESPONSIBILITIES_FILE_NAME = 'responsibilities.md';\n\n/**\n * Thrown when one or more projects fail metadata validation (missing/invalid\n * responsibilities.md, bad framework tags, ...). Executors catch this to point\n * AI at the webpieces.responsibilities.md instructions template.\n */\nexport class MetadataValidationError extends Error {\n    constructor(public readonly problems: string[]) {\n        super(\n            `Architecture metadata validation failed (${problems.length} problem(s)):\\n` +\n                problems.map((problem: string) => `  - ${problem}`).join('\\n')\n        );\n        this.name = 'MetadataValidationError';\n    }\n}\n\n/**\n * Read per-project root + tags from nx's project graph.\n */\nexport async function collectProjectInfo(): Promise<Map<string, ProjectInfo>> {\n    const projectGraph = await createProjectGraphAsync();\n    const infos = new Map<string, ProjectInfo>();\n    for (const [name, node] of Object.entries(projectGraph.nodes)) {\n        infos.set(name, new ProjectInfo(name, node.data.root, node.data.tags ?? []));\n    }\n    return infos;\n}\n\n/**\n * Enrich every graph entry in place with framework, shortDescription,\n * responsibilitiesFile and designFile. Throws MetadataValidationError listing\n * every problem when any project fails validation.\n */\nexport function enrichGraph(\n    graph: EnhancedGraph,\n    infos: Map<string, ProjectInfo>,\n    workspaceRoot: string\n): void {\n    const problems: string[] = [];\n\n    for (const [projectName, entry] of Object.entries(graph)) {\n        const info = infos.get(projectName);\n        if (!info) {\n            problems.push(`${projectName}: not found in nx project graph`);\n            continue;\n        }\n\n        const resolution = resolveFramework(info, workspaceRoot);\n        if (resolution.problem !== null) {\n            problems.push(resolution.problem);\n        } else if (resolution.frameworks !== null) {\n            entry.framework = resolution.frameworks;\n        }\n\n        const roleResolution = resolveRole(info);\n        if (roleResolution.problem !== null) {\n            problems.push(roleResolution.problem);\n        } else if (roleResolution.role !== null) {\n            entry.role = roleResolution.role;\n        }\n\n        enrichResponsibilities(entry, info, workspaceRoot, problems);\n\n        // Set designFile ONLY when the project has a REAL generated design (a\n        // non-empty `designs[]`), i.e. it has a @DocumentDesign root. Every\n        // project.json project gets a design.json written, but plain libs get an\n        // empty `{ designs: [] }` — those must NOT become clickable in the arch\n        // viz (designHtmlHref keys off designFile). See graph-visualizer.ts.\n        if (hasGeneratedDesign(workspaceRoot, info.root)) {\n            entry.designFile = toRepoRelative(info.root, 'design.json');\n        }\n    }\n\n    validateLibraryTypesMatch(graph, problems);\n    validateRoleDependencies(graph, problems);\n\n    if (problems.length > 0) {\n        throw new MetadataValidationError(problems);\n    }\n}\n\n/**\n * Roles that are terminal APPS — nothing may depend on them. A server or a\n * client is a top-level runnable; being depended upon means it is really a\n * library and should be retagged `role:lib`/`role:designed-lib`.\n */\nexport const APP_ROLES: ReadonlyArray<string> = ['server', 'client'];\n\n/**\n * Compatibility lattice — the \"up-set\" of each atomic env is the env itself\n * PLUS every ancestor it can legally consume code from (specialization edges\n * child → parent: react → browser, angular → browser, express → node). A\n * consumer promising env `c` can be satisfied by any dependency env in `up(c)`.\n */\nexport const ENV_UP_SETS: Readonly<Record<string, ReadonlyArray<string>>> = {\n    react: ['react', 'browser'],\n    angular: ['angular', 'browser'],\n    browser: ['browser'],\n    express: ['express', 'node'],\n    node: ['node'],\n};\n\n/** The up-set of an env (env itself + ancestors); unknown envs map to just themselves. */\nfunction upSet(env: string): ReadonlyArray<string> {\n    return ENV_UP_SETS[env] ?? [env];\n}\n\n/**\n * `library-types-match-client` rule.\n *\n * A project's `framework` field is its libType — the SET of runtime\n * environments it is validated to run in (browser | react | angular | node |\n * express). For a dependency edge Consumer C → Library L, the edge is LEGAL iff\n * for EVERY env `c` in C's set, up(c) ∩ L's set ≠ ∅ — i.e. every environment\n * the consumer promises to run in can be satisfied by the dependency. This keeps\n * an express app from depending on a browser-only lib, and lets a `browser+node`\n * lib be consumed by both react and express projects. Every violation is\n * appended to `problems` so `arch:generate` fails with the full list.\n */\nexport function validateLibraryTypesMatch(graph: EnhancedGraph, problems: string[]): void {\n    for (const [projectName, entry] of Object.entries(graph)) {\n        const fromSet = entry.framework;\n        if (fromSet === undefined) continue; // framework resolution already flagged this project\n\n        for (const dep of entry.dependsOn) {\n            const depEntry = graph[dep];\n            const toSet = depEntry?.framework;\n            if (toSet === undefined) continue;\n\n            const unsatisfied = fromSet.filter(\n                (env: string) => !upSet(env).some((up: string) => toSet.includes(up))\n            );\n            if (unsatisfied.length === 0) continue;\n\n            problems.push(\n                `library-types-match-client: '${projectName}' [${fromSet.join(', ')}] must not depend on ` +\n                    `'${dep}' [${toSet.join(', ')}] — the consumer env(s) ${unsatisfied.join(', ')} cannot be ` +\n                    `satisfied by the dependency (each consumer env must resolve to itself or an ancestor it ` +\n                    `consumes from: react/angular→browser, express→node). Widen '${dep}' framework tags or ` +\n                    `remove the dependency.`\n            );\n        }\n    }\n}\n\n/**\n * `role-dependency` rule.\n *\n * A project's `role` is its function (server | designed-lib | lib | client).\n * Apps are terminal — libraries and clients consume them, never the reverse:\n *   - a `client` is fully terminal: NOTHING may depend on it.\n *   - a `server` may only be depended upon by another `server` — the one\n *     legitimate case is a server-side orchestrator/e2e harness that boots\n *     other servers. A `lib`/`designed-lib`/`client` depending on a `server`\n *     inverts the dependency direction and is a violation.\n */\nexport function validateRoleDependencies(graph: EnhancedGraph, problems: string[]): void {\n    for (const [projectName, entry] of Object.entries(graph)) {\n        const fromRole = entry.role;\n        for (const dep of entry.dependsOn) {\n            const toRole = graph[dep]?.role;\n            if (toRole === undefined) continue; // role resolution already flagged this project\n            if (!APP_ROLES.includes(toRole)) continue;\n            // A server may orchestrate/boot other servers (e.g. an e2e harness).\n            if (toRole === 'server' && fromRole === 'server') continue;\n\n            const why =\n                toRole === 'client'\n                    ? `a 'client' app is terminal and may never be depended upon`\n                    : `a 'server' may only be depended upon by another 'server' (an orchestrator/e2e harness)`;\n            problems.push(\n                `role-dependency: '${projectName}' (role:${fromRole ?? 'none'}) must not depend on ` +\n                    `'${dep}' (role:${toRole}) — ${why}. Retag '${dep}' role:lib/role:designed-lib if it ` +\n                    `is actually a library, or remove the dependency.`\n            );\n        }\n    }\n}\n\nfunction enrichResponsibilities(\n    entry: EnhancedGraph[string],\n    info: ProjectInfo,\n    workspaceRoot: string,\n    problems: string[]\n): void {\n    const responsibilitiesFile = toRepoRelative(info.root, RESPONSIBILITIES_FILE_NAME);\n    entry.responsibilitiesFile = responsibilitiesFile;\n\n    const absolutePath = path.join(workspaceRoot, info.root, RESPONSIBILITIES_FILE_NAME);\n    if (!fs.existsSync(absolutePath)) {\n        problems.push(\n            `${info.name}: missing required ${responsibilitiesFile} — create it with a heading, ` +\n                `one short summary paragraph, then the full responsibilities of the module`\n        );\n        return;\n    }\n\n    const summary = extractShortDescription(fs.readFileSync(absolutePath, 'utf-8'));\n    const summaryProblem = validateShortDescription(summary, responsibilitiesFile);\n    if (summaryProblem !== null) {\n        problems.push(`${info.name}: ${summaryProblem}`);\n        return;\n    }\n    entry.shortDescription = summary;\n}\n\n/**\n * Repo-relative path with forward slashes (stable across platforms in the\n * committed JSON).\n */\nfunction toRepoRelative(projectRoot: string, fileName: string): string {\n    return [projectRoot.replace(/\\\\/g, '/').replace(/\\/+$/, ''), fileName].join('/');\n}\n\n/**\n * True when the project has a REAL generated DI design — a committed design.json\n * whose `designs[]` is non-empty (i.e. it has ≥1 @DocumentDesign root). Plain\n * libs get a `{ designs: [] }` file written, which must read as \"no design\" so\n * the arch viz does not render them as clickable. A missing/unparseable file is\n * treated as \"no design\".\n */\nfunction hasGeneratedDesign(workspaceRoot: string, projectRoot: string): boolean {\n    const designPath = path.join(workspaceRoot, projectRoot, 'design.json');\n    if (!fs.existsSync(designPath)) return false;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const parsed = JSON.parse(fs.readFileSync(designPath, 'utf-8'));\n        return Array.isArray(parsed.designs) && parsed.designs.length > 0;\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.warn(`⚠️  Skipping unparseable ${designPath}: ${error.message}`);\n        return false;\n    }\n}\n"]}

package/src/lib/graph-visualizer.js

@@ -47,7 +47,7 @@ function frameworkColor(frameworks) {
  * project's ROLE at a glance:
  *   server       → double border (a runnable server app)
  *   client       → dashed border (a client app, e.g. angular)
- *   designed-lib → bold border   (a library with a generated @ApiImplementation design)
+ *   designed-lib → bold border   (a library with a generated @DocumentDesign design)
  *   lib / other  → plain thin border
  */
 function roleBorderAttrs(role) {
@@ -273,7 +273,7 @@ function generateHTMLLegend() {
         </div>
         <div class="legend-item">
             <span class="legend-box" style="border: 2px solid #333;"></span>
-            <strong>designed-lib:</strong> library with a generated @ApiImplementation design (bold border)
+            <strong>designed-lib:</strong> library with a generated @DocumentDesign design (bold border)
         </div>
         <div class="legend-item">
             <span class="legend-box" style="border: 1px solid #ccc;"></span>

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, GraphEntry } from './graph-sorter';\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 * Fill color for an env set — the color of the first env in the set that has a\n * known color, else the default.\n */\nfunction 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 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 env set (libType), border shaped by role;\n    // the label shows the env set + role (e.g. [browser, node] · server).\n    // A node with a generated DI design also gets a URL so the rendered SVG box\n    // is 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 frameworks = info.framework ?? [];\n        const role = info.role ?? 'lib';\n        const color = frameworkColor(frameworks);\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 envSet = `[${frameworks.join(', ')}]`;\n        const labelMeta = isPromotedRole(role) ? `${envSet} · ${role}` : `L${info.level} · ${envSet} · ${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: #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        <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#), their framework env set (e.g. [browser, node]), and their role, 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"]}
+{"version":3,"file":"graph-visualizer.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-visualizer.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAiGH,kCAqEC;AAKD,oCAsBC;AAkID,gDAiBC;AAKD,8CAqBC;;AA5WD,+CAAyB;AACzB,mDAA6B;AAC7B,iDAAyC;AAIzC;;;;GAIG;AACH,MAAM,gBAAgB,GAA2B;IAC7C,OAAO,EAAE,SAAS,EAAE,6BAA6B;IACjD,KAAK,EAAE,SAAS,EAAE,2BAA2B;IAC7C,OAAO,EAAE,SAAS,EAAE,wCAAwC;IAC5D,OAAO,EAAE,SAAS,EAAE,iCAAiC;IACrD,IAAI,EAAE,SAAS,EAAE,kCAAkC;CACtD,CAAC;AAEF,MAAM,uBAAuB,GAAG,SAAS,CAAC,CAAC,+BAA+B;AAE1E;;;GAGG;AACH,SAAS,cAAc,CAAC,UAAoB;IACxC,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;IAC1C,CAAC;IACD,OAAO,uBAAuB,CAAC;AACnC,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,eAAe,CAAC,IAAY;IACjC,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,iBAAiB,CAAC;IAChD,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,yBAAyB,CAAC;IACxD,IAAI,IAAI,KAAK,cAAc;QAAE,OAAO,cAAc,CAAC;IACnD,OAAO,EAAE,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,cAAc,CAAC,IAAY;IAChC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,QAAQ,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CAAC,IAAY;IAC9B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,MAAM,eAAe,GAAG,cAAc,CAAC;AAEvC;;;;;;;;GAQG;AACH,SAAS,cAAc,CAAC,UAA8B;IAClD,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAC7B,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC;IACtE,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;AAC5D,CAAC;AAED;;GAEG;AACH,SAAgB,WAAW,CAAC,KAAoB,EAAE,QAAgB,kCAAkC;IAChG,IAAI,GAAG,GAAG,0BAA0B,CAAC;IACrC,GAAG,IAAI,iBAAiB,CAAC;IACzB,GAAG,IAAI,uDAAuD,CAAC;IAC/D,GAAG,IAAI,gCAAgC,CAAC;IAExC,4EAA4E;IAC5E,4EAA4E;IAC5E,2DAA2D;IAC3D,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAgB,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5F,MAAM,OAAO,GAAG,QAAQ,GAAG,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAG,CAAC,IAAgB,EAAU,EAAE,CACxC,cAAc,CAAC,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;IAE9D,MAAM,MAAM,GAA6B,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QACrC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAED,6EAA6E;IAC7E,sEAAsE;IACtE,4EAA4E;IAC5E,6EAA6E;IAC7E,KAAK,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;QACxC,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC;QAChC,MAAM,KAAK,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;QACzC,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,UAAU,IAAI,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,0EAA0E;QAC1E,wEAAwE;QACxE,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QAC5C,MAAM,SAAS,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,MAAM,MAAM,MAAM,IAAI,EAAE,CAAC;QACxG,GAAG,IAAI,MAAM,SAAS,iBAAiB,KAAK,IAAI,MAAM,GAAG,IAAI,YAAY,SAAS,OAAO,SAAS,QAAQ,CAAC;IAC/G,CAAC;IAED,GAAG,IAAI,IAAI,CAAC;IAEZ,4CAA4C;IAC5C,KAAK,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACrD,GAAG,IAAI,iBAAiB,CAAC;QACzB,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;YACnB,MAAM,SAAS,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;YAClC,GAAG,IAAI,IAAI,SAAS,KAAK,CAAC;QAC9B,CAAC,CAAC,CAAC;QACH,GAAG,IAAI,KAAK,CAAC;IACjB,CAAC;IAED,GAAG,IAAI,IAAI,CAAC;IAEZ,8BAA8B;IAC9B,KAAK,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;QACxC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;YACrC,MAAM,YAAY,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;YACvC,GAAG,IAAI,MAAM,SAAS,SAAS,YAAY,MAAM,CAAC;QACtD,CAAC;IACL,CAAC;IAED,GAAG,IAAI,qBAAqB,CAAC;IAC7B,GAAG,IAAI,YAAY,KAAK,8CAA8C,CAAC;IACvE,GAAG,IAAI,kBAAkB,CAAC;IAC1B,GAAG,IAAI,KAAK,CAAC;IAEb,OAAO,GAAG,CAAC;AACf,CAAC;AAED;;GAEG;AACH,SAAgB,YAAY,CAAC,GAAW,EAAE,QAAgB,kCAAkC;IACxF,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAC;IACpC,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAC;IACpC,MAAM,MAAM,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IAEvC,OAAO;;;;aAIE,KAAK;;;aAGL,MAAM;;;UAGT,KAAK;;MAET,MAAM;;cAEE,MAAM;;QAEZ,CAAC;AACT,CAAC;AAED,SAAS,kBAAkB;IACvB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAgDN,CAAC;AACN,CAAC;AAED,SAAS,kBAAkB;IACvB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAyCA,CAAC;AACZ,CAAC;AAED,SAAS,kBAAkB,CAAC,GAAW;IACnC,OAAO;sBACW,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC;;;;;;;;;;;KAWpC,CAAC;AACN,CAAC;AAMD;;;;;;;;;;GAUG;AACH,SAAgB,kBAAkB,CAC9B,KAAoB,EACpB,aAAqB,EACrB,QAAgB,kCAAkC;IAElD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;IAE5D,0BAA0B;IAC1B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5B,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,MAAM,IAAI,GAAG,YAAY,CAAC,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;IAC5D,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,mBAAmB,CAAC,CAAC;IAC3D,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAE1C,OAAO,EAAE,QAAQ,EAAE,CAAC;AACxB,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAAC,QAAgB;IAC9C,8DAA8D;IAC9D,IAAI,CAAC;QACD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QAClC,IAAI,WAAmB,CAAC;QAExB,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACxB,WAAW,GAAG,SAAS,QAAQ,GAAG,CAAC;QACvC,CAAC;aAAM,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;YAC9B,WAAW,GAAG,aAAa,QAAQ,GAAG,CAAC;QAC3C,CAAC;aAAM,CAAC;YACJ,WAAW,GAAG,aAAa,QAAQ,GAAG,CAAC;QAC3C,CAAC;QAED,IAAA,wBAAQ,EAAC,WAAW,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC3C,OAAO,IAAI,CAAC;IAChB,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,6BAA6B;QAC7B,KAAK,GAAG,CAAC;QACT,OAAO,KAAK,CAAC;IACjB,CAAC;AACL,CAAC","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 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 * Fill color for an env set — the color of the first env in the set that has a\n * known color, else the default.\n */\nfunction 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 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 @DocumentDesign 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 env set (libType), border shaped by role;\n    // the label shows the env set + role (e.g. [browser, node] · server).\n    // A node with a generated DI design also gets a URL so the rendered SVG box\n    // is 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 frameworks = info.framework ?? [];\n        const role = info.role ?? 'lib';\n        const color = frameworkColor(frameworks);\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 envSet = `[${frameworks.join(', ')}]`;\n        const labelMeta = isPromotedRole(role) ? `${envSet} · ${role}` : `L${info.level} · ${envSet} · ${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: #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        <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 @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\" style=\"margin-top: 15px;\">\n            <em>Library nodes show their dependency level (L#), their framework env set (e.g. [browser, node]), and their role, 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"]}

package/src/lib/role-resolver.d.ts

@@ -5,9 +5,9 @@
  * architecture/dependencies.json — a project's ROLE, orthogonal to its
  * `framework` (libType). Known values:
  *
- *   - `server`       — a runnable server app; DI design roots on `@Controller`.
+ *   - `server`       — a runnable server app; DI design roots on `@DocumentDesign`.
  *   - `designed-lib` — a library whose DI design we generate; roots on
- *                      `@ApiImplementation` (required to have ≥1).
+ *                      `@DocumentDesign` (required to have ≥1).
  *   - `lib`          — a plain library; no DI design is generated.
  *   - `client`       — a client app (e.g. angular-site); angular apps keep their
  *                      component/route design, others get none.

package/src/lib/role-resolver.js

@@ -6,9 +6,9 @@
  * architecture/dependencies.json — a project's ROLE, orthogonal to its
  * `framework` (libType). Known values:
  *
- *   - `server`       — a runnable server app; DI design roots on `@Controller`.
+ *   - `server`       — a runnable server app; DI design roots on `@DocumentDesign`.
  *   - `designed-lib` — a library whose DI design we generate; roots on
- *                      `@ApiImplementation` (required to have ≥1).
+ *                      `@DocumentDesign` (required to have ≥1).
  *   - `lib`          — a plain library; no DI design is generated.
  *   - `client`       — a client app (e.g. angular-site); angular apps keep their
  *                      component/route design, others get none.

package/src/lib/role-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"role-resolver.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/role-resolver.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAqBH,kCAmBC;AApCY,QAAA,eAAe,GAAG,OAAO,CAAC;AAEvC,0EAA0E;AAC7D,QAAA,WAAW,GAA0B,CAAC,QAAQ,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;AAE9F,+DAA+D;AAClD,QAAA,YAAY,GAAG,KAAK,CAAC;AAElC,MAAa,cAAc;IAGH;IAEA;IAJpB;IACI,yDAAyD;IACzC,IAAmB;IACnC,iEAAiE;IACjD,OAAsB;QAFtB,SAAI,GAAJ,IAAI,CAAe;QAEnB,YAAO,GAAP,OAAO,CAAe;IACvC,CAAC;CACP;AAPD,wCAOC;AAED,SAAgB,WAAW,CAAC,IAAiB;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI;SACtB,MAAM,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,uBAAe,CAAC,CAAC;SACxD,GAAG,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,uBAAe,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAEpE,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,IAAI,cAAc,CACrB,IAAI,EACJ,GAAG,IAAI,CAAC,IAAI,SAAS,SAAS,CAAC,MAAM,kBAAkB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,qCAAqC,CACnH,CAAC;IACN,CAAC;IACD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,IAAI,cAAc,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,IAAI,kCAAkC,CAAC,CAAC;QACpF,CAAC;QACD,OAAO,IAAI,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAClD,CAAC;IAED,OAAO,IAAI,cAAc,CAAC,oBAAY,EAAE,IAAI,CAAC,CAAC;AAClD,CAAC","sourcesContent":["/**\n * Role Resolver\n *\n * Determines the `role` field written per project into\n * architecture/dependencies.json — a project's ROLE, orthogonal to its\n * `framework` (libType). Known values:\n *\n *   - `server`       — a runnable server app; DI design roots on `@Controller`.\n *   - `designed-lib` — a library whose DI design we generate; roots on\n *                      `@ApiImplementation` (required to have ≥1).\n *   - `lib`          — a plain library; no DI design is generated.\n *   - `client`       — a client app (e.g. angular-site); angular apps keep their\n *                      component/route design, others get none.\n *\n * Resolution order:\n * 1. Explicit nx tag `role:<value>` on the project (project.json tags) — the\n *    source of truth; every project should carry one (enforced by the\n *    `role-tag` code rule).\n * 2. Fallback: 'lib' (a plain library with no generated design) — the safe\n *    default so an untagged project never claims to be a server/client.\n */\n\nimport { ProjectInfo } from './project-info';\n\nexport const ROLE_TAG_PREFIX = 'role:';\n\n/** The roles the `role-tag` rule and the DI-graph analyzer understand. */\nexport const KNOWN_ROLES: ReadonlyArray<string> = ['server', 'designed-lib', 'lib', 'client'];\n\n/** Default role for a project with no explicit `role:` tag. */\nexport const DEFAULT_ROLE = 'lib';\n\nexport class RoleResolution {\n    constructor(\n        /** Resolved role name, or null when resolution failed */\n        public readonly role: string | null,\n        /** Problem description when resolution failed, otherwise null */\n        public readonly problem: string | null\n    ) {}\n}\n\nexport function resolveRole(info: ProjectInfo): RoleResolution {\n    const tagValues = info.tags\n        .filter((tag: string) => tag.startsWith(ROLE_TAG_PREFIX))\n        .map((tag: string) => tag.slice(ROLE_TAG_PREFIX.length).trim());\n\n    if (tagValues.length > 1) {\n        return new RoleResolution(\n            null,\n            `${info.name}: has ${tagValues.length} 'role:' tags (${tagValues.join(', ')}) — a project must have at most one`\n        );\n    }\n    if (tagValues.length === 1) {\n        if (tagValues[0].length === 0) {\n            return new RoleResolution(null, `${info.name}: 'role:' tag has an empty value`);\n        }\n        return new RoleResolution(tagValues[0], null);\n    }\n\n    return new RoleResolution(DEFAULT_ROLE, null);\n}\n"]}
+{"version":3,"file":"role-resolver.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/role-resolver.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAqBH,kCAmBC;AApCY,QAAA,eAAe,GAAG,OAAO,CAAC;AAEvC,0EAA0E;AAC7D,QAAA,WAAW,GAA0B,CAAC,QAAQ,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;AAE9F,+DAA+D;AAClD,QAAA,YAAY,GAAG,KAAK,CAAC;AAElC,MAAa,cAAc;IAGH;IAEA;IAJpB;IACI,yDAAyD;IACzC,IAAmB;IACnC,iEAAiE;IACjD,OAAsB;QAFtB,SAAI,GAAJ,IAAI,CAAe;QAEnB,YAAO,GAAP,OAAO,CAAe;IACvC,CAAC;CACP;AAPD,wCAOC;AAED,SAAgB,WAAW,CAAC,IAAiB;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI;SACtB,MAAM,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,uBAAe,CAAC,CAAC;SACxD,GAAG,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,uBAAe,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAEpE,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,IAAI,cAAc,CACrB,IAAI,EACJ,GAAG,IAAI,CAAC,IAAI,SAAS,SAAS,CAAC,MAAM,kBAAkB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,qCAAqC,CACnH,CAAC;IACN,CAAC;IACD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,IAAI,cAAc,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,IAAI,kCAAkC,CAAC,CAAC;QACpF,CAAC;QACD,OAAO,IAAI,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAClD,CAAC;IAED,OAAO,IAAI,cAAc,CAAC,oBAAY,EAAE,IAAI,CAAC,CAAC;AAClD,CAAC","sourcesContent":["/**\n * Role Resolver\n *\n * Determines the `role` field written per project into\n * architecture/dependencies.json — a project's ROLE, orthogonal to its\n * `framework` (libType). Known values:\n *\n *   - `server`       — a runnable server app; DI design roots on `@DocumentDesign`.\n *   - `designed-lib` — a library whose DI design we generate; roots on\n *                      `@DocumentDesign` (required to have ≥1).\n *   - `lib`          — a plain library; no DI design is generated.\n *   - `client`       — a client app (e.g. angular-site); angular apps keep their\n *                      component/route design, others get none.\n *\n * Resolution order:\n * 1. Explicit nx tag `role:<value>` on the project (project.json tags) — the\n *    source of truth; every project should carry one (enforced by the\n *    `role-tag` code rule).\n * 2. Fallback: 'lib' (a plain library with no generated design) — the safe\n *    default so an untagged project never claims to be a server/client.\n */\n\nimport { ProjectInfo } from './project-info';\n\nexport const ROLE_TAG_PREFIX = 'role:';\n\n/** The roles the `role-tag` rule and the DI-graph analyzer understand. */\nexport const KNOWN_ROLES: ReadonlyArray<string> = ['server', 'designed-lib', 'lib', 'client'];\n\n/** Default role for a project with no explicit `role:` tag. */\nexport const DEFAULT_ROLE = 'lib';\n\nexport class RoleResolution {\n    constructor(\n        /** Resolved role name, or null when resolution failed */\n        public readonly role: string | null,\n        /** Problem description when resolution failed, otherwise null */\n        public readonly problem: string | null\n    ) {}\n}\n\nexport function resolveRole(info: ProjectInfo): RoleResolution {\n    const tagValues = info.tags\n        .filter((tag: string) => tag.startsWith(ROLE_TAG_PREFIX))\n        .map((tag: string) => tag.slice(ROLE_TAG_PREFIX.length).trim());\n\n    if (tagValues.length > 1) {\n        return new RoleResolution(\n            null,\n            `${info.name}: has ${tagValues.length} 'role:' tags (${tagValues.join(', ')}) — a project must have at most one`\n        );\n    }\n    if (tagValues.length === 1) {\n        if (tagValues[0].length === 0) {\n            return new RoleResolution(null, `${info.name}: 'role:' tag has an empty value`);\n        }\n        return new RoleResolution(tagValues[0], null);\n    }\n\n    return new RoleResolution(DEFAULT_ROLE, null);\n}\n"]}