@webpieces/nx-webpieces-rules 0.3.348 → 0.3.350

package/package.json

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

package/src/executors/di-graph-generate/executor.js

@@ -133,11 +133,11 @@ function chooseAnalyzer(tags, srcDir) {
  * `missing-design-annotation` rule.
  */
 function reportMissingDesignAnnotation(projectName, role) {
-    if (role === 'server') {
-        console.error(`❌ ${projectName} is tagged role:server but has no @DocumentDesign class.\n` +
-            `   All controllers should be annotated with @DocumentDesign() ` +
-            `(from @webpieces/http-routing) so their design.json / design.html get generated\n` +
-            `   and linked from architecture/dependencies.html.`);
+    if (role === 'server' || role === 'app') {
+        console.error(`❌ ${projectName} is tagged role:${role} but has no @DocumentDesign class.\n` +
+            `   A role:${role} project must expose one @DocumentDesign() root class (the App the ` +
+            `container resolves via container.get(XxxApp)) so its design.json / design.html get\n` +
+            `   generated and linked from architecture/dependencies.html.`);
         return;
     }
     console.error(`❌ ${projectName} is tagged role:designed-lib but has no @DocumentDesign class.\n` +
@@ -154,7 +154,7 @@ function reportMissingDesignAnnotation(projectName, role) {
 function failsMissingDesignAnnotation(shared, role, graph, projectName) {
     const missingRule = shared.rules.get(MISSING_DESIGN_RULE_NAME);
     const enforce = !missingRule || !missingRule.isOff;
-    if (enforce && graph.designs.length === 0 && (role === 'server' || role === 'designed-lib')) {
+    if (enforce && graph.designs.length === 0 && (role === 'server' || role === 'app' || role === 'designed-lib')) {
         reportMissingDesignAnnotation(projectName, role);
         return true;
     }

package/src/executors/di-graph-generate/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/di-graph-generate/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * DI Graph Generate Executor\n *\n * Per-project: statically analyzes the project's Inversify dependency DAG\n * (constructor injection from controllers — or library top-of-DAG classes —\n * down to leaves) and writes three checked-in files at the project root:\n *\n *   design.json — machine-readable graph (deterministic, sorted)\n *   design.md   — Mermaid diagram rendered by GitHub/IDEs in PRs\n *   design.html — clickable viz.js page (linked from architecture/dependencies.html)\n *\n * Runs on every build (cache:false; the build gates on\n * validate-di-graph-unchanged which dependsOn this target). Unrecognized DI\n * patterns become \"unresolved\" nodes rather than failing the build.\n *\n * Config (webpieces.config.json, rule key `di-graph`): mode RUN_EVERY_TIME | OFF.\n *\n * Usage: nx run <project>:di-graph-generate\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { loadAndValidate, ResolvedConfig } from '@webpieces/rules-config';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport {\n    DiAnalyzer,\n    frameworkTags,\n    explicitRoleTag,\n    FrameworkMarkers,\n    selectAnalyzer,\n} from '../../lib/di-graph/analyzer-strategy';\nimport { createProjectProgram } from '../../lib/di-graph/program';\nimport { toDesignJson } from '../../lib/di-graph/serializer';\nimport { toDesignMarkdown } from '../../lib/di-graph/mermaid';\nimport { generateDesignHTML } from '../../lib/di-graph/design-visualizer';\nimport { DiDesign, DiGraph } from '../../lib/di-graph/model';\nimport { toError } from '../../toError';\n\nexport interface DiGraphGenerateOptions {\n    // No options here — config comes from webpieces.config.json at runtime.\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nconst RULE_NAME = 'di-graph';\nconst MISSING_DESIGN_RULE_NAME = 'missing-design-annotation';\n\n// Cheap substring pre-scan: a project whose source never mentions any DI marker\n// gets an empty graph without paying for a ts.Program. Angular markers\n// (@Component/bootstrapApplication) are included so an Angular app that uses no\n// Inversify decorator isn't short-circuited to empty.\nconst DI_MARKERS = [\n    '@DocumentDesign(',\n    '@provideSingleton',\n    '@provideFrameworkSingleton',\n    '@provideTransient',\n    '@injectable',\n    'new ContainerModule',\n    '@inject(',\n    '@Component(',\n    'bootstrapApplication',\n];\n\nconst ANGULAR_MARKERS = ['@Component(', 'bootstrapApplication'];\n// A non-Angular DI-design root. When no role tag is set, its presence steers the\n// marker-fallback toward the Inversify analyzer (server/controller mode).\nconst DESIGN_ROOT_MARKER = '@DocumentDesign(';\n\n/** Recursively read every project .ts file, folding each into `visit`. */\nfunction forEachSourceFile(dir: string, visit: (content: string) => void): void {\n    if (!fs.existsSync(dir)) return;\n    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {\n        const full = path.join(dir, entry.name);\n        if (entry.isDirectory()) {\n            if (entry.name === 'node_modules' || entry.name === 'dist') continue;\n            forEachSourceFile(full, visit);\n        } else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {\n            visit(fs.readFileSync(full, 'utf-8'));\n        }\n    }\n}\n\nfunction sourceHasDiMarkers(dir: string): boolean {\n    let found = false;\n    forEachSourceFile(dir, (content: string) => {\n        if (!found && DI_MARKERS.some((marker: string) => content.includes(marker))) found = true;\n    });\n    return found;\n}\n\n/** Pre-scan a project's source for the framework markers used when no tag is set. */\nfunction detectFrameworkMarkers(dir: string): FrameworkMarkers {\n    let angular = false;\n    let controller = false;\n    forEachSourceFile(dir, (content: string) => {\n        if (!angular && ANGULAR_MARKERS.some((marker: string) => content.includes(marker))) angular = true;\n        if (!controller && content.includes(DESIGN_ROOT_MARKER)) controller = true;\n    });\n    return new FrameworkMarkers(angular, controller);\n}\n\n/**\n * Repo-relative back link from a project's committed design.html up to\n * architecture/dependencies.html, so a reader who clicked a box in the\n * architecture graph can click back out. E.g. 'packages/http/http-api' →\n * '../../../architecture/dependencies.html'.\n */\nfunction architectureBackHref(projectRoot: string): string {\n    return path.posix.relative(projectRoot.replace(/\\\\/g, '/'), 'architecture/dependencies.html');\n}\n\nfunction writeDesignFiles(projectRootAbs: string, projectRoot: string, graph: DiGraph): void {\n    // toDesignJson sorts the graph in place, so design.md/design.html below all\n    // see the same deterministic ordering (no git churn on re-run).\n    fs.writeFileSync(path.join(projectRootAbs, 'design.json'), toDesignJson(graph));\n    fs.writeFileSync(path.join(projectRootAbs, 'design.md'), toDesignMarkdown(graph));\n    fs.writeFileSync(\n        path.join(projectRootAbs, 'design.html'),\n        generateDesignHTML(graph, architectureBackHref(projectRoot)),\n    );\n}\n\n/** The analyzer chosen for a project plus the role tag that drove the choice. */\nclass AnalyzerChoice {\n    constructor(\n        public readonly analyzer: DiAnalyzer,\n        public readonly role: string | null,\n    ) {}\n}\n\n/**\n * Select the analyzer by role (server & designed-lib → @DocumentDesign,\n * client→angular design, lib→skip). The explicit `role:` nx tag is the source of\n * truth; when absent we fall back to the legacy `framework:` selection + marker\n * pre-scan so designs stay identical until a project is retagged.\n */\nfunction chooseAnalyzer(tags: string[], srcDir: string): AnalyzerChoice {\n    const role = explicitRoleTag(tags);\n    const frameworks = frameworkTags(tags);\n    const analyzer = selectAnalyzer(role, frameworks, detectFrameworkMarkers(srcDir));\n    console.log(\n        `   Analyzer: ${analyzer.constructor.name} ` +\n            `(role tag: ${role ?? 'none'}, framework tags: ${frameworks.length > 0 ? frameworks.join(', ') : 'none'})`,\n    );\n    return new AnalyzerChoice(analyzer, role);\n}\n\n/**\n * A server/designed-lib project that produced no design (zero @DocumentDesign\n * roots) fails the build with role-specific guidance. Enforced under the\n * `missing-design-annotation` rule.\n */\nfunction reportMissingDesignAnnotation(projectName: string, role: string): void {\n    if (role === 'server') {\n        console.error(\n            `❌ ${projectName} is tagged role:server but has no @DocumentDesign class.\\n` +\n                `   All controllers should be annotated with @DocumentDesign() ` +\n                `(from @webpieces/http-routing) so their design.json / design.html get generated\\n` +\n                `   and linked from architecture/dependencies.html.`,\n        );\n        return;\n    }\n    console.error(\n        `❌ ${projectName} is tagged role:designed-lib but has no @DocumentDesign class.\\n` +\n            `   One or more classes you want a design printed for need @DocumentDesign() ` +\n            `(from @webpieces/http-routing) added —\\n` +\n            `   or retag the project role:lib if it has no design.`,\n    );\n}\n\n/**\n * A server/designed-lib project MUST expose at least one @DocumentDesign root,\n * else its design is empty and the role is meaningless. Returns true (and reports)\n * when the build should fail. The `missing-design-annotation` rule gates it:\n * absent (an older published config) → enforce; OFF → skip.\n */\nfunction failsMissingDesignAnnotation(\n    shared: ResolvedConfig,\n    role: string | null,\n    graph: DiGraph,\n    projectName: string,\n): boolean {\n    const missingRule = shared.rules.get(MISSING_DESIGN_RULE_NAME);\n    const enforce = !missingRule || !missingRule.isOff;\n    if (enforce && graph.designs.length === 0 && (role === 'server' || role === 'designed-lib')) {\n        reportMissingDesignAnnotation(projectName, role);\n        return true;\n    }\n    return false;\n}\n\nexport default async function runExecutor(\n    _options: DiGraphGenerateOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const shared = loadAndValidate(context.root).resolved;\n    const rule = shared.rules.get(RULE_NAME);\n    if (rule && rule.isOff) {\n        console.log(`\\n⏭️  Skipping ${RULE_NAME} generation (mode: OFF)\\n`);\n        return { success: true };\n    }\n\n    const projectName = context.projectName ?? 'project';\n    const projectConfig = context.projectsConfigurations?.projects[projectName];\n    const projectRoot = projectConfig?.root ?? '.';\n    const projectRootAbs = path.join(context.root, projectRoot);\n    const srcDir = path.join(projectRootAbs, 'src');\n\n    console.log(`\\n🧬 Generating DI design graph for ${projectName}\\n`);\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- chokepoint: a generator crash must produce an actionable failure, not a stack trace mid-build\n    try {\n        if (!sourceHasDiMarkers(srcDir)) {\n            console.log('   No DI markers found — writing empty design graph');\n            writeDesignFiles(projectRootAbs, projectRoot, new DiGraph(projectName));\n            return { success: true };\n        }\n\n        const program = createProjectProgram(projectRootAbs);\n        if (!program) {\n            console.log('   No usable tsconfig/source — writing empty design graph');\n            writeDesignFiles(projectRootAbs, projectRoot, new DiGraph(projectName));\n            return { success: true };\n        }\n\n        const choice = chooseAnalyzer(projectConfig?.tags ?? [], srcDir);\n        const graph = choice.analyzer.analyzeProject(program, context.root, projectRoot, projectName);\n\n        if (failsMissingDesignAnnotation(shared, choice.role, graph, projectName)) {\n            return { success: false };\n        }\n\n        writeDesignFiles(projectRootAbs, projectRoot, graph);\n\n        const nodeCount = graph.designs.reduce((sum: number, d: DiDesign) => sum + d.nodes.length, 0);\n        const edgeCount = graph.designs.reduce((sum: number, d: DiDesign) => sum + d.edges.length, 0);\n        console.log(\n            `✅ Wrote ${projectRoot}/design.json + design.md + design.html ` +\n                `(${graph.designs.length} design(s), ${nodeCount} node(s), ${edgeCount} edge(s))`,\n        );\n        const unresolved = [...new Set(graph.designs.flatMap((d: DiDesign) => d.unresolved))];\n        if (unresolved.length > 0) {\n            console.warn(`⚠️  ${unresolved.length} unresolved token(s)/type(s): ${unresolved.join(', ')}`);\n        }\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error(`❌ DI graph generation failed for ${projectName}: ${error.message}`);\n        console.error(`   To unblock builds, set rules[\"${RULE_NAME}\"].mode=\"OFF\" in webpieces.config.json.`);\n        return { success: false };\n    }\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/di-graph-generate/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * DI Graph Generate Executor\n *\n * Per-project: statically analyzes the project's Inversify dependency DAG\n * (constructor injection from controllers — or library top-of-DAG classes —\n * down to leaves) and writes three checked-in files at the project root:\n *\n *   design.json — machine-readable graph (deterministic, sorted)\n *   design.md   — Mermaid diagram rendered by GitHub/IDEs in PRs\n *   design.html — clickable viz.js page (linked from architecture/dependencies.html)\n *\n * Runs on every build (cache:false; the build gates on\n * validate-di-graph-unchanged which dependsOn this target). Unrecognized DI\n * patterns become \"unresolved\" nodes rather than failing the build.\n *\n * Config (webpieces.config.json, rule key `di-graph`): mode RUN_EVERY_TIME | OFF.\n *\n * Usage: nx run <project>:di-graph-generate\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { loadAndValidate, ResolvedConfig } from '@webpieces/rules-config';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport {\n    DiAnalyzer,\n    frameworkTags,\n    explicitRoleTag,\n    FrameworkMarkers,\n    selectAnalyzer,\n} from '../../lib/di-graph/analyzer-strategy';\nimport { createProjectProgram } from '../../lib/di-graph/program';\nimport { toDesignJson } from '../../lib/di-graph/serializer';\nimport { toDesignMarkdown } from '../../lib/di-graph/mermaid';\nimport { generateDesignHTML } from '../../lib/di-graph/design-visualizer';\nimport { DiDesign, DiGraph } from '../../lib/di-graph/model';\nimport { toError } from '../../toError';\n\nexport interface DiGraphGenerateOptions {\n    // No options here — config comes from webpieces.config.json at runtime.\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nconst RULE_NAME = 'di-graph';\nconst MISSING_DESIGN_RULE_NAME = 'missing-design-annotation';\n\n// Cheap substring pre-scan: a project whose source never mentions any DI marker\n// gets an empty graph without paying for a ts.Program. Angular markers\n// (@Component/bootstrapApplication) are included so an Angular app that uses no\n// Inversify decorator isn't short-circuited to empty.\nconst DI_MARKERS = [\n    '@DocumentDesign(',\n    '@provideSingleton',\n    '@provideFrameworkSingleton',\n    '@provideTransient',\n    '@injectable',\n    'new ContainerModule',\n    '@inject(',\n    '@Component(',\n    'bootstrapApplication',\n];\n\nconst ANGULAR_MARKERS = ['@Component(', 'bootstrapApplication'];\n// A non-Angular DI-design root. When no role tag is set, its presence steers the\n// marker-fallback toward the Inversify analyzer (server/controller mode).\nconst DESIGN_ROOT_MARKER = '@DocumentDesign(';\n\n/** Recursively read every project .ts file, folding each into `visit`. */\nfunction forEachSourceFile(dir: string, visit: (content: string) => void): void {\n    if (!fs.existsSync(dir)) return;\n    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {\n        const full = path.join(dir, entry.name);\n        if (entry.isDirectory()) {\n            if (entry.name === 'node_modules' || entry.name === 'dist') continue;\n            forEachSourceFile(full, visit);\n        } else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {\n            visit(fs.readFileSync(full, 'utf-8'));\n        }\n    }\n}\n\nfunction sourceHasDiMarkers(dir: string): boolean {\n    let found = false;\n    forEachSourceFile(dir, (content: string) => {\n        if (!found && DI_MARKERS.some((marker: string) => content.includes(marker))) found = true;\n    });\n    return found;\n}\n\n/** Pre-scan a project's source for the framework markers used when no tag is set. */\nfunction detectFrameworkMarkers(dir: string): FrameworkMarkers {\n    let angular = false;\n    let controller = false;\n    forEachSourceFile(dir, (content: string) => {\n        if (!angular && ANGULAR_MARKERS.some((marker: string) => content.includes(marker))) angular = true;\n        if (!controller && content.includes(DESIGN_ROOT_MARKER)) controller = true;\n    });\n    return new FrameworkMarkers(angular, controller);\n}\n\n/**\n * Repo-relative back link from a project's committed design.html up to\n * architecture/dependencies.html, so a reader who clicked a box in the\n * architecture graph can click back out. E.g. 'packages/http/http-api' →\n * '../../../architecture/dependencies.html'.\n */\nfunction architectureBackHref(projectRoot: string): string {\n    return path.posix.relative(projectRoot.replace(/\\\\/g, '/'), 'architecture/dependencies.html');\n}\n\nfunction writeDesignFiles(projectRootAbs: string, projectRoot: string, graph: DiGraph): void {\n    // toDesignJson sorts the graph in place, so design.md/design.html below all\n    // see the same deterministic ordering (no git churn on re-run).\n    fs.writeFileSync(path.join(projectRootAbs, 'design.json'), toDesignJson(graph));\n    fs.writeFileSync(path.join(projectRootAbs, 'design.md'), toDesignMarkdown(graph));\n    fs.writeFileSync(\n        path.join(projectRootAbs, 'design.html'),\n        generateDesignHTML(graph, architectureBackHref(projectRoot)),\n    );\n}\n\n/** The analyzer chosen for a project plus the role tag that drove the choice. */\nclass AnalyzerChoice {\n    constructor(\n        public readonly analyzer: DiAnalyzer,\n        public readonly role: string | null,\n    ) {}\n}\n\n/**\n * Select the analyzer by role (server & designed-lib → @DocumentDesign,\n * client→angular design, lib→skip). The explicit `role:` nx tag is the source of\n * truth; when absent we fall back to the legacy `framework:` selection + marker\n * pre-scan so designs stay identical until a project is retagged.\n */\nfunction chooseAnalyzer(tags: string[], srcDir: string): AnalyzerChoice {\n    const role = explicitRoleTag(tags);\n    const frameworks = frameworkTags(tags);\n    const analyzer = selectAnalyzer(role, frameworks, detectFrameworkMarkers(srcDir));\n    console.log(\n        `   Analyzer: ${analyzer.constructor.name} ` +\n            `(role tag: ${role ?? 'none'}, framework tags: ${frameworks.length > 0 ? frameworks.join(', ') : 'none'})`,\n    );\n    return new AnalyzerChoice(analyzer, role);\n}\n\n/**\n * A server/designed-lib project that produced no design (zero @DocumentDesign\n * roots) fails the build with role-specific guidance. Enforced under the\n * `missing-design-annotation` rule.\n */\nfunction reportMissingDesignAnnotation(projectName: string, role: string): void {\n    if (role === 'server' || role === 'app') {\n        console.error(\n            `❌ ${projectName} is tagged role:${role} but has no @DocumentDesign class.\\n` +\n                `   A role:${role} project must expose one @DocumentDesign() root class (the App the ` +\n                `container resolves via container.get(XxxApp)) so its design.json / design.html get\\n` +\n                `   generated and linked from architecture/dependencies.html.`,\n        );\n        return;\n    }\n    console.error(\n        `❌ ${projectName} is tagged role:designed-lib but has no @DocumentDesign class.\\n` +\n            `   One or more classes you want a design printed for need @DocumentDesign() ` +\n            `(from @webpieces/http-routing) added —\\n` +\n            `   or retag the project role:lib if it has no design.`,\n    );\n}\n\n/**\n * A server/designed-lib project MUST expose at least one @DocumentDesign root,\n * else its design is empty and the role is meaningless. Returns true (and reports)\n * when the build should fail. The `missing-design-annotation` rule gates it:\n * absent (an older published config) → enforce; OFF → skip.\n */\nfunction failsMissingDesignAnnotation(\n    shared: ResolvedConfig,\n    role: string | null,\n    graph: DiGraph,\n    projectName: string,\n): boolean {\n    const missingRule = shared.rules.get(MISSING_DESIGN_RULE_NAME);\n    const enforce = !missingRule || !missingRule.isOff;\n    if (enforce && graph.designs.length === 0 && (role === 'server' || role === 'app' || role === 'designed-lib')) {\n        reportMissingDesignAnnotation(projectName, role);\n        return true;\n    }\n    return false;\n}\n\nexport default async function runExecutor(\n    _options: DiGraphGenerateOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const shared = loadAndValidate(context.root).resolved;\n    const rule = shared.rules.get(RULE_NAME);\n    if (rule && rule.isOff) {\n        console.log(`\\n⏭️  Skipping ${RULE_NAME} generation (mode: OFF)\\n`);\n        return { success: true };\n    }\n\n    const projectName = context.projectName ?? 'project';\n    const projectConfig = context.projectsConfigurations?.projects[projectName];\n    const projectRoot = projectConfig?.root ?? '.';\n    const projectRootAbs = path.join(context.root, projectRoot);\n    const srcDir = path.join(projectRootAbs, 'src');\n\n    console.log(`\\n🧬 Generating DI design graph for ${projectName}\\n`);\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- chokepoint: a generator crash must produce an actionable failure, not a stack trace mid-build\n    try {\n        if (!sourceHasDiMarkers(srcDir)) {\n            console.log('   No DI markers found — writing empty design graph');\n            writeDesignFiles(projectRootAbs, projectRoot, new DiGraph(projectName));\n            return { success: true };\n        }\n\n        const program = createProjectProgram(projectRootAbs);\n        if (!program) {\n            console.log('   No usable tsconfig/source — writing empty design graph');\n            writeDesignFiles(projectRootAbs, projectRoot, new DiGraph(projectName));\n            return { success: true };\n        }\n\n        const choice = chooseAnalyzer(projectConfig?.tags ?? [], srcDir);\n        const graph = choice.analyzer.analyzeProject(program, context.root, projectRoot, projectName);\n\n        if (failsMissingDesignAnnotation(shared, choice.role, graph, projectName)) {\n            return { success: false };\n        }\n\n        writeDesignFiles(projectRootAbs, projectRoot, graph);\n\n        const nodeCount = graph.designs.reduce((sum: number, d: DiDesign) => sum + d.nodes.length, 0);\n        const edgeCount = graph.designs.reduce((sum: number, d: DiDesign) => sum + d.edges.length, 0);\n        console.log(\n            `✅ Wrote ${projectRoot}/design.json + design.md + design.html ` +\n                `(${graph.designs.length} design(s), ${nodeCount} node(s), ${edgeCount} edge(s))`,\n        );\n        const unresolved = [...new Set(graph.designs.flatMap((d: DiDesign) => d.unresolved))];\n        if (unresolved.length > 0) {\n            console.warn(`⚠️  ${unresolved.length} unresolved token(s)/type(s): ${unresolved.join(', ')}`);\n        }\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error(`❌ DI graph generation failed for ${projectName}: ${error.message}`);\n        console.error(`   To unblock builds, set rules[\"${RULE_NAME}\"].mode=\"OFF\" in webpieces.config.json.`);\n        return { success: false };\n    }\n}\n"]}

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

@@ -60,6 +60,9 @@ export declare function explicitRoleTag(tags: readonly string[]): string | null;
  * fallback keeps pre-retag designs identical).
  *
  *  - `server`       → Inversify, roots on `@DocumentDesign` (controller kind)
+ *  - `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.
  *  - `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

@@ -105,6 +105,9 @@ function explicitRoleTag(tags) {
  * fallback keeps pre-retag designs identical).
  *
  *  - `server`       → Inversify, roots on `@DocumentDesign` (controller kind)
+ *  - `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.
  *  - `designed-lib` → Inversify, roots on `@DocumentDesign` (apiImplementation kind)
  *  - `client`       → Angular design for angular apps; otherwise skip
  *  - `lib`          → skip (plain libraries get no design)
@@ -114,6 +117,8 @@ function explicitRoleTag(tags) {
 function selectAnalyzer(role, frameworks, markers) {
     if (role === 'server')
         return new InversifyAnalyzer('controller');
+    if (role === 'app')
+        return new InversifyAnalyzer('controller');
     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 *  - `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 === '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 *  - `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"]}

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

@@ -35,9 +35,9 @@ export declare function collectProjectInfo(): Promise<Map<string, ProjectInfo>>;
  */
 export declare function enrichGraph(graph: EnhancedGraph, infos: Map<string, ProjectInfo>, workspaceRoot: string): void;
 /**
- * Roles that are terminal APPS — nothing may depend on them. A server or a
- * client is a top-level runnable; being depended upon means it is really a
- * library and should be retagged `role:lib`/`role:designed-lib`.
+ * Roles that are terminal APPS — nothing may depend on them. A server, a
+ * non-HTTP `app`, or a client is a top-level runnable; being depended upon means
+ * it is really a library and should be retagged `role:lib`/`role:designed-lib`.
  */
 export declare const APP_ROLES: ReadonlyArray<string>;
 /**

package/src/lib/graph-metadata.js

@@ -109,11 +109,11 @@ function enrichGraph(graph, infos, workspaceRoot) {
     }
 }
 /**
- * Roles that are terminal APPS — nothing may depend on them. A server or a
- * client is a top-level runnable; being depended upon means it is really a
- * library and should be retagged `role:lib`/`role:designed-lib`.
+ * Roles that are terminal APPS — nothing may depend on them. A server, a
+ * non-HTTP `app`, or a client is a top-level runnable; being depended upon means
+ * it is really a library and should be retagged `role:lib`/`role:designed-lib`.
  */
-exports.APP_ROLES = ['server', 'client'];
+exports.APP_ROLES = ['server', 'app', 'client'];
 /**
  * Compatibility lattice — the "up-set" of each atomic env is the env itself
  * PLUS every ancestor it can legally consume code from (specialization edges

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 or a\n * client is a top-level runnable; being depended upon means it is really a\n * library and should be retagged `role:lib`/`role:designed-lib`.\n */\nexport const APP_ROLES: ReadonlyArray<string> = ['server', 'client'];\n\n/**\n * Compatibility lattice — the \"up-set\" of each atomic env is the env itself\n * PLUS every ancestor it can legally consume code from (specialization edges\n * child → parent: react → browser, angular → browser, express → node). A\n * consumer promising env `c` can be satisfied by any dependency env in `up(c)`.\n */\nexport const ENV_UP_SETS: Readonly<Record<string, ReadonlyArray<string>>> = {\n    react: ['react', 'browser'],\n    angular: ['angular', 'browser'],\n    browser: ['browser'],\n    express: ['express', 'node'],\n    node: ['node'],\n};\n\n/** The up-set of an env (env itself + ancestors); unknown envs map to just themselves. */\nfunction upSet(env: string): ReadonlyArray<string> {\n    return ENV_UP_SETS[env] ?? [env];\n}\n\n/**\n * `library-types-match-client` rule.\n *\n * A project's `framework` field is its libType — the SET of runtime\n * environments it is validated to run in (browser | react | angular | node |\n * express). For a dependency edge Consumer C → Library L, the edge is LEGAL iff\n * for EVERY env `c` in C's set, up(c) ∩ L's set ≠ ∅ — i.e. every environment\n * the consumer promises to run in can be satisfied by the dependency. This keeps\n * an express app from depending on a browser-only lib, and lets a `browser+node`\n * lib be consumed by both react and express projects. Every violation is\n * appended to `problems` so `arch:generate` fails with the full list.\n */\nexport function validateLibraryTypesMatch(graph: EnhancedGraph, problems: string[]): void {\n    for (const [projectName, entry] of Object.entries(graph)) {\n        const fromSet = entry.framework;\n        if (fromSet === undefined) continue; // framework resolution already flagged this project\n\n        for (const dep of entry.dependsOn) {\n            const depEntry = graph[dep];\n            const toSet = depEntry?.framework;\n            if (toSet === undefined) continue;\n\n            const unsatisfied = fromSet.filter(\n                (env: string) => !upSet(env).some((up: string) => toSet.includes(up))\n            );\n            if (unsatisfied.length === 0) continue;\n\n            problems.push(\n                `library-types-match-client: '${projectName}' [${fromSet.join(', ')}] must not depend on ` +\n                    `'${dep}' [${toSet.join(', ')}] — the consumer env(s) ${unsatisfied.join(', ')} cannot be ` +\n                    `satisfied by the dependency (each consumer env must resolve to itself or an ancestor it ` +\n                    `consumes from: react/angular→browser, express→node). Widen '${dep}' framework tags or ` +\n                    `remove the dependency.`\n            );\n        }\n    }\n}\n\n/**\n * `role-dependency` rule.\n *\n * A project's `role` is its function (server | designed-lib | lib | client).\n * Apps are terminal — libraries and clients consume them, never the reverse:\n *   - a `client` is fully terminal: NOTHING may depend on it.\n *   - a `server` may only be depended upon by another `server` — the one\n *     legitimate case is a server-side orchestrator/e2e harness that boots\n *     other servers. A `lib`/`designed-lib`/`client` depending on a `server`\n *     inverts the dependency direction and is a violation.\n */\nexport function validateRoleDependencies(graph: EnhancedGraph, problems: string[]): void {\n    for (const [projectName, entry] of Object.entries(graph)) {\n        const fromRole = entry.role;\n        for (const dep of entry.dependsOn) {\n            const toRole = graph[dep]?.role;\n            if (toRole === undefined) continue; // role resolution already flagged this project\n            if (!APP_ROLES.includes(toRole)) continue;\n            // A server may orchestrate/boot other servers (e.g. an e2e harness).\n            if (toRole === 'server' && fromRole === 'server') continue;\n\n            const why =\n                toRole === 'client'\n                    ? `a 'client' app is terminal and may never be depended upon`\n                    : `a 'server' may only be depended upon by another 'server' (an orchestrator/e2e harness)`;\n            problems.push(\n                `role-dependency: '${projectName}' (role:${fromRole ?? 'none'}) must not depend on ` +\n                    `'${dep}' (role:${toRole}) — ${why}. Retag '${dep}' role:lib/role:designed-lib if it ` +\n                    `is actually a library, or remove the dependency.`\n            );\n        }\n    }\n}\n\nfunction enrichResponsibilities(\n    entry: EnhancedGraph[string],\n    info: ProjectInfo,\n    workspaceRoot: string,\n    problems: string[]\n): void {\n    const responsibilitiesFile = toRepoRelative(info.root, RESPONSIBILITIES_FILE_NAME);\n    entry.responsibilitiesFile = responsibilitiesFile;\n\n    const absolutePath = path.join(workspaceRoot, info.root, RESPONSIBILITIES_FILE_NAME);\n    if (!fs.existsSync(absolutePath)) {\n        problems.push(\n            `${info.name}: missing required ${responsibilitiesFile} — create it with a heading, ` +\n                `one short summary paragraph, then the full responsibilities of the module`\n        );\n        return;\n    }\n\n    const summary = extractShortDescription(fs.readFileSync(absolutePath, 'utf-8'));\n    const summaryProblem = validateShortDescription(summary, responsibilitiesFile);\n    if (summaryProblem !== null) {\n        problems.push(`${info.name}: ${summaryProblem}`);\n        return;\n    }\n    entry.shortDescription = summary;\n}\n\n/**\n * Repo-relative path with forward slashes (stable across platforms in the\n * committed JSON).\n */\nfunction toRepoRelative(projectRoot: string, fileName: string): string {\n    return [projectRoot.replace(/\\\\/g, '/').replace(/\\/+$/, ''), fileName].join('/');\n}\n\n/**\n * True when the project has a REAL generated DI design — a committed design.json\n * whose `designs[]` is non-empty (i.e. it has ≥1 @DocumentDesign root). Plain\n * libs get a `{ designs: [] }` file written, which must read as \"no design\" so\n * the arch viz does not render them as clickable. A missing/unparseable file is\n * treated as \"no design\".\n */\nfunction hasGeneratedDesign(workspaceRoot: string, projectRoot: string): boolean {\n    const designPath = path.join(workspaceRoot, projectRoot, 'design.json');\n    if (!fs.existsSync(designPath)) return false;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const parsed = JSON.parse(fs.readFileSync(designPath, 'utf-8'));\n        return Array.isArray(parsed.designs) && parsed.designs.length > 0;\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.warn(`⚠️  Skipping unparseable ${designPath}: ${error.message}`);\n        return false;\n    }\n}\n"]}
+{"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"]}

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

@@ -6,6 +6,9 @@
  * `framework` (libType). Known values:
  *
  *   - `server`       — a runnable server app; DI design roots on `@DocumentDesign`.
+ *   - `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.
  *   - `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

@@ -7,6 +7,9 @@
  * `framework` (libType). Known values:
  *
  *   - `server`       — a runnable server app; DI design roots on `@DocumentDesign`.
+ *   - `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.
  *   - `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.
@@ -28,7 +31,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', 'designed-lib', 'lib', 'client', 'api-lib'];
+exports.KNOWN_ROLES = ['server', 'app', '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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;;;AAqBH,kCAmBC;AApCY,QAAA,eAAe,GAAG,OAAO,CAAC;AAEvC,0EAA0E;AAC7D,QAAA,WAAW,GAA0B,CAAC,QAAQ,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;AAEzG,+DAA+D;AAClD,QAAA,YAAY,GAAG,KAAK,CAAC;AAElC,MAAa,cAAc;IAGH;IAEA;IAJpB;IACI,yDAAyD;IACzC,IAAmB;IACnC,iEAAiE;IACjD,OAAsB;QAFtB,SAAI,GAAJ,IAAI,CAAe;QAEnB,YAAO,GAAP,OAAO,CAAe;IACvC,CAAC;CACP;AAPD,wCAOC;AAED,SAAgB,WAAW,CAAC,IAAiB;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI;SACtB,MAAM,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,uBAAe,CAAC,CAAC;SACxD,GAAG,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,uBAAe,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAEpE,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,IAAI,cAAc,CACrB,IAAI,EACJ,GAAG,IAAI,CAAC,IAAI,SAAS,SAAS,CAAC,MAAM,kBAAkB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,qCAAqC,CACnH,CAAC;IACN,CAAC;IACD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,IAAI,cAAc,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,IAAI,kCAAkC,CAAC,CAAC;QACpF,CAAC;QACD,OAAO,IAAI,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAClD,CAAC;IAED,OAAO,IAAI,cAAc,CAAC,oBAAY,EAAE,IAAI,CAAC,CAAC;AAClD,CAAC","sourcesContent":["/**\n * Role Resolver\n *\n * Determines the `role` field written per project into\n * architecture/dependencies.json — a project's ROLE, orthogonal to its\n * `framework` (libType). Known values:\n *\n *   - `server`       — a runnable server app; DI design roots on `@DocumentDesign`.\n *   - `designed-lib` — a library whose DI design we generate; roots on\n *                      `@DocumentDesign` (required to have ≥1).\n *   - `lib`          — a plain library; no DI design is generated.\n *   - `client`       — a client app (e.g. angular-site); angular apps keep their\n *                      component/route design, others get none.\n *   - `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', '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;;;;;;;;;;;;;;;;;;;;;;;;;;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"]}

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

@@ -1 +1 @@
-{"version":3,"file":"runtime-graph.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-graph.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Runtime Graph\n *\n * Derives the runtime microservice graph SOLELY from architecture/dependencies.json\n * (the single source of truth): each project's `apiRelations` carry which api\n * classes it implements/uses and their transport (rpc | pubsub). Both\n * `architecture:generate` and `architecture:validate-runtime-architecture` call\n * the SAME `deriveRuntimeGraph`, so the committed graph and the validated graph\n * can never diverge.\n *\n * The runtime edge Z -> X (Z depends on X at runtime) is INFERRED: Z `uses` api\n * Y and X `implements` api Y. This edge does not exist in the compile-time\n * dependencies.json (both Z and X only compile-depend on the api library Y).\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { sortGraphTopologically } from './graph-sorter';\nimport type { EnhancedGraph } from './graph-sorter';\nimport type { ApiRef, ApiTransport } from './api-usage/api-relations';\nimport { sortApiRefs } from './api-usage/api-relations';\nimport { toError } from '../toError';\n\nexport const DEFAULT_RUNTIME_GRAPH_PATH = 'architecture/runtime-dependencies.json';\n\nexport interface RuntimeService {\n    level: number;\n    implements: string[];\n    uses: string[];\n    dependsOn: string[];\n    /**\n     * When false, this service is hidden from the rendered runtime graph (its\n     * node AND every edge touching it are omitted from the HTML/DOT). It stays\n     * in runtime-dependencies.json so the data view is complete. Absent means\n     * drawn (the default). Mirrors GraphEntry.drawOnGraph from the `drawOnGraph:`\n     * nx tag.\n     */\n    drawOnGraph?: boolean;\n}\n\nexport interface RuntimeApi {\n    implementedBy: string[];\n    usedBy: string[];\n    /** Transport of this API — 'rpc' (direct call) or 'pubsub' (delivered through a queue). */\n    type?: ApiTransport;\n}\n\nexport interface RuntimeEdge {\n    from: string;\n    to: string;\n    via: string[];\n    /**\n     * Transport of this edge. 'rpc' → a direct call arrow. 'pubsub' → the producer enqueues and the\n     * consumer is delivered later, so the runtime viz draws it as producer → QUEUE → consumer.\n     * Edges are split by transport, so every edge is a single kind.\n     */\n    type?: ApiTransport;\n}\n\nexport interface RuntimeUnresolved {\n    service: string;\n    api: string;\n}\n\nexport interface RuntimeGraph {\n    services: Record<string, RuntimeService>;\n    apis: Record<string, RuntimeApi>;\n    runtimeEdges: RuntimeEdge[];\n    unresolvedUses: RuntimeUnresolved[];\n}\n\ninterface EdgeResult {\n    edges: RuntimeEdge[];\n    unresolved: RuntimeUnresolved[];\n}\n\n/** Adjacency (service -> [targets]) used for leveling + cycle checks. */\nfunction adjacencyFromEdges(serviceNames: string[], edges: RuntimeEdge[]): Record<string, string[]> {\n    const adj: Record<string, string[]> = {};\n    for (const name of serviceNames) adj[name] = [];\n    for (const edge of edges) {\n        if (!adj[edge.from]) adj[edge.from] = [];\n        adj[edge.from].push(edge.to);\n    }\n    return adj;\n}\n\n/** Adjacency (service -> [targets]) from a loaded runtime graph. */\nexport function runtimeAdjacency(graph: RuntimeGraph): Record<string, string[]> {\n    return adjacencyFromEdges(Object.keys(graph.services), graph.runtimeEdges);\n}\n\n/** Assign levels via topological sort; falls back to level 0 when a cycle exists. */\nfunction assignLevels(adjacency: Record<string, string[]>): Record<string, number> {\n    const levels: Record<string, number> = {};\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const sorted = sortGraphTopologically(adjacency);\n        for (const name of Object.keys(sorted)) levels[name] = sorted[name].level;\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error;\n        for (const name of Object.keys(adjacency)) levels[name] = 0;\n    }\n    return levels;\n}\n\n/** One project's implements/uses at api-CLASS granularity, from dependencies.json apiRelations. */\ninterface ScanDecl {\n    name: string;\n    implementsApis: ApiRef[];\n    usesApis: ApiRef[];\n}\n\n/**\n * Derives the runtime microservice graph from architecture/dependencies.json `apiRelations`:\n * implementers × users per API, split by transport. An rpc edge is a direct call; a pubsub edge flows\n * through a queue (drawn producer → queue → consumer by the visualizer).\n */\nclass RuntimeGraphDeriver {\n    constructor(\n        private readonly projects: EnhancedGraph,\n        /** Project names tagged drawOnGraph:false — kept in the JSON but flagged so the viz omits them. */\n        private readonly hiddenProjects: Set<string>\n    ) {}\n\n    assemble(): RuntimeGraph {\n        const decls = this.collectDecls();\n        const apis = this.buildApis(decls);\n        const edgeResult = this.buildEdges(decls, apis);\n        const services = this.buildServices(decls, edgeResult.edges);\n        const apisObj: Record<string, RuntimeApi> = {};\n        for (const api of Array.from(apis.keys()).sort()) apisObj[api] = apis.get(api)!;\n        return { services, apis: apisObj, runtimeEdges: edgeResult.edges, unresolvedUses: edgeResult.unresolved };\n    }\n\n    /** Flatten each project's api-lib relations into implements/uses ApiRef lists. */\n    private collectDecls(): ScanDecl[] {\n        const decls: ScanDecl[] = [];\n        for (const name of Object.keys(this.projects).sort()) {\n            const relations = this.projects[name].apiRelations;\n            if (relations === undefined) continue;\n            const implementsApis: ApiRef[] = [];\n            const usesApis: ApiRef[] = [];\n            for (const owner of Object.keys(relations)) {\n                implementsApis.push(...relations[owner].implements);\n                usesApis.push(...relations[owner].uses);\n            }\n            if (implementsApis.length > 0 || usesApis.length > 0) {\n                decls.push({ name, implementsApis: sortApiRefs(implementsApis), usesApis: sortApiRefs(usesApis) });\n            }\n        }\n        return decls;\n    }\n\n    /** apiClassName -> { implementedBy, usedBy, type }. */\n    private buildApis(decls: ScanDecl[]): Map<string, RuntimeApi> {\n        const apis = new Map<string, RuntimeApi>();\n        const ensure = (api: string, type: ApiTransport): RuntimeApi => {\n            let entry = apis.get(api);\n            if (!entry) {\n                entry = { implementedBy: [], usedBy: [], type };\n                apis.set(api, entry);\n            }\n            return entry;\n        };\n        for (const decl of decls) {\n            for (const ref of decl.implementsApis) ensure(ref.api, ref.type).implementedBy.push(decl.name);\n            for (const ref of decl.usesApis) ensure(ref.api, ref.type).usedBy.push(decl.name);\n        }\n        for (const entry of apis.values()) {\n            entry.implementedBy.sort();\n            entry.usedBy.sort();\n        }\n        return apis;\n    }\n\n    /** Inferred edges U -> I via api A, split by transport; plus uses with no implementer. */\n    private buildEdges(decls: ScanDecl[], apis: Map<string, RuntimeApi>): EdgeResult {\n        const viaByKey = new Map<string, Set<string>>();\n        const unresolved: RuntimeUnresolved[] = [];\n        for (const decl of decls) {\n            for (const ref of decl.usesApis) {\n                const implementers = apis.get(ref.api)?.implementedBy ?? [];\n                if (implementers.length === 0) {\n                    unresolved.push({ service: decl.name, api: ref.api });\n                    continue;\n                }\n                for (const target of implementers) {\n                    if (target === decl.name) continue;\n                    const key = `${decl.name}\u0000${target}\u0000${ref.type}`;\n                    if (!viaByKey.has(key)) viaByKey.set(key, new Set());\n                    viaByKey.get(key)!.add(ref.api);\n                }\n            }\n        }\n        return { edges: this.edgesFromKeys(viaByKey), unresolved: sortUnresolved(unresolved) };\n    }\n\n    private edgesFromKeys(viaByKey: Map<string, Set<string>>): RuntimeEdge[] {\n        const edges: RuntimeEdge[] = [];\n        for (const key of viaByKey.keys()) {\n            const parts = key.split('\u0000');\n            edges.push({ from: parts[0], to: parts[1], via: Array.from(viaByKey.get(key)!).sort(), type: parts[2] as ApiTransport });\n        }\n        edges.sort(\n            (a: RuntimeEdge, b: RuntimeEdge) =>\n                a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || (a.type ?? '').localeCompare(b.type ?? ''),\n        );\n        return edges;\n    }\n\n    private buildServices(decls: ScanDecl[], edges: RuntimeEdge[]): Record<string, RuntimeService> {\n        const services: Record<string, RuntimeService> = {};\n        for (const decl of decls) {\n            const dependsOn = Array.from(\n                new Set(edges.filter((e: RuntimeEdge) => e.from === decl.name).map((e: RuntimeEdge) => e.to)),\n            ).sort();\n            services[decl.name] = {\n                level: 0,\n                implements: decl.implementsApis.map((r: ApiRef) => r.api),\n                uses: decl.usesApis.map((r: ApiRef) => r.api),\n                dependsOn,\n            };\n            if (this.hiddenProjects.has(decl.name)) services[decl.name].drawOnGraph = false;\n        }\n        const levels = assignLevels(adjacencyFromEdges(Object.keys(services), edges));\n        for (const name of Object.keys(services)) services[name].level = levels[name] ?? 0;\n        return services;\n    }\n}\n\n/**\n * Derive the runtime graph from dependencies.json's project `apiRelations` — the\n * single source of truth shared by generate + validate. `hiddenProjects`\n * (drawOnGraph:false, defaults to none) are kept in the graph but flagged so the\n * runtime visualizer omits their nodes + edges.\n */\n// webpieces-disable no-function-outside-class -- module entry point for the runtime graph derivation\nexport function deriveRuntimeGraph(\n    projects: EnhancedGraph,\n    hiddenProjects: Set<string> = new Set<string>()\n): RuntimeGraph {\n    return new RuntimeGraphDeriver(projects, hiddenProjects).assemble();\n}\n\n// webpieces-disable no-function-outside-class -- pure sort helper, matches the sibling helpers in this file\nfunction sortUnresolved(unresolved: RuntimeUnresolved[]): RuntimeUnresolved[] {\n    return [...unresolved].sort(\n        (a: RuntimeUnresolved, b: RuntimeUnresolved) => a.service.localeCompare(b.service) || a.api.localeCompare(b.api),\n    );\n}\n\n/** Deterministic JSON (sorted keys + arrays already sorted during assembly). */\nfunction formatRuntimeJson(graph: RuntimeGraph): string {\n    return JSON.stringify(graph, null, 4) + '\\n';\n}\n\nexport function saveRuntimeGraph(\n    graph: RuntimeGraph,\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): void {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    const dir = path.dirname(fullPath);\n    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });\n    fs.writeFileSync(fullPath, formatRuntimeJson(graph), 'utf-8');\n}\n\nexport function runtimeGraphFileExists(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): boolean {\n    return fs.existsSync(path.join(workspaceRoot, graphPath));\n}\n\nexport function loadRuntimeGraph(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): RuntimeGraph | null {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    if (!fs.existsSync(fullPath)) return null;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        return JSON.parse(fs.readFileSync(fullPath, 'utf-8')) as RuntimeGraph;\n    } catch (err: unknown) {\n        const error = toError(err);\n        throw new Error(`Failed to load runtime graph from ${fullPath}`, { cause: error });\n    }\n}\n\n/** Serialize for an in-memory equality check (matches the on-disk format). */\nexport function serializeRuntimeGraph(graph: RuntimeGraph): string {\n    return formatRuntimeJson(graph);\n}\n"]}
+{"version":3,"file":"runtime-graph.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-graph.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Runtime Graph\n *\n * Derives the runtime microservice graph SOLELY from architecture/dependencies.json\n * (the single source of truth): each project's `apiRelations` carry which api\n * classes it implements/uses and their transport (rpc | pubsub). Both\n * `architecture:generate` and `architecture:validate-runtime-architecture` call\n * the SAME `deriveRuntimeGraph`, so the committed graph and the validated graph\n * can never diverge.\n *\n * The runtime edge Z -> X (Z depends on X at runtime) is INFERRED: Z `uses` api\n * Y and X `implements` api Y. This edge does not exist in the compile-time\n * dependencies.json (both Z and X only compile-depend on the api library Y).\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { sortGraphTopologically } from './graph-sorter';\nimport type { EnhancedGraph } from './graph-sorter';\nimport type { ApiRef, ApiTransport } from './api-usage/api-relations';\nimport { sortApiRefs } from './api-usage/api-relations';\nimport { toError } from '../toError';\n\nexport const DEFAULT_RUNTIME_GRAPH_PATH = 'architecture/runtime-dependencies.json';\n\nexport interface RuntimeService {\n    level: number;\n    implements: string[];\n    uses: string[];\n    dependsOn: string[];\n    /**\n     * When false, this service is hidden from the rendered runtime graph (its\n     * node AND every edge touching it are omitted from the HTML/DOT). It stays\n     * in runtime-dependencies.json so the data view is complete. Absent means\n     * drawn (the default). Mirrors GraphEntry.drawOnGraph from the `drawOnGraph:`\n     * nx tag.\n     */\n    drawOnGraph?: boolean;\n}\n\nexport interface RuntimeApi {\n    implementedBy: string[];\n    usedBy: string[];\n    /** Transport of this API — 'rpc' (direct call) or 'pubsub' (delivered through a queue). */\n    type?: ApiTransport;\n}\n\nexport interface RuntimeEdge {\n    from: string;\n    to: string;\n    via: string[];\n    /**\n     * Transport of this edge. 'rpc' → a direct call arrow. 'pubsub' → the producer enqueues and the\n     * consumer is delivered later, so the runtime viz draws it as producer → QUEUE → consumer.\n     * Edges are split by transport, so every edge is a single kind.\n     */\n    type?: ApiTransport;\n}\n\nexport interface RuntimeUnresolved {\n    service: string;\n    api: string;\n}\n\nexport interface RuntimeGraph {\n    services: Record<string, RuntimeService>;\n    apis: Record<string, RuntimeApi>;\n    runtimeEdges: RuntimeEdge[];\n    unresolvedUses: RuntimeUnresolved[];\n}\n\ninterface EdgeResult {\n    edges: RuntimeEdge[];\n    unresolved: RuntimeUnresolved[];\n}\n\n/** Adjacency (service -> [targets]) used for leveling + cycle checks. */\nfunction adjacencyFromEdges(serviceNames: string[], edges: RuntimeEdge[]): Record<string, string[]> {\n    const adj: Record<string, string[]> = {};\n    for (const name of serviceNames) adj[name] = [];\n    for (const edge of edges) {\n        if (!adj[edge.from]) adj[edge.from] = [];\n        adj[edge.from].push(edge.to);\n    }\n    return adj;\n}\n\n/** Adjacency (service -> [targets]) from a loaded runtime graph. */\nexport function runtimeAdjacency(graph: RuntimeGraph): Record<string, string[]> {\n    return adjacencyFromEdges(Object.keys(graph.services), graph.runtimeEdges);\n}\n\n/** Assign levels via topological sort; falls back to level 0 when a cycle exists. */\nfunction assignLevels(adjacency: Record<string, string[]>): Record<string, number> {\n    const levels: Record<string, number> = {};\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const sorted = sortGraphTopologically(adjacency);\n        for (const name of Object.keys(sorted)) levels[name] = sorted[name].level;\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error;\n        for (const name of Object.keys(adjacency)) levels[name] = 0;\n    }\n    return levels;\n}\n\n/** One project's implements/uses at api-CLASS granularity, from dependencies.json apiRelations. */\ninterface ScanDecl {\n    name: string;\n    implementsApis: ApiRef[];\n    usesApis: ApiRef[];\n}\n\n/**\n * Derives the runtime microservice graph from architecture/dependencies.json `apiRelations`:\n * implementers × users per API, split by transport. An rpc edge is a direct call; a pubsub edge flows\n * through a queue (drawn producer → queue → consumer by the visualizer).\n *\n * Nodes are the runnable apps only — role:server / role:client. A library is NEVER a node; its\n * implements/uses (a shared client-factory or route-registration lib) are attributed to the\n * servers/clients that embed it, walked transitively over dependsOn (see collectDecls).\n */\nclass RuntimeGraphDeriver {\n    constructor(\n        private readonly projects: EnhancedGraph,\n        /** Project names tagged drawOnGraph:false — kept in the JSON but flagged so the viz omits them. */\n        private readonly hiddenProjects: Set<string>\n    ) {}\n\n    assemble(): RuntimeGraph {\n        const decls = this.collectDecls();\n        const apis = this.buildApis(decls);\n        const edgeResult = this.buildEdges(decls, apis);\n        const services = this.buildServices(decls, edgeResult.edges);\n        const apisObj: Record<string, RuntimeApi> = {};\n        for (const api of Array.from(apis.keys()).sort()) apisObj[api] = apis.get(api)!;\n        return { services, apis: apisObj, runtimeEdges: edgeResult.edges, unresolvedUses: edgeResult.unresolved };\n    }\n\n    /**\n     * One ScanDecl per RUNTIME NODE (role:server / role:client). A node's effective\n     * relations are its OWN apiRelations PLUS those of every library in its transitive\n     * dependsOn closure: a lib that calls createRpcClient/addRoutes runs inside the\n     * server/client that embeds it, so the relation is attributed to that node — the\n     * lib is never a runtime node. Recursion stops at other nodes (each server/client\n     * owns its own relations). dependsOn is transitively reduced, but reduction\n     * preserves reachability, so the recursive walk still reaches every lib a node\n     * embeds through libraries.\n     */\n    private collectDecls(): ScanDecl[] {\n        const decls: ScanDecl[] = [];\n        for (const name of Object.keys(this.projects).sort()) {\n            if (!this.isNode(name)) continue;\n            const implementsApis: ApiRef[] = [];\n            const usesApis: ApiRef[] = [];\n            this.collectEffectiveRelations(name, implementsApis, usesApis, new Set<string>([name]));\n            if (implementsApis.length > 0 || usesApis.length > 0) {\n                decls.push({\n                    name,\n                    implementsApis: dedupApiRefs(sortApiRefs(implementsApis)),\n                    usesApis: dedupApiRefs(sortApiRefs(usesApis)),\n                });\n            }\n        }\n        return decls;\n    }\n\n    /** True when a project is a runtime node — a server or client app (never a library). */\n    private isNode(name: string): boolean {\n        const role = this.projects[name]?.role;\n        return role === 'server' || role === 'client';\n    }\n\n    /**\n     * Accumulate `name`'s own api relations, then recurse through its LIBRARY deps\n     * (skipping other nodes, which own their own relations). `visited` guards against\n     * re-walking a lib reachable by more than one path (and any cycle).\n     */\n    private collectEffectiveRelations(name: string, impl: ApiRef[], uses: ApiRef[], visited: Set<string>): void {\n        const entry = this.projects[name];\n        if (entry === undefined) return;\n        const relations = entry.apiRelations;\n        if (relations !== undefined) {\n            for (const owner of Object.keys(relations)) {\n                impl.push(...relations[owner].implements);\n                uses.push(...relations[owner].uses);\n            }\n        }\n        for (const dep of entry.dependsOn) {\n            if (visited.has(dep)) continue;\n            visited.add(dep);\n            if (this.isNode(dep)) continue; // another server/client owns its own relations\n            this.collectEffectiveRelations(dep, impl, uses, visited);\n        }\n    }\n\n    /** apiClassName -> { implementedBy, usedBy, type }. */\n    private buildApis(decls: ScanDecl[]): Map<string, RuntimeApi> {\n        const apis = new Map<string, RuntimeApi>();\n        const ensure = (api: string, type: ApiTransport): RuntimeApi => {\n            let entry = apis.get(api);\n            if (!entry) {\n                entry = { implementedBy: [], usedBy: [], type };\n                apis.set(api, entry);\n            }\n            return entry;\n        };\n        for (const decl of decls) {\n            for (const ref of decl.implementsApis) ensure(ref.api, ref.type).implementedBy.push(decl.name);\n            for (const ref of decl.usesApis) ensure(ref.api, ref.type).usedBy.push(decl.name);\n        }\n        for (const entry of apis.values()) {\n            entry.implementedBy.sort();\n            entry.usedBy.sort();\n        }\n        return apis;\n    }\n\n    /** Inferred edges U -> I via api A, split by transport; plus uses with no implementer. */\n    private buildEdges(decls: ScanDecl[], apis: Map<string, RuntimeApi>): EdgeResult {\n        const viaByKey = new Map<string, Set<string>>();\n        const unresolved: RuntimeUnresolved[] = [];\n        for (const decl of decls) {\n            for (const ref of decl.usesApis) {\n                const implementers = apis.get(ref.api)?.implementedBy ?? [];\n                if (implementers.length === 0) {\n                    unresolved.push({ service: decl.name, api: ref.api });\n                    continue;\n                }\n                for (const target of implementers) {\n                    if (target === decl.name) continue;\n                    const key = `${decl.name}\u0000${target}\u0000${ref.type}`;\n                    if (!viaByKey.has(key)) viaByKey.set(key, new Set());\n                    viaByKey.get(key)!.add(ref.api);\n                }\n            }\n        }\n        return { edges: this.edgesFromKeys(viaByKey), unresolved: sortUnresolved(unresolved) };\n    }\n\n    private edgesFromKeys(viaByKey: Map<string, Set<string>>): RuntimeEdge[] {\n        const edges: RuntimeEdge[] = [];\n        for (const key of viaByKey.keys()) {\n            const parts = key.split('\u0000');\n            edges.push({ from: parts[0], to: parts[1], via: Array.from(viaByKey.get(key)!).sort(), type: parts[2] as ApiTransport });\n        }\n        edges.sort(\n            (a: RuntimeEdge, b: RuntimeEdge) =>\n                a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || (a.type ?? '').localeCompare(b.type ?? ''),\n        );\n        return edges;\n    }\n\n    private buildServices(decls: ScanDecl[], edges: RuntimeEdge[]): Record<string, RuntimeService> {\n        const services: Record<string, RuntimeService> = {};\n        for (const decl of decls) {\n            const dependsOn = Array.from(\n                new Set(edges.filter((e: RuntimeEdge) => e.from === decl.name).map((e: RuntimeEdge) => e.to)),\n            ).sort();\n            services[decl.name] = {\n                level: 0,\n                implements: decl.implementsApis.map((r: ApiRef) => r.api),\n                uses: decl.usesApis.map((r: ApiRef) => r.api),\n                dependsOn,\n            };\n            if (this.hiddenProjects.has(decl.name)) services[decl.name].drawOnGraph = false;\n        }\n        const levels = assignLevels(adjacencyFromEdges(Object.keys(services), edges));\n        for (const name of Object.keys(services)) services[name].level = levels[name] ?? 0;\n        return services;\n    }\n}\n\n/**\n * Derive the runtime graph from dependencies.json's project `apiRelations` — the\n * single source of truth shared by generate + validate. `hiddenProjects`\n * (drawOnGraph:false, defaults to none) are kept in the graph but flagged so the\n * runtime visualizer omits their nodes + edges.\n */\n// webpieces-disable no-function-outside-class -- module entry point for the runtime graph derivation\nexport function deriveRuntimeGraph(\n    projects: EnhancedGraph,\n    hiddenProjects: Set<string> = new Set<string>()\n): RuntimeGraph {\n    return new RuntimeGraphDeriver(projects, hiddenProjects).assemble();\n}\n\n/** Drop duplicate api refs (same api class), keeping the first — needed after a node absorbs the\n * same api from both its own relations and an embedded lib's. Input is pre-sorted, so output stays\n * deterministic. */\n// webpieces-disable no-function-outside-class -- pure list helper, matches the sibling helpers in this file\nfunction dedupApiRefs(refs: ApiRef[]): ApiRef[] {\n    const seen = new Set<string>();\n    const out: ApiRef[] = [];\n    for (const ref of refs) {\n        if (seen.has(ref.api)) continue;\n        seen.add(ref.api);\n        out.push(ref);\n    }\n    return out;\n}\n\n// webpieces-disable no-function-outside-class -- pure sort helper, matches the sibling helpers in this file\nfunction sortUnresolved(unresolved: RuntimeUnresolved[]): RuntimeUnresolved[] {\n    return [...unresolved].sort(\n        (a: RuntimeUnresolved, b: RuntimeUnresolved) => a.service.localeCompare(b.service) || a.api.localeCompare(b.api),\n    );\n}\n\n/** Deterministic JSON (sorted keys + arrays already sorted during assembly). */\nfunction formatRuntimeJson(graph: RuntimeGraph): string {\n    return JSON.stringify(graph, null, 4) + '\\n';\n}\n\nexport function saveRuntimeGraph(\n    graph: RuntimeGraph,\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): void {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    const dir = path.dirname(fullPath);\n    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });\n    fs.writeFileSync(fullPath, formatRuntimeJson(graph), 'utf-8');\n}\n\nexport function runtimeGraphFileExists(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): boolean {\n    return fs.existsSync(path.join(workspaceRoot, graphPath));\n}\n\nexport function loadRuntimeGraph(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_RUNTIME_GRAPH_PATH,\n): RuntimeGraph | null {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    if (!fs.existsSync(fullPath)) return null;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        return JSON.parse(fs.readFileSync(fullPath, 'utf-8')) as RuntimeGraph;\n    } catch (err: unknown) {\n        const error = toError(err);\n        throw new Error(`Failed to load runtime graph from ${fullPath}`, { cause: error });\n    }\n}\n\n/** Serialize for an in-memory equality check (matches the on-disk format). */\nexport function serializeRuntimeGraph(graph: RuntimeGraph): string {\n    return formatRuntimeJson(graph);\n}\n"]}