@webpieces/nx-webpieces-rules 0.3.362 → 0.3.364

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/nx-webpieces-rules",
-  "version": "0.3.362",
+  "version": "0.3.364",
   "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.362",
-    "@webpieces/code-rules": "0.3.362",
-    "@webpieces/eslint-rules": "0.3.362",
-    "@webpieces/pr-gate": "0.3.362",
-    "@webpieces/rules-config": "0.3.362",
+    "@webpieces/ai-hook-rules": "0.3.364",
+    "@webpieces/code-rules": "0.3.364",
+    "@webpieces/eslint-rules": "0.3.364",
+    "@webpieces/pr-gate": "0.3.364",
+    "@webpieces/rules-config": "0.3.364",
     "madge": "8.0.0"
   },
   "peerDependencies": {

package/src/lib/di-graph/analyzer-strategy.d.ts

@@ -63,6 +63,7 @@ export declare function explicitRoleTag(tags: readonly string[]): string | null;
  *  - `app`          → Inversify, roots on `@DocumentDesign` (controller kind) — a runnable
  *                     (non-HTTP) application bootstrapped via `container.get(XxxApp)`, e.g. the
  *                     tooling packages (AiRulesApp, RulesApp). Drawn exactly like a server.
+ *  - `bundle`       → skip (an aggregator of apps; no design of its own)
  *  - `designed-lib` → Inversify, roots on `@DocumentDesign` (apiImplementation kind)
  *  - `client`       → Angular design for angular apps; otherwise skip
  *  - `lib`          → skip (plain libraries get no design)

package/src/lib/di-graph/analyzer-strategy.js

@@ -108,6 +108,7 @@ function explicitRoleTag(tags) {
  *  - `app`          → Inversify, roots on `@DocumentDesign` (controller kind) — a runnable
  *                     (non-HTTP) application bootstrapped via `container.get(XxxApp)`, e.g. the
  *                     tooling packages (AiRulesApp, RulesApp). Drawn exactly like a server.
+ *  - `bundle`       → skip (an aggregator of apps; no design of its own)
  *  - `designed-lib` → Inversify, roots on `@DocumentDesign` (apiImplementation kind)
  *  - `client`       → Angular design for angular apps; otherwise skip
  *  - `lib`          → skip (plain libraries get no design)
@@ -119,6 +120,8 @@ function selectAnalyzer(role, frameworks, markers) {
         return new InversifyAnalyzer('controller');
     if (role === 'app')
         return new InversifyAnalyzer('controller');
+    if (role === 'bundle')
+        return new EmptyAnalyzer();
     if (role === 'designed-lib')
         return new InversifyAnalyzer('apiImplementation');
     if (role === 'client')

package/src/lib/di-graph/analyzer-strategy.js.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer-strategy.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/di-graph/analyzer-strategy.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * DI Analyzer Strategy\n *\n * Picks which DI analyzer generates a project's design graph. The primary\n * driver is the project's `role` nx tag; the `framework` env set (its libType)\n * only distinguishes the client runtime by set membership:\n *\n *   - env set includes `express` → {@link InversifyAnalyzer} (roots on `@DocumentDesign`)\n *   - env set includes `angular` → {@link AngularAnalyzer}  (roots on the bootstrap/route components)\n *   - anything else (`react`, `browser`, `node`, ...) → {@link EmptyAnalyzer} (skip)\n *\n * The explicit tags are the source of truth. When the role tag is ABSENT (e.g.\n * before retag), a cheap marker pre-scan corroborates: `@Component(` /\n * `bootstrapApplication` → angular; `@DocumentDesign(` → Inversify. This makes the\n * committed design.* identical whether selection is tag- or marker-driven.\n */\n\nimport type * as ts from 'typescript';\nimport { DiGraph } from './model';\nimport { buildDiGraph, DiRootMode } from './analyzer';\nimport { buildAngularDiGraph } from './angular-analyzer';\n\nconst FRAMEWORK_TAG_PREFIX = 'framework:';\nconst ROLE_TAG_PREFIX = 'role:';\n\n/** Which framework a source tree's decorators point at (marker pre-scan fallback). */\nexport class FrameworkMarkers {\n    angular: boolean;\n    controller: boolean;\n\n    constructor(angular: boolean, controller: boolean) {\n        this.angular = angular;\n        this.controller = controller;\n    }\n}\n\n/** Statically analyzes one project's DI dependency DAG into a `DiGraph`. */\nexport interface DiAnalyzer {\n    analyzeProject(program: ts.Program, workspaceRoot: string, projectRoot: string, projectName: string): DiGraph;\n}\n\n/**\n * Inversify analyzer: one design per `@DocumentDesign` root. The `rootMode` only\n * sets the root box kind:\n *  - `'controller'` (server projects) → `controller`.\n *  - `'apiImplementation'` (role:designed-lib) → `apiImplementation`.\n */\nexport class InversifyAnalyzer implements DiAnalyzer {\n    private readonly rootMode: DiRootMode;\n\n    constructor(rootMode: DiRootMode = 'controller') {\n        this.rootMode = rootMode;\n    }\n\n    analyzeProject(program: ts.Program, workspaceRoot: string, projectRoot: string, projectName: string): DiGraph {\n        return buildDiGraph(program, workspaceRoot, projectRoot, projectName, false, this.rootMode);\n    }\n}\n\n/** Angular: one design per entry component (bootstrap + routed). */\nexport class AngularAnalyzer implements DiAnalyzer {\n    analyzeProject(program: ts.Program, workspaceRoot: string, projectRoot: string, projectName: string): DiGraph {\n        return buildAngularDiGraph(program, workspaceRoot, projectRoot, projectName);\n    }\n}\n\n/** Non-angular/non-express projects: an empty graph (skip). */\nexport class EmptyAnalyzer implements DiAnalyzer {\n    analyzeProject(\n        _program: ts.Program,\n        _workspaceRoot: string,\n        _projectRoot: string,\n        projectName: string,\n    ): DiGraph {\n        return new DiGraph(projectName);\n    }\n}\n\n/** Extract the explicit `<prefix><value>` nx tag, or null when the project has none. */\nfunction explicitTag(tags: readonly string[], prefix: string): string | null {\n    for (const tag of tags) {\n        if (tag.startsWith(prefix)) {\n            const value = tag.slice(prefix.length).trim();\n            if (value.length > 0) return value;\n        }\n    }\n    return null;\n}\n\n/** Extract the FIRST explicit `framework:<value>` nx tag, or null when the project has none. */\nexport function explicitFrameworkTag(tags: readonly string[]): string | null {\n    return explicitTag(tags, FRAMEWORK_TAG_PREFIX);\n}\n\n/** Extract every explicit `framework:<value>` nx tag as an env set (the project's libType). */\nexport function frameworkTags(tags: readonly string[]): string[] {\n    const values: string[] = [];\n    for (const tag of tags) {\n        if (tag.startsWith(FRAMEWORK_TAG_PREFIX)) {\n            const value = tag.slice(FRAMEWORK_TAG_PREFIX.length).trim();\n            if (value.length > 0) values.push(value);\n        }\n    }\n    return values;\n}\n\n/** Extract the explicit `role:<value>` nx tag, or null when the project has none. */\nexport function explicitRoleTag(tags: readonly string[]): string | null {\n    return explicitTag(tags, ROLE_TAG_PREFIX);\n}\n\n/**\n * Choose the analyzer for a project. `role` (server|designed-lib|lib|client) is\n * the source of truth for WHAT to root on; `frameworks` is the project's env set\n * (its libType) and distinguishes the client runtime (angular vs other) by set\n * membership; `markers` corroborate only when the role tag is ABSENT (rollout\n * fallback keeps pre-retag designs identical).\n *\n *  - `server`       → Inversify, roots on `@DocumentDesign` (controller kind)\n *  - `app`          → Inversify, roots on `@DocumentDesign` (controller kind) — a runnable\n *                     (non-HTTP) application bootstrapped via `container.get(XxxApp)`, e.g. the\n *                     tooling packages (AiRulesApp, RulesApp). Drawn exactly like a server.\n *  - `designed-lib` → Inversify, roots on `@DocumentDesign` (apiImplementation kind)\n *  - `client`       → Angular design for angular apps; otherwise skip\n *  - `lib`          → skip (plain libraries get no design)\n *  - `api-lib`      → skip (contract-only libraries get no design)\n *  - role absent    → legacy framework/marker selection\n */\nexport function selectAnalyzer(\n    role: string | null,\n    frameworks: string[],\n    markers: FrameworkMarkers,\n): DiAnalyzer {\n    if (role === 'server') return new InversifyAnalyzer('controller');\n    if (role === 'app') return new InversifyAnalyzer('controller');\n    if (role === 'designed-lib') return new InversifyAnalyzer('apiImplementation');\n    if (role === 'client') return frameworks.includes('angular') ? new AngularAnalyzer() : new EmptyAnalyzer();\n    if (role === 'lib') return new EmptyAnalyzer();\n    if (role === 'api-lib') return new EmptyAnalyzer();\n\n    // Role tag absent — fall back to the legacy framework/marker selection so\n    // designs stay identical until a project is retagged.\n    if (frameworks.includes('express')) return new InversifyAnalyzer('controller');\n    if (frameworks.includes('angular')) return new AngularAnalyzer();\n    if (frameworks.length > 0) return new EmptyAnalyzer();\n    if (markers.angular) return new AngularAnalyzer();\n    if (markers.controller) return new InversifyAnalyzer('controller');\n    return new EmptyAnalyzer();\n}\n"]}
+{"version":3,"file":"analyzer-strategy.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/di-graph/analyzer-strategy.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * DI Analyzer Strategy\n *\n * Picks which DI analyzer generates a project's design graph. The primary\n * driver is the project's `role` nx tag; the `framework` env set (its libType)\n * only distinguishes the client runtime by set membership:\n *\n *   - env set includes `express` → {@link InversifyAnalyzer} (roots on `@DocumentDesign`)\n *   - env set includes `angular` → {@link AngularAnalyzer}  (roots on the bootstrap/route components)\n *   - anything else (`react`, `browser`, `node`, ...) → {@link EmptyAnalyzer} (skip)\n *\n * The explicit tags are the source of truth. When the role tag is ABSENT (e.g.\n * before retag), a cheap marker pre-scan corroborates: `@Component(` /\n * `bootstrapApplication` → angular; `@DocumentDesign(` → Inversify. This makes the\n * committed design.* identical whether selection is tag- or marker-driven.\n */\n\nimport type * as ts from 'typescript';\nimport { DiGraph } from './model';\nimport { buildDiGraph, DiRootMode } from './analyzer';\nimport { buildAngularDiGraph } from './angular-analyzer';\n\nconst FRAMEWORK_TAG_PREFIX = 'framework:';\nconst ROLE_TAG_PREFIX = 'role:';\n\n/** Which framework a source tree's decorators point at (marker pre-scan fallback). */\nexport class FrameworkMarkers {\n    angular: boolean;\n    controller: boolean;\n\n    constructor(angular: boolean, controller: boolean) {\n        this.angular = angular;\n        this.controller = controller;\n    }\n}\n\n/** Statically analyzes one project's DI dependency DAG into a `DiGraph`. */\nexport interface DiAnalyzer {\n    analyzeProject(program: ts.Program, workspaceRoot: string, projectRoot: string, projectName: string): DiGraph;\n}\n\n/**\n * Inversify analyzer: one design per `@DocumentDesign` root. The `rootMode` only\n * sets the root box kind:\n *  - `'controller'` (server projects) → `controller`.\n *  - `'apiImplementation'` (role:designed-lib) → `apiImplementation`.\n */\nexport class InversifyAnalyzer implements DiAnalyzer {\n    private readonly rootMode: DiRootMode;\n\n    constructor(rootMode: DiRootMode = 'controller') {\n        this.rootMode = rootMode;\n    }\n\n    analyzeProject(program: ts.Program, workspaceRoot: string, projectRoot: string, projectName: string): DiGraph {\n        return buildDiGraph(program, workspaceRoot, projectRoot, projectName, false, this.rootMode);\n    }\n}\n\n/** Angular: one design per entry component (bootstrap + routed). */\nexport class AngularAnalyzer implements DiAnalyzer {\n    analyzeProject(program: ts.Program, workspaceRoot: string, projectRoot: string, projectName: string): DiGraph {\n        return buildAngularDiGraph(program, workspaceRoot, projectRoot, projectName);\n    }\n}\n\n/** Non-angular/non-express projects: an empty graph (skip). */\nexport class EmptyAnalyzer implements DiAnalyzer {\n    analyzeProject(\n        _program: ts.Program,\n        _workspaceRoot: string,\n        _projectRoot: string,\n        projectName: string,\n    ): DiGraph {\n        return new DiGraph(projectName);\n    }\n}\n\n/** Extract the explicit `<prefix><value>` nx tag, or null when the project has none. */\nfunction explicitTag(tags: readonly string[], prefix: string): string | null {\n    for (const tag of tags) {\n        if (tag.startsWith(prefix)) {\n            const value = tag.slice(prefix.length).trim();\n            if (value.length > 0) return value;\n        }\n    }\n    return null;\n}\n\n/** Extract the FIRST explicit `framework:<value>` nx tag, or null when the project has none. */\nexport function explicitFrameworkTag(tags: readonly string[]): string | null {\n    return explicitTag(tags, FRAMEWORK_TAG_PREFIX);\n}\n\n/** Extract every explicit `framework:<value>` nx tag as an env set (the project's libType). */\nexport function frameworkTags(tags: readonly string[]): string[] {\n    const values: string[] = [];\n    for (const tag of tags) {\n        if (tag.startsWith(FRAMEWORK_TAG_PREFIX)) {\n            const value = tag.slice(FRAMEWORK_TAG_PREFIX.length).trim();\n            if (value.length > 0) values.push(value);\n        }\n    }\n    return values;\n}\n\n/** Extract the explicit `role:<value>` nx tag, or null when the project has none. */\nexport function explicitRoleTag(tags: readonly string[]): string | null {\n    return explicitTag(tags, ROLE_TAG_PREFIX);\n}\n\n/**\n * Choose the analyzer for a project. `role` (server|designed-lib|lib|client) is\n * the source of truth for WHAT to root on; `frameworks` is the project's env set\n * (its libType) and distinguishes the client runtime (angular vs other) by set\n * membership; `markers` corroborate only when the role tag is ABSENT (rollout\n * fallback keeps pre-retag designs identical).\n *\n *  - `server`       → Inversify, roots on `@DocumentDesign` (controller kind)\n *  - `app`          → Inversify, roots on `@DocumentDesign` (controller kind) — a runnable\n *                     (non-HTTP) application bootstrapped via `container.get(XxxApp)`, e.g. the\n *                     tooling packages (AiRulesApp, RulesApp). Drawn exactly like a server.\n *  - `bundle`       → skip (an aggregator of apps; no design of its own)\n *  - `designed-lib` → Inversify, roots on `@DocumentDesign` (apiImplementation kind)\n *  - `client`       → Angular design for angular apps; otherwise skip\n *  - `lib`          → skip (plain libraries get no design)\n *  - `api-lib`      → skip (contract-only libraries get no design)\n *  - role absent    → legacy framework/marker selection\n */\nexport function selectAnalyzer(\n    role: string | null,\n    frameworks: string[],\n    markers: FrameworkMarkers,\n): DiAnalyzer {\n    if (role === 'server') return new InversifyAnalyzer('controller');\n    if (role === 'app') return new InversifyAnalyzer('controller');\n    if (role === 'bundle') return new EmptyAnalyzer();\n    if (role === 'designed-lib') return new InversifyAnalyzer('apiImplementation');\n    if (role === 'client') return frameworks.includes('angular') ? new AngularAnalyzer() : new EmptyAnalyzer();\n    if (role === 'lib') return new EmptyAnalyzer();\n    if (role === 'api-lib') return new EmptyAnalyzer();\n\n    // Role tag absent — fall back to the legacy framework/marker selection so\n    // designs stay identical until a project is retagged.\n    if (frameworks.includes('express')) return new InversifyAnalyzer('controller');\n    if (frameworks.includes('angular')) return new AngularAnalyzer();\n    if (frameworks.length > 0) return new EmptyAnalyzer();\n    if (markers.angular) return new AngularAnalyzer();\n    if (markers.controller) return new InversifyAnalyzer('controller');\n    return new EmptyAnalyzer();\n}\n"]}

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

@@ -70,5 +70,8 @@ export declare function validateLibraryTypesMatch(graph: EnhancedGraph, problems
  *     legitimate case is a server-side orchestrator/e2e harness that boots
  *     other servers. A `lib`/`designed-lib`/`client` depending on a `server`
  *     inverts the dependency direction and is a violation.
+ *   - a `bundle` is the one role permitted to depend on ANY app: it aggregates
+ *     several apps into one distributable (e.g. an nx plugin re-exposing multiple
+ *     tooling apps), so a `bundle → app` edge is legitimate, not inverted.
  */
 export declare function validateRoleDependencies(graph: EnhancedGraph, problems: string[]): void;

package/src/lib/graph-metadata.js

@@ -174,6 +174,9 @@ function validateLibraryTypesMatch(graph, problems) {
  *     legitimate case is a server-side orchestrator/e2e harness that boots
  *     other servers. A `lib`/`designed-lib`/`client` depending on a `server`
  *     inverts the dependency direction and is a violation.
+ *   - a `bundle` is the one role permitted to depend on ANY app: it aggregates
+ *     several apps into one distributable (e.g. an nx plugin re-exposing multiple
+ *     tooling apps), so a `bundle → app` edge is legitimate, not inverted.
  */
 function validateRoleDependencies(graph, problems) {
     for (const [projectName, entry] of Object.entries(graph)) {
@@ -187,6 +190,9 @@ function validateRoleDependencies(graph, problems) {
             // A server may orchestrate/boot other servers (e.g. an e2e harness).
             if (toRole === 'server' && fromRole === 'server')
                 continue;
+            // A bundle aggregates apps — it may depend on any app role.
+            if (fromRole === 'bundle')
+                continue;
             const why = toRole === 'client'
                 ? `a 'client' app is terminal and may never be depended upon`
                 : `a 'server' may only be depended upon by another 'server' (an orchestrator/e2e harness)`;

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 { resolveDrawOnGraph } from './draw-on-graph-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        // Only persist the field when hidden (false); drawn projects (the\n        // default) stay clean in dependencies.json with no drawOnGraph line.\n        const drawResolution = resolveDrawOnGraph(info);\n        if (drawResolution.problem !== null) {\n            problems.push(drawResolution.problem);\n        } else if (drawResolution.drawOnGraph === false) {\n            entry.drawOnGraph = false;\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, a\n * non-HTTP `app`, or a client is a top-level runnable; being depended upon means\n * it is really a library and should be retagged `role:lib`/`role:designed-lib`.\n */\nexport const APP_ROLES: ReadonlyArray<string> = ['server', 'app', '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"]}
+{"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 { resolveDrawOnGraph } from './draw-on-graph-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        // Only persist the field when hidden (false); drawn projects (the\n        // default) stay clean in dependencies.json with no drawOnGraph line.\n        const drawResolution = resolveDrawOnGraph(info);\n        if (drawResolution.problem !== null) {\n            problems.push(drawResolution.problem);\n        } else if (drawResolution.drawOnGraph === false) {\n            entry.drawOnGraph = false;\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, a\n * non-HTTP `app`, or a client is a top-level runnable; being depended upon means\n * it is really a library and should be retagged `role:lib`/`role:designed-lib`.\n */\nexport const APP_ROLES: ReadonlyArray<string> = ['server', 'app', '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 *   - a `bundle` is the one role permitted to depend on ANY app: it aggregates\n *     several apps into one distributable (e.g. an nx plugin re-exposing multiple\n *     tooling apps), so a `bundle → app` edge is legitimate, not inverted.\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            // A bundle aggregates apps — it may depend on any app role.\n            if (fromRole === 'bundle') 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.d.ts

@@ -32,9 +32,11 @@ export declare class GraphVisualizer {
      * Role border styling — fill stays keyed on framework; the border shows a
      * project's ROLE at a glance. Server and client are the top-level runnable
      * nodes, so they get bold, colored borders to stand out:
-     *   server       → thick GREEN border (a runnable server app)
-     *   client       → thick RED border   (a client app, e.g. angular)
-     *   designed-lib → bold border        (a library with a generated @DocumentDesign design)
+     *   server       → thick GREEN border  (a runnable server app)
+     *   app          → thick BLUE border   (a runnable non-HTTP app, e.g. a tooling app)
+     *   bundle       → thick PURPLE border (an aggregator that bundles several apps)
+     *   client       → thick RED border    (a client app, e.g. angular)
+     *   designed-lib → bold border         (a library with a generated @DocumentDesign design)
      *   lib / other  → plain thin border
      */
     private roleBorderAttrs;

package/src/lib/graph-visualizer.js

@@ -72,14 +72,20 @@ class GraphVisualizer {
      * Role border styling — fill stays keyed on framework; the border shows a
      * project's ROLE at a glance. Server and client are the top-level runnable
      * nodes, so they get bold, colored borders to stand out:
-     *   server       → thick GREEN border (a runnable server app)
-     *   client       → thick RED border   (a client app, e.g. angular)
-     *   designed-lib → bold border        (a library with a generated @DocumentDesign design)
+     *   server       → thick GREEN border  (a runnable server app)
+     *   app          → thick BLUE border   (a runnable non-HTTP app, e.g. a tooling app)
+     *   bundle       → thick PURPLE border (an aggregator that bundles several apps)
+     *   client       → thick RED border    (a client app, e.g. angular)
+     *   designed-lib → bold border         (a library with a generated @DocumentDesign design)
      *   lib / other  → plain thin border
      */
     roleBorderAttrs(role) {
         if (role === 'server')
             return ', color="green", penwidth=3';
+        if (role === 'app')
+            return ', color="#1976d2", penwidth=3';
+        if (role === 'bundle')
+            return ', color="#6A1B9A", penwidth=3';
         if (role === 'client')
             return ', color="red", penwidth=3';
         if (role === 'api-lib')

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

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

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

@@ -9,6 +9,10 @@
  *   - `app`          — a runnable non-HTTP application bootstrapped via
  *                      `container.get(XxxApp)` (e.g. the tooling packages); DI design
  *                      roots on `@DocumentDesign`, drawn exactly like a server.
+ *   - `bundle`       — an aggregator that BUNDLES several apps into one distributable
+ *                      (e.g. an nx plugin re-exposing multiple tooling apps). It is the
+ *                      one role permitted to depend on `role:app` projects; it has no DI
+ *                      design of its own (it is a container of apps, not a designed root).
  *   - `designed-lib` — a library whose DI design we generate; roots on
  *                      `@DocumentDesign` (required to have ≥1).
  *   - `lib`          — a plain library; no DI design is generated.

package/src/lib/role-resolver.js

@@ -10,6 +10,10 @@
  *   - `app`          — a runnable non-HTTP application bootstrapped via
  *                      `container.get(XxxApp)` (e.g. the tooling packages); DI design
  *                      roots on `@DocumentDesign`, drawn exactly like a server.
+ *   - `bundle`       — an aggregator that BUNDLES several apps into one distributable
+ *                      (e.g. an nx plugin re-exposing multiple tooling apps). It is the
+ *                      one role permitted to depend on `role:app` projects; it has no DI
+ *                      design of its own (it is a container of apps, not a designed root).
  *   - `designed-lib` — a library whose DI design we generate; roots on
  *                      `@DocumentDesign` (required to have ≥1).
  *   - `lib`          — a plain library; no DI design is generated.
@@ -31,7 +35,7 @@ exports.RoleResolution = exports.DEFAULT_ROLE = exports.KNOWN_ROLES = exports.RO
 exports.resolveRole = resolveRole;
 exports.ROLE_TAG_PREFIX = 'role:';
 /** The roles the `role-tag` rule and the DI-graph analyzer understand. */
-exports.KNOWN_ROLES = ['server', 'app', 'designed-lib', 'lib', 'client', 'api-lib'];
+exports.KNOWN_ROLES = ['server', 'app', 'bundle', 'designed-lib', 'lib', 'client', 'api-lib'];
 /** Default role for a project with no explicit `role:` tag. */
 exports.DEFAULT_ROLE = 'lib';
 class RoleResolution {

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;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;AAqBH,kCAmBC;AApCY,QAAA,eAAe,GAAG,OAAO,CAAC;AAEvC,0EAA0E;AAC7D,QAAA,WAAW,GAA0B,CAAC,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;AAEhH,+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 *   - `app`          — a runnable non-HTTP application bootstrapped via\n *                      `container.get(XxxApp)` (e.g. the tooling packages); DI design\n *                      roots on `@DocumentDesign`, drawn exactly like a server.\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 *   - `api-lib`      — an API-contract library: exports `@ApiPath`/`@Rpc`/`@PubSub`\n *                      abstract `*Api` classes that servers implement and clients\n *                      generate typed clients from. No DI design of its own.\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', 'app', 'designed-lib', 'lib', 'client', 'api-lib'];\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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;;;AAqBH,kCAmBC;AApCY,QAAA,eAAe,GAAG,OAAO,CAAC;AAEvC,0EAA0E;AAC7D,QAAA,WAAW,GAA0B,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;AAE1H,+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 *   - `app`          — a runnable non-HTTP application bootstrapped via\n *                      `container.get(XxxApp)` (e.g. the tooling packages); DI design\n *                      roots on `@DocumentDesign`, drawn exactly like a server.\n *   - `bundle`       — an aggregator that BUNDLES several apps into one distributable\n *                      (e.g. an nx plugin re-exposing multiple tooling apps). It is the\n *                      one role permitted to depend on `role:app` projects; it has no DI\n *                      design of its own (it is a container of apps, not a designed root).\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 *   - `api-lib`      — an API-contract library: exports `@ApiPath`/`@Rpc`/`@PubSub`\n *                      abstract `*Api` classes that servers implement and clients\n *                      generate typed clients from. No DI design of its own.\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', 'app', 'bundle', 'designed-lib', 'lib', 'client', 'api-lib'];\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"]}