@webpieces/nx-webpieces-rules 0.4.486 → 0.4.488

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/nx-webpieces-rules",
-  "version": "0.4.486",
+  "version": "0.4.488",
   "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.4.486",
-    "@webpieces/code-rules": "0.4.486",
-    "@webpieces/eslint-rules": "0.4.486",
-    "@webpieces/pr-gate": "0.4.486",
-    "@webpieces/rules-config": "0.4.486",
+    "@webpieces/ai-hook-rules": "0.4.488",
+    "@webpieces/code-rules": "0.4.488",
+    "@webpieces/eslint-rules": "0.4.488",
+    "@webpieces/pr-gate": "0.4.488",
+    "@webpieces/rules-config": "0.4.488",
     "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 runtime_config_1 = require("../../lib/runtime-config");
 const graph_visualizer_1 = require("../../lib/graph-visualizer");
 const runtime_graph_1 = require("../../lib/runtime-graph");
 const toError_1 = require("../../toError");
@@ -25,12 +26,14 @@ 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) {
+function generateRuntimeGraph(workspaceRoot, graph, hiddenProjects, apiContracts) {
     console.log('📡 Deriving runtime graph from dependencies.json (implements × uses per API)...');
-    const report = (0, runtime_graph_1.deriveRuntimeGraphReport)(graph, hiddenProjects);
+    const report = (0, runtime_graph_1.deriveRuntimeGraphReport)(graph, hiddenProjects, apiContracts);
     (0, runtime_graph_1.saveRuntimeGraph)(report.graph, workspaceRoot);
     const serviceCount = Object.keys(report.graph.services).length;
-    console.log(`✅ Runtime graph saved (${serviceCount} services, ${report.graph.runtimeEdges.length} runtime edges)`);
+    const queueCount = Object.keys(report.graph.queues).length;
+    console.log(`✅ Runtime graph saved (${serviceCount} services, ${report.graph.runtimeEdges.length} runtime edges, ` +
+        `${queueCount} queues, ${report.graph.triggers.length} cron/external triggers)`);
     // Every edge the derivation had to GUESS at. Loud on purpose: a fanned-out edge is committed and
     // then reasoned about as if it were derived, which is how a fictional call survives for months.
     printRuntimeWarnings(report.warnings);
@@ -60,9 +63,37 @@ function printRuntimeWarnings(warnings) {
 // webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file
 function scanApiRelations(workspaceRoot, graph, projectInfos) {
     console.log('🔎 Scanning source for implements/uses API relations...');
-    const scan = (0, api_scanner_1.scanAndAttachApiRelations)(workspaceRoot, graph, projectInfos);
+    const externalApiPaths = (0, runtime_config_1.loadRuntimeConfig)(workspaceRoot).externalApiPaths;
+    const scan = (0, api_scanner_1.scanAndAttachApiRelations)(workspaceRoot, graph, projectInfos, externalApiPaths);
     if (scan.unresolvedApiCalls.length > 0)
         console.warn((0, api_scanner_1.describeUnresolvedApiCalls)(scan.unresolvedApiCalls));
+    const contracts = (0, api_scanner_1.buildApiContracts)(scan);
+    // An endpoint whose declared trigger its api kind cannot deliver would silently draw a queue or a
+    // clock that nothing could ever fire — name it here, where the fix is one decorator away.
+    const mismatches = (0, api_scanner_1.describeMismatchedEndpointKinds)(contracts);
+    if (mismatches.length > 0) {
+        console.error(`❌ ${mismatches.length} @Endpoint kind(s) conflict with their api kind:`);
+        for (const mismatch of mismatches)
+            console.error(`     • ${mismatch}`);
+    }
+    return contracts;
+}
+/** 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
+function hiddenProjectsIn(graph) {
+    const hidden = new Set();
+    for (const name of Object.keys(graph)) {
+        if (graph[name].drawOnGraph === false)
+            hidden.add(name);
+    }
+    return hidden;
+}
+// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file
+function printGraphSummary(graph) {
+    const levels = new Set(Object.values(graph).map((entry) => entry.level));
+    console.log(`\n📈 Graph Summary:`);
+    console.log(`   Projects: ${Object.keys(graph).length}`);
+    console.log(`   Levels: ${levels.size} (0-${Math.max(...levels)})`);
 }
 async function runExecutor(options, context) {
     const graphPath = options.graphPath;
@@ -85,10 +116,12 @@ async function runExecutor(options, context) {
         // 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.
-        scanApiRelations(workspaceRoot, enhancedGraph, projectInfos);
-        // Step 4: Save the graph
+        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);
+        (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.
@@ -97,18 +130,8 @@ async function runExecutor(options, context) {
         // 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).
-        const hiddenProjects = new Set();
-        for (const name of Object.keys(enhancedGraph)) {
-            if (enhancedGraph[name].drawOnGraph === false)
-                hiddenProjects.add(name);
-        }
-        generateRuntimeGraph(workspaceRoot, enhancedGraph, hiddenProjects);
-        // Print summary
-        const projectCount = Object.keys(enhancedGraph).length;
-        const levels = new Set(Object.values(enhancedGraph).map((e) => e.level));
-        console.log(`\n📈 Graph Summary:`);
-        console.log(`   Projects: ${projectCount}`);
-        console.log(`   Levels: ${levels.size} (0-${Math.max(...levels)})`);
+        generateRuntimeGraph(workspaceRoot, enhancedGraph, hiddenProjectsIn(enhancedGraph), apiContracts);
+        printGraphSummary(enhancedGraph);
         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":";AAAA;;;;;;;GAOG;;AAsEH,8BAoEC;AAvID,0DAAwD;AACxD,+DAAiE;AACjE,yDAAgE;AAChE,yDAAmD;AACnD,6DAAoG;AAEpG,iEAAwG;AAExG,iEAA6D;AAC7D,2DAAqF;AACrF,2CAAwC;AAUxC;;;;;GAKG;AACH,2GAA2G;AAC3G,SAAS,oBAAoB,CAAC,aAAqB,EAAE,KAAoB,EAAE,cAA2B;IAClG,OAAO,CAAC,GAAG,CAAC,iFAAiF,CAAC,CAAC;IAC/F,MAAM,MAAM,GAAG,IAAA,wCAAwB,EAAC,KAAK,EAAE,cAAc,CAAC,CAAC;IAC/D,IAAA,gCAAgB,EAAC,MAAM,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IAC9C,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC;IAC/D,OAAO,CAAC,GAAG,CACP,0BAA0B,YAAY,cAAc,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,iBAAiB,CACxG,CAAC;IACF,iGAAiG;IACjG,gGAAgG;IAChG,oBAAoB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACtC,8FAA8F;IAC9F,2FAA2F;IAC3F,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,QAAQ,CAAC,MAAM,sDAAsD,CAAC,CAAC;QACjG,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ;YAAE,OAAO,CAAC,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAC;QAC1E,OAAO,CAAC,KAAK,CAAC,2DAA2D,CAAC,CAAC;IAC/E,CAAC;AACL,CAAC;AAED,sGAAsG;AACtG,2GAA2G;AAC3G,SAAS,oBAAoB,CAAC,QAAkB;IAC5C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAClC,OAAO,CAAC,IAAI,CAAC,OAAO,QAAQ,CAAC,MAAM,wDAAwD,CAAC,CAAC;IAC7F,KAAK,MAAM,OAAO,IAAI,QAAQ;QAAE,OAAO,CAAC,IAAI,CAAC,UAAU,OAAO,EAAE,CAAC,CAAC;AACtE,CAAC;AAED;;;;GAIG;AACH,2GAA2G;AAC3G,SAAS,gBAAgB,CAAC,aAAqB,EAAE,KAAoB,EAAE,YAAsC;IACzG,OAAO,CAAC,GAAG,CAAC,yDAAyD,CAAC,CAAC;IACvE,MAAM,IAAI,GAAG,IAAA,uCAAyB,EAAC,aAAa,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;IAC3E,IAAI,IAAI,CAAC,kBAAkB,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,IAAA,wCAA0B,EAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAC9G,CAAC;AAEc,KAAK,UAAU,WAAW,CACrC,OAAgC,EAChC,OAAwB;IAExB,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACpC,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC,OAAO,CAAC,GAAG,CAAC,qCAAqC,CAAC,CAAC;IAEnD,8DAA8D;IAC9D,IAAI,CAAC;QACD,gFAAgF;QAChF,OAAO,CAAC,GAAG,CAAC,2DAA2D,CAAC,CAAC;QACzE,MAAM,YAAY,GAAG,MAAM,IAAA,sCAAoB,GAAE,CAAC;QAElD,gEAAgE;QAChE,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;QAClD,MAAM,aAAa,GAAG,IAAA,qCAAsB,EAAC,YAAY,CAAC,CAAC;QAE3D,qEAAqE;QACrE,uEAAuE;QACvE,qEAAqE;QACrE,OAAO,CAAC,GAAG,CAAC,oEAAoE,CAAC,CAAC;QAClF,MAAM,YAAY,GAAG,MAAM,IAAA,mCAAkB,GAAE,CAAC;QAChD,IAAA,4BAAW,EAAC,aAAa,EAAE,YAAY,EAAE,aAAa,CAAC,CAAC;QAExD,wEAAwE;QACxE,0EAA0E;QAC1E,+BAA+B;QAC/B,gBAAgB,CAAC,aAAa,EAAE,aAAa,EAAE,YAAY,CAAC,CAAC;QAE7D,yBAAyB;QACzB,OAAO,CAAC,GAAG,CAAC,sDAAsD,CAAC,CAAC;QACpE,IAAA,wBAAS,EAAC,aAAa,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC;QACnD,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;QAE1C,wEAAwE;QACxE,qEAAqE;QACrE,MAAM,QAAQ,GAAG,IAAI,kCAAe,EAAE,CAAC,kBAAkB,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;QACxF,OAAO,CAAC,GAAG,CAAC,WAAW,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QAE5C,sEAAsE;QACtE,wEAAwE;QACxE,yEAAyE;QACzE,MAAM,cAAc,GAAG,IAAI,GAAG,EAAU,CAAC;QACzC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;YAC5C,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC,WAAW,KAAK,KAAK;gBAAE,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC5E,CAAC;QACD,oBAAoB,CAAC,aAAa,EAAE,aAAa,EAAE,cAAc,CAAC,CAAC;QAEnE,gBAAgB;QAChB,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC;QACvD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QACzE,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;QACnC,OAAO,CAAC,GAAG,CAAC,gBAAgB,YAAY,EAAE,CAAC,CAAC;QAC5C,OAAO,CAAC,GAAG,CAAC,cAAc,MAAM,CAAC,IAAI,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAEpE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,KAAK,CAAC,4BAA4B,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAC3D,IAAI,KAAK,YAAY,wCAAuB,EAAE,CAAC;YAC3C,MAAM,MAAM,GAAG,IAAA,4BAAa,EAAC,aAAa,EAAE,+BAA+B,CAAC,CAAC;YAC7E,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAClB,OAAO,CAAC,KAAK,CAAC,mBAAmB,GAAG,MAAM,GAAG,qDAAqD,CAAC,CAAC;QACxG,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC","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 { scanAndAttachApiRelations, describeUnresolvedApiCalls } from '../../lib/api-usage/api-scanner';\nimport type { EnhancedGraph } 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(workspaceRoot: string, graph: EnhancedGraph, hiddenProjects: Set<string>): void {\n    console.log('📡 Deriving runtime graph from dependencies.json (implements × uses per API)...');\n    const report = deriveRuntimeGraphReport(graph, hiddenProjects);\n    saveRuntimeGraph(report.graph, workspaceRoot);\n    const serviceCount = Object.keys(report.graph.services).length;\n    console.log(\n        `✅ Runtime graph saved (${serviceCount} services, ${report.graph.runtimeEdges.length} runtime edges)`,\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(workspaceRoot: string, graph: EnhancedGraph, projectInfos: Map<string, ProjectInfo>): void {\n    console.log('🔎 Scanning source for implements/uses API relations...');\n    const scan = scanAndAttachApiRelations(workspaceRoot, graph, projectInfos);\n    if (scan.unresolvedApiCalls.length > 0) console.warn(describeUnresolvedApiCalls(scan.unresolvedApiCalls));\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        scanApiRelations(workspaceRoot, enhancedGraph, projectInfos);\n\n        // Step 4: Save the graph\n        console.log('💾 Saving graph to architecture/dependencies.json...');\n        saveGraph(enhancedGraph, workspaceRoot, graphPath);\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        const hiddenProjects = new Set<string>();\n        for (const name of Object.keys(enhancedGraph)) {\n            if (enhancedGraph[name].drawOnGraph === false) hiddenProjects.add(name);\n        }\n        generateRuntimeGraph(workspaceRoot, enhancedGraph, hiddenProjects);\n\n        // Print summary\n        const projectCount = Object.keys(enhancedGraph).length;\n        const levels = new Set(Object.values(enhancedGraph).map((e) => e.level));\n        console.log(`\\n📈 Graph Summary:`);\n        console.log(`   Projects: ${projectCount}`);\n        console.log(`   Levels: ${levels.size} (0-${Math.max(...levels)})`);\n\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    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    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"]}

package/src/executors/validate-api-relations/executor.js

@@ -16,6 +16,7 @@ const graph_generator_1 = require("../../lib/graph-generator");
 const graph_sorter_1 = require("../../lib/graph-sorter");
 const graph_metadata_1 = require("../../lib/graph-metadata");
 const api_scanner_1 = require("../../lib/api-usage/api-scanner");
+const runtime_config_1 = require("../../lib/runtime-config");
 const api_relations_validator_1 = require("../../lib/api-usage/api-relations-validator");
 const toError_1 = require("../../toError");
 // webpieces-disable no-function-outside-class -- nx executor entry point (default export), like every sibling executor
@@ -29,7 +30,11 @@ async function runExecutor(_options, context) {
         const rawGraph = await (0, graph_generator_1.generateGraph)();
         const graph = (0, graph_sorter_1.sortGraphTopologically)(rawGraph);
         const projectInfos = await (0, graph_metadata_1.collectProjectInfo)();
-        const scan = (0, api_scanner_1.scanAndAttachApiRelations)(workspaceRoot, graph, projectInfos);
+        // Same externalApiPaths as generate: a vendor lib must be classified by the SAME rules here,
+        // or a server depending on one would be reported unclassified purely because this scan was
+        // configured differently from the one that wrote the graph.
+        const externalApiPaths = (0, runtime_config_1.loadRuntimeConfig)(workspaceRoot).externalApiPaths;
+        const scan = (0, api_scanner_1.scanAndAttachApiRelations)(workspaceRoot, graph, projectInfos, externalApiPaths);
         const violations = (0, api_relations_validator_1.findUnclassifiedApiDeps)(graph, projectInfos, scan);
         if (violations.length === 0) {
             console.log('✅ Every server/client api-lib dependency is implemented or used.');

package/src/executors/validate-api-relations/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-api-relations/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;AAmBH,8BAkCC;AAlDD,+DAA0D;AAC1D,yDAAgE;AAChE,6DAA8D;AAC9D,iEAA4E;AAC5E,yFAAkH;AAClH,2CAAwC;AAUxC,uHAAuH;AACxG,KAAK,UAAU,WAAW,CACrC,QAAqC,EACrC,OAAwB;IAExB,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC,OAAO,CAAC,GAAG,CAAC,0EAA0E,CAAC,CAAC;IAExF,8DAA8D;IAC9D,IAAI,CAAC;QACD,4EAA4E;QAC5E,8DAA8D;QAC9D,MAAM,QAAQ,GAAG,MAAM,IAAA,+BAAa,GAAE,CAAC;QACvC,MAAM,KAAK,GAAG,IAAA,qCAAsB,EAAC,QAAQ,CAAC,CAAC;QAC/C,MAAM,YAAY,GAAG,MAAM,IAAA,mCAAkB,GAAE,CAAC;QAChD,MAAM,IAAI,GAAG,IAAA,uCAAyB,EAAC,aAAa,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;QAE3E,MAAM,UAAU,GAAG,IAAA,iDAAuB,EAAC,KAAK,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC;QACtE,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,CAAC,GAAG,CAAC,kEAAkE,CAAC,CAAC;YAChF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC7B,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,KAAK,UAAU,CAAC,MAAM,wCAAwC,CAAC,CAAC;QAC9E,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACjC,OAAO,CAAC,KAAK,CAAC,IAAA,oDAA0B,EAAC,SAAS,CAAC,CAAC,CAAC;YACrD,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,KAAK,CAAC,oCAAoC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QACnE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC","sourcesContent":["/**\n * Validate API Relations Executor\n *\n * Fails when a runnable project (role:server / role:client) depends on an api-lib\n * but the source scan finds it neither IMPLEMENTS (serves via addRoutes) nor USES\n * (calls via createRpcClient/createPubSubClient) any of that api-lib's contracts.\n * Such an edge is an unexplained dependency — a dead import or forgotten wiring.\n *\n * Usage:\n * nx run architecture:validate-api-relations\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { generateGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { collectProjectInfo } from '../../lib/graph-metadata';\nimport { scanAndAttachApiRelations } from '../../lib/api-usage/api-scanner';\nimport { findUnclassifiedApiDeps, describeUnclassifiedApiDep } from '../../lib/api-usage/api-relations-validator';\nimport { toError } from '../../toError';\n\nexport interface ValidateApiRelationsOptions {\n    // No options needed\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n// webpieces-disable no-function-outside-class -- nx executor entry point (default export), like every sibling executor\nexport default async function runExecutor(\n    _options: ValidateApiRelationsOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const workspaceRoot = context.root;\n\n    console.log('\\n🔗 Validating API Relations (implements/uses per api-lib dependency)\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Full (un-reduced) graph so a direct api-lib dependency is never hidden by\n        // transitive reduction, then attach the derived apiRelations.\n        const rawGraph = await generateGraph();\n        const graph = sortGraphTopologically(rawGraph);\n        const projectInfos = await collectProjectInfo();\n        const scan = scanAndAttachApiRelations(workspaceRoot, graph, projectInfos);\n\n        const violations = findUnclassifiedApiDeps(graph, projectInfos, scan);\n        if (violations.length === 0) {\n            console.log('✅ Every server/client api-lib dependency is implemented or used.');\n            return { success: true };\n        }\n\n        console.error(`❌ ${violations.length} unexplained api-lib dependenc(ies):\\n`);\n        for (const violation of violations) {\n            console.error(describeUnclassifiedApiDep(violation));\n            console.error('');\n        }\n        return { success: false };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error('❌ API relations validation failed:', error.message);\n        return { success: false };\n    }\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-api-relations/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;AAoBH,8BAsCC;AAvDD,+DAA0D;AAC1D,yDAAgE;AAChE,6DAA8D;AAC9D,iEAA4E;AAC5E,6DAA6D;AAC7D,yFAAkH;AAClH,2CAAwC;AAUxC,uHAAuH;AACxG,KAAK,UAAU,WAAW,CACrC,QAAqC,EACrC,OAAwB;IAExB,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC,OAAO,CAAC,GAAG,CAAC,0EAA0E,CAAC,CAAC;IAExF,8DAA8D;IAC9D,IAAI,CAAC;QACD,4EAA4E;QAC5E,8DAA8D;QAC9D,MAAM,QAAQ,GAAG,MAAM,IAAA,+BAAa,GAAE,CAAC;QACvC,MAAM,KAAK,GAAG,IAAA,qCAAsB,EAAC,QAAQ,CAAC,CAAC;QAC/C,MAAM,YAAY,GAAG,MAAM,IAAA,mCAAkB,GAAE,CAAC;QAChD,6FAA6F;QAC7F,2FAA2F;QAC3F,4DAA4D;QAC5D,MAAM,gBAAgB,GAAG,IAAA,kCAAiB,EAAC,aAAa,CAAC,CAAC,gBAAgB,CAAC;QAC3E,MAAM,IAAI,GAAG,IAAA,uCAAyB,EAAC,aAAa,EAAE,KAAK,EAAE,YAAY,EAAE,gBAAgB,CAAC,CAAC;QAE7F,MAAM,UAAU,GAAG,IAAA,iDAAuB,EAAC,KAAK,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC;QACtE,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,CAAC,GAAG,CAAC,kEAAkE,CAAC,CAAC;YAChF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC7B,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,KAAK,UAAU,CAAC,MAAM,wCAAwC,CAAC,CAAC;QAC9E,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACjC,OAAO,CAAC,KAAK,CAAC,IAAA,oDAA0B,EAAC,SAAS,CAAC,CAAC,CAAC;YACrD,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,KAAK,CAAC,oCAAoC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QACnE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC","sourcesContent":["/**\n * Validate API Relations Executor\n *\n * Fails when a runnable project (role:server / role:client) depends on an api-lib\n * but the source scan finds it neither IMPLEMENTS (serves via addRoutes) nor USES\n * (calls via createRpcClient/createPubSubClient) any of that api-lib's contracts.\n * Such an edge is an unexplained dependency — a dead import or forgotten wiring.\n *\n * Usage:\n * nx run architecture:validate-api-relations\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { generateGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { collectProjectInfo } from '../../lib/graph-metadata';\nimport { scanAndAttachApiRelations } from '../../lib/api-usage/api-scanner';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport { findUnclassifiedApiDeps, describeUnclassifiedApiDep } from '../../lib/api-usage/api-relations-validator';\nimport { toError } from '../../toError';\n\nexport interface ValidateApiRelationsOptions {\n    // No options needed\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n// webpieces-disable no-function-outside-class -- nx executor entry point (default export), like every sibling executor\nexport default async function runExecutor(\n    _options: ValidateApiRelationsOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const workspaceRoot = context.root;\n\n    console.log('\\n🔗 Validating API Relations (implements/uses per api-lib dependency)\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Full (un-reduced) graph so a direct api-lib dependency is never hidden by\n        // transitive reduction, then attach the derived apiRelations.\n        const rawGraph = await generateGraph();\n        const graph = sortGraphTopologically(rawGraph);\n        const projectInfos = await collectProjectInfo();\n        // Same externalApiPaths as generate: a vendor lib must be classified by the SAME rules here,\n        // or a server depending on one would be reported unclassified purely because this scan was\n        // configured differently from the one that wrote the graph.\n        const externalApiPaths = loadRuntimeConfig(workspaceRoot).externalApiPaths;\n        const scan = scanAndAttachApiRelations(workspaceRoot, graph, projectInfos, externalApiPaths);\n\n        const violations = findUnclassifiedApiDeps(graph, projectInfos, scan);\n        if (violations.length === 0) {\n            console.log('✅ Every server/client api-lib dependency is implemented or used.');\n            return { success: true };\n        }\n\n        console.error(`❌ ${violations.length} unexplained api-lib dependenc(ies):\\n`);\n        for (const violation of violations) {\n            console.error(describeUnclassifiedApiDep(violation));\n            console.error('');\n        }\n        return { success: false };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error('❌ API relations validation failed:', error.message);\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 runtime_config_1 = require("../../lib/runtime-config");
 const rule_gate_1 = require("../../lib/rule-gate");
 const toError_1 = require("../../toError");
 const TMP_MD_FILE = 'webpieces.dependencies.md';
@@ -44,6 +45,29 @@ function reportMismatch(summary, workspaceRoot) {
     console.error('  2. If intentional, ASK USER to run: nx run architecture:generate since this is a critical change');
     console.error('  3. Commit the updated architecture/dependencies.json');
 }
+/**
+ * A human-readable summary of how the regenerated api contract table differs from the committed one,
+ * or null when they match. Named per contract so the message points at the api that changed rather
+ * than dumping two JSON blobs.
+ */
+// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch in this file
+function describeContractDrift(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 in source`);
+        else if (b === undefined)
+            changes.push(`  + ${name}: in source but missing from dependencies.json`);
+        else if (JSON.stringify(a) !== JSON.stringify(b))
+            changes.push(`  ~ ${name}: endpoints/kinds/queues changed`);
+    }
+    if (changes.length === 0)
+        return null;
+    return `apiContracts drift (${changes.length} contract(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
@@ -59,8 +83,31 @@ async function buildCurrentGraph(workspaceRoot) {
     const projectInfos = await (0, graph_metadata_1.collectProjectInfo)();
     (0, graph_metadata_1.enrichGraph)(currentGraph, projectInfos, workspaceRoot);
     console.log('🔎 Scanning source for implements/uses API relations...');
-    (0, api_scanner_1.scanAndAttachApiRelations)(workspaceRoot, currentGraph, projectInfos);
-    return currentGraph;
+    // The SAME externalApiPaths the generator uses: scanning without them would drop every vendor
+    // 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));
+}
+/** The regenerated graph plus its api contract table — both halves of what dependencies.json holds. */
+class CurrentArchitecture {
+    graph;
+    apiContracts;
+    constructor(graph, apiContracts) {
+        this.graph = graph;
+        this.apiContracts = apiContracts;
+    }
+}
+/** The bootstrap path: there is nothing to diff against yet, so say how to create it. */
+// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch in this file
+function reportMissingGraph() {
+    console.error('❌ No saved graph found at architecture/dependencies.json');
+    console.error('');
+    console.error('To initialize:');
+    console.error('  1. Run: nx run architecture:generate');
+    console.error('  2. Run: nx run architecture:visualize');
+    console.error('  3. Manually inspect the generated graph to confirm it is the desired architecture');
+    console.error('  4. Commit architecture/dependencies.json');
 }
 async function runExecutor(options, context) {
     const graphPath = options.graphPath;
@@ -75,13 +122,7 @@ async function runExecutor(options, context) {
     try {
         // Check if saved graph exists
         if (!(0, graph_loader_1.graphFileExists)(workspaceRoot, graphPath)) {
-            console.error('❌ No saved graph found at architecture/dependencies.json');
-            console.error('');
-            console.error('To initialize:');
-            console.error('  1. Run: nx run architecture:generate');
-            console.error('  2. Run: nx run architecture:visualize');
-            console.error('  3. Manually inspect the generated graph to confirm it is the desired architecture');
-            console.error('  4. Commit architecture/dependencies.json');
+            reportMissingGraph();
             return { success: false };
         }
         // Steps 1-3: build + enrich + scan the current graph (same pipeline the
@@ -96,13 +137,22 @@ async function runExecutor(options, context) {
         }
         // Step 5: Compare graphs
         console.log('🔍 Comparing current graph to saved graph...');
-        const comparison = (0, graph_comparator_1.compareGraphs)(currentGraph, savedGraph.projects);
-        if (comparison.identical) {
-            console.log('✅ Architecture unchanged - current graph matches saved graph');
-            return { success: true };
+        const comparison = (0, graph_comparator_1.compareGraphs)(currentGraph.graph, savedGraph.projects);
+        if (!comparison.identical) {
+            reportMismatch(comparison.summary, workspaceRoot);
+            return { success: false };
         }
-        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);
+            return { success: false };
+        }
+        console.log('✅ Architecture unchanged - current graph matches saved graph');
+        return { success: true };
     }
     catch (err) {
         const error = (0, toError_1.toError)(err);

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 } from '../../lib/api-usage/api-scanner';\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 * 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<EnhancedGraph> {\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    scanAndAttachApiRelations(workspaceRoot, currentGraph, projectInfos);\n    return currentGraph;\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            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            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, savedGraph.projects);\n\n        if (comparison.identical) {\n            console.log('✅ Architecture unchanged - current graph matches saved graph');\n            return { success: true };\n        }\n        reportMismatch(comparison.summary, workspaceRoot);\n        return { success: false };\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 { 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"]}

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

@@ -79,7 +79,9 @@ async function runExecutor(_options, context) {
         if (depsFile.projects[name].drawOnGraph === false)
             hiddenProjects.add(name);
     }
-    const report = (0, runtime_graph_1.deriveRuntimeGraphReport)(depsFile.projects, hiddenProjects);
+    // 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 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    const report = deriveRuntimeGraphReport(depsFile.projects, hiddenProjects);\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(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"]}

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

@@ -0,0 +1,71 @@
+/**
+ * API contract AST accessors
+ *
+ * The pure, stateless half of the api scan: given a TypeScript node, what contract / endpoint /
+ * injected type does it describe? Split out of api-scanner.ts, which owns the STATEFUL walk (project
+ * programs, the source index, relation accumulation) and had grown past the file-size limit.
+ *
+ * Everything here is parser-level on purpose. Decorators must be read exactly as written, and a
+ * plain parse cannot be diverted to a decorator-erased `.d.ts` by module resolution — the bug
+ * api-scanner's source pre-pass exists to guard against.
+ */
+import * as ts from 'typescript';
+import { ApiClassInfo, ApiMethodMeta, ApiTransport } from './api-relations';
+/** {api, owner: `project`, type} when `cls` is an `abstract class` carrying `@ApiPath`, else null. */
+export declare function apiClassInfoFrom(cls: ts.ClassDeclaration, project: string): ApiClassInfo | null;
+export declare function apiTransport(cls: ts.ClassDeclaration): ApiTransport;
+/**
+ * Every `@Endpoint(path, kind)` method on a contract class, in declaration order.
+ *
+ * `kind` is a REQUIRED argument of the decorator, so a missing/non-literal second argument means the
+ * source does not compile (or is mid-edit) — we skip the method rather than defaulting it. Defaulting
+ * would put an undeclared cron or webhook into the graph as an ordinary rpc call, which is precisely
+ * the blindness the required argument exists to remove.
+ */
+export declare function endpointMethodsOf(cls: ts.ClassDeclaration, api: string): ApiMethodMeta[];
+/** The arguments of a decorator's call expression, or [] when it is a bare `@Foo` reference. */
+export declare function decoratorArgs(decorator: ts.Decorator): ts.NodeArray<ts.Expression> | ts.Expression[];
+/** The named decorator on a class member, or null. */
+export declare function memberDecorator(member: ts.ClassElement, name: string): ts.Decorator | null;
+/** The first argument of a class decorator when it is a string literal (`@ApiPath('/x')`), else null. */
+export declare function decoratorStringArg(cls: ts.ClassDeclaration, name: string): string | null;
+/** The constructor's parameters, or [] when the class declares no constructor. */
+export declare function constructorParamsOf(cls: ts.ClassDeclaration): readonly ts.ParameterDeclaration[];
+/**
+ * The bare name of a type reference (`GmailApi`, or `gmail.GmailApi` -> `GmailApi`), else null.
+ * Generic wrappers are deliberately NOT unwrapped: `Provider<GmailApi>` hands out the contract
+ * lazily, which is still a use, but it is not the shape any of these seams take today and guessing
+ * at type arguments would start matching things that merely mention a contract.
+ */
+export declare function typeReferenceName(type: ts.TypeNode | undefined): string | null;
+/** Every type name in the class's `implements` clause — the contracts this class IS, not ones it calls. */
+export declare function implementedTypeNames(cls: ts.ClassDeclaration): Set<string>;
+export declare function isAbstractClass(cls: ts.ClassDeclaration): boolean;
+export declare function hasClassDecorator(cls: ts.ClassDeclaration, name: string): boolean;
+/**
+ * The service a client-factory call aims at, from its config argument:
+ * `createRpcClient(WarmupApi, new ClientConfig('helper-fsdb'))` → `'helper-fsdb'`.
+ *
+ * Only a `new <Xxx>ClientConfig('<string literal>')` yields a name. A variable, a template string
+ * or a computed expression yields null — the target is genuinely unknown at scan time, and the
+ * runtime graph must fall back to fan-out (loudly) rather than guess.
+ */
+export declare function targetServiceOf(call: ts.CallExpression): string | null;
+export declare function calleeMethodName(call: ts.CallExpression): string | null;
+export declare function isTestFile(fileName: string): boolean;
+/** {api, owner, type:'rpc'|'pubsub'} for an in-repo contract class, else null. */
+export declare function apiClassInfoFromNode(node: ts.Node, project: string): ApiClassInfo | null;
+/**
+ * {api, owner, type:'external'} for a VENDOR contract, else null.
+ *
+ * A vendor contract cannot be detected the way an in-repo one is. It carries no @ApiPath (there is
+ * no route — the call leaves through a vendor SDK), and it is usually a plain `interface` bound to a
+ * Symbol token, which is not even a class. So inside a project the workspace has DECLARED external
+ * (`runtime-architecture.externalApiPaths`) the signal is structural instead: an exported
+ * `interface`/`abstract class` whose name ends in `Api`. That deliberately picks up `GmailApi` and
+ * `StorageApi` while leaving their DTOs, `*Config` types and `*Client` implementations alone.
+ */
+export declare function externalApiInfoFrom(node: ts.Node, project: string): ApiClassInfo | 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[];