@webpieces/nx-webpieces-rules 0.4.520 → 0.4.522

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/nx-webpieces-rules",
-  "version": "0.4.520",
+  "version": "0.4.522",
   "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",
@@ -22,11 +22,11 @@
     "bin/**/*"
   ],
   "dependencies": {
-    "@webpieces/ai-hook-rules": "0.4.520",
-    "@webpieces/code-rules": "0.4.520",
-    "@webpieces/eslint-rules": "0.4.520",
-    "@webpieces/pr-gate": "0.4.520",
-    "@webpieces/rules-config": "0.4.520",
+    "@webpieces/ai-hook-rules": "0.4.522",
+    "@webpieces/code-rules": "0.4.522",
+    "@webpieces/eslint-rules": "0.4.522",
+    "@webpieces/pr-gate": "0.4.522",
+    "@webpieces/rules-config": "0.4.522",
     "madge": "8.0.0"
   },
   "peerDependencies": {

package/src/executors/generate/executor.js

@@ -15,6 +15,7 @@ const graph_sorter_1 = require("../../lib/graph-sorter");
 const graph_loader_1 = require("../../lib/graph-loader");
 const graph_metadata_1 = require("../../lib/graph-metadata");
 const api_scanner_1 = require("../../lib/api-usage/api-scanner");
+const external_systems_1 = require("../../lib/api-usage/external-systems");
 const runtime_config_1 = require("../../lib/runtime-config");
 const graph_visualizer_1 = require("../../lib/graph-visualizer");
 const runtime_graph_1 = require("../../lib/runtime-graph");
@@ -26,9 +27,9 @@ const toError_1 = require("../../toError");
  * pubsub APIs become edges the viz draws through a queue.
  */
 // webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file
-function generateRuntimeGraph(workspaceRoot, graph, hiddenProjects, apiContracts) {
+function generateRuntimeGraph(workspaceRoot, graph, hiddenProjects, apiContracts, externalSystems) {
     console.log('📡 Deriving runtime graph from dependencies.json (implements × uses per API)...');
-    const report = (0, runtime_graph_1.deriveRuntimeGraphReport)(graph, hiddenProjects, apiContracts);
+    const report = (0, runtime_graph_1.deriveRuntimeGraphReport)(graph, hiddenProjects, apiContracts, externalSystems);
     (0, runtime_graph_1.saveRuntimeGraph)(report.graph, workspaceRoot);
     const serviceCount = Object.keys(report.graph.services).length;
     const queueCount = Object.keys(report.graph.queues).length;
@@ -81,7 +82,16 @@ function scanApiRelations(workspaceRoot, graph, projectInfos) {
         for (const mismatch of mismatches)
             console.error(`     • ${mismatch}`);
     }
-    return contracts;
+    return new ScannedTables(contracts, (0, external_systems_1.buildExternalSystems)(scan.apiIndex, projectInfos));
+}
+/** The two committed tables one scan produces, kept together so callers cannot persist just one. */
+class ScannedTables {
+    apiContracts;
+    externalSystems;
+    constructor(apiContracts, externalSystems) {
+        this.apiContracts = apiContracts;
+        this.externalSystems = externalSystems;
+    }
 }
 /** Projects tagged drawOnGraph:false — kept in the JSON, omitted from every rendered graph. */
 // webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file
@@ -100,43 +110,53 @@ function printGraphSummary(graph) {
     console.log(`   Projects: ${Object.keys(graph).length}`);
     console.log(`   Levels: ${levels.size} (0-${Math.max(...levels)})`);
 }
+/**
+ * The whole generation pipeline. Split out of runExecutor so that function stays a thin
+ * try/catch-and-report shell — the error reporting is what a caller reads on failure, and it should
+ * not be separated from the throw by fifty lines of steps.
+ */
+// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file
+async function generateEverything(workspaceRoot, graphPath) {
+    // Step 1: Build the full graph from nx, then transitively reduce it to the view
+    console.log("📊 Generating dependency graph from nx's project graph...");
+    const reducedGraph = await (0, graph_generator_1.generateReducedGraph)();
+    // Step 2: Topological sort (to assign levels for visualization)
+    console.log('🔄 Computing topological layers...');
+    const enhancedGraph = (0, graph_sorter_1.sortGraphTopologically)(reducedGraph);
+    // Step 3: Enrich with AI metadata (framework, shortDescription, file
+    // pointers). This VALIDATES (responsibilities.md required per project)
+    // and throws before any write, so a failure never clobbers the file.
+    console.log('🏷️  Enriching graph with framework + responsibilities metadata...');
+    const projectInfos = await (0, graph_metadata_1.collectProjectInfo)();
+    (0, graph_metadata_1.enrichGraph)(enhancedGraph, projectInfos, workspaceRoot);
+    // Step 3b: Classify each api-lib edge (implements/uses + rpc/pubsub) by
+    // scanning source, so dependencies.json + the viz + the runtime graph all
+    // read the same derived truth.
+    const scanned = scanApiRelations(workspaceRoot, enhancedGraph, projectInfos);
+    const apiContracts = scanned.apiContracts;
+    // Step 4: Save the graph, INCLUDING the per-contract method table and the external-system
+    // declarations the runtime derivation reads back — generate derives from the in-memory graph,
+    // validate from the file, so anything not written here would make the two disagree.
+    console.log('💾 Saving graph to architecture/dependencies.json...');
+    (0, graph_loader_1.saveGraph)(enhancedGraph, workspaceRoot, graphPath, apiContracts, scanned.externalSystems);
+    console.log('✅ Graph saved successfully');
+    // Step 4b: Write the committed, clickable HTML view next to the JSON so
+    // dependencies.html regenerates in lock-step with dependencies.json.
+    const vizPaths = new graph_visualizer_1.GraphVisualizer().writeVisualization(enhancedGraph, workspaceRoot);
+    console.log(`✅ Wrote ${vizPaths.htmlPath}`);
+    // Step 5: Generate the runtime microservice graph from the same scan.
+    // Projects tagged drawOnGraph:false are threaded through so the runtime
+    // graph hides them too (they stay flagged in runtime-dependencies.json).
+    generateRuntimeGraph(workspaceRoot, enhancedGraph, hiddenProjectsIn(enhancedGraph), apiContracts, scanned.externalSystems);
+    printGraphSummary(enhancedGraph);
+}
 async function runExecutor(options, context) {
     const graphPath = options.graphPath;
     const workspaceRoot = context.root;
     console.log('\n📊 Architecture Graph Generator\n');
     // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
     try {
-        // Step 1: Build the full graph from nx, then transitively reduce it to the view
-        console.log("📊 Generating dependency graph from nx's project graph...");
-        const reducedGraph = await (0, graph_generator_1.generateReducedGraph)();
-        // Step 2: Topological sort (to assign levels for visualization)
-        console.log('🔄 Computing topological layers...');
-        const enhancedGraph = (0, graph_sorter_1.sortGraphTopologically)(reducedGraph);
-        // Step 3: Enrich with AI metadata (framework, shortDescription, file
-        // pointers). This VALIDATES (responsibilities.md required per project)
-        // and throws before any write, so a failure never clobbers the file.
-        console.log('🏷️  Enriching graph with framework + responsibilities metadata...');
-        const projectInfos = await (0, graph_metadata_1.collectProjectInfo)();
-        (0, graph_metadata_1.enrichGraph)(enhancedGraph, projectInfos, workspaceRoot);
-        // Step 3b: Classify each api-lib edge (implements/uses + rpc/pubsub) by
-        // scanning source, so dependencies.json + the viz + the runtime graph all
-        // read the same derived truth.
-        const apiContracts = scanApiRelations(workspaceRoot, enhancedGraph, projectInfos);
-        // Step 4: Save the graph, INCLUDING the per-contract method table the runtime derivation
-        // reads back — generate derives from the in-memory graph, validate from the file, so
-        // anything not written here would make the two disagree.
-        console.log('💾 Saving graph to architecture/dependencies.json...');
-        (0, graph_loader_1.saveGraph)(enhancedGraph, workspaceRoot, graphPath, apiContracts);
-        console.log('✅ Graph saved successfully');
-        // Step 4b: Write the committed, clickable HTML view next to the JSON so
-        // dependencies.html regenerates in lock-step with dependencies.json.
-        const vizPaths = new graph_visualizer_1.GraphVisualizer().writeVisualization(enhancedGraph, workspaceRoot);
-        console.log(`✅ Wrote ${vizPaths.htmlPath}`);
-        // Step 5: Generate the runtime microservice graph from the same scan.
-        // Projects tagged drawOnGraph:false are threaded through so the runtime
-        // graph hides them too (they stay flagged in runtime-dependencies.json).
-        generateRuntimeGraph(workspaceRoot, enhancedGraph, hiddenProjectsIn(enhancedGraph), apiContracts);
-        printGraphSummary(enhancedGraph);
+        await generateEverything(workspaceRoot, graphPath);
         return { success: true };
     }
     catch (err) {

package/src/executors/generate/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/generate/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Generate Executor\n *\n * Generates the architecture dependency graph and saves it to architecture/dependencies.json.\n *\n * Usage:\n * nx run architecture:generate\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { writeTemplate } from '@webpieces/rules-config';\nimport { generateReducedGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { saveGraph } from '../../lib/graph-loader';\nimport { collectProjectInfo, enrichGraph, MetadataValidationError } from '../../lib/graph-metadata';\nimport { ProjectInfo } from '../../lib/project-info';\nimport {\n    scanAndAttachApiRelations,\n    describeUnresolvedApiCalls,\n    describeNonLiteralDecoratorArgs,\n    buildApiContracts,\n    describeMismatchedEndpointKinds,\n} from '../../lib/api-usage/api-scanner';\nimport type { ApiContracts } from '../../lib/api-usage/api-relations';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport type { EnhancedGraph, GraphEntry } from '../../lib/graph-sorter';\nimport { GraphVisualizer } from '../../lib/graph-visualizer';\nimport { deriveRuntimeGraphReport, saveRuntimeGraph } from '../../lib/runtime-graph';\nimport { toError } from '../../toError';\n\nexport interface GenerateExecutorOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n/**\n * Generate the runtime microservice graph alongside the compile-time graph, DERIVED from the same\n * dependencies.json (its per-project apiRelations) — one regenerate produces both committed files, and\n * validate derives from the SAME source so they can't diverge. rpc APIs become direct runtime edges;\n * pubsub APIs become edges the viz draws through a queue.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction generateRuntimeGraph(\n    workspaceRoot: string,\n    graph: EnhancedGraph,\n    hiddenProjects: Set<string>,\n    apiContracts: ApiContracts,\n): void {\n    console.log('📡 Deriving runtime graph from dependencies.json (implements × uses per API)...');\n    const report = deriveRuntimeGraphReport(graph, hiddenProjects, apiContracts);\n    saveRuntimeGraph(report.graph, workspaceRoot);\n    const serviceCount = Object.keys(report.graph.services).length;\n    const queueCount = Object.keys(report.graph.queues).length;\n    console.log(\n        `✅ Runtime graph saved (${serviceCount} services, ${report.graph.runtimeEdges.length} runtime edges, ` +\n            `${queueCount} queues, ${report.graph.triggers.length} cron/external triggers)`,\n    );\n    // Every edge the derivation had to GUESS at. Loud on purpose: a fanned-out edge is committed and\n    // then reasoned about as if it were derived, which is how a fictional call survives for months.\n    printRuntimeWarnings(report.warnings);\n    // Printed here, FAILED by validate-runtime-architecture: generate must still write the graph,\n    // or the validator would have nothing to compare against and the error would be unfixable.\n    if (report.problems.length > 0) {\n        console.error(`❌ ${report.problems.length} client call(s) name a service no module answers to:`);\n        for (const problem of report.problems) console.error(`     • ${problem}`);\n        console.error('   This FAILS architecture:validate-runtime-architecture.');\n    }\n}\n\n/** Print the derivation's guessed-edge warnings (nothing at all when the graph is fully targeted). */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction printRuntimeWarnings(warnings: string[]): void {\n    if (warnings.length === 0) return;\n    console.warn(`⚠️  ${warnings.length} runtime edge(s) could not be targeted to ONE service:`);\n    for (const warning of warnings) console.warn(`     • ${warning}`);\n}\n\n/**\n * Scan for api relations and attach them, surfacing any contract we could NOT map back to source.\n * Unresolved contracts mean the graph we are about to WRITE is incomplete, so they must be loud —\n * a green run that quietly omits a service gets committed, rendered, and trusted.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction scanApiRelations(\n    workspaceRoot: string,\n    graph: EnhancedGraph,\n    projectInfos: Map<string, ProjectInfo>,\n): ApiContracts {\n    console.log('🔎 Scanning source for implements/uses API relations...');\n    const externalApiPaths = loadRuntimeConfig(workspaceRoot).externalApiPaths;\n    const scan = scanAndAttachApiRelations(workspaceRoot, graph, projectInfos, externalApiPaths);\n    if (scan.unresolvedApiCalls.length > 0) console.warn(describeUnresolvedApiCalls(scan.unresolvedApiCalls));\n    // A decorator argument we could not read costs the graph a basePath, a method, or a whole\n    // contract — none of which leaves a trace in the output. Name them before anything is written.\n    if (scan.nonLiteralDecoratorArgs.length > 0) {\n        console.warn(describeNonLiteralDecoratorArgs(scan.nonLiteralDecoratorArgs));\n    }\n    const contracts = buildApiContracts(scan);\n    // An endpoint whose declared trigger its api kind cannot deliver would silently draw a queue or a\n    // clock that nothing could ever fire — name it here, where the fix is one decorator away.\n    const mismatches = describeMismatchedEndpointKinds(contracts);\n    if (mismatches.length > 0) {\n        console.error(`❌ ${mismatches.length} @Endpoint kind(s) conflict with their api kind:`);\n        for (const mismatch of mismatches) console.error(`     • ${mismatch}`);\n    }\n    return contracts;\n}\n\n/** Projects tagged drawOnGraph:false — kept in the JSON, omitted from every rendered graph. */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction hiddenProjectsIn(graph: EnhancedGraph): Set<string> {\n    const hidden = new Set<string>();\n    for (const name of Object.keys(graph)) {\n        if (graph[name].drawOnGraph === false) hidden.add(name);\n    }\n    return hidden;\n}\n\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction printGraphSummary(graph: EnhancedGraph): void {\n    const levels = new Set(Object.values(graph).map((entry: GraphEntry) => entry.level));\n    console.log(`\\n📈 Graph Summary:`);\n    console.log(`   Projects: ${Object.keys(graph).length}`);\n    console.log(`   Levels: ${levels.size} (0-${Math.max(...levels)})`);\n}\n\nexport default async function runExecutor(\n    options: GenerateExecutorOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    console.log('\\n📊 Architecture Graph Generator\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Step 1: Build the full graph from nx, then transitively reduce it to the view\n        console.log(\"📊 Generating dependency graph from nx's project graph...\");\n        const reducedGraph = await generateReducedGraph();\n\n        // Step 2: Topological sort (to assign levels for visualization)\n        console.log('🔄 Computing topological layers...');\n        const enhancedGraph = sortGraphTopologically(reducedGraph);\n\n        // Step 3: Enrich with AI metadata (framework, shortDescription, file\n        // pointers). This VALIDATES (responsibilities.md required per project)\n        // and throws before any write, so a failure never clobbers the file.\n        console.log('🏷️  Enriching graph with framework + responsibilities metadata...');\n        const projectInfos = await collectProjectInfo();\n        enrichGraph(enhancedGraph, projectInfos, workspaceRoot);\n\n        // Step 3b: Classify each api-lib edge (implements/uses + rpc/pubsub) by\n        // scanning source, so dependencies.json + the viz + the runtime graph all\n        // read the same derived truth.\n        const apiContracts = scanApiRelations(workspaceRoot, enhancedGraph, projectInfos);\n\n        // Step 4: Save the graph, INCLUDING the per-contract method table the runtime derivation\n        // reads back — generate derives from the in-memory graph, validate from the file, so\n        // anything not written here would make the two disagree.\n        console.log('💾 Saving graph to architecture/dependencies.json...');\n        saveGraph(enhancedGraph, workspaceRoot, graphPath, apiContracts);\n        console.log('✅ Graph saved successfully');\n\n        // Step 4b: Write the committed, clickable HTML view next to the JSON so\n        // dependencies.html regenerates in lock-step with dependencies.json.\n        const vizPaths = new GraphVisualizer().writeVisualization(enhancedGraph, workspaceRoot);\n        console.log(`✅ Wrote ${vizPaths.htmlPath}`);\n\n        // Step 5: Generate the runtime microservice graph from the same scan.\n        // Projects tagged drawOnGraph:false are threaded through so the runtime\n        // graph hides them too (they stay flagged in runtime-dependencies.json).\n        generateRuntimeGraph(workspaceRoot, enhancedGraph, hiddenProjectsIn(enhancedGraph), apiContracts);\n\n        printGraphSummary(enhancedGraph);\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error('❌ Graph generation failed:', error.message);\n        if (error instanceof MetadataValidationError) {\n            const mdPath = writeTemplate(workspaceRoot, 'webpieces.responsibilities.md');\n            console.error('');\n            console.error('⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️');\n        }\n        return { success: false };\n    }\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/generate/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Generate Executor\n *\n * Generates the architecture dependency graph and saves it to architecture/dependencies.json.\n *\n * Usage:\n * nx run architecture:generate\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { writeTemplate } from '@webpieces/rules-config';\nimport { generateReducedGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { saveGraph } from '../../lib/graph-loader';\nimport { collectProjectInfo, enrichGraph, MetadataValidationError } from '../../lib/graph-metadata';\nimport { ProjectInfo } from '../../lib/project-info';\nimport {\n    scanAndAttachApiRelations,\n    describeUnresolvedApiCalls,\n    describeNonLiteralDecoratorArgs,\n    buildApiContracts,\n    describeMismatchedEndpointKinds,\n} from '../../lib/api-usage/api-scanner';\nimport { buildExternalSystems } from '../../lib/api-usage/external-systems';\nimport type { ApiContracts, ExternalSystemDecls } from '../../lib/api-usage/api-relations';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport type { EnhancedGraph, GraphEntry } from '../../lib/graph-sorter';\nimport { GraphVisualizer } from '../../lib/graph-visualizer';\nimport { deriveRuntimeGraphReport, saveRuntimeGraph } from '../../lib/runtime-graph';\nimport { toError } from '../../toError';\n\nexport interface GenerateExecutorOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n/**\n * Generate the runtime microservice graph alongside the compile-time graph, DERIVED from the same\n * dependencies.json (its per-project apiRelations) — one regenerate produces both committed files, and\n * validate derives from the SAME source so they can't diverge. rpc APIs become direct runtime edges;\n * pubsub APIs become edges the viz draws through a queue.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction generateRuntimeGraph(\n    workspaceRoot: string,\n    graph: EnhancedGraph,\n    hiddenProjects: Set<string>,\n    apiContracts: ApiContracts,\n    externalSystems: ExternalSystemDecls,\n): void {\n    console.log('📡 Deriving runtime graph from dependencies.json (implements × uses per API)...');\n    const report = deriveRuntimeGraphReport(graph, hiddenProjects, apiContracts, externalSystems);\n    saveRuntimeGraph(report.graph, workspaceRoot);\n    const serviceCount = Object.keys(report.graph.services).length;\n    const queueCount = Object.keys(report.graph.queues).length;\n    console.log(\n        `✅ Runtime graph saved (${serviceCount} services, ${report.graph.runtimeEdges.length} runtime edges, ` +\n            `${queueCount} queues, ${report.graph.triggers.length} cron/external triggers)`,\n    );\n    // Every edge the derivation had to GUESS at. Loud on purpose: a fanned-out edge is committed and\n    // then reasoned about as if it were derived, which is how a fictional call survives for months.\n    printRuntimeWarnings(report.warnings);\n    // Printed here, FAILED by validate-runtime-architecture: generate must still write the graph,\n    // or the validator would have nothing to compare against and the error would be unfixable.\n    if (report.problems.length > 0) {\n        console.error(`❌ ${report.problems.length} client call(s) name a service no module answers to:`);\n        for (const problem of report.problems) console.error(`     • ${problem}`);\n        console.error('   This FAILS architecture:validate-runtime-architecture.');\n    }\n}\n\n/** Print the derivation's guessed-edge warnings (nothing at all when the graph is fully targeted). */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction printRuntimeWarnings(warnings: string[]): void {\n    if (warnings.length === 0) return;\n    console.warn(`⚠️  ${warnings.length} runtime edge(s) could not be targeted to ONE service:`);\n    for (const warning of warnings) console.warn(`     • ${warning}`);\n}\n\n/**\n * Scan for api relations and attach them, surfacing any contract we could NOT map back to source.\n * Unresolved contracts mean the graph we are about to WRITE is incomplete, so they must be loud —\n * a green run that quietly omits a service gets committed, rendered, and trusted.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction scanApiRelations(\n    workspaceRoot: string,\n    graph: EnhancedGraph,\n    projectInfos: Map<string, ProjectInfo>,\n): ScannedTables {\n    console.log('🔎 Scanning source for implements/uses API relations...');\n    const externalApiPaths = loadRuntimeConfig(workspaceRoot).externalApiPaths;\n    const scan = scanAndAttachApiRelations(workspaceRoot, graph, projectInfos, externalApiPaths);\n    if (scan.unresolvedApiCalls.length > 0) console.warn(describeUnresolvedApiCalls(scan.unresolvedApiCalls));\n    // A decorator argument we could not read costs the graph a basePath, a method, or a whole\n    // contract — none of which leaves a trace in the output. Name them before anything is written.\n    if (scan.nonLiteralDecoratorArgs.length > 0) {\n        console.warn(describeNonLiteralDecoratorArgs(scan.nonLiteralDecoratorArgs));\n    }\n    const contracts = buildApiContracts(scan);\n    // An endpoint whose declared trigger its api kind cannot deliver would silently draw a queue or a\n    // clock that nothing could ever fire — name it here, where the fix is one decorator away.\n    const mismatches = describeMismatchedEndpointKinds(contracts);\n    if (mismatches.length > 0) {\n        console.error(`❌ ${mismatches.length} @Endpoint kind(s) conflict with their api kind:`);\n        for (const mismatch of mismatches) console.error(`     • ${mismatch}`);\n    }\n    return new ScannedTables(contracts, buildExternalSystems(scan.apiIndex, projectInfos));\n}\n\n/** The two committed tables one scan produces, kept together so callers cannot persist just one. */\nclass ScannedTables {\n    constructor(\n        public readonly apiContracts: ApiContracts,\n        public readonly externalSystems: ExternalSystemDecls,\n    ) {}\n}\n\n/** Projects tagged drawOnGraph:false — kept in the JSON, omitted from every rendered graph. */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction hiddenProjectsIn(graph: EnhancedGraph): Set<string> {\n    const hidden = new Set<string>();\n    for (const name of Object.keys(graph)) {\n        if (graph[name].drawOnGraph === false) hidden.add(name);\n    }\n    return hidden;\n}\n\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction printGraphSummary(graph: EnhancedGraph): void {\n    const levels = new Set(Object.values(graph).map((entry: GraphEntry) => entry.level));\n    console.log(`\\n📈 Graph Summary:`);\n    console.log(`   Projects: ${Object.keys(graph).length}`);\n    console.log(`   Levels: ${levels.size} (0-${Math.max(...levels)})`);\n}\n\n/**\n * The whole generation pipeline. Split out of runExecutor so that function stays a thin\n * try/catch-and-report shell — the error reporting is what a caller reads on failure, and it should\n * not be separated from the throw by fifty lines of steps.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nasync function generateEverything(workspaceRoot: string, graphPath: string | undefined): Promise<void> {\n    // Step 1: Build the full graph from nx, then transitively reduce it to the view\n    console.log(\"📊 Generating dependency graph from nx's project graph...\");\n    const reducedGraph = await generateReducedGraph();\n\n    // Step 2: Topological sort (to assign levels for visualization)\n    console.log('🔄 Computing topological layers...');\n    const enhancedGraph = sortGraphTopologically(reducedGraph);\n\n    // Step 3: Enrich with AI metadata (framework, shortDescription, file\n    // pointers). This VALIDATES (responsibilities.md required per project)\n    // and throws before any write, so a failure never clobbers the file.\n    console.log('🏷️  Enriching graph with framework + responsibilities metadata...');\n    const projectInfos = await collectProjectInfo();\n    enrichGraph(enhancedGraph, projectInfos, workspaceRoot);\n\n    // Step 3b: Classify each api-lib edge (implements/uses + rpc/pubsub) by\n    // scanning source, so dependencies.json + the viz + the runtime graph all\n    // read the same derived truth.\n    const scanned = scanApiRelations(workspaceRoot, enhancedGraph, projectInfos);\n    const apiContracts = scanned.apiContracts;\n\n    // Step 4: Save the graph, INCLUDING the per-contract method table and the external-system\n    // declarations the runtime derivation reads back — generate derives from the in-memory graph,\n    // validate from the file, so anything not written here would make the two disagree.\n    console.log('💾 Saving graph to architecture/dependencies.json...');\n    saveGraph(enhancedGraph, workspaceRoot, graphPath, apiContracts, scanned.externalSystems);\n    console.log('✅ Graph saved successfully');\n\n    // Step 4b: Write the committed, clickable HTML view next to the JSON so\n    // dependencies.html regenerates in lock-step with dependencies.json.\n    const vizPaths = new GraphVisualizer().writeVisualization(enhancedGraph, workspaceRoot);\n    console.log(`✅ Wrote ${vizPaths.htmlPath}`);\n\n    // Step 5: Generate the runtime microservice graph from the same scan.\n    // Projects tagged drawOnGraph:false are threaded through so the runtime\n    // graph hides them too (they stay flagged in runtime-dependencies.json).\n    generateRuntimeGraph(\n        workspaceRoot,\n        enhancedGraph,\n        hiddenProjectsIn(enhancedGraph),\n        apiContracts,\n        scanned.externalSystems,\n    );\n\n    printGraphSummary(enhancedGraph);\n}\n\nexport default async function runExecutor(\n    options: GenerateExecutorOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    console.log('\\n📊 Architecture Graph Generator\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        await generateEverything(workspaceRoot, graphPath);\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error('❌ Graph generation failed:', error.message);\n        if (error instanceof MetadataValidationError) {\n            const mdPath = writeTemplate(workspaceRoot, 'webpieces.responsibilities.md');\n            console.error('');\n            console.error('⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️');\n        }\n        return { success: false };\n    }\n}\n"]}

package/src/executors/validate-architecture-unchanged/executor.js

@@ -17,6 +17,7 @@ const graph_comparator_1 = require("../../lib/graph-comparator");
 const graph_loader_1 = require("../../lib/graph-loader");
 const graph_metadata_1 = require("../../lib/graph-metadata");
 const api_scanner_1 = require("../../lib/api-usage/api-scanner");
+const external_systems_1 = require("../../lib/api-usage/external-systems");
 const runtime_config_1 = require("../../lib/runtime-config");
 const rule_gate_1 = require("../../lib/rule-gate");
 const toError_1 = require("../../toError");
@@ -68,6 +69,40 @@ function describeContractDrift(current, saved) {
         return null;
     return `apiContracts drift (${changes.length} contract(s)):\n${changes.join('\n')}`;
 }
+/**
+ * Drift in EITHER side table of dependencies.json — the api contracts or the external-system
+ * declarations — or null when both match. The first difference found is reported; fixing it is the
+ * same single command either way, so listing both adds noise rather than information.
+ */
+// webpieces-disable no-function-outside-class -- executor step helper, matches describeContractDrift above
+function describeTableDrift(current, saved) {
+    const contractDrift = describeContractDrift(current.apiContracts, saved.apiContracts);
+    if (contractDrift !== null)
+        return contractDrift;
+    return describeExternalSystemDrift(current.externalSystems, saved.externalSystems);
+}
+/**
+ * The same drift report for the declared external systems, or null when they match. Named per
+ * system so the message points at the database that changed rather than dumping two JSON blobs.
+ */
+// webpieces-disable no-function-outside-class -- executor step helper, matches describeContractDrift above
+function describeExternalSystemDrift(current, saved) {
+    const names = [...new Set([...Object.keys(current), ...Object.keys(saved)])].sort();
+    const changes = [];
+    for (const name of names) {
+        const a = current[name];
+        const b = saved[name];
+        if (a === undefined)
+            changes.push(`  - ${name}: in dependencies.json but no longer declared in source`);
+        else if (b === undefined)
+            changes.push(`  + ${name}: declared in source but missing from dependencies.json`);
+        else if (JSON.stringify(a) !== JSON.stringify(b))
+            changes.push(`  ~ ${name}: kind/label/declarers changed`);
+    }
+    if (changes.length === 0)
+        return null;
+    return `externalSystems drift (${changes.length} system(s)):\n${changes.join('\n')}`;
+}
 /**
  * Build the current dependency graph exactly as the generator does: reduce the nx
  * graph, sort into levels, enrich with metadata, and attach the derived
@@ -87,15 +122,17 @@ async function buildCurrentGraph(workspaceRoot) {
     // relation from the regenerated graph and report drift against a perfectly fresh file.
     const externalApiPaths = (0, runtime_config_1.loadRuntimeConfig)(workspaceRoot).externalApiPaths;
     const scan = (0, api_scanner_1.scanAndAttachApiRelations)(workspaceRoot, currentGraph, projectInfos, externalApiPaths);
-    return new CurrentArchitecture(currentGraph, (0, api_scanner_1.buildApiContracts)(scan));
+    return new CurrentArchitecture(currentGraph, (0, api_scanner_1.buildApiContracts)(scan), (0, external_systems_1.buildExternalSystems)(scan.apiIndex, projectInfos));
 }
-/** The regenerated graph plus its api contract table — both halves of what dependencies.json holds. */
+/** The regenerated graph plus the two tables beside it — everything dependencies.json holds. */
 class CurrentArchitecture {
     graph;
     apiContracts;
-    constructor(graph, apiContracts) {
+    externalSystems;
+    constructor(graph, apiContracts, externalSystems) {
         this.graph = graph;
         this.apiContracts = apiContracts;
+        this.externalSystems = externalSystems;
     }
 }
 /** The bootstrap path: there is nothing to diff against yet, so say how to create it. */
@@ -142,13 +179,12 @@ async function runExecutor(options, context) {
             reportMismatch(comparison.summary, workspaceRoot);
             return { success: false };
         }
-        // Step 6: Compare the api contract table too. It is NOT part of the project graph, so a
-        // changed @Endpoint kind or queue name would otherwise pass here AND pass
-        // validate-runtime-architecture (which derives from this same stale file) — leaving a queue
-        // or cron in the committed graph that no longer matches the source.
-        const contractDrift = describeContractDrift(currentGraph.apiContracts, savedGraph.apiContracts);
-        if (contractDrift !== null) {
-            reportMismatch(contractDrift, workspaceRoot);
+        // Step 6: Compare the two side tables as well. Neither is part of the project graph, so a
+        // changed @Endpoint kind, queue name, or external-system declaration would otherwise pass
+        // here AND pass validate-runtime-architecture (which derives from this same stale file).
+        const tableDrift = describeTableDrift(currentGraph, savedGraph);
+        if (tableDrift !== null) {
+            reportMismatch(tableDrift, workspaceRoot);
             return { success: false };
         }
         console.log('✅ Architecture unchanged - current graph matches saved graph');

package/src/executors/validate-architecture-unchanged/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-architecture-unchanged/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate Architecture Unchanged Executor\n *\n * Validates that the current architecture graph matches the saved blessed graph.\n * This ensures no unapproved architecture changes have been made.\n *\n * Usage:\n * nx run architecture:validate-architecture-unchanged\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { writeTemplate } from '@webpieces/rules-config';\nimport { generateReducedGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { compareGraphs } from '../../lib/graph-comparator';\nimport { loadBlessedGraph, graphFileExists } from '../../lib/graph-loader';\nimport { collectProjectInfo, enrichGraph, MetadataValidationError } from '../../lib/graph-metadata';\nimport { scanAndAttachApiRelations, buildApiContracts } from '../../lib/api-usage/api-scanner';\nimport type { ApiContracts } from '../../lib/api-usage/api-relations';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport { RuleGate } from '../../lib/rule-gate';\nimport type { EnhancedGraph } from '../../lib/graph-sorter';\nimport { toError } from '../../toError';\n\nexport interface ValidateArchitectureUnchangedOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nconst TMP_MD_FILE = 'webpieces.dependencies.md';\n\n/**\n * Write the instructions documentation to .webpieces/instruct-ai/.\n * Sourced from @webpieces/rules-config.\n */\nfunction writeTmpInstructionsFile(workspaceRoot: string): string {\n    const mdPath = writeTemplate(workspaceRoot, TMP_MD_FILE);\n\n    return mdPath;\n}\n\n/**\n * Report a current-vs-saved graph mismatch and write the AI instructions file.\n */\nfunction reportMismatch(summary: string, workspaceRoot: string): void {\n    const mdPath = writeTmpInstructionsFile(workspaceRoot);\n\n    console.error('❌ Architecture has changed since last update!');\n    console.error('\\nDifferences:');\n    console.error(summary);\n    console.error('');\n    console.error('⚠️  *** Refer to ' + mdPath + ' for instructions on how to fix *** ⚠️');\n    console.error('');\n    console.error('To fix:');\n    console.error('  1. Review the changes above');\n    console.error('  2. If intentional, ASK USER to run: nx run architecture:generate since this is a critical change');\n    console.error('  3. Commit the updated architecture/dependencies.json');\n}\n\n/**\n * A human-readable summary of how the regenerated api contract table differs from the committed one,\n * or null when they match. Named per contract so the message points at the api that changed rather\n * than dumping two JSON blobs.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch in this file\nfunction describeContractDrift(current: ApiContracts, saved: ApiContracts): string | null {\n    const names = [...new Set([...Object.keys(current), ...Object.keys(saved)])].sort();\n    const changes: string[] = [];\n    for (const name of names) {\n        const a = current[name];\n        const b = saved[name];\n        if (a === undefined) changes.push(`  - ${name}: in dependencies.json but no longer in source`);\n        else if (b === undefined) changes.push(`  + ${name}: in source but missing from dependencies.json`);\n        else if (JSON.stringify(a) !== JSON.stringify(b)) changes.push(`  ~ ${name}: endpoints/kinds/queues changed`);\n    }\n    if (changes.length === 0) return null;\n    return `apiContracts drift (${changes.length} contract(s)):\\n${changes.join('\\n')}`;\n}\n\n/**\n * Build the current dependency graph exactly as the generator does: reduce the nx\n * graph, sort into levels, enrich with metadata, and attach the derived\n * apiRelations — so this validator compares like-for-like against the committed file.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch/writeTmpInstructionsFile in this file\nasync function buildCurrentGraph(workspaceRoot: string): Promise<CurrentArchitecture> {\n    console.log('📊 Generating current dependency graph...');\n    const reducedGraph = await generateReducedGraph();\n    console.log('🔄 Computing topological layers...');\n    const currentGraph = sortGraphTopologically(reducedGraph);\n    console.log('🏷️  Enriching graph with framework + responsibilities metadata...');\n    const projectInfos = await collectProjectInfo();\n    enrichGraph(currentGraph, projectInfos, workspaceRoot);\n    console.log('🔎 Scanning source for implements/uses API relations...');\n    // The SAME externalApiPaths the generator uses: scanning without them would drop every vendor\n    // relation from the regenerated graph and report drift against a perfectly fresh file.\n    const externalApiPaths = loadRuntimeConfig(workspaceRoot).externalApiPaths;\n    const scan = scanAndAttachApiRelations(workspaceRoot, currentGraph, projectInfos, externalApiPaths);\n    return new CurrentArchitecture(currentGraph, buildApiContracts(scan));\n}\n\n/** The regenerated graph plus its api contract table — both halves of what dependencies.json holds. */\nclass CurrentArchitecture {\n    constructor(\n        public readonly graph: EnhancedGraph,\n        public readonly apiContracts: ApiContracts,\n    ) {}\n}\n\n/** The bootstrap path: there is nothing to diff against yet, so say how to create it. */\n// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch in this file\nfunction reportMissingGraph(): void {\n    console.error('❌ No saved graph found at architecture/dependencies.json');\n    console.error('');\n    console.error('To initialize:');\n    console.error('  1. Run: nx run architecture:generate');\n    console.error('  2. Run: nx run architecture:visualize');\n    console.error('  3. Manually inspect the generated graph to confirm it is the desired architecture');\n    console.error('  4. Commit architecture/dependencies.json');\n}\n\nexport default async function runExecutor(\n    options: ValidateArchitectureUnchangedOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    // Epoch-gateable: this rule diffs against the blessed architecture/dependencies.json, so\n    // \"grandfather the current drift until <epoch>\" is meaningful — hence honorEpoch = true.\n    if (new RuleGate().isDisabled(workspaceRoot, 'validate-architecture-unchanged', true)) {\n        return { success: true };\n    }\n\n    console.log('\\n🔍 Validating Architecture Unchanged\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Check if saved graph exists\n        if (!graphFileExists(workspaceRoot, graphPath)) {\n            reportMissingGraph();\n            return { success: false };\n        }\n\n        // Steps 1-3: build + enrich + scan the current graph (same pipeline the\n        // generator runs, so any drift is caught).\n        const currentGraph = await buildCurrentGraph(workspaceRoot);\n\n        // Step 4: Load saved graph\n        console.log('📂 Loading saved graph...');\n        const savedGraph = loadBlessedGraph(workspaceRoot, graphPath);\n\n        if (!savedGraph) {\n            console.error('❌ Could not load saved graph');\n            return { success: false };\n        }\n\n        // Step 5: Compare graphs\n        console.log('🔍 Comparing current graph to saved graph...');\n        const comparison = compareGraphs(currentGraph.graph, savedGraph.projects);\n\n        if (!comparison.identical) {\n            reportMismatch(comparison.summary, workspaceRoot);\n            return { success: false };\n        }\n\n        // Step 6: Compare the api contract table too. It is NOT part of the project graph, so a\n        // changed @Endpoint kind or queue name would otherwise pass here AND pass\n        // validate-runtime-architecture (which derives from this same stale file) — leaving a queue\n        // or cron in the committed graph that no longer matches the source.\n        const contractDrift = describeContractDrift(currentGraph.apiContracts, savedGraph.apiContracts);\n        if (contractDrift !== null) {\n            reportMismatch(contractDrift, workspaceRoot);\n            return { success: false };\n        }\n\n        console.log('✅ Architecture unchanged - current graph matches saved graph');\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error('❌ Architecture validation failed:', error.message);\n        if (error instanceof MetadataValidationError) {\n            const mdPath = writeTemplate(workspaceRoot, 'webpieces.responsibilities.md');\n            console.error('');\n            console.error('⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️');\n        }\n        return { success: false };\n    }\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-architecture-unchanged/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate Architecture Unchanged Executor\n *\n * Validates that the current architecture graph matches the saved blessed graph.\n * This ensures no unapproved architecture changes have been made.\n *\n * Usage:\n * nx run architecture:validate-architecture-unchanged\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { writeTemplate } from '@webpieces/rules-config';\nimport { generateReducedGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { compareGraphs } from '../../lib/graph-comparator';\nimport { loadBlessedGraph, graphFileExists } from '../../lib/graph-loader';\nimport type { DependenciesFile } from '../../lib/graph-loader';\nimport { collectProjectInfo, enrichGraph, MetadataValidationError } from '../../lib/graph-metadata';\nimport { scanAndAttachApiRelations, buildApiContracts } from '../../lib/api-usage/api-scanner';\nimport { buildExternalSystems } from '../../lib/api-usage/external-systems';\nimport type { ApiContracts, ExternalSystemDecls } from '../../lib/api-usage/api-relations';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport { RuleGate } from '../../lib/rule-gate';\nimport type { EnhancedGraph } from '../../lib/graph-sorter';\nimport { toError } from '../../toError';\n\nexport interface ValidateArchitectureUnchangedOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nconst TMP_MD_FILE = 'webpieces.dependencies.md';\n\n/**\n * Write the instructions documentation to .webpieces/instruct-ai/.\n * Sourced from @webpieces/rules-config.\n */\nfunction writeTmpInstructionsFile(workspaceRoot: string): string {\n    const mdPath = writeTemplate(workspaceRoot, TMP_MD_FILE);\n\n    return mdPath;\n}\n\n/**\n * Report a current-vs-saved graph mismatch and write the AI instructions file.\n */\nfunction reportMismatch(summary: string, workspaceRoot: string): void {\n    const mdPath = writeTmpInstructionsFile(workspaceRoot);\n\n    console.error('❌ Architecture has changed since last update!');\n    console.error('\\nDifferences:');\n    console.error(summary);\n    console.error('');\n    console.error('⚠️  *** Refer to ' + mdPath + ' for instructions on how to fix *** ⚠️');\n    console.error('');\n    console.error('To fix:');\n    console.error('  1. Review the changes above');\n    console.error('  2. If intentional, ASK USER to run: nx run architecture:generate since this is a critical change');\n    console.error('  3. Commit the updated architecture/dependencies.json');\n}\n\n/**\n * A human-readable summary of how the regenerated api contract table differs from the committed one,\n * or null when they match. Named per contract so the message points at the api that changed rather\n * than dumping two JSON blobs.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch in this file\nfunction describeContractDrift(current: ApiContracts, saved: ApiContracts): string | null {\n    const names = [...new Set([...Object.keys(current), ...Object.keys(saved)])].sort();\n    const changes: string[] = [];\n    for (const name of names) {\n        const a = current[name];\n        const b = saved[name];\n        if (a === undefined) changes.push(`  - ${name}: in dependencies.json but no longer in source`);\n        else if (b === undefined) changes.push(`  + ${name}: in source but missing from dependencies.json`);\n        else if (JSON.stringify(a) !== JSON.stringify(b)) changes.push(`  ~ ${name}: endpoints/kinds/queues changed`);\n    }\n    if (changes.length === 0) return null;\n    return `apiContracts drift (${changes.length} contract(s)):\\n${changes.join('\\n')}`;\n}\n\n/**\n * Drift in EITHER side table of dependencies.json — the api contracts or the external-system\n * declarations — or null when both match. The first difference found is reported; fixing it is the\n * same single command either way, so listing both adds noise rather than information.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches describeContractDrift above\nfunction describeTableDrift(current: CurrentArchitecture, saved: DependenciesFile): string | null {\n    const contractDrift = describeContractDrift(current.apiContracts, saved.apiContracts);\n    if (contractDrift !== null) return contractDrift;\n    return describeExternalSystemDrift(current.externalSystems, saved.externalSystems);\n}\n\n/**\n * The same drift report for the declared external systems, or null when they match. Named per\n * system so the message points at the database that changed rather than dumping two JSON blobs.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches describeContractDrift above\nfunction describeExternalSystemDrift(current: ExternalSystemDecls, saved: ExternalSystemDecls): string | null {\n    const names = [...new Set([...Object.keys(current), ...Object.keys(saved)])].sort();\n    const changes: string[] = [];\n    for (const name of names) {\n        const a = current[name];\n        const b = saved[name];\n        if (a === undefined) changes.push(`  - ${name}: in dependencies.json but no longer declared in source`);\n        else if (b === undefined) changes.push(`  + ${name}: declared in source but missing from dependencies.json`);\n        else if (JSON.stringify(a) !== JSON.stringify(b)) changes.push(`  ~ ${name}: kind/label/declarers changed`);\n    }\n    if (changes.length === 0) return null;\n    return `externalSystems drift (${changes.length} system(s)):\\n${changes.join('\\n')}`;\n}\n\n/**\n * Build the current dependency graph exactly as the generator does: reduce the nx\n * graph, sort into levels, enrich with metadata, and attach the derived\n * apiRelations — so this validator compares like-for-like against the committed file.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch/writeTmpInstructionsFile in this file\nasync function buildCurrentGraph(workspaceRoot: string): Promise<CurrentArchitecture> {\n    console.log('📊 Generating current dependency graph...');\n    const reducedGraph = await generateReducedGraph();\n    console.log('🔄 Computing topological layers...');\n    const currentGraph = sortGraphTopologically(reducedGraph);\n    console.log('🏷️  Enriching graph with framework + responsibilities metadata...');\n    const projectInfos = await collectProjectInfo();\n    enrichGraph(currentGraph, projectInfos, workspaceRoot);\n    console.log('🔎 Scanning source for implements/uses API relations...');\n    // The SAME externalApiPaths the generator uses: scanning without them would drop every vendor\n    // relation from the regenerated graph and report drift against a perfectly fresh file.\n    const externalApiPaths = loadRuntimeConfig(workspaceRoot).externalApiPaths;\n    const scan = scanAndAttachApiRelations(workspaceRoot, currentGraph, projectInfos, externalApiPaths);\n    return new CurrentArchitecture(\n        currentGraph,\n        buildApiContracts(scan),\n        buildExternalSystems(scan.apiIndex, projectInfos),\n    );\n}\n\n/** The regenerated graph plus the two tables beside it — everything dependencies.json holds. */\nclass CurrentArchitecture {\n    constructor(\n        public readonly graph: EnhancedGraph,\n        public readonly apiContracts: ApiContracts,\n        public readonly externalSystems: ExternalSystemDecls,\n    ) {}\n}\n\n/** The bootstrap path: there is nothing to diff against yet, so say how to create it. */\n// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch in this file\nfunction reportMissingGraph(): void {\n    console.error('❌ No saved graph found at architecture/dependencies.json');\n    console.error('');\n    console.error('To initialize:');\n    console.error('  1. Run: nx run architecture:generate');\n    console.error('  2. Run: nx run architecture:visualize');\n    console.error('  3. Manually inspect the generated graph to confirm it is the desired architecture');\n    console.error('  4. Commit architecture/dependencies.json');\n}\n\nexport default async function runExecutor(\n    options: ValidateArchitectureUnchangedOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    // Epoch-gateable: this rule diffs against the blessed architecture/dependencies.json, so\n    // \"grandfather the current drift until <epoch>\" is meaningful — hence honorEpoch = true.\n    if (new RuleGate().isDisabled(workspaceRoot, 'validate-architecture-unchanged', true)) {\n        return { success: true };\n    }\n\n    console.log('\\n🔍 Validating Architecture Unchanged\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Check if saved graph exists\n        if (!graphFileExists(workspaceRoot, graphPath)) {\n            reportMissingGraph();\n            return { success: false };\n        }\n\n        // Steps 1-3: build + enrich + scan the current graph (same pipeline the\n        // generator runs, so any drift is caught).\n        const currentGraph = await buildCurrentGraph(workspaceRoot);\n\n        // Step 4: Load saved graph\n        console.log('📂 Loading saved graph...');\n        const savedGraph = loadBlessedGraph(workspaceRoot, graphPath);\n\n        if (!savedGraph) {\n            console.error('❌ Could not load saved graph');\n            return { success: false };\n        }\n\n        // Step 5: Compare graphs\n        console.log('🔍 Comparing current graph to saved graph...');\n        const comparison = compareGraphs(currentGraph.graph, savedGraph.projects);\n\n        if (!comparison.identical) {\n            reportMismatch(comparison.summary, workspaceRoot);\n            return { success: false };\n        }\n\n        // Step 6: Compare the two side tables as well. Neither is part of the project graph, so a\n        // changed @Endpoint kind, queue name, or external-system declaration would otherwise pass\n        // here AND pass validate-runtime-architecture (which derives from this same stale file).\n        const tableDrift = describeTableDrift(currentGraph, savedGraph);\n        if (tableDrift !== null) {\n            reportMismatch(tableDrift, workspaceRoot);\n            return { success: false };\n        }\n\n        console.log('✅ Architecture unchanged - current graph matches saved graph');\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error('❌ Architecture validation failed:', error.message);\n        if (error instanceof MetadataValidationError) {\n            const mdPath = writeTemplate(workspaceRoot, 'webpieces.responsibilities.md');\n            console.error('');\n            console.error('⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️');\n        }\n        return { success: false };\n    }\n}\n"]}

package/src/executors/validate-runtime-architecture/executor.js

@@ -81,7 +81,7 @@ async function runExecutor(_options, context) {
     }
     // apiContracts comes from the SAME loaded file, so the queue/trigger data the derivation sees
     // here is byte-identical to what generate saw in memory.
-    const report = (0, runtime_graph_1.deriveRuntimeGraphReport)(depsFile.projects, hiddenProjects, depsFile.apiContracts);
+    const report = (0, runtime_graph_1.deriveRuntimeGraphReport)(depsFile.projects, hiddenProjects, depsFile.apiContracts, depsFile.externalSystems);
     const graph = report.graph;
     for (const warning of report.warnings)
         console.warn(`⚠️  ${warning}`);

package/src/executors/validate-runtime-architecture/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-runtime-architecture/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate Runtime Architecture Executor (workspace)\n *\n * Two workspace-level checks on the runtime microservice graph:\n *   1. No-cycles: every runtime cycle must be in the `allowedCycles` allowlist\n *      with an unexpired `until`; any other cycle fails the build.\n *   2. Unchanged: the freshly-assembled graph must match the committed\n *      architecture/runtime-dependencies.json (run `architecture:generate`).\n *\n * On/off + a whole-rule grace window come from webpieces.config.json\n * (rule: runtime-architecture).\n *\n * Usage: nx run architecture:validate-runtime-architecture\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { loadBlessedGraph } from '../../lib/graph-loader';\nimport {\n    deriveRuntimeGraphReport,\n    loadRuntimeGraph,\n    runtimeAdjacency,\n    runtimeGraphFileExists,\n    serializeRuntimeGraph,\n} from '../../lib/runtime-graph';\nimport type { RuntimeGraph } from '../../lib/runtime-graph';\nimport { findRuntimeCycles, cycleKey } from '../../lib/runtime-cycles';\nimport type { AllowedCycle } from '../../lib/runtime-config';\nimport { loadRuntimeConfig, runtimeReportOnly, RUNTIME_RULE_NAME } from '../../lib/runtime-config';\n\nexport interface ValidateRuntimeArchitectureOptions {\n    // Config comes from webpieces.config.json at runtime.\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n/** Allowlist keys (sorted-services -> entry) that are still in their grace window. */\nfunction activeAllowedKeys(allowed: AllowedCycle[]): Map<string, AllowedCycle> {\n    const nowSeconds = Date.now() / 1000;\n    const map = new Map<string, AllowedCycle>();\n    for (const entry of allowed) {\n        const active = entry.until === undefined || nowSeconds < entry.until;\n        if (active) map.set(cycleKey(entry.services), entry);\n    }\n    return map;\n}\n\n/** Returns disallowed-cycle messages (empty = all cycles allowed or none). */\nfunction checkCycles(graph: RuntimeGraph, allowed: AllowedCycle[]): string[] {\n    const cycles = findRuntimeCycles(runtimeAdjacency(graph));\n    if (cycles.length === 0) return [];\n\n    const activeAllow = activeAllowedKeys(allowed);\n    const problems: string[] = [];\n    for (const cycle of cycles) {\n        const entry = activeAllow.get(cycle.key);\n        if (entry) {\n            console.log(`⏳ Allowed runtime cycle [${cycle.services.join(' <-> ')}] — ${entry.reason ?? 'no reason given'}`);\n            continue;\n        }\n        problems.push(`runtime cycle: ${cycle.services.join(' -> ')} -> ${cycle.services[0]}`);\n    }\n    return problems;\n}\n\n/** Returns an unchanged-check message, or null if the committed graph matches. */\nfunction checkUnchanged(workspaceRoot: string, current: RuntimeGraph): string | null {\n    if (!runtimeGraphFileExists(workspaceRoot)) {\n        return 'No committed architecture/runtime-dependencies.json — run: nx run architecture:generate';\n    }\n    const saved = loadRuntimeGraph(workspaceRoot);\n    if (saved && serializeRuntimeGraph(saved) === serializeRuntimeGraph(current)) return null;\n    return 'Runtime graph changed since last commit — run: nx run architecture:generate and commit the result';\n}\n\nexport default async function runExecutor(\n    _options: ValidateRuntimeArchitectureOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const workspaceRoot = context.root;\n    const config = loadRuntimeConfig(workspaceRoot);\n\n    if (config.off) {\n        console.log(`\\n⏭️  Skipping ${RUNTIME_RULE_NAME} (mode: OFF)\\n`);\n        return { success: true };\n    }\n\n    console.log('\\n📡 Validating runtime microservice architecture\\n');\n    // Derive the \"current\" runtime graph from the committed dependencies.json — the SAME source\n    // architecture:generate derives from — so the unchanged-check compares like-for-like and can\n    // never fail on a clean, freshly-generated tree. (validate-architecture-unchanged separately\n    // guarantees dependencies.json itself is fresh.)\n    const depsFile = loadBlessedGraph(workspaceRoot);\n    if (depsFile === null) {\n        console.error('❌ No architecture/dependencies.json — run: nx run architecture:generate');\n        return { success: false };\n    }\n    const hiddenProjects = new Set<string>();\n    for (const name of Object.keys(depsFile.projects)) {\n        if (depsFile.projects[name].drawOnGraph === false) hiddenProjects.add(name);\n    }\n    // apiContracts comes from the SAME loaded file, so the queue/trigger data the derivation sees\n    // here is byte-identical to what generate saw in memory.\n    const report = deriveRuntimeGraphReport(depsFile.projects, hiddenProjects, depsFile.apiContracts);\n    const graph = report.graph;\n    for (const warning of report.warnings) console.warn(`⚠️  ${warning}`);\n\n    // A call site naming a service no module answers to FAILS: the contract is served in-repo, so\n    // the name is a typo or a stale rename, and the graph only ever hid it by fanning the edge out.\n    const problems: string[] = [...report.problems, ...checkCycles(graph, config.allowedCycles)];\n    const unchanged = checkUnchanged(workspaceRoot, graph);\n    if (unchanged) problems.push(unchanged);\n\n    for (const u of graph.unresolvedUses) {\n        console.log(`⚠️  ${u.service} uses \"${u.api}\" but no in-repo service implements it (external?)`);\n    }\n\n    if (problems.length === 0) {\n        console.log('✅ Runtime architecture valid (no disallowed cycles, graph unchanged)\\n');\n        return { success: true };\n    }\n\n    console.error('\\n❌ Runtime architecture validation failed:\\n');\n    for (const p of problems) console.error(`  - ${p}`);\n    console.error('\\nAllow a cycle temporarily via runtime-architecture.allowedCycles (services + reason + until) in webpieces.config.json.\\n');\n\n    const reportOnly = runtimeReportOnly(config);\n    if (reportOnly.skip) {\n        console.log(`⏳ Reported but not failing (${reportOnly.reason}).\\n`);\n        return { success: true };\n    }\n    return { success: false };\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-runtime-architecture/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate Runtime Architecture Executor (workspace)\n *\n * Two workspace-level checks on the runtime microservice graph:\n *   1. No-cycles: every runtime cycle must be in the `allowedCycles` allowlist\n *      with an unexpired `until`; any other cycle fails the build.\n *   2. Unchanged: the freshly-assembled graph must match the committed\n *      architecture/runtime-dependencies.json (run `architecture:generate`).\n *\n * On/off + a whole-rule grace window come from webpieces.config.json\n * (rule: runtime-architecture).\n *\n * Usage: nx run architecture:validate-runtime-architecture\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { loadBlessedGraph } from '../../lib/graph-loader';\nimport {\n    deriveRuntimeGraphReport,\n    loadRuntimeGraph,\n    runtimeAdjacency,\n    runtimeGraphFileExists,\n    serializeRuntimeGraph,\n} from '../../lib/runtime-graph';\nimport type { RuntimeGraph } from '../../lib/runtime-graph';\nimport { findRuntimeCycles, cycleKey } from '../../lib/runtime-cycles';\nimport type { AllowedCycle } from '../../lib/runtime-config';\nimport { loadRuntimeConfig, runtimeReportOnly, RUNTIME_RULE_NAME } from '../../lib/runtime-config';\n\nexport interface ValidateRuntimeArchitectureOptions {\n    // Config comes from webpieces.config.json at runtime.\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n/** Allowlist keys (sorted-services -> entry) that are still in their grace window. */\nfunction activeAllowedKeys(allowed: AllowedCycle[]): Map<string, AllowedCycle> {\n    const nowSeconds = Date.now() / 1000;\n    const map = new Map<string, AllowedCycle>();\n    for (const entry of allowed) {\n        const active = entry.until === undefined || nowSeconds < entry.until;\n        if (active) map.set(cycleKey(entry.services), entry);\n    }\n    return map;\n}\n\n/** Returns disallowed-cycle messages (empty = all cycles allowed or none). */\nfunction checkCycles(graph: RuntimeGraph, allowed: AllowedCycle[]): string[] {\n    const cycles = findRuntimeCycles(runtimeAdjacency(graph));\n    if (cycles.length === 0) return [];\n\n    const activeAllow = activeAllowedKeys(allowed);\n    const problems: string[] = [];\n    for (const cycle of cycles) {\n        const entry = activeAllow.get(cycle.key);\n        if (entry) {\n            console.log(`⏳ Allowed runtime cycle [${cycle.services.join(' <-> ')}] — ${entry.reason ?? 'no reason given'}`);\n            continue;\n        }\n        problems.push(`runtime cycle: ${cycle.services.join(' -> ')} -> ${cycle.services[0]}`);\n    }\n    return problems;\n}\n\n/** Returns an unchanged-check message, or null if the committed graph matches. */\nfunction checkUnchanged(workspaceRoot: string, current: RuntimeGraph): string | null {\n    if (!runtimeGraphFileExists(workspaceRoot)) {\n        return 'No committed architecture/runtime-dependencies.json — run: nx run architecture:generate';\n    }\n    const saved = loadRuntimeGraph(workspaceRoot);\n    if (saved && serializeRuntimeGraph(saved) === serializeRuntimeGraph(current)) return null;\n    return 'Runtime graph changed since last commit — run: nx run architecture:generate and commit the result';\n}\n\nexport default async function runExecutor(\n    _options: ValidateRuntimeArchitectureOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const workspaceRoot = context.root;\n    const config = loadRuntimeConfig(workspaceRoot);\n\n    if (config.off) {\n        console.log(`\\n⏭️  Skipping ${RUNTIME_RULE_NAME} (mode: OFF)\\n`);\n        return { success: true };\n    }\n\n    console.log('\\n📡 Validating runtime microservice architecture\\n');\n    // Derive the \"current\" runtime graph from the committed dependencies.json — the SAME source\n    // architecture:generate derives from — so the unchanged-check compares like-for-like and can\n    // never fail on a clean, freshly-generated tree. (validate-architecture-unchanged separately\n    // guarantees dependencies.json itself is fresh.)\n    const depsFile = loadBlessedGraph(workspaceRoot);\n    if (depsFile === null) {\n        console.error('❌ No architecture/dependencies.json — run: nx run architecture:generate');\n        return { success: false };\n    }\n    const hiddenProjects = new Set<string>();\n    for (const name of Object.keys(depsFile.projects)) {\n        if (depsFile.projects[name].drawOnGraph === false) hiddenProjects.add(name);\n    }\n    // apiContracts comes from the SAME loaded file, so the queue/trigger data the derivation sees\n    // here is byte-identical to what generate saw in memory.\n    const report = deriveRuntimeGraphReport(\n        depsFile.projects,\n        hiddenProjects,\n        depsFile.apiContracts,\n        depsFile.externalSystems,\n    );\n    const graph = report.graph;\n    for (const warning of report.warnings) console.warn(`⚠️  ${warning}`);\n\n    // A call site naming a service no module answers to FAILS: the contract is served in-repo, so\n    // the name is a typo or a stale rename, and the graph only ever hid it by fanning the edge out.\n    const problems: string[] = [...report.problems, ...checkCycles(graph, config.allowedCycles)];\n    const unchanged = checkUnchanged(workspaceRoot, graph);\n    if (unchanged) problems.push(unchanged);\n\n    for (const u of graph.unresolvedUses) {\n        console.log(`⚠️  ${u.service} uses \"${u.api}\" but no in-repo service implements it (external?)`);\n    }\n\n    if (problems.length === 0) {\n        console.log('✅ Runtime architecture valid (no disallowed cycles, graph unchanged)\\n');\n        return { success: true };\n    }\n\n    console.error('\\n❌ Runtime architecture validation failed:\\n');\n    for (const p of problems) console.error(`  - ${p}`);\n    console.error('\\nAllow a cycle temporarily via runtime-architecture.allowedCycles (services + reason + until) in webpieces.config.json.\\n');\n\n    const reportOnly = runtimeReportOnly(config);\n    if (reportOnly.skip) {\n        console.log(`⏳ Reported but not failing (${reportOnly.reason}).\\n`);\n        return { success: true };\n    }\n    return { success: false };\n}\n"]}

package/src/lib/api-usage/api-ast.d.ts

@@ -10,7 +10,7 @@
  * api-scanner's source pre-pass exists to guard against.
  */
 import * as ts from 'typescript';
-import { ApiClassInfo, ApiMethodMeta, ApiTransport, EmptiedApiContract, NonLiteralDecoratorArg, UnresolvedEndpointPath } from './api-relations';
+import { ApiClassInfo, ApiMethodMeta, ApiTransport, EmptiedApiContract, ExternalSystemDeclaration, NonLiteralDecoratorArg, UnresolvedEndpointPath } from './api-relations';
 /**
  * The module-scope `const NAME = '<string literal>'` bindings of ONE source file.
  *
@@ -151,6 +151,22 @@ export declare function apiClassInfoFromNode(node: ts.Node, project: string, dia
  * `StorageApi` while leaving their DTOs, `*Config` types and `*Client` implementations alone.
  */
 export declare function externalApiInfoFrom(node: ts.Node, project: string): ApiClassInfo | null;
+/**
+ * The `@externalSystem <kind> [label]` JSDoc tag on a vendor contract, or null when absent.
+ *
+ * JSDoc rather than a decorator is not a style choice: these seams are TS `interface`s, and TS has
+ * no interface decorators. Without the tag the contract still renders — as the generic dashed box it
+ * always was — so this is purely additive and nothing needs migrating.
+ *
+ * The label defaults to the contract name minus its `Api` suffix (`FirestoreAdminApi` →
+ * `FirestoreAdmin`), because the label is the node IDENTITY: two contracts that mean the same system
+ * must be given the SAME explicit label to converge on one node.
+ *
+ * An unrecognised kind is ignored rather than defaulted. Silently drawing a `@externalSystem
+ * databse` typo as a generic box is recoverable; drawing it as the wrong shape teaches the reader
+ * something false about the architecture.
+ */
+export declare function externalSystemTagFrom(node: ts.Node, api: string): ExternalSystemDeclaration | null;
 /** True when the declaration carries an `export` modifier. */
 export declare function isExported(node: ts.InterfaceDeclaration | ts.ClassDeclaration): boolean;
 export declare function collectTsFiles(dir: string): string[];

package/src/lib/api-usage/api-ast.js

@@ -33,6 +33,7 @@ exports.calleeMethodName = calleeMethodName;
 exports.isTestFile = isTestFile;
 exports.apiClassInfoFromNode = apiClassInfoFromNode;
 exports.externalApiInfoFrom = externalApiInfoFrom;
+exports.externalSystemTagFrom = externalSystemTagFrom;
 exports.isExported = isExported;
 exports.collectTsFiles = collectTsFiles;
 const tslib_1 = require("tslib");
@@ -49,6 +50,8 @@ const ENDPOINT_KINDS = ['rpc', 'cloudtasks', 'cron', 'external'];
  * The same convention the in-repo contracts already follow, applied where no decorator can be read.
  */
 const EXTERNAL_CONTRACT_SUFFIX = 'Api';
+/** JSDoc tag a vendor contract uses to declare WHAT it is a seam to: `@externalSystem database Firestore`. */
+const EXTERNAL_SYSTEM_TAG = 'externalSystem';
 /**
  * Client-config class-name suffix whose FIRST constructor argument is the target service name —
  * `ClientConfig('helper-fsdb')` (rpc) and `TaskClientConfig('helper-fsdb')` (pubsub) both take
@@ -426,7 +429,42 @@ function externalApiInfoFrom(node, project) {
     const api = node.name.text;
     if (!api.endsWith(EXTERNAL_CONTRACT_SUFFIX))
         return null;
-    return { api, owner: project, type: 'external', methods: [] };
+    const externalSystem = externalSystemTagFrom(node, api);
+    return externalSystem === null
+        ? { api, owner: project, type: 'external', methods: [] }
+        : { api, owner: project, type: 'external', methods: [], externalSystem };
+}
+/**
+ * The `@externalSystem <kind> [label]` JSDoc tag on a vendor contract, or null when absent.
+ *
+ * JSDoc rather than a decorator is not a style choice: these seams are TS `interface`s, and TS has
+ * no interface decorators. Without the tag the contract still renders — as the generic dashed box it
+ * always was — so this is purely additive and nothing needs migrating.
+ *
+ * The label defaults to the contract name minus its `Api` suffix (`FirestoreAdminApi` →
+ * `FirestoreAdmin`), because the label is the node IDENTITY: two contracts that mean the same system
+ * must be given the SAME explicit label to converge on one node.
+ *
+ * An unrecognised kind is ignored rather than defaulted. Silently drawing a `@externalSystem
+ * databse` typo as a generic box is recoverable; drawing it as the wrong shape teaches the reader
+ * something false about the architecture.
+ */
+// webpieces-disable no-function-outside-class -- pure AST accessor, matching the sibling helpers in di-graph/bindings.ts
+function externalSystemTagFrom(node, api) {
+    for (const tag of ts.getJSDocTags(node)) {
+        if (tag.tagName.text !== EXTERNAL_SYSTEM_TAG)
+            continue;
+        const comment = typeof tag.comment === 'string' ? tag.comment : '';
+        const parts = comment.trim().split(/\s+/).filter((part) => part !== '');
+        if (parts.length === 0)
+            continue;
+        const kind = parts[0].toLowerCase();
+        if (!(0, api_relations_1.isExternalSystemKind)(kind))
+            continue;
+        const label = parts.slice(1).join(' ').trim();
+        return { kind, label: label === '' ? api.replace(/Api$/, '') : label };
+    }
+    return null;
 }
 /** True when the declaration carries an `export` modifier. */
 // webpieces-disable no-function-outside-class -- pure AST predicate, matching the sibling helpers in di-graph/bindings.ts