@webpieces/nx-webpieces-rules 0.4.862 → 0.4.864

package/package.json

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

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

@@ -19,6 +19,7 @@ const graph_comparator_1 = require("../../lib/graph-comparator");
 const graph_loader_1 = require("../../lib/graph-loader");
 const graph_metadata_1 = require("../../lib/graph-metadata");
 const tag_truth_1 = require("../../lib/tag-truth");
+const canonical_clients_1 = require("../../lib/runtime-wiring/canonical-clients");
 const approved_graph_1 = require("../../lib/runtime-wiring/approved-graph");
 const rule_gate_1 = require("../../lib/rule-gate");
 const toError_1 = require("../../toError");
@@ -117,6 +118,7 @@ class CurrentGraphBuilder {
         const currentGraph = (0, graph_sorter_1.sortGraphTopologically)(reducedGraph);
         console.log('🏷️  Enriching graph with framework + responsibilities metadata...');
         const projectInfos = await (0, graph_metadata_1.collectProjectInfo)();
+        new canonical_clients_1.WorkspaceClientBindings().assert(workspaceRoot, projectInfos);
         (0, graph_metadata_1.enrichGraph)(currentGraph, projectInfos, workspaceRoot);
         new tag_truth_1.TagTruthCheck().assertTrue(currentGraph, projectInfos, workspaceRoot);
         new approved_graph_1.ApprovedWiringGraph().attach(workspaceRoot, currentGraph, projectInfos, graphPath);

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":";AAAA;;;;;;;;GAQG;;;AA+FH,gDAOC;AAuFD,8BAkEC;AA5PD,0DAKiC;AACjC,+DAAiE;AACjE,yDAAgE;AAChE,iEAA2D;AAC3D,yDAA2E;AAE3E,6DAAoG;AACpG,mDAAoD;AACpD,4EAA8E;AAI9E,mDAA+C;AAE/C,2CAAwC;AAUxC,MAAM,WAAW,GAAG,2BAA2B,CAAC;AAEhD;;;GAGG;AACH,SAAS,wBAAwB,CAAC,aAAqB;IACnD,MAAM,MAAM,GAAG,IAAA,4BAAa,EAAC,aAAa,EAAE,WAAW,CAAC,CAAC;IAEzD,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,SAAS,cAAc,CAAC,OAAe,EAAE,aAAqB;IAC1D,MAAM,MAAM,GAAG,wBAAwB,CAAC,aAAa,CAAC,CAAC;IAEvD,OAAO,CAAC,KAAK,CAAC,+CAA+C,CAAC,CAAC;IAC/D,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACvB,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAClB,OAAO,CAAC,KAAK,CAAC,mBAAmB,GAAG,MAAM,GAAG,wCAAwC,CAAC,CAAC;IACvF,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAClB,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACzB,OAAO,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;IAC/C,OAAO,CAAC,KAAK,CACT,oGAAoG,CACvG,CAAC;IACF,OAAO,CAAC,KAAK,CAAC,wDAAwD,CAAC,CAAC;AAC5E,CAAC;AAED;;;;GAIG;AACH,2GAA2G;AAC3G,SAAS,yBAAyB,CAC9B,OAA4B,EAC5B,KAA0B;IAE1B,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACpF,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACxB,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,SAAS;YACf,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,uDAAuD,CAAC,CAAC;aAChF,IAAI,CAAC,KAAK,SAAS;YACpB,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,mDAAmD,CAAC,CAAC;aAC5E,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,iCAAiC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7F,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,2BAA2B,OAAO,CAAC,MAAM,cAAc,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AACvF,CAAC;AAED;;;;GAIG;AACH,+GAA+G;AAC/G,SAAgB,kBAAkB,CAC9B,OAA4B,EAC5B,KAAuB;IAEvB,MAAM,SAAS,GAAG,yBAAyB,CAAC,OAAO,CAAC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAC9F,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACzC,OAAO,2BAA2B,CAAC,OAAO,CAAC,eAAe,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;AACvF,CAAC;AAED;;;GAGG;AACH,+GAA+G;AAC/G,SAAS,2BAA2B,CAChC,OAA4B,EAC5B,KAA0B;IAE1B,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACpF,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACxB,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,SAAS;YACf,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,yDAAyD,CAAC,CAAC;aAClF,IAAI,CAAC,KAAK,SAAS;YACpB,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,yDAAyD,CAAC,CAAC;aAClF,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;YAC5C,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,gCAAgC,CAAC,CAAC;IAClE,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,0BAA0B,OAAO,CAAC,MAAM,iBAAiB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AACzF,CAAC;AAED;;;;GAIG;AACH,MAAa,mBAAmB;IAC5B,KAAK,CAAC,KAAK,CAAC,aAAqB,EAAE,SAAkB;QACjD,OAAO,CAAC,GAAG,CAAC,2CAA2C,CAAC,CAAC;QACzD,MAAM,YAAY,GAAG,MAAM,IAAA,sCAAoB,GAAE,CAAC;QAClD,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;QAClD,MAAM,YAAY,GAAG,IAAA,qCAAsB,EAAC,YAAY,CAAC,CAAC;QAC1D,OAAO,CAAC,GAAG,CAAC,oEAAoE,CAAC,CAAC;QAClF,MAAM,YAAY,GAAG,MAAM,IAAA,mCAAkB,GAAE,CAAC;QAChD,IAAA,4BAAW,EAAC,YAAY,EAAE,YAAY,EAAE,aAAa,CAAC,CAAC;QACvD,IAAI,yBAAa,EAAE,CAAC,UAAU,CAAC,YAAY,EAAE,YAAY,EAAE,aAAa,CAAC,CAAC;QAC1E,IAAI,oCAAmB,EAAE,CAAC,MAAM,CAAC,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;QACvF,MAAM,KAAK,GAAG,IAAA,+BAAgB,EAAC,aAAa,EAAE,SAAS,CAAC,CAAC;QACzD,IAAI,KAAK,KAAK,IAAI;YACd,MAAM,IAAI,4BAAa,CACnB,+BAA+B,EAC/B,yBAAyB,EACzB,SAAS,EACT,SAAS,EACT;gBACI,IAAI,qBAAM,CACN,gFAAgF,EAChF,IAAI,CACP;aACJ,CACJ,CAAC;QACN,OAAO,IAAI,mBAAmB,CAAC,YAAY,EAAE,KAAK,CAAC,gBAAgB,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IAChG,CAAC;CACJ;AA3BD,kDA2BC;AAED,gGAAgG;AAChG,MAAa,mBAAmB;IAER;IACA;IACA;IAHpB,YACoB,KAAoB,EACpB,gBAAqC,EACrC,eAAoC;QAFpC,UAAK,GAAL,KAAK,CAAe;QACpB,qBAAgB,GAAhB,gBAAgB,CAAqB;QACrC,oBAAe,GAAf,eAAe,CAAqB;IACrD,CAAC;CACP;AAND,kDAMC;AAED,yFAAyF;AACzF,2GAA2G;AAC3G,SAAS,kBAAkB;IACvB,MAAM,IAAI,4BAAa,CACnB,+BAA+B,EAC/B,kDAAkD,EAClD,SAAS,EACT,SAAS,EACT;QACI,IAAI,qBAAM,CACN,mXAAmX,EACnX,IAAI,CACP;KACJ,CACJ,CAAC;AACN,CAAC;AAEc,KAAK,UAAU,WAAW,CACrC,OAA6C,EAC7C,OAAwB;IAExB,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACpC,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC,yFAAyF;IACzF,yFAAyF;IACzF,IAAI,IAAI,oBAAQ,EAAE,CAAC,UAAU,CAAC,aAAa,EAAE,iCAAiC,EAAE,IAAI,CAAC,EAAE,CAAC;QACpF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC7B,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;IAExD,8DAA8D;IAC9D,IAAI,CAAC;QACD,8BAA8B;QAC9B,IAAI,CAAC,IAAA,8BAAe,EAAC,aAAa,EAAE,SAAS,CAAC,EAAE,CAAC;YAC7C,kBAAkB,EAAE,CAAC;YACrB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;QAED,wEAAwE;QACxE,2CAA2C;QAC3C,MAAM,YAAY,GAAG,MAAM,IAAI,mBAAmB,EAAE,CAAC,KAAK,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;QAErF,2BAA2B;QAC3B,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;QACzC,MAAM,UAAU,GAAG,IAAA,+BAAgB,EAAC,aAAa,EAAE,SAAS,CAAC,CAAC;QAE9D,IAAI,CAAC,UAAU,EAAE,CAAC;YACd,OAAO,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;YAC9C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;QAED,yBAAyB;QACzB,OAAO,CAAC,GAAG,CAAC,8CAA8C,CAAC,CAAC;QAC5D,MAAM,UAAU,GAAG,IAAA,gCAAa,EAAC,YAAY,CAAC,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;QAE1E,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC;YACxB,cAAc,CAAC,UAAU,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;YAClD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;QAED,6FAA6F;QAC7F,0FAA0F;QAC1F,sEAAsE;QACtE,MAAM,UAAU,GAAG,kBAAkB,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;QAChE,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;YACtB,cAAc,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;YAC1C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,8DAA8D,CAAC,CAAC;QAC5E,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,yFAAyF;QACzF,wFAAwF;QACxF,MAAM,QAAQ,GACV,KAAK,YAAY,4BAAa,CAAC,CAAC,CAAC,IAAA,qCAAsB,EAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;QACnF,OAAO,CAAC,KAAK,CAAC,mCAAmC,EAAE,QAAQ,CAAC,CAAC;QAC7D,qBAAqB,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;QAC5C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC;AAED,gFAAgF;AAChF,SAAS,qBAAqB,CAAC,KAAY,EAAE,aAAqB;IAC9D,IAAI,KAAK,YAAY,wCAAuB,EAAE,CAAC;QAC3C,MAAM,MAAM,GAAG,IAAA,4BAAa,EAAC,aAAa,EAAE,+BAA+B,CAAC,CAAC;QAC7E,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAClB,OAAO,CAAC,KAAK,CACT,mBAAmB,GAAG,MAAM,GAAG,qDAAqD,CACvF,CAAC;IACN,CAAC;AACL,CAAC","sourcesContent":["/**\n * Validate Architecture Unchanged Executor\n *\n * Validates that the current architecture graph matches the saved blessed graph.\n * This ensures no unapproved architecture changes have been made.\n *\n * Usage:\n * nx run architecture:validate-architecture-unchanged\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport {\n    writeTemplate,\n    Option,\n    RuleFailError,\n    renderRuleFailForHuman,\n} from '@webpieces/rules-config';\nimport { generateReducedGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { compareGraphs } from '../../lib/graph-comparator';\nimport { loadBlessedGraph, graphFileExists } from '../../lib/graph-loader';\nimport type { DependenciesFile } from '../../lib/graph-loader';\nimport { collectProjectInfo, enrichGraph, MetadataValidationError } from '../../lib/graph-metadata';\nimport { TagTruthCheck } from '../../lib/tag-truth';\nimport { ApprovedWiringGraph } from '../../lib/runtime-wiring/approved-graph';\nimport type { ExternalSystemDecls } from '../../lib/api-usage/api-relations';\nimport { ApiContractFiles } from '../../lib/api-contract-files';\nimport type { ApiContractFileRefs } from '../../lib/api-contract-files';\nimport { RuleGate } from '../../lib/rule-gate';\nimport type { EnhancedGraph } from '../../lib/graph-sorter';\nimport { toError } from '../../toError';\n\nexport interface ValidateArchitectureUnchangedOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nconst TMP_MD_FILE = 'webpieces.dependencies.md';\n\n/**\n * Write the instructions documentation to .webpieces/instruct-ai/.\n * Sourced from @webpieces/rules-config.\n */\nfunction writeTmpInstructionsFile(workspaceRoot: string): string {\n    const mdPath = writeTemplate(workspaceRoot, TMP_MD_FILE);\n\n    return mdPath;\n}\n\n/**\n * Report a current-vs-saved graph mismatch and write the AI instructions file.\n */\nfunction reportMismatch(summary: string, workspaceRoot: string): void {\n    const mdPath = writeTmpInstructionsFile(workspaceRoot);\n\n    console.error('❌ Architecture has changed since last update!');\n    console.error('\\nDifferences:');\n    console.error(summary);\n    console.error('');\n    console.error('⚠️  *** Refer to ' + mdPath + ' for instructions on how to fix *** ⚠️');\n    console.error('');\n    console.error('To fix:');\n    console.error('  1. Review the changes above');\n    console.error(\n        '  2. If intentional, ASK USER to run: nx run architecture:generate since this is a critical change',\n    );\n    console.error('  3. Commit the updated architecture/dependencies.json');\n}\n\n/**\n * Which APIs dependencies.json links to a contract file, compared by LINK only — an added or removed\n * API. The endpoints inside `architecture/apis/<Api>.json` are deliberately NOT compared (#949): an\n * endpoint change must not fail this rule. Null when the links match.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch in this file\nfunction describeContractLinkDrift(\n    current: ApiContractFileRefs,\n    saved: ApiContractFileRefs,\n): string | null {\n    const names = [...new Set([...Object.keys(current), ...Object.keys(saved)])].sort();\n    const changes: string[] = [];\n    for (const name of names) {\n        const a = current[name];\n        const b = saved[name];\n        if (a === undefined)\n            changes.push(`  - ${name}: linked in dependencies.json but no longer in source`);\n        else if (b === undefined)\n            changes.push(`  + ${name}: in source but not linked from dependencies.json`);\n        else if (a !== b) changes.push(`  ~ ${name}: contract file link changed (${b} -> ${a})`);\n    }\n    if (changes.length === 0) return null;\n    return `apiContractFiles drift (${changes.length} api(s)):\\n${changes.join('\\n')}`;\n}\n\n/**\n * Drift in EITHER side table of dependencies.json — the api contract-file links or the\n * external-system declarations — or null when both match. The first difference found is reported;\n * fixing it is the same single command either way, so listing both adds noise rather than information.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches describeContractLinkDrift above\nexport function describeTableDrift(\n    current: CurrentArchitecture,\n    saved: DependenciesFile,\n): string | null {\n    const linkDrift = describeContractLinkDrift(current.apiContractFiles, saved.apiContractFiles);\n    if (linkDrift !== null) return linkDrift;\n    return describeExternalSystemDrift(current.externalSystems, saved.externalSystems);\n}\n\n/**\n * The same drift report for the declared external systems, or null when they match. Named per\n * system so the message points at the database that changed rather than dumping two JSON blobs.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches describeContractLinkDrift above\nfunction describeExternalSystemDrift(\n    current: ExternalSystemDecls,\n    saved: ExternalSystemDecls,\n): string | null {\n    const names = [...new Set([...Object.keys(current), ...Object.keys(saved)])].sort();\n    const changes: string[] = [];\n    for (const name of names) {\n        const a = current[name];\n        const b = saved[name];\n        if (a === undefined)\n            changes.push(`  - ${name}: in dependencies.json but no longer declared in source`);\n        else if (b === undefined)\n            changes.push(`  + ${name}: declared in source but missing from dependencies.json`);\n        else if (JSON.stringify(a) !== JSON.stringify(b))\n            changes.push(`  ~ ${name}: kind/label/declarers changed`);\n    }\n    if (changes.length === 0) return null;\n    return `externalSystems drift (${changes.length} system(s)):\\n${changes.join('\\n')}`;\n}\n\n/**\n * Build the current dependency graph exactly as the generator does: reduce the nx\n * graph, sort into levels, enrich with metadata, and attach the derived\n * apiRelations — so this validator compares like-for-like against the committed file.\n */\nexport class CurrentGraphBuilder {\n    async build(workspaceRoot: string, graphPath?: string): Promise<CurrentArchitecture> {\n        console.log('📊 Generating current dependency graph...');\n        const reducedGraph = await generateReducedGraph();\n        console.log('🔄 Computing topological layers...');\n        const currentGraph = sortGraphTopologically(reducedGraph);\n        console.log('🏷️  Enriching graph with framework + responsibilities metadata...');\n        const projectInfos = await collectProjectInfo();\n        enrichGraph(currentGraph, projectInfos, workspaceRoot);\n        new TagTruthCheck().assertTrue(currentGraph, projectInfos, workspaceRoot);\n        new ApprovedWiringGraph().attach(workspaceRoot, currentGraph, projectInfos, graphPath);\n        const saved = loadBlessedGraph(workspaceRoot, graphPath);\n        if (saved === null)\n            throw new RuleFailError(\n                'validate-runtime-architecture',\n                'Missing approved graph.',\n                undefined,\n                undefined,\n                [\n                    new Option(\n                        'Migrate src/wiring.ts and review runtime-deps.json and API contract approvals.',\n                        true,\n                    ),\n                ],\n            );\n        return new CurrentArchitecture(currentGraph, saved.apiContractFiles, saved.externalSystems);\n    }\n}\n\n/** The regenerated graph plus the two tables beside it — everything dependencies.json holds. */\nexport class CurrentArchitecture {\n    constructor(\n        public readonly graph: EnhancedGraph,\n        public readonly apiContractFiles: ApiContractFileRefs,\n        public readonly externalSystems: ExternalSystemDecls,\n    ) {}\n}\n\n/** The bootstrap path: there is nothing to diff against yet, so say how to create it. */\n// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch in this file\nfunction reportMissingGraph(): never {\n    throw new RuleFailError(\n        'validate-runtime-architecture',\n        'Missing reviewed architecture/dependencies.json.',\n        undefined,\n        undefined,\n        [\n            new Option(\n                'Run owning API source build checks to emit contract candidates, review and copy them into architecture/apis/<ApiName>.json, and create dependencies.json with projects:{}, apiContractFiles:{\"<ApiName>\":\"apis/<ApiName>.json\"}, and reviewed externalSystems. Approve tagged owners runtime-deps.json candidates, then run architecture:generate and review the resulting graph.',\n                true,\n            ),\n        ],\n    );\n}\n\nexport default async function runExecutor(\n    options: ValidateArchitectureUnchangedOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    // Epoch-gateable: this rule diffs against the blessed architecture/dependencies.json, so\n    // \"grandfather the current drift until <epoch>\" is meaningful — hence honorEpoch = true.\n    if (new RuleGate().isDisabled(workspaceRoot, 'validate-architecture-unchanged', true)) {\n        return { success: true };\n    }\n\n    console.log('\\n🔍 Validating Architecture Unchanged\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Check if saved graph exists\n        if (!graphFileExists(workspaceRoot, graphPath)) {\n            reportMissingGraph();\n            return { success: false };\n        }\n\n        // Steps 1-3: build + enrich + scan the current graph (same pipeline the\n        // generator runs, so any drift is caught).\n        const currentGraph = await new CurrentGraphBuilder().build(workspaceRoot, graphPath);\n\n        // Step 4: Load saved graph\n        console.log('📂 Loading saved graph...');\n        const savedGraph = loadBlessedGraph(workspaceRoot, graphPath);\n\n        if (!savedGraph) {\n            console.error('❌ Could not load saved graph');\n            return { success: false };\n        }\n\n        // Step 5: Compare graphs\n        console.log('🔍 Comparing current graph to saved graph...');\n        const comparison = compareGraphs(currentGraph.graph, savedGraph.projects);\n\n        if (!comparison.identical) {\n            reportMismatch(comparison.summary, workspaceRoot);\n            return { success: false };\n        }\n\n        // Step 6: Compare the two side tables as well: which APIs are linked to a contract file, and\n        // the external-system declarations. The endpoints inside architecture/apis/<Api>.json are\n        // NOT compared — an endpoint change must never fail this rule (#949).\n        const tableDrift = describeTableDrift(currentGraph, savedGraph);\n        if (tableDrift !== null) {\n            reportMismatch(tableDrift, workspaceRoot);\n            return { success: false };\n        }\n\n        console.log('✅ Architecture unchanged - current graph matches saved graph');\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        // A RuleFailError (e.g. a dependencies.json still carrying the moved `apiContracts` key)\n        // carries its cures in Option[]; render them rather than dropping them with `.message`.\n        const rendered =\n            error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message;\n        console.error('❌ Architecture validation failed:', rendered);\n        reportMetadataFailure(error, workspaceRoot);\n        return { success: false };\n    }\n}\n\n// webpieces-disable no-function-outside-class -- executor diagnostic formatting\nfunction reportMetadataFailure(error: Error, workspaceRoot: string): void {\n    if (error instanceof MetadataValidationError) {\n        const mdPath = writeTemplate(workspaceRoot, 'webpieces.responsibilities.md');\n        console.error('');\n        console.error(\n            '⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️',\n        );\n    }\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-architecture-unchanged/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate Architecture Unchanged Executor\n *\n * Validates that the current architecture graph matches the saved blessed graph.\n * This ensures no unapproved architecture changes have been made.\n *\n * Usage:\n * nx run architecture:validate-architecture-unchanged\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport {\n    writeTemplate,\n    Option,\n    RuleFailError,\n    renderRuleFailForHuman,\n} from '@webpieces/rules-config';\nimport { generateReducedGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { compareGraphs } from '../../lib/graph-comparator';\nimport { loadBlessedGraph, graphFileExists } from '../../lib/graph-loader';\nimport type { DependenciesFile } from '../../lib/graph-loader';\nimport { collectProjectInfo, enrichGraph, MetadataValidationError } from '../../lib/graph-metadata';\nimport { TagTruthCheck } from '../../lib/tag-truth';\nimport { WorkspaceClientBindings } from '../../lib/runtime-wiring/canonical-clients';\nimport { ApprovedWiringGraph } from '../../lib/runtime-wiring/approved-graph';\nimport type { ExternalSystemDecls } from '../../lib/api-usage/api-relations';\nimport { ApiContractFiles } from '../../lib/api-contract-files';\nimport type { ApiContractFileRefs } from '../../lib/api-contract-files';\nimport { RuleGate } from '../../lib/rule-gate';\nimport type { EnhancedGraph } from '../../lib/graph-sorter';\nimport { toError } from '../../toError';\n\nexport interface ValidateArchitectureUnchangedOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nconst TMP_MD_FILE = 'webpieces.dependencies.md';\n\n/**\n * Write the instructions documentation to .webpieces/instruct-ai/.\n * Sourced from @webpieces/rules-config.\n */\nfunction writeTmpInstructionsFile(workspaceRoot: string): string {\n    const mdPath = writeTemplate(workspaceRoot, TMP_MD_FILE);\n\n    return mdPath;\n}\n\n/**\n * Report a current-vs-saved graph mismatch and write the AI instructions file.\n */\nfunction reportMismatch(summary: string, workspaceRoot: string): void {\n    const mdPath = writeTmpInstructionsFile(workspaceRoot);\n\n    console.error('❌ Architecture has changed since last update!');\n    console.error('\\nDifferences:');\n    console.error(summary);\n    console.error('');\n    console.error('⚠️  *** Refer to ' + mdPath + ' for instructions on how to fix *** ⚠️');\n    console.error('');\n    console.error('To fix:');\n    console.error('  1. Review the changes above');\n    console.error(\n        '  2. If intentional, ASK USER to run: nx run architecture:generate since this is a critical change',\n    );\n    console.error('  3. Commit the updated architecture/dependencies.json');\n}\n\n/**\n * Which APIs dependencies.json links to a contract file, compared by LINK only — an added or removed\n * API. The endpoints inside `architecture/apis/<Api>.json` are deliberately NOT compared (#949): an\n * endpoint change must not fail this rule. Null when the links match.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch in this file\nfunction describeContractLinkDrift(\n    current: ApiContractFileRefs,\n    saved: ApiContractFileRefs,\n): string | null {\n    const names = [...new Set([...Object.keys(current), ...Object.keys(saved)])].sort();\n    const changes: string[] = [];\n    for (const name of names) {\n        const a = current[name];\n        const b = saved[name];\n        if (a === undefined)\n            changes.push(`  - ${name}: linked in dependencies.json but no longer in source`);\n        else if (b === undefined)\n            changes.push(`  + ${name}: in source but not linked from dependencies.json`);\n        else if (a !== b) changes.push(`  ~ ${name}: contract file link changed (${b} -> ${a})`);\n    }\n    if (changes.length === 0) return null;\n    return `apiContractFiles drift (${changes.length} api(s)):\\n${changes.join('\\n')}`;\n}\n\n/**\n * Drift in EITHER side table of dependencies.json — the api contract-file links or the\n * external-system declarations — or null when both match. The first difference found is reported;\n * fixing it is the same single command either way, so listing both adds noise rather than information.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches describeContractLinkDrift above\nexport function describeTableDrift(\n    current: CurrentArchitecture,\n    saved: DependenciesFile,\n): string | null {\n    const linkDrift = describeContractLinkDrift(current.apiContractFiles, saved.apiContractFiles);\n    if (linkDrift !== null) return linkDrift;\n    return describeExternalSystemDrift(current.externalSystems, saved.externalSystems);\n}\n\n/**\n * The same drift report for the declared external systems, or null when they match. Named per\n * system so the message points at the database that changed rather than dumping two JSON blobs.\n */\n// webpieces-disable no-function-outside-class -- executor step helper, matches describeContractLinkDrift above\nfunction describeExternalSystemDrift(\n    current: ExternalSystemDecls,\n    saved: ExternalSystemDecls,\n): string | null {\n    const names = [...new Set([...Object.keys(current), ...Object.keys(saved)])].sort();\n    const changes: string[] = [];\n    for (const name of names) {\n        const a = current[name];\n        const b = saved[name];\n        if (a === undefined)\n            changes.push(`  - ${name}: in dependencies.json but no longer declared in source`);\n        else if (b === undefined)\n            changes.push(`  + ${name}: declared in source but missing from dependencies.json`);\n        else if (JSON.stringify(a) !== JSON.stringify(b))\n            changes.push(`  ~ ${name}: kind/label/declarers changed`);\n    }\n    if (changes.length === 0) return null;\n    return `externalSystems drift (${changes.length} system(s)):\\n${changes.join('\\n')}`;\n}\n\n/**\n * Build the current dependency graph exactly as the generator does: reduce the nx\n * graph, sort into levels, enrich with metadata, and attach the derived\n * apiRelations — so this validator compares like-for-like against the committed file.\n */\nexport class CurrentGraphBuilder {\n    async build(workspaceRoot: string, graphPath?: string): Promise<CurrentArchitecture> {\n        console.log('📊 Generating current dependency graph...');\n        const reducedGraph = await generateReducedGraph();\n        console.log('🔄 Computing topological layers...');\n        const currentGraph = sortGraphTopologically(reducedGraph);\n        console.log('🏷️  Enriching graph with framework + responsibilities metadata...');\n        const projectInfos = await collectProjectInfo();\n        new WorkspaceClientBindings().assert(workspaceRoot, projectInfos);\n        enrichGraph(currentGraph, projectInfos, workspaceRoot);\n        new TagTruthCheck().assertTrue(currentGraph, projectInfos, workspaceRoot);\n        new ApprovedWiringGraph().attach(workspaceRoot, currentGraph, projectInfos, graphPath);\n        const saved = loadBlessedGraph(workspaceRoot, graphPath);\n        if (saved === null)\n            throw new RuleFailError(\n                'validate-runtime-architecture',\n                'Missing approved graph.',\n                undefined,\n                undefined,\n                [\n                    new Option(\n                        'Migrate src/wiring.ts and review runtime-deps.json and API contract approvals.',\n                        true,\n                    ),\n                ],\n            );\n        return new CurrentArchitecture(currentGraph, saved.apiContractFiles, saved.externalSystems);\n    }\n}\n\n/** The regenerated graph plus the two tables beside it — everything dependencies.json holds. */\nexport class CurrentArchitecture {\n    constructor(\n        public readonly graph: EnhancedGraph,\n        public readonly apiContractFiles: ApiContractFileRefs,\n        public readonly externalSystems: ExternalSystemDecls,\n    ) {}\n}\n\n/** The bootstrap path: there is nothing to diff against yet, so say how to create it. */\n// webpieces-disable no-function-outside-class -- executor step helper, matches reportMismatch in this file\nfunction reportMissingGraph(): never {\n    throw new RuleFailError(\n        'validate-runtime-architecture',\n        'Missing reviewed architecture/dependencies.json.',\n        undefined,\n        undefined,\n        [\n            new Option(\n                'Run owning API source build checks to emit contract candidates, review and copy them into architecture/apis/<ApiName>.json, and create dependencies.json with projects:{}, apiContractFiles:{\"<ApiName>\":\"apis/<ApiName>.json\"}, and reviewed externalSystems. Approve tagged owners runtime-deps.json candidates, then run architecture:generate and review the resulting graph.',\n                true,\n            ),\n        ],\n    );\n}\n\nexport default async function runExecutor(\n    options: ValidateArchitectureUnchangedOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    // Epoch-gateable: this rule diffs against the blessed architecture/dependencies.json, so\n    // \"grandfather the current drift until <epoch>\" is meaningful — hence honorEpoch = true.\n    if (new RuleGate().isDisabled(workspaceRoot, 'validate-architecture-unchanged', true)) {\n        return { success: true };\n    }\n\n    console.log('\\n🔍 Validating Architecture Unchanged\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Check if saved graph exists\n        if (!graphFileExists(workspaceRoot, graphPath)) {\n            reportMissingGraph();\n            return { success: false };\n        }\n\n        // Steps 1-3: build + enrich + scan the current graph (same pipeline the\n        // generator runs, so any drift is caught).\n        const currentGraph = await new CurrentGraphBuilder().build(workspaceRoot, graphPath);\n\n        // Step 4: Load saved graph\n        console.log('📂 Loading saved graph...');\n        const savedGraph = loadBlessedGraph(workspaceRoot, graphPath);\n\n        if (!savedGraph) {\n            console.error('❌ Could not load saved graph');\n            return { success: false };\n        }\n\n        // Step 5: Compare graphs\n        console.log('🔍 Comparing current graph to saved graph...');\n        const comparison = compareGraphs(currentGraph.graph, savedGraph.projects);\n\n        if (!comparison.identical) {\n            reportMismatch(comparison.summary, workspaceRoot);\n            return { success: false };\n        }\n\n        // Step 6: Compare the two side tables as well: which APIs are linked to a contract file, and\n        // the external-system declarations. The endpoints inside architecture/apis/<Api>.json are\n        // NOT compared — an endpoint change must never fail this rule (#949).\n        const tableDrift = describeTableDrift(currentGraph, savedGraph);\n        if (tableDrift !== null) {\n            reportMismatch(tableDrift, workspaceRoot);\n            return { success: false };\n        }\n\n        console.log('✅ Architecture unchanged - current graph matches saved graph');\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        // A RuleFailError (e.g. a dependencies.json still carrying the moved `apiContracts` key)\n        // carries its cures in Option[]; render them rather than dropping them with `.message`.\n        const rendered =\n            error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message;\n        console.error('❌ Architecture validation failed:', rendered);\n        reportMetadataFailure(error, workspaceRoot);\n        return { success: false };\n    }\n}\n\n// webpieces-disable no-function-outside-class -- executor diagnostic formatting\nfunction reportMetadataFailure(error: Error, workspaceRoot: string): void {\n    if (error instanceof MetadataValidationError) {\n        const mdPath = writeTemplate(workspaceRoot, 'webpieces.responsibilities.md');\n        console.error('');\n        console.error(\n            '⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️',\n        );\n    }\n}\n"]}

package/src/lib/api-usage/api-doc-rules-scan.js

@@ -66,7 +66,7 @@ const api_doc_rules_1 = require("./api-doc-rules");
 const api_doc_rules_verdicts_1 = require("./api-doc-rules-verdicts");
 const wire_closure_1 = require("./wire-closure");
 /** `@ApiPath(` at COLUMN ZERO — a docstring that TALKS about a contract declares none. */
-const DECLARES_CONTRACT = /^@ApiPath\(/m;
+const DECLARES_CONTRACT = /@/;
 /** ONE contract file, and which of the two rules apply to the project that owns it. */
 class ContractFile {
     absPath;

package/src/lib/api-usage/api-doc-rules-scan.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-doc-rules-scan.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-usage/api-doc-rules-scan.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `api-rules-for-openapi` and `api-rules-for-mcp` (#1011) — the CI half of \"is this contract\n * publishable\", on every `@ApiPath` class IN SCOPE, `@ApiType` or not.\n *\n * \"In scope\" is the rule's `mode` (#1017): `AFFECTED_PROJECT` scans the contracts of the projects the\n * diff touched — the granularity nx already builds at, and the mode a consumer normally picks —\n * while `RUN_EVERY_TIME` scans the whole workspace for a migration sweep. `ApiDocRule.coversProject`\n * is the one place that answers it, for both rules.\n *\n * ## The acceptance contract, and why this file drives the generator instead of copying it\n *\n * The rules exist so that ADDING `@ApiType(...)` (and `@WpMcpTool`) to a contract that passes them\n * always works. That is only true if \"expressible\" has exactly ONE definition, so this scan runs the\n * generator's own code — `ApiDocExtractor` / `TypeResolver` from `@webpieces/api-doc-model` for the\n * OpenAPI half, and `McpSchemaRenderer` tool-by-tool for the MCP half. A second implementation of\n * \"what can be published\" would drift from the first on the release that improved either one, and\n * the drift would be silent: the rules would stay green while generation started failing. The two\n * packages ship on the same release train, so the dependency is in lockstep by construction.\n *\n * Two things here are STRICTER than the generator, deliberately, and both are publishing rules\n * rather than expressibility ones (being stricter cannot break the acceptance contract — it can only\n * refuse something that would have generated):\n *\n *  - an `unknown` VALUE TYPE anywhere (`Record<string, unknown>`, `unknown[]`, a bare `unknown`\n *    field). The extractor maps it to a primitive and the generator publishes `{}`, which in JSON\n *    Schema means \"anything\" — a partner-facing field with no shape, which is the defect the\n *    unmapped guard exists for, arriving through a door the guard does not watch.\n *  - an `rpc` or `external` endpoint whose response is `void`. Fire-and-forget is the CONTRACT of a\n *    `cloudtasks` or `cron` endpoint and is allowed there; an endpoint somebody WAITS on that answers\n *    nothing can never gain a field without a breaking change, where a named empty response object\n *    grows additively forever (#1017 — #1016 read this narrowly as rpc-only because `external` was\n *    unstated).\n *\n * ## Why it lives in the rules engine and not in the doc parser\n *\n * `@webpieces/api-doc-model` is only ever pointed at contracts somebody chose to publish. `@ApiType`\n * is a PUBLISHING decision added later, on purpose — so a shape rule that only ran on contracts which\n * had already opted in would let a team discover, six months afterwards, that the type was never\n * expressible, by which time it is in partners' generated clients. So every check below runs on every\n * contract in scope, opted in or not — `@ApiType` narrows nothing here.\n *\n * ## The wire closure (#1064, D4)\n *\n * Every named type a contract reaches must be DECLARED in a `role:api-lib` project and end in the\n * suffix its `required-type-suffix` entry demands — see `wire-closure.ts`. It is a shared defect: a type\n * declared in a general library is wrong on the wire whichever document it would have been in.\n *\n * ## Root-level unions are NOT re-checked here\n *\n * `no-root-union-api-type` (#1009) already refuses them, workspace-wide, with its own config key and\n * its own per-site hatch. One implementation. The MCP half still reports one when it meets it,\n * because `McpSchemaRenderer` refuses it as its own backstop and this scan reports whatever the\n * renderer says — which is the correct division: the OpenAPI document publishes a root union\n * perfectly well, and only a tool schema cannot carry one.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport * as ts from 'typescript';\nimport {\n    ApiDocExtractionError,\n    ApiDocExtractor,\n    ApiDocModel,\n    DocumentedEndpoint,\n    McpRenderError,\n    McpSchemaRenderer,\n    TypeRef,\n    UnmappedType,\n} from '@webpieces/api-doc-model';\nimport { ProjectInfo } from '../project-info';\nimport { collectTsFiles, isTestFile } from './api-ast';\nimport {\n    ApiContractDefect,\n    ApiDocRule,\n    ApiDocRulesFindings,\n    ApiRuleFindings,\n    DisableComment,\n    McpExclusion,\n    MCP_RULE,\n    OPENAPI_RULE,\n} from './api-doc-rules';\nimport {\n    ANSWERING_KINDS,\n    ContractLines,\n    unknownValueCure,\n    VOID_RPC_CURE,\n    carriesUnknown,\n    classifyUnmapped,\n    contractLinesOf,\n    contractNamesIn,\n    isVoidLike,\n    toolFailures,\n} from './api-doc-rules-verdicts';\nimport { WireClosure, WireClosureRule } from './wire-closure';\n\n/** `@ApiPath(` at COLUMN ZERO — a docstring that TALKS about a contract declares none. */\nconst DECLARES_CONTRACT = /^@ApiPath\\(/m;\n\n/** ONE contract file, and which of the two rules apply to the project that owns it. */\nclass ContractFile {\n    constructor(\n        public readonly absPath: string,\n        public readonly openApi: boolean,\n        public readonly mcp: boolean,\n    ) {}\n}\n\n/** Where one declaration sits, already split out of the extractor's `File.ts:LINE:COL` spelling. */\nclass Site {\n    constructor(\n        public readonly absPath: string,\n        public readonly line: number,\n    ) {}\n\n    /** `path/to/File.ts:LINE`, workspace-relative — what a refusal prints. */\n    relativeTo(workspaceRoot: string): string {\n        return `${path.relative(workspaceRoot, this.absPath)}:${this.line}`;\n    }\n\n    /** `abs/File.ts:12:5` -> a Site. An unparseable one falls back to line 1 of `fallback`. */\n    // webpieces-disable no-function-outside-class -- static factory of this class\n    static parse(location: string, fallback: string): Site {\n        const match = location.match(/^(.*):(\\d+):\\d+$/);\n        if (match === null) return new Site(fallback, 1);\n        return new Site(match[1], Number(match[2]));\n    }\n}\n\n/**\n * ONE rule's accumulator. It is what applies the per-site disable, so the disable semantics live in\n * exactly one place and cannot differ between the two rules.\n */\nclass DefectCollector {\n    private readonly violations: ApiContractDefect[] = [];\n    private readonly reasonless: ApiContractDefect[] = [];\n\n    constructor(private readonly ruleName: string) {}\n\n    /** The rule this collector reports under — what a shared defect's cure has to name. */\n    rule(): string {\n        return this.ruleName;\n    }\n\n    add(defect: ApiContractDefect, site: Site): void {\n        const disable = DisableComment.readAt(site.absPath, site.line, this.ruleName);\n        if (disable === undefined) {\n            this.violations.push(defect);\n            return;\n        }\n        if (!disable.hasReason) this.reasonless.push(defect);\n    }\n\n    findings(): ApiRuleFindings {\n        return new ApiRuleFindings(\n            DefectCollector.externalFirst(this.violations),\n            DefectCollector.externalFirst(this.reasonless),\n        );\n    }\n\n    /**\n     * Partner-facing contracts first. The same defect is a different size depending on who reads the\n     * document it would have been in, and a list that buries the `external-customer` ones among\n     * thirty internal ones has hidden the only urgent line in it.\n     */\n    // webpieces-disable no-function-outside-class -- private static ordering of this class\n    private static externalFirst(found: readonly ApiContractDefect[]): ApiContractDefect[] {\n        return [...found].sort(\n            (a: ApiContractDefect, b: ApiContractDefect) =>\n                Number(b.isExternal()) - Number(a.isExternal()),\n        );\n    }\n}\n\n/**\n * Routes a defect to the rule that owns it.\n *\n * Every OpenAPI-level defect ALSO blocks MCP, so it is reported by whichever rule is running —\n * `api-rules-for-openapi` when that one is on, and `api-rules-for-mcp` alone when it is not. It is\n * never reported twice: a team running both would otherwise read every shared defect in two places\n * and have to work out that they are one.\n */\nclass DefectSink {\n    constructor(\n        private readonly openApi: DefectCollector | undefined,\n        private readonly mcp: DefectCollector | undefined,\n    ) {}\n\n    /**\n     * A defect that blocks the OpenAPI document, and therefore every tool on it too.\n     *\n     * The defect is BUILT from the rule that ends up reporting it, not handed in ready-made, because\n     * a shared defect does not know in advance which rule will carry it: `api-rules-for-openapi` when\n     * that one runs, and `api-rules-for-mcp` alone when it does not. A cure that named a fixed rule\n     * would, on the mcp-only configuration, prescribe a `// webpieces-disable` line the collector\n     * reading that site does not look for.\n     */\n    shared(build: (rule: string) => ApiContractDefect, site: Site): void {\n        const target = this.openApi ?? this.mcp;\n        if (target === undefined) return;\n        target.add(build(target.rule()), site);\n    }\n\n    /** A defect that blocks ONE tool and nothing else. */\n    mcpOnly(defect: ApiContractDefect, site: Site): void {\n        this.mcp?.add(defect, site);\n    }\n\n    anyRuleRuns(): boolean {\n        return this.openApi !== undefined || this.mcp !== undefined;\n    }\n\n    /** True when `api-rules-for-mcp` applies to this file — what the exclusion list is scoped to. */\n    mcpRuns(): boolean {\n        return this.mcp !== undefined;\n    }\n}\n\n/**\n * Walks every project's `src`, extracts every `@ApiPath` contract with the generator's own\n * extractor, and judges the result against the two rules.\n *\n * ONE `ts.Program` over every contract file in the workspace, because a DTO a contract reaches\n * routinely lives in another project and the checker has to be able to follow the import — the same\n * reason the repo sweep in `@webpieces/api-doc-model`'s own spec builds one program rather than one\n * per file.\n */\nexport class ApiDocRulesScan {\n    /**\n     * Every `@InvalidEndpointForMcp` endpoint met on a file the MCP rule applies to.\n     *\n     * Collected even on a run with no findings at all, because restating them IS the feature: the\n     * alternative considered in #1014 was a one-off warning when somebody adds one, and a warning\n     * printed once at the moment of the decision is read by the one person who already knows.\n     */\n    private readonly exclusions: McpExclusion[] = [];\n\n    constructor(\n        private readonly workspaceRoot: string,\n        private readonly projectInfos: Map<string, ProjectInfo>,\n        /** OFF unless a caller read otherwise out of webpieces.config.json, which MUST state it. */\n        private readonly openApiRule: ApiDocRule = ApiDocRule.off(OPENAPI_RULE),\n        private readonly mcpRule: ApiDocRule = ApiDocRule.off(MCP_RULE),\n        /** The suffix half of the wire closure; the role half always runs when either rule does. */\n        private readonly wireClosureRule: WireClosureRule = WireClosureRule.withoutSuffixes(),\n    ) {}\n\n    run(): ApiDocRulesFindings {\n        if (!this.openApiRule.enabled && !this.mcpRule.enabled) return ApiDocRulesFindings.empty();\n        const files = this.contractFiles();\n        if (files.length === 0) return ApiDocRulesFindings.empty();\n\n        const openApi = this.openApiRule.enabled ? new DefectCollector(OPENAPI_RULE) : undefined;\n        const mcp = this.mcpRule.enabled ? new DefectCollector(MCP_RULE) : undefined;\n        const program = ts.createProgram(\n            files.map((file: ContractFile) => file.absPath),\n            this.compilerOptions(),\n        );\n        const toolNames = new Map<string, string>();\n        const closure = new WireClosure(this.workspaceRoot, this.projectInfos, this.wireClosureRule);\n        for (const file of files) {\n            const sink = new DefectSink(\n                file.openApi ? openApi : undefined,\n                file.mcp ? mcp : undefined,\n            );\n            this.judgeFile(file, program, sink, toolNames, closure);\n        }\n        return new ApiDocRulesFindings(\n            openApi?.findings() ?? new ApiRuleFindings([], []),\n            mcp?.findings() ?? new ApiRuleFindings([], []),\n            this.exclusions,\n        );\n    }\n\n    /** Every contract in one file, or the ONE refusal that stopped the file being read at all. */\n    private judgeFile(\n        file: ContractFile,\n        program: ts.Program,\n        sink: DefectSink,\n        toolNames: Map<string, string>,\n        closure: WireClosure,\n    ): void {\n        if (!sink.anyRuleRuns()) return;\n        const source = program.getSourceFile(file.absPath);\n        if (source === undefined) return;\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- an extraction refusal IS a finding; it is reported, not propagated\n        try {\n            for (const model of new ApiDocExtractor().extractAllFrom(program, source)) {\n                this.judgeModel(model, source, sink, toolNames);\n                this.judgeWireClosure(model, sink, source.fileName, closure);\n            }\n        } catch (err: unknown) {\n            //const error = toError(err);\n            if (!(err instanceof ApiDocExtractionError)) throw err;\n            this.reportExtractionFailure(err, file, source, sink);\n        }\n    }\n\n    /**\n     * An extraction that REFUSED. Reported under the shared list because it stops BOTH documents:\n     * `@Endpoint` arguments that cannot be constant-folded, a bound on a non-numeric field, and the\n     * `@ApiType(..., MCP)` ⇔ `@WpMcpTool` biconditional all fail here, before a model exists.\n     */\n    private reportExtractionFailure(\n        error: ApiDocExtractionError,\n        file: ContractFile,\n        source: ts.SourceFile,\n        sink: DefectSink,\n    ): void {\n        const site = Site.parse(error.location, file.absPath);\n        sink.shared(\n            (): ApiContractDefect => new ApiContractDefect(\n                contractNamesIn(source)[0] ?? path.basename(file.absPath),\n                '',\n                `the contract cannot be read at all — ${error.message}`,\n                site.relativeTo(this.workspaceRoot),\n                error.cure,\n                [],\n            ),\n            site,\n        );\n    }\n\n    /** ONE contract: the shared OpenAPI checks, then the MCP-only ones. */\n    private judgeModel(\n        model: ApiDocModel,\n        source: ts.SourceFile,\n        sink: DefectSink,\n        toolNames: Map<string, string>,\n    ): void {\n        const lines = contractLinesOf(source, model.contractName);\n        this.judgeUnmapped(model, sink, source.fileName);\n        this.judgeUnknownValues(model, sink, source.fileName);\n        this.judgeAnsweringResponses(model, source, lines, sink);\n        this.judgeTools(model, source, lines, sink, toolNames);\n    }\n\n    /**\n     * D4 — every named type the contract reaches is declared in a `role:api-lib` project and carries its\n     * suffix. Shared: a type that should never have left a general library blocks every document.\n     */\n    private judgeWireClosure(model: ApiDocModel, sink: DefectSink, fallback: string, closure: WireClosure): void {\n        for (const type of model.types.values()) {\n            const site = Site.parse(type.location, fallback);\n            for (const verdict of closure.judge(type, site.absPath)) {\n                sink.shared(\n                    (): ApiContractDefect => new ApiContractDefect(\n                        model.contractName,\n                        '',\n                        verdict.what,\n                        site.relativeTo(this.workspaceRoot),\n                        verdict.cure,\n                        model.apiTypes,\n                    ),\n                    site,\n                );\n            }\n        }\n    }\n\n    /** Everything `TypeResolver` could not represent — the generator's OWN verdict, re-worded. */\n    private judgeUnmapped(model: ApiDocModel, sink: DefectSink, fallback: string): void {\n        for (const unmapped of model.unmapped) {\n            const site = Site.parse(unmapped.location, fallback);\n            const verdict = classifyUnmapped(unmapped);\n            sink.shared(\n                (): ApiContractDefect => new ApiContractDefect(\n                    model.contractName,\n                    '',\n                    verdict.what,\n                    site.relativeTo(this.workspaceRoot),\n                    verdict.cure,\n                    model.apiTypes,\n                ),\n                site,\n            );\n        }\n    }\n\n    /** `Record<string, unknown>`, `unknown[]`, `x: unknown` — by VALUE TYPE, never by spelling. */\n    private judgeUnknownValues(model: ApiDocModel, sink: DefectSink, fallback: string): void {\n        for (const type of model.types.values()) {\n            for (const field of type.fields) {\n                if (!carriesUnknown(field.type)) continue;\n                const site = Site.parse(field.location, fallback);\n                sink.shared(\n                    (rule: string): ApiContractDefect =>\n                        new ApiContractDefect(\n                            model.contractName,\n                            '',\n                            `'${type.name}.${field.name}' publishes an 'unknown' value, so the ` +\n                                'document states no shape for it at all',\n                            site.relativeTo(this.workspaceRoot),\n                            unknownValueCure(rule),\n                            model.apiTypes,\n                        ),\n                    site,\n                );\n            }\n        }\n    }\n\n    /**\n     * An endpoint somebody WAITS ON must NAME a response DTO, even an empty one.\n     *\n     * `Promise<void>` on a `cloudtasks` or `cron` endpoint is the CONTRACT — fire-and-forget, nothing\n     * to shape — and is allowed. On an `rpc` OR an `external` it is a one-way door: both are\n     * synchronous request/response, an outside caller reads what comes back, and a `void` response\n     * can never gain a field without breaking every generated client where `{}` grows additively\n     * forever. This is a contract-EVOLUTION rule, which is why it is here and not in the MCP half: it\n     * is worth having on an endpoint that never becomes a tool. See ANSWERING_KINDS (#1017).\n     */\n    private judgeAnsweringResponses(\n        model: ApiDocModel,\n        source: ts.SourceFile,\n        lines: ContractLines,\n        sink: DefectSink,\n    ): void {\n        for (const endpoint of model.endpoints) {\n            // `.some` and not `.includes`: the model's `kind` is a widened string, and the list is\n            // typed EndpointKind so a kind that stops existing is a compile error here.\n            if (!ANSWERING_KINDS.some((kind: string): boolean => kind === endpoint.kind)) continue;\n            if (endpoint.response !== undefined && !isVoidLike(endpoint.response)) continue;\n            const site = new Site(source.fileName, lines.lineOf(endpoint.methodName));\n            sink.shared(\n                (): ApiContractDefect => new ApiContractDefect(\n                    model.contractName,\n                    endpoint.methodName,\n                    `an ${endpoint.kind} endpoint returns nothing a document can name (void, ` +\n                        'unknown, or no declared return type)',\n                    site.relativeTo(this.workspaceRoot),\n                    VOID_RPC_CURE,\n                    model.apiTypes,\n                ),\n                site,\n            );\n        }\n    }\n\n    /** Everything `McpToolRegistry` refuses to boot on, plus whatever the renderer cannot render. */\n    private judgeTools(\n        model: ApiDocModel,\n        source: ts.SourceFile,\n        lines: ContractLines,\n        sink: DefectSink,\n        toolNames: Map<string, string>,\n    ): void {\n        const renderer = new McpSchemaRenderer(model);\n        for (const endpoint of model.endpoints) {\n            if (endpoint.invalidForMcp !== undefined) {\n                if (!sink.mcpRuns()) continue;\n                // @InvalidEndpointForMcp IS the answer to \"could this be a tool\". The decorator\n                // carries the argument, so the rule asks nothing further and no webpieces-disable is\n                // needed — a suppression would be a second, weaker spelling of the same declaration.\n                this.exclusions.push(\n                    new McpExclusion(\n                        model.contractName,\n                        endpoint.methodName,\n                        endpoint.invalidForMcp,\n                        new Site(\n                            source.fileName,\n                            lines.lineOf(endpoint.methodName),\n                        ).relativeTo(this.workspaceRoot),\n                    ),\n                );\n                continue;\n            }\n            if (endpoint.mcpTool === undefined) continue;\n            const site = new Site(source.fileName, lines.lineOf(endpoint.methodName));\n            for (const failure of toolFailures(endpoint, renderer, toolNames, model)) {\n                sink.mcpOnly(\n                    new ApiContractDefect(\n                        model.contractName,\n                        endpoint.methodName,\n                        failure.what,\n                        site.relativeTo(this.workspaceRoot),\n                        failure.cure,\n                        model.apiTypes,\n                    ),\n                    site,\n                );\n            }\n        }\n        for (const methodName of lines.toolsWithoutEndpoint) {\n            const site = new Site(source.fileName, lines.lineOf(methodName));\n            sink.mcpOnly(\n                new ApiContractDefect(\n                    model.contractName,\n                    methodName,\n                    'carries @WpMcpTool but is not an @Endpoint, so it is not routed at all',\n                    site.relativeTo(this.workspaceRoot),\n                    \"Add @Endpoint(POST, '/path', READ, RPC) to it, or drop the @WpMcpTool.\",\n                    model.apiTypes,\n                ),\n                site,\n            );\n        }\n    }\n\n    /** Every non-test `.ts` under a project's `src` whose text DECLARES an `@ApiPath` contract. */\n    private contractFiles(): ContractFile[] {\n        const found: ContractFile[] = [];\n        for (const info of this.projectInfos.values()) {\n            if (info.root === '' || info.root === '.') continue;\n            // ONE question, asked of the rule itself: `mode` (OFF / AFFECTED_PROJECT /\n            // RUN_EVERY_TIME) and `allowedPaths` are both folded into coversProject, so the\n            // affected-project narrowing cannot be honoured in one branch and skipped in the other.\n            const openApi = this.openApiRule.coversProject(info.root);\n            const mcp = this.mcpRule.coversProject(info.root);\n            if (!openApi && !mcp) continue;\n            const srcDir = path.join(path.resolve(this.workspaceRoot, info.root), 'src');\n            if (!fs.existsSync(srcDir)) continue;\n            for (const file of collectTsFiles(srcDir)) {\n                if (isTestFile(file)) continue; // a fixture is not a published contract\n                if (!DECLARES_CONTRACT.test(fs.readFileSync(file, 'utf8'))) continue;\n                found.push(new ContractFile(file, openApi, mcp));\n            }\n        }\n        return found.sort((a: ContractFile, b: ContractFile) => a.absPath.localeCompare(b.absPath));\n    }\n\n    /**\n     * `tsconfig.base.json`'s options when the workspace has one, so an `@webpieces/*` import in a\n     * contract RESOLVES and the checker can follow a DTO into another project. Without that the\n     * resolver reports every cross-project type as unmapped, which would be a rule failing on its\n     * own inability to read rather than on anything the author wrote.\n     */\n    private compilerOptions(): ts.CompilerOptions {\n        const base = path.join(this.workspaceRoot, 'tsconfig.base.json');\n        const declared = fs.existsSync(base)\n            ? ts.parseJsonConfigFileContent(\n                  ts.readConfigFile(base, ts.sys.readFile).config,\n                  ts.sys,\n                  this.workspaceRoot,\n              ).options\n            : {};\n        return {\n            ...declared,\n            noEmit: true,\n            skipLibCheck: true,\n            types: [],\n            experimentalDecorators: true,\n        };\n    }\n}\n"]}
+{"version":3,"file":"api-doc-rules-scan.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-usage/api-doc-rules-scan.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `api-rules-for-openapi` and `api-rules-for-mcp` (#1011) — the CI half of \"is this contract\n * publishable\", on every `@ApiPath` class IN SCOPE, `@ApiType` or not.\n *\n * \"In scope\" is the rule's `mode` (#1017): `AFFECTED_PROJECT` scans the contracts of the projects the\n * diff touched — the granularity nx already builds at, and the mode a consumer normally picks —\n * while `RUN_EVERY_TIME` scans the whole workspace for a migration sweep. `ApiDocRule.coversProject`\n * is the one place that answers it, for both rules.\n *\n * ## The acceptance contract, and why this file drives the generator instead of copying it\n *\n * The rules exist so that ADDING `@ApiType(...)` (and `@WpMcpTool`) to a contract that passes them\n * always works. That is only true if \"expressible\" has exactly ONE definition, so this scan runs the\n * generator's own code — `ApiDocExtractor` / `TypeResolver` from `@webpieces/api-doc-model` for the\n * OpenAPI half, and `McpSchemaRenderer` tool-by-tool for the MCP half. A second implementation of\n * \"what can be published\" would drift from the first on the release that improved either one, and\n * the drift would be silent: the rules would stay green while generation started failing. The two\n * packages ship on the same release train, so the dependency is in lockstep by construction.\n *\n * Two things here are STRICTER than the generator, deliberately, and both are publishing rules\n * rather than expressibility ones (being stricter cannot break the acceptance contract — it can only\n * refuse something that would have generated):\n *\n *  - an `unknown` VALUE TYPE anywhere (`Record<string, unknown>`, `unknown[]`, a bare `unknown`\n *    field). The extractor maps it to a primitive and the generator publishes `{}`, which in JSON\n *    Schema means \"anything\" — a partner-facing field with no shape, which is the defect the\n *    unmapped guard exists for, arriving through a door the guard does not watch.\n *  - an `rpc` or `external` endpoint whose response is `void`. Fire-and-forget is the CONTRACT of a\n *    `cloudtasks` or `cron` endpoint and is allowed there; an endpoint somebody WAITS on that answers\n *    nothing can never gain a field without a breaking change, where a named empty response object\n *    grows additively forever (#1017 — #1016 read this narrowly as rpc-only because `external` was\n *    unstated).\n *\n * ## Why it lives in the rules engine and not in the doc parser\n *\n * `@webpieces/api-doc-model` is only ever pointed at contracts somebody chose to publish. `@ApiType`\n * is a PUBLISHING decision added later, on purpose — so a shape rule that only ran on contracts which\n * had already opted in would let a team discover, six months afterwards, that the type was never\n * expressible, by which time it is in partners' generated clients. So every check below runs on every\n * contract in scope, opted in or not — `@ApiType` narrows nothing here.\n *\n * ## The wire closure (#1064, D4)\n *\n * Every named type a contract reaches must be DECLARED in a `role:api-lib` project and end in the\n * suffix its `required-type-suffix` entry demands — see `wire-closure.ts`. It is a shared defect: a type\n * declared in a general library is wrong on the wire whichever document it would have been in.\n *\n * ## Root-level unions are NOT re-checked here\n *\n * `no-root-union-api-type` (#1009) already refuses them, workspace-wide, with its own config key and\n * its own per-site hatch. One implementation. The MCP half still reports one when it meets it,\n * because `McpSchemaRenderer` refuses it as its own backstop and this scan reports whatever the\n * renderer says — which is the correct division: the OpenAPI document publishes a root union\n * perfectly well, and only a tool schema cannot carry one.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport * as ts from 'typescript';\nimport {\n    ApiDocExtractionError,\n    ApiDocExtractor,\n    ApiDocModel,\n    DocumentedEndpoint,\n    McpRenderError,\n    McpSchemaRenderer,\n    TypeRef,\n    UnmappedType,\n} from '@webpieces/api-doc-model';\nimport { ProjectInfo } from '../project-info';\nimport { collectTsFiles, isTestFile } from './api-ast';\nimport {\n    ApiContractDefect,\n    ApiDocRule,\n    ApiDocRulesFindings,\n    ApiRuleFindings,\n    DisableComment,\n    McpExclusion,\n    MCP_RULE,\n    OPENAPI_RULE,\n} from './api-doc-rules';\nimport {\n    ANSWERING_KINDS,\n    ContractLines,\n    unknownValueCure,\n    VOID_RPC_CURE,\n    carriesUnknown,\n    classifyUnmapped,\n    contractLinesOf,\n    contractNamesIn,\n    isVoidLike,\n    toolFailures,\n} from './api-doc-rules-verdicts';\nimport { WireClosure, WireClosureRule } from './wire-closure';\n\n/** `@ApiPath(` at COLUMN ZERO — a docstring that TALKS about a contract declares none. */\nconst DECLARES_CONTRACT = /@/;\n\n/** ONE contract file, and which of the two rules apply to the project that owns it. */\nclass ContractFile {\n    constructor(\n        public readonly absPath: string,\n        public readonly openApi: boolean,\n        public readonly mcp: boolean,\n    ) {}\n}\n\n/** Where one declaration sits, already split out of the extractor's `File.ts:LINE:COL` spelling. */\nclass Site {\n    constructor(\n        public readonly absPath: string,\n        public readonly line: number,\n    ) {}\n\n    /** `path/to/File.ts:LINE`, workspace-relative — what a refusal prints. */\n    relativeTo(workspaceRoot: string): string {\n        return `${path.relative(workspaceRoot, this.absPath)}:${this.line}`;\n    }\n\n    /** `abs/File.ts:12:5` -> a Site. An unparseable one falls back to line 1 of `fallback`. */\n    // webpieces-disable no-function-outside-class -- static factory of this class\n    static parse(location: string, fallback: string): Site {\n        const match = location.match(/^(.*):(\\d+):\\d+$/);\n        if (match === null) return new Site(fallback, 1);\n        return new Site(match[1], Number(match[2]));\n    }\n}\n\n/**\n * ONE rule's accumulator. It is what applies the per-site disable, so the disable semantics live in\n * exactly one place and cannot differ between the two rules.\n */\nclass DefectCollector {\n    private readonly violations: ApiContractDefect[] = [];\n    private readonly reasonless: ApiContractDefect[] = [];\n\n    constructor(private readonly ruleName: string) {}\n\n    /** The rule this collector reports under — what a shared defect's cure has to name. */\n    rule(): string {\n        return this.ruleName;\n    }\n\n    add(defect: ApiContractDefect, site: Site): void {\n        const disable = DisableComment.readAt(site.absPath, site.line, this.ruleName);\n        if (disable === undefined) {\n            this.violations.push(defect);\n            return;\n        }\n        if (!disable.hasReason) this.reasonless.push(defect);\n    }\n\n    findings(): ApiRuleFindings {\n        return new ApiRuleFindings(\n            DefectCollector.externalFirst(this.violations),\n            DefectCollector.externalFirst(this.reasonless),\n        );\n    }\n\n    /**\n     * Partner-facing contracts first. The same defect is a different size depending on who reads the\n     * document it would have been in, and a list that buries the `external-customer` ones among\n     * thirty internal ones has hidden the only urgent line in it.\n     */\n    // webpieces-disable no-function-outside-class -- private static ordering of this class\n    private static externalFirst(found: readonly ApiContractDefect[]): ApiContractDefect[] {\n        return [...found].sort(\n            (a: ApiContractDefect, b: ApiContractDefect) =>\n                Number(b.isExternal()) - Number(a.isExternal()),\n        );\n    }\n}\n\n/**\n * Routes a defect to the rule that owns it.\n *\n * Every OpenAPI-level defect ALSO blocks MCP, so it is reported by whichever rule is running —\n * `api-rules-for-openapi` when that one is on, and `api-rules-for-mcp` alone when it is not. It is\n * never reported twice: a team running both would otherwise read every shared defect in two places\n * and have to work out that they are one.\n */\nclass DefectSink {\n    constructor(\n        private readonly openApi: DefectCollector | undefined,\n        private readonly mcp: DefectCollector | undefined,\n    ) {}\n\n    /**\n     * A defect that blocks the OpenAPI document, and therefore every tool on it too.\n     *\n     * The defect is BUILT from the rule that ends up reporting it, not handed in ready-made, because\n     * a shared defect does not know in advance which rule will carry it: `api-rules-for-openapi` when\n     * that one runs, and `api-rules-for-mcp` alone when it does not. A cure that named a fixed rule\n     * would, on the mcp-only configuration, prescribe a `// webpieces-disable` line the collector\n     * reading that site does not look for.\n     */\n    shared(build: (rule: string) => ApiContractDefect, site: Site): void {\n        const target = this.openApi ?? this.mcp;\n        if (target === undefined) return;\n        target.add(build(target.rule()), site);\n    }\n\n    /** A defect that blocks ONE tool and nothing else. */\n    mcpOnly(defect: ApiContractDefect, site: Site): void {\n        this.mcp?.add(defect, site);\n    }\n\n    anyRuleRuns(): boolean {\n        return this.openApi !== undefined || this.mcp !== undefined;\n    }\n\n    /** True when `api-rules-for-mcp` applies to this file — what the exclusion list is scoped to. */\n    mcpRuns(): boolean {\n        return this.mcp !== undefined;\n    }\n}\n\n/**\n * Walks every project's `src`, extracts every `@ApiPath` contract with the generator's own\n * extractor, and judges the result against the two rules.\n *\n * ONE `ts.Program` over every contract file in the workspace, because a DTO a contract reaches\n * routinely lives in another project and the checker has to be able to follow the import — the same\n * reason the repo sweep in `@webpieces/api-doc-model`'s own spec builds one program rather than one\n * per file.\n */\nexport class ApiDocRulesScan {\n    /**\n     * Every `@InvalidEndpointForMcp` endpoint met on a file the MCP rule applies to.\n     *\n     * Collected even on a run with no findings at all, because restating them IS the feature: the\n     * alternative considered in #1014 was a one-off warning when somebody adds one, and a warning\n     * printed once at the moment of the decision is read by the one person who already knows.\n     */\n    private readonly exclusions: McpExclusion[] = [];\n\n    constructor(\n        private readonly workspaceRoot: string,\n        private readonly projectInfos: Map<string, ProjectInfo>,\n        /** OFF unless a caller read otherwise out of webpieces.config.json, which MUST state it. */\n        private readonly openApiRule: ApiDocRule = ApiDocRule.off(OPENAPI_RULE),\n        private readonly mcpRule: ApiDocRule = ApiDocRule.off(MCP_RULE),\n        /** The suffix half of the wire closure; the role half always runs when either rule does. */\n        private readonly wireClosureRule: WireClosureRule = WireClosureRule.withoutSuffixes(),\n    ) {}\n\n    run(): ApiDocRulesFindings {\n        if (!this.openApiRule.enabled && !this.mcpRule.enabled) return ApiDocRulesFindings.empty();\n        const files = this.contractFiles();\n        if (files.length === 0) return ApiDocRulesFindings.empty();\n\n        const openApi = this.openApiRule.enabled ? new DefectCollector(OPENAPI_RULE) : undefined;\n        const mcp = this.mcpRule.enabled ? new DefectCollector(MCP_RULE) : undefined;\n        const program = ts.createProgram(\n            files.map((file: ContractFile) => file.absPath),\n            this.compilerOptions(),\n        );\n        const toolNames = new Map<string, string>();\n        const closure = new WireClosure(this.workspaceRoot, this.projectInfos, this.wireClosureRule);\n        for (const file of files) {\n            const sink = new DefectSink(\n                file.openApi ? openApi : undefined,\n                file.mcp ? mcp : undefined,\n            );\n            this.judgeFile(file, program, sink, toolNames, closure);\n        }\n        return new ApiDocRulesFindings(\n            openApi?.findings() ?? new ApiRuleFindings([], []),\n            mcp?.findings() ?? new ApiRuleFindings([], []),\n            this.exclusions,\n        );\n    }\n\n    /** Every contract in one file, or the ONE refusal that stopped the file being read at all. */\n    private judgeFile(\n        file: ContractFile,\n        program: ts.Program,\n        sink: DefectSink,\n        toolNames: Map<string, string>,\n        closure: WireClosure,\n    ): void {\n        if (!sink.anyRuleRuns()) return;\n        const source = program.getSourceFile(file.absPath);\n        if (source === undefined) return;\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- an extraction refusal IS a finding; it is reported, not propagated\n        try {\n            for (const model of new ApiDocExtractor().extractAllFrom(program, source)) {\n                this.judgeModel(model, source, sink, toolNames);\n                this.judgeWireClosure(model, sink, source.fileName, closure);\n            }\n        } catch (err: unknown) {\n            //const error = toError(err);\n            if (!(err instanceof ApiDocExtractionError)) throw err;\n            this.reportExtractionFailure(err, file, source, sink);\n        }\n    }\n\n    /**\n     * An extraction that REFUSED. Reported under the shared list because it stops BOTH documents:\n     * `@Endpoint` arguments that cannot be constant-folded, a bound on a non-numeric field, and the\n     * `@ApiType(..., MCP)` ⇔ `@WpMcpTool` biconditional all fail here, before a model exists.\n     */\n    private reportExtractionFailure(\n        error: ApiDocExtractionError,\n        file: ContractFile,\n        source: ts.SourceFile,\n        sink: DefectSink,\n    ): void {\n        const site = Site.parse(error.location, file.absPath);\n        sink.shared(\n            (): ApiContractDefect => new ApiContractDefect(\n                contractNamesIn(source)[0] ?? path.basename(file.absPath),\n                '',\n                `the contract cannot be read at all — ${error.message}`,\n                site.relativeTo(this.workspaceRoot),\n                error.cure,\n                [],\n            ),\n            site,\n        );\n    }\n\n    /** ONE contract: the shared OpenAPI checks, then the MCP-only ones. */\n    private judgeModel(\n        model: ApiDocModel,\n        source: ts.SourceFile,\n        sink: DefectSink,\n        toolNames: Map<string, string>,\n    ): void {\n        const lines = contractLinesOf(source, model.contractName);\n        this.judgeUnmapped(model, sink, source.fileName);\n        this.judgeUnknownValues(model, sink, source.fileName);\n        this.judgeAnsweringResponses(model, source, lines, sink);\n        this.judgeTools(model, source, lines, sink, toolNames);\n    }\n\n    /**\n     * D4 — every named type the contract reaches is declared in a `role:api-lib` project and carries its\n     * suffix. Shared: a type that should never have left a general library blocks every document.\n     */\n    private judgeWireClosure(model: ApiDocModel, sink: DefectSink, fallback: string, closure: WireClosure): void {\n        for (const type of model.types.values()) {\n            const site = Site.parse(type.location, fallback);\n            for (const verdict of closure.judge(type, site.absPath)) {\n                sink.shared(\n                    (): ApiContractDefect => new ApiContractDefect(\n                        model.contractName,\n                        '',\n                        verdict.what,\n                        site.relativeTo(this.workspaceRoot),\n                        verdict.cure,\n                        model.apiTypes,\n                    ),\n                    site,\n                );\n            }\n        }\n    }\n\n    /** Everything `TypeResolver` could not represent — the generator's OWN verdict, re-worded. */\n    private judgeUnmapped(model: ApiDocModel, sink: DefectSink, fallback: string): void {\n        for (const unmapped of model.unmapped) {\n            const site = Site.parse(unmapped.location, fallback);\n            const verdict = classifyUnmapped(unmapped);\n            sink.shared(\n                (): ApiContractDefect => new ApiContractDefect(\n                    model.contractName,\n                    '',\n                    verdict.what,\n                    site.relativeTo(this.workspaceRoot),\n                    verdict.cure,\n                    model.apiTypes,\n                ),\n                site,\n            );\n        }\n    }\n\n    /** `Record<string, unknown>`, `unknown[]`, `x: unknown` — by VALUE TYPE, never by spelling. */\n    private judgeUnknownValues(model: ApiDocModel, sink: DefectSink, fallback: string): void {\n        for (const type of model.types.values()) {\n            for (const field of type.fields) {\n                if (!carriesUnknown(field.type)) continue;\n                const site = Site.parse(field.location, fallback);\n                sink.shared(\n                    (rule: string): ApiContractDefect =>\n                        new ApiContractDefect(\n                            model.contractName,\n                            '',\n                            `'${type.name}.${field.name}' publishes an 'unknown' value, so the ` +\n                                'document states no shape for it at all',\n                            site.relativeTo(this.workspaceRoot),\n                            unknownValueCure(rule),\n                            model.apiTypes,\n                        ),\n                    site,\n                );\n            }\n        }\n    }\n\n    /**\n     * An endpoint somebody WAITS ON must NAME a response DTO, even an empty one.\n     *\n     * `Promise<void>` on a `cloudtasks` or `cron` endpoint is the CONTRACT — fire-and-forget, nothing\n     * to shape — and is allowed. On an `rpc` OR an `external` it is a one-way door: both are\n     * synchronous request/response, an outside caller reads what comes back, and a `void` response\n     * can never gain a field without breaking every generated client where `{}` grows additively\n     * forever. This is a contract-EVOLUTION rule, which is why it is here and not in the MCP half: it\n     * is worth having on an endpoint that never becomes a tool. See ANSWERING_KINDS (#1017).\n     */\n    private judgeAnsweringResponses(\n        model: ApiDocModel,\n        source: ts.SourceFile,\n        lines: ContractLines,\n        sink: DefectSink,\n    ): void {\n        for (const endpoint of model.endpoints) {\n            // `.some` and not `.includes`: the model's `kind` is a widened string, and the list is\n            // typed EndpointKind so a kind that stops existing is a compile error here.\n            if (!ANSWERING_KINDS.some((kind: string): boolean => kind === endpoint.kind)) continue;\n            if (endpoint.response !== undefined && !isVoidLike(endpoint.response)) continue;\n            const site = new Site(source.fileName, lines.lineOf(endpoint.methodName));\n            sink.shared(\n                (): ApiContractDefect => new ApiContractDefect(\n                    model.contractName,\n                    endpoint.methodName,\n                    `an ${endpoint.kind} endpoint returns nothing a document can name (void, ` +\n                        'unknown, or no declared return type)',\n                    site.relativeTo(this.workspaceRoot),\n                    VOID_RPC_CURE,\n                    model.apiTypes,\n                ),\n                site,\n            );\n        }\n    }\n\n    /** Everything `McpToolRegistry` refuses to boot on, plus whatever the renderer cannot render. */\n    private judgeTools(\n        model: ApiDocModel,\n        source: ts.SourceFile,\n        lines: ContractLines,\n        sink: DefectSink,\n        toolNames: Map<string, string>,\n    ): void {\n        const renderer = new McpSchemaRenderer(model);\n        for (const endpoint of model.endpoints) {\n            if (endpoint.invalidForMcp !== undefined) {\n                if (!sink.mcpRuns()) continue;\n                // @InvalidEndpointForMcp IS the answer to \"could this be a tool\". The decorator\n                // carries the argument, so the rule asks nothing further and no webpieces-disable is\n                // needed — a suppression would be a second, weaker spelling of the same declaration.\n                this.exclusions.push(\n                    new McpExclusion(\n                        model.contractName,\n                        endpoint.methodName,\n                        endpoint.invalidForMcp,\n                        new Site(\n                            source.fileName,\n                            lines.lineOf(endpoint.methodName),\n                        ).relativeTo(this.workspaceRoot),\n                    ),\n                );\n                continue;\n            }\n            if (endpoint.mcpTool === undefined) continue;\n            const site = new Site(source.fileName, lines.lineOf(endpoint.methodName));\n            for (const failure of toolFailures(endpoint, renderer, toolNames, model)) {\n                sink.mcpOnly(\n                    new ApiContractDefect(\n                        model.contractName,\n                        endpoint.methodName,\n                        failure.what,\n                        site.relativeTo(this.workspaceRoot),\n                        failure.cure,\n                        model.apiTypes,\n                    ),\n                    site,\n                );\n            }\n        }\n        for (const methodName of lines.toolsWithoutEndpoint) {\n            const site = new Site(source.fileName, lines.lineOf(methodName));\n            sink.mcpOnly(\n                new ApiContractDefect(\n                    model.contractName,\n                    methodName,\n                    'carries @WpMcpTool but is not an @Endpoint, so it is not routed at all',\n                    site.relativeTo(this.workspaceRoot),\n                    \"Add @Endpoint(POST, '/path', READ, RPC) to it, or drop the @WpMcpTool.\",\n                    model.apiTypes,\n                ),\n                site,\n            );\n        }\n    }\n\n    /** Every non-test `.ts` under a project's `src` whose text DECLARES an `@ApiPath` contract. */\n    private contractFiles(): ContractFile[] {\n        const found: ContractFile[] = [];\n        for (const info of this.projectInfos.values()) {\n            if (info.root === '' || info.root === '.') continue;\n            // ONE question, asked of the rule itself: `mode` (OFF / AFFECTED_PROJECT /\n            // RUN_EVERY_TIME) and `allowedPaths` are both folded into coversProject, so the\n            // affected-project narrowing cannot be honoured in one branch and skipped in the other.\n            const openApi = this.openApiRule.coversProject(info.root);\n            const mcp = this.mcpRule.coversProject(info.root);\n            if (!openApi && !mcp) continue;\n            const srcDir = path.join(path.resolve(this.workspaceRoot, info.root), 'src');\n            if (!fs.existsSync(srcDir)) continue;\n            for (const file of collectTsFiles(srcDir)) {\n                if (isTestFile(file)) continue; // a fixture is not a published contract\n                if (!DECLARES_CONTRACT.test(fs.readFileSync(file, 'utf8'))) continue;\n                found.push(new ContractFile(file, openApi, mcp));\n            }\n        }\n        return found.sort((a: ContractFile, b: ContractFile) => a.absPath.localeCompare(b.absPath));\n    }\n\n    /**\n     * `tsconfig.base.json`'s options when the workspace has one, so an `@webpieces/*` import in a\n     * contract RESOLVES and the checker can follow a DTO into another project. Without that the\n     * resolver reports every cross-project type as unmapped, which would be a rule failing on its\n     * own inability to read rather than on anything the author wrote.\n     */\n    private compilerOptions(): ts.CompilerOptions {\n        const base = path.join(this.workspaceRoot, 'tsconfig.base.json');\n        const declared = fs.existsSync(base)\n            ? ts.parseJsonConfigFileContent(\n                  ts.readConfigFile(base, ts.sys.readFile).config,\n                  ts.sys,\n                  this.workspaceRoot,\n              ).options\n            : {};\n        return {\n            ...declared,\n            noEmit: true,\n            skipLibCheck: true,\n            types: [],\n            experimentalDecorators: true,\n        };\n    }\n}\n"]}

package/src/lib/api-usage/api-doc-rules-verdicts.js

@@ -225,9 +225,9 @@ function toolFailures(endpoint, renderer, toolNames, model) {
             'one, because a tool with no credential is an unauthenticated endpoint an ' +
             'agent can call.'));
     }
-    if (endpoint.mcpAuthText === undefined) {
-        found.push(new Verdict('an MCP tool does not declare @WpMcpAuthJwt(...)', 'Add @WpMcpAuthJwt(...) beside the HTTP auth. MCP authorization is rechecked ' +
-            'before the endpoint boundary and is declared separately on purpose.'));
+    if (endpoint.authorizationText === undefined) {
+        found.push(new Verdict('an MCP tool does not declare @WpAuthorization(...)', 'Add @WpAuthorization(...) beside @WpAuth. Common operation authorization is rechecked ' +
+            'before tool/schema lookup and at the receiving endpoint.'));
     }
     const rendered = renderFailure(renderer, endpoint);
     if (rendered !== undefined)
@@ -306,15 +306,14 @@ function contractLinesOf(source, contractName) {
 function lineOf(source, node) {
     return source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
 }
-/** True when `node` carries `@name(...)`. Matched on the syntax, like every reader in this file. */
+/** Match canonical imports, including aliases and namespace calls. */
 // webpieces-disable no-function-outside-class -- pure AST reader
 function hasDecoratorNamed(node, name) {
     const decorators = ts.canHaveDecorators(node) ? (ts.getDecorators(node) ?? []) : [];
     for (const decorator of decorators) {
         const call = decorator.expression;
         if (ts.isCallExpression(call) &&
-            ts.isIdentifier(call.expression) &&
-            call.expression.text === name) {
+            api_doc_model_1.ApiDocExtractor.canonicalCallName(call.expression) === name) {
             return true;
         }
     }

package/src/lib/api-usage/api-doc-rules-verdicts.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-doc-rules-verdicts.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-usage/api-doc-rules-verdicts.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The pure VERDICTS the api-contract rules print, split out of `api-doc-rules-scan.ts`, which owns\n * the walk and is at its file-size limit.\n *\n * Nothing here touches the filesystem or the project graph. Each function answers one question about\n * ONE declaration the extractor or the renderer has already ruled on, and turns it into the two\n * halves every webpieces refusal carries — what is wrong, and what to do instead. The DECISION is\n * never made here: `model.unmapped` is the extractor's and a render failure is the renderer's. What\n * this file adds is the WORDING, which is the part a generic \"no model representation for this type\n * form\" cannot give an author.\n */\n\nimport * as ts from 'typescript';\nimport {\n    ApiDocModel,\n    DocumentedEndpoint,\n    McpRenderError,\n    McpSchemaRenderer,\n    TypeRef,\n    UnmappedType,\n} from '@webpieces/api-doc-model';\nimport { EndpointKind } from './api-relations';\n\n/**\n * The one trigger kind an MCP tool may have. A LITERAL, for the same reason `EndpointKind` beside it\n * is one: this package deliberately does not depend on `@webpieces/core-util` at runtime, and the\n * set the literal belongs to is pinned by that type.\n */\nexport const RPC_KIND: EndpointKind = 'rpc';\n\n/**\n * The endpoint kinds whose response a caller WAITS FOR, and which therefore must name a DTO (#1017).\n *\n * `rpc` and `external` are both synchronous request/response: somebody posts and reads what comes\n * back, so there IS a body and it must be a named type that can gain a field later. `void` on either\n * is a one-way door — a `void` response can never grow without breaking every generated client, where\n * an empty DTO grows additively forever. #1016 refused it on `rpc` only, because `external` was\n * unstated at the time; it is stated now.\n *\n * `cloudtasks` and `cron` are deliberately NOT here: delivery is fire-and-forget, nobody waits for a\n * body, and `Promise<void>` is the CONTRACT rather than an omission.\n */\nexport const ANSWERING_KINDS: readonly EndpointKind[] = ['rpc', 'external'];\n\n/** The scalar keywords a MIXED SCALAR union is made of. */\nconst SCALAR_KEYWORDS = new Set<ts.SyntaxKind>([\n    ts.SyntaxKind.StringKeyword,\n    ts.SyntaxKind.NumberKeyword,\n    ts.SyntaxKind.BooleanKeyword,\n]);\n\n/** ONE reason a declaration is refused, in the two halves every refusal prints. */\nexport class Verdict {\n    constructor(\n        public readonly what: string,\n        public readonly cure: string,\n    ) {}\n}\n\n\n/** Method name -> the line its declaration starts on, for one contract class. */\nexport class ContractLines {\n    constructor(\n        public readonly classLine: number,\n        public readonly byMethod: ReadonlyMap<string, number>,\n        /** Methods carrying `@WpMcpTool` that do NOT also carry `@Endpoint`. */\n        public readonly toolsWithoutEndpoint: readonly string[],\n    ) {}\n\n    lineOf(methodName: string): number {\n        return this.byMethod.get(methodName) ?? this.classLine;\n    }\n}\n\n\n/**\n * The cure for an `unknown` value, for whichever rule is REPORTING it.\n *\n * It takes the rule name rather than naming one, because this defect is shared: it blocks the\n * OpenAPI document, so `DefectSink` routes it to `api-rules-for-openapi` when that rule is running\n * and to `api-rules-for-mcp` when it is the only one. A hard-coded rule name would then hand an\n * author, on the mcp-only configuration, a `// webpieces-disable api-rules-for-openapi` line that\n * the collector reading the site does not look for — a cure that does not cure, which is the one\n * failure mode a printed cure must not have.\n */\n// webpieces-disable no-function-outside-class -- pure message builder, beside the verdicts that print it\nexport function unknownValueCure(rule: string): string {\n    return (\n        'Name the value type — a DTO, an array of one, a string-literal union, or ' +\n        'Record<string, ThatDto>. If the shape really is unknowable (a transport envelope, ' +\n        'arbitrary SQL rows), write the per-site disable and say so: ' +\n        `// webpieces-disable ${rule} -- <why this field is published with no shape>. ` +\n        'An existing no-any-unknown disable does NOT count — that rule asked whether the code is ' +\n        'type-safe, which is a different question from whether a partner is handed a shapeless field.'\n    );\n}\n\n/** The one cure for a `void` endpoint that somebody is WAITING on (rpc or external). */\nexport const VOID_RPC_CURE =\n    'Declare a named response DTO and return Promise<That>, even when it has no fields today: an ' +\n    'empty object grows additively forever, and a void response cannot gain a field without ' +\n    'breaking every generated client. An external endpoint is a synchronous call an outside caller ' +\n    'waits on, so it has a body too — an empty one serializes as {} and the failure detail rides on ' +\n    'the thrown error. Promise<void> stays legal on a cloudtasks or cron endpoint, where ' +\n    'fire-and-forget is the contract.';\n\n/**\n * Why the resolver could not map this type, said in the author's vocabulary.\n *\n * The DECISION to refuse is the extractor's and is not second-guessed here — every entry in\n * `model.unmapped` becomes a defect. What this adds is the MESSAGE: an open enum and a mixed scalar\n * union are the two shapes a real repo actually hits (measured: 6 of 98 endpoints, from exactly\n * these two), and \"no model representation for this type form\" tells their author nothing.\n */\n// webpieces-disable no-function-outside-class -- pure classifier over the extractor's own verdict\nexport function classifyUnmapped(unmapped: UnmappedType): Verdict {\n    const branches = unionBranchesOf(unmapped.typeText);\n    if (isOpenEnum(branches)) {\n        return new Verdict(\n            `'${unmapped.typeText}' is an OPEN ENUM — literals unioned with the wide type`,\n            'Use an enum OR a string, not both. TypeScript COLLAPSES this union to the wide type, ' +\n                'so the literals buy no compile-time safety and a document cannot state them as a ' +\n                \"closed set. Either drop the `| string` (`'a' | 'b'` publishes as a real enum), or \" +\n                'drop the literals and list the known values in the JSDoc.',\n        );\n    }\n    if (isMixedScalarUnion(branches)) {\n        return new Verdict(\n            `'${unmapped.typeText}' is a MIXED SCALAR union`,\n            'Give the field ONE type. JSON Schema can spell {\"type\": [\"string\",\"number\"]}, but ' +\n                'this framework\\'s ApiJsonSchema helpers read a type array as \"one real type plus ' +\n                'maybe null\" (baseTypeOf returns the first non-null member), so publishing it ' +\n                'would VALIDATE WRONGLY — which is worse than refusing it. Pick the type, or wrap ' +\n                'the alternatives in a discriminated union of named objects.',\n        );\n    }\n    return new Verdict(\n        `'${unmapped.typeText}' has no shape a document can state — ${unmapped.reason}`,\n        'Give it a type a document can carry: a named DTO, an array of one, a string-literal ' +\n            'union, a Record<string, ThatDto>, or a primitive. A field with no shape publishes as ' +\n            '\"anything\".',\n    );\n}\n\n/** The branches of `typeText` when it parses as a union, else an empty list. */\n// webpieces-disable no-function-outside-class -- pure parser used by classifyUnmapped alone\nfunction unionBranchesOf(typeText: string): readonly ts.TypeNode[] {\n    const parsed = ts.createSourceFile(\n        '__unmapped.ts',\n        `type __X = ${typeText};`,\n        ts.ScriptTarget.Latest,\n        true,\n    );\n    const alias = parsed.statements[0];\n    if (alias === undefined || !ts.isTypeAliasDeclaration(alias)) return [];\n    if (!ts.isUnionTypeNode(alias.type)) return [];\n    return alias.type.types.filter((branch: ts.TypeNode) => !isNullishBranch(branch));\n}\n\n/** `'a' | 'b' | string`, and the numeric equivalent. See #1010 and the decision on #1011. */\n// webpieces-disable no-function-outside-class -- pure predicate beside classifyUnmapped\nfunction isOpenEnum(branches: readonly ts.TypeNode[]): boolean {\n    const wide = branches.some(\n        (branch: ts.TypeNode) =>\n            branch.kind === ts.SyntaxKind.StringKeyword ||\n            branch.kind === ts.SyntaxKind.NumberKeyword,\n    );\n    const literals = branches.some((branch: ts.TypeNode) => ts.isLiteralTypeNode(branch));\n    return wide && literals;\n}\n\n/** `string | number`, `string | boolean | null` — two or more DIFFERENT scalar keywords. */\n// webpieces-disable no-function-outside-class -- pure predicate beside classifyUnmapped\nfunction isMixedScalarUnion(branches: readonly ts.TypeNode[]): boolean {\n    if (branches.length < 2) return false;\n    const kinds = new Set<ts.SyntaxKind>();\n    for (const branch of branches) {\n        if (!SCALAR_KEYWORDS.has(branch.kind)) return false;\n        kinds.add(branch.kind);\n    }\n    return kinds.size >= 2;\n}\n\n/** `null` / `undefined` branches — nullability, not composition, exactly as the resolver reads it. */\n// webpieces-disable no-function-outside-class -- pure predicate beside classifyUnmapped\nfunction isNullishBranch(node: ts.TypeNode): boolean {\n    if (node.kind === ts.SyntaxKind.UndefinedKeyword || node.kind === ts.SyntaxKind.NullKeyword) {\n        return true;\n    }\n    return ts.isLiteralTypeNode(node) && node.literal.kind === ts.SyntaxKind.NullKeyword;\n}\n\n/**\n * True when this type PUBLISHES an `unknown` value.\n *\n * It looks at the VALUE TYPE wherever it sits — the item of an array, the value of an open map, the\n * field itself — and never at the `Record<>` spelling, because the real cases in the wild are not\n * all Records: `params?: unknown[]` is the same defect written differently.\n *\n * It does NOT descend through a `ref`: a named DTO is its own entry in the model and its own fields\n * are judged there, so descending would report the same field once per type that points at it.\n */\n// webpieces-disable no-function-outside-class -- pure predicate over one TypeRef\nexport function carriesUnknown(ref: TypeRef): boolean {\n    if (ref.kind === 'primitive') return ref.primitive === 'unknown';\n    if (ref.kind === 'array') return carriesUnknown(ref.items!);\n    if (ref.kind === 'openMap') return carriesUnknown(ref.values!);\n    return false;\n}\n\n/**\n * `void`, `unknown` and `any` all reach the model as the same primitive — the resolver maps the\n * three keywords onto one, because to a document they say the identical thing: nothing.\n */\n// webpieces-disable no-function-outside-class -- pure predicate over one TypeRef\nexport function isVoidLike(ref: TypeRef): boolean {\n    return ref.kind === 'primitive' && ref.primitive === 'unknown';\n}\n\n/**\n * Every reason this tool could not be served, in the order `McpToolRegistry` asks them at boot —\n * unique name, trigger kind, HTTP auth, MCP auth — and then the renderer's own verdict.\n *\n * The registry's four are restated from the model rather than driven, because they are decorator\n * PRESENCE facts the model already carries verbatim; the SCHEMA question is the one with a real\n * implementation behind it, and that one is driven.\n */\n// webpieces-disable no-function-outside-class, max-lines-new-methods -- pure judge over one endpoint, and the four boot checks read as one list\nexport function toolFailures(\n    endpoint: DocumentedEndpoint,\n    renderer: McpSchemaRenderer,\n    toolNames: Map<string, string>,\n    model: ApiDocModel,\n): readonly Verdict[] {\n    const found: Verdict[] = [];\n    const toolName = endpoint.mcpTool!.name;\n    const claimed = toolNames.get(toolName);\n    if (claimed === undefined) {\n        toolNames.set(toolName, `${model.contractName}.${endpoint.methodName}`);\n    } else {\n        found.push(\n            new Verdict(\n                `tool name '${toolName}' is already declared by ${claimed}`,\n                'Tool names are the protocol identity and are globally unique — rename one of the ' +\n                    'two @WpMcpTool declarations.',\n            ),\n        );\n    }\n    if (endpoint.kind !== RPC_KIND) {\n        found.push(\n            new Verdict(\n                `an MCP tool is declared on a '${endpoint.kind}' endpoint`,\n                'Only an RPC endpoint can be a tool — a cloudtasks, cron or external endpoint is ' +\n                    'driven by something other than a caller. Make it RPC, or drop the @WpMcpTool.',\n            ),\n        );\n    }\n    if (endpoint.auth === undefined) {\n        found.push(\n            new Verdict(\n                'an MCP tool declares no HTTP auth',\n                'Put a @WpAuth... decorator on the method. The MCP server refuses to boot without ' +\n                    'one, because a tool with no credential is an unauthenticated endpoint an ' +\n                    'agent can call.',\n            ),\n        );\n    }\n    if (endpoint.mcpAuthText === undefined) {\n        found.push(\n            new Verdict(\n                'an MCP tool does not declare @WpMcpAuthJwt(...)',\n                'Add @WpMcpAuthJwt(...) beside the HTTP auth. MCP authorization is rechecked ' +\n                    'before the endpoint boundary and is declared separately on purpose.',\n            ),\n        );\n    }\n    const rendered = renderFailure(renderer, endpoint);\n    if (rendered !== undefined) found.push(rendered);\n    return found;\n}\n\n/**\n * The renderer's own refusal for one tool, or undefined when it renders.\n *\n * This is the whole acceptance contract for the MCP half: \"passes the rule\" and \"renders a tool\" are\n * the SAME statement, because the rule asks the renderer. It covers the method's missing JSDoc,\n * every reachable DTO field's missing JSDoc, a request or response that is not a named object, a\n * root-level union, a recursive DTO, an `unknown` leaf and a malformed `@mcpHeader` — none of which\n * is restated here.\n *\n * One verdict per tool, because the renderer stops at the first thing it cannot draw. A tool blocked\n * by several undocumented fields is therefore fixed a round at a time, which is the price of having\n * exactly one definition of renderable rather than a second walk that could disagree with it.\n */\n// webpieces-disable no-function-outside-class -- pure judge beside toolFailures\nfunction renderFailure(\n    renderer: McpSchemaRenderer,\n    endpoint: DocumentedEndpoint,\n): Verdict | undefined {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- the render refusal IS the verdict\n    try {\n        renderer.tool(endpoint);\n        return undefined;\n    } catch (err: unknown) {\n        //const error = toError(err);\n        if (!(err instanceof McpRenderError)) throw err;\n        return new Verdict(`${err.message} — no MCP schema could be built`, err.cure);\n    }\n}\n\n/** Every `@ApiPath` class name declared at the top level of a file, in declaration order. */\n// webpieces-disable no-function-outside-class -- pure AST reader\nexport function contractNamesIn(source: ts.SourceFile): string[] {\n    const names: string[] = [];\n    for (const statement of source.statements) {\n        if (!ts.isClassDeclaration(statement) || statement.name === undefined) continue;\n        if (hasDecoratorNamed(statement, 'ApiPath')) names.push(statement.name.text);\n    }\n    return names;\n}\n\n/**\n * Where each method of one contract starts, and which of them carry `@WpMcpTool` without\n * `@Endpoint`.\n *\n * The line numbers exist because the MCP failures come from the RENDERER, whose location is a NAME\n * (`Order.window`) rather than a file offset — it publishes a schema, not a diagnostic. Anchoring\n * every tool failure at its METHOD is also where an author would write the disable: \"this tool is\n * deliberately not renderable\" is a decision about the method, not about a field three DTOs down.\n */\n// webpieces-disable no-function-outside-class -- pure AST reader beside contractNamesIn\nexport function contractLinesOf(source: ts.SourceFile, contractName: string): ContractLines {\n    for (const statement of source.statements) {\n        if (!ts.isClassDeclaration(statement) || statement.name?.text !== contractName) continue;\n        const byMethod = new Map<string, number>();\n        const orphanTools: string[] = [];\n        for (const member of statement.members) {\n            if (!ts.isMethodDeclaration(member) || !ts.isIdentifier(member.name)) continue;\n            byMethod.set(member.name.text, lineOf(source, member));\n            if (hasDecoratorNamed(member, 'WpMcpTool') && !hasDecoratorNamed(member, 'Endpoint')) {\n                orphanTools.push(member.name.text);\n            }\n        }\n        return new ContractLines(lineOf(source, statement), byMethod, orphanTools);\n    }\n    return new ContractLines(1, new Map<string, number>(), []);\n}\n\n/** 1-based line of a node's first token, decorators excluded. */\n// webpieces-disable no-function-outside-class -- pure AST reader\nfunction lineOf(source: ts.SourceFile, node: ts.Node): number {\n    return source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;\n}\n\n/** True when `node` carries `@name(...)`. Matched on the syntax, like every reader in this file. */\n// webpieces-disable no-function-outside-class -- pure AST reader\nfunction hasDecoratorNamed(node: ts.Node, name: string): boolean {\n    const decorators = ts.canHaveDecorators(node) ? (ts.getDecorators(node) ?? []) : [];\n    for (const decorator of decorators) {\n        const call = decorator.expression;\n        if (\n            ts.isCallExpression(call) &&\n            ts.isIdentifier(call.expression) &&\n            call.expression.text === name\n        ) {\n            return true;\n        }\n    }\n    return false;\n}\n"]}
+{"version":3,"file":"api-doc-rules-verdicts.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-usage/api-doc-rules-verdicts.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The pure VERDICTS the api-contract rules print, split out of `api-doc-rules-scan.ts`, which owns\n * the walk and is at its file-size limit.\n *\n * Nothing here touches the filesystem or the project graph. Each function answers one question about\n * ONE declaration the extractor or the renderer has already ruled on, and turns it into the two\n * halves every webpieces refusal carries — what is wrong, and what to do instead. The DECISION is\n * never made here: `model.unmapped` is the extractor's and a render failure is the renderer's. What\n * this file adds is the WORDING, which is the part a generic \"no model representation for this type\n * form\" cannot give an author.\n */\n\nimport * as ts from 'typescript';\nimport {\n    ApiDocModel,\n    ApiDocExtractor,\n    DocumentedEndpoint,\n    McpRenderError,\n    McpSchemaRenderer,\n    TypeRef,\n    UnmappedType,\n} from '@webpieces/api-doc-model';\nimport { EndpointKind } from './api-relations';\n\n/**\n * The one trigger kind an MCP tool may have. A LITERAL, for the same reason `EndpointKind` beside it\n * is one: this package deliberately does not depend on `@webpieces/core-util` at runtime, and the\n * set the literal belongs to is pinned by that type.\n */\nexport const RPC_KIND: EndpointKind = 'rpc';\n\n/**\n * The endpoint kinds whose response a caller WAITS FOR, and which therefore must name a DTO (#1017).\n *\n * `rpc` and `external` are both synchronous request/response: somebody posts and reads what comes\n * back, so there IS a body and it must be a named type that can gain a field later. `void` on either\n * is a one-way door — a `void` response can never grow without breaking every generated client, where\n * an empty DTO grows additively forever. #1016 refused it on `rpc` only, because `external` was\n * unstated at the time; it is stated now.\n *\n * `cloudtasks` and `cron` are deliberately NOT here: delivery is fire-and-forget, nobody waits for a\n * body, and `Promise<void>` is the CONTRACT rather than an omission.\n */\nexport const ANSWERING_KINDS: readonly EndpointKind[] = ['rpc', 'external'];\n\n/** The scalar keywords a MIXED SCALAR union is made of. */\nconst SCALAR_KEYWORDS = new Set<ts.SyntaxKind>([\n    ts.SyntaxKind.StringKeyword,\n    ts.SyntaxKind.NumberKeyword,\n    ts.SyntaxKind.BooleanKeyword,\n]);\n\n/** ONE reason a declaration is refused, in the two halves every refusal prints. */\nexport class Verdict {\n    constructor(\n        public readonly what: string,\n        public readonly cure: string,\n    ) {}\n}\n\n\n/** Method name -> the line its declaration starts on, for one contract class. */\nexport class ContractLines {\n    constructor(\n        public readonly classLine: number,\n        public readonly byMethod: ReadonlyMap<string, number>,\n        /** Methods carrying `@WpMcpTool` that do NOT also carry `@Endpoint`. */\n        public readonly toolsWithoutEndpoint: readonly string[],\n    ) {}\n\n    lineOf(methodName: string): number {\n        return this.byMethod.get(methodName) ?? this.classLine;\n    }\n}\n\n\n/**\n * The cure for an `unknown` value, for whichever rule is REPORTING it.\n *\n * It takes the rule name rather than naming one, because this defect is shared: it blocks the\n * OpenAPI document, so `DefectSink` routes it to `api-rules-for-openapi` when that rule is running\n * and to `api-rules-for-mcp` when it is the only one. A hard-coded rule name would then hand an\n * author, on the mcp-only configuration, a `// webpieces-disable api-rules-for-openapi` line that\n * the collector reading the site does not look for — a cure that does not cure, which is the one\n * failure mode a printed cure must not have.\n */\n// webpieces-disable no-function-outside-class -- pure message builder, beside the verdicts that print it\nexport function unknownValueCure(rule: string): string {\n    return (\n        'Name the value type — a DTO, an array of one, a string-literal union, or ' +\n        'Record<string, ThatDto>. If the shape really is unknowable (a transport envelope, ' +\n        'arbitrary SQL rows), write the per-site disable and say so: ' +\n        `// webpieces-disable ${rule} -- <why this field is published with no shape>. ` +\n        'An existing no-any-unknown disable does NOT count — that rule asked whether the code is ' +\n        'type-safe, which is a different question from whether a partner is handed a shapeless field.'\n    );\n}\n\n/** The one cure for a `void` endpoint that somebody is WAITING on (rpc or external). */\nexport const VOID_RPC_CURE =\n    'Declare a named response DTO and return Promise<That>, even when it has no fields today: an ' +\n    'empty object grows additively forever, and a void response cannot gain a field without ' +\n    'breaking every generated client. An external endpoint is a synchronous call an outside caller ' +\n    'waits on, so it has a body too — an empty one serializes as {} and the failure detail rides on ' +\n    'the thrown error. Promise<void> stays legal on a cloudtasks or cron endpoint, where ' +\n    'fire-and-forget is the contract.';\n\n/**\n * Why the resolver could not map this type, said in the author's vocabulary.\n *\n * The DECISION to refuse is the extractor's and is not second-guessed here — every entry in\n * `model.unmapped` becomes a defect. What this adds is the MESSAGE: an open enum and a mixed scalar\n * union are the two shapes a real repo actually hits (measured: 6 of 98 endpoints, from exactly\n * these two), and \"no model representation for this type form\" tells their author nothing.\n */\n// webpieces-disable no-function-outside-class -- pure classifier over the extractor's own verdict\nexport function classifyUnmapped(unmapped: UnmappedType): Verdict {\n    const branches = unionBranchesOf(unmapped.typeText);\n    if (isOpenEnum(branches)) {\n        return new Verdict(\n            `'${unmapped.typeText}' is an OPEN ENUM — literals unioned with the wide type`,\n            'Use an enum OR a string, not both. TypeScript COLLAPSES this union to the wide type, ' +\n                'so the literals buy no compile-time safety and a document cannot state them as a ' +\n                \"closed set. Either drop the `| string` (`'a' | 'b'` publishes as a real enum), or \" +\n                'drop the literals and list the known values in the JSDoc.',\n        );\n    }\n    if (isMixedScalarUnion(branches)) {\n        return new Verdict(\n            `'${unmapped.typeText}' is a MIXED SCALAR union`,\n            'Give the field ONE type. JSON Schema can spell {\"type\": [\"string\",\"number\"]}, but ' +\n                'this framework\\'s ApiJsonSchema helpers read a type array as \"one real type plus ' +\n                'maybe null\" (baseTypeOf returns the first non-null member), so publishing it ' +\n                'would VALIDATE WRONGLY — which is worse than refusing it. Pick the type, or wrap ' +\n                'the alternatives in a discriminated union of named objects.',\n        );\n    }\n    return new Verdict(\n        `'${unmapped.typeText}' has no shape a document can state — ${unmapped.reason}`,\n        'Give it a type a document can carry: a named DTO, an array of one, a string-literal ' +\n            'union, a Record<string, ThatDto>, or a primitive. A field with no shape publishes as ' +\n            '\"anything\".',\n    );\n}\n\n/** The branches of `typeText` when it parses as a union, else an empty list. */\n// webpieces-disable no-function-outside-class -- pure parser used by classifyUnmapped alone\nfunction unionBranchesOf(typeText: string): readonly ts.TypeNode[] {\n    const parsed = ts.createSourceFile(\n        '__unmapped.ts',\n        `type __X = ${typeText};`,\n        ts.ScriptTarget.Latest,\n        true,\n    );\n    const alias = parsed.statements[0];\n    if (alias === undefined || !ts.isTypeAliasDeclaration(alias)) return [];\n    if (!ts.isUnionTypeNode(alias.type)) return [];\n    return alias.type.types.filter((branch: ts.TypeNode) => !isNullishBranch(branch));\n}\n\n/** `'a' | 'b' | string`, and the numeric equivalent. See #1010 and the decision on #1011. */\n// webpieces-disable no-function-outside-class -- pure predicate beside classifyUnmapped\nfunction isOpenEnum(branches: readonly ts.TypeNode[]): boolean {\n    const wide = branches.some(\n        (branch: ts.TypeNode) =>\n            branch.kind === ts.SyntaxKind.StringKeyword ||\n            branch.kind === ts.SyntaxKind.NumberKeyword,\n    );\n    const literals = branches.some((branch: ts.TypeNode) => ts.isLiteralTypeNode(branch));\n    return wide && literals;\n}\n\n/** `string | number`, `string | boolean | null` — two or more DIFFERENT scalar keywords. */\n// webpieces-disable no-function-outside-class -- pure predicate beside classifyUnmapped\nfunction isMixedScalarUnion(branches: readonly ts.TypeNode[]): boolean {\n    if (branches.length < 2) return false;\n    const kinds = new Set<ts.SyntaxKind>();\n    for (const branch of branches) {\n        if (!SCALAR_KEYWORDS.has(branch.kind)) return false;\n        kinds.add(branch.kind);\n    }\n    return kinds.size >= 2;\n}\n\n/** `null` / `undefined` branches — nullability, not composition, exactly as the resolver reads it. */\n// webpieces-disable no-function-outside-class -- pure predicate beside classifyUnmapped\nfunction isNullishBranch(node: ts.TypeNode): boolean {\n    if (node.kind === ts.SyntaxKind.UndefinedKeyword || node.kind === ts.SyntaxKind.NullKeyword) {\n        return true;\n    }\n    return ts.isLiteralTypeNode(node) && node.literal.kind === ts.SyntaxKind.NullKeyword;\n}\n\n/**\n * True when this type PUBLISHES an `unknown` value.\n *\n * It looks at the VALUE TYPE wherever it sits — the item of an array, the value of an open map, the\n * field itself — and never at the `Record<>` spelling, because the real cases in the wild are not\n * all Records: `params?: unknown[]` is the same defect written differently.\n *\n * It does NOT descend through a `ref`: a named DTO is its own entry in the model and its own fields\n * are judged there, so descending would report the same field once per type that points at it.\n */\n// webpieces-disable no-function-outside-class -- pure predicate over one TypeRef\nexport function carriesUnknown(ref: TypeRef): boolean {\n    if (ref.kind === 'primitive') return ref.primitive === 'unknown';\n    if (ref.kind === 'array') return carriesUnknown(ref.items!);\n    if (ref.kind === 'openMap') return carriesUnknown(ref.values!);\n    return false;\n}\n\n/**\n * `void`, `unknown` and `any` all reach the model as the same primitive — the resolver maps the\n * three keywords onto one, because to a document they say the identical thing: nothing.\n */\n// webpieces-disable no-function-outside-class -- pure predicate over one TypeRef\nexport function isVoidLike(ref: TypeRef): boolean {\n    return ref.kind === 'primitive' && ref.primitive === 'unknown';\n}\n\n/**\n * Every reason this tool could not be served, in the order `McpToolRegistry` asks them at boot —\n * unique name, trigger kind, HTTP auth, MCP auth — and then the renderer's own verdict.\n *\n * The registry's four are restated from the model rather than driven, because they are decorator\n * PRESENCE facts the model already carries verbatim; the SCHEMA question is the one with a real\n * implementation behind it, and that one is driven.\n */\n// webpieces-disable no-function-outside-class, max-lines-new-methods -- pure judge over one endpoint, and the four boot checks read as one list\nexport function toolFailures(\n    endpoint: DocumentedEndpoint,\n    renderer: McpSchemaRenderer,\n    toolNames: Map<string, string>,\n    model: ApiDocModel,\n): readonly Verdict[] {\n    const found: Verdict[] = [];\n    const toolName = endpoint.mcpTool!.name;\n    const claimed = toolNames.get(toolName);\n    if (claimed === undefined) {\n        toolNames.set(toolName, `${model.contractName}.${endpoint.methodName}`);\n    } else {\n        found.push(\n            new Verdict(\n                `tool name '${toolName}' is already declared by ${claimed}`,\n                'Tool names are the protocol identity and are globally unique — rename one of the ' +\n                    'two @WpMcpTool declarations.',\n            ),\n        );\n    }\n    if (endpoint.kind !== RPC_KIND) {\n        found.push(\n            new Verdict(\n                `an MCP tool is declared on a '${endpoint.kind}' endpoint`,\n                'Only an RPC endpoint can be a tool — a cloudtasks, cron or external endpoint is ' +\n                    'driven by something other than a caller. Make it RPC, or drop the @WpMcpTool.',\n            ),\n        );\n    }\n    if (endpoint.auth === undefined) {\n        found.push(\n            new Verdict(\n                'an MCP tool declares no HTTP auth',\n                'Put a @WpAuth... decorator on the method. The MCP server refuses to boot without ' +\n                    'one, because a tool with no credential is an unauthenticated endpoint an ' +\n                    'agent can call.',\n            ),\n        );\n    }\n    if (endpoint.authorizationText === undefined) {\n        found.push(\n            new Verdict(\n                'an MCP tool does not declare @WpAuthorization(...)',\n                'Add @WpAuthorization(...) beside @WpAuth. Common operation authorization is rechecked ' +\n                    'before tool/schema lookup and at the receiving endpoint.',\n            ),\n        );\n    }\n    const rendered = renderFailure(renderer, endpoint);\n    if (rendered !== undefined) found.push(rendered);\n    return found;\n}\n\n/**\n * The renderer's own refusal for one tool, or undefined when it renders.\n *\n * This is the whole acceptance contract for the MCP half: \"passes the rule\" and \"renders a tool\" are\n * the SAME statement, because the rule asks the renderer. It covers the method's missing JSDoc,\n * every reachable DTO field's missing JSDoc, a request or response that is not a named object, a\n * root-level union, a recursive DTO, an `unknown` leaf and a malformed `@mcpHeader` — none of which\n * is restated here.\n *\n * One verdict per tool, because the renderer stops at the first thing it cannot draw. A tool blocked\n * by several undocumented fields is therefore fixed a round at a time, which is the price of having\n * exactly one definition of renderable rather than a second walk that could disagree with it.\n */\n// webpieces-disable no-function-outside-class -- pure judge beside toolFailures\nfunction renderFailure(\n    renderer: McpSchemaRenderer,\n    endpoint: DocumentedEndpoint,\n): Verdict | undefined {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- the render refusal IS the verdict\n    try {\n        renderer.tool(endpoint);\n        return undefined;\n    } catch (err: unknown) {\n        //const error = toError(err);\n        if (!(err instanceof McpRenderError)) throw err;\n        return new Verdict(`${err.message} — no MCP schema could be built`, err.cure);\n    }\n}\n\n/** Every `@ApiPath` class name declared at the top level of a file, in declaration order. */\n// webpieces-disable no-function-outside-class -- pure AST reader\nexport function contractNamesIn(source: ts.SourceFile): string[] {\n    const names: string[] = [];\n    for (const statement of source.statements) {\n        if (!ts.isClassDeclaration(statement) || statement.name === undefined) continue;\n        if (hasDecoratorNamed(statement, 'ApiPath')) names.push(statement.name.text);\n    }\n    return names;\n}\n\n/**\n * Where each method of one contract starts, and which of them carry `@WpMcpTool` without\n * `@Endpoint`.\n *\n * The line numbers exist because the MCP failures come from the RENDERER, whose location is a NAME\n * (`Order.window`) rather than a file offset — it publishes a schema, not a diagnostic. Anchoring\n * every tool failure at its METHOD is also where an author would write the disable: \"this tool is\n * deliberately not renderable\" is a decision about the method, not about a field three DTOs down.\n */\n// webpieces-disable no-function-outside-class -- pure AST reader beside contractNamesIn\nexport function contractLinesOf(source: ts.SourceFile, contractName: string): ContractLines {\n    for (const statement of source.statements) {\n        if (!ts.isClassDeclaration(statement) || statement.name?.text !== contractName) continue;\n        const byMethod = new Map<string, number>();\n        const orphanTools: string[] = [];\n        for (const member of statement.members) {\n            if (!ts.isMethodDeclaration(member) || !ts.isIdentifier(member.name)) continue;\n            byMethod.set(member.name.text, lineOf(source, member));\n            if (hasDecoratorNamed(member, 'WpMcpTool') && !hasDecoratorNamed(member, 'Endpoint')) {\n                orphanTools.push(member.name.text);\n            }\n        }\n        return new ContractLines(lineOf(source, statement), byMethod, orphanTools);\n    }\n    return new ContractLines(1, new Map<string, number>(), []);\n}\n\n/** 1-based line of a node's first token, decorators excluded. */\n// webpieces-disable no-function-outside-class -- pure AST reader\nfunction lineOf(source: ts.SourceFile, node: ts.Node): number {\n    return source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;\n}\n\n/** Match canonical imports, including aliases and namespace calls. */\n// webpieces-disable no-function-outside-class -- pure AST reader\nfunction hasDecoratorNamed(node: ts.Node, name: string): boolean {\n    const decorators = ts.canHaveDecorators(node) ? (ts.getDecorators(node) ?? []) : [];\n    for (const decorator of decorators) {\n        const call = decorator.expression;\n        if (\n            ts.isCallExpression(call) &&\n            ApiDocExtractor.canonicalCallName(call.expression) === name\n        ) {\n            return true;\n        }\n    }\n    return false;\n}\n"]}

package/src/lib/runtime-wiring/canonical-clients.d.ts

@@ -0,0 +1,19 @@
+import * as ts from 'typescript';
+import type { ProjectInfo } from '../project-info';
+/** ALL-CODE grammar check: no git diff, line exemptions, or wiring.ts carve-out. */
+export declare class CanonicalClientBindings {
+    private readonly checker;
+    constructor(checker: ts.TypeChecker);
+    problems(file: ts.SourceFile): string[];
+    assert(problems: readonly string[]): void;
+    private checkFactory;
+    private singleton;
+    private property;
+    private method;
+    private expand;
+}
+/** Architecture validation scans every participating owner, even when its build isn't affected. */
+export declare class WorkspaceClientBindings {
+    private program;
+    assert(workspaceRoot: string, infos: ReadonlyMap<string, ProjectInfo>): void;
+}

package/src/lib/runtime-wiring/canonical-clients.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkspaceClientBindings = exports.CanonicalClientBindings = void 0;
+const tslib_1 = require("tslib");
+const path = tslib_1.__importStar(require("path"));
+const ts = tslib_1.__importStar(require("typescript"));
+const rules_config_1 = require("@webpieces/rules-config");
+const program_1 = require("../di-graph/program");
+/** ALL-CODE grammar check: no git diff, line exemptions, or wiring.ts carve-out. */
+class CanonicalClientBindings {
+    checker;
+    constructor(checker) {
+        this.checker = checker;
+    }
+    problems(file) {
+        const problems = [];
+        const visit = (node) => {
+            if (ts.isCallExpression(node) && this.method(node.expression) === 'toDynamicValue') {
+                const bind = this.expand(node.expression);
+                const receiver = ts.isPropertyAccessExpression(bind) || ts.isElementAccessExpression(bind)
+                    ? this.expand(bind.expression)
+                    : undefined;
+                if (receiver !== undefined &&
+                    ts.isCallExpression(receiver) &&
+                    this.method(receiver.expression) === 'bind' &&
+                    this.singleton(node)) {
+                    this.checkFactory(node.arguments[0], receiver.arguments[0], false, file, problems);
+                }
+            }
+            if (ts.isObjectLiteralExpression(node)) {
+                const token = this.property(node, 'provide');
+                const factory = this.property(node, 'useFactory');
+                if (token !== undefined && factory !== undefined)
+                    this.checkFactory(factory, token, true, file, problems);
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(file);
+        return problems;
+    }
+    assert(problems) {
+        if (problems.length === 0)
+            return;
+        throw new rules_config_1.RuleFailError('validate-runtime-architecture', problems.join('\n'), undefined, undefined, [
+            new rules_config_1.Option('Replace every supported hand-written registration, including unchanged code in src/wiring.ts. Use RuntimeClients.bindRpc with rpcTarget; RuntimeTaskClients.bindPubSub for task clients; provideRpcClient for browser providers. Preserve tokens, filters and lazy singleton resolution.', true),
+        ]);
+    }
+    checkFactory(factory, token, browser, file, problems) {
+        if (factory === undefined || token === undefined)
+            return;
+        const value = this.expand(factory);
+        if (!ts.isArrowFunction(value) && !ts.isFunctionExpression(value))
+            return;
+        const result = ts.isBlock(value.body) &&
+            value.body.statements.length === 1 &&
+            ts.isReturnStatement(value.body.statements[0])
+            ? value.body.statements[0].expression
+            : ts.isBlock(value.body)
+                ? undefined
+                : value.body;
+        if (result === undefined)
+            return; // Side effects/custom adapters have no helper equivalent.
+        const call = this.expand(result);
+        if (!ts.isCallExpression(call))
+            return;
+        const declaration = this.checker.getResolvedSignature(call)?.declaration;
+        const owner = declaration?.parent;
+        if (owner === undefined || !ts.isClassDeclaration(owner))
+            return;
+        const name = owner.name?.text;
+        const method = this.method(call.expression);
+        const rpc = name === 'ClientHttpFactory' && method === 'createRpcClient' && !browser;
+        const task = name === 'ClientCloudTasksFactory' && method === 'createPubSubClient' && !browser;
+        const provider = name === 'ClientHttpBrowserFactory' && method === 'createRpcClient' && browser;
+        if (!rpc && !task && !provider)
+            return;
+        if (call.arguments.length < 2 || call.arguments.length > (rpc ? 3 : 2))
+            return;
+        const config = this.expand(call.arguments[1]);
+        if (!ts.isNewExpression(config) ||
+            this.method(config.expression) !== (task ? 'TaskClientConfig' : 'ClientConfig') ||
+            config.arguments?.length !== 1)
+            return; // Custom config options aren't supported by helpers.
+        const api = call.arguments[0].getText();
+        const target = config.arguments[0].getText();
+        const filters = call.arguments[2] === undefined ? '' : `, ${call.arguments[2].getText()}`;
+        const replacement = task
+            ? `new RuntimeTaskClients(options).bindPubSub(${token.getText()}, ${api}, ${target});`
+            : provider
+                ? `provideRpcClient(${token.getText()}, ${api}, rpcTarget(${api}, ${target}))`
+                : `new RuntimeClients(options).bindRpc(${token.getText()}, ${api}, rpcTarget(${api}, ${target})${filters});`;
+        const location = file.getLineAndCharacterOfPosition(factory.getStart(file));
+        problems.push(`${file.fileName}:${location.line + 1}:${location.character + 1}: canonical client registration required: ${replacement}`);
+    }
+    singleton(call) {
+        let node = call;
+        while (node.parent !== undefined &&
+            (ts.isPropertyAccessExpression(node.parent) ||
+                ts.isElementAccessExpression(node.parent) ||
+                ts.isCallExpression(node.parent))) {
+            node = node.parent;
+            if (ts.isCallExpression(node) && this.method(node.expression) === 'inSingletonScope')
+                return true;
+        }
+        return false;
+    }
+    property(node, name) {
+        for (const property of node.properties) {
+            if (ts.isPropertyAssignment(property) &&
+                (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) &&
+                property.name.text === name)
+                return property.initializer;
+            if (ts.isShorthandPropertyAssignment(property) && property.name.text === name)
+                return property.name;
+        }
+        return undefined;
+    }
+    method(expression) {
+        const value = this.expand(expression);
+        if (ts.isPropertyAccessExpression(value))
+            return value.name.text;
+        if (ts.isElementAccessExpression(value) && ts.isStringLiteralLike(value.argumentExpression))
+            return value.argumentExpression.text;
+        const symbol = this.checker.getSymbolAtLocation(value);
+        return symbol !== undefined && (symbol.flags & ts.SymbolFlags.Alias) !== 0
+            ? this.checker.getAliasedSymbol(symbol).getName()
+            : (symbol?.getName() ?? value.getText());
+    }
+    expand(expression, seen = new Set()) {
+        if (seen.has(expression))
+            return expression;
+        seen.add(expression);
+        if (ts.isParenthesizedExpression(expression) ||
+            ts.isAsExpression(expression) ||
+            ts.isNonNullExpression(expression) ||
+            ts.isSatisfiesExpression(expression))
+            return this.expand(expression.expression, seen);
+        const declaration = this.checker.getSymbolAtLocation(expression)?.valueDeclaration;
+        if (declaration !== undefined &&
+            ts.isVariableDeclaration(declaration) &&
+            declaration.initializer !== undefined)
+            return this.expand(declaration.initializer, seen);
+        return expression;
+    }
+}
+exports.CanonicalClientBindings = CanonicalClientBindings;
+/** Architecture validation scans every participating owner, even when its build isn't affected. */
+class WorkspaceClientBindings {
+    program(root) {
+        const configured = (0, program_1.createProjectProgram)(root);
+        const files = ts.sys.readDirectory(path.join(root, 'src'), ['.ts', '.tsx'], ['**/*.spec.ts', '**/*.test.ts', '**/__tests__/**', '**/node_modules/**']);
+        return ts.createProgram(files, configured?.getCompilerOptions() ?? {});
+    }
+    assert(workspaceRoot, infos) {
+        const problems = [];
+        for (const info of infos.values()) {
+            if (!info.tags.some((tag) => tag === 'webpieces' || tag === 'webpieces-lib'))
+                continue;
+            const program = this.program(path.resolve(workspaceRoot, info.root));
+            const check = new CanonicalClientBindings(program.getTypeChecker());
+            const root = path.resolve(workspaceRoot, info.root) + path.sep;
+            for (const file of program.getSourceFiles()) {
+                if (file.isDeclarationFile ||
+                    !file.fileName.startsWith(root) ||
+                    /(?:\.spec\.|\.test\.|\/__tests__\/|\/node_modules\/)/.test(file.fileName))
+                    continue;
+                problems.push(...check.problems(file));
+            }
+        }
+        // No source program is needed to render a structured aggregate failure.
+        if (problems.length > 0)
+            throw new rules_config_1.RuleFailError('validate-runtime-architecture', problems.join('\n'), undefined, undefined, [
+                new rules_config_1.Option('Migrate all reported registrations using the canonical helpers and rpcTarget, preserving tokens and filters. This checks ALL CODE in every participating runtime owner, irrespective of the current diff.', true),
+            ]);
+    }
+}
+exports.WorkspaceClientBindings = WorkspaceClientBindings;
+//# sourceMappingURL=canonical-clients.js.map

package/src/lib/runtime-wiring/canonical-clients.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-clients.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-wiring/canonical-clients.ts"],"names":[],"mappings":"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","sourcesContent":["import * as path from 'path';\nimport * as ts from 'typescript';\nimport { Option, RuleFailError } from '@webpieces/rules-config';\nimport type { ProjectInfo } from '../project-info';\nimport { createProjectProgram } from '../di-graph/program';\n\n/** ALL-CODE grammar check: no git diff, line exemptions, or wiring.ts carve-out. */\nexport class CanonicalClientBindings {\n    constructor(private readonly checker: ts.TypeChecker) {}\n\n    problems(file: ts.SourceFile): string[] {\n        const problems: string[] = [];\n        const visit = (node: ts.Node): void => {\n            if (ts.isCallExpression(node) && this.method(node.expression) === 'toDynamicValue') {\n                const bind = this.expand(node.expression);\n                const receiver =\n                    ts.isPropertyAccessExpression(bind) || ts.isElementAccessExpression(bind)\n                        ? this.expand(bind.expression)\n                        : undefined;\n                if (\n                    receiver !== undefined &&\n                    ts.isCallExpression(receiver) &&\n                    this.method(receiver.expression) === 'bind' &&\n                    this.singleton(node)\n                ) {\n                    this.checkFactory(\n                        node.arguments[0],\n                        receiver.arguments[0],\n                        false,\n                        file,\n                        problems,\n                    );\n                }\n            }\n            if (ts.isObjectLiteralExpression(node)) {\n                const token = this.property(node, 'provide');\n                const factory = this.property(node, 'useFactory');\n                if (token !== undefined && factory !== undefined)\n                    this.checkFactory(factory, token, true, file, problems);\n            }\n            ts.forEachChild(node, visit);\n        };\n        visit(file);\n        return problems;\n    }\n\n    assert(problems: readonly string[]): void {\n        if (problems.length === 0) return;\n        throw new RuleFailError(\n            'validate-runtime-architecture',\n            problems.join('\\n'),\n            undefined,\n            undefined,\n            [\n                new Option(\n                    'Replace every supported hand-written registration, including unchanged code in src/wiring.ts. Use RuntimeClients.bindRpc with rpcTarget; RuntimeTaskClients.bindPubSub for task clients; provideRpcClient for browser providers. Preserve tokens, filters and lazy singleton resolution.',\n                    true,\n                ),\n            ],\n        );\n    }\n\n    private checkFactory(\n        factory: ts.Expression | undefined,\n        token: ts.Expression | undefined,\n        browser: boolean,\n        file: ts.SourceFile,\n        problems: string[],\n    ): void {\n        if (factory === undefined || token === undefined) return;\n        const value = this.expand(factory);\n        if (!ts.isArrowFunction(value) && !ts.isFunctionExpression(value)) return;\n        const result =\n            ts.isBlock(value.body) &&\n            value.body.statements.length === 1 &&\n            ts.isReturnStatement(value.body.statements[0])\n                ? value.body.statements[0].expression\n                : ts.isBlock(value.body)\n                  ? undefined\n                  : value.body;\n        if (result === undefined) return; // Side effects/custom adapters have no helper equivalent.\n        const call = this.expand(result);\n        if (!ts.isCallExpression(call)) return;\n        const declaration = this.checker.getResolvedSignature(call)?.declaration;\n        const owner = declaration?.parent;\n        if (owner === undefined || !ts.isClassDeclaration(owner)) return;\n        const name = owner.name?.text;\n        const method = this.method(call.expression);\n        const rpc = name === 'ClientHttpFactory' && method === 'createRpcClient' && !browser;\n        const task =\n            name === 'ClientCloudTasksFactory' && method === 'createPubSubClient' && !browser;\n        const provider =\n            name === 'ClientHttpBrowserFactory' && method === 'createRpcClient' && browser;\n        if (!rpc && !task && !provider) return;\n        if (call.arguments.length < 2 || call.arguments.length > (rpc ? 3 : 2)) return;\n        const config = this.expand(call.arguments[1]);\n        if (\n            !ts.isNewExpression(config) ||\n            this.method(config.expression) !== (task ? 'TaskClientConfig' : 'ClientConfig') ||\n            config.arguments?.length !== 1\n        )\n            return; // Custom config options aren't supported by helpers.\n        const api = call.arguments[0].getText();\n        const target = config.arguments[0].getText();\n        const filters = call.arguments[2] === undefined ? '' : `, ${call.arguments[2].getText()}`;\n        const replacement = task\n            ? `new RuntimeTaskClients(options).bindPubSub(${token.getText()}, ${api}, ${target});`\n            : provider\n              ? `provideRpcClient(${token.getText()}, ${api}, rpcTarget(${api}, ${target}))`\n              : `new RuntimeClients(options).bindRpc(${token.getText()}, ${api}, rpcTarget(${api}, ${target})${filters});`;\n        const location = file.getLineAndCharacterOfPosition(factory.getStart(file));\n        problems.push(\n            `${file.fileName}:${location.line + 1}:${location.character + 1}: canonical client registration required: ${replacement}`,\n        );\n    }\n\n    private singleton(call: ts.CallExpression): boolean {\n        let node: ts.Node = call;\n        while (\n            node.parent !== undefined &&\n            (ts.isPropertyAccessExpression(node.parent) ||\n                ts.isElementAccessExpression(node.parent) ||\n                ts.isCallExpression(node.parent))\n        ) {\n            node = node.parent;\n            if (ts.isCallExpression(node) && this.method(node.expression) === 'inSingletonScope')\n                return true;\n        }\n        return false;\n    }\n\n    private property(node: ts.ObjectLiteralExpression, name: string): ts.Expression | undefined {\n        for (const property of node.properties) {\n            if (\n                ts.isPropertyAssignment(property) &&\n                (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) &&\n                property.name.text === name\n            )\n                return property.initializer;\n            if (ts.isShorthandPropertyAssignment(property) && property.name.text === name)\n                return property.name;\n        }\n        return undefined;\n    }\n\n    private method(expression: ts.Expression): string {\n        const value = this.expand(expression);\n        if (ts.isPropertyAccessExpression(value)) return value.name.text;\n        if (ts.isElementAccessExpression(value) && ts.isStringLiteralLike(value.argumentExpression))\n            return value.argumentExpression.text;\n        const symbol = this.checker.getSymbolAtLocation(value);\n        return symbol !== undefined && (symbol.flags & ts.SymbolFlags.Alias) !== 0\n            ? this.checker.getAliasedSymbol(symbol).getName()\n            : (symbol?.getName() ?? value.getText());\n    }\n\n    private expand(expression: ts.Expression, seen: Set<ts.Node> = new Set()): ts.Expression {\n        if (seen.has(expression)) return expression;\n        seen.add(expression);\n        if (\n            ts.isParenthesizedExpression(expression) ||\n            ts.isAsExpression(expression) ||\n            ts.isNonNullExpression(expression) ||\n            ts.isSatisfiesExpression(expression)\n        )\n            return this.expand(expression.expression, seen);\n        const declaration = this.checker.getSymbolAtLocation(expression)?.valueDeclaration;\n        if (\n            declaration !== undefined &&\n            ts.isVariableDeclaration(declaration) &&\n            declaration.initializer !== undefined\n        )\n            return this.expand(declaration.initializer, seen);\n        return expression;\n    }\n}\n\n/** Architecture validation scans every participating owner, even when its build isn't affected. */\nexport class WorkspaceClientBindings {\n    private program(root: string): ts.Program {\n        const configured = createProjectProgram(root);\n        const files = ts.sys.readDirectory(\n            path.join(root, 'src'),\n            ['.ts', '.tsx'],\n            ['**/*.spec.ts', '**/*.test.ts', '**/__tests__/**', '**/node_modules/**'],\n        );\n        return ts.createProgram(files, configured?.getCompilerOptions() ?? {});\n    }\n\n    assert(workspaceRoot: string, infos: ReadonlyMap<string, ProjectInfo>): void {\n        const problems: string[] = [];\n        for (const info of infos.values()) {\n            if (!info.tags.some((tag) => tag === 'webpieces' || tag === 'webpieces-lib')) continue;\n            const program = this.program(path.resolve(workspaceRoot, info.root));\n            const check = new CanonicalClientBindings(program.getTypeChecker());\n            const root = path.resolve(workspaceRoot, info.root) + path.sep;\n            for (const file of program.getSourceFiles()) {\n                if (\n                    file.isDeclarationFile ||\n                    !file.fileName.startsWith(root) ||\n                    /(?:\\.spec\\.|\\.test\\.|\\/__tests__\\/|\\/node_modules\\/)/.test(file.fileName)\n                )\n                    continue;\n                problems.push(...check.problems(file));\n            }\n        }\n        // No source program is needed to render a structured aggregate failure.\n        if (problems.length > 0)\n            throw new RuleFailError(\n                'validate-runtime-architecture',\n                problems.join('\\n'),\n                undefined,\n                undefined,\n                [\n                    new Option(\n                        'Migrate all reported registrations using the canonical helpers and rpcTarget, preserving tokens and filters. This checks ALL CODE in every participating runtime owner, irrespective of the current diff.',\n                        true,\n                    ),\n                ],\n            );\n    }\n}\n"]}

package/src/lib/runtime-wiring/source-extractor.js

@@ -8,6 +8,7 @@ const rules_config_1 = require("@webpieces/rules-config");
 const program_1 = require("../di-graph/program");
 const declaration_1 = require("./declaration");
 const source_values_1 = require("./source-values");
+const canonical_clients_1 = require("./canonical-clients");
 /** Build-only extraction. It never imports application modules or invokes their constructors. */
 class WiringSourceExtractor {
     workspaceRoot;
@@ -26,6 +27,14 @@ class WiringSourceExtractor {
         this.values = new source_values_1.WiringSourceValues(workspaceRoot, infos, program.getTypeChecker());
     }
     extract() {
+        const clients = new canonical_clients_1.CanonicalClientBindings(this.program.getTypeChecker());
+        const problems = this.program
+            .getSourceFiles()
+            .filter((file) => !file.isDeclarationFile &&
+            this.owns(file.fileName) &&
+            !/(?:\.spec\.|\.test\.|\/__tests__\/)/.test(file.fileName))
+            .flatMap((file) => clients.problems(file));
+        clients.assert(problems);
         const wiringPath = path.resolve(this.workspaceRoot, this.info.root, 'src/wiring.ts');
         const wiring = this.program.getSourceFile(wiringPath);
         if (wiring === undefined)
@@ -228,7 +237,7 @@ class WiringSourceExtractor {
     }
     fail(message) {
         throw new rules_config_1.RuleFailError('validate-runtime-architecture', message, undefined, undefined, [
-            new rules_config_1.Option('Move topology into canonical src/wiring.ts and use the documented static plan grammar; do not execute configuration to extract it.', true),
+            new rules_config_1.Option('Move topology into canonical src/wiring.ts using RuntimeClients.bindRpc(token, Api, rpcTarget(Api, deployment)), RuntimeTaskClients.bindPubSub, or provideRpcClient for supported registrations, and use the documented static plan grammar; do not execute configuration to extract it.', true),
         ]);
     }
 }

package/src/lib/runtime-wiring/source-extractor.js.map

@@ -1 +1 @@
-{"version":3,"file":"source-extractor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-wiring/source-extractor.ts"],"names":[],"mappings":"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","sourcesContent":["import * as path from 'path';\nimport * as ts from 'typescript';\nimport { Option, RuleFailError } from '@webpieces/rules-config';\nimport type { ProjectInfo } from '../project-info';\nimport { createProjectProgram } from '../di-graph/program';\nimport {\n    ContractIdentity,\n    ImplementsFacts,\n    UsesFacts,\n    RuntimeDeclaration,\n    WiringExport,\n    WiringRelationship,\n    WiringSelection,\n} from './declaration';\nimport { WiringSourceValues } from './source-values';\n\n/** Build-only extraction. It never imports application modules or invokes their constructors. */\nexport class WiringSourceExtractor {\n    private readonly values: WiringSourceValues;\n    private readonly exported: Record<string, WiringExport> = {};\n    private entry: string | undefined;\n    private host: string | undefined;\n\n    constructor(\n        private readonly workspaceRoot: string,\n        private readonly info: ProjectInfo,\n        private readonly infos: ReadonlyMap<string, ProjectInfo>,\n        private readonly program: ts.Program,\n    ) {\n        this.values = new WiringSourceValues(workspaceRoot, infos, program.getTypeChecker());\n    }\n\n    extract(): RuntimeDeclaration {\n        const wiringPath = path.resolve(this.workspaceRoot, this.info.root, 'src/wiring.ts');\n        const wiring = this.program.getSourceFile(wiringPath);\n        if (wiring === undefined) this.fail(`Missing canonical ${wiringPath}.`);\n        for (const file of this.program.getSourceFiles()) {\n            if (\n                file.isDeclarationFile ||\n                !this.owns(file.fileName) ||\n                /(?:\\.spec\\.|\\.test\\.|\\/__tests__\\/)/.test(file.fileName)\n            )\n                continue;\n            this.visit(file, file.fileName === wiringPath);\n        }\n        const framework = this.info.tags.includes('framework:angular')\n            ? 'angular'\n            : this.info.tags.some((tag) => tag === 'framework:node' || tag === 'framework:express')\n              ? 'node'\n              : 'browser';\n        if (this.info.tags.includes('webpieces') && this.entry === undefined)\n            this.fail(`${this.info.name} requires getRuntimeWiring() returning a typed plan.`);\n        return new RuntimeDeclaration(\n            this.info.name,\n            framework,\n            this.exported,\n            this.entry,\n            this.host,\n        );\n    }\n\n    private visit(node: ts.Node, inWiring: boolean): void {\n        if (\n            !inWiring &&\n            (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) &&\n            [\n                'addRoutes',\n                'createRpcClient',\n                'createPubSubClient',\n                'bindRpc',\n                'bindPubSub',\n            ].includes(this.values.symbolName(node))\n        )\n            this.fail(\n                `${node.getSourceFile().fileName}: topology method references belong in src/wiring.ts, including aliases.`,\n            );\n        if (\n            inWiring &&\n            ts.isNewExpression(node) &&\n            this.values.symbolName(node.expression) === 'ExternalContractUse'\n        )\n            this.recordExternal(node);\n        if (ts.isCallExpression(node)) {\n            const name = this.values.symbolName(node.expression);\n            if (\n                [\n                    'addRoutes',\n                    'createRpcClient',\n                    'createPubSubClient',\n                    'bindRpc',\n                    'bindPubSub',\n                    'provideRpcClient',\n                ].includes(name)\n            ) {\n                if (!inWiring)\n                    this.fail(\n                        `${node.getSourceFile().fileName}: ${name} must be owned by src/wiring.ts.`,\n                    );\n                this.recordRelationship(node, name);\n            }\n        }\n        if (inWiring && ts.isMethodDeclaration(node) && node.name.getText() === 'getRuntimeWiring')\n            this.recordPlan(node);\n        ts.forEachChild(node, (child) => this.visit(child, inWiring));\n    }\n\n    private recordExternal(expression: ts.NewExpression): void {\n        const owner = this.exportOwner(expression);\n        const identity = expression.arguments?.[0];\n        if (owner === undefined || identity === undefined || !ts.isStringLiteralLike(identity))\n            this.fail(\n                'ExternalContractUse belongs to a selected exported module and requires a literal project#contract identity.',\n            );\n        const qualified = (identity as ts.StringLiteralLike).text.split('#');\n        const project = qualified[0];\n        const exportedName = qualified[1];\n        const extra = qualified[2];\n        if (!project || !exportedName || extra !== undefined)\n            this.fail('ExternalContractUse requires one qualified project#contract identity.');\n        if (!this.values.hasExternalConsumer(this.info.name, project, exportedName, this.program))\n            this.fail(\n                `${project}#${exportedName} has no production business consumer in ${this.info.name}; adapters and test doubles do not establish uses.`,\n            );\n        const exported = this.exported[owner!] ?? new WiringExport('binding', [], []);\n        exported.relationships.push(\n            new WiringRelationship(\n                new ContractIdentity(project, exportedName),\n                new UsesFacts('external', {\n                    kind: 'unknown',\n                    reason: 'Vendor interface; destination classified by approved contract metadata',\n                }),\n            ),\n        );\n        this.exported[owner!] = exported;\n    }\n\n    private recordRelationship(call: ts.CallExpression, method: string): void {\n        const owner = this.exportOwner(call);\n        // The generic Angular integration adapter defines the primitive; its invocations own facts.\n        if (owner === 'provideRpcClient' && method === 'createRpcClient') return;\n        if (owner === undefined)\n            this.fail(`Unowned ${method} at ${call.getSourceFile().fileName}:${call.getStart()}.`);\n        const apiIndex =\n            method === 'bindRpc' || method === 'bindPubSub' || method === 'provideRpcClient'\n                ? 1\n                : 0;\n        const api = call.arguments[apiIndex];\n        if (api === undefined) this.fail(`${method} requires an explicit API contract.`);\n        const contract = this.values.identity(api!);\n        const direction = method === 'addRoutes' ? 'implements' : 'uses';\n        const contractTransport = this.values.transport(api!);\n        const transport =\n            method === 'addRoutes'\n                ? contractTransport\n                : method === 'bindPubSub' || method === 'createPubSubClient'\n                  ? 'pubsub'\n                  : 'rpc';\n        if (transport !== contractTransport)\n            this.fail(\n                `${method} transport disagrees with ${contract.project}#${contract.exportedName}.`,\n            );\n        const target =\n            direction === 'implements'\n                ? undefined\n                : this.values.target(call.arguments[apiIndex + 1]);\n        const kind =\n            direction === 'implements'\n                ? 'routing'\n                : method === 'provideRpcClient'\n                  ? 'providers'\n                  : 'binding';\n        const exported = this.exported[owner!] ?? new WiringExport(kind, [], []);\n        exported.relationships.push(\n            new WiringRelationship(\n                contract,\n                direction === 'implements'\n                    ? new ImplementsFacts(transport, this.values.condition(call))\n                    : new UsesFacts(transport, target!, this.values.condition(call)),\n            ),\n        );\n        this.exported[owner!] = exported;\n    }\n\n    private recordPlan(method: ts.MethodDeclaration): void {\n        const owner = this.exportOwner(method);\n        if (owner === undefined) this.fail('The plan class must be exported from src/wiring.ts.');\n        const returns = this.planReturns(method, owner!);\n        const expression = returns[0].expression as ts.NewExpression;\n        const name = this.values.symbolName(expression.expression);\n        const args = expression.arguments ?? [];\n        let arrays: readonly ts.Expression[];\n        if (name === 'ServerWiring') {\n            const host = this.values.target(args[0]);\n            if (host.kind !== 'service')\n                this.fail('ServerWiring requires a literal host identity.');\n            this.host = host.service;\n            if (\n                args[1] === undefined ||\n                !ts.isNewExpression(args[1]) ||\n                this.values.symbolName(args[1].expression) !== 'ServerWiringOptions'\n            )\n                this.fail(\n                    'Use ServerWiringOptions with separate bindingModules and routingModules arrays.',\n                );\n            arrays = (args[1] as ts.NewExpression).arguments ?? [];\n        } else if (name === 'BrowserWiring') arrays = args;\n        else this.fail(`Unsupported plan ${name}; use ServerWiring or BrowserWiring.`);\n        const selections: WiringSelection[] = [];\n        for (const array of arrays) {\n            if (!ts.isArrayLiteralExpression(array))\n                this.fail(\n                    'Plan module/provider lists must be static arrays; dynamic composition needs an explicit supported policy.',\n                );\n            for (const element of (array as ts.ArrayLiteralExpression).elements) {\n                if (ts.isObjectLiteralExpression(element)) continue; // ordinary Angular providers; API factories are checked independently\n                if (\n                    ts.isCallExpression(element) &&\n                    this.values.symbolName(element.expression) === 'provideRpcClient'\n                )\n                    continue;\n                const invocation =\n                    ts.isNewExpression(element) || ts.isCallExpression(element)\n                        ? element\n                        : undefined;\n                const identity = this.values.identity(\n                    invocation === undefined ? element : invocation.expression,\n                );\n                const targets = invocation === undefined ? {} : this.values.arguments(invocation);\n                selections.push(\n                    new WiringSelection(\n                        identity.project,\n                        identity.exportedName,\n                        targets,\n                        invocation === undefined ? {} : this.values.policies(invocation),\n                    ),\n                );\n                if (\n                    identity.project === this.info.name &&\n                    this.exported[identity.exportedName] === undefined\n                )\n                    this.exported[identity.exportedName] = new WiringExport('binding', [], []);\n            }\n        }\n        this.exported[owner!] = new WiringExport('plan', [], selections);\n        this.entry = owner;\n    }\n\n    private planReturns(method: ts.MethodDeclaration, owner: string): ts.ReturnStatement[] {\n        const returns: ts.ReturnStatement[] = [];\n        const visit = (node: ts.Node): void => {\n            if (ts.isReturnStatement(node)) returns.push(node);\n            else ts.forEachChild(node, visit);\n        };\n        if (method.body !== undefined) visit(method.body);\n        if (\n            returns.length !== 1 ||\n            returns[0].expression === undefined ||\n            !ts.isNewExpression(returns[0].expression)\n        )\n            this.fail(`${owner}.getRuntimeWiring must return one statically composed plan.`);\n        return returns;\n    }\n\n    private exportOwner(node: ts.Node): string | undefined {\n        let current: ts.Node | undefined = node;\n        while (current !== undefined) {\n            if (\n                ts.isClassDeclaration(current) &&\n                current.name !== undefined &&\n                (ts.getModifiers(current) ?? []).some(\n                    (modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword,\n                )\n            )\n                return current.name.text;\n            if (\n                ts.isFunctionDeclaration(current) &&\n                current.name !== undefined &&\n                (ts.getModifiers(current) ?? []).some(\n                    (modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword,\n                )\n            )\n                return current.name.text;\n            if (ts.isVariableDeclaration(current) && ts.isIdentifier(current.name)) {\n                const statement = current.parent.parent;\n                if (\n                    ts.isVariableStatement(statement) &&\n                    (ts.getModifiers(statement) ?? []).some(\n                        (modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword,\n                    )\n                )\n                    return current.name.text;\n            }\n            current = current.parent;\n        }\n        return undefined;\n    }\n\n    private owns(file: string): boolean {\n        const root = path.resolve(this.workspaceRoot, this.info.root) + path.sep;\n        return path.resolve(file).startsWith(root) && !file.includes('/node_modules/');\n    }\n\n    private fail(message: string): never {\n        throw new RuleFailError('validate-runtime-architecture', message, undefined, undefined, [\n            new Option(\n                'Move topology into canonical src/wiring.ts and use the documented static plan grammar; do not execute configuration to extract it.',\n                true,\n            ),\n        ]);\n    }\n}\n\n/** Factory kept separate so graph assembly cannot accidentally create a compiler. */\nexport class WiringProjectProgram {\n    create(workspaceRoot: string, info: ProjectInfo): ts.Program {\n        const root = path.resolve(workspaceRoot, info.root);\n        const configured = createProjectProgram(root);\n        if (configured !== null) return configured;\n        const config = ts.findConfigFile(root, ts.sys.fileExists, 'tsconfig.json');\n        const parsed =\n            config === undefined ? undefined : ts.readConfigFile(config, ts.sys.readFile);\n        const options =\n            parsed === undefined\n                ? {}\n                : ts.parseJsonConfigFileContent(parsed.config, ts.sys, root).options;\n        const files = ts.sys.readDirectory(\n            path.join(root, 'src'),\n            ['.ts'],\n            ['**/*.spec.ts', '**/*.test.ts'],\n        );\n        return ts.createProgram(files, options);\n    }\n}\n"]}
+{"version":3,"file":"source-extractor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/runtime-wiring/source-extractor.ts"],"names":[],"mappings":"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","sourcesContent":["import * as path from 'path';\nimport * as ts from 'typescript';\nimport { Option, RuleFailError } from '@webpieces/rules-config';\nimport type { ProjectInfo } from '../project-info';\nimport { createProjectProgram } from '../di-graph/program';\nimport {\n    ContractIdentity,\n    ImplementsFacts,\n    UsesFacts,\n    RuntimeDeclaration,\n    WiringExport,\n    WiringRelationship,\n    WiringSelection,\n} from './declaration';\nimport { WiringSourceValues } from './source-values';\nimport { CanonicalClientBindings } from './canonical-clients';\n\n/** Build-only extraction. It never imports application modules or invokes their constructors. */\nexport class WiringSourceExtractor {\n    private readonly values: WiringSourceValues;\n    private readonly exported: Record<string, WiringExport> = {};\n    private entry: string | undefined;\n    private host: string | undefined;\n\n    constructor(\n        private readonly workspaceRoot: string,\n        private readonly info: ProjectInfo,\n        private readonly infos: ReadonlyMap<string, ProjectInfo>,\n        private readonly program: ts.Program,\n    ) {\n        this.values = new WiringSourceValues(workspaceRoot, infos, program.getTypeChecker());\n    }\n\n    extract(): RuntimeDeclaration {\n        const clients = new CanonicalClientBindings(this.program.getTypeChecker());\n        const problems = this.program\n            .getSourceFiles()\n            .filter(\n                (file) =>\n                    !file.isDeclarationFile &&\n                    this.owns(file.fileName) &&\n                    !/(?:\\.spec\\.|\\.test\\.|\\/__tests__\\/)/.test(file.fileName),\n            )\n            .flatMap((file) => clients.problems(file));\n        clients.assert(problems);\n        const wiringPath = path.resolve(this.workspaceRoot, this.info.root, 'src/wiring.ts');\n        const wiring = this.program.getSourceFile(wiringPath);\n        if (wiring === undefined) this.fail(`Missing canonical ${wiringPath}.`);\n        for (const file of this.program.getSourceFiles()) {\n            if (\n                file.isDeclarationFile ||\n                !this.owns(file.fileName) ||\n                /(?:\\.spec\\.|\\.test\\.|\\/__tests__\\/)/.test(file.fileName)\n            )\n                continue;\n            this.visit(file, file.fileName === wiringPath);\n        }\n        const framework = this.info.tags.includes('framework:angular')\n            ? 'angular'\n            : this.info.tags.some((tag) => tag === 'framework:node' || tag === 'framework:express')\n              ? 'node'\n              : 'browser';\n        if (this.info.tags.includes('webpieces') && this.entry === undefined)\n            this.fail(`${this.info.name} requires getRuntimeWiring() returning a typed plan.`);\n        return new RuntimeDeclaration(\n            this.info.name,\n            framework,\n            this.exported,\n            this.entry,\n            this.host,\n        );\n    }\n\n    private visit(node: ts.Node, inWiring: boolean): void {\n        if (\n            !inWiring &&\n            (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) &&\n            [\n                'addRoutes',\n                'createRpcClient',\n                'createPubSubClient',\n                'bindRpc',\n                'bindPubSub',\n            ].includes(this.values.symbolName(node))\n        )\n            this.fail(\n                `${node.getSourceFile().fileName}: topology method references belong in src/wiring.ts, including aliases.`,\n            );\n        if (\n            inWiring &&\n            ts.isNewExpression(node) &&\n            this.values.symbolName(node.expression) === 'ExternalContractUse'\n        )\n            this.recordExternal(node);\n        if (ts.isCallExpression(node)) {\n            const name = this.values.symbolName(node.expression);\n            if (\n                [\n                    'addRoutes',\n                    'createRpcClient',\n                    'createPubSubClient',\n                    'bindRpc',\n                    'bindPubSub',\n                    'provideRpcClient',\n                ].includes(name)\n            ) {\n                if (!inWiring)\n                    this.fail(\n                        `${node.getSourceFile().fileName}: ${name} must be owned by src/wiring.ts.`,\n                    );\n                this.recordRelationship(node, name);\n            }\n        }\n        if (inWiring && ts.isMethodDeclaration(node) && node.name.getText() === 'getRuntimeWiring')\n            this.recordPlan(node);\n        ts.forEachChild(node, (child) => this.visit(child, inWiring));\n    }\n\n    private recordExternal(expression: ts.NewExpression): void {\n        const owner = this.exportOwner(expression);\n        const identity = expression.arguments?.[0];\n        if (owner === undefined || identity === undefined || !ts.isStringLiteralLike(identity))\n            this.fail(\n                'ExternalContractUse belongs to a selected exported module and requires a literal project#contract identity.',\n            );\n        const qualified = (identity as ts.StringLiteralLike).text.split('#');\n        const project = qualified[0];\n        const exportedName = qualified[1];\n        const extra = qualified[2];\n        if (!project || !exportedName || extra !== undefined)\n            this.fail('ExternalContractUse requires one qualified project#contract identity.');\n        if (!this.values.hasExternalConsumer(this.info.name, project, exportedName, this.program))\n            this.fail(\n                `${project}#${exportedName} has no production business consumer in ${this.info.name}; adapters and test doubles do not establish uses.`,\n            );\n        const exported = this.exported[owner!] ?? new WiringExport('binding', [], []);\n        exported.relationships.push(\n            new WiringRelationship(\n                new ContractIdentity(project, exportedName),\n                new UsesFacts('external', {\n                    kind: 'unknown',\n                    reason: 'Vendor interface; destination classified by approved contract metadata',\n                }),\n            ),\n        );\n        this.exported[owner!] = exported;\n    }\n\n    private recordRelationship(call: ts.CallExpression, method: string): void {\n        const owner = this.exportOwner(call);\n        // The generic Angular integration adapter defines the primitive; its invocations own facts.\n        if (owner === 'provideRpcClient' && method === 'createRpcClient') return;\n        if (owner === undefined)\n            this.fail(`Unowned ${method} at ${call.getSourceFile().fileName}:${call.getStart()}.`);\n        const apiIndex =\n            method === 'bindRpc' || method === 'bindPubSub' || method === 'provideRpcClient'\n                ? 1\n                : 0;\n        const api = call.arguments[apiIndex];\n        if (api === undefined) this.fail(`${method} requires an explicit API contract.`);\n        const contract = this.values.identity(api!);\n        const direction = method === 'addRoutes' ? 'implements' : 'uses';\n        const contractTransport = this.values.transport(api!);\n        const transport =\n            method === 'addRoutes'\n                ? contractTransport\n                : method === 'bindPubSub' || method === 'createPubSubClient'\n                  ? 'pubsub'\n                  : 'rpc';\n        if (transport !== contractTransport)\n            this.fail(\n                `${method} transport disagrees with ${contract.project}#${contract.exportedName}.`,\n            );\n        const target =\n            direction === 'implements'\n                ? undefined\n                : this.values.target(call.arguments[apiIndex + 1]);\n        const kind =\n            direction === 'implements'\n                ? 'routing'\n                : method === 'provideRpcClient'\n                  ? 'providers'\n                  : 'binding';\n        const exported = this.exported[owner!] ?? new WiringExport(kind, [], []);\n        exported.relationships.push(\n            new WiringRelationship(\n                contract,\n                direction === 'implements'\n                    ? new ImplementsFacts(transport, this.values.condition(call))\n                    : new UsesFacts(transport, target!, this.values.condition(call)),\n            ),\n        );\n        this.exported[owner!] = exported;\n    }\n\n    private recordPlan(method: ts.MethodDeclaration): void {\n        const owner = this.exportOwner(method);\n        if (owner === undefined) this.fail('The plan class must be exported from src/wiring.ts.');\n        const returns = this.planReturns(method, owner!);\n        const expression = returns[0].expression as ts.NewExpression;\n        const name = this.values.symbolName(expression.expression);\n        const args = expression.arguments ?? [];\n        let arrays: readonly ts.Expression[];\n        if (name === 'ServerWiring') {\n            const host = this.values.target(args[0]);\n            if (host.kind !== 'service')\n                this.fail('ServerWiring requires a literal host identity.');\n            this.host = host.service;\n            if (\n                args[1] === undefined ||\n                !ts.isNewExpression(args[1]) ||\n                this.values.symbolName(args[1].expression) !== 'ServerWiringOptions'\n            )\n                this.fail(\n                    'Use ServerWiringOptions with separate bindingModules and routingModules arrays.',\n                );\n            arrays = (args[1] as ts.NewExpression).arguments ?? [];\n        } else if (name === 'BrowserWiring') arrays = args;\n        else this.fail(`Unsupported plan ${name}; use ServerWiring or BrowserWiring.`);\n        const selections: WiringSelection[] = [];\n        for (const array of arrays) {\n            if (!ts.isArrayLiteralExpression(array))\n                this.fail(\n                    'Plan module/provider lists must be static arrays; dynamic composition needs an explicit supported policy.',\n                );\n            for (const element of (array as ts.ArrayLiteralExpression).elements) {\n                if (ts.isObjectLiteralExpression(element)) continue; // ordinary Angular providers; API factories are checked independently\n                if (\n                    ts.isCallExpression(element) &&\n                    this.values.symbolName(element.expression) === 'provideRpcClient'\n                )\n                    continue;\n                const invocation =\n                    ts.isNewExpression(element) || ts.isCallExpression(element)\n                        ? element\n                        : undefined;\n                const identity = this.values.identity(\n                    invocation === undefined ? element : invocation.expression,\n                );\n                const targets = invocation === undefined ? {} : this.values.arguments(invocation);\n                selections.push(\n                    new WiringSelection(\n                        identity.project,\n                        identity.exportedName,\n                        targets,\n                        invocation === undefined ? {} : this.values.policies(invocation),\n                    ),\n                );\n                if (\n                    identity.project === this.info.name &&\n                    this.exported[identity.exportedName] === undefined\n                )\n                    this.exported[identity.exportedName] = new WiringExport('binding', [], []);\n            }\n        }\n        this.exported[owner!] = new WiringExport('plan', [], selections);\n        this.entry = owner;\n    }\n\n    private planReturns(method: ts.MethodDeclaration, owner: string): ts.ReturnStatement[] {\n        const returns: ts.ReturnStatement[] = [];\n        const visit = (node: ts.Node): void => {\n            if (ts.isReturnStatement(node)) returns.push(node);\n            else ts.forEachChild(node, visit);\n        };\n        if (method.body !== undefined) visit(method.body);\n        if (\n            returns.length !== 1 ||\n            returns[0].expression === undefined ||\n            !ts.isNewExpression(returns[0].expression)\n        )\n            this.fail(`${owner}.getRuntimeWiring must return one statically composed plan.`);\n        return returns;\n    }\n\n    private exportOwner(node: ts.Node): string | undefined {\n        let current: ts.Node | undefined = node;\n        while (current !== undefined) {\n            if (\n                ts.isClassDeclaration(current) &&\n                current.name !== undefined &&\n                (ts.getModifiers(current) ?? []).some(\n                    (modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword,\n                )\n            )\n                return current.name.text;\n            if (\n                ts.isFunctionDeclaration(current) &&\n                current.name !== undefined &&\n                (ts.getModifiers(current) ?? []).some(\n                    (modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword,\n                )\n            )\n                return current.name.text;\n            if (ts.isVariableDeclaration(current) && ts.isIdentifier(current.name)) {\n                const statement = current.parent.parent;\n                if (\n                    ts.isVariableStatement(statement) &&\n                    (ts.getModifiers(statement) ?? []).some(\n                        (modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword,\n                    )\n                )\n                    return current.name.text;\n            }\n            current = current.parent;\n        }\n        return undefined;\n    }\n\n    private owns(file: string): boolean {\n        const root = path.resolve(this.workspaceRoot, this.info.root) + path.sep;\n        return path.resolve(file).startsWith(root) && !file.includes('/node_modules/');\n    }\n\n    private fail(message: string): never {\n        throw new RuleFailError('validate-runtime-architecture', message, undefined, undefined, [\n            new Option(\n                'Move topology into canonical src/wiring.ts using RuntimeClients.bindRpc(token, Api, rpcTarget(Api, deployment)), RuntimeTaskClients.bindPubSub, or provideRpcClient for supported registrations, and use the documented static plan grammar; do not execute configuration to extract it.',\n                true,\n            ),\n        ]);\n    }\n}\n\n/** Factory kept separate so graph assembly cannot accidentally create a compiler. */\nexport class WiringProjectProgram {\n    create(workspaceRoot: string, info: ProjectInfo): ts.Program {\n        const root = path.resolve(workspaceRoot, info.root);\n        const configured = createProjectProgram(root);\n        if (configured !== null) return configured;\n        const config = ts.findConfigFile(root, ts.sys.fileExists, 'tsconfig.json');\n        const parsed =\n            config === undefined ? undefined : ts.readConfigFile(config, ts.sys.readFile);\n        const options =\n            parsed === undefined\n                ? {}\n                : ts.parseJsonConfigFileContent(parsed.config, ts.sys, root).options;\n        const files = ts.sys.readDirectory(\n            path.join(root, 'src'),\n            ['.ts'],\n            ['**/*.spec.ts', '**/*.test.ts'],\n        );\n        return ts.createProgram(files, options);\n    }\n}\n"]}

package/src/rule-help.js

@@ -9,7 +9,7 @@ exports.ruleHelp = {
     'nx-wiring': new rules_sdk_1.RuleHelp('Wire the required validation targets into the Nx execution graph.', 'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.'),
     'di-graph': new rules_sdk_1.RuleHelp('Generate and validate dependency-injection design graphs.', 'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.'),
     'missing-design-annotation': new rules_sdk_1.RuleHelp('Declare the application design roots required for DI analysis.', 'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.'),
-    'validate-architecture-unchanged': new rules_sdk_1.RuleHelp('Keep the committed architecture graph aligned with current dependencies.', 'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.'),
+    'validate-architecture-unchanged': new rules_sdk_1.RuleHelp('Keep the committed architecture graph aligned with current dependencies and enforce canonical client registrations across ALL CODE in participating runtime owners.', 'In src/wiring.ts use new RuntimeClients(options).bindRpc(token, Api, rpcTarget(Api, deployment), filters?) from @webpieces/http-client-node, new RuntimeTaskClients(options).bindPubSub(token, Api, deployment) from @webpieces/cloudtasks-client, and provideRpcClient(token, Api, rpcTarget(Api, deployment)) from @webpieces/http-client-browser. Migrate every supported raw singleton/provider factory, including unchanged owners; preserve tokens and filters. Review graph changes and runtime-deps.json candidates explicitly.'),
     'validate-no-architecture-cycles': new rules_sdk_1.RuleHelp('Keep the project dependency architecture free of cycles.', 'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.'),
     'validate-packagejson': new rules_sdk_1.RuleHelp('Align package dependencies with declared project dependencies.', 'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.'),
     'validate-versions-locked': new rules_sdk_1.RuleHelp('Pin dependency versions consistently across governed projects.', 'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.'),

package/src/rule-help.js.map

@@ -1 +1 @@
-{"version":3,"file":"rule-help.js","sourceRoot":"","sources":["../../../../../packages/tooling/nx-webpieces-rules/src/rule-help.ts"],"names":[],"mappings":";;;AAAA,oDAAgD;AAEhD,gEAAgE;AACnD,QAAA,QAAQ,GAAuC;IACxD,uBAAuB,EAAE,IAAI,oBAAQ,CACjC,kDAAkD,EAClD,sIAAsI,CACzI;IACD,sBAAsB,EAAE,IAAI,oBAAQ,CAChC,2DAA2D,EAC3D,sIAAsI,CACzI;IACD,WAAW,EAAE,IAAI,oBAAQ,CACrB,mEAAmE,EACnE,sIAAsI,CACzI;IACD,UAAU,EAAE,IAAI,oBAAQ,CACpB,2DAA2D,EAC3D,sIAAsI,CACzI;IACD,2BAA2B,EAAE,IAAI,oBAAQ,CACrC,gEAAgE,EAChE,sIAAsI,CACzI;IACD,iCAAiC,EAAE,IAAI,oBAAQ,CAC3C,0EAA0E,EAC1E,sIAAsI,CACzI;IACD,iCAAiC,EAAE,IAAI,oBAAQ,CAC3C,0DAA0D,EAC1D,sIAAsI,CACzI;IACD,sBAAsB,EAAE,IAAI,oBAAQ,CAChC,gEAAgE,EAChE,sIAAsI,CACzI;IACD,0BAA0B,EAAE,IAAI,oBAAQ,CACpC,gEAAgE,EAChE,sIAAsI,CACzI;IACD,sBAAsB,EAAE,IAAI,oBAAQ,CAChC,8EAA8E,EAC9E,sIAAsI,CACzI;IACD,wBAAwB,EAAE,IAAI,oBAAQ,CAClC,qEAAqE,EACrE,sIAAsI,CACzI;IACD,uBAAuB,EAAE,IAAI,oBAAQ,CACjC,uEAAuE,EACvE,sIAAsI,CACzI;IACD,mBAAmB,EAAE,IAAI,oBAAQ,CAC7B,mEAAmE,EACnE,sIAAsI,CACzI;IACD,sBAAsB,EAAE,IAAI,oBAAQ,CAChC,+DAA+D,EAC/D,sIAAsI,CACzI;IACD,cAAc,EAAE,IAAI,oBAAQ,CACxB,sDAAsD,EACtD,sIAAsI,CACzI;IACD,kBAAkB,EAAE,IAAI,oBAAQ,CAC5B,gEAAgE,EAChE,sIAAsI,CACzI;CACJ,CAAC","sourcesContent":["import { RuleHelp } from '@webpieces/rules-sdk';\n\n/** Owner-authored guidance consumed by the registry catalog. */\nexport const ruleHelp: Readonly<Record<string, RuleHelp>> = {\n    'no-file-import-cycles': new RuleHelp(\n        'Keep each project free of circular file imports.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'runtime-architecture': new RuleHelp(\n        'Validate runtime service and API dependency declarations.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'nx-wiring': new RuleHelp(\n        'Wire the required validation targets into the Nx execution graph.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'di-graph': new RuleHelp(\n        'Generate and validate dependency-injection design graphs.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'missing-design-annotation': new RuleHelp(\n        'Declare the application design roots required for DI analysis.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'validate-architecture-unchanged': new RuleHelp(\n        'Keep the committed architecture graph aligned with current dependencies.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'validate-no-architecture-cycles': new RuleHelp(\n        'Keep the project dependency architecture free of cycles.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'validate-packagejson': new RuleHelp(\n        'Align package dependencies with declared project dependencies.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'validate-versions-locked': new RuleHelp(\n        'Pin dependency versions consistently across governed projects.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'validate-eslint-sync': new RuleHelp(\n        'Keep managed ESLint configuration synchronized with its installed templates.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'no-root-union-api-type': new RuleHelp(\n        'Use a stable named root API contract rather than a root union type.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'api-rules-for-openapi': new RuleHelp(\n        'Validate API contracts against their configured OpenAPI requirements.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'api-rules-for-mcp': new RuleHelp(\n        'Validate API contracts against their configured MCP requirements.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'api-lib-dependencies': new RuleHelp(\n        'Validate the configured API library dependency relationships.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'api-lib-path': new RuleHelp(\n        'Use the configured paths for API contract libraries.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'framework-folder': new RuleHelp(\n        'Align framework declarations with their project folder layout.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n};\n"]}
+{"version":3,"file":"rule-help.js","sourceRoot":"","sources":["../../../../../packages/tooling/nx-webpieces-rules/src/rule-help.ts"],"names":[],"mappings":";;;AAAA,oDAAgD;AAEhD,gEAAgE;AACnD,QAAA,QAAQ,GAAuC;IACxD,uBAAuB,EAAE,IAAI,oBAAQ,CACjC,kDAAkD,EAClD,sIAAsI,CACzI;IACD,sBAAsB,EAAE,IAAI,oBAAQ,CAChC,2DAA2D,EAC3D,sIAAsI,CACzI;IACD,WAAW,EAAE,IAAI,oBAAQ,CACrB,mEAAmE,EACnE,sIAAsI,CACzI;IACD,UAAU,EAAE,IAAI,oBAAQ,CACpB,2DAA2D,EAC3D,sIAAsI,CACzI;IACD,2BAA2B,EAAE,IAAI,oBAAQ,CACrC,gEAAgE,EAChE,sIAAsI,CACzI;IACD,iCAAiC,EAAE,IAAI,oBAAQ,CAC3C,qKAAqK,EACrK,ygBAAygB,CAC5gB;IACD,iCAAiC,EAAE,IAAI,oBAAQ,CAC3C,0DAA0D,EAC1D,sIAAsI,CACzI;IACD,sBAAsB,EAAE,IAAI,oBAAQ,CAChC,gEAAgE,EAChE,sIAAsI,CACzI;IACD,0BAA0B,EAAE,IAAI,oBAAQ,CACpC,gEAAgE,EAChE,sIAAsI,CACzI;IACD,sBAAsB,EAAE,IAAI,oBAAQ,CAChC,8EAA8E,EAC9E,sIAAsI,CACzI;IACD,wBAAwB,EAAE,IAAI,oBAAQ,CAClC,qEAAqE,EACrE,sIAAsI,CACzI;IACD,uBAAuB,EAAE,IAAI,oBAAQ,CACjC,uEAAuE,EACvE,sIAAsI,CACzI;IACD,mBAAmB,EAAE,IAAI,oBAAQ,CAC7B,mEAAmE,EACnE,sIAAsI,CACzI;IACD,sBAAsB,EAAE,IAAI,oBAAQ,CAChC,+DAA+D,EAC/D,sIAAsI,CACzI;IACD,cAAc,EAAE,IAAI,oBAAQ,CACxB,sDAAsD,EACtD,sIAAsI,CACzI;IACD,kBAAkB,EAAE,IAAI,oBAAQ,CAC5B,gEAAgE,EAChE,sIAAsI,CACzI;CACJ,CAAC","sourcesContent":["import { RuleHelp } from '@webpieces/rules-sdk';\n\n/** Owner-authored guidance consumed by the registry catalog. */\nexport const ruleHelp: Readonly<Record<string, RuleHelp>> = {\n    'no-file-import-cycles': new RuleHelp(\n        'Keep each project free of circular file imports.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'runtime-architecture': new RuleHelp(\n        'Validate runtime service and API dependency declarations.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'nx-wiring': new RuleHelp(\n        'Wire the required validation targets into the Nx execution graph.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'di-graph': new RuleHelp(\n        'Generate and validate dependency-injection design graphs.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'missing-design-annotation': new RuleHelp(\n        'Declare the application design roots required for DI analysis.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'validate-architecture-unchanged': new RuleHelp(\n        'Keep the committed architecture graph aligned with current dependencies and enforce canonical client registrations across ALL CODE in participating runtime owners.',\n        'In src/wiring.ts use new RuntimeClients(options).bindRpc(token, Api, rpcTarget(Api, deployment), filters?) from @webpieces/http-client-node, new RuntimeTaskClients(options).bindPubSub(token, Api, deployment) from @webpieces/cloudtasks-client, and provideRpcClient(token, Api, rpcTarget(Api, deployment)) from @webpieces/http-client-browser. Migrate every supported raw singleton/provider factory, including unchanged owners; preserve tokens and filters. Review graph changes and runtime-deps.json candidates explicitly.',\n    ),\n    'validate-no-architecture-cycles': new RuleHelp(\n        'Keep the project dependency architecture free of cycles.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'validate-packagejson': new RuleHelp(\n        'Align package dependencies with declared project dependencies.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'validate-versions-locked': new RuleHelp(\n        'Pin dependency versions consistently across governed projects.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'validate-eslint-sync': new RuleHelp(\n        'Keep managed ESLint configuration synchronized with its installed templates.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'no-root-union-api-type': new RuleHelp(\n        'Use a stable named root API contract rather than a root union type.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'api-rules-for-openapi': new RuleHelp(\n        'Validate API contracts against their configured OpenAPI requirements.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'api-rules-for-mcp': new RuleHelp(\n        'Validate API contracts against their configured MCP requirements.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'api-lib-dependencies': new RuleHelp(\n        'Validate the configured API library dependency relationships.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'api-lib-path': new RuleHelp(\n        'Use the configured paths for API contract libraries.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n    'framework-folder': new RuleHelp(\n        'Align framework declarations with their project folder layout.',\n        'Apply this policy in source, or review its explicit settings in {configFile}. An intentional opt-out requires complete OFF settings.',\n    ),\n};\n"]}