@webpieces/nx-webpieces-rules 0.4.832 → 0.4.834

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/nx-webpieces-rules",
-  "version": "0.4.832",
+  "version": "0.4.834",
   "description": "Nx-specific webpieces validation rules and graph tooling. Bundles all @webpieces rule packages with Nx graph validators and an inference plugin.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -18,13 +18,13 @@
     "README.md"
   ],
   "dependencies": {
-    "@webpieces/ai-hook-rules": "0.4.832",
-    "@webpieces/api-doc-model": "0.4.832",
-    "@webpieces/code-rules": "0.4.832",
-    "@webpieces/core-util": "0.4.832",
-    "@webpieces/eslint-rules": "0.4.832",
-    "@webpieces/pr-gate": "0.4.832",
-    "@webpieces/rules-config": "0.4.832",
+    "@webpieces/ai-hook-rules": "0.4.834",
+    "@webpieces/api-doc-model": "0.4.834",
+    "@webpieces/code-rules": "0.4.834",
+    "@webpieces/core-util": "0.4.834",
+    "@webpieces/eslint-rules": "0.4.834",
+    "@webpieces/pr-gate": "0.4.834",
+    "@webpieces/rules-config": "0.4.834",
     "madge": "8.0.0"
   },
   "peerDependencies": {

package/src/executors/generate/executor.js

@@ -17,6 +17,7 @@ const graph_cycles_1 = require("../../lib/graph-cycles");
 const graph_loader_1 = require("../../lib/graph-loader");
 const api_contract_files_1 = require("../../lib/api-contract-files");
 const graph_metadata_1 = require("../../lib/graph-metadata");
+const tag_truth_1 = require("../../lib/tag-truth");
 const api_scanner_1 = require("../../lib/api-usage/api-scanner");
 // The unresolved-contract report moved beside the other contract reports when api-scanner.ts reached
 // its file-size limit.
@@ -153,6 +154,7 @@ async function generateEverything(workspaceRoot, graphPath) {
     console.log('🏷️  Enriching graph with framework + responsibilities metadata...');
     const projectInfos = await (0, graph_metadata_1.collectProjectInfo)();
     (0, graph_metadata_1.enrichGraph)(enhancedGraph, projectInfos, workspaceRoot);
+    new tag_truth_1.TagTruthCheck().assertTrue(enhancedGraph, projectInfos, workspaceRoot); // #1064, before any write
     // Step 3b: Classify each api-lib edge (implements/uses + rpc/pubsub) by
     // scanning source, so dependencies.json + the viz + the runtime graph all
     // read the same derived truth.

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

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/generate/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Generate Executor\n *\n * Generates the architecture dependency graph and saves it to architecture/dependencies.json, 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 { writeTemplate, RuleFailError, renderRuleFailForHuman } 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 { ProjectInfo } from '../../lib/project-info';\nimport {\n    scanAndAttachApiRelations,\n    describeNonLiteralDecoratorArgs,\n    buildApiContracts,\n    describeMismatchedEndpointKinds,\n} from '../../lib/api-usage/api-scanner';\n// The unresolved-contract report moved beside the other contract reports when api-scanner.ts reached\n// its file-size limit.\nimport {\n    describeMcpExclusions,\n    describeUnresolvedApiCalls,\n} from '../../lib/api-usage/api-contract-errors';\nimport { buildExternalSystems } from '../../lib/api-usage/external-systems';\nimport type { ApiContracts, ExternalSystemDecls } from '../../lib/api-usage/api-relations';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport type { EnhancedGraph, GraphEntry } from '../../lib/graph-sorter';\nimport { GraphVisualizer } from '../../lib/graph-visualizer';\nimport { deriveRuntimeGraphReport, saveRuntimeGraph } from '../../lib/runtime-graph';\nimport { 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(`❌ ${report.problems.length} client call(s) name a service no module answers to:`);\n        for (const problem of report.problems) console.error(`     • ${problem}`);\n        console.error('   This FAILS architecture:validate-runtime-architecture.');\n    }\n}\n\n/** Print the derivation's guessed-edge warnings (nothing at all when the graph is fully targeted). */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction printRuntimeWarnings(warnings: string[]): void {\n    if (warnings.length === 0) return;\n    console.warn(`⚠️  ${warnings.length} runtime edge(s) could not be targeted to ONE service:`);\n    for (const warning of warnings) console.warn(`     • ${warning}`);\n}\n\n/**\n * Scan for api relations and attach them, surfacing any contract we could NOT map back to source.\n * Unresolved contracts mean the graph we are about to WRITE is incomplete, so they must be loud —\n * a green run that quietly omits a service gets committed, rendered, and trusted.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction scanApiRelations(\n    workspaceRoot: string,\n    graph: EnhancedGraph,\n    projectInfos: Map<string, ProjectInfo>,\n): ScannedTables {\n    console.log('🔎 Scanning source for implements/uses API relations...');\n    const externalApiPaths = loadRuntimeConfig(workspaceRoot).externalApiPaths;\n    const scan = scanAndAttachApiRelations(workspaceRoot, graph, projectInfos, externalApiPaths);\n    if (scan.unresolvedApiCalls.length > 0) console.warn(describeUnresolvedApiCalls(scan.unresolvedApiCalls));\n    // #1014: restated on EVERY run, green or red. An exclusion announced once, at the moment\n    // somebody adds it, is read by the one person who already knows the decision.\n    if (scan.apiDocRules.mcpExclusions.length > 0) {\n        console.log(describeMcpExclusions(scan.apiDocRules.mcpExclusions));\n    }\n    // A decorator argument we could not read costs the graph a basePath, a method, or a whole\n    // contract — none of which leaves a trace in the output. Name them before anything is written.\n    if (scan.nonLiteralDecoratorArgs.length > 0) {\n        console.warn(describeNonLiteralDecoratorArgs(scan.nonLiteralDecoratorArgs));\n    }\n    const contracts = buildApiContracts(scan);\n    // An endpoint whose declared trigger its api kind cannot deliver would silently draw a queue or a\n    // clock that nothing could ever fire — name it here, where the fix is one decorator away.\n    const mismatches = describeMismatchedEndpointKinds(contracts);\n    if (mismatches.length > 0) {\n        console.error(`❌ ${mismatches.length} @Endpoint kind(s) conflict with their api kind:`);\n        for (const mismatch of mismatches) console.error(`     • ${mismatch}`);\n    }\n    return new ScannedTables(contracts, buildExternalSystems(scan.apiIndex, projectInfos));\n}\n\n/** The two committed tables one scan produces, kept together so callers cannot persist just one. */\nclass ScannedTables {\n    constructor(\n        public readonly apiContracts: ApiContracts,\n        public readonly externalSystems: ExternalSystemDecls,\n    ) {}\n}\n\n/** Projects tagged drawOnGraph:false — kept in the JSON, omitted from every rendered graph. */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction hiddenProjectsIn(graph: EnhancedGraph): Set<string> {\n    const hidden = new Set<string>();\n    for (const name of Object.keys(graph)) {\n        if (graph[name].drawOnGraph === false) hidden.add(name);\n    }\n    return hidden;\n}\n\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction printGraphSummary(graph: EnhancedGraph): void {\n    const levels = new Set(Object.values(graph).map((entry: GraphEntry) => entry.level));\n    console.log(`\\n📈 Graph Summary:`);\n    console.log(`   Projects: ${Object.keys(graph).length}`);\n    console.log(`   Levels: ${levels.size} (0-${Math.max(...levels)})`);\n}\n\n/**\n * The whole generation pipeline. Split out of runExecutor so that function stays a thin\n * try/catch-and-report shell — the error reporting is what a caller reads on failure, and it should\n * not be separated from the throw by fifty lines of steps.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nasync function generateEverything(workspaceRoot: string, graphPath: string | undefined): Promise<void> {\n    // Step 1: Build the full graph from nx, then transitively reduce it to the view\n    console.log(\"📊 Generating dependency graph from nx's project graph...\");\n    const reducedGraph = await generateReducedGraph();\n\n    // Step 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(reducedGraph, cycles.levelsOf(enhancedGraph), 'the freshly sorted graph');\n\n    // Step 3: Enrich with AI metadata (framework, shortDescription, file\n    // pointers). This VALIDATES (responsibilities.md required per project)\n    // and throws before any write, so a failure never clobbers the file.\n    console.log('🏷️  Enriching graph with framework + responsibilities metadata...');\n    const projectInfos = await collectProjectInfo();\n    enrichGraph(enhancedGraph, projectInfos, workspaceRoot);\n\n    // Step 3b: Classify each api-lib edge (implements/uses + rpc/pubsub) by\n    // scanning source, so dependencies.json + the viz + the runtime graph all\n    // read the same derived truth.\n    const scanned = scanApiRelations(workspaceRoot, enhancedGraph, projectInfos);\n    const apiContracts = scanned.apiContracts;\n\n    // Step 4: 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 effectiveGraphPath = graphPath ?? DEFAULT_GRAPH_PATH;\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) 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(enhancedGraph, workspaceRoot, effectiveGraphPath, contractRefs, scanned.externalSystems);\n    console.log('✅ Graph saved successfully');\n\n    // Step 4b: Write the committed, clickable HTML view next to the JSON so\n    // dependencies.html regenerates in lock-step with dependencies.json.\n    const vizPaths = new GraphVisualizer().writeVisualization(enhancedGraph, workspaceRoot);\n    console.log(`✅ Wrote ${vizPaths.htmlPath}`);\n\n    // Step 5: Generate the runtime microservice graph from the same scan.\n    // Projects tagged drawOnGraph:false are threaded through so the runtime\n    // graph hides them too (they stay flagged in runtime-dependencies.json).\n    generateRuntimeGraph(\n        workspaceRoot,\n        enhancedGraph,\n        hiddenProjectsIn(enhancedGraph),\n        apiContracts,\n        scanned.externalSystems,\n    );\n\n    printGraphSummary(enhancedGraph);\n}\n\nexport default async function runExecutor(\n    options: GenerateExecutorOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    console.log('\\n📊 Architecture Graph Generator\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        await generateEverything(workspaceRoot, graphPath);\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        // 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 = 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('⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️');\n        }\n        return { success: false };\n    }\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/generate/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Generate Executor\n *\n * Generates the architecture dependency graph and saves it to architecture/dependencies.json, 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 { writeTemplate, RuleFailError, renderRuleFailForHuman } 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 {\n    scanAndAttachApiRelations,\n    describeNonLiteralDecoratorArgs,\n    buildApiContracts,\n    describeMismatchedEndpointKinds,\n} from '../../lib/api-usage/api-scanner';\n// The unresolved-contract report moved beside the other contract reports when api-scanner.ts reached\n// its file-size limit.\nimport {\n    describeMcpExclusions,\n    describeUnresolvedApiCalls,\n} from '../../lib/api-usage/api-contract-errors';\nimport { buildExternalSystems } from '../../lib/api-usage/external-systems';\nimport type { ApiContracts, ExternalSystemDecls } from '../../lib/api-usage/api-relations';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport type { EnhancedGraph, GraphEntry } from '../../lib/graph-sorter';\nimport { GraphVisualizer } from '../../lib/graph-visualizer';\nimport { deriveRuntimeGraphReport, saveRuntimeGraph } from '../../lib/runtime-graph';\nimport { 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(`❌ ${report.problems.length} client call(s) name a service no module answers to:`);\n        for (const problem of report.problems) console.error(`     • ${problem}`);\n        console.error('   This FAILS architecture:validate-runtime-architecture.');\n    }\n}\n\n/** Print the derivation's guessed-edge warnings (nothing at all when the graph is fully targeted). */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction printRuntimeWarnings(warnings: string[]): void {\n    if (warnings.length === 0) return;\n    console.warn(`⚠️  ${warnings.length} runtime edge(s) could not be targeted to ONE service:`);\n    for (const warning of warnings) console.warn(`     • ${warning}`);\n}\n\n/**\n * Scan for api relations and attach them, surfacing any contract we could NOT map back to source.\n * Unresolved contracts mean the graph we are about to WRITE is incomplete, so they must be loud —\n * a green run that quietly omits a service gets committed, rendered, and trusted.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction scanApiRelations(\n    workspaceRoot: string,\n    graph: EnhancedGraph,\n    projectInfos: Map<string, ProjectInfo>,\n): ScannedTables {\n    console.log('🔎 Scanning source for implements/uses API relations...');\n    const externalApiPaths = loadRuntimeConfig(workspaceRoot).externalApiPaths;\n    const scan = scanAndAttachApiRelations(workspaceRoot, graph, projectInfos, externalApiPaths);\n    if (scan.unresolvedApiCalls.length > 0) console.warn(describeUnresolvedApiCalls(scan.unresolvedApiCalls));\n    // #1014: restated on EVERY run, green or red. An exclusion announced once, at the moment\n    // somebody adds it, is read by the one person who already knows the decision.\n    if (scan.apiDocRules.mcpExclusions.length > 0) {\n        console.log(describeMcpExclusions(scan.apiDocRules.mcpExclusions));\n    }\n    // A decorator argument we could not read costs the graph a basePath, a method, or a whole\n    // contract — none of which leaves a trace in the output. Name them before anything is written.\n    if (scan.nonLiteralDecoratorArgs.length > 0) {\n        console.warn(describeNonLiteralDecoratorArgs(scan.nonLiteralDecoratorArgs));\n    }\n    const contracts = buildApiContracts(scan);\n    // An endpoint whose declared trigger its api kind cannot deliver would silently draw a queue or a\n    // clock that nothing could ever fire — name it here, where the fix is one decorator away.\n    const mismatches = describeMismatchedEndpointKinds(contracts);\n    if (mismatches.length > 0) {\n        console.error(`❌ ${mismatches.length} @Endpoint kind(s) conflict with their api kind:`);\n        for (const mismatch of mismatches) console.error(`     • ${mismatch}`);\n    }\n    return new ScannedTables(contracts, buildExternalSystems(scan.apiIndex, projectInfos));\n}\n\n/** The two committed tables one scan produces, kept together so callers cannot persist just one. */\nclass ScannedTables {\n    constructor(\n        public readonly apiContracts: ApiContracts,\n        public readonly externalSystems: ExternalSystemDecls,\n    ) {}\n}\n\n/** Projects tagged drawOnGraph:false — kept in the JSON, omitted from every rendered graph. */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction hiddenProjectsIn(graph: EnhancedGraph): Set<string> {\n    const hidden = new Set<string>();\n    for (const name of Object.keys(graph)) {\n        if (graph[name].drawOnGraph === false) hidden.add(name);\n    }\n    return hidden;\n}\n\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nfunction printGraphSummary(graph: EnhancedGraph): void {\n    const levels = new Set(Object.values(graph).map((entry: GraphEntry) => entry.level));\n    console.log(`\\n📈 Graph Summary:`);\n    console.log(`   Projects: ${Object.keys(graph).length}`);\n    console.log(`   Levels: ${levels.size} (0-${Math.max(...levels)})`);\n}\n\n/**\n * The whole generation pipeline. Split out of runExecutor so that function stays a thin\n * try/catch-and-report shell — the error reporting is what a caller reads on failure, and it should\n * not be separated from the throw by fifty lines of steps.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, like the rest of this executor file\nasync function generateEverything(workspaceRoot: string, graphPath: string | undefined): Promise<void> {\n    // Step 1: Build the full graph from nx, then transitively reduce it to the view\n    console.log(\"📊 Generating dependency graph from nx's project graph...\");\n    const reducedGraph = await generateReducedGraph();\n\n    // Step 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(reducedGraph, cycles.levelsOf(enhancedGraph), 'the freshly sorted graph');\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    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);\n    const apiContracts = scanned.apiContracts;\n\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 effectiveGraphPath = graphPath ?? DEFAULT_GRAPH_PATH;\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) 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(enhancedGraph, workspaceRoot, effectiveGraphPath, contractRefs, scanned.externalSystems);\n    console.log('✅ Graph saved successfully');\n\n    // Step 4b: Write the committed, clickable HTML view next to the JSON so\n    // dependencies.html regenerates in lock-step with dependencies.json.\n    const vizPaths = new GraphVisualizer().writeVisualization(enhancedGraph, workspaceRoot);\n    console.log(`✅ Wrote ${vizPaths.htmlPath}`);\n\n    // Step 5: Generate the runtime microservice graph from the same scan.\n    // Projects tagged drawOnGraph:false are threaded through so the runtime\n    // graph hides them too (they stay flagged in runtime-dependencies.json).\n    generateRuntimeGraph(\n        workspaceRoot,\n        enhancedGraph,\n        hiddenProjectsIn(enhancedGraph),\n        apiContracts,\n        scanned.externalSystems,\n    );\n\n    printGraphSummary(enhancedGraph);\n}\n\nexport default async function runExecutor(\n    options: GenerateExecutorOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    console.log('\\n📊 Architecture Graph Generator\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        await generateEverything(workspaceRoot, graphPath);\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        // 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 = 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('⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️');\n        }\n        return { success: false };\n    }\n}\n"]}

package/src/executors/openapi-components-generate/executor.d.ts

@@ -17,7 +17,8 @@
  *     }
  *   }
  *
- * where the manifest declares `"kind": "components"` and names the library's entry files. The
+ * where the manifest declares `"kind": "components"` and names the library's entry files. Only a
+ * `role:api-lib` project may carry the tag (#1064, D5) — it is refused here and in validate-nx-wiring. The
  * `^openapi-components-generate` edge orders a chain of DTO libraries; a contract library's
  * `openapi-generate` carries the same edge. validate-nx-wiring enforces both (ComponentsWiring).
  *

package/src/executors/openapi-components-generate/executor.js

@@ -18,7 +18,8 @@
  *     }
  *   }
  *
- * where the manifest declares `"kind": "components"` and names the library's entry files. The
+ * where the manifest declares `"kind": "components"` and names the library's entry files. Only a
+ * `role:api-lib` project may carry the tag (#1064, D5) — it is refused here and in validate-nx-wiring. The
  * `^openapi-components-generate` edge orders a chain of DTO libraries; a contract library's
  * `openapi-generate` carries the same edge. validate-nx-wiring enforces both (ComponentsWiring).
  *
@@ -32,7 +33,9 @@ const core_util_1 = require("@webpieces/core-util");
 const generator_package_1 = require("../../lib/api-docs/generator-package");
 const executor_1 = require("../openapi-generate/executor");
 /** `openapi-components-generate`: a DTO library's `components.openapi.json`. */
-exports.COMPONENTS_DOCUMENT = new executor_1.GenerateSpec(core_util_1.GeneratedApiDocsLayout.COMPONENTS_TARGET, generator_package_1.OPENAPI_COMPONENTS_GENERATOR);
+exports.COMPONENTS_DOCUMENT = new executor_1.GenerateSpec(core_util_1.GeneratedApiDocsLayout.COMPONENTS_TARGET, generator_package_1.OPENAPI_COMPONENTS_GENERATOR, 
+// #1064 (D5): only a role:api-lib publishes the schemas contract documents $ref.
+'api-lib');
 // webpieces-disable no-function-outside-class -- nx executor module: nx resolves a default-export function here
 async function runExecutor(options, context) {
     return executor_1.GenerateExecutorMain.run(exports.COMPONENTS_DOCUMENT, options, context);

package/src/executors/openapi-components-generate/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/openapi-components-generate/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAmBH,8BAKC;AArBD,oDAA8D;AAE9D,4EAAoF;AACpF,2DAIsC;AAEtC,gFAAgF;AACnE,QAAA,mBAAmB,GAAG,IAAI,uBAAY,CAC/C,kCAAsB,CAAC,iBAAiB,EACxC,gDAA4B,CAC/B,CAAC;AAEF,gHAAgH;AACjG,KAAK,UAAU,WAAW,CACrC,OAA+B,EAC/B,OAAwB;IAExB,OAAO,+BAAoB,CAAC,GAAG,CAAC,2BAAmB,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAC3E,CAAC","sourcesContent":["/**\n * openapi-components-generate Executor (#1058)\n *\n * Renders a DTO library's components-only OpenAPI document, `components.openapi.json` — every type\n * the library exports and declares, `info.version` = the package version — INTO the outputPath of the\n * target it dependsOn (the library's `build`), so it ships inside the library's npm package exactly as\n * a contract library's documents do. Contract documents `$ref` its schemas instead of copying them.\n *\n * Consumers do not declare this executor. The nx-webpieces-rules plugin INFERS the target on a project\n * tagged `generate:openapi-components`; project.json states only the consumer's values:\n *\n *   \"tags\": [\"generate:openapi-components\"],\n *   \"targets\": {\n *     \"openapi-components-generate\": {\n *       \"dependsOn\": [\"build\", \"^openapi-components-generate\"],\n *       \"options\": { \"manifest\": \"<project>/openapi.manifest.json\", \"format\": \"json\" }\n *     }\n *   }\n *\n * where the manifest declares `\"kind\": \"components\"` and names the library's entry files. The\n * `^openapi-components-generate` edge orders a chain of DTO libraries; a contract library's\n * `openapi-generate` carries the same edge. validate-nx-wiring enforces both (ComponentsWiring).\n *\n * It is the openapi-generate executor body with its own target name and generator minimum: `wp-openapi`\n * reads the manifest's `kind` and decides what to render.\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { GeneratedApiDocsLayout } from '@webpieces/core-util';\nimport { ExecutorResult } from '../../executor-result';\nimport { OPENAPI_COMPONENTS_GENERATOR } from '../../lib/api-docs/generator-package';\nimport {\n    GenerateExecutorMain,\n    GenerateSpec,\n    OpenApiGenerateOptions,\n} from '../openapi-generate/executor';\n\n/** `openapi-components-generate`: a DTO library's `components.openapi.json`. */\nexport const COMPONENTS_DOCUMENT = new GenerateSpec(\n    GeneratedApiDocsLayout.COMPONENTS_TARGET,\n    OPENAPI_COMPONENTS_GENERATOR,\n);\n\n// webpieces-disable no-function-outside-class -- nx executor module: nx resolves a default-export function here\nexport default async function runExecutor(\n    options: OpenApiGenerateOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    return GenerateExecutorMain.run(COMPONENTS_DOCUMENT, options, context);\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/openapi-components-generate/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;AAqBH,8BAKC;AAvBD,oDAA8D;AAE9D,4EAAoF;AACpF,2DAIsC;AAEtC,gFAAgF;AACnE,QAAA,mBAAmB,GAAG,IAAI,uBAAY,CAC/C,kCAAsB,CAAC,iBAAiB,EACxC,gDAA4B;AAC5B,iFAAiF;AACjF,SAAS,CACZ,CAAC;AAEF,gHAAgH;AACjG,KAAK,UAAU,WAAW,CACrC,OAA+B,EAC/B,OAAwB;IAExB,OAAO,+BAAoB,CAAC,GAAG,CAAC,2BAAmB,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAC3E,CAAC","sourcesContent":["/**\n * openapi-components-generate Executor (#1058)\n *\n * Renders a DTO library's components-only OpenAPI document, `components.openapi.json` — every type\n * the library exports and declares, `info.version` = the package version — INTO the outputPath of the\n * target it dependsOn (the library's `build`), so it ships inside the library's npm package exactly as\n * a contract library's documents do. Contract documents `$ref` its schemas instead of copying them.\n *\n * Consumers do not declare this executor. The nx-webpieces-rules plugin INFERS the target on a project\n * tagged `generate:openapi-components`; project.json states only the consumer's values:\n *\n *   \"tags\": [\"generate:openapi-components\"],\n *   \"targets\": {\n *     \"openapi-components-generate\": {\n *       \"dependsOn\": [\"build\", \"^openapi-components-generate\"],\n *       \"options\": { \"manifest\": \"<project>/openapi.manifest.json\", \"format\": \"json\" }\n *     }\n *   }\n *\n * where the manifest declares `\"kind\": \"components\"` and names the library's entry files. Only a\n * `role:api-lib` project may carry the tag (#1064, D5) — it is refused here and in validate-nx-wiring. The\n * `^openapi-components-generate` edge orders a chain of DTO libraries; a contract library's\n * `openapi-generate` carries the same edge. validate-nx-wiring enforces both (ComponentsWiring).\n *\n * It is the openapi-generate executor body with its own target name and generator minimum: `wp-openapi`\n * reads the manifest's `kind` and decides what to render.\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { GeneratedApiDocsLayout } from '@webpieces/core-util';\nimport { ExecutorResult } from '../../executor-result';\nimport { OPENAPI_COMPONENTS_GENERATOR } from '../../lib/api-docs/generator-package';\nimport {\n    GenerateExecutorMain,\n    GenerateSpec,\n    OpenApiGenerateOptions,\n} from '../openapi-generate/executor';\n\n/** `openapi-components-generate`: a DTO library's `components.openapi.json`. */\nexport const COMPONENTS_DOCUMENT = new GenerateSpec(\n    GeneratedApiDocsLayout.COMPONENTS_TARGET,\n    OPENAPI_COMPONENTS_GENERATOR,\n    // #1064 (D5): only a role:api-lib publishes the schemas contract documents $ref.\n    'api-lib',\n);\n\n// webpieces-disable no-function-outside-class -- nx executor module: nx resolves a default-export function here\nexport default async function runExecutor(\n    options: OpenApiGenerateOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    return GenerateExecutorMain.run(COMPONENTS_DOCUMENT, options, context);\n}\n"]}

package/src/executors/openapi-generate/executor.d.ts

@@ -53,7 +53,19 @@ export interface OpenApiGenerateOptions {
 export declare class GenerateSpec {
     readonly targetName: string;
     readonly generator: GeneratorPackage;
-    constructor(targetName: string, generator: GeneratorPackage);
+    /**
+     * The `role:` tag the project must carry, or null when any role may run it. A components
+     * document is published only by a `role:api-lib` (#1064, D5): tagging a general library so its
+     * types can be `$ref`ed is not a way to put them on the wire.
+     */
+    readonly requiredRole: string | null;
+    constructor(targetName: string, generator: GeneratorPackage, 
+    /**
+     * The `role:` tag the project must carry, or null when any role may run it. A components
+     * document is published only by a `role:api-lib` (#1064, D5): tagging a general library so its
+     * types can be `$ref`ed is not a way to put them on the wire.
+     */
+    requiredRole: string | null);
 }
 /** `openapi-generate`: a contract library's documents and MCP tool catalogs. */
 export declare const CONTRACT_DOCUMENTS: GenerateSpec;
@@ -69,6 +81,8 @@ export declare class OpenApiGenerate {
     spec: GenerateSpec, resolver?: ConsumerBinResolver, runner?: GeneratorRunner, scratch?: RepoScratchDirs);
     /** @returns the files written, absolute. Throws RuleFailError on every refusal. */
     run(options: OpenApiGenerateOptions, context: ExecutorContext): string[];
+    /** Refuses to run for a project that does not carry the spec's required role. */
+    private assertRole;
 }
 /** The single top-level handler both generating executors report through. */
 export declare class GenerateExecutorMain {

package/src/executors/openapi-generate/executor.js

@@ -56,14 +56,22 @@ const toError_1 = require("../../toError");
 class GenerateSpec {
     targetName;
     generator;
-    constructor(targetName, generator) {
+    requiredRole;
+    constructor(targetName, generator, 
+    /**
+     * The `role:` tag the project must carry, or null when any role may run it. A components
+     * document is published only by a `role:api-lib` (#1064, D5): tagging a general library so its
+     * types can be `$ref`ed is not a way to put them on the wire.
+     */
+    requiredRole) {
         this.targetName = targetName;
         this.generator = generator;
+        this.requiredRole = requiredRole;
     }
 }
 exports.GenerateSpec = GenerateSpec;
 /** `openapi-generate`: a contract library's documents and MCP tool catalogs. */
-exports.CONTRACT_DOCUMENTS = new GenerateSpec(core_util_1.GeneratedApiDocsLayout.OPENAPI_TARGET, generator_package_1.OPENAPI_GENERATOR);
+exports.CONTRACT_DOCUMENTS = new GenerateSpec(core_util_1.GeneratedApiDocsLayout.OPENAPI_TARGET, generator_package_1.OPENAPI_GENERATOR, null);
 /** Everything except the process-facing reporting, so the suite drives it exactly as nx does. */
 class OpenApiGenerate {
     spec;
@@ -82,6 +90,7 @@ class OpenApiGenerate {
     run(options, context) {
         const ruleName = this.spec.targetName;
         const target = generator_target_1.GeneratorTarget.of(ruleName, context);
+        this.assertRole(context);
         const outDir = target.documentsDir(ruleName);
         const manifest = target.requiredOption(options.manifest, 'manifest');
         const format = target.requiredOption(options.format, 'format');
@@ -105,6 +114,25 @@ class OpenApiGenerate {
             fs.rmSync(staging, { recursive: true, force: true });
         }
     }
+    /** Refuses to run for a project that does not carry the spec's required role. */
+    assertRole(context) {
+        const required = this.spec.requiredRole;
+        if (required === null)
+            return;
+        const projectName = context.projectName ?? '';
+        const tags = context.projectsConfigurations?.projects[projectName]?.tags ?? [];
+        if (tags.includes(`role:${required}`))
+            return;
+        const carried = tags.filter((tag) => tag.startsWith('role:')).join(', ') || 'no role tag';
+        throw new rules_config_1.RuleFailError(this.spec.targetName, `${projectName} runs ${this.spec.targetName} but carries ${carried} — a components document is ` +
+            `published only by a role:${required} project. Tagging a general library is not a way to put ` +
+            'its types on the wire: every type a contract reaches is declared in an api library.', undefined, undefined, [
+            new rules_config_1.Option(`Move the wire types into a role:${required} DTO library and tag THAT one ` +
+                '"generate:openapi-components"; drop the tag from this project.', true),
+            new rules_config_1.Option(`If this project holds only contracts and wire types, retag it role:${required} ` +
+                '(validate-api-lib-tag checks that it does).'),
+        ]);
+    }
 }
 exports.OpenApiGenerate = OpenApiGenerate;
 /** The single top-level handler both generating executors report through. */

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

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/openapi-generate/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * openapi-generate Executor\n *\n * Renders a project's contracts to OpenAPI, plus ONE MCP tool catalog per contract\n * (`mcp-<ContractClass>-tools.json`), INTO the outputPath of the target it dependsOn — the api\n * library's `build` (its @nx/js:tsc step) — so the documents are packed and published inside the api library's npm\n * package: a consumer installs the library and has the contract. They are build output, never\n * committed.\n *\n * Consumers do not declare this executor. The nx-webpieces-rules plugin INFERS the target on a project\n * tagged `generate:openapi` (executor, cache, inputs, outputs); project.json states only what is the\n * consumer's to decide, under the same target name:\n *\n *   \"tags\": [\"generate:openapi\"],\n *   \"targets\": {\n *     \"build\": { \"executor\": \"@nx/js:tsc\", \"outputs\": [\"{options.outputPath}\"],\n *                \"options\": { \"outputPath\": \"dist/<project>\", ... } },\n *     \"openapi-generate\": {\n *       \"dependsOn\": [\"build\"],\n *       \"options\": { \"manifest\": \"<project>/openapi.manifest.json\", \"format\": \"both\" }\n *     }\n *   }\n *\n * and dependents pull it in through nx.json: `\"^openapi-generate\"` in every targetDefaults entry\n * governing a `build` or `test` (#1023 — see GenerateWiring).\n *\n * The output directory is the outputPath of the ONE target `dependsOn` names (GeneratedApiDocsLayout\n * in @webpieces/core-util — the same lookup the MCP server reads with), never a hardcoded target name\n * and never an assumed dist/. `outputs` are CHECKED against what a run wrote — see GeneratorTarget. The\n * generator itself is the CONSUMER's `@webpieces/openapi-generator`, resolved from its node_modules and\n * version-checked; this plugin bundles no copy of it (see ConsumerBinResolver).\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { GeneratedApiDocsLayout } from '@webpieces/core-util';\nimport { RepoScratchDirs, RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { ExecutorResult } from '../../executor-result';\nimport { ConsumerBinRequest, ConsumerBinResolver } from '../../lib/api-docs/consumer-bin-resolver';\nimport { GeneratorPackage, OPENAPI_GENERATOR } from '../../lib/api-docs/generator-package';\nimport { GeneratorRunner } from '../../lib/api-docs/generator-runner';\nimport { GeneratorTarget, StagedOutput } from '../../lib/api-docs/generator-target';\nimport { toError } from '../../toError';\n\nexport interface OpenApiGenerateOptions {\n    /** Workspace-relative path to the project's `openapi.manifest.json`. Required; no default. */\n    manifest?: string;\n    /** `json`, `yaml` or `both`. Required; no default — it decides what the package ships. */\n    format?: string;\n}\n\n/**\n * WHICH generating target an {@link OpenApiGenerate} runs as: the target name (what its refusals are\n * reported under, and whose dependsOn names the output directory) and the oldest generator release\n * carrying what that target needs. Data-only.\n *\n * `wp-openapi` decides what to render from the manifest's own `kind`, so the contract documents and a\n * DTO library's components document (#1058) are one executor body with two of these.\n */\nexport class GenerateSpec {\n    constructor(\n        readonly targetName: string,\n        readonly generator: GeneratorPackage,\n    ) {}\n}\n\n/** `openapi-generate`: a contract library's documents and MCP tool catalogs. */\nexport const CONTRACT_DOCUMENTS = new GenerateSpec(GeneratedApiDocsLayout.OPENAPI_TARGET, OPENAPI_GENERATOR);\n\n/** Everything except the process-facing reporting, so the suite drives it exactly as nx does. */\nexport class OpenApiGenerate {\n    constructor(\n        /** Which generating target this run is — stated by every caller, never implied. */\n        private readonly spec: GenerateSpec,\n        private readonly resolver: ConsumerBinResolver = new ConsumerBinResolver(),\n        private readonly runner: GeneratorRunner = new GeneratorRunner(),\n        private readonly scratch: RepoScratchDirs = new RepoScratchDirs(),\n    ) {}\n\n    /** @returns the files written, absolute. Throws RuleFailError on every refusal. */\n    run(options: OpenApiGenerateOptions, context: ExecutorContext): string[] {\n        const ruleName = this.spec.targetName;\n        const target = GeneratorTarget.of(ruleName, context);\n        const outDir = target.documentsDir(ruleName);\n        const manifest = target.requiredOption(options.manifest, 'manifest');\n        const format = target.requiredOption(options.format, 'format');\n        const bin = this.resolver.resolve(new ConsumerBinRequest(\n            ruleName, this.spec.generator, [path.join(context.root, target.projectRoot), context.root]));\n\n        const staging = this.scratch.make(context.root, 'wp-openapi-generate-');\n        // webpieces-disable no-unmanaged-exceptions -- try/FINALLY only, nothing is caught: the staging\n        // directory is removed however this ends, and every throw still reaches runExecutor below\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const run = this.runner.run(bin, [\n                '--manifest', path.resolve(context.root, manifest), '--out', staging, '--format', format,\n            ], context.root);\n            if (!run.ok) {\n                throw new RuleFailError(\n                    ruleName,\n                    `${bin.packageName} ${bin.version} refused ${manifest}:\\n${run.output}`,\n                );\n            }\n            const written = new StagedOutput().publish(staging, outDir);\n            target.assertOutputsCover(written);\n            return written;\n        } finally {\n            fs.rmSync(staging, { recursive: true, force: true });\n        }\n    }\n}\n\n/** The single top-level handler both generating executors report through. */\nexport class GenerateExecutorMain {\n    // webpieces-disable no-function-outside-class -- static entry point of this class\n    static async run(spec: GenerateSpec, options: OpenApiGenerateOptions, context: ExecutorContext): Promise<ExecutorResult> {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- this IS the executor's single top-level handler\n        try {\n            const written = new OpenApiGenerate(spec).run(options, context);\n            for (const file of written) console.log(`wrote ${path.relative(context.root, file)}`);\n            return new ExecutorResult(true);\n        } catch (err: unknown) {\n            const error = toError(err);\n            console.error(`❌ ${spec.targetName}: ${error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message}`);\n            return new ExecutorResult(false);\n        }\n    }\n}\n\n// webpieces-disable no-function-outside-class -- nx executor module: nx resolves a default-export function here\nexport default async function runExecutor(\n    options: OpenApiGenerateOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    return GenerateExecutorMain.run(CONTRACT_DOCUMENTS, options, context);\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/openapi-generate/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;;AAwIH,8BAKC;;AA1ID,oDAA8D;AAC9D,0DAAyG;AACzG,+CAAyB;AACzB,mDAA6B;AAC7B,2DAAuD;AACvD,oFAAmG;AACnG,4EAA2F;AAC3F,0EAAsE;AACtE,0EAAoF;AACpF,2CAAwC;AASxC;;;;;;;GAOG;AACH,MAAa,YAAY;IAER;IACA;IAMA;IARb,YACa,UAAkB,EAClB,SAA2B;IACpC;;;;OAIG;IACM,YAA2B;QAP3B,eAAU,GAAV,UAAU,CAAQ;QAClB,cAAS,GAAT,SAAS,CAAkB;QAM3B,iBAAY,GAAZ,YAAY,CAAe;IACrC,CAAC;CACP;AAXD,oCAWC;AAED,gFAAgF;AACnE,QAAA,kBAAkB,GAAG,IAAI,YAAY,CAAC,kCAAsB,CAAC,cAAc,EAAE,qCAAiB,EAAE,IAAI,CAAC,CAAC;AAEnH,iGAAiG;AACjG,MAAa,eAAe;IAGH;IACA;IACA;IACA;IALrB;IACI,mFAAmF;IAClE,IAAkB,EAClB,WAAgC,IAAI,2CAAmB,EAAE,EACzD,SAA0B,IAAI,kCAAe,EAAE,EAC/C,UAA2B,IAAI,8BAAe,EAAE;QAHhD,SAAI,GAAJ,IAAI,CAAc;QAClB,aAAQ,GAAR,QAAQ,CAAiD;QACzD,WAAM,GAAN,MAAM,CAAyC;QAC/C,YAAO,GAAP,OAAO,CAAyC;IAClE,CAAC;IAEJ,mFAAmF;IACnF,GAAG,CAAC,OAA+B,EAAE,OAAwB;QACzD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC;QACtC,MAAM,MAAM,GAAG,kCAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACrD,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACzB,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QAC7C,MAAM,QAAQ,GAAG,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACrE,MAAM,MAAM,GAAG,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,0CAAkB,CACpD,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAEjG,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,sBAAsB,CAAC,CAAC;QACxE,gGAAgG;QAChG,0FAA0F;QAC1F,8DAA8D;QAC9D,IAAI,CAAC;YACD,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE;gBAC7B,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM;aAC3F,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;YACjB,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACV,MAAM,IAAI,4BAAa,CACnB,QAAQ,EACR,GAAG,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,OAAO,YAAY,QAAQ,MAAM,GAAG,CAAC,MAAM,EAAE,CAC1E,CAAC;YACN,CAAC;YACD,MAAM,OAAO,GAAG,IAAI,+BAAY,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC5D,MAAM,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;YACnC,OAAO,OAAO,CAAC;QACnB,CAAC;gBAAS,CAAC;YACP,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,CAAC;IACL,CAAC;IAED,iFAAiF;IACzE,UAAU,CAAC,OAAwB;QACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC;QACxC,IAAI,QAAQ,KAAK,IAAI;YAAE,OAAO;QAC9B,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC;QAC9C,MAAM,IAAI,GAAG,OAAO,CAAC,sBAAsB,EAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC;QAC/E,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,QAAQ,EAAE,CAAC;YAAE,OAAO;QAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,aAAa,CAAC;QAClG,MAAM,IAAI,4BAAa,CACnB,IAAI,CAAC,IAAI,CAAC,UAAU,EACpB,GAAG,WAAW,SAAS,IAAI,CAAC,IAAI,CAAC,UAAU,gBAAgB,OAAO,8BAA8B;YAC5F,4BAA4B,QAAQ,0DAA0D;YAC9F,qFAAqF,EACzF,SAAS,EACT,SAAS,EACT;YACI,IAAI,qBAAM,CACN,mCAAmC,QAAQ,gCAAgC;gBACvE,gEAAgE,EACpE,IAAI,CACP;YACD,IAAI,qBAAM,CACN,sEAAsE,QAAQ,GAAG;gBAC7E,6CAA6C,CACpD;SACJ,CACJ,CAAC;IACN,CAAC;CACJ;AAtED,0CAsEC;AAED,6EAA6E;AAC7E,MAAa,oBAAoB;IAC7B,kFAAkF;IAClF,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAkB,EAAE,OAA+B,EAAE,OAAwB;QAC1F,iHAAiH;QACjH,IAAI,CAAC;YACD,MAAM,OAAO,GAAG,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAChE,KAAK,MAAM,IAAI,IAAI,OAAO;gBAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;YACtF,OAAO,IAAI,gCAAc,CAAC,IAAI,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;YAC3B,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,UAAU,KAAK,KAAK,YAAY,4BAAa,CAAC,CAAC,CAAC,IAAA,qCAAsB,EAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACzH,OAAO,IAAI,gCAAc,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC;IACL,CAAC;CACJ;AAdD,oDAcC;AAED,gHAAgH;AACjG,KAAK,UAAU,WAAW,CACrC,OAA+B,EAC/B,OAAwB;IAExB,OAAO,oBAAoB,CAAC,GAAG,CAAC,0BAAkB,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAC1E,CAAC","sourcesContent":["/**\n * openapi-generate Executor\n *\n * Renders a project's contracts to OpenAPI, plus ONE MCP tool catalog per contract\n * (`mcp-<ContractClass>-tools.json`), INTO the outputPath of the target it dependsOn — the api\n * library's `build` (its @nx/js:tsc step) — so the documents are packed and published inside the api library's npm\n * package: a consumer installs the library and has the contract. They are build output, never\n * committed.\n *\n * Consumers do not declare this executor. The nx-webpieces-rules plugin INFERS the target on a project\n * tagged `generate:openapi` (executor, cache, inputs, outputs); project.json states only what is the\n * consumer's to decide, under the same target name:\n *\n *   \"tags\": [\"generate:openapi\"],\n *   \"targets\": {\n *     \"build\": { \"executor\": \"@nx/js:tsc\", \"outputs\": [\"{options.outputPath}\"],\n *                \"options\": { \"outputPath\": \"dist/<project>\", ... } },\n *     \"openapi-generate\": {\n *       \"dependsOn\": [\"build\"],\n *       \"options\": { \"manifest\": \"<project>/openapi.manifest.json\", \"format\": \"both\" }\n *     }\n *   }\n *\n * and dependents pull it in through nx.json: `\"^openapi-generate\"` in every targetDefaults entry\n * governing a `build` or `test` (#1023 — see GenerateWiring).\n *\n * The output directory is the outputPath of the ONE target `dependsOn` names (GeneratedApiDocsLayout\n * in @webpieces/core-util — the same lookup the MCP server reads with), never a hardcoded target name\n * and never an assumed dist/. `outputs` are CHECKED against what a run wrote — see GeneratorTarget. The\n * generator itself is the CONSUMER's `@webpieces/openapi-generator`, resolved from its node_modules and\n * version-checked; this plugin bundles no copy of it (see ConsumerBinResolver).\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { GeneratedApiDocsLayout } from '@webpieces/core-util';\nimport { Option, RepoScratchDirs, RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { ExecutorResult } from '../../executor-result';\nimport { ConsumerBinRequest, ConsumerBinResolver } from '../../lib/api-docs/consumer-bin-resolver';\nimport { GeneratorPackage, OPENAPI_GENERATOR } from '../../lib/api-docs/generator-package';\nimport { GeneratorRunner } from '../../lib/api-docs/generator-runner';\nimport { GeneratorTarget, StagedOutput } from '../../lib/api-docs/generator-target';\nimport { toError } from '../../toError';\n\nexport interface OpenApiGenerateOptions {\n    /** Workspace-relative path to the project's `openapi.manifest.json`. Required; no default. */\n    manifest?: string;\n    /** `json`, `yaml` or `both`. Required; no default — it decides what the package ships. */\n    format?: string;\n}\n\n/**\n * WHICH generating target an {@link OpenApiGenerate} runs as: the target name (what its refusals are\n * reported under, and whose dependsOn names the output directory) and the oldest generator release\n * carrying what that target needs. Data-only.\n *\n * `wp-openapi` decides what to render from the manifest's own `kind`, so the contract documents and a\n * DTO library's components document (#1058) are one executor body with two of these.\n */\nexport class GenerateSpec {\n    constructor(\n        readonly targetName: string,\n        readonly generator: GeneratorPackage,\n        /**\n         * The `role:` tag the project must carry, or null when any role may run it. A components\n         * document is published only by a `role:api-lib` (#1064, D5): tagging a general library so its\n         * types can be `$ref`ed is not a way to put them on the wire.\n         */\n        readonly requiredRole: string | null,\n    ) {}\n}\n\n/** `openapi-generate`: a contract library's documents and MCP tool catalogs. */\nexport const CONTRACT_DOCUMENTS = new GenerateSpec(GeneratedApiDocsLayout.OPENAPI_TARGET, OPENAPI_GENERATOR, null);\n\n/** Everything except the process-facing reporting, so the suite drives it exactly as nx does. */\nexport class OpenApiGenerate {\n    constructor(\n        /** Which generating target this run is — stated by every caller, never implied. */\n        private readonly spec: GenerateSpec,\n        private readonly resolver: ConsumerBinResolver = new ConsumerBinResolver(),\n        private readonly runner: GeneratorRunner = new GeneratorRunner(),\n        private readonly scratch: RepoScratchDirs = new RepoScratchDirs(),\n    ) {}\n\n    /** @returns the files written, absolute. Throws RuleFailError on every refusal. */\n    run(options: OpenApiGenerateOptions, context: ExecutorContext): string[] {\n        const ruleName = this.spec.targetName;\n        const target = GeneratorTarget.of(ruleName, context);\n        this.assertRole(context);\n        const outDir = target.documentsDir(ruleName);\n        const manifest = target.requiredOption(options.manifest, 'manifest');\n        const format = target.requiredOption(options.format, 'format');\n        const bin = this.resolver.resolve(new ConsumerBinRequest(\n            ruleName, this.spec.generator, [path.join(context.root, target.projectRoot), context.root]));\n\n        const staging = this.scratch.make(context.root, 'wp-openapi-generate-');\n        // webpieces-disable no-unmanaged-exceptions -- try/FINALLY only, nothing is caught: the staging\n        // directory is removed however this ends, and every throw still reaches runExecutor below\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const run = this.runner.run(bin, [\n                '--manifest', path.resolve(context.root, manifest), '--out', staging, '--format', format,\n            ], context.root);\n            if (!run.ok) {\n                throw new RuleFailError(\n                    ruleName,\n                    `${bin.packageName} ${bin.version} refused ${manifest}:\\n${run.output}`,\n                );\n            }\n            const written = new StagedOutput().publish(staging, outDir);\n            target.assertOutputsCover(written);\n            return written;\n        } finally {\n            fs.rmSync(staging, { recursive: true, force: true });\n        }\n    }\n\n    /** Refuses to run for a project that does not carry the spec's required role. */\n    private assertRole(context: ExecutorContext): void {\n        const required = this.spec.requiredRole;\n        if (required === null) return;\n        const projectName = context.projectName ?? '';\n        const tags = context.projectsConfigurations?.projects[projectName]?.tags ?? [];\n        if (tags.includes(`role:${required}`)) return;\n        const carried = tags.filter((tag: string) => tag.startsWith('role:')).join(', ') || 'no role tag';\n        throw new RuleFailError(\n            this.spec.targetName,\n            `${projectName} runs ${this.spec.targetName} but carries ${carried} — a components document is ` +\n                `published only by a role:${required} project. Tagging a general library is not a way to put ` +\n                'its types on the wire: every type a contract reaches is declared in an api library.',\n            undefined,\n            undefined,\n            [\n                new Option(\n                    `Move the wire types into a role:${required} DTO library and tag THAT one ` +\n                        '\"generate:openapi-components\"; drop the tag from this project.',\n                    true,\n                ),\n                new Option(\n                    `If this project holds only contracts and wire types, retag it role:${required} ` +\n                        '(validate-api-lib-tag checks that it does).',\n                ),\n            ],\n        );\n    }\n}\n\n/** The single top-level handler both generating executors report through. */\nexport class GenerateExecutorMain {\n    // webpieces-disable no-function-outside-class -- static entry point of this class\n    static async run(spec: GenerateSpec, options: OpenApiGenerateOptions, context: ExecutorContext): Promise<ExecutorResult> {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- this IS the executor's single top-level handler\n        try {\n            const written = new OpenApiGenerate(spec).run(options, context);\n            for (const file of written) console.log(`wrote ${path.relative(context.root, file)}`);\n            return new ExecutorResult(true);\n        } catch (err: unknown) {\n            const error = toError(err);\n            console.error(`❌ ${spec.targetName}: ${error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message}`);\n            return new ExecutorResult(false);\n        }\n    }\n}\n\n// webpieces-disable no-function-outside-class -- nx executor module: nx resolves a default-export function here\nexport default async function runExecutor(\n    options: OpenApiGenerateOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    return GenerateExecutorMain.run(CONTRACT_DOCUMENTS, options, context);\n}\n"]}

package/src/executors/validate-api-lib-tag/executor.d.ts

@@ -1,9 +1,11 @@
 /**
  * Validate API-lib Tag Executor
  *
- * Fails when the `role:api-lib` tag and the code disagree, in either direction:
- * a project tagged role:api-lib that exports no API contract, or a project that
- * exports an @ApiPath/@Rpc/@PubSub abstract class but is not tagged role:api-lib.
+ * Fails when the api roles and the code disagree, in either direction: a project
+ * tagged role:api-lib that exports neither a contract (@ApiPath/@Rpc/@PubSub,
+ * @WpInternal/@WpIpcEndpoint, or an in-process abstract …Api) nor only wire types,
+ * a role:api-client that exports no contract, or a project that exports an
+ * @ApiPath/@Rpc/@PubSub abstract class but carries neither api role (#1064, D3).
  *
  * Usage:
  * nx run architecture:validate-api-lib-tag

package/src/executors/validate-api-lib-tag/executor.js

@@ -2,9 +2,11 @@
 /**
  * Validate API-lib Tag Executor
  *
- * Fails when the `role:api-lib` tag and the code disagree, in either direction:
- * a project tagged role:api-lib that exports no API contract, or a project that
- * exports an @ApiPath/@Rpc/@PubSub abstract class but is not tagged role:api-lib.
+ * Fails when the api roles and the code disagree, in either direction: a project
+ * tagged role:api-lib that exports neither a contract (@ApiPath/@Rpc/@PubSub,
+ * @WpInternal/@WpIpcEndpoint, or an in-process abstract …Api) nor only wire types,
+ * a role:api-client that exports no contract, or a project that exports an
+ * @ApiPath/@Rpc/@PubSub abstract class but carries neither api role (#1064, D3).
  *
  * Usage:
  * nx run architecture:validate-api-lib-tag
@@ -23,9 +25,9 @@ async function runExecutor(_options, context) {
     try {
         const projectInfos = await (0, graph_metadata_1.collectProjectInfo)();
         const scan = new api_scanner_1.ApiUsageScanner(workspaceRoot, projectInfos).scan();
-        const violations = (0, api_lib_tag_validator_1.findApiLibTagViolations)(projectInfos, scan);
+        const violations = (0, api_lib_tag_validator_1.findApiLibTagViolations)(projectInfos, scan, workspaceRoot);
         if (violations.length === 0) {
-            console.log('✅ role:api-lib matches the code (every api-lib exports a contract, and vice-versa).');
+            console.log('✅ role:api-lib / role:api-client match the code (every api library exports a contract or only wire types, and vice-versa).');
             return { success: true };
         }
         console.error(`❌ ${violations.length} role:api-lib tag/code mismatch(es):\n`);

package/src/executors/validate-api-lib-tag/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-api-lib-tag/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;AAiBH,8BA8BC;AA5CD,6DAA8D;AAC9D,iEAAkE;AAClE,qFAAgH;AAChH,2CAAwC;AAUxC,uHAAuH;AACxG,KAAK,UAAU,WAAW,CACrC,QAAkC,EAClC,OAAwB;IAExB,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC,OAAO,CAAC,GAAG,CAAC,6DAA6D,CAAC,CAAC;IAE3E,8DAA8D;IAC9D,IAAI,CAAC;QACD,MAAM,YAAY,GAAG,MAAM,IAAA,mCAAkB,GAAE,CAAC;QAChD,MAAM,IAAI,GAAG,IAAI,6BAAe,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC,IAAI,EAAE,CAAC;QACrE,MAAM,UAAU,GAAG,IAAA,+CAAuB,EAAC,YAAY,EAAE,IAAI,CAAC,CAAC;QAE/D,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,CAAC,GAAG,CAAC,qFAAqF,CAAC,CAAC;YACnG,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC7B,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,KAAK,UAAU,CAAC,MAAM,wCAAwC,CAAC,CAAC;QAC9E,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACjC,OAAO,CAAC,KAAK,CAAC,IAAA,kDAA0B,EAAC,SAAS,CAAC,CAAC,CAAC;YACrD,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,KAAK,CAAC,kCAAkC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QACjE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC","sourcesContent":["/**\n * Validate API-lib Tag Executor\n *\n * Fails when the `role:api-lib` tag and the code disagree, in either direction:\n * a project tagged role:api-lib that exports no API contract, or a project that\n * exports an @ApiPath/@Rpc/@PubSub abstract class but is not tagged role:api-lib.\n *\n * Usage:\n * nx run architecture:validate-api-lib-tag\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { collectProjectInfo } from '../../lib/graph-metadata';\nimport { ApiUsageScanner } from '../../lib/api-usage/api-scanner';\nimport { findApiLibTagViolations, describeApiLibTagViolation } from '../../lib/api-usage/api-lib-tag-validator';\nimport { toError } from '../../toError';\n\nexport interface ValidateApiLibTagOptions {\n    // No options needed\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n// webpieces-disable no-function-outside-class -- nx executor entry point (default export), like every sibling executor\nexport default async function runExecutor(\n    _options: ValidateApiLibTagOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const workspaceRoot = context.root;\n\n    console.log('\\n🏷️  Validating role:api-lib tag ⇔ API contract exports\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const projectInfos = await collectProjectInfo();\n        const scan = new ApiUsageScanner(workspaceRoot, projectInfos).scan();\n        const violations = findApiLibTagViolations(projectInfos, scan);\n\n        if (violations.length === 0) {\n            console.log('✅ role:api-lib matches the code (every api-lib exports a contract, and vice-versa).');\n            return { success: true };\n        }\n\n        console.error(`❌ ${violations.length} role:api-lib tag/code mismatch(es):\\n`);\n        for (const violation of violations) {\n            console.error(describeApiLibTagViolation(violation));\n            console.error('');\n        }\n        return { success: false };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error('❌ api-lib tag validation failed:', error.message);\n        return { success: false };\n    }\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-api-lib-tag/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;AAiBH,8BA8BC;AA5CD,6DAA8D;AAC9D,iEAAkE;AAClE,qFAAgH;AAChH,2CAAwC;AAUxC,uHAAuH;AACxG,KAAK,UAAU,WAAW,CACrC,QAAkC,EAClC,OAAwB;IAExB,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC,OAAO,CAAC,GAAG,CAAC,6DAA6D,CAAC,CAAC;IAE3E,8DAA8D;IAC9D,IAAI,CAAC;QACD,MAAM,YAAY,GAAG,MAAM,IAAA,mCAAkB,GAAE,CAAC;QAChD,MAAM,IAAI,GAAG,IAAI,6BAAe,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC,IAAI,EAAE,CAAC;QACrE,MAAM,UAAU,GAAG,IAAA,+CAAuB,EAAC,YAAY,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;QAE9E,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,CAAC,GAAG,CAAC,4HAA4H,CAAC,CAAC;YAC1I,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC7B,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,KAAK,UAAU,CAAC,MAAM,wCAAwC,CAAC,CAAC;QAC9E,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACjC,OAAO,CAAC,KAAK,CAAC,IAAA,kDAA0B,EAAC,SAAS,CAAC,CAAC,CAAC;YACrD,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,KAAK,CAAC,kCAAkC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QACjE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC","sourcesContent":["/**\n * Validate API-lib Tag Executor\n *\n * Fails when the api roles and the code disagree, in either direction: a project\n * tagged role:api-lib that exports neither a contract (@ApiPath/@Rpc/@PubSub,\n * @WpInternal/@WpIpcEndpoint, or an in-process abstract …Api) nor only wire types,\n * a role:api-client that exports no contract, or a project that exports an\n * @ApiPath/@Rpc/@PubSub abstract class but carries neither api role (#1064, D3).\n *\n * Usage:\n * nx run architecture:validate-api-lib-tag\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { collectProjectInfo } from '../../lib/graph-metadata';\nimport { ApiUsageScanner } from '../../lib/api-usage/api-scanner';\nimport { findApiLibTagViolations, describeApiLibTagViolation } from '../../lib/api-usage/api-lib-tag-validator';\nimport { toError } from '../../toError';\n\nexport interface ValidateApiLibTagOptions {\n    // No options needed\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n// webpieces-disable no-function-outside-class -- nx executor entry point (default export), like every sibling executor\nexport default async function runExecutor(\n    _options: ValidateApiLibTagOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const workspaceRoot = context.root;\n\n    console.log('\\n🏷️  Validating role:api-lib tag ⇔ API contract exports\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const projectInfos = await collectProjectInfo();\n        const scan = new ApiUsageScanner(workspaceRoot, projectInfos).scan();\n        const violations = findApiLibTagViolations(projectInfos, scan, workspaceRoot);\n\n        if (violations.length === 0) {\n            console.log('✅ role:api-lib / role:api-client match the code (every api library exports a contract or only wire types, and vice-versa).');\n            return { success: true };\n        }\n\n        console.error(`❌ ${violations.length} role:api-lib tag/code mismatch(es):\\n`);\n        for (const violation of violations) {\n            console.error(describeApiLibTagViolation(violation));\n            console.error('');\n        }\n        return { success: false };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error('❌ api-lib tag validation failed:', error.message);\n        return { success: false };\n    }\n}\n"]}

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

@@ -18,6 +18,7 @@ const graph_sorter_1 = require("../../lib/graph-sorter");
 const graph_comparator_1 = require("../../lib/graph-comparator");
 const graph_loader_1 = require("../../lib/graph-loader");
 const graph_metadata_1 = require("../../lib/graph-metadata");
+const tag_truth_1 = require("../../lib/tag-truth");
 const api_scanner_1 = require("../../lib/api-usage/api-scanner");
 const external_systems_1 = require("../../lib/api-usage/external-systems");
 const api_contract_files_1 = require("../../lib/api-contract-files");
@@ -120,6 +121,7 @@ async function buildCurrentGraph(workspaceRoot) {
     console.log('🏷️  Enriching graph with framework + responsibilities metadata...');
     const projectInfos = await (0, graph_metadata_1.collectProjectInfo)();
     (0, graph_metadata_1.enrichGraph)(currentGraph, projectInfos, workspaceRoot);
+    new tag_truth_1.TagTruthCheck().assertTrue(currentGraph, projectInfos, workspaceRoot);
     console.log('🔎 Scanning source for implements/uses API relations...');
     // The SAME externalApiPaths the generator uses: scanning without them would drop every vendor
     // relation from the regenerated graph and report drift against a perfectly fresh file.

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

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-architecture-unchanged/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate Architecture Unchanged Executor\n *\n * Validates that the current architecture graph matches the saved blessed graph.\n * This ensures no unapproved architecture changes have been made.\n *\n * Usage:\n * nx run architecture:validate-architecture-unchanged\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { writeTemplate, RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport { generateReducedGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { compareGraphs } from '../../lib/graph-comparator';\nimport { loadBlessedGraph, graphFileExists } from '../../lib/graph-loader';\nimport type { DependenciesFile } from '../../lib/graph-loader';\nimport { collectProjectInfo, enrichGraph, MetadataValidationError } from '../../lib/graph-metadata';\nimport { scanAndAttachApiRelations, buildApiContracts } from '../../lib/api-usage/api-scanner';\nimport { buildExternalSystems } from '../../lib/api-usage/external-systems';\nimport type { ExternalSystemDecls } from '../../lib/api-usage/api-relations';\nimport { ApiContractFiles } from '../../lib/api-contract-files';\nimport type { ApiContractFileRefs } from '../../lib/api-contract-files';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport { RuleGate } from '../../lib/rule-gate';\nimport type { EnhancedGraph } from '../../lib/graph-sorter';\nimport { toError } from '../../toError';\n\nexport interface ValidateArchitectureUnchangedOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nconst TMP_MD_FILE = 'webpieces.dependencies.md';\n\n/**\n * Write the instructions documentation to .webpieces/instruct-ai/.\n * Sourced from @webpieces/rules-config.\n */\nfunction writeTmpInstructionsFile(workspaceRoot: string): string {\n    const mdPath = writeTemplate(workspaceRoot, TMP_MD_FILE);\n\n    return mdPath;\n}\n\n/**\n * Report a current-vs-saved graph mismatch and write the AI instructions file.\n */\nfunction reportMismatch(summary: string, workspaceRoot: string): void {\n    const mdPath = writeTmpInstructionsFile(workspaceRoot);\n\n    console.error('❌ Architecture has changed since last update!');\n    console.error('\\nDifferences:');\n    console.error(summary);\n    console.error('');\n    console.error('⚠️  *** Refer to ' + mdPath + ' for instructions on how to fix *** ⚠️');\n    console.error('');\n    console.error('To fix:');\n    console.error('  1. Review the changes above');\n    console.error('  2. If intentional, ASK USER to run: nx run architecture:generate since this is a critical change');\n    console.error('  3. Commit the updated architecture/dependencies.json');\n}\n\n/**\n * 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(current: ApiContractFileRefs, saved: ApiContractFileRefs): 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}: linked in dependencies.json but no longer in source`);\n        else if (b === undefined) 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(current: CurrentArchitecture, saved: DependenciesFile): 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(current: ExternalSystemDecls, saved: ExternalSystemDecls): string | null {\n    const names = [...new Set([...Object.keys(current), ...Object.keys(saved)])].sort();\n    const changes: string[] = [];\n    for (const name of names) {\n        const a = current[name];\n        const b = saved[name];\n        if (a === undefined) changes.push(`  - ${name}: in dependencies.json but no longer declared in source`);\n        else if (b === undefined) changes.push(`  + ${name}: declared in source but missing from dependencies.json`);\n        else if (JSON.stringify(a) !== JSON.stringify(b)) changes.push(`  ~ ${name}: kind/label/declarers changed`);\n    }\n    if (changes.length === 0) return null;\n    return `externalSystems drift (${changes.length} system(s)):\\n${changes.join('\\n')}`;\n}\n\n/**\n * Build the current dependency graph exactly as the generator does: reduce the nx\n * graph, sort into levels, enrich with metadata, and attach the derived\n * apiRelations — so this validator compares like-for-like against the committed file.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch/writeTmpInstructionsFile in this file\nasync function buildCurrentGraph(workspaceRoot: string): Promise<CurrentArchitecture> {\n    console.log('📊 Generating current dependency graph...');\n    const reducedGraph = await generateReducedGraph();\n    console.log('🔄 Computing topological layers...');\n    const currentGraph = sortGraphTopologically(reducedGraph);\n    console.log('🏷️  Enriching graph with framework + responsibilities metadata...');\n    const projectInfos = await collectProjectInfo();\n    enrichGraph(currentGraph, projectInfos, workspaceRoot);\n    console.log('🔎 Scanning source for implements/uses API relations...');\n    // The SAME externalApiPaths the generator uses: scanning without them would drop every vendor\n    // relation from the regenerated graph and report drift against a perfectly fresh file.\n    const externalApiPaths = loadRuntimeConfig(workspaceRoot).externalApiPaths;\n    const scan = scanAndAttachApiRelations(workspaceRoot, currentGraph, projectInfos, externalApiPaths);\n    return new CurrentArchitecture(\n        currentGraph,\n        new ApiContractFiles().refsFor(buildApiContracts(scan)),\n        buildExternalSystems(scan.apiIndex, projectInfos),\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(): void {\n    console.error('❌ No saved graph found at architecture/dependencies.json');\n    console.error('');\n    console.error('To initialize:');\n    console.error('  1. Run: nx run architecture:generate');\n    console.error('  2. Run: nx run architecture:visualize');\n    console.error('  3. Manually inspect the generated graph to confirm it is the desired architecture');\n    console.error('  4. Commit architecture/dependencies.json');\n}\n\nexport default async function runExecutor(\n    options: ValidateArchitectureUnchangedOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    // Epoch-gateable: this rule diffs against the blessed architecture/dependencies.json, so\n    // \"grandfather the current drift until <epoch>\" is meaningful — hence honorEpoch = true.\n    if (new RuleGate().isDisabled(workspaceRoot, 'validate-architecture-unchanged', true)) {\n        return { success: true };\n    }\n\n    console.log('\\n🔍 Validating Architecture Unchanged\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Check if saved graph exists\n        if (!graphFileExists(workspaceRoot, graphPath)) {\n            reportMissingGraph();\n            return { success: false };\n        }\n\n        // Steps 1-3: build + enrich + scan the current graph (same pipeline the\n        // generator runs, so any drift is caught).\n        const currentGraph = await buildCurrentGraph(workspaceRoot);\n\n        // Step 4: Load saved graph\n        console.log('📂 Loading saved graph...');\n        const savedGraph = loadBlessedGraph(workspaceRoot, graphPath);\n\n        if (!savedGraph) {\n            console.error('❌ Could not load saved graph');\n            return { success: false };\n        }\n\n        // Step 5: Compare graphs\n        console.log('🔍 Comparing current graph to saved graph...');\n        const comparison = compareGraphs(currentGraph.graph, savedGraph.projects);\n\n        if (!comparison.identical) {\n            reportMismatch(comparison.summary, workspaceRoot);\n            return { success: false };\n        }\n\n        // Step 6: Compare the two side tables as well: 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 = error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message;\n        console.error('❌ Architecture validation failed:', rendered);\n        if (error instanceof MetadataValidationError) {\n            const mdPath = writeTemplate(workspaceRoot, 'webpieces.responsibilities.md');\n            console.error('');\n            console.error('⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️');\n        }\n        return { success: false };\n    }\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-architecture-unchanged/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate Architecture Unchanged Executor\n *\n * Validates that the current architecture graph matches the saved blessed graph.\n * This ensures no unapproved architecture changes have been made.\n *\n * Usage:\n * nx run architecture:validate-architecture-unchanged\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { writeTemplate, RuleFailError, renderRuleFailForHuman } 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 { scanAndAttachApiRelations, buildApiContracts } from '../../lib/api-usage/api-scanner';\nimport { buildExternalSystems } from '../../lib/api-usage/external-systems';\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 { loadRuntimeConfig } from '../../lib/runtime-config';\nimport { RuleGate } from '../../lib/rule-gate';\nimport type { EnhancedGraph } from '../../lib/graph-sorter';\nimport { toError } from '../../toError';\n\nexport interface ValidateArchitectureUnchangedOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nconst TMP_MD_FILE = 'webpieces.dependencies.md';\n\n/**\n * Write the instructions documentation to .webpieces/instruct-ai/.\n * Sourced from @webpieces/rules-config.\n */\nfunction writeTmpInstructionsFile(workspaceRoot: string): string {\n    const mdPath = writeTemplate(workspaceRoot, TMP_MD_FILE);\n\n    return mdPath;\n}\n\n/**\n * Report a current-vs-saved graph mismatch and write the AI instructions file.\n */\nfunction reportMismatch(summary: string, workspaceRoot: string): void {\n    const mdPath = writeTmpInstructionsFile(workspaceRoot);\n\n    console.error('❌ Architecture has changed since last update!');\n    console.error('\\nDifferences:');\n    console.error(summary);\n    console.error('');\n    console.error('⚠️  *** Refer to ' + mdPath + ' for instructions on how to fix *** ⚠️');\n    console.error('');\n    console.error('To fix:');\n    console.error('  1. Review the changes above');\n    console.error('  2. If intentional, ASK USER to run: nx run architecture:generate since this is a critical change');\n    console.error('  3. Commit the updated architecture/dependencies.json');\n}\n\n/**\n * 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(current: ApiContractFileRefs, saved: ApiContractFileRefs): 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}: linked in dependencies.json but no longer in source`);\n        else if (b === undefined) 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(current: CurrentArchitecture, saved: DependenciesFile): 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(current: ExternalSystemDecls, saved: ExternalSystemDecls): string | null {\n    const names = [...new Set([...Object.keys(current), ...Object.keys(saved)])].sort();\n    const changes: string[] = [];\n    for (const name of names) {\n        const a = current[name];\n        const b = saved[name];\n        if (a === undefined) changes.push(`  - ${name}: in dependencies.json but no longer declared in source`);\n        else if (b === undefined) changes.push(`  + ${name}: declared in source but missing from dependencies.json`);\n        else if (JSON.stringify(a) !== JSON.stringify(b)) changes.push(`  ~ ${name}: kind/label/declarers changed`);\n    }\n    if (changes.length === 0) return null;\n    return `externalSystems drift (${changes.length} system(s)):\\n${changes.join('\\n')}`;\n}\n\n/**\n * Build the current dependency graph exactly as the generator does: reduce the nx\n * graph, sort into levels, enrich with metadata, and attach the derived\n * apiRelations — so this validator compares like-for-like against the committed file.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch/writeTmpInstructionsFile in this file\nasync function buildCurrentGraph(workspaceRoot: string): Promise<CurrentArchitecture> {\n    console.log('📊 Generating current dependency graph...');\n    const reducedGraph = await generateReducedGraph();\n    console.log('🔄 Computing topological layers...');\n    const currentGraph = sortGraphTopologically(reducedGraph);\n    console.log('🏷️  Enriching graph with framework + responsibilities metadata...');\n    const projectInfos = await collectProjectInfo();\n    enrichGraph(currentGraph, projectInfos, workspaceRoot);\n    new TagTruthCheck().assertTrue(currentGraph, projectInfos, workspaceRoot);\n    console.log('🔎 Scanning source for implements/uses API relations...');\n    // The SAME externalApiPaths the generator uses: scanning without them would drop every vendor\n    // relation from the regenerated graph and report drift against a perfectly fresh file.\n    const externalApiPaths = loadRuntimeConfig(workspaceRoot).externalApiPaths;\n    const scan = scanAndAttachApiRelations(workspaceRoot, currentGraph, projectInfos, externalApiPaths);\n    return new CurrentArchitecture(\n        currentGraph,\n        new ApiContractFiles().refsFor(buildApiContracts(scan)),\n        buildExternalSystems(scan.apiIndex, projectInfos),\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(): void {\n    console.error('❌ No saved graph found at architecture/dependencies.json');\n    console.error('');\n    console.error('To initialize:');\n    console.error('  1. Run: nx run architecture:generate');\n    console.error('  2. Run: nx run architecture:visualize');\n    console.error('  3. Manually inspect the generated graph to confirm it is the desired architecture');\n    console.error('  4. Commit architecture/dependencies.json');\n}\n\nexport default async function runExecutor(\n    options: ValidateArchitectureUnchangedOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    // Epoch-gateable: this rule diffs against the blessed architecture/dependencies.json, so\n    // \"grandfather the current drift until <epoch>\" is meaningful — hence honorEpoch = true.\n    if (new RuleGate().isDisabled(workspaceRoot, 'validate-architecture-unchanged', true)) {\n        return { success: true };\n    }\n\n    console.log('\\n🔍 Validating Architecture Unchanged\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Check if saved graph exists\n        if (!graphFileExists(workspaceRoot, graphPath)) {\n            reportMissingGraph();\n            return { success: false };\n        }\n\n        // Steps 1-3: build + enrich + scan the current graph (same pipeline the\n        // generator runs, so any drift is caught).\n        const currentGraph = await buildCurrentGraph(workspaceRoot);\n\n        // Step 4: Load saved graph\n        console.log('📂 Loading saved graph...');\n        const savedGraph = loadBlessedGraph(workspaceRoot, graphPath);\n\n        if (!savedGraph) {\n            console.error('❌ Could not load saved graph');\n            return { success: false };\n        }\n\n        // Step 5: Compare graphs\n        console.log('🔍 Comparing current graph to saved graph...');\n        const comparison = compareGraphs(currentGraph.graph, savedGraph.projects);\n\n        if (!comparison.identical) {\n            reportMismatch(comparison.summary, workspaceRoot);\n            return { success: false };\n        }\n\n        // Step 6: Compare the two side tables as well: 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 = error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message;\n        console.error('❌ Architecture validation failed:', rendered);\n        if (error instanceof MetadataValidationError) {\n            const mdPath = writeTemplate(workspaceRoot, 'webpieces.responsibilities.md');\n            console.error('');\n            console.error('⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️');\n        }\n        return { success: false };\n    }\n}\n"]}

package/src/lib/api-docs/components-wiring.d.ts

@@ -12,6 +12,10 @@
  * a contract document before the library document it references exists, and the generator's
  * fail-closed refusal ("never generated") fires intermittently, mostly in CI. So it is refused here,
  * on the resolved graph, with the exact `dependsOn` to write.
+ *
+ * The tag itself is allowed only on a `role:api-lib` project (#1064, D5): a components document puts a
+ * library's types on the wire, and every wire type is declared in an api library. Tagging a general
+ * library such as `company-core` must not be a way out of moving the type.
  */
 import type { ProjectConfiguration } from '@nx/devkit';
 import { DeclaredDependsOn, GenerateWiringProblem, ProjectDependency } from './generate-wiring';
@@ -23,6 +27,8 @@ export declare class ComponentsWiring {
     /** The DTO libraries tagged to publish a components document. */
     libraries(): string[];
     problems(): GenerateWiringProblem[];
+    /** Only a `role:api-lib` publishes a components document (D5). */
+    private roleOf;
     /** `openapi-components-generate` dependsOn exactly the library's own `build`, the tsc target. */
     private shapeOf;
     private missingEdge;

package/src/lib/api-docs/components-wiring.js

@@ -13,6 +13,10 @@
  * a contract document before the library document it references exists, and the generator's
  * fail-closed refusal ("never generated") fires intermittently, mostly in CI. So it is refused here,
  * on the resolved graph, with the exact `dependsOn` to write.
+ *
+ * The tag itself is allowed only on a `role:api-lib` project (#1064, D5): a components document puts a
+ * library's types on the wire, and every wire type is declared in an api library. Tagging a general
+ * library such as `company-core` must not be a way out of moving the type.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ComponentsWiring = void 0;
@@ -23,6 +27,7 @@ const generate_wiring_1 = require("./generate-wiring");
 const BUILD_TARGET = 'build';
 const COMPONENTS_TARGET = core_util_1.GeneratedApiDocsLayout.COMPONENTS_TARGET;
 const UPSTREAM_COMPONENTS = `^${COMPONENTS_TARGET}`;
+const API_LIB_ROLE_TAG = 'role:api-lib';
 /** The targets that READ upstream components documents, and so must run after them. */
 const READING_TARGETS = [COMPONENTS_TARGET, core_util_1.GeneratedApiDocsLayout.OPENAPI_TARGET];
 class ComponentsWiring {
@@ -44,7 +49,7 @@ class ComponentsWiring {
         const libraries = new Set(this.libraries());
         const problems = [];
         for (const name of this.libraries())
-            problems.push(...this.shapeOf(name));
+            problems.push(...this.roleOf(name), ...this.shapeOf(name));
         for (const name of Object.keys(this.projects).sort()) {
             const upstream = this.librariesUpstreamOf(name, libraries);
             if (upstream.length === 0)
@@ -58,6 +63,18 @@ class ComponentsWiring {
         }
         return problems;
     }
+    /** Only a `role:api-lib` publishes a components document (D5). */
+    roleOf(name) {
+        const project = this.projects[name];
+        const tags = project.tags ?? [];
+        if (tags.includes(API_LIB_ROLE_TAG))
+            return [];
+        const carried = tags.filter((tag) => tag.startsWith('role:')).join(', ') || 'no role tag';
+        return [new generate_wiring_1.GenerateWiringProblem(name, `${name} is tagged "${generate_targets_1.GENERATE_OPENAPI_COMPONENTS_TAG}" but carries ${carried} — only a role:api-lib ` +
+                'publishes a components document, because every type a contract reaches is declared in an api library.', `${name}: in ${project.root}/project.json, drop "${generate_targets_1.GENERATE_OPENAPI_COMPONENTS_TAG}" and move the wire ` +
+                `types into a role:api-lib DTO library tagged with it — or, when ${name} holds only contracts and ` +
+                'wire types, retag it role:api-lib.')];
+    }
     /** `openapi-components-generate` dependsOn exactly the library's own `build`, the tsc target. */
     shapeOf(name) {
         const project = this.projects[name];