@webpieces/nx-webpieces-rules 0.4.893 → 0.4.894

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/nx-webpieces-rules",
-  "version": "0.4.893",
+  "version": "0.4.894",
   "description": "Nx-specific webpieces validation rules, graph tooling, executors, and inference plugin.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -20,12 +20,12 @@
     "README.md"
   ],
   "dependencies": {
-    "@webpieces/api-doc-model": "0.4.893",
-    "@webpieces/core-util": "0.4.893",
-    "@webpieces/eslint-rules": "0.4.893",
-    "@webpieces/rules-config": "0.4.893",
+    "@webpieces/api-doc-model": "0.4.894",
+    "@webpieces/core-util": "0.4.894",
+    "@webpieces/eslint-rules": "0.4.894",
+    "@webpieces/rules-config": "0.4.894",
     "madge": "8.0.0",
-    "@webpieces/rules-sdk": "0.4.893"
+    "@webpieces/rules-sdk": "0.4.894"
   },
   "peerDependencies": {
     "@nx/devkit": ">=18.0.0"
@@ -41,7 +41,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@webpieces/tooling-testkit": "0.4.893"
+    "@webpieces/tooling-testkit": "0.4.894"
   },
   "types": "./src/index.d.ts",
   "bin": {

package/src/executors/generate/executor.js

@@ -26,9 +26,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, externalSystems) {
+function generateRuntimeGraph(workspaceRoot, graph, hiddenProjects, apiContracts, externalSystems, remoteServices) {
     console.log('📡 Deriving runtime graph from dependencies.json (implements × uses per API)...');
-    const report = (0, runtime_graph_1.deriveRuntimeGraphReport)(graph, hiddenProjects, apiContracts, externalSystems);
+    const report = (0, runtime_graph_1.deriveRuntimeGraphReport)(graph, hiddenProjects, apiContracts, externalSystems, remoteServices);
     (0, runtime_graph_1.saveRuntimeGraph)(report.graph, workspaceRoot);
     const serviceCount = Object.keys(report.graph.services).length;
     const queueCount = Object.keys(report.graph.queues).length;
@@ -70,15 +70,19 @@ function scanApiRelations(workspaceRoot, graph, projectInfos, graphPath = graph_
         throw new rules_config_1.RuleFailError('validate-runtime-architecture', 'Missing approved API contract references.', undefined, undefined, [
             new rules_config_1.Option('Migrate src/wiring.ts and review runtime-deps.json and API contract approvals before generation.', true),
         ]);
-    return new ScannedTables(new api_contract_files_1.ApiContractFiles().load(workspaceRoot, graphPath, saved.apiContractFiles), saved.externalSystems);
+    return new ScannedTables(new api_contract_files_1.ApiContractFiles().load(workspaceRoot, graphPath, saved.apiContractFiles), saved.externalSystems, saved.remoteServices);
 }
-/** The two committed tables one scan produces, kept together so callers cannot persist just one. */
+/** The committed tables one scan produces, kept together so callers cannot persist just one. */
 class ScannedTables {
     apiContracts;
     externalSystems;
-    constructor(apiContracts, externalSystems) {
+    remoteServices;
+    constructor(apiContracts, externalSystems, 
+    /** Reviewed remote services (#1203): read from the saved file, written back verbatim. */
+    remoteServices) {
         this.apiContracts = apiContracts;
         this.externalSystems = externalSystems;
+        this.remoteServices = remoteServices;
     }
 }
 /** Projects tagged drawOnGraph:false — kept in the JSON, omitted from every rendered graph. */
@@ -155,7 +159,7 @@ class ArchitectureGenerator {
         // 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);
+        generateRuntimeGraph(workspaceRoot, enhancedGraph, hiddenProjectsIn(enhancedGraph), apiContracts, scanned.externalSystems, scanned.remoteServices);
         printGraphSummary(enhancedGraph);
     }
 }
@@ -176,7 +180,7 @@ function saveApprovedGraph(workspaceRoot, effectiveGraphPath, enhancedGraph, sca
     // validate from the files, so anything not written here would make the two disagree.
     console.log('💾 Saving graph to architecture/dependencies.json...');
     const contractRefs = contractFiles.refsFor(apiContracts);
-    (0, graph_loader_2.saveGraph)(enhancedGraph, workspaceRoot, effectiveGraphPath, contractRefs, scanned.externalSystems);
+    (0, graph_loader_2.saveGraph)(enhancedGraph, workspaceRoot, effectiveGraphPath, contractRefs, scanned.externalSystems, scanned.remoteServices);
     console.log('✅ Graph saved successfully');
 }
 async function runExecutor(options, context) {

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":["import { ApprovedWiringGraph } from '../../lib/runtime-wiring/approved-graph';\nimport { loadBlessedGraph } from '../../lib/graph-loader';\n/**\n * Generate Executor\n *\n * Generates the architecture dependency graph and saves it to architecture/dependencies.json, plus\n * one contract file per API under architecture/apis/ (stale ones are deleted).\n *\n * Usage:\n * nx run architecture:generate\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport {\n    writeTemplate,\n    Option,\n    RuleFailError,\n    renderRuleFailForHuman,\n} from '@webpieces/rules-config';\nimport { generateReducedGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { ProjectCycleDetector } from '../../lib/graph-cycles';\nimport { saveGraph, DEFAULT_GRAPH_PATH } from '../../lib/graph-loader';\nimport { ApiContractFiles } from '../../lib/api-contract-files';\nimport { collectProjectInfo, enrichGraph, MetadataValidationError } from '../../lib/graph-metadata';\nimport { TagTruthCheck } from '../../lib/tag-truth';\nimport { ProjectInfo } from '../../lib/project-info';\nimport type { ApiContracts, ExternalSystemDecls } from '../../lib/api-usage/api-relations';\nimport type { EnhancedGraph, GraphEntry } from '../../lib/graph-sorter';\nimport { GraphVisualizer } from '../../lib/graph-visualizer';\nimport { GENERATE_IMPACT_KINDS, ImpactRefresh } from '../../lib/graph-impact';\nimport * as path from 'path';\nimport { deriveRuntimeGraphReport, saveRuntimeGraph } from '../../lib/runtime-graph';\nimport { printAutoHiddenServers } from '../../lib/runtime-participant-resolver';\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    printAutoHiddenServers(report.autoHidden);\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(\n            `❌ ${report.problems.length} client call(s) name a service no module answers to:`,\n        );\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    graphPath: string = DEFAULT_GRAPH_PATH,\n): ScannedTables {\n    console.log('📖 Assembling approved runtime-deps.json declarations (no source extraction)...');\n    new ApprovedWiringGraph().attach(workspaceRoot, graph, projectInfos, graphPath);\n    const saved = loadBlessedGraph(workspaceRoot, graphPath);\n    if (saved === null)\n        throw new RuleFailError(\n            'validate-runtime-architecture',\n            'Missing approved API contract references.',\n            undefined,\n            undefined,\n            [\n                new Option(\n                    'Migrate src/wiring.ts and review runtime-deps.json and API contract approvals before generation.',\n                    true,\n                ),\n            ],\n        );\n    return new ScannedTables(\n        new ApiContractFiles().load(workspaceRoot, graphPath, saved.apiContractFiles),\n        saved.externalSystems,\n    );\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 */\nexport class ArchitectureGenerator {\n    constructor(\n        private readonly visualizer: GraphVisualizer,\n        private readonly impact: ImpactRefresh = new ImpactRefresh(),\n    ) {}\n\n    async generate(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 1b: The graph is a BUILD graph — refuse a cyclic one, naming EVERY cycle. This runs\n        // before the sort deliberately: the sort also refuses, but reports one cycle and an\n        // undifferentiated list of everything tangled with it, so a repo with several cycles pays one\n        // full regeneration per cycle to discover them.\n        console.log('🔄 Checking the project graph is acyclic...');\n        const cycles = new ProjectCycleDetector();\n        cycles.assertAcyclic(reducedGraph, 'the nx project graph');\n\n        // Step 2: Topological sort (to assign levels for visualization)\n        console.log('🔄 Computing topological layers...');\n        const enhancedGraph = sortGraphTopologically(reducedGraph);\n        // ...and assert the stratification it just produced actually holds: every dependency strictly\n        // below its dependent. Safe to assert only because the graph was sorted a line ago — a stale\n        // committed file is never checked this way.\n        cycles.assertLevelsDescend(\n            reducedGraph,\n            cycles.levelsOf(enhancedGraph),\n            'the freshly sorted graph',\n        );\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        // enrichGraph pinned servers, clients and apps to the top row (#1179): prove the promotion\n        // kept every dependency strictly below its dependent before anything is written.\n        cycles.assertLevelsDescend(reducedGraph, cycles.levelsOf(enhancedGraph), 'the entry-point-promoted graph');\n        new TagTruthCheck().assertTrue(enhancedGraph, projectInfos, workspaceRoot); // #1064, before any write\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, graphPath);\n        const apiContracts = scanned.apiContracts;\n\n        saveApprovedGraph(workspaceRoot, graphPath ?? DEFAULT_GRAPH_PATH, enhancedGraph, scanned);\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 = this.visualizer.writeVisualization(enhancedGraph, workspaceRoot);\n        console.log(`✅ Wrote ${vizPaths.htmlPath}`);\n\n        // Step 4c: The page's Impact mode — nx affected for \"Changed on this branch\" ONLY, into a\n        // gitignored sidecar beside the html (never into the committed files). Generate never scans\n        // the last commit; that comparison is arch:visualize's. Optional: it reports, it never throws.\n        console.log(\n            await this.impact.run(path.dirname(vizPaths.htmlPath), workspaceRoot, enhancedGraph, GENERATE_IMPACT_KINDS),\n        );\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}\n\n// webpieces-disable no-function-outside-class -- persist the approved graph and contract tables together\nfunction saveApprovedGraph(\n    workspaceRoot: string,\n    effectiveGraphPath: string,\n    enhancedGraph: EnhancedGraph,\n    scanned: ScannedTables,\n): void {\n    // Step 4: Write one contract file per API (architecture/apis/<Api>.json) and delete the files of\n    // APIs that no longer exist. dependencies.json only LINKS to them, so an endpoint change rewrites\n    // an api file and never the dependency graph. The runtime validator reads these files back.\n    const apiContracts = scanned.apiContracts;\n    const contractFiles = new ApiContractFiles();\n    const written = contractFiles.write(workspaceRoot, effectiveGraphPath, apiContracts);\n    console.log(`✅ Wrote ${written.written.length} api contract file(s)`);\n    for (const deleted of written.deleted)\n        console.log(`🗑️  Deleted stale api contract file ${deleted}`);\n\n    // Step 4a: Save the graph, INCLUDING the contract-file links and the external-system\n    // declarations the runtime derivation reads back — generate derives from the in-memory graph,\n    // validate from the files, so anything not written here would make the two disagree.\n    console.log('💾 Saving graph to architecture/dependencies.json...');\n    const contractRefs = contractFiles.refsFor(apiContracts);\n    saveGraph(\n        enhancedGraph,\n        workspaceRoot,\n        effectiveGraphPath,\n        contractRefs,\n        scanned.externalSystems,\n    );\n    console.log('✅ Graph saved successfully');\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 new ArchitectureGenerator(new GraphVisualizer()).generate(workspaceRoot, graphPath);\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        // A RuleFailError carries its cures as Option[]; `Error.message` is only the aiMessage, so\n        // printing that alone silently drops them. renderRuleFailForHuman is the ONE renderer that\n        // numbers them, and this catch is the top-level handler for the nx target.\n        const rendered =\n            error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message;\n        console.error('❌ Graph generation failed:', rendered);\n        if (error instanceof MetadataValidationError) {\n            const mdPath = writeTemplate(workspaceRoot, 'webpieces.responsibilities.md');\n            console.error('');\n            console.error(\n                '⚠️  *** Refer to ' +\n                    mdPath +\n                    ' for how to author responsibilities.md files *** ⚠️',\n            );\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":["import { ApprovedWiringGraph } from '../../lib/runtime-wiring/approved-graph';\nimport { loadBlessedGraph } from '../../lib/graph-loader';\n/**\n * Generate Executor\n *\n * Generates the architecture dependency graph and saves it to architecture/dependencies.json, plus\n * one contract file per API under architecture/apis/ (stale ones are deleted).\n *\n * Usage:\n * nx run architecture:generate\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport {\n    writeTemplate,\n    Option,\n    RuleFailError,\n    renderRuleFailForHuman,\n} from '@webpieces/rules-config';\nimport { generateReducedGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { ProjectCycleDetector } from '../../lib/graph-cycles';\nimport { saveGraph, DEFAULT_GRAPH_PATH } from '../../lib/graph-loader';\nimport { ApiContractFiles } from '../../lib/api-contract-files';\nimport { collectProjectInfo, enrichGraph, MetadataValidationError } from '../../lib/graph-metadata';\nimport { TagTruthCheck } from '../../lib/tag-truth';\nimport { ProjectInfo } from '../../lib/project-info';\nimport type { ApiContracts, ExternalSystemDecls } from '../../lib/api-usage/api-relations';\nimport type { EnhancedGraph, GraphEntry } from '../../lib/graph-sorter';\nimport type { RemoteServices } from '../../lib/remote-services';\nimport { GraphVisualizer } from '../../lib/graph-visualizer';\nimport { GENERATE_IMPACT_KINDS, ImpactRefresh } from '../../lib/graph-impact';\nimport * as path from 'path';\nimport { deriveRuntimeGraphReport, saveRuntimeGraph } from '../../lib/runtime-graph';\nimport { printAutoHiddenServers } from '../../lib/runtime-participant-resolver';\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    remoteServices: RemoteServices,\n): void {\n    console.log('📡 Deriving runtime graph from dependencies.json (implements × uses per API)...');\n    const report = deriveRuntimeGraphReport(\n        graph,\n        hiddenProjects,\n        apiContracts,\n        externalSystems,\n        remoteServices,\n    );\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    printAutoHiddenServers(report.autoHidden);\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(\n            `❌ ${report.problems.length} client call(s) name a service no module answers to:`,\n        );\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    graphPath: string = DEFAULT_GRAPH_PATH,\n): ScannedTables {\n    console.log('📖 Assembling approved runtime-deps.json declarations (no source extraction)...');\n    new ApprovedWiringGraph().attach(workspaceRoot, graph, projectInfos, graphPath);\n    const saved = loadBlessedGraph(workspaceRoot, graphPath);\n    if (saved === null)\n        throw new RuleFailError(\n            'validate-runtime-architecture',\n            'Missing approved API contract references.',\n            undefined,\n            undefined,\n            [\n                new Option(\n                    'Migrate src/wiring.ts and review runtime-deps.json and API contract approvals before generation.',\n                    true,\n                ),\n            ],\n        );\n    return new ScannedTables(\n        new ApiContractFiles().load(workspaceRoot, graphPath, saved.apiContractFiles),\n        saved.externalSystems,\n        saved.remoteServices,\n    );\n}\n\n/** The 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        /** Reviewed remote services (#1203): read from the saved file, written back verbatim. */\n        public readonly remoteServices: RemoteServices,\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 */\nexport class ArchitectureGenerator {\n    constructor(\n        private readonly visualizer: GraphVisualizer,\n        private readonly impact: ImpactRefresh = new ImpactRefresh(),\n    ) {}\n\n    async generate(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 1b: The graph is a BUILD graph — refuse a cyclic one, naming EVERY cycle. This runs\n        // before the sort deliberately: the sort also refuses, but reports one cycle and an\n        // undifferentiated list of everything tangled with it, so a repo with several cycles pays one\n        // full regeneration per cycle to discover them.\n        console.log('🔄 Checking the project graph is acyclic...');\n        const cycles = new ProjectCycleDetector();\n        cycles.assertAcyclic(reducedGraph, 'the nx project graph');\n\n        // Step 2: Topological sort (to assign levels for visualization)\n        console.log('🔄 Computing topological layers...');\n        const enhancedGraph = sortGraphTopologically(reducedGraph);\n        // ...and assert the stratification it just produced actually holds: every dependency strictly\n        // below its dependent. Safe to assert only because the graph was sorted a line ago — a stale\n        // committed file is never checked this way.\n        cycles.assertLevelsDescend(\n            reducedGraph,\n            cycles.levelsOf(enhancedGraph),\n            'the freshly sorted graph',\n        );\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        // enrichGraph pinned servers, clients and apps to the top row (#1179): prove the promotion\n        // kept every dependency strictly below its dependent before anything is written.\n        cycles.assertLevelsDescend(reducedGraph, cycles.levelsOf(enhancedGraph), 'the entry-point-promoted graph');\n        new TagTruthCheck().assertTrue(enhancedGraph, projectInfos, workspaceRoot); // #1064, before any write\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, graphPath);\n        const apiContracts = scanned.apiContracts;\n\n        saveApprovedGraph(workspaceRoot, graphPath ?? DEFAULT_GRAPH_PATH, enhancedGraph, scanned);\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 = this.visualizer.writeVisualization(enhancedGraph, workspaceRoot);\n        console.log(`✅ Wrote ${vizPaths.htmlPath}`);\n\n        // Step 4c: The page's Impact mode — nx affected for \"Changed on this branch\" ONLY, into a\n        // gitignored sidecar beside the html (never into the committed files). Generate never scans\n        // the last commit; that comparison is arch:visualize's. Optional: it reports, it never throws.\n        console.log(\n            await this.impact.run(path.dirname(vizPaths.htmlPath), workspaceRoot, enhancedGraph, GENERATE_IMPACT_KINDS),\n        );\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            scanned.remoteServices,\n        );\n\n        printGraphSummary(enhancedGraph);\n    }\n}\n\n// webpieces-disable no-function-outside-class -- persist the approved graph and contract tables together\nfunction saveApprovedGraph(\n    workspaceRoot: string,\n    effectiveGraphPath: string,\n    enhancedGraph: EnhancedGraph,\n    scanned: ScannedTables,\n): void {\n    // Step 4: Write one contract file per API (architecture/apis/<Api>.json) and delete the files of\n    // APIs that no longer exist. dependencies.json only LINKS to them, so an endpoint change rewrites\n    // an api file and never the dependency graph. The runtime validator reads these files back.\n    const apiContracts = scanned.apiContracts;\n    const contractFiles = new ApiContractFiles();\n    const written = contractFiles.write(workspaceRoot, effectiveGraphPath, apiContracts);\n    console.log(`✅ Wrote ${written.written.length} api contract file(s)`);\n    for (const deleted of written.deleted)\n        console.log(`🗑️  Deleted stale api contract file ${deleted}`);\n\n    // Step 4a: Save the graph, INCLUDING the contract-file links and the external-system\n    // declarations the runtime derivation reads back — generate derives from the in-memory graph,\n    // validate from the files, so anything not written here would make the two disagree.\n    console.log('💾 Saving graph to architecture/dependencies.json...');\n    const contractRefs = contractFiles.refsFor(apiContracts);\n    saveGraph(\n        enhancedGraph,\n        workspaceRoot,\n        effectiveGraphPath,\n        contractRefs,\n        scanned.externalSystems,\n        scanned.remoteServices,\n    );\n    console.log('✅ Graph saved successfully');\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 new ArchitectureGenerator(new GraphVisualizer()).generate(workspaceRoot, graphPath);\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        // A RuleFailError carries its cures as Option[]; `Error.message` is only the aiMessage, so\n        // printing that alone silently drops them. renderRuleFailForHuman is the ONE renderer that\n        // numbers them, and this catch is the top-level handler for the nx target.\n        const rendered =\n            error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message;\n        console.error('❌ Graph generation failed:', rendered);\n        if (error instanceof MetadataValidationError) {\n            const mdPath = writeTemplate(workspaceRoot, 'webpieces.responsibilities.md');\n            console.error('');\n            console.error(\n                '⚠️  *** Refer to ' +\n                    mdPath +\n                    ' for how to author responsibilities.md files *** ⚠️',\n            );\n        }\n        return { success: false };\n    }\n}\n"]}

package/src/executors/validate-architecture-unchanged/executor.d.ts

@@ -11,6 +11,7 @@ import type { ExecutorContext } from '@nx/devkit';
 import type { DependenciesFile } from '../../lib/graph-loader';
 import type { ExternalSystemDecls } from '../../lib/api-usage/api-relations';
 import type { ApiContractFileRefs } from '../../lib/api-contract-files';
+import type { RemoteServices } from '../../lib/remote-services';
 import type { EnhancedGraph } from '../../lib/graph-sorter';
 export interface ValidateArchitectureUnchangedOptions {
     graphPath?: string;
@@ -32,11 +33,12 @@ export declare function describeTableDrift(current: CurrentArchitecture, saved:
 export declare class CurrentGraphBuilder {
     build(workspaceRoot: string, graphPath?: string): Promise<CurrentArchitecture>;
 }
-/** The regenerated graph plus the two tables beside it — everything dependencies.json holds. */
+/** The regenerated graph plus the tables beside it — everything dependencies.json holds. */
 export declare class CurrentArchitecture {
     readonly graph: EnhancedGraph;
     readonly apiContractFiles: ApiContractFileRefs;
     readonly externalSystems: ExternalSystemDecls;
-    constructor(graph: EnhancedGraph, apiContractFiles: ApiContractFileRefs, externalSystems: ExternalSystemDecls);
+    readonly remoteServices: RemoteServices;
+    constructor(graph: EnhancedGraph, apiContractFiles: ApiContractFileRefs, externalSystems: ExternalSystemDecls, remoteServices: RemoteServices);
 }
 export default function runExecutor(options: ValidateArchitectureUnchangedOptions, context: ExecutorContext): Promise<ExecutorResult>;

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

@@ -80,7 +80,32 @@ function describeTableDrift(current, saved) {
     const linkDrift = describeContractLinkDrift(current.apiContractFiles, saved.apiContractFiles);
     if (linkDrift !== null)
         return linkDrift;
-    return describeExternalSystemDrift(current.externalSystems, saved.externalSystems);
+    const systemDrift = describeExternalSystemDrift(current.externalSystems, saved.externalSystems);
+    if (systemDrift !== null)
+        return systemDrift;
+    return describeRemoteServiceDrift(current.remoteServices, saved.remoteServices);
+}
+/**
+ * The same drift report for the reviewed remote services (#1203), or null when they match. The table
+ * is approval metadata, so a difference means the file changed under the generated graph.
+ */
+// webpieces-disable no-function-outside-class -- executor step helper, matches describeContractLinkDrift above
+function describeRemoteServiceDrift(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 approved`);
+        else if (b === undefined)
+            changes.push(`  + ${name}: approved but missing from dependencies.json`);
+        else if (JSON.stringify(a) !== JSON.stringify(b))
+            changes.push(`  ~ ${name}: label/implements changed`);
+    }
+    if (changes.length === 0)
+        return null;
+    return `remoteServices drift (${changes.length} service(s)):\n${changes.join('\n')}`;
 }
 /**
  * The same drift report for the declared external systems, or null when they match. Named per
@@ -125,19 +150,21 @@ class CurrentGraphBuilder {
             throw new rules_config_1.RuleFailError('validate-runtime-architecture', 'Missing approved graph.', undefined, undefined, [
                 new rules_config_1.Option('Migrate src/wiring.ts and review runtime-deps.json and API contract approvals.', true),
             ]);
-        return new CurrentArchitecture(currentGraph, saved.apiContractFiles, saved.externalSystems);
+        return new CurrentArchitecture(currentGraph, saved.apiContractFiles, saved.externalSystems, saved.remoteServices);
     }
 }
 exports.CurrentGraphBuilder = CurrentGraphBuilder;
-/** The regenerated graph plus the two tables beside it — everything dependencies.json holds. */
+/** The regenerated graph plus the tables beside it — everything dependencies.json holds. */
 class CurrentArchitecture {
     graph;
     apiContractFiles;
     externalSystems;
-    constructor(graph, apiContractFiles, externalSystems) {
+    remoteServices;
+    constructor(graph, apiContractFiles, externalSystems, remoteServices) {
         this.graph = graph;
         this.apiContractFiles = apiContractFiles;
         this.externalSystems = externalSystems;
+        this.remoteServices = remoteServices;
     }
 }
 exports.CurrentArchitecture = CurrentArchitecture;
@@ -145,7 +172,7 @@ exports.CurrentArchitecture = CurrentArchitecture;
 // webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch in this file
 function reportMissingGraph() {
     throw new rules_config_1.RuleFailError('validate-runtime-architecture', 'Missing reviewed architecture/dependencies.json.', undefined, undefined, [
-        new rules_config_1.Option('Run owning API source build checks to emit contract candidates, review and copy them into architecture/apis/<ApiName>.json, and create dependencies.json with projects:{}, apiContractFiles:{"<ApiName>":"apis/<ApiName>.json"}, and reviewed externalSystems. Approve tagged owners runtime-deps.json candidates, then run architecture:generate and review the resulting graph.', true),
+        new rules_config_1.Option('Run owning API source build checks to emit contract candidates, review and copy them into architecture/apis/<ApiName>.json, and create dependencies.json with projects:{}, apiContractFiles:{"<ApiName>":"apis/<ApiName>.json"}, reviewed externalSystems, and (only when a uses targets a service outside this workspace) reviewed remoteServices. Approve tagged owners runtime-deps.json candidates, then run architecture:generate and review the resulting graph.', true),
     ]);
 }
 async function runExecutor(options, context) {

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 {\n    writeTemplate,\n    Option,\n    RuleFailError,\n    renderRuleFailForHuman,\n} 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 { TagTruthCheck } from '../../lib/tag-truth';\nimport { ApprovedWiringGraph } from '../../lib/runtime-wiring/approved-graph';\nimport type { ExternalSystemDecls } from '../../lib/api-usage/api-relations';\nimport { ApiContractFiles } from '../../lib/api-contract-files';\nimport type { ApiContractFileRefs } from '../../lib/api-contract-files';\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(\n        '  2. If intentional, ASK USER to run: nx run architecture:generate since this is a critical change',\n    );\n    console.error('  3. Commit the updated architecture/dependencies.json');\n}\n\n/**\n * Which APIs dependencies.json links to a contract file, compared by LINK only — an added or removed\n * API. The endpoints inside `architecture/apis/<Api>.json` are deliberately NOT compared (#949): an\n * endpoint change must not fail this rule. Null when the links match.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch in this file\nfunction describeContractLinkDrift(\n    current: ApiContractFileRefs,\n    saved: ApiContractFileRefs,\n): 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)\n            changes.push(`  - ${name}: linked in dependencies.json but no longer in source`);\n        else if (b === undefined)\n            changes.push(`  + ${name}: in source but not linked from dependencies.json`);\n        else if (a !== b) changes.push(`  ~ ${name}: contract file link changed (${b} -> ${a})`);\n    }\n    if (changes.length === 0) return null;\n    return `apiContractFiles drift (${changes.length} api(s)):\\n${changes.join('\\n')}`;\n}\n\n/**\n * Drift in EITHER side table of dependencies.json — the api contract-file links or the\n * external-system declarations — or null when both match. The first difference found is reported;\n * fixing it is the 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 describeContractLinkDrift above\nexport function describeTableDrift(\n    current: CurrentArchitecture,\n    saved: DependenciesFile,\n): string | null {\n    const linkDrift = describeContractLinkDrift(current.apiContractFiles, saved.apiContractFiles);\n    if (linkDrift !== null) return linkDrift;\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 describeContractLinkDrift above\nfunction describeExternalSystemDrift(\n    current: ExternalSystemDecls,\n    saved: ExternalSystemDecls,\n): 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)\n            changes.push(`  - ${name}: in dependencies.json but no longer declared in source`);\n        else if (b === undefined)\n            changes.push(`  + ${name}: declared in source but missing from dependencies.json`);\n        else if (JSON.stringify(a) !== JSON.stringify(b))\n            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 */\nexport class CurrentGraphBuilder {\n    async build(workspaceRoot: string, graphPath?: 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        new TagTruthCheck().assertTrue(currentGraph, projectInfos, workspaceRoot);\n        new ApprovedWiringGraph().attach(workspaceRoot, currentGraph, projectInfos, graphPath);\n        const saved = loadBlessedGraph(workspaceRoot, graphPath);\n        if (saved === null)\n            throw new RuleFailError(\n                'validate-runtime-architecture',\n                'Missing approved graph.',\n                undefined,\n                undefined,\n                [\n                    new Option(\n                        'Migrate src/wiring.ts and review runtime-deps.json and API contract approvals.',\n                        true,\n                    ),\n                ],\n            );\n        return new CurrentArchitecture(currentGraph, saved.apiContractFiles, saved.externalSystems);\n    }\n}\n\n/** The regenerated graph plus the two tables beside it — everything dependencies.json holds. */\nexport class CurrentArchitecture {\n    constructor(\n        public readonly graph: EnhancedGraph,\n        public readonly apiContractFiles: ApiContractFileRefs,\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(): never {\n    throw new RuleFailError(\n        'validate-runtime-architecture',\n        'Missing reviewed architecture/dependencies.json.',\n        undefined,\n        undefined,\n        [\n            new Option(\n                'Run owning API source build checks to emit contract candidates, review and copy them into architecture/apis/<ApiName>.json, and create dependencies.json with projects:{}, apiContractFiles:{\"<ApiName>\":\"apis/<ApiName>.json\"}, and reviewed externalSystems. Approve tagged owners runtime-deps.json candidates, then run architecture:generate and review the resulting graph.',\n                true,\n            ),\n        ],\n    );\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 new CurrentGraphBuilder().build(workspaceRoot, graphPath);\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: which APIs are linked to a contract file, and\n        // the external-system declarations. The endpoints inside architecture/apis/<Api>.json are\n        // NOT compared — an endpoint change must never fail this rule (#949).\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        // A RuleFailError (e.g. a dependencies.json still carrying the moved `apiContracts` key)\n        // carries its cures in Option[]; render them rather than dropping them with `.message`.\n        const rendered =\n            error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message;\n        console.error('❌ Architecture validation failed:', rendered);\n        reportMetadataFailure(error, workspaceRoot);\n        return { success: false };\n    }\n}\n\n// webpieces-disable no-function-outside-class -- executor diagnostic formatting\nfunction reportMetadataFailure(error: Error, workspaceRoot: string): void {\n    if (error instanceof MetadataValidationError) {\n        const mdPath = writeTemplate(workspaceRoot, 'webpieces.responsibilities.md');\n        console.error('');\n        console.error(\n            '⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️',\n        );\n    }\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-architecture-unchanged/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAgGH,gDASC;AAiHD,8BAkEC;AAzRD,0DAKiC;AACjC,+DAAiE;AACjE,yDAAgE;AAChE,iEAA2D;AAC3D,yDAA2E;AAE3E,6DAAoG;AACpG,mDAAoD;AACpD,4EAA8E;AAK9E,mDAA+C;AAE/C,2CAAwC;AAUxC,MAAM,WAAW,GAAG,2BAA2B,CAAC;AAEhD;;;GAGG;AACH,SAAS,wBAAwB,CAAC,aAAqB;IACnD,MAAM,MAAM,GAAG,IAAA,4BAAa,EAAC,aAAa,EAAE,WAAW,CAAC,CAAC;IAEzD,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,SAAS,cAAc,CAAC,OAAe,EAAE,aAAqB;IAC1D,MAAM,MAAM,GAAG,wBAAwB,CAAC,aAAa,CAAC,CAAC;IAEvD,OAAO,CAAC,KAAK,CAAC,+CAA+C,CAAC,CAAC;IAC/D,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACvB,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAClB,OAAO,CAAC,KAAK,CAAC,mBAAmB,GAAG,MAAM,GAAG,wCAAwC,CAAC,CAAC;IACvF,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAClB,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACzB,OAAO,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;IAC/C,OAAO,CAAC,KAAK,CACT,oGAAoG,CACvG,CAAC;IACF,OAAO,CAAC,KAAK,CAAC,wDAAwD,CAAC,CAAC;AAC5E,CAAC;AAED;;;;GAIG;AACH,2GAA2G;AAC3G,SAAS,yBAAyB,CAC9B,OAA4B,EAC5B,KAA0B;IAE1B,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACpF,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACxB,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,SAAS;YACf,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,uDAAuD,CAAC,CAAC;aAChF,IAAI,CAAC,KAAK,SAAS;YACpB,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,mDAAmD,CAAC,CAAC;aAC5E,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,iCAAiC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7F,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,2BAA2B,OAAO,CAAC,MAAM,cAAc,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AACvF,CAAC;AAED;;;;GAIG;AACH,+GAA+G;AAC/G,SAAgB,kBAAkB,CAC9B,OAA4B,EAC5B,KAAuB;IAEvB,MAAM,SAAS,GAAG,yBAAyB,CAAC,OAAO,CAAC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAC9F,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACzC,MAAM,WAAW,GAAG,2BAA2B,CAAC,OAAO,CAAC,eAAe,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IAChG,IAAI,WAAW,KAAK,IAAI;QAAE,OAAO,WAAW,CAAC;IAC7C,OAAO,0BAA0B,CAAC,OAAO,CAAC,cAAc,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;AACpF,CAAC;AAED;;;GAGG;AACH,+GAA+G;AAC/G,SAAS,0BAA0B,CAAC,OAAuB,EAAE,KAAqB;IAC9E,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACpF,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACxB,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,SAAS;YAAE,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,+CAA+C,CAAC,CAAC;aACzF,IAAI,CAAC,KAAK,SAAS;YAAE,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,+CAA+C,CAAC,CAAC;aAC9F,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;YAC5C,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,4BAA4B,CAAC,CAAC;IAC9D,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,yBAAyB,OAAO,CAAC,MAAM,kBAAkB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AACzF,CAAC;AAED;;;GAGG;AACH,+GAA+G;AAC/G,SAAS,2BAA2B,CAChC,OAA4B,EAC5B,KAA0B;IAE1B,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACpF,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACxB,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,SAAS;YACf,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,yDAAyD,CAAC,CAAC;aAClF,IAAI,CAAC,KAAK,SAAS;YACpB,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,yDAAyD,CAAC,CAAC;aAClF,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;YAC5C,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,gCAAgC,CAAC,CAAC;IAClE,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,0BAA0B,OAAO,CAAC,MAAM,iBAAiB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AACzF,CAAC;AAED;;;;GAIG;AACH,MAAa,mBAAmB;IAC5B,KAAK,CAAC,KAAK,CAAC,aAAqB,EAAE,SAAkB;QACjD,OAAO,CAAC,GAAG,CAAC,2CAA2C,CAAC,CAAC;QACzD,MAAM,YAAY,GAAG,MAAM,IAAA,sCAAoB,GAAE,CAAC;QAClD,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;QAClD,MAAM,YAAY,GAAG,IAAA,qCAAsB,EAAC,YAAY,CAAC,CAAC;QAC1D,OAAO,CAAC,GAAG,CAAC,oEAAoE,CAAC,CAAC;QAClF,MAAM,YAAY,GAAG,MAAM,IAAA,mCAAkB,GAAE,CAAC;QAChD,IAAA,4BAAW,EAAC,YAAY,EAAE,YAAY,EAAE,aAAa,CAAC,CAAC;QACvD,IAAI,yBAAa,EAAE,CAAC,UAAU,CAAC,YAAY,EAAE,YAAY,EAAE,aAAa,CAAC,CAAC;QAC1E,IAAI,oCAAmB,EAAE,CAAC,MAAM,CAAC,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;QACvF,MAAM,KAAK,GAAG,IAAA,+BAAgB,EAAC,aAAa,EAAE,SAAS,CAAC,CAAC;QACzD,IAAI,KAAK,KAAK,IAAI;YACd,MAAM,IAAI,4BAAa,CACnB,+BAA+B,EAC/B,yBAAyB,EACzB,SAAS,EACT,SAAS,EACT;gBACI,IAAI,qBAAM,CACN,gFAAgF,EAChF,IAAI,CACP;aACJ,CACJ,CAAC;QACN,OAAO,IAAI,mBAAmB,CAC1B,YAAY,EACZ,KAAK,CAAC,gBAAgB,EACtB,KAAK,CAAC,eAAe,EACrB,KAAK,CAAC,cAAc,CACvB,CAAC;IACN,CAAC;CACJ;AAhCD,kDAgCC;AAED,4FAA4F;AAC5F,MAAa,mBAAmB;IAER;IACA;IACA;IACA;IAJpB,YACoB,KAAoB,EACpB,gBAAqC,EACrC,eAAoC,EACpC,cAA8B;QAH9B,UAAK,GAAL,KAAK,CAAe;QACpB,qBAAgB,GAAhB,gBAAgB,CAAqB;QACrC,oBAAe,GAAf,eAAe,CAAqB;QACpC,mBAAc,GAAd,cAAc,CAAgB;IAC/C,CAAC;CACP;AAPD,kDAOC;AAED,yFAAyF;AACzF,2GAA2G;AAC3G,SAAS,kBAAkB;IACvB,MAAM,IAAI,4BAAa,CACnB,+BAA+B,EAC/B,kDAAkD,EAClD,SAAS,EACT,SAAS,EACT;QACI,IAAI,qBAAM,CACN,wcAAwc,EACxc,IAAI,CACP;KACJ,CACJ,CAAC;AACN,CAAC;AAEc,KAAK,UAAU,WAAW,CACrC,OAA6C,EAC7C,OAAwB;IAExB,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACpC,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC,yFAAyF;IACzF,yFAAyF;IACzF,IAAI,IAAI,oBAAQ,EAAE,CAAC,UAAU,CAAC,aAAa,EAAE,iCAAiC,EAAE,IAAI,CAAC,EAAE,CAAC;QACpF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC7B,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;IAExD,8DAA8D;IAC9D,IAAI,CAAC;QACD,8BAA8B;QAC9B,IAAI,CAAC,IAAA,8BAAe,EAAC,aAAa,EAAE,SAAS,CAAC,EAAE,CAAC;YAC7C,kBAAkB,EAAE,CAAC;YACrB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;QAED,wEAAwE;QACxE,2CAA2C;QAC3C,MAAM,YAAY,GAAG,MAAM,IAAI,mBAAmB,EAAE,CAAC,KAAK,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;QAErF,2BAA2B;QAC3B,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;QACzC,MAAM,UAAU,GAAG,IAAA,+BAAgB,EAAC,aAAa,EAAE,SAAS,CAAC,CAAC;QAE9D,IAAI,CAAC,UAAU,EAAE,CAAC;YACd,OAAO,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;YAC9C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;QAED,yBAAyB;QACzB,OAAO,CAAC,GAAG,CAAC,8CAA8C,CAAC,CAAC;QAC5D,MAAM,UAAU,GAAG,IAAA,gCAAa,EAAC,YAAY,CAAC,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;QAE1E,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC;YACxB,cAAc,CAAC,UAAU,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;YAClD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;QAED,6FAA6F;QAC7F,0FAA0F;QAC1F,sEAAsE;QACtE,MAAM,UAAU,GAAG,kBAAkB,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;QAChE,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;YACtB,cAAc,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;YAC1C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,8DAA8D,CAAC,CAAC;QAC5E,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,yFAAyF;QACzF,wFAAwF;QACxF,MAAM,QAAQ,GACV,KAAK,YAAY,4BAAa,CAAC,CAAC,CAAC,IAAA,qCAAsB,EAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;QACnF,OAAO,CAAC,KAAK,CAAC,mCAAmC,EAAE,QAAQ,CAAC,CAAC;QAC7D,qBAAqB,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;QAC5C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC;AAED,gFAAgF;AAChF,SAAS,qBAAqB,CAAC,KAAY,EAAE,aAAqB;IAC9D,IAAI,KAAK,YAAY,wCAAuB,EAAE,CAAC;QAC3C,MAAM,MAAM,GAAG,IAAA,4BAAa,EAAC,aAAa,EAAE,+BAA+B,CAAC,CAAC;QAC7E,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAClB,OAAO,CAAC,KAAK,CACT,mBAAmB,GAAG,MAAM,GAAG,qDAAqD,CACvF,CAAC;IACN,CAAC;AACL,CAAC","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 {\n    writeTemplate,\n    Option,\n    RuleFailError,\n    renderRuleFailForHuman,\n} 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 { TagTruthCheck } from '../../lib/tag-truth';\nimport { ApprovedWiringGraph } from '../../lib/runtime-wiring/approved-graph';\nimport type { ExternalSystemDecls } from '../../lib/api-usage/api-relations';\nimport { ApiContractFiles } from '../../lib/api-contract-files';\nimport type { ApiContractFileRefs } from '../../lib/api-contract-files';\nimport type { RemoteServices } from '../../lib/remote-services';\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(\n        '  2. If intentional, ASK USER to run: nx run architecture:generate since this is a critical change',\n    );\n    console.error('  3. Commit the updated architecture/dependencies.json');\n}\n\n/**\n * Which APIs dependencies.json links to a contract file, compared by LINK only — an added or removed\n * API. The endpoints inside `architecture/apis/<Api>.json` are deliberately NOT compared (#949): an\n * endpoint change must not fail this rule. Null when the links match.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch in this file\nfunction describeContractLinkDrift(\n    current: ApiContractFileRefs,\n    saved: ApiContractFileRefs,\n): 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)\n            changes.push(`  - ${name}: linked in dependencies.json but no longer in source`);\n        else if (b === undefined)\n            changes.push(`  + ${name}: in source but not linked from dependencies.json`);\n        else if (a !== b) changes.push(`  ~ ${name}: contract file link changed (${b} -> ${a})`);\n    }\n    if (changes.length === 0) return null;\n    return `apiContractFiles drift (${changes.length} api(s)):\\n${changes.join('\\n')}`;\n}\n\n/**\n * Drift in EITHER side table of dependencies.json — the api contract-file links or the\n * external-system declarations — or null when both match. The first difference found is reported;\n * fixing it is the 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 describeContractLinkDrift above\nexport function describeTableDrift(\n    current: CurrentArchitecture,\n    saved: DependenciesFile,\n): string | null {\n    const linkDrift = describeContractLinkDrift(current.apiContractFiles, saved.apiContractFiles);\n    if (linkDrift !== null) return linkDrift;\n    const systemDrift = describeExternalSystemDrift(current.externalSystems, saved.externalSystems);\n    if (systemDrift !== null) return systemDrift;\n    return describeRemoteServiceDrift(current.remoteServices, saved.remoteServices);\n}\n\n/**\n * The same drift report for the reviewed remote services (#1203), or null when they match. The table\n * is approval metadata, so a difference means the file changed under the generated graph.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches describeContractLinkDrift above\nfunction describeRemoteServiceDrift(current: RemoteServices, saved: RemoteServices): 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 approved`);\n        else if (b === undefined) changes.push(`  + ${name}: approved but missing from dependencies.json`);\n        else if (JSON.stringify(a) !== JSON.stringify(b))\n            changes.push(`  ~ ${name}: label/implements changed`);\n    }\n    if (changes.length === 0) return null;\n    return `remoteServices drift (${changes.length} service(s)):\\n${changes.join('\\n')}`;\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 describeContractLinkDrift above\nfunction describeExternalSystemDrift(\n    current: ExternalSystemDecls,\n    saved: ExternalSystemDecls,\n): 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)\n            changes.push(`  - ${name}: in dependencies.json but no longer declared in source`);\n        else if (b === undefined)\n            changes.push(`  + ${name}: declared in source but missing from dependencies.json`);\n        else if (JSON.stringify(a) !== JSON.stringify(b))\n            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 */\nexport class CurrentGraphBuilder {\n    async build(workspaceRoot: string, graphPath?: 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        new TagTruthCheck().assertTrue(currentGraph, projectInfos, workspaceRoot);\n        new ApprovedWiringGraph().attach(workspaceRoot, currentGraph, projectInfos, graphPath);\n        const saved = loadBlessedGraph(workspaceRoot, graphPath);\n        if (saved === null)\n            throw new RuleFailError(\n                'validate-runtime-architecture',\n                'Missing approved graph.',\n                undefined,\n                undefined,\n                [\n                    new Option(\n                        'Migrate src/wiring.ts and review runtime-deps.json and API contract approvals.',\n                        true,\n                    ),\n                ],\n            );\n        return new CurrentArchitecture(\n            currentGraph,\n            saved.apiContractFiles,\n            saved.externalSystems,\n            saved.remoteServices,\n        );\n    }\n}\n\n/** The regenerated graph plus the tables beside it — everything dependencies.json holds. */\nexport class CurrentArchitecture {\n    constructor(\n        public readonly graph: EnhancedGraph,\n        public readonly apiContractFiles: ApiContractFileRefs,\n        public readonly externalSystems: ExternalSystemDecls,\n        public readonly remoteServices: RemoteServices,\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(): never {\n    throw new RuleFailError(\n        'validate-runtime-architecture',\n        'Missing reviewed architecture/dependencies.json.',\n        undefined,\n        undefined,\n        [\n            new Option(\n                'Run owning API source build checks to emit contract candidates, review and copy them into architecture/apis/<ApiName>.json, and create dependencies.json with projects:{}, apiContractFiles:{\"<ApiName>\":\"apis/<ApiName>.json\"}, reviewed externalSystems, and (only when a uses targets a service outside this workspace) reviewed remoteServices. Approve tagged owners runtime-deps.json candidates, then run architecture:generate and review the resulting graph.',\n                true,\n            ),\n        ],\n    );\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 new CurrentGraphBuilder().build(workspaceRoot, graphPath);\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: which APIs are linked to a contract file, and\n        // the external-system declarations. The endpoints inside architecture/apis/<Api>.json are\n        // NOT compared — an endpoint change must never fail this rule (#949).\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        // A RuleFailError (e.g. a dependencies.json still carrying the moved `apiContracts` key)\n        // carries its cures in Option[]; render them rather than dropping them with `.message`.\n        const rendered =\n            error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message;\n        console.error('❌ Architecture validation failed:', rendered);\n        reportMetadataFailure(error, workspaceRoot);\n        return { success: false };\n    }\n}\n\n// webpieces-disable no-function-outside-class -- executor diagnostic formatting\nfunction reportMetadataFailure(error: Error, workspaceRoot: string): void {\n    if (error instanceof MetadataValidationError) {\n        const mdPath = writeTemplate(workspaceRoot, 'webpieces.responsibilities.md');\n        console.error('');\n        console.error(\n            '⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️',\n        );\n    }\n}\n"]}

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

@@ -50,7 +50,7 @@ function deriveOrRender(workspaceRoot, depsFile, hiddenProjects) {
         // The queue/trigger data comes from the generated architecture/apis/<Api>.json files that
         // dependencies.json links to — the same files generate wrote from its in-memory table.
         const apiContracts = new api_contract_files_1.ApiContractFiles().load(workspaceRoot, graph_loader_1.DEFAULT_GRAPH_PATH, depsFile.apiContractFiles);
-        return (0, runtime_graph_1.deriveRuntimeGraphReport)(depsFile.projects, hiddenProjects, apiContracts, depsFile.externalSystems);
+        return (0, runtime_graph_1.deriveRuntimeGraphReport)(depsFile.projects, hiddenProjects, apiContracts, depsFile.externalSystems, depsFile.remoteServices);
     }
     catch (err) {
         const error = (0, toError_1.toError)(err);

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 * Workspace-level checks on the runtime microservice graph:\n *   1. Unchanged: the freshly-assembled graph must match the committed\n *      architecture/runtime-dependencies.json (run `architecture:generate`).\n *   2. Every role:server project has a node on the graph.\n *\n * CYCLES ARE NOT CHECKED HERE, and there is deliberately no allowlist for them any more. A runtime\n * cycle now fails inside the DERIVATION — `assignLevels` (lib/runtime-graph-levels.ts) throws a\n * RuleFailError naming every chain, because CD deploys in dependency order and a cyclic architecture\n * has no such order. `deriveRuntimeGraphReport` below therefore cannot return a cyclic graph, and the\n * only way past it is to break the cycle, or to declare ONE edge with a `cutLegacyCycle:<target>` nx\n * tag on the CALLING project.\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 { RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport { loadBlessedGraph, DEFAULT_GRAPH_PATH } from '../../lib/graph-loader';\nimport { ApiContractFiles } from '../../lib/api-contract-files';\nimport type { DependenciesFile } from '../../lib/graph-loader';\nimport { toError } from '../../toError';\nimport type { EnhancedGraph } from '../../lib/graph-sorter';\nimport {\n    deriveRuntimeGraphReport,\n    loadRuntimeGraph,\n    runtimeGraphFileExists,\n    serializeRuntimeGraph,\n} from '../../lib/runtime-graph';\nimport type { RuntimeGraph, RuntimeGraphReport } from '../../lib/runtime-graph';\nimport { printAutoHiddenServers } from '../../lib/runtime-participant-resolver';\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/**\n * The derived report, or the RENDERED failure when the derivation refused to produce one.\n *\n * `assignLevels` throws a `RuleFailError` on a cyclic graph, and its cures live in that error's\n * `Option[]` — which `Error.message` does NOT carry. This executor is the top-level handler for its\n * nx target, so it renders through the one human renderer here; letting the throw escape `runExecutor`\n * would print the message with every cure silently dropped. Nothing is swallowed: the caller reports\n * the rendered text and fails, and anything that is not a rule verdict is rethrown untouched.\n *\n * A rendered failure ends the run rather than joining `problems`: there is no graph left to run the\n * other checks against, and a cycle is deliberately the one failure this rule does NOT route through\n * its report-only window — an architecture with no deploy order is not a style preference.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches checkUnchanged in this file\nfunction deriveOrRender(\n    workspaceRoot: string,\n    depsFile: DependenciesFile,\n    hiddenProjects: Set<string>,\n): RuntimeGraphReport | string {\n    // webpieces-disable no-unmanaged-exceptions -- top-level handler for this nx target; it renders, it does not swallow\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // The queue/trigger data comes from the generated architecture/apis/<Api>.json files that\n        // dependencies.json links to — the same files generate wrote from its in-memory table.\n        const apiContracts = new ApiContractFiles().load(\n            workspaceRoot, DEFAULT_GRAPH_PATH, depsFile.apiContractFiles);\n        return deriveRuntimeGraphReport(\n            depsFile.projects, hiddenProjects, apiContracts, depsFile.externalSystems);\n    } catch (err: unknown) {\n        const error = toError(err);\n        if (error instanceof RuleFailError) return renderRuleFailForHuman(error);\n        throw error;\n    }\n}\n\n/**\n * The committed dependencies.json, or the RENDERED failure when it is absent or cannot be read as the\n * current shape (e.g. it still carries the retired `apiContracts` key). Rendered here for the same\n * reason as deriveOrRender: this executor is the top-level handler for its nx target.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches deriveOrRender in this file\nfunction loadOrRender(workspaceRoot: string): DependenciesFile | string {\n    // webpieces-disable no-unmanaged-exceptions -- top-level handler for this nx target; it renders, it does not swallow\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const depsFile = loadBlessedGraph(workspaceRoot);\n        return depsFile ?? 'No architecture/dependencies.json — run: nx run architecture:generate';\n    } catch (err: unknown) {\n        const error = toError(err);\n        if (error instanceof RuleFailError) return renderRuleFailForHuman(error);\n        throw error;\n    }\n}\n\n/**\n * Every `role:server` project must have a NODE in the runtime graph. A pure set difference against\n * what the derivation produced, and it exists because the derivation once dropped relation-less\n * servers silently: the diagram claimed to be complete while a deployed service was missing from it.\n * Now the only sanctioned way for a server to be absent from the drawing is `drawOnGraph:false`, and\n * anything else that ever removes one fails the build by name instead of disappearing quietly.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches checkUnchanged in this file\nexport function checkServersPresent(\n    projects: EnhancedGraph,\n    hiddenProjects: Set<string>,\n    graph: RuntimeGraph,\n): string[] {\n    const problems: string[] = [];\n    for (const name of Object.keys(projects).sort()) {\n        if (projects[name].role !== 'server') continue;\n        if (hiddenProjects.has(name)) continue;\n        if (graph.services[name] !== undefined) continue;\n        problems.push(\n            `role:server '${name}' has no node in the runtime graph. Tag it drawOnGraph:false in its ` +\n                `project.json if that is intended.`,\n        );\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 = loadOrRender(workspaceRoot);\n    if (typeof depsFile === 'string') {\n        console.error(`\\n❌ Runtime architecture validation failed:\\n\\n${depsFile}\\n`);\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    // The api contracts come from the per-API files dependencies.json links to, which generate\n    // wrote from the table it derived from in memory.\n    // A cyclic graph leaves no graph to run the rest of the checks against, and is the one failure\n    // this rule never softens through the report-only window below — see deriveOrRender.\n    const derived = deriveOrRender(workspaceRoot, depsFile, hiddenProjects);\n    if (typeof derived === 'string') {\n        console.error(`\\n❌ Runtime architecture validation failed:\\n\\n${derived}\\n`);\n        return { success: false };\n    }\n    const report = derived;\n    const graph = report.graph;\n    for (const warning of report.warnings) console.warn(`⚠️  ${warning}`);\n    printAutoHiddenServers(report.autoHidden);\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[] = [\n        ...report.problems,\n        ...checkServersPresent(depsFile.projects, hiddenProjects, graph),\n    ];\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 (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\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 * Workspace-level checks on the runtime microservice graph:\n *   1. Unchanged: the freshly-assembled graph must match the committed\n *      architecture/runtime-dependencies.json (run `architecture:generate`).\n *   2. Every role:server project has a node on the graph.\n *\n * CYCLES ARE NOT CHECKED HERE, and there is deliberately no allowlist for them any more. A runtime\n * cycle now fails inside the DERIVATION — `assignLevels` (lib/runtime-graph-levels.ts) throws a\n * RuleFailError naming every chain, because CD deploys in dependency order and a cyclic architecture\n * has no such order. `deriveRuntimeGraphReport` below therefore cannot return a cyclic graph, and the\n * only way past it is to break the cycle, or to declare ONE edge with a `cutLegacyCycle:<target>` nx\n * tag on the CALLING project.\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 { RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport { loadBlessedGraph, DEFAULT_GRAPH_PATH } from '../../lib/graph-loader';\nimport { ApiContractFiles } from '../../lib/api-contract-files';\nimport type { DependenciesFile } from '../../lib/graph-loader';\nimport { toError } from '../../toError';\nimport type { EnhancedGraph } from '../../lib/graph-sorter';\nimport {\n    deriveRuntimeGraphReport,\n    loadRuntimeGraph,\n    runtimeGraphFileExists,\n    serializeRuntimeGraph,\n} from '../../lib/runtime-graph';\nimport type { RuntimeGraph, RuntimeGraphReport } from '../../lib/runtime-graph';\nimport { printAutoHiddenServers } from '../../lib/runtime-participant-resolver';\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/**\n * The derived report, or the RENDERED failure when the derivation refused to produce one.\n *\n * `assignLevels` throws a `RuleFailError` on a cyclic graph, and its cures live in that error's\n * `Option[]` — which `Error.message` does NOT carry. This executor is the top-level handler for its\n * nx target, so it renders through the one human renderer here; letting the throw escape `runExecutor`\n * would print the message with every cure silently dropped. Nothing is swallowed: the caller reports\n * the rendered text and fails, and anything that is not a rule verdict is rethrown untouched.\n *\n * A rendered failure ends the run rather than joining `problems`: there is no graph left to run the\n * other checks against, and a cycle is deliberately the one failure this rule does NOT route through\n * its report-only window — an architecture with no deploy order is not a style preference.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches checkUnchanged in this file\nfunction deriveOrRender(\n    workspaceRoot: string,\n    depsFile: DependenciesFile,\n    hiddenProjects: Set<string>,\n): RuntimeGraphReport | string {\n    // webpieces-disable no-unmanaged-exceptions -- top-level handler for this nx target; it renders, it does not swallow\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // The queue/trigger data comes from the generated architecture/apis/<Api>.json files that\n        // dependencies.json links to — the same files generate wrote from its in-memory table.\n        const apiContracts = new ApiContractFiles().load(\n            workspaceRoot, DEFAULT_GRAPH_PATH, depsFile.apiContractFiles);\n        return deriveRuntimeGraphReport(\n            depsFile.projects, hiddenProjects, apiContracts, depsFile.externalSystems,\n            depsFile.remoteServices);\n    } catch (err: unknown) {\n        const error = toError(err);\n        if (error instanceof RuleFailError) return renderRuleFailForHuman(error);\n        throw error;\n    }\n}\n\n/**\n * The committed dependencies.json, or the RENDERED failure when it is absent or cannot be read as the\n * current shape (e.g. it still carries the retired `apiContracts` key). Rendered here for the same\n * reason as deriveOrRender: this executor is the top-level handler for its nx target.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches deriveOrRender in this file\nfunction loadOrRender(workspaceRoot: string): DependenciesFile | string {\n    // webpieces-disable no-unmanaged-exceptions -- top-level handler for this nx target; it renders, it does not swallow\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const depsFile = loadBlessedGraph(workspaceRoot);\n        return depsFile ?? 'No architecture/dependencies.json — run: nx run architecture:generate';\n    } catch (err: unknown) {\n        const error = toError(err);\n        if (error instanceof RuleFailError) return renderRuleFailForHuman(error);\n        throw error;\n    }\n}\n\n/**\n * Every `role:server` project must have a NODE in the runtime graph. A pure set difference against\n * what the derivation produced, and it exists because the derivation once dropped relation-less\n * servers silently: the diagram claimed to be complete while a deployed service was missing from it.\n * Now the only sanctioned way for a server to be absent from the drawing is `drawOnGraph:false`, and\n * anything else that ever removes one fails the build by name instead of disappearing quietly.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches checkUnchanged in this file\nexport function checkServersPresent(\n    projects: EnhancedGraph,\n    hiddenProjects: Set<string>,\n    graph: RuntimeGraph,\n): string[] {\n    const problems: string[] = [];\n    for (const name of Object.keys(projects).sort()) {\n        if (projects[name].role !== 'server') continue;\n        if (hiddenProjects.has(name)) continue;\n        if (graph.services[name] !== undefined) continue;\n        problems.push(\n            `role:server '${name}' has no node in the runtime graph. Tag it drawOnGraph:false in its ` +\n                `project.json if that is intended.`,\n        );\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 = loadOrRender(workspaceRoot);\n    if (typeof depsFile === 'string') {\n        console.error(`\\n❌ Runtime architecture validation failed:\\n\\n${depsFile}\\n`);\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    // The api contracts come from the per-API files dependencies.json links to, which generate\n    // wrote from the table it derived from in memory.\n    // A cyclic graph leaves no graph to run the rest of the checks against, and is the one failure\n    // this rule never softens through the report-only window below — see deriveOrRender.\n    const derived = deriveOrRender(workspaceRoot, depsFile, hiddenProjects);\n    if (typeof derived === 'string') {\n        console.error(`\\n❌ Runtime architecture validation failed:\\n\\n${derived}\\n`);\n        return { success: false };\n    }\n    const report = derived;\n    const graph = report.graph;\n    for (const warning of report.warnings) console.warn(`⚠️  ${warning}`);\n    printAutoHiddenServers(report.autoHidden);\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[] = [\n        ...report.problems,\n        ...checkServersPresent(depsFile.projects, hiddenProjects, graph),\n    ];\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 (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\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/graph-loader.d.ts

@@ -8,6 +8,7 @@
  * {
  *     "aiInstructions": "...how AI should use the per-project fields...",
  *     "apiContractFiles": { "<ApiName>": "apis/<ApiName>.json" },
+ *     "remoteServices": { "<serviceName>": { "label"?, "implements": [{ "api", "type" }] } },
  *     "projects": {
  *         "<project>": { level, framework, products, shortDescription,
  *                        responsibilitiesFile, designFile, dependsOn }
@@ -32,6 +33,7 @@
 import type { EnhancedGraph } from './graph-sorter';
 import type { ExternalSystemDecls } from './api-usage/api-relations';
 import type { ApiContractFileRefs } from './api-contract-files';
+import type { RemoteServices } from './remote-services';
 /**
  * Default path for the dependencies file (relative to workspace root)
  */
@@ -70,6 +72,12 @@ export declare class DependenciesFile {
      * not written would make generate and validate disagree.
      */
     readonly externalSystems: ExternalSystemDecls;
+    /**
+     * REVIEWED out-of-workspace services a `uses` may target (#1203), keyed by service name. Like
+     * `apiContractFiles` it is approval metadata: generation reads it and writes it back verbatim,
+     * and never infers or adds an entry. See remote-services.ts.
+     */
+    readonly remoteServices: RemoteServices;
     constructor(aiInstructions: string, commands: CommandMap, projects: EnhancedGraph, 
     /**
      * apiClassName -> its contract file (`apis/<ApiName>.json`, relative to this file's
@@ -82,7 +90,13 @@ export declare class DependenciesFile {
      * the runtime graph is derived from the committed files, so a declaration that is scanned but
      * not written would make generate and validate disagree.
      */
-    externalSystems?: ExternalSystemDecls);
+    externalSystems?: ExternalSystemDecls, 
+    /**
+     * REVIEWED out-of-workspace services a `uses` may target (#1203), keyed by service name. Like
+     * `apiContractFiles` it is approval metadata: generation reads it and writes it back verbatim,
+     * and never infers or adds an entry. See remote-services.ts.
+     */
+    remoteServices?: RemoteServices);
 }
 /**
  * Load the blessed graph from disk. Understands both the current wrapper
@@ -100,7 +114,7 @@ export declare function loadBlessedGraph(workspaceRoot: string, graphPath?: stri
  * @param workspaceRoot - Absolute path to workspace root
  * @param graphPath - Relative path to graph file (default: architecture/dependencies.json)
  */
-export declare function saveGraph(graph: EnhancedGraph, workspaceRoot: string, graphPath?: string, apiContractFiles?: ApiContractFileRefs, externalSystems?: ExternalSystemDecls): void;
+export declare function saveGraph(graph: EnhancedGraph, workspaceRoot: string, graphPath?: string, apiContractFiles?: ApiContractFileRefs, externalSystems?: ExternalSystemDecls, remoteServices?: RemoteServices): void;
 /**
  * Check if the graph file exists
  */