@webpieces/nx-webpieces-rules 0.4.810 → 0.4.812

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

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * The build SHAPE a project opting into generated API documents must have, checked by
+ * `validate-nx-wiring` (#1021):
+ *
+ * ```
+ * <api-lib>:compile           @nx/js:tsc → its outputPath                   (dependsOn ^build)
+ * <api-lib>:openapi-generate  dependsOn ["compile"] → writes into compile's outputPath
+ * <api-lib>:build             nx:noop, dependsOn ["compile", "openapi-generate"]
+ * ```
+ *
+ * Why that shape and no other: nx `dependsOn` only points BACKWARD, generation must run AFTER tsc
+ * (whose cleanup wipes the outputPath), and every consumer only ever asks for `^build` — servers,
+ * Dockerfiles (`nx run-many -t build -p lang-server`). With `build` as a noop over both, every existing
+ * `^build` pulls generation in with zero consumer change.
+ *
+ * And one rule for the projects that DEPEND on such a library: their `test` must dependsOn `^build`.
+ * A server spec that boots the MCP server reads the library's generated tool catalogs out of its build
+ * output (`McpToolCatalog.fromPackages` on a workspace source directory), so a test run that did not
+ * build the library first fails on a missing file — or, worse, passes against a stale one.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GenerateWiring = exports.ProjectDependency = exports.GenerateWiringProblem = void 0;
+const core_util_1 = require("@webpieces/core-util");
+const rules_config_1 = require("@webpieces/rules-config");
+const generate_targets_1 = require("../../generate-targets");
+/** One project's wiring defect, and the exact project.json edit that fixes it. Data-only. */
+class GenerateWiringProblem {
+    project;
+    problem;
+    cure;
+    constructor(project, problem, cure) {
+        this.project = project;
+        this.problem = problem;
+        this.cure = cure;
+    }
+}
+exports.GenerateWiringProblem = GenerateWiringProblem;
+/** The one field of an nx graph dependency this check reads. Data-only. */
+class ProjectDependency {
+    target;
+    constructor(target) {
+        this.target = target;
+    }
+}
+exports.ProjectDependency = ProjectDependency;
+/** The executors the plugin infers from a tag — a project.json naming one by hand is a second opt-in. */
+const INFERRED_EXECUTORS = [
+    '@webpieces/nx-webpieces-rules:openapi-generate',
+    '@webpieces/nx-webpieces-rules:docs-generate',
+];
+class GenerateWiring {
+    projects;
+    dependencies;
+    constructor(
+    /** nx's RESOLVED project configurations — targetDefaults and inferred targets merged in. */
+    projects, 
+    /** The project graph's dependencies, by source project. */
+    dependencies) {
+        this.projects = projects;
+        this.dependencies = dependencies;
+    }
+    /** The projects tagged to generate API documents. */
+    generating() {
+        return Object.keys(this.projects)
+            .filter((name) => {
+            const tags = this.projects[name].tags ?? [];
+            return tags.includes(generate_targets_1.GENERATE_OPENAPI_TAG) || tags.includes(generate_targets_1.GENERATE_DOCS_SITE_TAG);
+        })
+            .sort();
+    }
+    /** The problems as ONE structured failure: each problem in the message, each fix as an Option. */
+    failure(problems) {
+        return new rules_config_1.RuleFailError('nx-wiring', 'A project generating API documents is not wired so that ^build generates them:\n' +
+            problems.map((each) => `  ${each.project}: ${each.problem}`).join('\n'), undefined, undefined, problems.map((each) => new rules_config_1.Option(`${each.project}: ${each.cure}`, true)));
+    }
+    /** Render {@link failure} through the one human renderer, as validate-nx-wiring's report. */
+    report(problems) {
+        console.error(`\n❌ ${(0, rules_config_1.renderRuleFailForHuman)(this.failure(problems))}\n`);
+    }
+    problems() {
+        const generating = this.generating();
+        const problems = this.handWritten(new Set(generating));
+        for (const name of generating)
+            problems.push(...this.shapeOf(name));
+        problems.push(...this.dependentsOf(new Set(generating)));
+        return problems;
+    }
+    /**
+     * An UNTAGGED project naming an inferred executor by hand: a second way to opt in, which also slips
+     * past the shape check (and breaks the graph load the day the installed plugin lacks the executor).
+     */
+    handWritten(generating) {
+        const problems = [];
+        for (const name of Object.keys(this.projects).sort()) {
+            if (generating.has(name))
+                continue;
+            const project = this.projects[name];
+            for (const [targetName, target] of Object.entries(project.targets ?? {})) {
+                if (target.executor === undefined || !INFERRED_EXECUTORS.includes(target.executor))
+                    continue;
+                problems.push(new GenerateWiringProblem(name, `targets.${targetName} names the executor ${target.executor} by hand, and the project has no ` +
+                    `"${generate_targets_1.GENERATE_OPENAPI_TAG}" / "${generate_targets_1.GENERATE_DOCS_SITE_TAG}" tag. Opting in is the tag; the plugin ` +
+                    'infers the executor.', `Add "${targetName === core_util_1.GeneratedApiDocsLayout.DOCS_TARGET ? generate_targets_1.GENERATE_DOCS_SITE_TAG : generate_targets_1.GENERATE_OPENAPI_TAG}" ` +
+                    `to "tags" in ${project.root}/project.json and delete the "executor" line of targets.${targetName}.`));
+            }
+        }
+        return problems;
+    }
+    shapeOf(name) {
+        const project = this.projects[name];
+        const where = `${project.root}/project.json`;
+        const targets = project.targets ?? {};
+        const lookup = new core_util_1.GeneratedApiDocsLayout(project.root, name, targets).outputTarget();
+        if (lookup.found === undefined) {
+            return [new GenerateWiringProblem(name, lookup.problem.problem, lookup.problem.cure)];
+        }
+        const compileName = lookup.found.targetName;
+        const problems = [];
+        if (!this.names(targets[compileName], '^build')) {
+            problems.push(new GenerateWiringProblem(name, `${name}:${compileName} (the target ${core_util_1.GeneratedApiDocsLayout.OPENAPI_TARGET} writes into) does ` +
+                'not dependsOn "^build", so upstream libraries are not built before it compiles.', `Add "dependsOn": ["^build"] to targets.${compileName} in ${where}.`));
+        }
+        const build = targets['build'];
+        const buildOk = build !== undefined && build.executor === 'nx:noop' &&
+            this.names(build, compileName) && this.names(build, core_util_1.GeneratedApiDocsLayout.OPENAPI_TARGET);
+        if (!buildOk) {
+            problems.push(new GenerateWiringProblem(name, `${name}:build must be an nx:noop over "${compileName}" and "${core_util_1.GeneratedApiDocsLayout.OPENAPI_TARGET}" ` +
+                `— it is what every consumer's ^build asks for, so it is what pulls generation in — and it is ` +
+                `${build === undefined ? 'missing' : `${build.executor ?? '(no executor)'} dependsOn ${JSON.stringify(build.dependsOn ?? [])}`}.`, `Set targets.build in ${where} to ` +
+                `{ "executor": "nx:noop", "dependsOn": ["${compileName}", "${core_util_1.GeneratedApiDocsLayout.OPENAPI_TARGET}"] }, ` +
+                `moving the @nx/js:tsc options to targets.${compileName}.`));
+        }
+        return problems;
+    }
+    dependentsOf(generating) {
+        const problems = [];
+        for (const name of Object.keys(this.projects).sort()) {
+            const upstream = (this.dependencies[name] ?? [])
+                .map((dependency) => dependency.target)
+                .filter((target) => generating.has(target) && target !== name);
+            const test = this.projects[name].targets?.['test'];
+            if (upstream.length === 0 || test === undefined || this.names(test, '^build'))
+                continue;
+            problems.push(new GenerateWiringProblem(name, `${name} depends on ${[...new Set(upstream)].sort().join(', ')}, which generate${upstream.length === 1 ? 's' : ''} ` +
+                'API documents and MCP tool catalogs into their build output, and its test target does not ' +
+                'dependsOn "^build" — a spec that boots the MCP server would read catalogs that were never built.', `Add "dependsOn": ["^build"] to targets.test in ${this.projects[name].root}/project.json.`));
+        }
+        return problems;
+    }
+    /** Whether `target` dependsOn `wanted` — `^x` for the upstream form, `x` for a sibling. */
+    names(target, wanted) {
+        const upstream = wanted.startsWith('^');
+        const name = upstream ? wanted.slice(1) : wanted;
+        return (target?.dependsOn ?? []).some((entry) => {
+            if (typeof entry === 'string')
+                return entry === wanted;
+            return entry.target === name && (entry.dependencies === true) === upstream;
+        });
+    }
+}
+exports.GenerateWiring = GenerateWiring;
+//# sourceMappingURL=generate-wiring.js.map

package/src/lib/api-docs/generate-wiring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-wiring.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-docs/generate-wiring.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The build SHAPE a project opting into generated API documents must have, checked by\n * `validate-nx-wiring` (#1021):\n *\n * ```\n * <api-lib>:compile           @nx/js:tsc → its outputPath                   (dependsOn ^build)\n * <api-lib>:openapi-generate  dependsOn [\"compile\"] → writes into compile's outputPath\n * <api-lib>:build             nx:noop, dependsOn [\"compile\", \"openapi-generate\"]\n * ```\n *\n * Why that shape and no other: nx `dependsOn` only points BACKWARD, generation must run AFTER tsc\n * (whose cleanup wipes the outputPath), and every consumer only ever asks for `^build` — servers,\n * Dockerfiles (`nx run-many -t build -p lang-server`). With `build` as a noop over both, every existing\n * `^build` pulls generation in with zero consumer change.\n *\n * And one rule for the projects that DEPEND on such a library: their `test` must dependsOn `^build`.\n * A server spec that boots the MCP server reads the library's generated tool catalogs out of its build\n * output (`McpToolCatalog.fromPackages` on a workspace source directory), so a test run that did not\n * build the library first fails on a missing file — or, worse, passes against a stale one.\n */\n\nimport type { ProjectConfiguration, TargetConfiguration, TargetDependencyConfig } from '@nx/devkit';\nimport { GeneratedApiDocsLayout } from '@webpieces/core-util';\nimport { Option, RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport { GENERATE_DOCS_SITE_TAG, GENERATE_OPENAPI_TAG } from '../../generate-targets';\n\n/** One project's wiring defect, and the exact project.json edit that fixes it. Data-only. */\nexport class GenerateWiringProblem {\n    constructor(\n        readonly project: string,\n        readonly problem: string,\n        readonly cure: string,\n    ) {}\n}\n\n/** The one field of an nx graph dependency this check reads. Data-only. */\nexport class ProjectDependency {\n    constructor(readonly target: string) {}\n}\n\ntype DependsOnEntry = string | TargetDependencyConfig;\n\n/** The executors the plugin infers from a tag — a project.json naming one by hand is a second opt-in. */\nconst INFERRED_EXECUTORS: readonly string[] = [\n    '@webpieces/nx-webpieces-rules:openapi-generate',\n    '@webpieces/nx-webpieces-rules:docs-generate',\n];\n\nexport class GenerateWiring {\n    constructor(\n        /** nx's RESOLVED project configurations — targetDefaults and inferred targets merged in. */\n        private readonly projects: Readonly<Record<string, ProjectConfiguration>>,\n        /** The project graph's dependencies, by source project. */\n        private readonly dependencies: Readonly<Record<string, readonly ProjectDependency[]>>,\n    ) {}\n\n    /** The projects tagged to generate API documents. */\n    generating(): string[] {\n        return Object.keys(this.projects)\n            .filter((name: string) => {\n                const tags = this.projects[name]!.tags ?? [];\n                return tags.includes(GENERATE_OPENAPI_TAG) || tags.includes(GENERATE_DOCS_SITE_TAG);\n            })\n            .sort();\n    }\n\n    /** The problems as ONE structured failure: each problem in the message, each fix as an Option. */\n    failure(problems: readonly GenerateWiringProblem[]): RuleFailError {\n        return new RuleFailError(\n            'nx-wiring',\n            'A project generating API documents is not wired so that ^build generates them:\\n' +\n                problems.map((each: GenerateWiringProblem) => `  ${each.project}: ${each.problem}`).join('\\n'),\n            undefined,\n            undefined,\n            problems.map((each: GenerateWiringProblem) => new Option(`${each.project}: ${each.cure}`, true)),\n        );\n    }\n\n    /** Render {@link failure} through the one human renderer, as validate-nx-wiring's report. */\n    report(problems: readonly GenerateWiringProblem[]): void {\n        console.error(`\\n❌ ${renderRuleFailForHuman(this.failure(problems))}\\n`);\n    }\n\n    problems(): GenerateWiringProblem[] {\n        const generating = this.generating();\n        const problems: GenerateWiringProblem[] = this.handWritten(new Set(generating));\n        for (const name of generating) problems.push(...this.shapeOf(name));\n        problems.push(...this.dependentsOf(new Set(generating)));\n        return problems;\n    }\n\n    /**\n     * An UNTAGGED project naming an inferred executor by hand: a second way to opt in, which also slips\n     * past the shape check (and breaks the graph load the day the installed plugin lacks the executor).\n     */\n    private handWritten(generating: ReadonlySet<string>): GenerateWiringProblem[] {\n        const problems: GenerateWiringProblem[] = [];\n        for (const name of Object.keys(this.projects).sort()) {\n            if (generating.has(name)) continue;\n            const project = this.projects[name]!;\n            for (const [targetName, target] of Object.entries(project.targets ?? {})) {\n                if (target.executor === undefined || !INFERRED_EXECUTORS.includes(target.executor)) continue;\n                problems.push(new GenerateWiringProblem(\n                    name,\n                    `targets.${targetName} names the executor ${target.executor} by hand, and the project has no ` +\n                        `\"${GENERATE_OPENAPI_TAG}\" / \"${GENERATE_DOCS_SITE_TAG}\" tag. Opting in is the tag; the plugin ` +\n                        'infers the executor.',\n                    `Add \"${targetName === GeneratedApiDocsLayout.DOCS_TARGET ? GENERATE_DOCS_SITE_TAG : GENERATE_OPENAPI_TAG}\" ` +\n                        `to \"tags\" in ${project.root}/project.json and delete the \"executor\" line of targets.${targetName}.`,\n                ));\n            }\n        }\n        return problems;\n    }\n\n    private shapeOf(name: string): GenerateWiringProblem[] {\n        const project = this.projects[name]!;\n        const where = `${project.root}/project.json`;\n        const targets = project.targets ?? {};\n        const lookup = new GeneratedApiDocsLayout(project.root, name, targets).outputTarget();\n        if (lookup.found === undefined) {\n            return [new GenerateWiringProblem(name, lookup.problem!.problem, lookup.problem!.cure)];\n        }\n        const compileName = lookup.found.targetName;\n        const problems: GenerateWiringProblem[] = [];\n        if (!this.names(targets[compileName], '^build')) {\n            problems.push(new GenerateWiringProblem(\n                name,\n                `${name}:${compileName} (the target ${GeneratedApiDocsLayout.OPENAPI_TARGET} writes into) does ` +\n                    'not dependsOn \"^build\", so upstream libraries are not built before it compiles.',\n                `Add \"dependsOn\": [\"^build\"] to targets.${compileName} in ${where}.`,\n            ));\n        }\n        const build = targets['build'];\n        const buildOk = build !== undefined && build.executor === 'nx:noop' &&\n            this.names(build, compileName) && this.names(build, GeneratedApiDocsLayout.OPENAPI_TARGET);\n        if (!buildOk) {\n            problems.push(new GenerateWiringProblem(\n                name,\n                `${name}:build must be an nx:noop over \"${compileName}\" and \"${GeneratedApiDocsLayout.OPENAPI_TARGET}\" ` +\n                    `— it is what every consumer's ^build asks for, so it is what pulls generation in — and it is ` +\n                    `${build === undefined ? 'missing' : `${build.executor ?? '(no executor)'} dependsOn ${JSON.stringify(build.dependsOn ?? [])}`}.`,\n                `Set targets.build in ${where} to ` +\n                    `{ \"executor\": \"nx:noop\", \"dependsOn\": [\"${compileName}\", \"${GeneratedApiDocsLayout.OPENAPI_TARGET}\"] }, ` +\n                    `moving the @nx/js:tsc options to targets.${compileName}.`,\n            ));\n        }\n        return problems;\n    }\n\n    private dependentsOf(generating: ReadonlySet<string>): GenerateWiringProblem[] {\n        const problems: GenerateWiringProblem[] = [];\n        for (const name of Object.keys(this.projects).sort()) {\n            const upstream = (this.dependencies[name] ?? [])\n                .map((dependency: ProjectDependency) => dependency.target)\n                .filter((target: string) => generating.has(target) && target !== name);\n            const test = this.projects[name]!.targets?.['test'];\n            if (upstream.length === 0 || test === undefined || this.names(test, '^build')) continue;\n            problems.push(new GenerateWiringProblem(\n                name,\n                `${name} depends on ${[...new Set(upstream)].sort().join(', ')}, which generate${upstream.length === 1 ? 's' : ''} ` +\n                    'API documents and MCP tool catalogs into their build output, and its test target does not ' +\n                    'dependsOn \"^build\" — a spec that boots the MCP server would read catalogs that were never built.',\n                `Add \"dependsOn\": [\"^build\"] to targets.test in ${this.projects[name]!.root}/project.json.`,\n            ));\n        }\n        return problems;\n    }\n\n    /** Whether `target` dependsOn `wanted` — `^x` for the upstream form, `x` for a sibling. */\n    private names(target: TargetConfiguration | undefined, wanted: string): boolean {\n        const upstream = wanted.startsWith('^');\n        const name = upstream ? wanted.slice(1) : wanted;\n        return (target?.dependsOn ?? []).some((entry: DependsOnEntry) => {\n            if (typeof entry === 'string') return entry === wanted;\n            return entry.target === name && (entry.dependencies === true) === upstream;\n        });\n    }\n}\n"]}

package/src/lib/api-docs/generator-package.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A generator the `openapi-generate` / `docs-generate` executors RUN but never bundle, and the oldest
+ * release of it that has every capability the executor relies on. Data-only.
+ *
+ * `minimumVersion` is the version handshake. A capability ships in the generator (the server stream)
+ * first; the executor that relies on it follows, and raises this number in the same change. Keep it the
+ * FIRST release carrying the capability, not the latest one — raising it further forces a consumer bump
+ * that buys nothing.
+ */
+export declare class GeneratorPackage {
+    readonly packageName: string;
+    readonly binName: string;
+    readonly minimumVersion: string;
+    constructor(packageName: string, binName: string, minimumVersion: string);
+}
+/**
+ * `wp-openapi` with `--manifest/--out/--format`, writing ONE MCP tool catalog PER CONTRACT
+ * (`mcp-<ContractClass>-tools.json`, #1021). 0.4.812 is the first release carrying that layout; an
+ * older generator writes the single `mcp-tools.json` no server of this release reads.
+ */
+export declare const OPENAPI_GENERATOR: GeneratorPackage;
+/** `wp-docs-site --spec/--prose/--out`: 0.4.807 is the first release carrying the docs site (#1007). */
+export declare const DOCS_SITE: GeneratorPackage;

package/src/lib/api-docs/generator-package.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOCS_SITE = exports.OPENAPI_GENERATOR = exports.GeneratorPackage = void 0;
+/**
+ * A generator the `openapi-generate` / `docs-generate` executors RUN but never bundle, and the oldest
+ * release of it that has every capability the executor relies on. Data-only.
+ *
+ * `minimumVersion` is the version handshake. A capability ships in the generator (the server stream)
+ * first; the executor that relies on it follows, and raises this number in the same change. Keep it the
+ * FIRST release carrying the capability, not the latest one — raising it further forces a consumer bump
+ * that buys nothing.
+ */
+class GeneratorPackage {
+    packageName;
+    binName;
+    minimumVersion;
+    constructor(packageName, binName, minimumVersion) {
+        this.packageName = packageName;
+        this.binName = binName;
+        this.minimumVersion = minimumVersion;
+    }
+}
+exports.GeneratorPackage = GeneratorPackage;
+/**
+ * `wp-openapi` with `--manifest/--out/--format`, writing ONE MCP tool catalog PER CONTRACT
+ * (`mcp-<ContractClass>-tools.json`, #1021). 0.4.812 is the first release carrying that layout; an
+ * older generator writes the single `mcp-tools.json` no server of this release reads.
+ */
+exports.OPENAPI_GENERATOR = new GeneratorPackage('@webpieces/openapi-generator', 'wp-openapi', '0.4.812');
+/** `wp-docs-site --spec/--prose/--out`: 0.4.807 is the first release carrying the docs site (#1007). */
+exports.DOCS_SITE = new GeneratorPackage('@webpieces/docs-site', 'wp-docs-site', '0.4.807');
+//# sourceMappingURL=generator-package.js.map

package/src/lib/api-docs/generator-package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator-package.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-docs/generator-package.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,MAAa,gBAAgB;IAEZ;IACA;IACA;IAHb,YACa,WAAmB,EACnB,OAAe,EACf,cAAsB;QAFtB,gBAAW,GAAX,WAAW,CAAQ;QACnB,YAAO,GAAP,OAAO,CAAQ;QACf,mBAAc,GAAd,cAAc,CAAQ;IAChC,CAAC;CACP;AAND,4CAMC;AAED;;;;GAIG;AACU,QAAA,iBAAiB,GAAG,IAAI,gBAAgB,CAAC,8BAA8B,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;AAE/G,wGAAwG;AAC3F,QAAA,SAAS,GAAG,IAAI,gBAAgB,CAAC,sBAAsB,EAAE,cAAc,EAAE,SAAS,CAAC,CAAC","sourcesContent":["/**\n * A generator the `openapi-generate` / `docs-generate` executors RUN but never bundle, and the oldest\n * release of it that has every capability the executor relies on. Data-only.\n *\n * `minimumVersion` is the version handshake. A capability ships in the generator (the server stream)\n * first; the executor that relies on it follows, and raises this number in the same change. Keep it the\n * FIRST release carrying the capability, not the latest one — raising it further forces a consumer bump\n * that buys nothing.\n */\nexport class GeneratorPackage {\n    constructor(\n        readonly packageName: string,\n        readonly binName: string,\n        readonly minimumVersion: string,\n    ) {}\n}\n\n/**\n * `wp-openapi` with `--manifest/--out/--format`, writing ONE MCP tool catalog PER CONTRACT\n * (`mcp-<ContractClass>-tools.json`, #1021). 0.4.812 is the first release carrying that layout; an\n * older generator writes the single `mcp-tools.json` no server of this release reads.\n */\nexport const OPENAPI_GENERATOR = new GeneratorPackage('@webpieces/openapi-generator', 'wp-openapi', '0.4.812');\n\n/** `wp-docs-site --spec/--prose/--out`: 0.4.807 is the first release carrying the docs site (#1007). */\nexport const DOCS_SITE = new GeneratorPackage('@webpieces/docs-site', 'wp-docs-site', '0.4.807');\n"]}

package/src/lib/api-docs/generator-runner.d.ts

@@ -0,0 +1,21 @@
+import { ConsumerBin } from './consumer-bin-resolver';
+/** One finished generator process. Data-only. */
+export declare class GeneratorRun {
+    readonly exitCode: number;
+    /** stdout and stderr, in that order — the generator reports its refusals on stdout. */
+    readonly output: string;
+    constructor(exitCode: number, 
+    /** stdout and stderr, in that order — the generator reports its refusals on stdout. */
+    output: string);
+    get ok(): boolean;
+}
+/**
+ * Runs a resolved {@link ConsumerBin} with the node that is running US, so the generator gets the
+ * consumer's `node_modules` (it lives there) without depending on a `.bin` shim or on `PATH`.
+ *
+ * It REPORTS the outcome rather than throwing on a non-zero exit, so the executor that ran it decides
+ * how to word the refusal (it names the manifest or the document it was rendering).
+ */
+export declare class GeneratorRunner {
+    run(bin: ConsumerBin, args: readonly string[], cwd: string): GeneratorRun;
+}

package/src/lib/api-docs/generator-runner.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeneratorRunner = exports.GeneratorRun = void 0;
+const child_process_1 = require("child_process");
+/** One finished generator process. Data-only. */
+class GeneratorRun {
+    exitCode;
+    output;
+    constructor(exitCode, 
+    /** stdout and stderr, in that order — the generator reports its refusals on stdout. */
+    output) {
+        this.exitCode = exitCode;
+        this.output = output;
+    }
+    get ok() {
+        return this.exitCode === 0;
+    }
+}
+exports.GeneratorRun = GeneratorRun;
+/**
+ * Runs a resolved {@link ConsumerBin} with the node that is running US, so the generator gets the
+ * consumer's `node_modules` (it lives there) without depending on a `.bin` shim or on `PATH`.
+ *
+ * It REPORTS the outcome rather than throwing on a non-zero exit, so the executor that ran it decides
+ * how to word the refusal (it names the manifest or the document it was rendering).
+ */
+class GeneratorRunner {
+    run(bin, args, cwd) {
+        const result = (0, child_process_1.spawnSync)(process.execPath, [bin.binPath, ...args], { cwd, encoding: 'utf8' });
+        const output = [result.stdout ?? '', result.stderr ?? '', result.error?.message ?? '']
+            .filter((part) => part.trim() !== '')
+            .join('\n')
+            .trim();
+        return new GeneratorRun(result.status ?? 1, output);
+    }
+}
+exports.GeneratorRunner = GeneratorRunner;
+//# sourceMappingURL=generator-runner.js.map

package/src/lib/api-docs/generator-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator-runner.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-docs/generator-runner.ts"],"names":[],"mappings":";;;AAAA,iDAA0C;AAG1C,iDAAiD;AACjD,MAAa,YAAY;IAER;IAEA;IAHb,YACa,QAAgB;IACzB,uFAAuF;IAC9E,MAAc;QAFd,aAAQ,GAAR,QAAQ,CAAQ;QAEhB,WAAM,GAAN,MAAM,CAAQ;IACxB,CAAC;IAEJ,IAAI,EAAE;QACF,OAAO,IAAI,CAAC,QAAQ,KAAK,CAAC,CAAC;IAC/B,CAAC;CACJ;AAVD,oCAUC;AAED;;;;;;GAMG;AACH,MAAa,eAAe;IACxB,GAAG,CAAC,GAAgB,EAAE,IAAuB,EAAE,GAAW;QACtD,MAAM,MAAM,GAAG,IAAA,yBAAS,EAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;QAC9F,MAAM,MAAM,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE,EAAE,MAAM,CAAC,KAAK,EAAE,OAAO,IAAI,EAAE,CAAC;aACjF,MAAM,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;aAC5C,IAAI,CAAC,IAAI,CAAC;aACV,IAAI,EAAE,CAAC;QACZ,OAAO,IAAI,YAAY,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;IACxD,CAAC;CACJ;AATD,0CASC","sourcesContent":["import { spawnSync } from 'child_process';\nimport { ConsumerBin } from './consumer-bin-resolver';\n\n/** One finished generator process. Data-only. */\nexport class GeneratorRun {\n    constructor(\n        readonly exitCode: number,\n        /** stdout and stderr, in that order — the generator reports its refusals on stdout. */\n        readonly output: string,\n    ) {}\n\n    get ok(): boolean {\n        return this.exitCode === 0;\n    }\n}\n\n/**\n * Runs a resolved {@link ConsumerBin} with the node that is running US, so the generator gets the\n * consumer's `node_modules` (it lives there) without depending on a `.bin` shim or on `PATH`.\n *\n * It REPORTS the outcome rather than throwing on a non-zero exit, so the executor that ran it decides\n * how to word the refusal (it names the manifest or the document it was rendering).\n */\nexport class GeneratorRunner {\n    run(bin: ConsumerBin, args: readonly string[], cwd: string): GeneratorRun {\n        const result = spawnSync(process.execPath, [bin.binPath, ...args], { cwd, encoding: 'utf8' });\n        const output = [result.stdout ?? '', result.stderr ?? '', result.error?.message ?? '']\n            .filter((part: string) => part.trim() !== '')\n            .join('\\n')\n            .trim();\n        return new GeneratorRun(result.status ?? 1, output);\n    }\n}\n"]}

package/src/lib/api-docs/generator-target.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The shared half of the `openapi-generate` and `docs-generate` executors: WHERE a generated document
+ * goes, and the proof that the target is wired so that nx both orders and caches it correctly.
+ *
+ * Both halves read the project's own declarations and never supply a value of their own:
+ *
+ * - the documents' directory is the `outputPath` of the target `openapi-generate` dependsOn — the api
+ *   library's `compile` (tsc) step, which writes the directory the package is packed from, so the
+ *   documents ship INSIDE the published package. It is ASKED of nx through `GeneratedApiDocsLayout`
+ *   (`@webpieces/core-util`), the same lookup `McpToolCatalog.fromPackages` reads with, and never
+ *   assumed: this repo builds into a workspace-root `dist/apps/...`, another consumer builds into a
+ *   project-local `<project>/dist`, and hardcoding either one — or the target's NAME — generates the
+ *   document somewhere the package is not packed from;
+ * - the ordering and the cache are the target's own `dependsOn` and `outputs`, which the executor
+ *   checks rather than trusts, because both failures are silent: without the `dependsOn` edge, tsc's
+ *   clean of `outputPath` races the write (the document vanishes and a dependent test dies on ENOENT,
+ *   intermittently, only in CI), and `outputs` that miss a written file make every cache hit restore a
+ *   package without that file.
+ */
+import type { ExecutorContext, TargetConfiguration } from '@nx/devkit';
+export declare class GeneratorTarget {
+    /** The executor's name, which is what every refusal is reported under. */
+    readonly ruleName: string;
+    readonly workspaceRoot: string;
+    readonly projectName: string;
+    /** Workspace-relative. */
+    readonly projectRoot: string;
+    readonly targetName: string;
+    readonly target: TargetConfiguration;
+    readonly targets: Record<string, TargetConfiguration>;
+    constructor(
+    /** The executor's name, which is what every refusal is reported under. */
+    ruleName: string, workspaceRoot: string, projectName: string, 
+    /** Workspace-relative. */
+    projectRoot: string, targetName: string, target: TargetConfiguration, targets: Record<string, TargetConfiguration>);
+    static of(ruleName: string, context: ExecutorContext): GeneratorTarget;
+    /**
+     * Absolute path to the directory the documents live in: the `outputPath` of the target
+     * `openapi-generate` dependsOn — the directory the package is packed from.
+     */
+    documentsDir(): string;
+    /** Absolute `<projectRoot>/<dir>`, refusing anything that is not strictly inside the project. */
+    insideProject(dir: string, optionName: string): string;
+    /** Refuse unless this target `dependsOn` the sibling `required` target. */
+    assertDependsOn(required: string): void;
+    /** Refuse unless every written file is covered by the target's declared `outputs`, so a cache hit restores it. */
+    assertOutputsCover(writtenAbs: readonly string[]): void;
+    /** A workspace-relative path the consumer stated, from `options`, required and never defaulted. */
+    requiredOption(value: string | undefined, name: string): string;
+    private namesSibling;
+    /** nx's own tokens, so a path written the way nx accepts it resolves the way nx resolves it. */
+    private interpolate;
+}
+/**
+ * Generate into a STAGING directory, then publish into the output directory — so the executor knows
+ * exactly which files the run produced (for {@link GeneratorTarget.assertOutputsCover}) without
+ * parsing a generator's console output, and a failed run leaves the output directory untouched.
+ */
+export declare class StagedOutput {
+    publish(stagingDir: string, destDir: string): string[];
+}

package/src/lib/api-docs/generator-target.js

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * The shared half of the `openapi-generate` and `docs-generate` executors: WHERE a generated document
+ * goes, and the proof that the target is wired so that nx both orders and caches it correctly.
+ *
+ * Both halves read the project's own declarations and never supply a value of their own:
+ *
+ * - the documents' directory is the `outputPath` of the target `openapi-generate` dependsOn — the api
+ *   library's `compile` (tsc) step, which writes the directory the package is packed from, so the
+ *   documents ship INSIDE the published package. It is ASKED of nx through `GeneratedApiDocsLayout`
+ *   (`@webpieces/core-util`), the same lookup `McpToolCatalog.fromPackages` reads with, and never
+ *   assumed: this repo builds into a workspace-root `dist/apps/...`, another consumer builds into a
+ *   project-local `<project>/dist`, and hardcoding either one — or the target's NAME — generates the
+ *   document somewhere the package is not packed from;
+ * - the ordering and the cache are the target's own `dependsOn` and `outputs`, which the executor
+ *   checks rather than trusts, because both failures are silent: without the `dependsOn` edge, tsc's
+ *   clean of `outputPath` races the write (the document vanishes and a dependent test dies on ENOENT,
+ *   intermittently, only in CI), and `outputs` that miss a written file make every cache hit restore a
+ *   package without that file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StagedOutput = exports.GeneratorTarget = void 0;
+const tslib_1 = require("tslib");
+const core_util_1 = require("@webpieces/core-util");
+const rules_config_1 = require("@webpieces/rules-config");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+class GeneratorTarget {
+    ruleName;
+    workspaceRoot;
+    projectName;
+    projectRoot;
+    targetName;
+    target;
+    targets;
+    constructor(
+    /** The executor's name, which is what every refusal is reported under. */
+    ruleName, workspaceRoot, projectName, 
+    /** Workspace-relative. */
+    projectRoot, targetName, target, targets) {
+        this.ruleName = ruleName;
+        this.workspaceRoot = workspaceRoot;
+        this.projectName = projectName;
+        this.projectRoot = projectRoot;
+        this.targetName = targetName;
+        this.target = target;
+        this.targets = targets;
+    }
+    // webpieces-disable no-function-outside-class -- static factory of this class
+    static of(ruleName, context) {
+        const projectName = context.projectName ?? '';
+        const project = context.projectsConfigurations?.projects[projectName];
+        const targetName = context.targetName ?? '';
+        const target = project?.targets?.[targetName];
+        if (project === undefined || target === undefined) {
+            // nx hands every executor its own project and target; their absence is our bug, not the consumer's.
+            throw new Error(`${ruleName}: nx did not describe project '${projectName}' target '${targetName}'`);
+        }
+        return new GeneratorTarget(ruleName, context.root, projectName, project.root, targetName, target, project.targets ?? {});
+    }
+    /**
+     * Absolute path to the directory the documents live in: the `outputPath` of the target
+     * `openapi-generate` dependsOn — the directory the package is packed from.
+     */
+    documentsDir() {
+        const lookup = new core_util_1.GeneratedApiDocsLayout(this.projectRoot, this.projectName, this.targets).outputTarget();
+        if (lookup.found === undefined) {
+            throw new rules_config_1.RuleFailError(this.ruleName, `${lookup.problem.problem} The documents go into the build's own output directory — the ` +
+                'one the package is packed from — and are never assumed to be ./dist.', undefined, undefined, [new rules_config_1.Option(lookup.problem.cure, true)]);
+        }
+        return path.resolve(this.workspaceRoot, lookup.found.outputPath);
+    }
+    /** Absolute `<projectRoot>/<dir>`, refusing anything that is not strictly inside the project. */
+    insideProject(dir, optionName) {
+        const projectAbs = path.resolve(this.workspaceRoot, this.projectRoot);
+        const resolved = path.resolve(projectAbs, dir);
+        const relative = path.relative(projectAbs, resolved);
+        if (relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative))
+            return resolved;
+        throw new rules_config_1.RuleFailError(this.ruleName, `${this.projectName}:${this.targetName} options.${optionName} is '${dir}', which is not a directory ` +
+            `strictly inside ${this.projectRoot}. It is emptied and rewritten on every run, so it may only ` +
+            'name a directory of the project\'s own.', undefined, undefined, [new rules_config_1.Option(`Set options.${optionName} to a project-relative directory, e.g. "generated-docs"`, true)]);
+    }
+    /** Refuse unless this target `dependsOn` the sibling `required` target. */
+    assertDependsOn(required) {
+        const entries = this.target.dependsOn ?? [];
+        if (entries.some((entry) => this.namesSibling(entry, required)))
+            return;
+        throw new rules_config_1.RuleFailError(this.ruleName, `${this.projectName}:${this.targetName} does not declare dependsOn "${required}". It reads what ` +
+            `${required} writes, so without that edge nx may run it before or alongside ${required} and ` +
+            `render a stale or missing document. That fails intermittently and mostly in CI, which is ` +
+            `why it is refused here instead.`, undefined, undefined, [new rules_config_1.Option(`Add "dependsOn": ["${required}"] to the ${this.targetName} target in ${this.projectRoot}/project.json`, true)]);
+    }
+    /** Refuse unless every written file is covered by the target's declared `outputs`, so a cache hit restores it. */
+    assertOutputsCover(writtenAbs) {
+        const patterns = (this.target.outputs ?? []).map((output) => this.interpolate(output));
+        const uncovered = writtenAbs
+            .map((file) => path.relative(this.workspaceRoot, file).split(path.sep).join('/'))
+            .filter((file) => !(0, rules_config_1.matchesAnyGlob)(file, patterns));
+        if (uncovered.length === 0)
+            return;
+        throw new rules_config_1.RuleFailError(this.ruleName, `${this.projectName}:${this.targetName} wrote files its declared outputs do not cover, so a ` +
+            `cache hit would restore a package WITHOUT them:\n` +
+            uncovered.map((file) => `  ${file}`).join('\n'), undefined, undefined, [new rules_config_1.Option(`Cover them in the ${this.targetName} target's "outputs" in ${this.projectRoot}/project.json, ` +
+                `e.g. "{workspaceRoot}/${path.posix.dirname(uncovered[0])}/<the files>"`, true)]);
+    }
+    /** A workspace-relative path the consumer stated, from `options`, required and never defaulted. */
+    requiredOption(value, name) {
+        if (typeof value === 'string' && value.trim() !== '')
+            return value;
+        throw new rules_config_1.RuleFailError(this.ruleName, `${this.projectName}:${this.targetName} has no options.${name}. It is required and has no default.`, undefined, undefined, [new rules_config_1.Option(`Set options.${name} on the ${this.targetName} target in ${this.projectRoot}/project.json`, true)]);
+    }
+    namesSibling(entry, required) {
+        if (typeof entry === 'string')
+            return entry === required;
+        const projects = entry.projects;
+        const self = projects === undefined || projects === 'self' ||
+            (Array.isArray(projects) && projects.length === 1 && projects[0] === this.projectName);
+        return entry.target === required && entry.dependencies !== true && self;
+    }
+    /** nx's own tokens, so a path written the way nx accepts it resolves the way nx resolves it. */
+    interpolate(text) {
+        return text
+            .replace(/\{workspaceRoot\}\/?/g, '')
+            .replace(/\{projectRoot\}/g, this.projectRoot)
+            .replace(/\{projectName\}/g, this.projectName)
+            .replace(/\{options\.([A-Za-z0-9_]+)\}/g, (whole, key) => {
+            const value = this.target.options?.[key];
+            return typeof value === 'string' ? value : whole;
+        });
+    }
+}
+exports.GeneratorTarget = GeneratorTarget;
+/**
+ * Generate into a STAGING directory, then publish into the output directory — so the executor knows
+ * exactly which files the run produced (for {@link GeneratorTarget.assertOutputsCover}) without
+ * parsing a generator's console output, and a failed run leaves the output directory untouched.
+ */
+class StagedOutput {
+    publish(stagingDir, destDir) {
+        const written = [];
+        const copy = (from, to) => {
+            fs.mkdirSync(to, { recursive: true });
+            for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+                const source = path.join(from, entry.name);
+                const target = path.join(to, entry.name);
+                if (entry.isDirectory()) {
+                    copy(source, target);
+                }
+                else {
+                    fs.copyFileSync(source, target);
+                    written.push(target);
+                }
+            }
+        };
+        copy(stagingDir, destDir);
+        return written.sort();
+    }
+}
+exports.StagedOutput = StagedOutput;
+//# sourceMappingURL=generator-target.js.map

package/src/lib/api-docs/generator-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator-target.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-docs/generator-target.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The shared half of the `openapi-generate` and `docs-generate` executors: WHERE a generated document\n * goes, and the proof that the target is wired so that nx both orders and caches it correctly.\n *\n * Both halves read the project's own declarations and never supply a value of their own:\n *\n * - the documents' directory is the `outputPath` of the target `openapi-generate` dependsOn — the api\n *   library's `compile` (tsc) step, which writes the directory the package is packed from, so the\n *   documents ship INSIDE the published package. It is ASKED of nx through `GeneratedApiDocsLayout`\n *   (`@webpieces/core-util`), the same lookup `McpToolCatalog.fromPackages` reads with, and never\n *   assumed: this repo builds into a workspace-root `dist/apps/...`, another consumer builds into a\n *   project-local `<project>/dist`, and hardcoding either one — or the target's NAME — generates the\n *   document somewhere the package is not packed from;\n * - the ordering and the cache are the target's own `dependsOn` and `outputs`, which the executor\n *   checks rather than trusts, because both failures are silent: without the `dependsOn` edge, tsc's\n *   clean of `outputPath` races the write (the document vanishes and a dependent test dies on ENOENT,\n *   intermittently, only in CI), and `outputs` that miss a written file make every cache hit restore a\n *   package without that file.\n */\n\nimport type { ExecutorContext, TargetConfiguration, TargetDependencyConfig } from '@nx/devkit';\nimport { GeneratedApiDocsLayout } from '@webpieces/core-util';\nimport { Option, RuleFailError, matchesAnyGlob } from '@webpieces/rules-config';\nimport * as fs from 'fs';\nimport * as path from 'path';\n\n/** What `dependsOn` may name: a sibling target by name, or nx's object form of the same. */\ntype DependsOnEntry = string | TargetDependencyConfig;\n\nexport class GeneratorTarget {\n    constructor(\n        /** The executor's name, which is what every refusal is reported under. */\n        readonly ruleName: string,\n        readonly workspaceRoot: string,\n        readonly projectName: string,\n        /** Workspace-relative. */\n        readonly projectRoot: string,\n        readonly targetName: string,\n        readonly target: TargetConfiguration,\n        readonly targets: Record<string, TargetConfiguration>,\n    ) {}\n\n    // webpieces-disable no-function-outside-class -- static factory of this class\n    static of(ruleName: string, context: ExecutorContext): GeneratorTarget {\n        const projectName = context.projectName ?? '';\n        const project = context.projectsConfigurations?.projects[projectName];\n        const targetName = context.targetName ?? '';\n        const target = project?.targets?.[targetName];\n        if (project === undefined || target === undefined) {\n            // nx hands every executor its own project and target; their absence is our bug, not the consumer's.\n            throw new Error(`${ruleName}: nx did not describe project '${projectName}' target '${targetName}'`);\n        }\n        return new GeneratorTarget(\n            ruleName, context.root, projectName, project.root, targetName, target, project.targets ?? {});\n    }\n\n    /**\n     * Absolute path to the directory the documents live in: the `outputPath` of the target\n     * `openapi-generate` dependsOn — the directory the package is packed from.\n     */\n    documentsDir(): string {\n        const lookup = new GeneratedApiDocsLayout(this.projectRoot, this.projectName, this.targets).outputTarget();\n        if (lookup.found === undefined) {\n            throw new RuleFailError(\n                this.ruleName,\n                `${lookup.problem!.problem} The documents go into the build's own output directory — the ` +\n                    'one the package is packed from — and are never assumed to be ./dist.',\n                undefined,\n                undefined,\n                [new Option(lookup.problem!.cure, true)],\n            );\n        }\n        return path.resolve(this.workspaceRoot, lookup.found.outputPath);\n    }\n\n    /** Absolute `<projectRoot>/<dir>`, refusing anything that is not strictly inside the project. */\n    insideProject(dir: string, optionName: string): string {\n        const projectAbs = path.resolve(this.workspaceRoot, this.projectRoot);\n        const resolved = path.resolve(projectAbs, dir);\n        const relative = path.relative(projectAbs, resolved);\n        if (relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative)) return resolved;\n        throw new RuleFailError(\n            this.ruleName,\n            `${this.projectName}:${this.targetName} options.${optionName} is '${dir}', which is not a directory ` +\n                `strictly inside ${this.projectRoot}. It is emptied and rewritten on every run, so it may only ` +\n                'name a directory of the project\\'s own.',\n            undefined,\n            undefined,\n            [new Option(`Set options.${optionName} to a project-relative directory, e.g. \"generated-docs\"`, true)],\n        );\n    }\n\n    /** Refuse unless this target `dependsOn` the sibling `required` target. */\n    assertDependsOn(required: string): void {\n        const entries: readonly DependsOnEntry[] = this.target.dependsOn ?? [];\n        if (entries.some((entry: DependsOnEntry) => this.namesSibling(entry, required))) return;\n        throw new RuleFailError(\n            this.ruleName,\n            `${this.projectName}:${this.targetName} does not declare dependsOn \"${required}\". It reads what ` +\n                `${required} writes, so without that edge nx may run it before or alongside ${required} and ` +\n                `render a stale or missing document. That fails intermittently and mostly in CI, which is ` +\n                `why it is refused here instead.`,\n            undefined,\n            undefined,\n            [new Option(`Add \"dependsOn\": [\"${required}\"] to the ${this.targetName} target in ${this.projectRoot}/project.json`, true)],\n        );\n    }\n\n    /** Refuse unless every written file is covered by the target's declared `outputs`, so a cache hit restores it. */\n    assertOutputsCover(writtenAbs: readonly string[]): void {\n        const patterns = (this.target.outputs ?? []).map((output: string) => this.interpolate(output));\n        const uncovered = writtenAbs\n            .map((file: string) => path.relative(this.workspaceRoot, file).split(path.sep).join('/'))\n            .filter((file: string) => !matchesAnyGlob(file, patterns));\n        if (uncovered.length === 0) return;\n        throw new RuleFailError(\n            this.ruleName,\n            `${this.projectName}:${this.targetName} wrote files its declared outputs do not cover, so a ` +\n                `cache hit would restore a package WITHOUT them:\\n` +\n                uncovered.map((file: string) => `  ${file}`).join('\\n'),\n            undefined,\n            undefined,\n            [new Option(\n                `Cover them in the ${this.targetName} target's \"outputs\" in ${this.projectRoot}/project.json, ` +\n                    `e.g. \"{workspaceRoot}/${path.posix.dirname(uncovered[0]!)}/<the files>\"`,\n                true,\n            )],\n        );\n    }\n\n    /** A workspace-relative path the consumer stated, from `options`, required and never defaulted. */\n    requiredOption(value: string | undefined, name: string): string {\n        if (typeof value === 'string' && value.trim() !== '') return value;\n        throw new RuleFailError(\n            this.ruleName,\n            `${this.projectName}:${this.targetName} has no options.${name}. It is required and has no default.`,\n            undefined,\n            undefined,\n            [new Option(`Set options.${name} on the ${this.targetName} target in ${this.projectRoot}/project.json`, true)],\n        );\n    }\n\n    private namesSibling(entry: DependsOnEntry, required: string): boolean {\n        if (typeof entry === 'string') return entry === required;\n        const projects = entry.projects;\n        const self = projects === undefined || projects === 'self' ||\n            (Array.isArray(projects) && projects.length === 1 && projects[0] === this.projectName);\n        return entry.target === required && entry.dependencies !== true && self;\n    }\n\n    /** nx's own tokens, so a path written the way nx accepts it resolves the way nx resolves it. */\n    private interpolate(text: string): string {\n        return text\n            .replace(/\\{workspaceRoot\\}\\/?/g, '')\n            .replace(/\\{projectRoot\\}/g, this.projectRoot)\n            .replace(/\\{projectName\\}/g, this.projectName)\n            .replace(/\\{options\\.([A-Za-z0-9_]+)\\}/g, (whole: string, key: string): string => {\n                const value = this.target.options?.[key];\n                return typeof value === 'string' ? value : whole;\n            });\n    }\n}\n\n/**\n * Generate into a STAGING directory, then publish into the output directory — so the executor knows\n * exactly which files the run produced (for {@link GeneratorTarget.assertOutputsCover}) without\n * parsing a generator's console output, and a failed run leaves the output directory untouched.\n */\nexport class StagedOutput {\n    publish(stagingDir: string, destDir: string): string[] {\n        const written: string[] = [];\n        const copy = (from: string, to: string): void => {\n            fs.mkdirSync(to, { recursive: true });\n            for (const entry of fs.readdirSync(from, { withFileTypes: true })) {\n                const source = path.join(from, entry.name);\n                const target = path.join(to, entry.name);\n                if (entry.isDirectory()) {\n                    copy(source, target);\n                } else {\n                    fs.copyFileSync(source, target);\n                    written.push(target);\n                }\n            }\n        };\n        copy(stagingDir, destDir);\n        return written.sort();\n    }\n}\n"]}

package/src/lib/api-docs/json-value.d.ts

@@ -0,0 +1,6 @@
+/** Everything a JSON document can hold — a parsed OpenAPI document or package.json is exactly this. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | JsonObject;
+/** The object case of {@link JsonValue}, named so the recursive alias can refer to it. */
+export type JsonObject = {
+    [key: string]: JsonValue;
+};

package/src/lib/api-docs/json-value.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=json-value.js.map

package/src/lib/api-docs/json-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-value.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-docs/json-value.ts"],"names":[],"mappings":"","sourcesContent":["/** Everything a JSON document can hold — a parsed OpenAPI document or package.json is exactly this. */\nexport type JsonValue = string | number | boolean | null | JsonValue[] | JsonObject;\n\n/** The object case of {@link JsonValue}, named so the recursive alias can refer to it. */\nexport type JsonObject = { [key: string]: JsonValue };\n"]}

package/src/plugin.d.ts

@@ -4,6 +4,8 @@
  * This plugin automatically creates targets for:
  * 1. Workspace-level architecture validation (generate, visualize, validate-*)
  * 2. Per-project circular dependency checking
+ * 3. Per-project API documents, opted into with a TAG: `generate:openapi` infers `openapi-generate`,
+ *    `generate:docs-site` infers `openapi-generate` + `docs-generate` (see generate-targets.ts)
  *
  * Install with: nx add @webpieces/nx-webpieces-rules
  *