@webpieces/nx-webpieces-rules 0.4.809 → 0.4.811

package/executors.json

@@ -150,6 +150,16 @@
             "schema": "./src/executors/di-graph-generate/schema.json",
             "description": "Per-project: generate the Inversify DI dependency DAG into design.json + design.md at the project root"
         },
+        "openapi-generate": {
+            "implementation": "./src/executors/openapi-generate/executor",
+            "schema": "./src/executors/openapi-generate/schema.json",
+            "description": "Per-project: render the contracts to OpenAPI + mcp-tools.json into the build outputPath, with the consumer's own @webpieces/openapi-generator"
+        },
+        "docs-generate": {
+            "implementation": "./src/executors/docs-generate/executor",
+            "schema": "./src/executors/docs-generate/schema.json",
+            "description": "Per-project: render the static API reference site from a generated document into the build outputPath, with the consumer's own @webpieces/docs-site"
+        },
         "validate-nx-wiring": {
             "implementation": "./src/executors/validate-nx-wiring/executor",
             "schema": "./src/executors/validate-nx-wiring/schema.json",

package/package.json

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

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

@@ -0,0 +1,47 @@
+/**
+ * docs-generate Executor
+ *
+ * Renders the static API reference site from a document `openapi-generate` already wrote into the
+ * project's build `outputPath`, and writes the site into `<outputPath>/<siteDir>` — build output,
+ * published with the package, never committed.
+ *
+ * Usage (project.json):
+ *
+ *   "docs-generate": {
+ *     "executor": "@webpieces/nx-webpieces-rules:docs-generate",
+ *     "dependsOn": ["openapi-generate"],
+ *     "cache": true,
+ *     "inputs": ["default", "^default"],
+ *     "outputs": ["{workspaceRoot}/dist/<project>/docs-site"],
+ *     "options": { "document": "public-openapi.json", "siteDir": "docs-site", "prose": "<project>/docs" }
+ *   }
+ *
+ * `document` should be the PARTNER-facing document: a site built from `full-private-openapi.json`
+ * publishes exactly the operations somebody decided not to publish. `prose` is optional because a site
+ * with no prose pages is a legal site; `document` and `siteDir` are required and have no defaults.
+ *
+ * The renderer is the CONSUMER's `@webpieces/docs-site`, resolved from its node_modules and
+ * version-checked; this plugin bundles no copy of it.
+ */
+import type { ExecutorContext } from '@nx/devkit';
+import { ConsumerBinResolver, GeneratorRunner } from '@webpieces/pr-gate';
+import { RepoScratchDirs } from '@webpieces/rules-config';
+import { ExecutorResult } from '../../executor-result';
+export interface DocsGenerateOptions {
+    /** A document name inside the build outputPath, e.g. `public-openapi.json`. Required. */
+    document?: string;
+    /** The site's directory name inside the build outputPath, e.g. `docs-site`. Required. */
+    siteDir?: string;
+    /** Workspace-relative directory holding `docs.manifest.json` and its markdown. Optional. */
+    prose?: string;
+}
+/** Everything except the process-facing reporting, so the suite drives it exactly as nx does. */
+export declare class DocsGenerate {
+    private readonly resolver;
+    private readonly runner;
+    private readonly scratch;
+    constructor(resolver?: ConsumerBinResolver, runner?: GeneratorRunner, scratch?: RepoScratchDirs);
+    /** @returns the files written, absolute. Throws RuleFailError on every refusal. */
+    run(options: DocsGenerateOptions, context: ExecutorContext): string[];
+}
+export default function runExecutor(options: DocsGenerateOptions, context: ExecutorContext): Promise<ExecutorResult>;

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

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * docs-generate Executor
+ *
+ * Renders the static API reference site from a document `openapi-generate` already wrote into the
+ * project's build `outputPath`, and writes the site into `<outputPath>/<siteDir>` — build output,
+ * published with the package, never committed.
+ *
+ * Usage (project.json):
+ *
+ *   "docs-generate": {
+ *     "executor": "@webpieces/nx-webpieces-rules:docs-generate",
+ *     "dependsOn": ["openapi-generate"],
+ *     "cache": true,
+ *     "inputs": ["default", "^default"],
+ *     "outputs": ["{workspaceRoot}/dist/<project>/docs-site"],
+ *     "options": { "document": "public-openapi.json", "siteDir": "docs-site", "prose": "<project>/docs" }
+ *   }
+ *
+ * `document` should be the PARTNER-facing document: a site built from `full-private-openapi.json`
+ * publishes exactly the operations somebody decided not to publish. `prose` is optional because a site
+ * with no prose pages is a legal site; `document` and `siteDir` are required and have no defaults.
+ *
+ * The renderer is the CONSUMER's `@webpieces/docs-site`, resolved from its node_modules and
+ * version-checked; this plugin bundles no copy of it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocsGenerate = void 0;
+exports.default = runExecutor;
+const tslib_1 = require("tslib");
+const pr_gate_1 = require("@webpieces/pr-gate");
+const rules_config_1 = require("@webpieces/rules-config");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const executor_result_1 = require("../../executor-result");
+const generator_target_1 = require("../../lib/generated-docs/generator-target");
+const toError_1 = require("../../toError");
+const RULE_NAME = 'docs-generate';
+/** Everything except the process-facing reporting, so the suite drives it exactly as nx does. */
+class DocsGenerate {
+    resolver;
+    runner;
+    scratch;
+    constructor(resolver = new pr_gate_1.ConsumerBinResolver(), runner = new pr_gate_1.GeneratorRunner(), scratch = new rules_config_1.RepoScratchDirs()) {
+        this.resolver = resolver;
+        this.runner = runner;
+        this.scratch = scratch;
+    }
+    /** @returns the files written, absolute. Throws RuleFailError on every refusal. */
+    run(options, context) {
+        const target = generator_target_1.GeneratorTarget.of(RULE_NAME, context);
+        target.assertDependsOn('openapi-generate');
+        const document = target.requiredOption(options.document, 'document');
+        const siteDir = target.requiredOption(options.siteDir, 'siteDir');
+        const outDir = target.buildOutputDir();
+        const spec = path.join(outDir, document);
+        if (!fs.existsSync(spec)) {
+            throw new rules_config_1.RuleFailError(RULE_NAME, `${path.relative(context.root, spec)} does not exist, so there is nothing to render. ` +
+                `openapi-generate writes only the documents the contracts' @ApiType(...) ask for.`, undefined, undefined, [new rules_config_1.Option(`Set options.document to a file openapi-generate writes into ${path.relative(context.root, outDir)}`, true)]);
+        }
+        const bin = this.resolver.resolve(new pr_gate_1.ConsumerBinRequest(RULE_NAME, pr_gate_1.DOCS_SITE, [path.join(context.root, target.projectRoot), context.root]));
+        const staging = this.scratch.make(context.root, 'wp-docs-generate-');
+        // webpieces-disable no-unmanaged-exceptions -- try/FINALLY only, nothing is caught: the staging
+        // directory is removed however this ends, and every throw still reaches runExecutor below
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            const args = ['--spec', spec, '--out', staging];
+            if (options.prose !== undefined)
+                args.push('--prose', path.resolve(context.root, options.prose));
+            const run = this.runner.run(bin, args, context.root);
+            if (!run.ok) {
+                throw new rules_config_1.RuleFailError(RULE_NAME, `${bin.packageName} ${bin.version} refused ${document}:\n${run.output}`);
+            }
+            // The site REPLACES the previous one: a page for an operation that no longer exists must not
+            // survive into the published package.
+            const siteOut = path.join(outDir, siteDir);
+            fs.rmSync(siteOut, { recursive: true, force: true });
+            const written = new generator_target_1.StagedOutput().publish(staging, siteOut);
+            target.assertOutputsCover(written);
+            return written;
+        }
+        finally {
+            fs.rmSync(staging, { recursive: true, force: true });
+        }
+    }
+}
+exports.DocsGenerate = DocsGenerate;
+// webpieces-disable no-function-outside-class -- nx executor module: nx resolves a default-export function here
+async function runExecutor(options, context) {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- this IS the executor's single top-level handler
+    try {
+        const written = new DocsGenerate().run(options, context);
+        console.log(`wrote ${written.length} file(s) of the docs site for ${context.projectName ?? ''}`);
+        return new executor_result_1.ExecutorResult(true);
+    }
+    catch (err) {
+        const error = (0, toError_1.toError)(err);
+        console.error(`❌ ${RULE_NAME}: ${error instanceof rules_config_1.RuleFailError ? (0, rules_config_1.renderRuleFailForHuman)(error) : error.message}`);
+        return new executor_result_1.ExecutorResult(false);
+    }
+}
+//# sourceMappingURL=executor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/docs-generate/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * docs-generate Executor\n *\n * Renders the static API reference site from a document `openapi-generate` already wrote into the\n * project's build `outputPath`, and writes the site into `<outputPath>/<siteDir>` — build output,\n * published with the package, never committed.\n *\n * Usage (project.json):\n *\n *   \"docs-generate\": {\n *     \"executor\": \"@webpieces/nx-webpieces-rules:docs-generate\",\n *     \"dependsOn\": [\"openapi-generate\"],\n *     \"cache\": true,\n *     \"inputs\": [\"default\", \"^default\"],\n *     \"outputs\": [\"{workspaceRoot}/dist/<project>/docs-site\"],\n *     \"options\": { \"document\": \"public-openapi.json\", \"siteDir\": \"docs-site\", \"prose\": \"<project>/docs\" }\n *   }\n *\n * `document` should be the PARTNER-facing document: a site built from `full-private-openapi.json`\n * publishes exactly the operations somebody decided not to publish. `prose` is optional because a site\n * with no prose pages is a legal site; `document` and `siteDir` are required and have no defaults.\n *\n * The renderer is the CONSUMER's `@webpieces/docs-site`, resolved from its node_modules and\n * version-checked; this plugin bundles no copy of it.\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { ConsumerBinRequest, ConsumerBinResolver, DOCS_SITE, GeneratorRunner } from '@webpieces/pr-gate';\nimport { Option, RepoScratchDirs, RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { ExecutorResult } from '../../executor-result';\nimport { GeneratorTarget, StagedOutput } from '../../lib/generated-docs/generator-target';\nimport { toError } from '../../toError';\n\nexport interface DocsGenerateOptions {\n    /** A document name inside the build outputPath, e.g. `public-openapi.json`. Required. */\n    document?: string;\n    /** The site's directory name inside the build outputPath, e.g. `docs-site`. Required. */\n    siteDir?: string;\n    /** Workspace-relative directory holding `docs.manifest.json` and its markdown. Optional. */\n    prose?: string;\n}\n\nconst RULE_NAME = 'docs-generate';\n\n/** Everything except the process-facing reporting, so the suite drives it exactly as nx does. */\nexport class DocsGenerate {\n    constructor(\n        private readonly resolver: ConsumerBinResolver = new ConsumerBinResolver(),\n        private readonly runner: GeneratorRunner = new GeneratorRunner(),\n        private readonly scratch: RepoScratchDirs = new RepoScratchDirs(),\n    ) {}\n\n    /** @returns the files written, absolute. Throws RuleFailError on every refusal. */\n    run(options: DocsGenerateOptions, context: ExecutorContext): string[] {\n        const target = GeneratorTarget.of(RULE_NAME, context);\n        target.assertDependsOn('openapi-generate');\n        const document = target.requiredOption(options.document, 'document');\n        const siteDir = target.requiredOption(options.siteDir, 'siteDir');\n        const outDir = target.buildOutputDir();\n        const spec = path.join(outDir, document);\n        if (!fs.existsSync(spec)) {\n            throw new RuleFailError(\n                RULE_NAME,\n                `${path.relative(context.root, spec)} does not exist, so there is nothing to render. ` +\n                    `openapi-generate writes only the documents the contracts' @ApiType(...) ask for.`,\n                undefined,\n                undefined,\n                [new Option(`Set options.document to a file openapi-generate writes into ${path.relative(context.root, outDir)}`, true)],\n            );\n        }\n        const bin = this.resolver.resolve(new ConsumerBinRequest(\n            RULE_NAME, DOCS_SITE, [path.join(context.root, target.projectRoot), context.root]));\n\n        const staging = this.scratch.make(context.root, 'wp-docs-generate-');\n        // webpieces-disable no-unmanaged-exceptions -- try/FINALLY only, nothing is caught: the staging\n        // directory is removed however this ends, and every throw still reaches runExecutor below\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const args = ['--spec', spec, '--out', staging];\n            if (options.prose !== undefined) args.push('--prose', path.resolve(context.root, options.prose));\n            const run = this.runner.run(bin, args, context.root);\n            if (!run.ok) {\n                throw new RuleFailError(RULE_NAME, `${bin.packageName} ${bin.version} refused ${document}:\\n${run.output}`);\n            }\n            // The site REPLACES the previous one: a page for an operation that no longer exists must not\n            // survive into the published package.\n            const siteOut = path.join(outDir, siteDir);\n            fs.rmSync(siteOut, { recursive: true, force: true });\n            const written = new StagedOutput().publish(staging, siteOut);\n            target.assertOutputsCover(written);\n            return written;\n        } finally {\n            fs.rmSync(staging, { recursive: true, force: true });\n        }\n    }\n}\n\n// webpieces-disable no-function-outside-class -- nx executor module: nx resolves a default-export function here\nexport default async function runExecutor(\n    options: DocsGenerateOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- this IS the executor's single top-level handler\n    try {\n        const written = new DocsGenerate().run(options, context);\n        console.log(`wrote ${written.length} file(s) of the docs site for ${context.projectName ?? ''}`);\n        return new ExecutorResult(true);\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error(`❌ ${RULE_NAME}: ${error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message}`);\n        return new ExecutorResult(false);\n    }\n}\n"]}

package/src/executors/docs-generate/schema.json

@@ -0,0 +1,21 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "title": "Docs Generate Executor",
+    "description": "Render the static API reference site from a document openapi-generate wrote into the build outputPath, with the consumer's own @webpieces/docs-site, into <outputPath>/<siteDir>. The target must dependsOn openapi-generate and declare outputs covering the site.",
+    "type": "object",
+    "properties": {
+        "document": {
+            "type": "string",
+            "description": "The document inside the build outputPath to render, e.g. public-openapi.json. No default."
+        },
+        "siteDir": {
+            "type": "string",
+            "description": "The site's directory name inside the build outputPath, e.g. docs-site. No default."
+        },
+        "prose": {
+            "type": "string",
+            "description": "Workspace-relative directory holding docs.manifest.json and the markdown it names. Optional: a site with no prose pages is legal."
+        }
+    },
+    "required": ["document", "siteDir"]
+}

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

@@ -0,0 +1,46 @@
+/**
+ * openapi-generate Executor
+ *
+ * Renders a project's contracts to OpenAPI (and `mcp-tools.json`) INTO the project's own build
+ * `outputPath`, so the documents are packed and published inside the api library's npm package: a
+ * consumer installs the library and has the contract. They are build output — never committed.
+ *
+ * Usage (project.json):
+ *
+ *   "openapi-generate": {
+ *     "executor": "@webpieces/nx-webpieces-rules:openapi-generate",
+ *     "dependsOn": ["build"],
+ *     "cache": true,
+ *     "inputs": ["default", "^default"],
+ *     "outputs": [
+ *       "{workspaceRoot}/dist/<project>/*openapi.json",
+ *       "{workspaceRoot}/dist/<project>/*openapi.yaml",
+ *       "{workspaceRoot}/dist/<project>/mcp-tools.json"
+ *     ],
+ *     "options": { "manifest": "<project>/openapi.manifest.json", "format": "both" }
+ *   }
+ *
+ * `dependsOn: ["build"]` and `outputs` are CHECKED, not merely recommended — see GeneratorTarget. The
+ * generator itself is the CONSUMER's `@webpieces/openapi-generator`, resolved from its node_modules and
+ * version-checked; this plugin bundles no copy of it (see ConsumerBinResolver in @webpieces/pr-gate).
+ */
+import type { ExecutorContext } from '@nx/devkit';
+import { ConsumerBinResolver, GeneratorRunner } from '@webpieces/pr-gate';
+import { RepoScratchDirs } from '@webpieces/rules-config';
+import { ExecutorResult } from '../../executor-result';
+export interface OpenApiGenerateOptions {
+    /** Workspace-relative path to the project's `openapi.manifest.json`. Required; no default. */
+    manifest?: string;
+    /** `json`, `yaml` or `both`. Required; no default — it decides what the package ships. */
+    format?: string;
+}
+/** Everything except the process-facing reporting, so the suite drives it exactly as nx does. */
+export declare class OpenApiGenerate {
+    private readonly resolver;
+    private readonly runner;
+    private readonly scratch;
+    constructor(resolver?: ConsumerBinResolver, runner?: GeneratorRunner, scratch?: RepoScratchDirs);
+    /** @returns the files written, absolute. Throws RuleFailError on every refusal. */
+    run(options: OpenApiGenerateOptions, context: ExecutorContext): string[];
+}
+export default function runExecutor(options: OpenApiGenerateOptions, context: ExecutorContext): Promise<ExecutorResult>;

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

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * openapi-generate Executor
+ *
+ * Renders a project's contracts to OpenAPI (and `mcp-tools.json`) INTO the project's own build
+ * `outputPath`, so the documents are packed and published inside the api library's npm package: a
+ * consumer installs the library and has the contract. They are build output — never committed.
+ *
+ * Usage (project.json):
+ *
+ *   "openapi-generate": {
+ *     "executor": "@webpieces/nx-webpieces-rules:openapi-generate",
+ *     "dependsOn": ["build"],
+ *     "cache": true,
+ *     "inputs": ["default", "^default"],
+ *     "outputs": [
+ *       "{workspaceRoot}/dist/<project>/*openapi.json",
+ *       "{workspaceRoot}/dist/<project>/*openapi.yaml",
+ *       "{workspaceRoot}/dist/<project>/mcp-tools.json"
+ *     ],
+ *     "options": { "manifest": "<project>/openapi.manifest.json", "format": "both" }
+ *   }
+ *
+ * `dependsOn: ["build"]` and `outputs` are CHECKED, not merely recommended — see GeneratorTarget. The
+ * generator itself is the CONSUMER's `@webpieces/openapi-generator`, resolved from its node_modules and
+ * version-checked; this plugin bundles no copy of it (see ConsumerBinResolver in @webpieces/pr-gate).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenApiGenerate = void 0;
+exports.default = runExecutor;
+const tslib_1 = require("tslib");
+const pr_gate_1 = require("@webpieces/pr-gate");
+const rules_config_1 = require("@webpieces/rules-config");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const executor_result_1 = require("../../executor-result");
+const generator_target_1 = require("../../lib/generated-docs/generator-target");
+const toError_1 = require("../../toError");
+const RULE_NAME = 'openapi-generate';
+/** Everything except the process-facing reporting, so the suite drives it exactly as nx does. */
+class OpenApiGenerate {
+    resolver;
+    runner;
+    scratch;
+    constructor(resolver = new pr_gate_1.ConsumerBinResolver(), runner = new pr_gate_1.GeneratorRunner(), scratch = new rules_config_1.RepoScratchDirs()) {
+        this.resolver = resolver;
+        this.runner = runner;
+        this.scratch = scratch;
+    }
+    /** @returns the files written, absolute. Throws RuleFailError on every refusal. */
+    run(options, context) {
+        const target = generator_target_1.GeneratorTarget.of(RULE_NAME, context);
+        target.assertDependsOn('build');
+        const manifest = target.requiredOption(options.manifest, 'manifest');
+        const format = target.requiredOption(options.format, 'format');
+        const outDir = target.buildOutputDir();
+        const bin = this.resolver.resolve(new pr_gate_1.ConsumerBinRequest(RULE_NAME, pr_gate_1.OPENAPI_GENERATOR, [path.join(context.root, target.projectRoot), context.root]));
+        const staging = this.scratch.make(context.root, 'wp-openapi-generate-');
+        // webpieces-disable no-unmanaged-exceptions -- try/FINALLY only, nothing is caught: the staging
+        // directory is removed however this ends, and every throw still reaches runExecutor below
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            const run = this.runner.run(bin, [
+                '--manifest', path.resolve(context.root, manifest), '--out', staging, '--format', format,
+            ], context.root);
+            if (!run.ok) {
+                throw new rules_config_1.RuleFailError(RULE_NAME, `${bin.packageName} ${bin.version} refused ${manifest}:\n${run.output}`);
+            }
+            const written = new generator_target_1.StagedOutput().publish(staging, outDir);
+            target.assertOutputsCover(written);
+            return written;
+        }
+        finally {
+            fs.rmSync(staging, { recursive: true, force: true });
+        }
+    }
+}
+exports.OpenApiGenerate = OpenApiGenerate;
+// webpieces-disable no-function-outside-class -- nx executor module: nx resolves a default-export function here
+async function runExecutor(options, context) {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- this IS the executor's single top-level handler
+    try {
+        const written = new OpenApiGenerate().run(options, context);
+        for (const file of written)
+            console.log(`wrote ${path.relative(context.root, file)}`);
+        return new executor_result_1.ExecutorResult(true);
+    }
+    catch (err) {
+        const error = (0, toError_1.toError)(err);
+        console.error(`❌ ${RULE_NAME}: ${error instanceof rules_config_1.RuleFailError ? (0, rules_config_1.renderRuleFailForHuman)(error) : error.message}`);
+        return new executor_result_1.ExecutorResult(false);
+    }
+}
+//# sourceMappingURL=executor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/openapi-generate/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * openapi-generate Executor\n *\n * Renders a project's contracts to OpenAPI (and `mcp-tools.json`) INTO the project's own build\n * `outputPath`, so the documents are packed and published inside the api library's npm package: a\n * consumer installs the library and has the contract. They are build output — never committed.\n *\n * Usage (project.json):\n *\n *   \"openapi-generate\": {\n *     \"executor\": \"@webpieces/nx-webpieces-rules:openapi-generate\",\n *     \"dependsOn\": [\"build\"],\n *     \"cache\": true,\n *     \"inputs\": [\"default\", \"^default\"],\n *     \"outputs\": [\n *       \"{workspaceRoot}/dist/<project>/*openapi.json\",\n *       \"{workspaceRoot}/dist/<project>/*openapi.yaml\",\n *       \"{workspaceRoot}/dist/<project>/mcp-tools.json\"\n *     ],\n *     \"options\": { \"manifest\": \"<project>/openapi.manifest.json\", \"format\": \"both\" }\n *   }\n *\n * `dependsOn: [\"build\"]` and `outputs` are CHECKED, not merely recommended — see GeneratorTarget. The\n * generator itself is the CONSUMER's `@webpieces/openapi-generator`, resolved from its node_modules and\n * version-checked; this plugin bundles no copy of it (see ConsumerBinResolver in @webpieces/pr-gate).\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport {\n    ConsumerBinRequest, ConsumerBinResolver, GeneratorRunner, OPENAPI_GENERATOR,\n} from '@webpieces/pr-gate';\nimport { RepoScratchDirs, RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { ExecutorResult } from '../../executor-result';\nimport { GeneratorTarget, StagedOutput } from '../../lib/generated-docs/generator-target';\nimport { toError } from '../../toError';\n\nexport interface OpenApiGenerateOptions {\n    /** Workspace-relative path to the project's `openapi.manifest.json`. Required; no default. */\n    manifest?: string;\n    /** `json`, `yaml` or `both`. Required; no default — it decides what the package ships. */\n    format?: string;\n}\n\nconst RULE_NAME = 'openapi-generate';\n\n/** Everything except the process-facing reporting, so the suite drives it exactly as nx does. */\nexport class OpenApiGenerate {\n    constructor(\n        private readonly resolver: ConsumerBinResolver = new ConsumerBinResolver(),\n        private readonly runner: GeneratorRunner = new GeneratorRunner(),\n        private readonly scratch: RepoScratchDirs = new RepoScratchDirs(),\n    ) {}\n\n    /** @returns the files written, absolute. Throws RuleFailError on every refusal. */\n    run(options: OpenApiGenerateOptions, context: ExecutorContext): string[] {\n        const target = GeneratorTarget.of(RULE_NAME, context);\n        target.assertDependsOn('build');\n        const manifest = target.requiredOption(options.manifest, 'manifest');\n        const format = target.requiredOption(options.format, 'format');\n        const outDir = target.buildOutputDir();\n        const bin = this.resolver.resolve(new ConsumerBinRequest(\n            RULE_NAME, OPENAPI_GENERATOR, [path.join(context.root, target.projectRoot), context.root]));\n\n        const staging = this.scratch.make(context.root, 'wp-openapi-generate-');\n        // webpieces-disable no-unmanaged-exceptions -- try/FINALLY only, nothing is caught: the staging\n        // directory is removed however this ends, and every throw still reaches runExecutor below\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const run = this.runner.run(bin, [\n                '--manifest', path.resolve(context.root, manifest), '--out', staging, '--format', format,\n            ], context.root);\n            if (!run.ok) {\n                throw new RuleFailError(\n                    RULE_NAME,\n                    `${bin.packageName} ${bin.version} refused ${manifest}:\\n${run.output}`,\n                );\n            }\n            const written = new StagedOutput().publish(staging, outDir);\n            target.assertOutputsCover(written);\n            return written;\n        } finally {\n            fs.rmSync(staging, { recursive: true, force: true });\n        }\n    }\n}\n\n// webpieces-disable no-function-outside-class -- nx executor module: nx resolves a default-export function here\nexport default async function runExecutor(\n    options: OpenApiGenerateOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- this IS the executor's single top-level handler\n    try {\n        const written = new OpenApiGenerate().run(options, context);\n        for (const file of written) console.log(`wrote ${path.relative(context.root, file)}`);\n        return new ExecutorResult(true);\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error(`❌ ${RULE_NAME}: ${error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message}`);\n        return new ExecutorResult(false);\n    }\n}\n"]}

package/src/executors/openapi-generate/schema.json

@@ -0,0 +1,18 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "title": "OpenAPI Generate Executor",
+    "description": "Render the project's contracts to OpenAPI (and mcp-tools.json) into the project's build outputPath, with the consumer's own @webpieces/openapi-generator. The target must dependsOn build and declare outputs covering what it writes.",
+    "type": "object",
+    "properties": {
+        "manifest": {
+            "type": "string",
+            "description": "Workspace-relative path to the project's openapi.manifest.json. No default."
+        },
+        "format": {
+            "type": "string",
+            "enum": ["json", "yaml", "both"],
+            "description": "Which serializations to write, and therefore publish. No default."
+        }
+    },
+    "required": ["manifest", "format"]
+}

package/src/lib/api-usage/api-doc-rules-scan.d.ts

@@ -1,6 +1,11 @@
 /**
  * `api-rules-for-openapi` and `api-rules-for-mcp` (#1011) — the CI half of "is this contract
- * publishable", on EVERY `@ApiPath` class in the workspace, `@ApiType` or not.
+ * publishable", on every `@ApiPath` class IN SCOPE, `@ApiType` or not.
+ *
+ * "In scope" is the rule's `mode` (#1017): `AFFECTED_PROJECT` scans the contracts of the projects the
+ * diff touched — the granularity nx already builds at, and the mode a consumer normally picks —
+ * while `RUN_EVERY_TIME` scans the whole workspace for a migration sweep. `ApiDocRule.coversProject`
+ * is the one place that answers it, for both rules.
  *
  * ## The acceptance contract, and why this file drives the generator instead of copying it
  *
@@ -20,17 +25,19 @@
  *    field). The extractor maps it to a primitive and the generator publishes `{}`, which in JSON
  *    Schema means "anything" — a partner-facing field with no shape, which is the defect the
  *    unmapped guard exists for, arriving through a door the guard does not watch.
- *  - an RPC whose response is `void`. Fire-and-forget is the CONTRACT of a `cloudtasks` or `cron`
- *    endpoint and is allowed there; an RPC that answers nothing can never gain a field without a
- *    breaking change, where a named empty response object grows additively forever.
+ *  - an `rpc` or `external` endpoint whose response is `void`. Fire-and-forget is the CONTRACT of a
+ *    `cloudtasks` or `cron` endpoint and is allowed there; an endpoint somebody WAITS on that answers
+ *    nothing can never gain a field without a breaking change, where a named empty response object
+ *    grows additively forever (#1017 — #1016 read this narrowly as rpc-only because `external` was
+ *    unstated).
  *
  * ## Why it lives in the rules engine and not in the doc parser
  *
  * `@webpieces/api-doc-model` is only ever pointed at contracts somebody chose to publish. `@ApiType`
  * is a PUBLISHING decision added later, on purpose — so a shape rule that only ran on contracts which
  * had already opted in would let a team discover, six months afterwards, that the type was never
- * expressible, by which time it is in partners' generated clients. Every check below runs on every
- * contract in the workspace.
+ * expressible, by which time it is in partners' generated clients. So every check below runs on every
+ * contract in scope, opted in or not — `@ApiType` narrows nothing here.
  *
  * ## Root-level unions are NOT re-checked here
  *
@@ -54,7 +61,7 @@ import { ApiDocRule, ApiDocRulesFindings } from './api-doc-rules';
 export declare class ApiDocRulesScan {
     private readonly workspaceRoot;
     private readonly projectInfos;
-    /** OFF unless a caller read otherwise out of webpieces.config.json — see `defaultRules`. */
+    /** OFF unless a caller read otherwise out of webpieces.config.json, which MUST state it. */
     private readonly openApiRule;
     private readonly mcpRule;
     /**
@@ -66,7 +73,7 @@ export declare class ApiDocRulesScan {
      */
     private readonly exclusions;
     constructor(workspaceRoot: string, projectInfos: Map<string, ProjectInfo>, 
-    /** OFF unless a caller read otherwise out of webpieces.config.json — see `defaultRules`. */
+    /** OFF unless a caller read otherwise out of webpieces.config.json, which MUST state it. */
     openApiRule?: ApiDocRule, mcpRule?: ApiDocRule);
     run(): ApiDocRulesFindings;
     /** Every contract in one file, or the ONE refusal that stopped the file being read at all. */
@@ -84,15 +91,16 @@ export declare class ApiDocRulesScan {
     /** `Record<string, unknown>`, `unknown[]`, `x: unknown` — by VALUE TYPE, never by spelling. */
     private judgeUnknownValues;
     /**
-     * An RPC must NAME a response DTO, even an empty one.
+     * An endpoint somebody WAITS ON must NAME a response DTO, even an empty one.
      *
      * `Promise<void>` on a `cloudtasks` or `cron` endpoint is the CONTRACT — fire-and-forget, nothing
-     * to shape — and is allowed. On an RPC it is a one-way door: a `void` response can never gain a
-     * field without breaking every generated client, where `{}` grows additively forever. This is a
-     * contract-EVOLUTION rule, which is why it is here and not in the MCP half: it is worth having on
-     * an RPC that never becomes a tool.
+     * to shape — and is allowed. On an `rpc` OR an `external` it is a one-way door: both are
+     * synchronous request/response, an outside caller reads what comes back, and a `void` response
+     * can never gain a field without breaking every generated client where `{}` grows additively
+     * forever. This is a contract-EVOLUTION rule, which is why it is here and not in the MCP half: it
+     * is worth having on an endpoint that never becomes a tool. See ANSWERING_KINDS (#1017).
      */
-    private judgeRpcResponses;
+    private judgeAnsweringResponses;
     /** Everything `McpToolRegistry` refuses to boot on, plus whatever the renderer cannot render. */
     private judgeTools;
     /** Every non-test `.ts` under a project's `src` whose text DECLARES an `@ApiPath` contract. */

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

@@ -1,7 +1,12 @@
 "use strict";
 /**
  * `api-rules-for-openapi` and `api-rules-for-mcp` (#1011) — the CI half of "is this contract
- * publishable", on EVERY `@ApiPath` class in the workspace, `@ApiType` or not.
+ * publishable", on every `@ApiPath` class IN SCOPE, `@ApiType` or not.
+ *
+ * "In scope" is the rule's `mode` (#1017): `AFFECTED_PROJECT` scans the contracts of the projects the
+ * diff touched — the granularity nx already builds at, and the mode a consumer normally picks —
+ * while `RUN_EVERY_TIME` scans the whole workspace for a migration sweep. `ApiDocRule.coversProject`
+ * is the one place that answers it, for both rules.
  *
  * ## The acceptance contract, and why this file drives the generator instead of copying it
  *
@@ -21,17 +26,19 @@
  *    field). The extractor maps it to a primitive and the generator publishes `{}`, which in JSON
  *    Schema means "anything" — a partner-facing field with no shape, which is the defect the
  *    unmapped guard exists for, arriving through a door the guard does not watch.
- *  - an RPC whose response is `void`. Fire-and-forget is the CONTRACT of a `cloudtasks` or `cron`
- *    endpoint and is allowed there; an RPC that answers nothing can never gain a field without a
- *    breaking change, where a named empty response object grows additively forever.
+ *  - an `rpc` or `external` endpoint whose response is `void`. Fire-and-forget is the CONTRACT of a
+ *    `cloudtasks` or `cron` endpoint and is allowed there; an endpoint somebody WAITS on that answers
+ *    nothing can never gain a field without a breaking change, where a named empty response object
+ *    grows additively forever (#1017 — #1016 read this narrowly as rpc-only because `external` was
+ *    unstated).
  *
  * ## Why it lives in the rules engine and not in the doc parser
  *
  * `@webpieces/api-doc-model` is only ever pointed at contracts somebody chose to publish. `@ApiType`
  * is a PUBLISHING decision added later, on purpose — so a shape rule that only ran on contracts which
  * had already opted in would let a team discover, six months afterwards, that the type was never
- * expressible, by which time it is in partners' generated clients. Every check below runs on every
- * contract in the workspace.
+ * expressible, by which time it is in partners' generated clients. So every check below runs on every
+ * contract in scope, opted in or not — `@ApiType` narrows nothing here.
  *
  * ## Root-level unions are NOT re-checked here
  *
@@ -48,7 +55,6 @@ const fs = tslib_1.__importStar(require("fs"));
 const path = tslib_1.__importStar(require("path"));
 const ts = tslib_1.__importStar(require("typescript"));
 const api_doc_model_1 = require("@webpieces/api-doc-model");
-const rules_config_1 = require("@webpieces/rules-config");
 const api_ast_1 = require("./api-ast");
 const api_doc_rules_1 = require("./api-doc-rules");
 const api_doc_rules_verdicts_1 = require("./api-doc-rules-verdicts");
@@ -188,7 +194,7 @@ class ApiDocRulesScan {
      */
     exclusions = [];
     constructor(workspaceRoot, projectInfos, 
-    /** OFF unless a caller read otherwise out of webpieces.config.json — see `defaultRules`. */
+    /** OFF unless a caller read otherwise out of webpieces.config.json, which MUST state it. */
     openApiRule = api_doc_rules_1.ApiDocRule.off(api_doc_rules_1.OPENAPI_RULE), mcpRule = api_doc_rules_1.ApiDocRule.off(api_doc_rules_1.MCP_RULE)) {
         this.workspaceRoot = workspaceRoot;
         this.projectInfos = projectInfos;
@@ -245,7 +251,7 @@ class ApiDocRulesScan {
         const lines = (0, api_doc_rules_verdicts_1.contractLinesOf)(source, model.contractName);
         this.judgeUnmapped(model, sink, source.fileName);
         this.judgeUnknownValues(model, sink, source.fileName);
-        this.judgeRpcResponses(model, source, lines, sink);
+        this.judgeAnsweringResponses(model, source, lines, sink);
         this.judgeTools(model, source, lines, sink, toolNames);
     }
     /** Everything `TypeResolver` could not represent — the generator's OWN verdict, re-worded. */
@@ -269,23 +275,26 @@ class ApiDocRulesScan {
         }
     }
     /**
-     * An RPC must NAME a response DTO, even an empty one.
+     * An endpoint somebody WAITS ON must NAME a response DTO, even an empty one.
      *
      * `Promise<void>` on a `cloudtasks` or `cron` endpoint is the CONTRACT — fire-and-forget, nothing
-     * to shape — and is allowed. On an RPC it is a one-way door: a `void` response can never gain a
-     * field without breaking every generated client, where `{}` grows additively forever. This is a
-     * contract-EVOLUTION rule, which is why it is here and not in the MCP half: it is worth having on
-     * an RPC that never becomes a tool.
+     * to shape — and is allowed. On an `rpc` OR an `external` it is a one-way door: both are
+     * synchronous request/response, an outside caller reads what comes back, and a `void` response
+     * can never gain a field without breaking every generated client where `{}` grows additively
+     * forever. This is a contract-EVOLUTION rule, which is why it is here and not in the MCP half: it
+     * is worth having on an endpoint that never becomes a tool. See ANSWERING_KINDS (#1017).
      */
-    judgeRpcResponses(model, source, lines, sink) {
+    judgeAnsweringResponses(model, source, lines, sink) {
         for (const endpoint of model.endpoints) {
-            if (endpoint.kind !== api_doc_rules_verdicts_1.RPC_KIND)
+            // `.some` and not `.includes`: the model's `kind` is a widened string, and the list is
+            // typed EndpointKind so a kind that stops existing is a compile error here.
+            if (!api_doc_rules_verdicts_1.ANSWERING_KINDS.some((kind) => kind === endpoint.kind))
                 continue;
             if (endpoint.response !== undefined && !(0, api_doc_rules_verdicts_1.isVoidLike)(endpoint.response))
                 continue;
             const site = new Site(source.fileName, lines.lineOf(endpoint.methodName));
-            sink.shared(() => new api_doc_rules_1.ApiContractDefect(model.contractName, endpoint.methodName, 'an RPC returns nothing a document can name (void, unknown, or no declared ' +
-                'return type)', site.relativeTo(this.workspaceRoot), api_doc_rules_verdicts_1.VOID_RPC_CURE, model.apiTypes), site);
+            sink.shared(() => new api_doc_rules_1.ApiContractDefect(model.contractName, endpoint.methodName, `an ${endpoint.kind} endpoint returns nothing a document can name (void, ` +
+                'unknown, or no declared return type)', site.relativeTo(this.workspaceRoot), api_doc_rules_verdicts_1.VOID_RPC_CURE, model.apiTypes), site);
         }
     }
     /** Everything `McpToolRegistry` refuses to boot on, plus whatever the renderer cannot render. */
@@ -319,9 +328,11 @@ class ApiDocRulesScan {
         for (const info of this.projectInfos.values()) {
             if (info.root === '' || info.root === '.')
                 continue;
-            const openApi = this.openApiRule.enabled &&
-                !(0, rules_config_1.matchesAnyGlob)(info.root, this.openApiRule.allowedPaths);
-            const mcp = this.mcpRule.enabled && !(0, rules_config_1.matchesAnyGlob)(info.root, this.mcpRule.allowedPaths);
+            // ONE question, asked of the rule itself: `mode` (OFF / AFFECTED_PROJECT /
+            // RUN_EVERY_TIME) and `allowedPaths` are both folded into coversProject, so the
+            // affected-project narrowing cannot be honoured in one branch and skipped in the other.
+            const openApi = this.openApiRule.coversProject(info.root);
+            const mcp = this.mcpRule.coversProject(info.root);
             if (!openApi && !mcp)
                 continue;
             const srcDir = path.join(path.resolve(this.workspaceRoot, info.root), 'src');