@webpieces/nx-webpieces-rules 0.4.779 → 0.4.780

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

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/visualize/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAeH,8BA0CC;AAtDD,yDAA0D;AAC1D,iEAA6D;AAC7D,2CAAwC;AAUzB,KAAK,UAAU,WAAW,CACrC,OAAiC,EACjC,OAAwB;IAExB,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACpC,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;IAEjD,8DAA8D;IAC9D,IAAI,CAAC;QACD,uBAAuB;QACvB,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;QACzC,MAAM,SAAS,GAAG,IAAA,+BAAgB,EAAC,aAAa,EAAE,SAAS,CAAC,CAAC;QAE7D,IAAI,CAAC,SAAS,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,0DAA0D,CAAC,CAAC;YAC1E,OAAO,CAAC,KAAK,CAAC,4CAA4C,CAAC,CAAC;YAC5D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;QACD,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC;QAEjC,yBAAyB;QACzB,OAAO,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAC;QAC9C,MAAM,UAAU,GAAG,IAAI,kCAAe,EAAE,CAAC;QACzC,MAAM,QAAQ,GAAG,UAAU,CAAC,kBAAkB,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;QACrE,OAAO,CAAC,GAAG,CAAC,gBAAgB,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QAEjD,yBAAyB;QACzB,OAAO,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;QACxD,IAAI,UAAU,CAAC,iBAAiB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClD,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QACpC,CAAC;aAAM,CAAC;YACJ,OAAO,CAAC,GAAG,CAAC,2CAA2C,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QAChF,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QACxD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC","sourcesContent":["/**\n * Visualize Executor\n *\n * Generates visual representations of the architecture graph (DOT + HTML)\n * and opens the visualization in a browser.\n *\n * Usage:\n * nx run architecture:visualize\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { loadBlessedGraph } from '../../lib/graph-loader';\nimport { GraphVisualizer } from '../../lib/graph-visualizer';\nimport { toError } from '../../toError';\n\nexport interface VisualizeExecutorOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nexport default async function runExecutor(\n    options: VisualizeExecutorOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    console.log('\\n🎨 Architecture Visualization\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Load the saved graph\n        console.log('📂 Loading saved graph...');\n        const graphFile = loadBlessedGraph(workspaceRoot, graphPath);\n\n        if (!graphFile) {\n            console.error('❌ No saved graph found at architecture/dependencies.json');\n            console.error('   Run: nx run architecture:generate first');\n            return { success: false };\n        }\n        const graph = graphFile.projects;\n\n        // Generate visualization\n        console.log('🎨 Generating visualization...');\n        const visualizer = new GraphVisualizer();\n        const vizPaths = visualizer.writeVisualization(graph, workspaceRoot);\n        console.log(`✅ Generated: ${vizPaths.htmlPath}`);\n\n        // Try to open in browser\n        console.log('\\n🌐 Opening visualization in browser...');\n        if (visualizer.openVisualization(vizPaths.htmlPath)) {\n            console.log('✅ Browser opened');\n        } else {\n            console.log(`⚠️  Could not auto-open. Open manually: ${vizPaths.htmlPath}`);\n        }\n\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error('❌ Visualization failed:', error.message);\n        return { success: false };\n    }\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/visualize/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAgBH,8BA2CC;AAxDD,yDAA0D;AAC1D,iEAA6D;AAC7D,0DAAgF;AAChF,2CAAwC;AAUzB,KAAK,UAAU,WAAW,CACrC,OAAiC,EACjC,OAAwB;IAExB,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACpC,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;IAEjD,8DAA8D;IAC9D,IAAI,CAAC;QACD,uBAAuB;QACvB,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;QACzC,MAAM,SAAS,GAAG,IAAA,+BAAgB,EAAC,aAAa,EAAE,SAAS,CAAC,CAAC;QAE7D,IAAI,CAAC,SAAS,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,0DAA0D,CAAC,CAAC;YAC1E,OAAO,CAAC,KAAK,CAAC,4CAA4C,CAAC,CAAC;YAC5D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;QACD,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC;QAEjC,yBAAyB;QACzB,OAAO,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAC;QAC9C,MAAM,UAAU,GAAG,IAAI,kCAAe,EAAE,CAAC;QACzC,MAAM,QAAQ,GAAG,UAAU,CAAC,kBAAkB,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;QACrE,OAAO,CAAC,GAAG,CAAC,gBAAgB,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QAEjD,yBAAyB;QACzB,OAAO,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;QACxD,IAAI,UAAU,CAAC,iBAAiB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClD,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QACpC,CAAC;aAAM,CAAC;YACJ,OAAO,CAAC,GAAG,CAAC,2CAA2C,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QAChF,CAAC;QAED,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,MAAM,QAAQ,GAAG,KAAK,YAAY,4BAAa,CAAC,CAAC,CAAC,IAAA,qCAAsB,EAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;QAChG,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,QAAQ,CAAC,CAAC;QACnD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC","sourcesContent":["/**\n * Visualize Executor\n *\n * Generates visual representations of the architecture graph (DOT + HTML)\n * and opens the visualization in a browser.\n *\n * Usage:\n * nx run architecture:visualize\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { loadBlessedGraph } from '../../lib/graph-loader';\nimport { GraphVisualizer } from '../../lib/graph-visualizer';\nimport { RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport { toError } from '../../toError';\n\nexport interface VisualizeExecutorOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nexport default async function runExecutor(\n    options: VisualizeExecutorOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    console.log('\\n🎨 Architecture Visualization\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Load the saved graph\n        console.log('📂 Loading saved graph...');\n        const graphFile = loadBlessedGraph(workspaceRoot, graphPath);\n\n        if (!graphFile) {\n            console.error('❌ No saved graph found at architecture/dependencies.json');\n            console.error('   Run: nx run architecture:generate first');\n            return { success: false };\n        }\n        const graph = graphFile.projects;\n\n        // Generate visualization\n        console.log('🎨 Generating visualization...');\n        const visualizer = new GraphVisualizer();\n        const vizPaths = visualizer.writeVisualization(graph, workspaceRoot);\n        console.log(`✅ Generated: ${vizPaths.htmlPath}`);\n\n        // Try to open in browser\n        console.log('\\n🌐 Opening visualization in browser...');\n        if (visualizer.openVisualization(vizPaths.htmlPath)) {\n            console.log('✅ Browser opened');\n        } else {\n            console.log(`⚠️  Could not auto-open. Open manually: ${vizPaths.htmlPath}`);\n        }\n\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        const rendered = error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message;\n        console.error('❌ Visualization failed:', rendered);\n        return { success: false };\n    }\n}\n"]}

package/src/lib/api-contract-files.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Per-API contract files: `architecture/apis/<ApiName>.json`.
+ *
+ * WHY these exist (issue #949): the full endpoint contract used to live inside
+ * architecture/dependencies.json under `apiContracts`, so adding ONE `@Endpoint` rewrote the project
+ * dependency graph and failed validate-architecture-unchanged until `architecture:generate` was rerun.
+ * dependencies.json is meant to change only when PROJECT dependencies change. Each API's contract now
+ * lives in its own generated file, and dependencies.json only LINKS to it (`apiContractFiles`), so it
+ * changes when an API is added or removed — never when an endpoint is.
+ *
+ * These files are written by `architecture:generate` and deliberately NOT drift-gated: nothing
+ * compares them to source. The runtime graph (generate, validate-runtime-architecture) reads its
+ * queue/trigger data from them.
+ */
+import type { ApiContracts } from './api-usage/api-relations';
+/** The directory, relative to dependencies.json's own directory, holding one file per API. */
+export declare const API_CONTRACTS_DIR = "apis";
+/** The rule name every contract-file failure is reported under. */
+export declare const API_CONTRACT_FILES_RULE = "validate-architecture-unchanged";
+/** apiClassName -> path of its contract file, RELATIVE to dependencies.json's directory. */
+export type ApiContractFileRefs = Record<string, string>;
+/**
+ * What one `architecture:generate` pass did to the `apis/` directory, so the executor can say so.
+ */
+export declare class ApiContractFilesWriteResult {
+    readonly written: string[];
+    readonly deleted: string[];
+    constructor(written: string[], deleted: string[]);
+}
+/**
+ * Reads and writes the per-API contract files. All paths are resolved against the directory that
+ * holds dependencies.json (`graphPath`), so a non-default graphPath keeps its contracts beside it.
+ */
+export declare class ApiContractFiles {
+    /** The link dependencies.json carries for one API: `apis/<ApiName>.json`. */
+    refFor(api: string): string;
+    /** The link table for every contract, in the contracts' (already sorted) order. */
+    refsFor(contracts: ApiContracts): ApiContractFileRefs;
+    /**
+     * Write one file per contract and DELETE every `apis/*.json` whose API no longer exists, so a
+     * removed API never leaves a stale contract behind for the runtime graph to read.
+     */
+    write(workspaceRoot: string, graphPath: string, contracts: ApiContracts): ApiContractFilesWriteResult;
+    /**
+     * Load every contract dependencies.json links to. A missing or unreadable file FAILS: the runtime
+     * graph would otherwise silently lose that API's queues and triggers.
+     */
+    load(workspaceRoot: string, graphPath: string, refs: ApiContractFileRefs): ApiContracts;
+    private loadOne;
+    /** Pretty, deterministic JSON: the api name first, then the contract in its declared field order. */
+    private format;
+    private dirFor;
+    private deleteStale;
+}

package/src/lib/api-contract-files.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * Per-API contract files: `architecture/apis/<ApiName>.json`.
+ *
+ * WHY these exist (issue #949): the full endpoint contract used to live inside
+ * architecture/dependencies.json under `apiContracts`, so adding ONE `@Endpoint` rewrote the project
+ * dependency graph and failed validate-architecture-unchanged until `architecture:generate` was rerun.
+ * dependencies.json is meant to change only when PROJECT dependencies change. Each API's contract now
+ * lives in its own generated file, and dependencies.json only LINKS to it (`apiContractFiles`), so it
+ * changes when an API is added or removed — never when an endpoint is.
+ *
+ * These files are written by `architecture:generate` and deliberately NOT drift-gated: nothing
+ * compares them to source. The runtime graph (generate, validate-runtime-architecture) reads its
+ * queue/trigger data from them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiContractFiles = exports.ApiContractFilesWriteResult = exports.API_CONTRACT_FILES_RULE = exports.API_CONTRACTS_DIR = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const rules_config_1 = require("@webpieces/rules-config");
+const toError_1 = require("../toError");
+/** The directory, relative to dependencies.json's own directory, holding one file per API. */
+exports.API_CONTRACTS_DIR = 'apis';
+/** The rule name every contract-file failure is reported under. */
+exports.API_CONTRACT_FILES_RULE = 'validate-architecture-unchanged';
+/**
+ * What one `architecture:generate` pass did to the `apis/` directory, so the executor can say so.
+ */
+class ApiContractFilesWriteResult {
+    written;
+    deleted;
+    constructor(written, deleted) {
+        this.written = written;
+        this.deleted = deleted;
+    }
+}
+exports.ApiContractFilesWriteResult = ApiContractFilesWriteResult;
+/**
+ * Reads and writes the per-API contract files. All paths are resolved against the directory that
+ * holds dependencies.json (`graphPath`), so a non-default graphPath keeps its contracts beside it.
+ */
+class ApiContractFiles {
+    /** The link dependencies.json carries for one API: `apis/<ApiName>.json`. */
+    refFor(api) {
+        return `${exports.API_CONTRACTS_DIR}/${api}.json`;
+    }
+    /** The link table for every contract, in the contracts' (already sorted) order. */
+    refsFor(contracts) {
+        const refs = {};
+        for (const api of Object.keys(contracts).sort())
+            refs[api] = this.refFor(api);
+        return refs;
+    }
+    /**
+     * Write one file per contract and DELETE every `apis/*.json` whose API no longer exists, so a
+     * removed API never leaves a stale contract behind for the runtime graph to read.
+     */
+    write(workspaceRoot, graphPath, contracts) {
+        const dir = this.dirFor(workspaceRoot, graphPath);
+        const written = [];
+        const apis = Object.keys(contracts).sort();
+        if (apis.length > 0)
+            fs.mkdirSync(dir, { recursive: true });
+        for (const api of apis) {
+            const fullPath = path.join(dir, `${api}.json`);
+            fs.writeFileSync(fullPath, this.format(api, contracts[api]), 'utf-8');
+            written.push(fullPath);
+        }
+        const deleted = this.deleteStale(dir, new Set(apis));
+        return new ApiContractFilesWriteResult(written, deleted);
+    }
+    /**
+     * Load every contract dependencies.json links to. A missing or unreadable file FAILS: the runtime
+     * graph would otherwise silently lose that API's queues and triggers.
+     */
+    load(workspaceRoot, graphPath, refs) {
+        const baseDir = path.dirname(path.join(workspaceRoot, graphPath));
+        const contracts = {};
+        for (const api of Object.keys(refs).sort()) {
+            contracts[api] = this.loadOne(api, path.join(baseDir, refs[api]));
+        }
+        return contracts;
+    }
+    loadOne(api, fullPath) {
+        if (!fs.existsSync(fullPath)) {
+            throw new rules_config_1.RuleFailError(exports.API_CONTRACT_FILES_RULE, `dependencies.json links ${api} to ${fullPath}, but that file does not exist.`, undefined, undefined, [new rules_config_1.Option('Regenerate the architecture files: pnpm nx run architecture:generate', true)]);
+        }
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            const parsed = JSON.parse(fs.readFileSync(fullPath, 'utf-8'));
+            const contract = {
+                owner: parsed.owner,
+                apiKind: parsed.apiKind,
+                basePath: parsed.basePath,
+                methods: parsed.methods,
+            };
+            return contract;
+        }
+        catch (err) {
+            const error = (0, toError_1.toError)(err);
+            throw new rules_config_1.RuleFailError(exports.API_CONTRACT_FILES_RULE, `Could not read the ${api} contract file ${fullPath}: ${error.message}`, undefined, undefined, [new rules_config_1.Option('Regenerate the architecture files: pnpm nx run architecture:generate', true)], undefined, error);
+        }
+    }
+    /** Pretty, deterministic JSON: the api name first, then the contract in its declared field order. */
+    format(api, contract) {
+        const file = {
+            api,
+            owner: contract.owner,
+            apiKind: contract.apiKind,
+            basePath: contract.basePath,
+            methods: contract.methods,
+        };
+        return JSON.stringify(file, null, 4) + '\n';
+    }
+    dirFor(workspaceRoot, graphPath) {
+        return path.join(path.dirname(path.join(workspaceRoot, graphPath)), exports.API_CONTRACTS_DIR);
+    }
+    deleteStale(dir, keep) {
+        if (!fs.existsSync(dir))
+            return [];
+        const deleted = [];
+        for (const name of fs.readdirSync(dir).sort()) {
+            if (!name.endsWith('.json'))
+                continue;
+            if (keep.has(name.slice(0, -'.json'.length)))
+                continue;
+            const fullPath = path.join(dir, name);
+            fs.rmSync(fullPath);
+            deleted.push(fullPath);
+        }
+        if (fs.readdirSync(dir).length === 0)
+            fs.rmdirSync(dir);
+        return deleted;
+    }
+}
+exports.ApiContractFiles = ApiContractFiles;
+//# sourceMappingURL=api-contract-files.js.map

package/src/lib/api-contract-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-contract-files.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-contract-files.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Per-API contract files: `architecture/apis/<ApiName>.json`.\n *\n * WHY these exist (issue #949): the full endpoint contract used to live inside\n * architecture/dependencies.json under `apiContracts`, so adding ONE `@Endpoint` rewrote the project\n * dependency graph and failed validate-architecture-unchanged until `architecture:generate` was rerun.\n * dependencies.json is meant to change only when PROJECT dependencies change. Each API's contract now\n * lives in its own generated file, and dependencies.json only LINKS to it (`apiContractFiles`), so it\n * changes when an API is added or removed — never when an endpoint is.\n *\n * These files are written by `architecture:generate` and deliberately NOT drift-gated: nothing\n * compares them to source. The runtime graph (generate, validate-runtime-architecture) reads its\n * queue/trigger data from them.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { RuleFailError, Option } from '@webpieces/rules-config';\nimport type { ApiContract, ApiContracts } from './api-usage/api-relations';\nimport { toError } from '../toError';\n\n/** The directory, relative to dependencies.json's own directory, holding one file per API. */\nexport const API_CONTRACTS_DIR = 'apis';\n\n/** The rule name every contract-file failure is reported under. */\nexport const API_CONTRACT_FILES_RULE = 'validate-architecture-unchanged';\n\n/** apiClassName -> path of its contract file, RELATIVE to dependencies.json's directory. */\nexport type ApiContractFileRefs = Record<string, string>;\n\n/**\n * What one `architecture:generate` pass did to the `apis/` directory, so the executor can say so.\n */\nexport class ApiContractFilesWriteResult {\n    constructor(\n        public readonly written: string[],\n        public readonly deleted: string[],\n    ) {}\n}\n\n/**\n * Reads and writes the per-API contract files. All paths are resolved against the directory that\n * holds dependencies.json (`graphPath`), so a non-default graphPath keeps its contracts beside it.\n */\nexport class ApiContractFiles {\n    /** The link dependencies.json carries for one API: `apis/<ApiName>.json`. */\n    refFor(api: string): string {\n        return `${API_CONTRACTS_DIR}/${api}.json`;\n    }\n\n    /** The link table for every contract, in the contracts' (already sorted) order. */\n    refsFor(contracts: ApiContracts): ApiContractFileRefs {\n        const refs: ApiContractFileRefs = {};\n        for (const api of Object.keys(contracts).sort()) refs[api] = this.refFor(api);\n        return refs;\n    }\n\n    /**\n     * Write one file per contract and DELETE every `apis/*.json` whose API no longer exists, so a\n     * removed API never leaves a stale contract behind for the runtime graph to read.\n     */\n    write(workspaceRoot: string, graphPath: string, contracts: ApiContracts): ApiContractFilesWriteResult {\n        const dir = this.dirFor(workspaceRoot, graphPath);\n        const written: string[] = [];\n        const apis = Object.keys(contracts).sort();\n        if (apis.length > 0) fs.mkdirSync(dir, { recursive: true });\n        for (const api of apis) {\n            const fullPath = path.join(dir, `${api}.json`);\n            fs.writeFileSync(fullPath, this.format(api, contracts[api]), 'utf-8');\n            written.push(fullPath);\n        }\n        const deleted = this.deleteStale(dir, new Set(apis));\n        return new ApiContractFilesWriteResult(written, deleted);\n    }\n\n    /**\n     * Load every contract dependencies.json links to. A missing or unreadable file FAILS: the runtime\n     * graph would otherwise silently lose that API's queues and triggers.\n     */\n    load(workspaceRoot: string, graphPath: string, refs: ApiContractFileRefs): ApiContracts {\n        const baseDir = path.dirname(path.join(workspaceRoot, graphPath));\n        const contracts: ApiContracts = {};\n        for (const api of Object.keys(refs).sort()) {\n            contracts[api] = this.loadOne(api, path.join(baseDir, refs[api]));\n        }\n        return contracts;\n    }\n\n    private loadOne(api: string, fullPath: string): ApiContract {\n        if (!fs.existsSync(fullPath)) {\n            throw new RuleFailError(\n                API_CONTRACT_FILES_RULE,\n                `dependencies.json links ${api} to ${fullPath}, but that file does not exist.`,\n                undefined,\n                undefined,\n                [new Option('Regenerate the architecture files: pnpm nx run architecture:generate', true)],\n            );\n        }\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const parsed = JSON.parse(fs.readFileSync(fullPath, 'utf-8')) as ApiContractFileJson;\n            const contract: ApiContract = {\n                owner: parsed.owner,\n                apiKind: parsed.apiKind,\n                basePath: parsed.basePath,\n                methods: parsed.methods,\n            };\n            return contract;\n        } catch (err: unknown) {\n            const error = toError(err);\n            throw new RuleFailError(\n                API_CONTRACT_FILES_RULE,\n                `Could not read the ${api} contract file ${fullPath}: ${error.message}`,\n                undefined,\n                undefined,\n                [new Option('Regenerate the architecture files: pnpm nx run architecture:generate', true)],\n                undefined,\n                error,\n            );\n        }\n    }\n\n    /** Pretty, deterministic JSON: the api name first, then the contract in its declared field order. */\n    private format(api: string, contract: ApiContract): string {\n        const file: ApiContractFileJson = {\n            api,\n            owner: contract.owner,\n            apiKind: contract.apiKind,\n            basePath: contract.basePath,\n            methods: contract.methods,\n        };\n        return JSON.stringify(file, null, 4) + '\\n';\n    }\n\n    private dirFor(workspaceRoot: string, graphPath: string): string {\n        return path.join(path.dirname(path.join(workspaceRoot, graphPath)), API_CONTRACTS_DIR);\n    }\n\n    private deleteStale(dir: string, keep: Set<string>): string[] {\n        if (!fs.existsSync(dir)) return [];\n        const deleted: string[] = [];\n        for (const name of fs.readdirSync(dir).sort()) {\n            if (!name.endsWith('.json')) continue;\n            if (keep.has(name.slice(0, -'.json'.length))) continue;\n            const fullPath = path.join(dir, name);\n            fs.rmSync(fullPath);\n            deleted.push(fullPath);\n        }\n        if (fs.readdirSync(dir).length === 0) fs.rmdirSync(dir);\n        return deleted;\n    }\n}\n\n/** The on-disk shape of one `apis/<ApiName>.json`. Describes foreign JSON we narrow on read. */\ninterface ApiContractFileJson extends ApiContract {\n    api: string;\n}\n"]}

package/src/lib/api-usage/api-contract-errors.d.ts

@@ -1,5 +1,5 @@
 /**
- * The three ways `buildApiContracts` refuses to emit a green, wrong `apiContracts` table.
+ * The three ways `buildApiContracts` refuses to emit a green, wrong api contract table.
  *
  * All three share one rule: an entry that is PRESENT but incomplete is worse than an absent one.
  * Every other entry in the table is complete, so a consumer has no reason to suspect the one that

package/src/lib/api-usage/api-contract-errors.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * The three ways `buildApiContracts` refuses to emit a green, wrong `apiContracts` table.
+ * The three ways `buildApiContracts` refuses to emit a green, wrong api contract table.
  *
  * All three share one rule: an entry that is PRESENT but incomplete is worse than an absent one.
  * Every other entry in the table is complete, so a consumer has no reason to suspect the one that
@@ -22,7 +22,7 @@ class MissingBasePathError extends Error {
     constructor(contracts) {
         super(`${contracts.length} API contract(s) have @Endpoint methods but no readable @ApiPath basePath:\n` +
             contracts.map((c) => `     • ${c}`).join('\n') +
-            `\n   basePath is REQUIRED in apiContracts — an entry without it makes every consumer\n` +
+            `\n   basePath is REQUIRED in every api contract — an entry without it makes every consumer\n` +
             `   compute basePath + path as just path, silently. Inline the @ApiPath string literal,\n` +
             `   or move the constant into the same module as the contract class.`);
         this.contracts = contracts;
@@ -44,7 +44,7 @@ class UnresolvedEndpointPathError extends Error {
             paths
                 .map((p) => `     • ${p.api}.${p.method} — @Endpoint(${p.argument}, ...) at ${p.at}`)
                 .join('\n') +
-            `\n   path is REQUIRED in apiContracts — every consumer builds its request URL as\n` +
+            `\n   path is REQUIRED in every api contract — every consumer builds its request URL as\n` +
             `   basePath + path, so an unreadable path is MISSING ROUTING, not cosmetic metadata,\n` +
             `   and a class whose every path is unreadable drops out of the graph entirely.\n` +
             `   Inline the @Endpoint string literal, or move the constant into the SAME module as\n` +
@@ -99,7 +99,7 @@ class EmptiedApiContractError extends Error {
             contracts
                 .map((c) => `     • ${c.api} — ${c.declared} @Endpoint method(s) declared, 0 usable, at ${c.at}`)
                 .join('\n') +
-            `\n   A contract with zero usable methods is DROPPED from apiContracts, so the class,\n` +
+            `\n   A contract with zero usable methods is DROPPED from the api contracts, so the class,\n` +
             `   its queues and its triggers disappear from the architecture graph with no error.\n` +
             `   Both @Endpoint arguments must be readable: the path as a string literal or a\n` +
             `   SAME-module const, and the kind as a literal 'rpc' | 'cloudtasks' | 'cron' |\n` +

package/src/lib/api-usage/api-contract-errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-contract-errors.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-usage/api-contract-errors.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAIH;;;GAGG;AACH,MAAa,oBAAqB,SAAQ,KAAK;IACf;IAA5B,YAA4B,SAA4B;QACpD,KAAK,CACD,GAAG,SAAS,CAAC,MAAM,8EAA8E;YAC7F,SAAS,CAAC,GAAG,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YACtD,wFAAwF;YACxF,0FAA0F;YAC1F,qEAAqE,CAC5E,CAAC;QAPsB,cAAS,GAAT,SAAS,CAAmB;QAQpD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACvC,CAAC;CACJ;AAXD,oDAWC;AAED;;;;;;GAMG;AACH,MAAa,2BAA4B,SAAQ,KAAK;IACtB;IAA5B,YAA4B,KAAwC;QAChE,KAAK,CACD,GAAG,KAAK,CAAC,MAAM,qDAAqD;YAChE,KAAK;iBACA,GAAG,CACA,CAAC,CAAyB,EAAE,EAAE,CAC1B,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM,gBAAgB,CAAC,CAAC,QAAQ,aAAa,CAAC,CAAC,EAAE,EAAE,CAC/E;iBACA,IAAI,CAAC,IAAI,CAAC;YACf,oFAAoF;YACpF,wFAAwF;YACxF,kFAAkF;YAClF,wFAAwF;YACxF,sFAAsF;YACtF,yFAAyF;YACzF,6BAA6B,CACpC,CAAC;QAhBsB,UAAK,GAAL,KAAK,CAAmC;QAiBhE,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC9C,CAAC;CACJ;AApBD,kEAoBC;AAED;;;;;;;;;GASG;AACH,MAAa,6BAA8B,SAAQ,KAAK;IACxB;IAA5B,YAA4B,OAA4C;QACpE,KAAK,CACD,GAAG,OAAO,CAAC,MAAM,2DAA2D;YACxE,OAAO;iBACF,GAAG,CACA,CAAC,CAA2B,EAAE,EAAE,CAC5B,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM,MAAM,CAAC,CAAC,QAAQ,OAAO,CAAC,CAAC,EAAE,EAAE,CAC/D;iBACA,IAAI,CAAC,IAAI,CAAC;YACf,wFAAwF;YACxF,uEAAuE;YACvE,+DAA+D;YAC/D,yFAAyF;YACzF,sEAAsE;YACtE,0FAA0F;YAC1F,qFAAqF,CAC5F,CAAC;QAhBsB,YAAO,GAAP,OAAO,CAAqC;QAiBpE,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAChD,CAAC;CACJ;AApBD,sEAoBC;AAED;;;;;;GAMG;AACH,MAAa,uBAAwB,SAAQ,KAAK;IAClB;IAA5B,YAA4B,SAAwC;QAChE,KAAK,CACD,GAAG,SAAS,CAAC,MAAM,4EAA4E;YAC3F,SAAS;iBACJ,GAAG,CACA,CAAC,CAAqB,EAAE,EAAE,CACtB,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,QAAQ,+CAA+C,CAAC,CAAC,EAAE,EAAE,CAC3F;iBACA,IAAI,CAAC,IAAI,CAAC;YACf,wFAAwF;YACxF,uFAAuF;YACvF,mFAAmF;YACnF,mFAAmF;YACnF,qFAAqF;YACrF,mCAAmC,CAC1C,CAAC;QAfsB,cAAS,GAAT,SAAS,CAA+B;QAgBhE,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IAC1C,CAAC;CACJ;AAnBD,0DAmBC","sourcesContent":["/**\n * The three ways `buildApiContracts` refuses to emit a green, wrong `apiContracts` table.\n *\n * All three share one rule: an entry that is PRESENT but incomplete is worse than an absent one.\n * Every other entry in the table is complete, so a consumer has no reason to suspect the one that\n * lost a field — it just computes a confidently wrong URL, or draws a service with no queues.\n *\n * Each aggregates EVERY offender into one message rather than throwing on the first: an author who\n * moved a constants module broke five decorators at once and wants all five named in one run.\n *\n * Split out of api-scanner.ts, which owns the scan itself and is at its file-size limit.\n */\n\nimport { EmptiedApiContract, UndeclaredExternalCaller, UnresolvedEndpointPath } from './api-relations';\n\n/**\n * A routed contract whose `@ApiPath` argument the scan could not read. Fatal on purpose: shipping the\n * entry without its basePath is what made `/whatsapp/test` render as `/test` in a downstream runbook.\n */\nexport class MissingBasePathError extends Error {\n    constructor(public readonly contracts: readonly string[]) {\n        super(\n            `${contracts.length} API contract(s) have @Endpoint methods but no readable @ApiPath basePath:\\n` +\n                contracts.map((c: string) => `     • ${c}`).join('\\n') +\n                `\\n   basePath is REQUIRED in apiContracts — an entry without it makes every consumer\\n` +\n                `   compute basePath + path as just path, silently. Inline the @ApiPath string literal,\\n` +\n                `   or move the constant into the same module as the contract class.`,\n        );\n        this.name = 'MissingBasePathError';\n    }\n}\n\n/**\n * `@Endpoint` paths the scan could not read. Fatal for the same reason MissingBasePathError is: the\n * two arguments are the two halves of ONE url. An http client builds its request as\n * `basePath + path`, so a contract shipped without a method's path is missing routing information,\n * and the consumer computes a confidently wrong URL. Skipping the method instead was worse still —\n * a class whose every path was an unreadable constant lost every method and vanished from the graph.\n */\nexport class UnresolvedEndpointPathError extends Error {\n    constructor(public readonly paths: readonly UnresolvedEndpointPath[]) {\n        super(\n            `${paths.length} @Endpoint path(s) could not be read as a string:\\n` +\n                paths\n                    .map(\n                        (p: UnresolvedEndpointPath) =>\n                            `     • ${p.api}.${p.method} — @Endpoint(${p.argument}, ...) at ${p.at}`,\n                    )\n                    .join('\\n') +\n                `\\n   path is REQUIRED in apiContracts — every consumer builds its request URL as\\n` +\n                `   basePath + path, so an unreadable path is MISSING ROUTING, not cosmetic metadata,\\n` +\n                `   and a class whose every path is unreadable drops out of the graph entirely.\\n` +\n                `   Inline the @Endpoint string literal, or move the constant into the SAME module as\\n` +\n                `   the contract class — a same-module const IS resolved, one imported from another\\n` +\n                `   module is NOT (this scan is parser-only by design: module resolution can land on a\\n` +\n                `   decorator-erased .d.ts).`,\n        );\n        this.name = 'UnresolvedEndpointPathError';\n    }\n}\n\n/**\n * `external` endpoints whose CALLER the scan could not read. Fatal, like the two above, because the\n * alternative is a diagram that lies by omission: the inbound box exists solely to name the system\n * calling us from outside, and with nothing to name it falls back to restating our own contract\n * name — which the reader already sees on the service box the arrow points at.\n *\n * `@Endpoint`'s TS overloads make `calledBy` a compile error to omit, so a scan reaching here saw a\n * JS caller, an `as any`, a cross-module constant this parser-only pass cannot fold, or a\n * `callerKind` that is not one of the declared kinds.\n */\nexport class UndeclaredExternalCallerError extends Error {\n    constructor(public readonly callers: readonly UndeclaredExternalCaller[]) {\n        super(\n            `${callers.length} 'external' @Endpoint(s) do not declare WHO calls them:\\n` +\n                callers\n                    .map(\n                        (c: UndeclaredExternalCaller) =>\n                            `     • ${c.api}.${c.method} — ${c.argument} at ${c.at}`,\n                    )\n                    .join('\\n') +\n                `\\n   An 'external' endpoint is driven by a system OUTSIDE this repo, and the runtime\\n` +\n                `   architecture graph draws that system as an inbound box. Name it:\\n` +\n                `     @Endpoint('/hook', 'external', { calledBy: 'twilio' })\\n` +\n                `   Add callerKind for anything that is not a vendor SaaS — database | cache | queue |\\n` +\n                `   storage | saas | system — e.g. a GCP Pub/Sub push subscription:\\n` +\n                `     @Endpoint('/push', 'external', { calledBy: 'pubsub-push', callerKind: 'system' })\\n` +\n                `   Use a string LITERAL or a SAME-module const: this scan is parser-only by design.`,\n        );\n        this.name = 'UndeclaredExternalCallerError';\n    }\n}\n\n/**\n * Contract classes that declared `@Endpoint` methods and kept none of them. Fatal because the\n * alternative is the silent drop the api scan exists to close: buildApiContracts legitimately skips\n * a zero-method class (a vendor seam has no routes), and a class gutted by unreadable decorator\n * arguments used the very same exit — which is how a service lost two real Cloud Tasks queues and an\n * inbound webhook without a single line of output.\n */\nexport class EmptiedApiContractError extends Error {\n    constructor(public readonly contracts: readonly EmptiedApiContract[]) {\n        super(\n            `${contracts.length} API contract class(es) declare @Endpoint methods but kept NONE of them:\\n` +\n                contracts\n                    .map(\n                        (c: EmptiedApiContract) =>\n                            `     • ${c.api} — ${c.declared} @Endpoint method(s) declared, 0 usable, at ${c.at}`,\n                    )\n                    .join('\\n') +\n                `\\n   A contract with zero usable methods is DROPPED from apiContracts, so the class,\\n` +\n                `   its queues and its triggers disappear from the architecture graph with no error.\\n` +\n                `   Both @Endpoint arguments must be readable: the path as a string literal or a\\n` +\n                `   SAME-module const, and the kind as a literal 'rpc' | 'cloudtasks' | 'cron' |\\n` +\n                `   'external'. Fix the arguments above, or remove the @Endpoint decorators if the\\n` +\n                `   class is genuinely not routed.`,\n        );\n        this.name = 'EmptiedApiContractError';\n    }\n}\n"]}
+{"version":3,"file":"api-contract-errors.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-usage/api-contract-errors.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAIH;;;GAGG;AACH,MAAa,oBAAqB,SAAQ,KAAK;IACf;IAA5B,YAA4B,SAA4B;QACpD,KAAK,CACD,GAAG,SAAS,CAAC,MAAM,8EAA8E;YAC7F,SAAS,CAAC,GAAG,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YACtD,8FAA8F;YAC9F,0FAA0F;YAC1F,qEAAqE,CAC5E,CAAC;QAPsB,cAAS,GAAT,SAAS,CAAmB;QAQpD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACvC,CAAC;CACJ;AAXD,oDAWC;AAED;;;;;;GAMG;AACH,MAAa,2BAA4B,SAAQ,KAAK;IACtB;IAA5B,YAA4B,KAAwC;QAChE,KAAK,CACD,GAAG,KAAK,CAAC,MAAM,qDAAqD;YAChE,KAAK;iBACA,GAAG,CACA,CAAC,CAAyB,EAAE,EAAE,CAC1B,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM,gBAAgB,CAAC,CAAC,QAAQ,aAAa,CAAC,CAAC,EAAE,EAAE,CAC/E;iBACA,IAAI,CAAC,IAAI,CAAC;YACf,0FAA0F;YAC1F,wFAAwF;YACxF,kFAAkF;YAClF,wFAAwF;YACxF,sFAAsF;YACtF,yFAAyF;YACzF,6BAA6B,CACpC,CAAC;QAhBsB,UAAK,GAAL,KAAK,CAAmC;QAiBhE,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC9C,CAAC;CACJ;AApBD,kEAoBC;AAED;;;;;;;;;GASG;AACH,MAAa,6BAA8B,SAAQ,KAAK;IACxB;IAA5B,YAA4B,OAA4C;QACpE,KAAK,CACD,GAAG,OAAO,CAAC,MAAM,2DAA2D;YACxE,OAAO;iBACF,GAAG,CACA,CAAC,CAA2B,EAAE,EAAE,CAC5B,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM,MAAM,CAAC,CAAC,QAAQ,OAAO,CAAC,CAAC,EAAE,EAAE,CAC/D;iBACA,IAAI,CAAC,IAAI,CAAC;YACf,wFAAwF;YACxF,uEAAuE;YACvE,+DAA+D;YAC/D,yFAAyF;YACzF,sEAAsE;YACtE,0FAA0F;YAC1F,qFAAqF,CAC5F,CAAC;QAhBsB,YAAO,GAAP,OAAO,CAAqC;QAiBpE,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAChD,CAAC;CACJ;AApBD,sEAoBC;AAED;;;;;;GAMG;AACH,MAAa,uBAAwB,SAAQ,KAAK;IAClB;IAA5B,YAA4B,SAAwC;QAChE,KAAK,CACD,GAAG,SAAS,CAAC,MAAM,4EAA4E;YAC3F,SAAS;iBACJ,GAAG,CACA,CAAC,CAAqB,EAAE,EAAE,CACtB,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,QAAQ,+CAA+C,CAAC,CAAC,EAAE,EAAE,CAC3F;iBACA,IAAI,CAAC,IAAI,CAAC;YACf,6FAA6F;YAC7F,uFAAuF;YACvF,mFAAmF;YACnF,mFAAmF;YACnF,qFAAqF;YACrF,mCAAmC,CAC1C,CAAC;QAfsB,cAAS,GAAT,SAAS,CAA+B;QAgBhE,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IAC1C,CAAC;CACJ;AAnBD,0DAmBC","sourcesContent":["/**\n * The three ways `buildApiContracts` refuses to emit a green, wrong api contract table.\n *\n * All three share one rule: an entry that is PRESENT but incomplete is worse than an absent one.\n * Every other entry in the table is complete, so a consumer has no reason to suspect the one that\n * lost a field — it just computes a confidently wrong URL, or draws a service with no queues.\n *\n * Each aggregates EVERY offender into one message rather than throwing on the first: an author who\n * moved a constants module broke five decorators at once and wants all five named in one run.\n *\n * Split out of api-scanner.ts, which owns the scan itself and is at its file-size limit.\n */\n\nimport { EmptiedApiContract, UndeclaredExternalCaller, UnresolvedEndpointPath } from './api-relations';\n\n/**\n * A routed contract whose `@ApiPath` argument the scan could not read. Fatal on purpose: shipping the\n * entry without its basePath is what made `/whatsapp/test` render as `/test` in a downstream runbook.\n */\nexport class MissingBasePathError extends Error {\n    constructor(public readonly contracts: readonly string[]) {\n        super(\n            `${contracts.length} API contract(s) have @Endpoint methods but no readable @ApiPath basePath:\\n` +\n                contracts.map((c: string) => `     • ${c}`).join('\\n') +\n                `\\n   basePath is REQUIRED in every api contract — an entry without it makes every consumer\\n` +\n                `   compute basePath + path as just path, silently. Inline the @ApiPath string literal,\\n` +\n                `   or move the constant into the same module as the contract class.`,\n        );\n        this.name = 'MissingBasePathError';\n    }\n}\n\n/**\n * `@Endpoint` paths the scan could not read. Fatal for the same reason MissingBasePathError is: the\n * two arguments are the two halves of ONE url. An http client builds its request as\n * `basePath + path`, so a contract shipped without a method's path is missing routing information,\n * and the consumer computes a confidently wrong URL. Skipping the method instead was worse still —\n * a class whose every path was an unreadable constant lost every method and vanished from the graph.\n */\nexport class UnresolvedEndpointPathError extends Error {\n    constructor(public readonly paths: readonly UnresolvedEndpointPath[]) {\n        super(\n            `${paths.length} @Endpoint path(s) could not be read as a string:\\n` +\n                paths\n                    .map(\n                        (p: UnresolvedEndpointPath) =>\n                            `     • ${p.api}.${p.method} — @Endpoint(${p.argument}, ...) at ${p.at}`,\n                    )\n                    .join('\\n') +\n                `\\n   path is REQUIRED in every api contract — every consumer builds its request URL as\\n` +\n                `   basePath + path, so an unreadable path is MISSING ROUTING, not cosmetic metadata,\\n` +\n                `   and a class whose every path is unreadable drops out of the graph entirely.\\n` +\n                `   Inline the @Endpoint string literal, or move the constant into the SAME module as\\n` +\n                `   the contract class — a same-module const IS resolved, one imported from another\\n` +\n                `   module is NOT (this scan is parser-only by design: module resolution can land on a\\n` +\n                `   decorator-erased .d.ts).`,\n        );\n        this.name = 'UnresolvedEndpointPathError';\n    }\n}\n\n/**\n * `external` endpoints whose CALLER the scan could not read. Fatal, like the two above, because the\n * alternative is a diagram that lies by omission: the inbound box exists solely to name the system\n * calling us from outside, and with nothing to name it falls back to restating our own contract\n * name — which the reader already sees on the service box the arrow points at.\n *\n * `@Endpoint`'s TS overloads make `calledBy` a compile error to omit, so a scan reaching here saw a\n * JS caller, an `as any`, a cross-module constant this parser-only pass cannot fold, or a\n * `callerKind` that is not one of the declared kinds.\n */\nexport class UndeclaredExternalCallerError extends Error {\n    constructor(public readonly callers: readonly UndeclaredExternalCaller[]) {\n        super(\n            `${callers.length} 'external' @Endpoint(s) do not declare WHO calls them:\\n` +\n                callers\n                    .map(\n                        (c: UndeclaredExternalCaller) =>\n                            `     • ${c.api}.${c.method} — ${c.argument} at ${c.at}`,\n                    )\n                    .join('\\n') +\n                `\\n   An 'external' endpoint is driven by a system OUTSIDE this repo, and the runtime\\n` +\n                `   architecture graph draws that system as an inbound box. Name it:\\n` +\n                `     @Endpoint('/hook', 'external', { calledBy: 'twilio' })\\n` +\n                `   Add callerKind for anything that is not a vendor SaaS — database | cache | queue |\\n` +\n                `   storage | saas | system — e.g. a GCP Pub/Sub push subscription:\\n` +\n                `     @Endpoint('/push', 'external', { calledBy: 'pubsub-push', callerKind: 'system' })\\n` +\n                `   Use a string LITERAL or a SAME-module const: this scan is parser-only by design.`,\n        );\n        this.name = 'UndeclaredExternalCallerError';\n    }\n}\n\n/**\n * Contract classes that declared `@Endpoint` methods and kept none of them. Fatal because the\n * alternative is the silent drop the api scan exists to close: buildApiContracts legitimately skips\n * a zero-method class (a vendor seam has no routes), and a class gutted by unreadable decorator\n * arguments used the very same exit — which is how a service lost two real Cloud Tasks queues and an\n * inbound webhook without a single line of output.\n */\nexport class EmptiedApiContractError extends Error {\n    constructor(public readonly contracts: readonly EmptiedApiContract[]) {\n        super(\n            `${contracts.length} API contract class(es) declare @Endpoint methods but kept NONE of them:\\n` +\n                contracts\n                    .map(\n                        (c: EmptiedApiContract) =>\n                            `     • ${c.api} — ${c.declared} @Endpoint method(s) declared, 0 usable, at ${c.at}`,\n                    )\n                    .join('\\n') +\n                `\\n   A contract with zero usable methods is DROPPED from the api contracts, so the class,\\n` +\n                `   its queues and its triggers disappear from the architecture graph with no error.\\n` +\n                `   Both @Endpoint arguments must be readable: the path as a string literal or a\\n` +\n                `   SAME-module const, and the kind as a literal 'rpc' | 'cloudtasks' | 'cron' |\\n` +\n                `   'external'. Fix the arguments above, or remove the @Endpoint decorators if the\\n` +\n                `   class is genuinely not routed.`,\n        );\n        this.name = 'EmptiedApiContractError';\n    }\n}\n"]}

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

@@ -190,10 +190,11 @@ export interface ExternalSystemDeclaration {
     label: string;
 }
 /**
- * The committed, per-contract view written to `architecture/dependencies.json` under `apiContracts`.
+ * The committed, per-contract view written to `architecture/apis/<ApiName>.json` (one file per API;
+ * dependencies.json only links to it under `apiContractFiles` — see ApiContractFiles).
  *
- * The runtime graph is derived SOLELY from dependencies.json so generate and validate can never
- * diverge — which means anything the runtime graph needs must be COMMITTED there, not re-scanned.
+ * The runtime graph is derived from the committed files so generate and validate can never
+ * diverge — which means anything the runtime graph needs must be COMMITTED, not re-scanned.
  * Per-method trigger kinds and queue names are exactly that: without this table the derivation
  * cannot tell a queued endpoint from a cron sweep, and cannot name the queue between two services.
  */
@@ -211,7 +212,7 @@ export interface ApiContract {
     basePath: string;
     methods: ApiMethodMeta[];
 }
-/** apiClassName -> its committed contract. Serialized as the `apiContracts` key. */
+/** apiClassName -> its committed contract. Serialized as one `architecture/apis/<ApiName>.json` each. */
 export type ApiContracts = Record<string, ApiContract>;
 /**
  * ONE decorator argument the scan saw but could not reduce to a string — `@ApiPath(SOME_CONST)`
@@ -252,7 +253,7 @@ export declare class NonLiteralDecoratorArg {
  * this one is FATAL. Upstream components need the URL: an http client builds its request as
  * `basePath + path`, so an unreadable path is missing ROUTING, not missing metadata — the same
  * reasoning that already makes basePath required. Skipping the method instead used to delete it, and
- * a class whose every path was a constant lost every method and vanished from `apiContracts` with
+ * a class whose every path was a constant lost every method and vanished from the contract table with
  * nothing printed anywhere.
  */
 export declare class UnresolvedEndpointPath {

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

@@ -104,7 +104,7 @@ exports.NonLiteralDecoratorArg = NonLiteralDecoratorArg;
  * this one is FATAL. Upstream components need the URL: an http client builds its request as
  * `basePath + path`, so an unreadable path is missing ROUTING, not missing metadata — the same
  * reasoning that already makes basePath required. Skipping the method instead used to delete it, and
- * a class whose every path was a constant lost every method and vanished from `apiContracts` with
+ * a class whose every path was a constant lost every method and vanished from the contract table with
  * nothing printed anywhere.
  */
 class UnresolvedEndpointPath {

package/src/lib/api-usage/api-relations.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-relations.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-usage/api-relations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * API Relations model\n *\n * The typed classification of a compile-time dependency edge P -> apiLib in\n * architecture/dependencies.json. Where the flat `dependsOn` only says \"P depends\n * on apiLib\", `apiRelations[apiLib]` says WHY: which API contracts P IMPLEMENTS\n * (serves, `class Ctrl extends XxxApi`) and which it USES (calls as a client,\n * `factory.createRpcClient(XxxApi, ...)` / `createPubSubClient(...)`), each tagged\n * with its transport.\n *\n * Interfaces + object literals here mirror the sibling runtime-graph.ts model —\n * these are serialization DTOs written verbatim into the committed JSON, and\n * `implements`/`uses` are legal interface property names (they are reserved words\n * only as binding identifiers, not as member names).\n */\n\n/**\n * Transport of an API contract:\n *  - `rpc`      — synchronous request/response over HTTP\n *  - `pubsub`   — fire-and-forget, delivered later through a Cloud Tasks queue\n *  - `external` — a contract for a system OUTSIDE this repo (firestore, gmail, ...). Nothing in-repo\n *                 implements it, so it never becomes a service→service edge; it terminates the graph\n *                 at a dashed vendor node. Detected from `runtime-architecture.externalApiPaths`\n *                 rather than from a decorator, because a vendor contract is a plain interface bound\n *                 to a Symbol token, not an `abstract class` carrying @ApiPath.\n */\nexport type ApiTransport = 'rpc' | 'pubsub' | 'external';\n\n/**\n * The kinds an external system can be DECLARED as. Each draws its own shape in the runtime viz, so\n * a datastore stops looking like an HTTP service.\n *\n * Lives here rather than beside the runtime graph model because that model already imports from this\n * file; putting it there and importing back would close a module cycle.\n */\nexport const EXTERNAL_SYSTEM_KINDS = [\n    'database',\n    'cache',\n    'queue',\n    'storage',\n    'saas',\n    'system',\n    /**\n     * A destination whose ADDRESS is supplied at runtime — a URL a partner registered, an OAuth\n     * callback, a per-tenant host. Unlike every other kind it does not name one vendor: it names the\n     * PLACE in our own system where somebody else's address is dialled, which is the fact a security\n     * review is looking for.\n     *\n     * Declared like every other kind, on the CONTRACT: `@externalSystem runtime partner-webhooks`.\n     * On the contract rather than at a `createRpcClient` call site deliberately — \"the far end of\n     * this contract is outside our estate\" is a property of the CONTRACT, true for every caller of\n     * it, so putting it there means one declaration however many services deliver over it, and\n     * nothing to keep in step when a second one appears. It also means this kind rides the exact\n     * same declare → resolve → draw pipeline `saas` and `database` already ride, rather than a\n     * second mechanism that reads construction sites and can disagree with the first.\n     */\n    'runtime',\n] as const;\n\nexport type ExternalSystemKind = (typeof EXTERNAL_SYSTEM_KINDS)[number];\n\n/** True for a string that names one of {@link EXTERNAL_SYSTEM_KINDS}. */\n// webpieces-disable no-function-outside-class -- type guard beside the type it guards, matching this file's DTO style\nexport function isExternalSystemKind(value: string): value is ExternalSystemKind {\n    return (EXTERNAL_SYSTEM_KINDS as readonly string[]).includes(value);\n}\n\n/**\n * ONE declared external system, keyed in {@link ExternalSystemDecls} by its IDENTITY.\n *\n * Identity, not display text: two projects each tagged `external:database:postgres` name the same\n * `postgres` node and converge on it with one arrow apiece, instead of drawing a database each.\n *\n * The two arrays are the two declaration sites, and a system may legitimately have both — a repo can\n * wrap a datastore behind a contract in one service and open it directly in another.\n */\nexport interface ExternalSystemDecl {\n    kind: ExternalSystemKind;\n    label: string;\n    /** Contracts declaring it with an `@externalSystem` JSDoc tag; every user of one gets an arrow. */\n    apis: string[];\n    /** Projects declaring it with an `external:<kind>:<identity>` nx tag; each gets its OWN arrow. */\n    projects: string[];\n}\n\n/** identity -> its declaration. Serialized as the `externalSystems` key of dependencies.json. */\nexport type ExternalSystemDecls = Record<string, ExternalSystemDecl>;\n\n/**\n * How a project relates to ONE api-lib it depends on:\n *  - `implements`       — it serves the api (a controller extends it)\n *  - `uses`             — it calls the api (generates a client)\n *  - `uses-implements`  — it does BOTH (implements some of the api-lib's contracts,\n *                          uses others)\n */\nexport type ApiRelationKind = 'implements' | 'uses' | 'uses-implements';\n\n/** One API class a project implements or uses, with its transport. */\nexport interface ApiRef {\n    api: string;\n    type: ApiTransport;\n    /**\n     * ONLY on a `uses` ref: the service the call site aims at, read from the client config literal\n     * (`createRpcClient(XxxApi, new ClientConfig('helper-fsdb'))` → `helper-fsdb`). It is matched\n     * against a project's DECLARED `serviceName` to pick the ONE runtime edge target, instead of\n     * fanning the edge out to every implementer of the api — which is catastrophically wrong for a\n     * company-wide contract registered in a shared library and therefore implemented by every server.\n     *\n     * Absent when the config argument is not a `new <Xxx>ClientConfig('<literal>')` (a variable, a\n     * computed name, ...). Absent means \"unknown target\", NOT \"no target\" — the runtime graph then\n     * falls back to the old fan-out and says so out loud.\n     */\n    targetService?: string;\n    /**\n     * ONLY on a `pubsub` uses ref. True means \"this producer was attributed to EVERY cloudtasks\n     * method of the contract, not to the methods it actually enqueues\".\n     *\n     * A producer builds one client for the whole contract (`createPubSubClient(EmailTaskApi, cfg)`)\n     * and enqueues through a proxy (`emailTasks.send(req)`) somewhere else entirely — often after\n     * the client has been stored in a DI binding — so WHICH methods it enqueues is not statically\n     * recoverable. The consumer side IS exact (addRoutes + the contract's method table). Recording\n     * the difference keeps a producer-side queue from being read as proof that queue is used.\n     */\n    methodsInferred?: boolean;\n}\n\n/**\n * Identity of a ref for de-duplication: an api used twice against DIFFERENT services is two distinct\n * relations (two distinct runtime edges), so the api name alone is not the key.\n */\n// webpieces-disable no-function-outside-class -- pure data helper for these serialization DTOs\nexport function apiRefKey(ref: ApiRef): string {\n    return `${ref.api} ${ref.targetService ?? ''}`;\n}\n\n/**\n * A project's relationship to ONE api-lib it depends on. Serialized verbatim into\n * architecture/dependencies.json under `apiRelations[apiLibProjectName]`.\n */\nexport interface ApiRelation {\n    kind: ApiRelationKind;\n    implements: ApiRef[];\n    uses: ApiRef[];\n}\n\n/** apiLibProjectName -> relation. Attached to a GraphEntry as `apiRelations`. */\nexport type ProjectApiRelations = Record<string, ApiRelation>;\n\n/**\n * What triggers ONE endpoint, mirroring core-util's `EndpointKind`. Duplicated as a string union\n * rather than imported: nx-webpieces-rules is build tooling and must not take a runtime dependency\n * on the framework it inspects (it reads decorators as TEXT, from projects that may be on a\n * different @webpieces version than the tooling itself).\n */\nexport type EndpointKind = 'rpc' | 'cloudtasks' | 'cron' | 'external';\n\n/** HTTP verbs understood by the generated contract runtime. */\nexport type ContractHttpMethod = 'GET' | 'POST';\n\n/** One path/query/body mapping emitted into architecture/dependencies.json. */\nexport interface ApiParameterMeta {\n    index: number;\n    source: 'path' | 'query' | 'body';\n    /** Path/query wire name; a JSON/form body occupies the whole entity and has no key. */\n    wireName?: string;\n}\n\n/**\n * One method on an API contract, as written in source: what triggers it, where it is mounted, and\n * (for a queued method) which Cloud Tasks queue delivers it.\n */\nexport interface ApiMethodMeta {\n    name: string;\n    /** The @Endpoint path, relative to the class's @ApiPath basePath. */\n    path: string;\n    kind: EndpointKind;\n    /** The actual incoming/outgoing verb; POST when @Endpoint omits httpMethod. */\n    httpMethod?: ContractHttpMethod;\n    /** Explicit parameter mappings; absent only when the method has none. */\n    parameters?: ApiParameterMeta[];\n    /** Present when callers receive the transport-neutral full response. */\n    responseType?: 'full';\n    /**\n     * `@Queue(...)` override, else `${ApiClassName}-${methodName}`.\n     *\n     * ONLY on a `cloudtasks` or `cron` method — those are the kinds actually delivered through a\n     * named queue or schedule, and Terraform matches on this string. A synchronous `rpc` (or an\n     * inbound `external`) endpoint has no queue and needs none; emitting a plausible-looking name for\n     * one put every synchronous endpoint one naive `methods.map(m => m.queueName)` away from being\n     * provisioned as a queue.\n     */\n    queueName?: string;\n    /**\n     * WHO outside this repo drives this endpoint, from `@Endpoint(p, 'external', { calledBy })`.\n     *\n     * ONLY on an `external` method, the same way `queueName` is only on the kinds that HAVE a queue.\n     *\n     * Deliberately the SAME {@link ExternalSystemDeclaration} the OUTBOUND `@externalSystem` tag\n     * resolves to, not a parallel inbound-only type: an inbound `saas twilio` and an outbound\n     * `saas twilio` are the same vendor, so sharing the type makes them share an IDENTITY and\n     * converge on ONE node instead of drawing twilio twice facing opposite directions.\n     *\n     * Optional in the TYPE only for graphs generated before the caller was required — generation\n     * FAILS on an `external` method whose caller cannot be read (UndeclaredExternalCallerError).\n     */\n    caller?: ExternalSystemDeclaration;\n}\n\n/**\n * A discovered API contract class: its name, the api-lib project that owns it, its transport, and\n * its per-method trigger table.\n */\nexport interface ApiClassInfo {\n    api: string;\n    owner: string;\n    type: ApiTransport;\n    /** The class's @ApiPath basePath; absent for an external (vendor) contract, which has no route. */\n    basePath?: string;\n    /**\n     * Every @Endpoint method, in declaration order. Empty for an external contract (a vendor\n     * interface has no endpoints — it is called through a vendor SDK, not mounted).\n     */\n    methods: ApiMethodMeta[];\n    /**\n     * Set when the contract carries an `@externalSystem <kind> [label]` JSDoc tag — a vendor seam\n     * declaring WHAT it is a seam to. JSDoc rather than a decorator because these seams are plain TS\n     * `interface`s, which cannot carry one.\n     */\n    externalSystem?: ExternalSystemDeclaration;\n}\n\n/** The `(kind, label)` pair a single declaration resolves to. */\nexport interface ExternalSystemDeclaration {\n    kind: ExternalSystemKind;\n    label: string;\n}\n\n/**\n * The committed, per-contract view written to `architecture/dependencies.json` under `apiContracts`.\n *\n * The runtime graph is derived SOLELY from dependencies.json so generate and validate can never\n * diverge — which means anything the runtime graph needs must be COMMITTED there, not re-scanned.\n * Per-method trigger kinds and queue names are exactly that: without this table the derivation\n * cannot tell a queued endpoint from a cron sweep, and cannot name the queue between two services.\n */\nexport interface ApiContract {\n    owner: string;\n    /** 'rpc' | 'pubsub' for an in-repo contract, 'external' for a vendor seam. */\n    apiKind: ApiTransport;\n    /**\n     * REQUIRED. Every routed contract carries `@ApiPath`, so every entry in this table must carry the\n     * base path its methods hang off. Optional was worse than absent: a consumer joining\n     * `basePath + path` for the ONE entry that lost it computed `/test` where the real route was\n     * `/whatsapp/test`, and had no reason to suspect it — every other entry had the field. Generation\n     * now FAILS instead of shipping an entry that computes a confidently wrong URL.\n     */\n    basePath: string;\n    methods: ApiMethodMeta[];\n}\n\n/** apiClassName -> its committed contract. Serialized as the `apiContracts` key. */\nexport type ApiContracts = Record<string, ApiContract>;\n\n/**\n * ONE decorator argument the scan saw but could not reduce to a string — `@ApiPath(SOME_CONST)`\n * where SOME_CONST is imported from another module, a computed expression, an enum member, ...\n *\n * Recorded rather than dropped. Before this existed, an unresolvable argument cost the contract its\n * basePath, or a method, or (when EVERY method's path was one) the whole class — with nothing\n * printed anywhere. Same-module constants now resolve, so what remains here is the genuinely\n * unresolvable, which the author can fix by inlining the literal or moving the constant in-module.\n */\nexport class NonLiteralDecoratorArg {\n    constructor(\n        /** The contract class the argument was written on. */\n        public readonly api: string,\n        /** `ApiPath` | `Endpoint` | `Queue`. */\n        public readonly decorator: string,\n        /** The method name for a member decorator, null for a class decorator. */\n        public readonly method: string | null,\n        /** The argument exactly as written, e.g. `WHATSAPP_API_PATH`. */\n        public readonly argument: string,\n        /** `path/to/file.ts:LINE`, workspace-relative. */\n        public readonly at: string,\n    ) {}\n}\n\n/**\n * ONE `@Endpoint(path, kind)` whose PATH argument was present but could not be reduced to a string.\n *\n * Split out of NonLiteralDecoratorArg (which stays a warning, covering @Queue and the rest) because\n * this one is FATAL. Upstream components need the URL: an http client builds its request as\n * `basePath + path`, so an unreadable path is missing ROUTING, not missing metadata — the same\n * reasoning that already makes basePath required. Skipping the method instead used to delete it, and\n * a class whose every path was a constant lost every method and vanished from `apiContracts` with\n * nothing printed anywhere.\n */\nexport class UnresolvedEndpointPath {\n    constructor(\n        /** The contract class the method is declared on. */\n        public readonly api: string,\n        /** The method name. */\n        public readonly method: string,\n        /** The path argument exactly as written, e.g. `PROCESS_PATH`. */\n        public readonly argument: string,\n        /** `path/to/file.ts:LINE`, workspace-relative. */\n        public readonly at: string,\n    ) {}\n}\n\n/**\n * ONE `external` `@Endpoint` whose CALLER could not be read from the source.\n *\n * Fatal for the same reason {@link UnresolvedEndpointPath} is. The inbound box exists to say who is\n * calling us from outside; with no caller it can only restate our own contract name, which is the\n * exact bug this diagnostic exists to make impossible to reintroduce. `@Endpoint`'s TS overloads\n * already require `calledBy`, so anything reaching here is a JS caller, an `as any`, a cross-module\n * constant the parser-only scan cannot fold, or an unknown `callerKind`.\n */\nexport class UndeclaredExternalCaller {\n    constructor(\n        /** The contract class the method is declared on. */\n        public readonly api: string,\n        /** The method name. */\n        public readonly method: string,\n        /** What was wrong, as written — `<missing>`, `SOME_CONST`, `callerKind: 'vendor'`. */\n        public readonly argument: string,\n        /** `path/to/file.ts:LINE`, workspace-relative. */\n        public readonly at: string,\n    ) {}\n}\n\n/**\n * A contract class that DECLARED `@Endpoint` methods and kept none of them.\n *\n * The backstop for the mechanism that hid an entire service: `buildApiContracts` skips a zero-method\n * class (correctly — a vendor seam has no routes), so a class gutted by unreadable decorator\n * arguments left through the same door as a legitimately routeless one. A class that declared\n * endpoints and produced none is never legitimate, so it is named instead.\n */\nexport class EmptiedApiContract {\n    constructor(\n        /** The contract class name. */\n        public readonly api: string,\n        /** How many `@Endpoint` decorators were written on it. */\n        public readonly declared: number,\n        /** `path/to/file.ts:LINE` of the class, workspace-relative. */\n        public readonly at: string,\n    ) {}\n}\n\n/** Derive the relation kind from the (possibly empty) implements/uses ref lists. */\n// webpieces-disable no-function-outside-class -- pure data helper for these serialization DTOs\nexport function deriveApiRelationKind(\n    implementsRefs: ApiRef[],\n    usesRefs: ApiRef[],\n): ApiRelationKind {\n    if (implementsRefs.length > 0 && usesRefs.length > 0) return 'uses-implements';\n    if (implementsRefs.length > 0) return 'implements';\n    return 'uses';\n}\n\n/**\n * Stable-sort a ref list by api name, then by target service, so the committed JSON is\n * deterministic even when one api is used against two different services.\n */\n// webpieces-disable no-function-outside-class -- pure data helper for these serialization DTOs\nexport function sortApiRefs(refs: ApiRef[]): ApiRef[] {\n    return [...refs].sort(\n        (a: ApiRef, b: ApiRef) =>\n            a.api.localeCompare(b.api) ||\n            (a.targetService ?? '').localeCompare(b.targetService ?? ''),\n    );\n}\n"]}
+{"version":3,"file":"api-relations.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-usage/api-relations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * API Relations model\n *\n * The typed classification of a compile-time dependency edge P -> apiLib in\n * architecture/dependencies.json. Where the flat `dependsOn` only says \"P depends\n * on apiLib\", `apiRelations[apiLib]` says WHY: which API contracts P IMPLEMENTS\n * (serves, `class Ctrl extends XxxApi`) and which it USES (calls as a client,\n * `factory.createRpcClient(XxxApi, ...)` / `createPubSubClient(...)`), each tagged\n * with its transport.\n *\n * Interfaces + object literals here mirror the sibling runtime-graph.ts model —\n * these are serialization DTOs written verbatim into the committed JSON, and\n * `implements`/`uses` are legal interface property names (they are reserved words\n * only as binding identifiers, not as member names).\n */\n\n/**\n * Transport of an API contract:\n *  - `rpc`      — synchronous request/response over HTTP\n *  - `pubsub`   — fire-and-forget, delivered later through a Cloud Tasks queue\n *  - `external` — a contract for a system OUTSIDE this repo (firestore, gmail, ...). Nothing in-repo\n *                 implements it, so it never becomes a service→service edge; it terminates the graph\n *                 at a dashed vendor node. Detected from `runtime-architecture.externalApiPaths`\n *                 rather than from a decorator, because a vendor contract is a plain interface bound\n *                 to a Symbol token, not an `abstract class` carrying @ApiPath.\n */\nexport type ApiTransport = 'rpc' | 'pubsub' | 'external';\n\n/**\n * The kinds an external system can be DECLARED as. Each draws its own shape in the runtime viz, so\n * a datastore stops looking like an HTTP service.\n *\n * Lives here rather than beside the runtime graph model because that model already imports from this\n * file; putting it there and importing back would close a module cycle.\n */\nexport const EXTERNAL_SYSTEM_KINDS = [\n    'database',\n    'cache',\n    'queue',\n    'storage',\n    'saas',\n    'system',\n    /**\n     * A destination whose ADDRESS is supplied at runtime — a URL a partner registered, an OAuth\n     * callback, a per-tenant host. Unlike every other kind it does not name one vendor: it names the\n     * PLACE in our own system where somebody else's address is dialled, which is the fact a security\n     * review is looking for.\n     *\n     * Declared like every other kind, on the CONTRACT: `@externalSystem runtime partner-webhooks`.\n     * On the contract rather than at a `createRpcClient` call site deliberately — \"the far end of\n     * this contract is outside our estate\" is a property of the CONTRACT, true for every caller of\n     * it, so putting it there means one declaration however many services deliver over it, and\n     * nothing to keep in step when a second one appears. It also means this kind rides the exact\n     * same declare → resolve → draw pipeline `saas` and `database` already ride, rather than a\n     * second mechanism that reads construction sites and can disagree with the first.\n     */\n    'runtime',\n] as const;\n\nexport type ExternalSystemKind = (typeof EXTERNAL_SYSTEM_KINDS)[number];\n\n/** True for a string that names one of {@link EXTERNAL_SYSTEM_KINDS}. */\n// webpieces-disable no-function-outside-class -- type guard beside the type it guards, matching this file's DTO style\nexport function isExternalSystemKind(value: string): value is ExternalSystemKind {\n    return (EXTERNAL_SYSTEM_KINDS as readonly string[]).includes(value);\n}\n\n/**\n * ONE declared external system, keyed in {@link ExternalSystemDecls} by its IDENTITY.\n *\n * Identity, not display text: two projects each tagged `external:database:postgres` name the same\n * `postgres` node and converge on it with one arrow apiece, instead of drawing a database each.\n *\n * The two arrays are the two declaration sites, and a system may legitimately have both — a repo can\n * wrap a datastore behind a contract in one service and open it directly in another.\n */\nexport interface ExternalSystemDecl {\n    kind: ExternalSystemKind;\n    label: string;\n    /** Contracts declaring it with an `@externalSystem` JSDoc tag; every user of one gets an arrow. */\n    apis: string[];\n    /** Projects declaring it with an `external:<kind>:<identity>` nx tag; each gets its OWN arrow. */\n    projects: string[];\n}\n\n/** identity -> its declaration. Serialized as the `externalSystems` key of dependencies.json. */\nexport type ExternalSystemDecls = Record<string, ExternalSystemDecl>;\n\n/**\n * How a project relates to ONE api-lib it depends on:\n *  - `implements`       — it serves the api (a controller extends it)\n *  - `uses`             — it calls the api (generates a client)\n *  - `uses-implements`  — it does BOTH (implements some of the api-lib's contracts,\n *                          uses others)\n */\nexport type ApiRelationKind = 'implements' | 'uses' | 'uses-implements';\n\n/** One API class a project implements or uses, with its transport. */\nexport interface ApiRef {\n    api: string;\n    type: ApiTransport;\n    /**\n     * ONLY on a `uses` ref: the service the call site aims at, read from the client config literal\n     * (`createRpcClient(XxxApi, new ClientConfig('helper-fsdb'))` → `helper-fsdb`). It is matched\n     * against a project's DECLARED `serviceName` to pick the ONE runtime edge target, instead of\n     * fanning the edge out to every implementer of the api — which is catastrophically wrong for a\n     * company-wide contract registered in a shared library and therefore implemented by every server.\n     *\n     * Absent when the config argument is not a `new <Xxx>ClientConfig('<literal>')` (a variable, a\n     * computed name, ...). Absent means \"unknown target\", NOT \"no target\" — the runtime graph then\n     * falls back to the old fan-out and says so out loud.\n     */\n    targetService?: string;\n    /**\n     * ONLY on a `pubsub` uses ref. True means \"this producer was attributed to EVERY cloudtasks\n     * method of the contract, not to the methods it actually enqueues\".\n     *\n     * A producer builds one client for the whole contract (`createPubSubClient(EmailTaskApi, cfg)`)\n     * and enqueues through a proxy (`emailTasks.send(req)`) somewhere else entirely — often after\n     * the client has been stored in a DI binding — so WHICH methods it enqueues is not statically\n     * recoverable. The consumer side IS exact (addRoutes + the contract's method table). Recording\n     * the difference keeps a producer-side queue from being read as proof that queue is used.\n     */\n    methodsInferred?: boolean;\n}\n\n/**\n * Identity of a ref for de-duplication: an api used twice against DIFFERENT services is two distinct\n * relations (two distinct runtime edges), so the api name alone is not the key.\n */\n// webpieces-disable no-function-outside-class -- pure data helper for these serialization DTOs\nexport function apiRefKey(ref: ApiRef): string {\n    return `${ref.api} ${ref.targetService ?? ''}`;\n}\n\n/**\n * A project's relationship to ONE api-lib it depends on. Serialized verbatim into\n * architecture/dependencies.json under `apiRelations[apiLibProjectName]`.\n */\nexport interface ApiRelation {\n    kind: ApiRelationKind;\n    implements: ApiRef[];\n    uses: ApiRef[];\n}\n\n/** apiLibProjectName -> relation. Attached to a GraphEntry as `apiRelations`. */\nexport type ProjectApiRelations = Record<string, ApiRelation>;\n\n/**\n * What triggers ONE endpoint, mirroring core-util's `EndpointKind`. Duplicated as a string union\n * rather than imported: nx-webpieces-rules is build tooling and must not take a runtime dependency\n * on the framework it inspects (it reads decorators as TEXT, from projects that may be on a\n * different @webpieces version than the tooling itself).\n */\nexport type EndpointKind = 'rpc' | 'cloudtasks' | 'cron' | 'external';\n\n/** HTTP verbs understood by the generated contract runtime. */\nexport type ContractHttpMethod = 'GET' | 'POST';\n\n/** One path/query/body mapping emitted into architecture/dependencies.json. */\nexport interface ApiParameterMeta {\n    index: number;\n    source: 'path' | 'query' | 'body';\n    /** Path/query wire name; a JSON/form body occupies the whole entity and has no key. */\n    wireName?: string;\n}\n\n/**\n * One method on an API contract, as written in source: what triggers it, where it is mounted, and\n * (for a queued method) which Cloud Tasks queue delivers it.\n */\nexport interface ApiMethodMeta {\n    name: string;\n    /** The @Endpoint path, relative to the class's @ApiPath basePath. */\n    path: string;\n    kind: EndpointKind;\n    /** The actual incoming/outgoing verb; POST when @Endpoint omits httpMethod. */\n    httpMethod?: ContractHttpMethod;\n    /** Explicit parameter mappings; absent only when the method has none. */\n    parameters?: ApiParameterMeta[];\n    /** Present when callers receive the transport-neutral full response. */\n    responseType?: 'full';\n    /**\n     * `@Queue(...)` override, else `${ApiClassName}-${methodName}`.\n     *\n     * ONLY on a `cloudtasks` or `cron` method — those are the kinds actually delivered through a\n     * named queue or schedule, and Terraform matches on this string. A synchronous `rpc` (or an\n     * inbound `external`) endpoint has no queue and needs none; emitting a plausible-looking name for\n     * one put every synchronous endpoint one naive `methods.map(m => m.queueName)` away from being\n     * provisioned as a queue.\n     */\n    queueName?: string;\n    /**\n     * WHO outside this repo drives this endpoint, from `@Endpoint(p, 'external', { calledBy })`.\n     *\n     * ONLY on an `external` method, the same way `queueName` is only on the kinds that HAVE a queue.\n     *\n     * Deliberately the SAME {@link ExternalSystemDeclaration} the OUTBOUND `@externalSystem` tag\n     * resolves to, not a parallel inbound-only type: an inbound `saas twilio` and an outbound\n     * `saas twilio` are the same vendor, so sharing the type makes them share an IDENTITY and\n     * converge on ONE node instead of drawing twilio twice facing opposite directions.\n     *\n     * Optional in the TYPE only for graphs generated before the caller was required — generation\n     * FAILS on an `external` method whose caller cannot be read (UndeclaredExternalCallerError).\n     */\n    caller?: ExternalSystemDeclaration;\n}\n\n/**\n * A discovered API contract class: its name, the api-lib project that owns it, its transport, and\n * its per-method trigger table.\n */\nexport interface ApiClassInfo {\n    api: string;\n    owner: string;\n    type: ApiTransport;\n    /** The class's @ApiPath basePath; absent for an external (vendor) contract, which has no route. */\n    basePath?: string;\n    /**\n     * Every @Endpoint method, in declaration order. Empty for an external contract (a vendor\n     * interface has no endpoints — it is called through a vendor SDK, not mounted).\n     */\n    methods: ApiMethodMeta[];\n    /**\n     * Set when the contract carries an `@externalSystem <kind> [label]` JSDoc tag — a vendor seam\n     * declaring WHAT it is a seam to. JSDoc rather than a decorator because these seams are plain TS\n     * `interface`s, which cannot carry one.\n     */\n    externalSystem?: ExternalSystemDeclaration;\n}\n\n/** The `(kind, label)` pair a single declaration resolves to. */\nexport interface ExternalSystemDeclaration {\n    kind: ExternalSystemKind;\n    label: string;\n}\n\n/**\n * The committed, per-contract view written to `architecture/apis/<ApiName>.json` (one file per API;\n * dependencies.json only links to it under `apiContractFiles` — see ApiContractFiles).\n *\n * The runtime graph is derived from the committed files so generate and validate can never\n * diverge — which means anything the runtime graph needs must be COMMITTED, not re-scanned.\n * Per-method trigger kinds and queue names are exactly that: without this table the derivation\n * cannot tell a queued endpoint from a cron sweep, and cannot name the queue between two services.\n */\nexport interface ApiContract {\n    owner: string;\n    /** 'rpc' | 'pubsub' for an in-repo contract, 'external' for a vendor seam. */\n    apiKind: ApiTransport;\n    /**\n     * REQUIRED. Every routed contract carries `@ApiPath`, so every entry in this table must carry the\n     * base path its methods hang off. Optional was worse than absent: a consumer joining\n     * `basePath + path` for the ONE entry that lost it computed `/test` where the real route was\n     * `/whatsapp/test`, and had no reason to suspect it — every other entry had the field. Generation\n     * now FAILS instead of shipping an entry that computes a confidently wrong URL.\n     */\n    basePath: string;\n    methods: ApiMethodMeta[];\n}\n\n/** apiClassName -> its committed contract. Serialized as one `architecture/apis/<ApiName>.json` each. */\nexport type ApiContracts = Record<string, ApiContract>;\n\n/**\n * ONE decorator argument the scan saw but could not reduce to a string — `@ApiPath(SOME_CONST)`\n * where SOME_CONST is imported from another module, a computed expression, an enum member, ...\n *\n * Recorded rather than dropped. Before this existed, an unresolvable argument cost the contract its\n * basePath, or a method, or (when EVERY method's path was one) the whole class — with nothing\n * printed anywhere. Same-module constants now resolve, so what remains here is the genuinely\n * unresolvable, which the author can fix by inlining the literal or moving the constant in-module.\n */\nexport class NonLiteralDecoratorArg {\n    constructor(\n        /** The contract class the argument was written on. */\n        public readonly api: string,\n        /** `ApiPath` | `Endpoint` | `Queue`. */\n        public readonly decorator: string,\n        /** The method name for a member decorator, null for a class decorator. */\n        public readonly method: string | null,\n        /** The argument exactly as written, e.g. `WHATSAPP_API_PATH`. */\n        public readonly argument: string,\n        /** `path/to/file.ts:LINE`, workspace-relative. */\n        public readonly at: string,\n    ) {}\n}\n\n/**\n * ONE `@Endpoint(path, kind)` whose PATH argument was present but could not be reduced to a string.\n *\n * Split out of NonLiteralDecoratorArg (which stays a warning, covering @Queue and the rest) because\n * this one is FATAL. Upstream components need the URL: an http client builds its request as\n * `basePath + path`, so an unreadable path is missing ROUTING, not missing metadata — the same\n * reasoning that already makes basePath required. Skipping the method instead used to delete it, and\n * a class whose every path was a constant lost every method and vanished from the contract table with\n * nothing printed anywhere.\n */\nexport class UnresolvedEndpointPath {\n    constructor(\n        /** The contract class the method is declared on. */\n        public readonly api: string,\n        /** The method name. */\n        public readonly method: string,\n        /** The path argument exactly as written, e.g. `PROCESS_PATH`. */\n        public readonly argument: string,\n        /** `path/to/file.ts:LINE`, workspace-relative. */\n        public readonly at: string,\n    ) {}\n}\n\n/**\n * ONE `external` `@Endpoint` whose CALLER could not be read from the source.\n *\n * Fatal for the same reason {@link UnresolvedEndpointPath} is. The inbound box exists to say who is\n * calling us from outside; with no caller it can only restate our own contract name, which is the\n * exact bug this diagnostic exists to make impossible to reintroduce. `@Endpoint`'s TS overloads\n * already require `calledBy`, so anything reaching here is a JS caller, an `as any`, a cross-module\n * constant the parser-only scan cannot fold, or an unknown `callerKind`.\n */\nexport class UndeclaredExternalCaller {\n    constructor(\n        /** The contract class the method is declared on. */\n        public readonly api: string,\n        /** The method name. */\n        public readonly method: string,\n        /** What was wrong, as written — `<missing>`, `SOME_CONST`, `callerKind: 'vendor'`. */\n        public readonly argument: string,\n        /** `path/to/file.ts:LINE`, workspace-relative. */\n        public readonly at: string,\n    ) {}\n}\n\n/**\n * A contract class that DECLARED `@Endpoint` methods and kept none of them.\n *\n * The backstop for the mechanism that hid an entire service: `buildApiContracts` skips a zero-method\n * class (correctly — a vendor seam has no routes), so a class gutted by unreadable decorator\n * arguments left through the same door as a legitimately routeless one. A class that declared\n * endpoints and produced none is never legitimate, so it is named instead.\n */\nexport class EmptiedApiContract {\n    constructor(\n        /** The contract class name. */\n        public readonly api: string,\n        /** How many `@Endpoint` decorators were written on it. */\n        public readonly declared: number,\n        /** `path/to/file.ts:LINE` of the class, workspace-relative. */\n        public readonly at: string,\n    ) {}\n}\n\n/** Derive the relation kind from the (possibly empty) implements/uses ref lists. */\n// webpieces-disable no-function-outside-class -- pure data helper for these serialization DTOs\nexport function deriveApiRelationKind(\n    implementsRefs: ApiRef[],\n    usesRefs: ApiRef[],\n): ApiRelationKind {\n    if (implementsRefs.length > 0 && usesRefs.length > 0) return 'uses-implements';\n    if (implementsRefs.length > 0) return 'implements';\n    return 'uses';\n}\n\n/**\n * Stable-sort a ref list by api name, then by target service, so the committed JSON is\n * deterministic even when one api is used against two different services.\n */\n// webpieces-disable no-function-outside-class -- pure data helper for these serialization DTOs\nexport function sortApiRefs(refs: ApiRef[]): ApiRef[] {\n    return [...refs].sort(\n        (a: ApiRef, b: ApiRef) =>\n            a.api.localeCompare(b.api) ||\n            (a.targetService ?? '').localeCompare(b.targetService ?? ''),\n    );\n}\n"]}

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

@@ -161,7 +161,8 @@ export declare class ApiUsageScanner {
  */
 export declare function scanAndAttachApiRelations(workspaceRoot: string, graph: EnhancedGraph, projectInfos: Map<string, ProjectInfo>, externalApiPaths?: readonly string[]): ApiScanResult;
 /**
- * The committed `apiContracts` table for architecture/dependencies.json, from a completed scan.
+ * The committed api contract table (one `architecture/apis/<ApiName>.json` per entry), from a
+ * completed scan.
  *
  * Only contracts with ≥1 endpoint are emitted: a vendor seam has no routes, so a table entry for it
  * would be an empty shell, and its identity is already carried by the `external` refs in

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

@@ -414,7 +414,8 @@ function scanAndAttachApiRelations(workspaceRoot, graph, projectInfos, externalA
     return result;
 }
 /**
- * The committed `apiContracts` table for architecture/dependencies.json, from a completed scan.
+ * The committed api contract table (one `architecture/apis/<ApiName>.json` per entry), from a
+ * completed scan.
  *
  * Only contracts with ≥1 endpoint are emitted: a vendor seam has no routes, so a table entry for it
  * would be an empty shell, and its identity is already carried by the `external` refs in