@webpieces/nx-webpieces-rules 0.4.811 → 0.4.812

package/src/executors/validate-nx-wiring/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-nx-wiring/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate Nx Wiring Executor\n *\n * Enforces that the build graph is wired for correct build ORDER. Two checks:\n *\n * 1. nx.json targetDefaults — the compile executors (@nx/js:tsc, @angular/build:application)\n *    must carry the load-bearing dependsOn:\n *      [\"^build\"]\n *\n * 2. Per-project override guard — a project that declares its OWN build.dependsOn OVERRIDES\n *    the targetDefaults entirely (nx does not merge dependsOn). That silently drops `^build`\n *    (→ upstream libs not built first, builds against an empty dist). So we check each compile\n *    project's RESOLVED build.dependsOn and fail if `^build` is missing.\n *\n * NOTE: the webpieces validators (architecture:validate-complete, per-project file-import\n * cycles, DI-graph unchanged) NO LONGER ride on the compile target. They live on the `ci`\n * composite target (synthesized by this plugin's createCiTarget), so `build`/compile is a\n * fast compile-only step while `nx ci` runs the full gate. This executor therefore only\n * guards build ORDER (`^build`), not the validators — those are guaranteed by the plugin.\n *\n * Conservative by design: only REQUIRES wiring on compile executors actually in use\n * (@nx/js:tsc, @angular/build:application). A repo that uses neither passes.\n *\n * Disable via webpieces.config.json rules[\"nx-wiring\"].mode=\"OFF\".\n *\n * Usage: nx run architecture:validate-nx-wiring\n */\n\nimport type {\n    ExecutorContext,\n    ProjectsConfigurations,\n    TargetDependencyConfig,\n} from '@nx/devkit';\nimport { createProjectGraphAsync, readProjectsConfigurationFromProjectGraph } from '@nx/devkit';\nimport { loadAndValidate } from '@webpieces/rules-config';\nimport * as fs from 'fs';\nimport * as path from 'path';\n\nexport interface ValidateNxWiringOptions {\n    requiredDeps?: string[];\n    compileExecutors?: string[];\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n// Compile executors (and any per-project build override) must keep `^build` so build order\n// follows nx's full graph — upstreams are built into dist before dependents compile.\n// Validators no longer belong here; they ride on the `ci` composite target instead.\nconst DEFAULT_REQUIRED_DEPS: string[] = ['^build'];\n\nconst DEFAULT_COMPILE_EXECUTORS: string[] = [\n    '@nx/js:tsc',\n    '@angular/build:application',\n];\n\nclass WiringProblem {\n    executorName: string;\n    missing: string[];\n    found: string[];\n\n    constructor(executorName: string, missing: string[], found: string[]) {\n        this.executorName = executorName;\n        this.missing = missing;\n        this.found = found;\n    }\n}\n\nclass ProjectGateProblem {\n    project: string;\n    executorName: string;\n    missing: string[];\n    found: string[];\n\n    constructor(project: string, executorName: string, missing: string[], found: string[]) {\n        this.project = project;\n        this.executorName = executorName;\n        this.missing = missing;\n        this.found = found;\n    }\n}\n\ninterface TargetDefaultEntry {\n    dependsOn?: string[];\n}\n\ninterface RawNxJson {\n    targetDefaults?: Record<string, TargetDefaultEntry>;\n}\n\nfunction readTargetDefaults(workspaceRoot: string): Record<string, TargetDefaultEntry> {\n    const nxJsonPath = path.join(workspaceRoot, 'nx.json');\n    if (!fs.existsSync(nxJsonPath)) return {};\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const raw = fs.readFileSync(nxJsonPath, 'utf8');\n        const parsed = JSON.parse(raw) as RawNxJson;\n        return parsed.targetDefaults ?? {};\n        // webpieces-disable catch-error-pattern -- malformed nx.json fails open so the check does not crash the build\n    } catch (err: unknown) {\n        //const error = toError(err); -- malformed nx.json fails open\n        void err;\n        return {};\n    }\n}\n\nfunction findCompileExecutorsInUse(\n    projectsConfig: ProjectsConfigurations,\n    compileExecutors: string[],\n): Set<string> {\n    const known = new Set(compileExecutors);\n    const inUse = new Set<string>();\n    for (const cfg of Object.values(projectsConfig.projects)) {\n        const targets = cfg.targets ?? {};\n        for (const target of Object.values(targets)) {\n            const executorName = target.executor;\n            if (executorName && known.has(executorName)) {\n                inUse.add(executorName);\n            }\n        }\n    }\n    return inUse;\n}\n\nfunction findProblems(\n    relevantExecutors: string[],\n    targetDefaults: Record<string, TargetDefaultEntry>,\n    requiredDeps: string[],\n): WiringProblem[] {\n    const problems: WiringProblem[] = [];\n    for (const executorName of relevantExecutors) {\n        const entry = targetDefaults[executorName];\n        const dependsOn = entry?.dependsOn ?? [];\n        const missing = requiredDeps.filter((dep: string) => !dependsOn.includes(dep));\n        if (missing.length > 0) {\n            problems.push(new WiringProblem(executorName, missing, dependsOn));\n        }\n    }\n    return problems;\n}\n\n/**\n * Normalize an nx dependsOn entry to a comparable string. The string form (\"^build\",\n * \"validate-complete\") passes through; the object form is rendered the same way\n * ({target:\"build\", dependencies:true} → \"^build\", {target:\"build\"} → \"build\").\n */\nfunction normalizeDeps(deps: (string | TargetDependencyConfig)[]): string[] {\n    return deps.map((dep) => {\n        if (typeof dep === 'string') return dep;\n        const target = dep.target ?? '';\n        return dep.dependencies ? `^${target}` : target;\n    });\n}\n\n/**\n * Check each compile project's RESOLVED build.dependsOn (targetDefaults already merged in)\n * for `^build`. A project that overrode it away is flagged.\n */\nfunction findProjectGateProblems(\n    projectsConfig: ProjectsConfigurations,\n    compileExecutors: Set<string>,\n    requiredPerProject: string[],\n): ProjectGateProblem[] {\n    const problems: ProjectGateProblem[] = [];\n    for (const [name, cfg] of Object.entries(projectsConfig.projects)) {\n        // Tooling/foundation packages (type:tooling) BUILD the validators, so gating their own\n        // build on validate-complete would create a bootstrap cycle. They are exempt: they keep\n        // build-order (\"^build\") only. Application/library code is still fully gated.\n        if ((cfg.tags ?? []).includes('type:tooling')) continue;\n        const build = cfg.targets?.['build'];\n        if (!build || !build.executor || !compileExecutors.has(build.executor)) continue;\n        const dependsOn = normalizeDeps(build.dependsOn ?? []);\n        const missing = requiredPerProject.filter((dep) => !dependsOn.includes(dep));\n        if (missing.length > 0) {\n            problems.push(new ProjectGateProblem(name, build.executor, missing, dependsOn));\n        }\n    }\n    return problems;\n}\n\nfunction reportFailure(problems: WiringProblem[], requiredDeps: string[]): void {\n    console.error('\\n❌ Build order is not wired in nx.json targetDefaults.\\n');\n    console.error('Compile executors must keep \"^build\" so upstream libs build into dist first.');\n    console.error('Add the missing dependsOn entries to nx.json targetDefaults:\\n');\n    const depsList = requiredDeps.map((dep: string) => `\"${dep}\"`).join(', ');\n    for (const problem of problems) {\n        const missingList = problem.missing.map((dep: string) => `\"${dep}\"`).join(', ');\n        console.error(`  \"${problem.executorName}\": {`);\n        console.error(`      \"dependsOn\": [${depsList}]`);\n        console.error('  }');\n        console.error(`    missing: ${missingList}\\n`);\n    }\n    console.error('To turn this wiring check off, set rules[\"nx-wiring\"].mode=\"OFF\" in');\n    console.error('webpieces.config.json.\\n');\n}\n\nfunction reportProjectGateFailure(problems: ProjectGateProblem[]): void {\n    console.error('\\n❌ Some projects override away the build order in their project.json.\\n');\n    console.error('A project-level build.dependsOn OVERRIDES nx.json targetDefaults (nx does not');\n    console.error('merge dependsOn). That silently drops \"^build\" (upstreams not built first →');\n    console.error('builds against an empty dist).\\n');\n    console.error('Fix: remove build.dependsOn from these project.json files so targetDefaults');\n    console.error('apply, OR include \"^build\" explicitly:\\n');\n    for (const p of problems) {\n        const missingList = p.missing.map((dep) => `\"${dep}\"`).join(', ');\n        console.error(`  ${p.project} (${p.executorName}):`);\n        console.error(`    resolved build.dependsOn: ${JSON.stringify(p.found)}`);\n        console.error(`    missing: ${missingList}\\n`);\n    }\n}\n\nexport default async function runExecutor(\n    options: ValidateNxWiringOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const shared = loadAndValidate(context.root).resolved;\n    const rule = shared.rules.get('nx-wiring');\n    if (rule && rule.isOff) {\n        console.log('\\n⏭️  Skipping validate-nx-wiring (mode: OFF)\\n');\n        return { success: true };\n    }\n\n    const requiredDeps = options.requiredDeps ?? DEFAULT_REQUIRED_DEPS;\n    const compileExecutors = options.compileExecutors ?? DEFAULT_COMPILE_EXECUTORS;\n\n    console.log('\\n🔌 Validating webpieces validators are wired into the build\\n');\n\n    const projectGraph = await createProjectGraphAsync();\n    const projectsConfig = readProjectsConfigurationFromProjectGraph(projectGraph);\n\n    const inUse = findCompileExecutorsInUse(projectsConfig, compileExecutors);\n    const relevantExecutors = compileExecutors.filter((executorName: string) =>\n        inUse.has(executorName),\n    );\n\n    if (relevantExecutors.length === 0) {\n        console.log('✅ No known compile executors in use — nothing to gate\\n');\n        return { success: true };\n    }\n\n    const targetDefaults = readTargetDefaults(context.root);\n    const wiringProblems = findProblems(relevantExecutors, targetDefaults, requiredDeps);\n    const gateProblems = findProjectGateProblems(projectsConfig, inUse, requiredDeps);\n\n    if (wiringProblems.length === 0 && gateProblems.length === 0) {\n        console.log('✅ Validators are wired into the build (targetDefaults + every project)\\n');\n        return { success: true };\n    }\n\n    if (wiringProblems.length > 0) reportFailure(wiringProblems, requiredDeps);\n    if (gateProblems.length > 0) reportProjectGateFailure(gateProblems);\n    return { success: false };\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-nx-wiring/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate Nx Wiring Executor\n *\n * Enforces that the build graph is wired for correct build ORDER. Two checks:\n *\n * 1. nx.json targetDefaults — the compile executors (@nx/js:tsc, @angular/build:application)\n *    must carry the load-bearing dependsOn:\n *      [\"^build\"]\n *\n * 2. Per-project override guard — a project that declares its OWN build.dependsOn OVERRIDES\n *    the targetDefaults entirely (nx does not merge dependsOn). That silently drops `^build`\n *    (→ upstream libs not built first, builds against an empty dist). So we check each compile\n *    project's RESOLVED build.dependsOn and fail if `^build` is missing.\n *\n * NOTE: the webpieces validators (architecture:validate-complete, per-project file-import\n * cycles, DI-graph unchanged) NO LONGER ride on the compile target. They live on the `ci`\n * composite target (synthesized by this plugin's createCiTarget), so `build`/compile is a\n * fast compile-only step while `nx ci` runs the full gate. This executor therefore only\n * guards build ORDER (`^build`), not the validators — those are guaranteed by the plugin.\n *\n * 3. Generated API documents (#1021) — a project tagged `generate:openapi` / `generate:docs-site` has the\n *    `compile` → `openapi-generate` → `build` (nx:noop) shape, and every project depending on one has\n *    `test` dependsOn `^build`. See GenerateWiring for why.\n *\n * Conservative by design: only REQUIRES wiring on compile executors actually in use\n * (@nx/js:tsc, @angular/build:application). A repo that uses neither passes.\n *\n * Disable via webpieces.config.json rules[\"nx-wiring\"].mode=\"OFF\".\n *\n * Usage: nx run architecture:validate-nx-wiring\n */\n\nimport type {\n    ExecutorContext,\n    ProjectsConfigurations,\n    TargetDependencyConfig,\n} from '@nx/devkit';\nimport { createProjectGraphAsync, readProjectsConfigurationFromProjectGraph } from '@nx/devkit';\nimport { loadAndValidate } from '@webpieces/rules-config';\nimport { GenerateWiring } from '../../lib/api-docs/generate-wiring';\nimport * as fs from 'fs';\nimport * as path from 'path';\n\nexport interface ValidateNxWiringOptions {\n    requiredDeps?: string[];\n    compileExecutors?: string[];\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n// Compile executors (and any per-project build override) must keep `^build` so build order\n// follows nx's full graph — upstreams are built into dist before dependents compile.\n// Validators no longer belong here; they ride on the `ci` composite target instead.\nconst DEFAULT_REQUIRED_DEPS: string[] = ['^build'];\n\nconst DEFAULT_COMPILE_EXECUTORS: string[] = [\n    '@nx/js:tsc',\n    '@angular/build:application',\n];\n\nclass WiringProblem {\n    executorName: string;\n    missing: string[];\n    found: string[];\n\n    constructor(executorName: string, missing: string[], found: string[]) {\n        this.executorName = executorName;\n        this.missing = missing;\n        this.found = found;\n    }\n}\n\nclass ProjectGateProblem {\n    project: string;\n    executorName: string;\n    missing: string[];\n    found: string[];\n\n    constructor(project: string, executorName: string, missing: string[], found: string[]) {\n        this.project = project;\n        this.executorName = executorName;\n        this.missing = missing;\n        this.found = found;\n    }\n}\n\ninterface TargetDefaultEntry {\n    dependsOn?: string[];\n}\n\ninterface RawNxJson {\n    targetDefaults?: Record<string, TargetDefaultEntry>;\n}\n\nfunction readTargetDefaults(workspaceRoot: string): Record<string, TargetDefaultEntry> {\n    const nxJsonPath = path.join(workspaceRoot, 'nx.json');\n    if (!fs.existsSync(nxJsonPath)) return {};\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const raw = fs.readFileSync(nxJsonPath, 'utf8');\n        const parsed = JSON.parse(raw) as RawNxJson;\n        return parsed.targetDefaults ?? {};\n        // webpieces-disable catch-error-pattern -- malformed nx.json fails open so the check does not crash the build\n    } catch (err: unknown) {\n        //const error = toError(err); -- malformed nx.json fails open\n        void err;\n        return {};\n    }\n}\n\nfunction findCompileExecutorsInUse(\n    projectsConfig: ProjectsConfigurations,\n    compileExecutors: string[],\n): Set<string> {\n    const known = new Set(compileExecutors);\n    const inUse = new Set<string>();\n    for (const cfg of Object.values(projectsConfig.projects)) {\n        const targets = cfg.targets ?? {};\n        for (const target of Object.values(targets)) {\n            const executorName = target.executor;\n            if (executorName && known.has(executorName)) {\n                inUse.add(executorName);\n            }\n        }\n    }\n    return inUse;\n}\n\nfunction findProblems(\n    relevantExecutors: string[],\n    targetDefaults: Record<string, TargetDefaultEntry>,\n    requiredDeps: string[],\n): WiringProblem[] {\n    const problems: WiringProblem[] = [];\n    for (const executorName of relevantExecutors) {\n        const entry = targetDefaults[executorName];\n        const dependsOn = entry?.dependsOn ?? [];\n        const missing = requiredDeps.filter((dep: string) => !dependsOn.includes(dep));\n        if (missing.length > 0) {\n            problems.push(new WiringProblem(executorName, missing, dependsOn));\n        }\n    }\n    return problems;\n}\n\n/**\n * Normalize an nx dependsOn entry to a comparable string. The string form (\"^build\",\n * \"validate-complete\") passes through; the object form is rendered the same way\n * ({target:\"build\", dependencies:true} → \"^build\", {target:\"build\"} → \"build\").\n */\nfunction normalizeDeps(deps: (string | TargetDependencyConfig)[]): string[] {\n    return deps.map((dep) => {\n        if (typeof dep === 'string') return dep;\n        const target = dep.target ?? '';\n        return dep.dependencies ? `^${target}` : target;\n    });\n}\n\n/**\n * Check each compile project's RESOLVED build.dependsOn (targetDefaults already merged in)\n * for `^build`. A project that overrode it away is flagged.\n */\nfunction findProjectGateProblems(\n    projectsConfig: ProjectsConfigurations,\n    compileExecutors: Set<string>,\n    requiredPerProject: string[],\n): ProjectGateProblem[] {\n    const problems: ProjectGateProblem[] = [];\n    for (const [name, cfg] of Object.entries(projectsConfig.projects)) {\n        // Tooling/foundation packages (type:tooling) BUILD the validators, so gating their own\n        // build on validate-complete would create a bootstrap cycle. They are exempt: they keep\n        // build-order (\"^build\") only. Application/library code is still fully gated.\n        if ((cfg.tags ?? []).includes('type:tooling')) continue;\n        const build = cfg.targets?.['build'];\n        if (!build || !build.executor || !compileExecutors.has(build.executor)) continue;\n        const dependsOn = normalizeDeps(build.dependsOn ?? []);\n        const missing = requiredPerProject.filter((dep) => !dependsOn.includes(dep));\n        if (missing.length > 0) {\n            problems.push(new ProjectGateProblem(name, build.executor, missing, dependsOn));\n        }\n    }\n    return problems;\n}\n\nfunction reportFailure(problems: WiringProblem[], requiredDeps: string[]): void {\n    console.error('\\n❌ Build order is not wired in nx.json targetDefaults.\\n');\n    console.error('Compile executors must keep \"^build\" so upstream libs build into dist first.');\n    console.error('Add the missing dependsOn entries to nx.json targetDefaults:\\n');\n    const depsList = requiredDeps.map((dep: string) => `\"${dep}\"`).join(', ');\n    for (const problem of problems) {\n        const missingList = problem.missing.map((dep: string) => `\"${dep}\"`).join(', ');\n        console.error(`  \"${problem.executorName}\": {`);\n        console.error(`      \"dependsOn\": [${depsList}]`);\n        console.error('  }');\n        console.error(`    missing: ${missingList}\\n`);\n    }\n    console.error('To turn this wiring check off, set rules[\"nx-wiring\"].mode=\"OFF\" in');\n    console.error('webpieces.config.json.\\n');\n}\n\nfunction reportProjectGateFailure(problems: ProjectGateProblem[]): void {\n    console.error('\\n❌ Some projects override away the build order in their project.json.\\n');\n    console.error('A project-level build.dependsOn OVERRIDES nx.json targetDefaults (nx does not');\n    console.error('merge dependsOn). That silently drops \"^build\" (upstreams not built first →');\n    console.error('builds against an empty dist).\\n');\n    console.error('Fix: remove build.dependsOn from these project.json files so targetDefaults');\n    console.error('apply, OR include \"^build\" explicitly:\\n');\n    for (const p of problems) {\n        const missingList = p.missing.map((dep) => `\"${dep}\"`).join(', ');\n        console.error(`  ${p.project} (${p.executorName}):`);\n        console.error(`    resolved build.dependsOn: ${JSON.stringify(p.found)}`);\n        console.error(`    missing: ${missingList}\\n`);\n    }\n}\n\nexport default async function runExecutor(\n    options: ValidateNxWiringOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const shared = loadAndValidate(context.root).resolved;\n    const rule = shared.rules.get('nx-wiring');\n    if (rule && rule.isOff) {\n        console.log('\\n⏭️  Skipping validate-nx-wiring (mode: OFF)\\n');\n        return { success: true };\n    }\n\n    const requiredDeps = options.requiredDeps ?? DEFAULT_REQUIRED_DEPS;\n    const compileExecutors = options.compileExecutors ?? DEFAULT_COMPILE_EXECUTORS;\n\n    console.log('\\n🔌 Validating webpieces validators are wired into the build\\n');\n\n    const projectGraph = await createProjectGraphAsync();\n    const projectsConfig = readProjectsConfigurationFromProjectGraph(projectGraph);\n\n    const generateWiring = new GenerateWiring(projectsConfig.projects, projectGraph.dependencies);\n    const generateProblems = generateWiring.problems();\n\n    const inUse = findCompileExecutorsInUse(projectsConfig, compileExecutors);\n    const relevantExecutors = compileExecutors.filter((executorName: string) =>\n        inUse.has(executorName),\n    );\n\n    if (relevantExecutors.length === 0) {\n        if (generateProblems.length > 0) {\n            generateWiring.report(generateProblems);\n            return { success: false };\n        }\n        console.log('✅ No known compile executors in use — nothing to gate\\n');\n        return { success: true };\n    }\n\n    const targetDefaults = readTargetDefaults(context.root);\n    const wiringProblems = findProblems(relevantExecutors, targetDefaults, requiredDeps);\n    const gateProblems = findProjectGateProblems(projectsConfig, inUse, requiredDeps);\n\n    if (wiringProblems.length === 0 && gateProblems.length === 0 && generateProblems.length === 0) {\n        console.log('✅ Validators are wired into the build (targetDefaults + every project)\\n');\n        return { success: true };\n    }\n\n    if (wiringProblems.length > 0) reportFailure(wiringProblems, requiredDeps);\n    if (gateProblems.length > 0) reportProjectGateFailure(gateProblems);\n    if (generateProblems.length > 0) generateWiring.report(generateProblems);\n    return { success: false };\n}\n"]}

package/src/generate-targets.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The API-document targets the inference plugin adds to a project that OPTS IN with an nx tag:
+ *
+ * | tag | inferred target(s) |
+ * |---|---|
+ * | `generate:openapi` | `openapi-generate` |
+ * | `generate:docs-site` | `openapi-generate` + `docs-generate` (a site is rendered from a document) |
+ *
+ * The plugin owns the executor, `cache`, `inputs` and `outputs` — the parts that are the same for every
+ * consumer and that a hand-written target gets wrong silently (a missed output is a cache hit that
+ * restores a package WITHOUT its documents). The consumer states only what is theirs to decide, in its
+ * project.json under the SAME target name, which nx merges over what is inferred here:
+ *
+ * - `openapi-generate`: `dependsOn` (the ONE compile target whose outputPath it writes into) and
+ *   `options.manifest` / `options.format`;
+ * - `docs-generate`: `options.document` / `options.siteDir` (and optionally `options.prose`).
+ *
+ * None of those has a default (`.claude/rules/no-rule-defaults.md`): a missing one fails the run naming
+ * the key. An untagged project costs one in-memory tag check — no source scan, no `@ApiType` search.
+ * A tag the INSTALLED plugin does not know yet is ignored by it, whereas a project.json naming an
+ * executor the installed plugin lacks breaks the graph load — which is why opting in is a tag and not
+ * a hand-written executor target.
+ *
+ * The api project's shape (`compile` → `openapi-generate` → `build` as an `nx:noop`) is enforced by
+ * `validate-nx-wiring`, not here: this runs while nx builds the graph, where a throw takes the whole
+ * workspace down rather than naming one project's fix.
+ */
+import type { TargetConfiguration } from '@nx/devkit';
+import { LayoutTargets } from '@webpieces/core-util';
+export declare const GENERATE_OPENAPI_TAG = "generate:openapi";
+export declare const GENERATE_DOCS_SITE_TAG = "generate:docs-site";
+/** The two fields of the raw project.json the inference reads. Data-only. */
+export declare class RawProjectJson {
+    readonly name: string;
+    readonly tags: readonly string[];
+    readonly targets: LayoutTargets;
+    constructor(name: string, tags: readonly string[], targets: LayoutTargets);
+}
+/** Reads the raw project.json — the tags and the consumer's own target options — at graph time. */
+export declare class RawProjectJsonReader {
+    read(workspaceRoot: string, projectFile: string, projectRoot: string): RawProjectJson;
+}
+export declare class GenerateTargets {
+    /** Workspace-relative project root. */
+    private readonly projectRoot;
+    private readonly project;
+    constructor(
+    /** Workspace-relative project root. */
+    projectRoot: string, project: RawProjectJson);
+    /** The targets the project's tags opt it into — `{}` for an untagged project. */
+    infer(): Record<string, TargetConfiguration>;
+    /**
+     * `outputs` point into the compile target's outputPath, read here from the SAME lookup the
+     * executor writes with. When the consumer has not stated `dependsOn` yet there is no outputPath to
+     * point at, so no outputs are inferred — and the executor's refusal names the missing `dependsOn`.
+     */
+    private openApiGenerate;
+    private docsGenerate;
+}

package/src/generate-targets.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * The API-document targets the inference plugin adds to a project that OPTS IN with an nx tag:
+ *
+ * | tag | inferred target(s) |
+ * |---|---|
+ * | `generate:openapi` | `openapi-generate` |
+ * | `generate:docs-site` | `openapi-generate` + `docs-generate` (a site is rendered from a document) |
+ *
+ * The plugin owns the executor, `cache`, `inputs` and `outputs` — the parts that are the same for every
+ * consumer and that a hand-written target gets wrong silently (a missed output is a cache hit that
+ * restores a package WITHOUT its documents). The consumer states only what is theirs to decide, in its
+ * project.json under the SAME target name, which nx merges over what is inferred here:
+ *
+ * - `openapi-generate`: `dependsOn` (the ONE compile target whose outputPath it writes into) and
+ *   `options.manifest` / `options.format`;
+ * - `docs-generate`: `options.document` / `options.siteDir` (and optionally `options.prose`).
+ *
+ * None of those has a default (`.claude/rules/no-rule-defaults.md`): a missing one fails the run naming
+ * the key. An untagged project costs one in-memory tag check — no source scan, no `@ApiType` search.
+ * A tag the INSTALLED plugin does not know yet is ignored by it, whereas a project.json naming an
+ * executor the installed plugin lacks breaks the graph load — which is why opting in is a tag and not
+ * a hand-written executor target.
+ *
+ * The api project's shape (`compile` → `openapi-generate` → `build` as an `nx:noop`) is enforced by
+ * `validate-nx-wiring`, not here: this runs while nx builds the graph, where a throw takes the whole
+ * workspace down rather than naming one project's fix.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GenerateTargets = exports.RawProjectJsonReader = exports.RawProjectJson = exports.GENERATE_DOCS_SITE_TAG = exports.GENERATE_OPENAPI_TAG = void 0;
+const core_util_1 = require("@webpieces/core-util");
+const fs_1 = require("fs");
+const path_1 = require("path");
+exports.GENERATE_OPENAPI_TAG = 'generate:openapi';
+exports.GENERATE_DOCS_SITE_TAG = 'generate:docs-site';
+/** The two fields of the raw project.json the inference reads. Data-only. */
+class RawProjectJson {
+    name;
+    tags;
+    targets;
+    constructor(name, tags, targets) {
+        this.name = name;
+        this.tags = tags;
+        this.targets = targets;
+    }
+}
+exports.RawProjectJson = RawProjectJson;
+/** Reads the raw project.json — the tags and the consumer's own target options — at graph time. */
+class RawProjectJsonReader {
+    read(workspaceRoot, projectFile, projectRoot) {
+        const raw = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(workspaceRoot, projectFile), 'utf8'));
+        return new RawProjectJson(raw.name ?? projectRoot, raw.tags ?? [], raw.targets ?? {});
+    }
+}
+exports.RawProjectJsonReader = RawProjectJsonReader;
+class GenerateTargets {
+    projectRoot;
+    project;
+    constructor(
+    /** Workspace-relative project root. */
+    projectRoot, project) {
+        this.projectRoot = projectRoot;
+        this.project = project;
+    }
+    /** The targets the project's tags opt it into — `{}` for an untagged project. */
+    infer() {
+        const tags = this.project.tags;
+        const docs = tags.includes(exports.GENERATE_DOCS_SITE_TAG);
+        if (!docs && !tags.includes(exports.GENERATE_OPENAPI_TAG))
+            return {};
+        const targets = {};
+        targets[core_util_1.GeneratedApiDocsLayout.OPENAPI_TARGET] = this.openApiGenerate();
+        if (docs)
+            targets[core_util_1.GeneratedApiDocsLayout.DOCS_TARGET] = this.docsGenerate();
+        return targets;
+    }
+    /**
+     * `outputs` point into the compile target's outputPath, read here from the SAME lookup the
+     * executor writes with. When the consumer has not stated `dependsOn` yet there is no outputPath to
+     * point at, so no outputs are inferred — and the executor's refusal names the missing `dependsOn`.
+     */
+    openApiGenerate() {
+        const found = new core_util_1.GeneratedApiDocsLayout(this.projectRoot, this.project.name, this.project.targets)
+            .outputTarget().found;
+        const outputs = found === undefined
+            ? []
+            : [
+                `{workspaceRoot}/${found.outputPath}/*openapi.json`,
+                `{workspaceRoot}/${found.outputPath}/*openapi.yaml`,
+                `{workspaceRoot}/${found.outputPath}/mcp-*-tools.json`,
+            ];
+        return {
+            executor: '@webpieces/nx-webpieces-rules:openapi-generate',
+            cache: true,
+            inputs: ['default', '^default'],
+            outputs,
+            metadata: {
+                technologies: ['nx'],
+                description: 'Generate the OpenAPI documents + one mcp-<ContractClass>-tools.json per MCP contract into the compile outputPath (tag: generate:openapi)',
+            },
+        };
+    }
+    docsGenerate() {
+        return {
+            executor: '@webpieces/nx-webpieces-rules:docs-generate',
+            dependsOn: [core_util_1.GeneratedApiDocsLayout.OPENAPI_TARGET],
+            cache: true,
+            inputs: ['default', '^default'],
+            outputs: ['{projectRoot}/{options.siteDir}'],
+            metadata: {
+                technologies: ['nx'],
+                description: 'Render the static API reference site into <projectRoot>/<siteDir> for hosting (tag: generate:docs-site)',
+            },
+        };
+    }
+}
+exports.GenerateTargets = GenerateTargets;
+//# sourceMappingURL=generate-targets.js.map

package/src/generate-targets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-targets.js","sourceRoot":"","sources":["../../../../../packages/tooling/nx-webpieces-rules/src/generate-targets.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The API-document targets the inference plugin adds to a project that OPTS IN with an nx tag:\n *\n * | tag | inferred target(s) |\n * |---|---|\n * | `generate:openapi` | `openapi-generate` |\n * | `generate:docs-site` | `openapi-generate` + `docs-generate` (a site is rendered from a document) |\n *\n * The plugin owns the executor, `cache`, `inputs` and `outputs` — the parts that are the same for every\n * consumer and that a hand-written target gets wrong silently (a missed output is a cache hit that\n * restores a package WITHOUT its documents). The consumer states only what is theirs to decide, in its\n * project.json under the SAME target name, which nx merges over what is inferred here:\n *\n * - `openapi-generate`: `dependsOn` (the ONE compile target whose outputPath it writes into) and\n *   `options.manifest` / `options.format`;\n * - `docs-generate`: `options.document` / `options.siteDir` (and optionally `options.prose`).\n *\n * None of those has a default (`.claude/rules/no-rule-defaults.md`): a missing one fails the run naming\n * the key. An untagged project costs one in-memory tag check — no source scan, no `@ApiType` search.\n * A tag the INSTALLED plugin does not know yet is ignored by it, whereas a project.json naming an\n * executor the installed plugin lacks breaks the graph load — which is why opting in is a tag and not\n * a hand-written executor target.\n *\n * The api project's shape (`compile` → `openapi-generate` → `build` as an `nx:noop`) is enforced by\n * `validate-nx-wiring`, not here: this runs while nx builds the graph, where a throw takes the whole\n * workspace down rather than naming one project's fix.\n */\n\nimport type { TargetConfiguration } from '@nx/devkit';\nimport { GeneratedApiDocsLayout, LayoutTargets } from '@webpieces/core-util';\nimport { readFileSync } from 'fs';\nimport { join } from 'path';\n\nexport const GENERATE_OPENAPI_TAG = 'generate:openapi';\nexport const GENERATE_DOCS_SITE_TAG = 'generate:docs-site';\n\n/** The two fields of the raw project.json the inference reads. Data-only. */\nexport class RawProjectJson {\n    constructor(\n        readonly name: string,\n        readonly tags: readonly string[],\n        readonly targets: LayoutTargets,\n    ) {}\n}\n\n/** The fields of a project.json that tag-driven inference reads, as they sit in the file. */\ntype ProjectJsonFields = { name?: string; tags?: string[]; targets?: LayoutTargets };\n\n/** Reads the raw project.json — the tags and the consumer's own target options — at graph time. */\nexport class RawProjectJsonReader {\n    read(workspaceRoot: string, projectFile: string, projectRoot: string): RawProjectJson {\n        const raw = JSON.parse(readFileSync(join(workspaceRoot, projectFile), 'utf8')) as ProjectJsonFields;\n        return new RawProjectJson(raw.name ?? projectRoot, raw.tags ?? [], raw.targets ?? {});\n    }\n}\n\nexport class GenerateTargets {\n    constructor(\n        /** Workspace-relative project root. */\n        private readonly projectRoot: string,\n        private readonly project: RawProjectJson,\n    ) {}\n\n    /** The targets the project's tags opt it into — `{}` for an untagged project. */\n    infer(): Record<string, TargetConfiguration> {\n        const tags = this.project.tags;\n        const docs = tags.includes(GENERATE_DOCS_SITE_TAG);\n        if (!docs && !tags.includes(GENERATE_OPENAPI_TAG)) return {};\n        const targets: Record<string, TargetConfiguration> = {};\n        targets[GeneratedApiDocsLayout.OPENAPI_TARGET] = this.openApiGenerate();\n        if (docs) targets[GeneratedApiDocsLayout.DOCS_TARGET] = this.docsGenerate();\n        return targets;\n    }\n\n    /**\n     * `outputs` point into the compile target's outputPath, read here from the SAME lookup the\n     * executor writes with. When the consumer has not stated `dependsOn` yet there is no outputPath to\n     * point at, so no outputs are inferred — and the executor's refusal names the missing `dependsOn`.\n     */\n    private openApiGenerate(): TargetConfiguration {\n        const found = new GeneratedApiDocsLayout(this.projectRoot, this.project.name, this.project.targets)\n            .outputTarget().found;\n        const outputs = found === undefined\n            ? []\n            : [\n                `{workspaceRoot}/${found.outputPath}/*openapi.json`,\n                `{workspaceRoot}/${found.outputPath}/*openapi.yaml`,\n                `{workspaceRoot}/${found.outputPath}/mcp-*-tools.json`,\n            ];\n        return {\n            executor: '@webpieces/nx-webpieces-rules:openapi-generate',\n            cache: true,\n            inputs: ['default', '^default'],\n            outputs,\n            metadata: {\n                technologies: ['nx'],\n                description:\n                    'Generate the OpenAPI documents + one mcp-<ContractClass>-tools.json per MCP contract into the compile outputPath (tag: generate:openapi)',\n            },\n        };\n    }\n\n    private docsGenerate(): TargetConfiguration {\n        return {\n            executor: '@webpieces/nx-webpieces-rules:docs-generate',\n            dependsOn: [GeneratedApiDocsLayout.OPENAPI_TARGET],\n            cache: true,\n            inputs: ['default', '^default'],\n            outputs: ['{projectRoot}/{options.siteDir}'],\n            metadata: {\n                technologies: ['nx'],\n                description:\n                    'Render the static API reference site into <projectRoot>/<siteDir> for hosting (tag: generate:docs-site)',\n            },\n        };\n    }\n}\n"]}

package/src/lib/api-docs/consumer-bin-resolver.d.ts

@@ -0,0 +1,62 @@
+import { GeneratorPackage } from './generator-package';
+/** What to resolve, and who is asking. Data-only, per CLAUDE.md. */
+export declare class ConsumerBinRequest {
+    /** The failing target's name, so a refusal says WHICH step could not find its generator. */
+    readonly ruleName: string;
+    readonly generator: GeneratorPackage;
+    /**
+     * The CONSUMER's directories, nearest first — the project root, then the workspace root. Lookup
+     * walks up from each exactly as node does, and never from the caller's own install location.
+     */
+    readonly searchFrom: readonly string[];
+    constructor(
+    /** The failing target's name, so a refusal says WHICH step could not find its generator. */
+    ruleName: string, generator: GeneratorPackage, 
+    /**
+     * The CONSUMER's directories, nearest first — the project root, then the workspace root. Lookup
+     * walks up from each exactly as node does, and never from the caller's own install location.
+     */
+    searchFrom: readonly string[]);
+}
+/** One generator bin, resolved out of the consumer's `node_modules`. Data-only. */
+export declare class ConsumerBin {
+    readonly packageName: string;
+    readonly version: string;
+    /** The installed package.json this was read from. */
+    readonly packageJson: string;
+    /** Absolute path to the bin's entry script. */
+    readonly binPath: string;
+    constructor(packageName: string, version: string, 
+    /** The installed package.json this was read from. */
+    packageJson: string, 
+    /** Absolute path to the bin's entry script. */
+    binPath: string);
+}
+/**
+ * Finds a generator bin in the CONSUMER's `node_modules`, never in a copy bundled beside the caller,
+ * and refuses one too old to have the capabilities the caller needs.
+ *
+ * ## Why never a bundled copy
+ *
+ * The generator reads the decorators the consumer's contracts are written with, so it must be the
+ * release the consumer pinned alongside those decorators. A copy shipped inside the nx plugin would be
+ * the PLUGIN's release — the rules stream, which a repo deliberately runs one release behind — and would
+ * document an app with a reader from a different release. The lookup therefore starts only from the
+ * directories the caller names (the consumer's project and workspace), and walks up from each exactly
+ * as node's resolution does. It never consults `require.resolve` from this file, which is the one
+ * lookup that WOULD find a bundled copy.
+ *
+ * ## The version handshake
+ *
+ * A capability always ships in the generator (the server stream) BEFORE a caller relies on it, so an
+ * installed generator older than `minimumVersion` is a pin to bump, never a bug to work around. The
+ * refusal names the bump: `@webpieces/openapi-generator >= X.Y.Z`.
+ */
+export declare class ConsumerBinResolver {
+    resolve(request: ConsumerBinRequest): ConsumerBin;
+    private findPackageJson;
+    private assertNewEnough;
+    /** `X.Y.Z[-pre]`, or `undefined` for anything else — which the handshake then refuses. */
+    private parseVersion;
+    private binPathOf;
+}

package/src/lib/api-docs/consumer-bin-resolver.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsumerBinResolver = exports.ConsumerBin = exports.ConsumerBinRequest = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const rules_config_1 = require("@webpieces/rules-config");
+/** What to resolve, and who is asking. Data-only, per CLAUDE.md. */
+class ConsumerBinRequest {
+    ruleName;
+    generator;
+    searchFrom;
+    constructor(
+    /** The failing target's name, so a refusal says WHICH step could not find its generator. */
+    ruleName, generator, 
+    /**
+     * The CONSUMER's directories, nearest first — the project root, then the workspace root. Lookup
+     * walks up from each exactly as node does, and never from the caller's own install location.
+     */
+    searchFrom) {
+        this.ruleName = ruleName;
+        this.generator = generator;
+        this.searchFrom = searchFrom;
+    }
+}
+exports.ConsumerBinRequest = ConsumerBinRequest;
+/** One generator bin, resolved out of the consumer's `node_modules`. Data-only. */
+class ConsumerBin {
+    packageName;
+    version;
+    packageJson;
+    binPath;
+    constructor(packageName, version, 
+    /** The installed package.json this was read from. */
+    packageJson, 
+    /** Absolute path to the bin's entry script. */
+    binPath) {
+        this.packageName = packageName;
+        this.version = version;
+        this.packageJson = packageJson;
+        this.binPath = binPath;
+    }
+}
+exports.ConsumerBin = ConsumerBin;
+/** A parsed `X.Y.Z[-pre]`. A prerelease sorts BELOW its release, which is what semver says. */
+class ReleaseVersion {
+    major;
+    minor;
+    patch;
+    prerelease;
+    constructor(major, minor, patch, prerelease) {
+        this.major = major;
+        this.minor = minor;
+        this.patch = patch;
+        this.prerelease = prerelease;
+    }
+    isAtLeast(other) {
+        if (this.major !== other.major)
+            return this.major > other.major;
+        if (this.minor !== other.minor)
+            return this.minor > other.minor;
+        if (this.patch !== other.patch)
+            return this.patch > other.patch;
+        return !this.prerelease || other.prerelease;
+    }
+}
+/**
+ * Finds a generator bin in the CONSUMER's `node_modules`, never in a copy bundled beside the caller,
+ * and refuses one too old to have the capabilities the caller needs.
+ *
+ * ## Why never a bundled copy
+ *
+ * The generator reads the decorators the consumer's contracts are written with, so it must be the
+ * release the consumer pinned alongside those decorators. A copy shipped inside the nx plugin would be
+ * the PLUGIN's release — the rules stream, which a repo deliberately runs one release behind — and would
+ * document an app with a reader from a different release. The lookup therefore starts only from the
+ * directories the caller names (the consumer's project and workspace), and walks up from each exactly
+ * as node's resolution does. It never consults `require.resolve` from this file, which is the one
+ * lookup that WOULD find a bundled copy.
+ *
+ * ## The version handshake
+ *
+ * A capability always ships in the generator (the server stream) BEFORE a caller relies on it, so an
+ * installed generator older than `minimumVersion` is a pin to bump, never a bug to work around. The
+ * refusal names the bump: `@webpieces/openapi-generator >= X.Y.Z`.
+ */
+class ConsumerBinResolver {
+    resolve(request) {
+        const packageJson = this.findPackageJson(request);
+        const manifest = JSON.parse(fs.readFileSync(packageJson, 'utf8'));
+        const version = typeof manifest['version'] === 'string' ? manifest['version'] : '';
+        this.assertNewEnough(request, packageJson, version);
+        const binPath = this.binPathOf(request, packageJson, manifest);
+        return new ConsumerBin(request.generator.packageName, version, packageJson, binPath);
+    }
+    findPackageJson(request) {
+        for (const start of request.searchFrom) {
+            let dir = path.resolve(start);
+            for (;;) {
+                const candidate = path.join(dir, 'node_modules', ...request.generator.packageName.split('/'), 'package.json');
+                if (fs.existsSync(candidate))
+                    return candidate;
+                const parent = path.dirname(dir);
+                if (parent === dir)
+                    break;
+                dir = parent;
+            }
+        }
+        throw new rules_config_1.RuleFailError(request.ruleName, `${request.generator.packageName} is not installed in this workspace (looked in node_modules at and above: ` +
+            `${request.searchFrom.join(', ')}). The generator must be the consumer's OWN install — the ` +
+            `release pinned beside the decorators it reads — and is never taken from a bundled copy.`, undefined, undefined, [new rules_config_1.Option(`Add it as a devDependency: ${request.generator.packageName} >= ${request.generator.minimumVersion}`, true)]);
+    }
+    assertNewEnough(request, packageJson, version) {
+        const minimum = this.parseVersion(request.generator.minimumVersion);
+        if (minimum === undefined) {
+            // Our own constant, not the consumer's input — a malformed one is a webpieces bug.
+            throw new Error(`minimumVersion '${request.generator.minimumVersion}' for ${request.generator.packageName} is not X.Y.Z`);
+        }
+        const installed = this.parseVersion(version);
+        if (installed !== undefined && installed.isAtLeast(minimum))
+            return;
+        throw new rules_config_1.RuleFailError(request.ruleName, `${request.generator.packageName} ${version === '' ? '(no version)' : version} is installed at ${packageJson}, ` +
+            `and ${request.ruleName} needs ${request.generator.packageName} >= ${request.generator.minimumVersion}.` +
+            (installed !== undefined && installed.prerelease
+                ? ' A prerelease such as a workspace link\'s 0.0.0-dev is not a release and has no compiled bin.'
+                : ''), undefined, undefined, [new rules_config_1.Option(`Bump the devDependency to ${request.generator.packageName} >= ${request.generator.minimumVersion}`, true)]);
+    }
+    /** `X.Y.Z[-pre]`, or `undefined` for anything else — which the handshake then refuses. */
+    parseVersion(text) {
+        const match = /^(\d+)\.(\d+)\.(\d+)(-.+)?$/.exec(text.trim());
+        if (match === null)
+            return undefined;
+        return new ReleaseVersion(Number(match[1]), Number(match[2]), Number(match[3]), match[4] !== undefined);
+    }
+    binPathOf(request, packageJson, manifest) {
+        const bin = manifest['bin'];
+        const declared = typeof bin === 'string'
+            ? bin
+            : (bin !== null && typeof bin === 'object' && !Array.isArray(bin) ? bin[request.generator.binName] : undefined);
+        const binPath = typeof declared === 'string' ? path.resolve(path.dirname(packageJson), declared) : '';
+        if (binPath !== '' && fs.existsSync(binPath))
+            return binPath;
+        throw new rules_config_1.RuleFailError(request.ruleName, `${request.generator.packageName} at ${packageJson} declares no runnable '${request.generator.binName}' bin` +
+            (binPath === '' ? '.' : ` (${binPath} does not exist).`), undefined, undefined, [new rules_config_1.Option(`Reinstall a published release: ${request.generator.packageName} >= ${request.generator.minimumVersion}`, true)]);
+    }
+}
+exports.ConsumerBinResolver = ConsumerBinResolver;
+//# sourceMappingURL=consumer-bin-resolver.js.map

package/src/lib/api-docs/consumer-bin-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumer-bin-resolver.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-docs/consumer-bin-resolver.ts"],"names":[],"mappings":";;;;AAAA,+CAAyB;AACzB,mDAA6B;AAC7B,0DAAgE;AAIhE,oEAAoE;AACpE,MAAa,kBAAkB;IAGd;IACA;IAKA;IARb;IACI,4FAA4F;IACnF,QAAgB,EAChB,SAA2B;IACpC;;;OAGG;IACM,UAA6B;QAN7B,aAAQ,GAAR,QAAQ,CAAQ;QAChB,cAAS,GAAT,SAAS,CAAkB;QAK3B,eAAU,GAAV,UAAU,CAAmB;IACvC,CAAC;CACP;AAXD,gDAWC;AAED,mFAAmF;AACnF,MAAa,WAAW;IAEP;IACA;IAEA;IAEA;IANb,YACa,WAAmB,EACnB,OAAe;IACxB,qDAAqD;IAC5C,WAAmB;IAC5B,+CAA+C;IACtC,OAAe;QALf,gBAAW,GAAX,WAAW,CAAQ;QACnB,YAAO,GAAP,OAAO,CAAQ;QAEf,gBAAW,GAAX,WAAW,CAAQ;QAEnB,YAAO,GAAP,OAAO,CAAQ;IACzB,CAAC;CACP;AATD,kCASC;AAED,+FAA+F;AAC/F,MAAM,cAAc;IAEH;IACA;IACA;IACA;IAJb,YACa,KAAa,EACb,KAAa,EACb,KAAa,EACb,UAAmB;QAHnB,UAAK,GAAL,KAAK,CAAQ;QACb,UAAK,GAAL,KAAK,CAAQ;QACb,UAAK,GAAL,KAAK,CAAQ;QACb,eAAU,GAAV,UAAU,CAAS;IAC7B,CAAC;IAEJ,SAAS,CAAC,KAAqB;QAC3B,IAAI,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAChE,IAAI,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAChE,IAAI,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAChE,OAAO,CAAC,IAAI,CAAC,UAAU,IAAI,KAAK,CAAC,UAAU,CAAC;IAChD,CAAC;CACJ;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAa,mBAAmB;IAC5B,OAAO,CAAC,OAA2B;QAC/B,MAAM,WAAW,GAAG,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAe,CAAC;QAChF,MAAM,OAAO,GAAG,OAAO,QAAQ,CAAC,SAAS,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACnF,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;QACpD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;QAC/D,OAAO,IAAI,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IACzF,CAAC;IAEO,eAAe,CAAC,OAA2B;QAC/C,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YACrC,IAAI,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC9B,SAAS,CAAC;gBACN,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC,CAAC;gBAC9G,IAAI,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC;oBAAE,OAAO,SAAS,CAAC;gBAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;gBACjC,IAAI,MAAM,KAAK,GAAG;oBAAE,MAAM;gBAC1B,GAAG,GAAG,MAAM,CAAC;YACjB,CAAC;QACL,CAAC;QACD,MAAM,IAAI,4BAAa,CACnB,OAAO,CAAC,QAAQ,EAChB,GAAG,OAAO,CAAC,SAAS,CAAC,WAAW,4EAA4E;YACxG,GAAG,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,4DAA4D;YAC5F,yFAAyF,EAC7F,SAAS,EACT,SAAS,EACT,CAAC,IAAI,qBAAM,CAAC,8BAA8B,OAAO,CAAC,SAAS,CAAC,WAAW,OAAO,OAAO,CAAC,SAAS,CAAC,cAAc,EAAE,EAAE,IAAI,CAAC,CAAC,CAC3H,CAAC;IACN,CAAC;IAEO,eAAe,CAAC,OAA2B,EAAE,WAAmB,EAAE,OAAe;QACrF,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;QACpE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YACxB,mFAAmF;YACnF,MAAM,IAAI,KAAK,CAAC,mBAAmB,OAAO,CAAC,SAAS,CAAC,cAAc,SAAS,OAAO,CAAC,SAAS,CAAC,WAAW,eAAe,CAAC,CAAC;QAC9H,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,SAAS,CAAC,OAAO,CAAC;YAAE,OAAO;QACpE,MAAM,IAAI,4BAAa,CACnB,OAAO,CAAC,QAAQ,EAChB,GAAG,OAAO,CAAC,SAAS,CAAC,WAAW,IAAI,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,oBAAoB,WAAW,IAAI;YAC5G,OAAO,OAAO,CAAC,QAAQ,UAAU,OAAO,CAAC,SAAS,CAAC,WAAW,OAAO,OAAO,CAAC,SAAS,CAAC,cAAc,GAAG;YACxG,CAAC,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,UAAU;gBAC5C,CAAC,CAAC,+FAA+F;gBACjG,CAAC,CAAC,EAAE,CAAC,EACb,SAAS,EACT,SAAS,EACT,CAAC,IAAI,qBAAM,CAAC,6BAA6B,OAAO,CAAC,SAAS,CAAC,WAAW,OAAO,OAAO,CAAC,SAAS,CAAC,cAAc,EAAE,EAAE,IAAI,CAAC,CAAC,CAC1H,CAAC;IACN,CAAC;IAED,0FAA0F;IAClF,YAAY,CAAC,IAAY;QAC7B,MAAM,KAAK,GAAG,6BAA6B,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9D,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,SAAS,CAAC;QACrC,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;IAC5G,CAAC;IAEO,SAAS,CAAC,OAA2B,EAAE,WAAmB,EAAE,QAAoB;QACpF,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC5B,MAAM,QAAQ,GAAG,OAAO,GAAG,KAAK,QAAQ;YACpC,CAAC,CAAC,GAAG;YACL,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,GAAkB,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACpI,MAAM,OAAO,GAAG,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACtG,IAAI,OAAO,KAAK,EAAE,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC;YAAE,OAAO,OAAO,CAAC;QAC7D,MAAM,IAAI,4BAAa,CACnB,OAAO,CAAC,QAAQ,EAChB,GAAG,OAAO,CAAC,SAAS,CAAC,WAAW,OAAO,WAAW,0BAA0B,OAAO,CAAC,SAAS,CAAC,OAAO,OAAO;YACxG,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,OAAO,mBAAmB,CAAC,EAC5D,SAAS,EACT,SAAS,EACT,CAAC,IAAI,qBAAM,CAAC,kCAAkC,OAAO,CAAC,SAAS,CAAC,WAAW,OAAO,OAAO,CAAC,SAAS,CAAC,cAAc,EAAE,EAAE,IAAI,CAAC,CAAC,CAC/H,CAAC;IACN,CAAC;CACJ;AA5ED,kDA4EC","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\nimport { Option, RuleFailError } from '@webpieces/rules-config';\nimport { GeneratorPackage } from './generator-package';\nimport { JsonObject } from './json-value';\n\n/** What to resolve, and who is asking. Data-only, per CLAUDE.md. */\nexport class ConsumerBinRequest {\n    constructor(\n        /** The failing target's name, so a refusal says WHICH step could not find its generator. */\n        readonly ruleName: string,\n        readonly generator: GeneratorPackage,\n        /**\n         * The CONSUMER's directories, nearest first — the project root, then the workspace root. Lookup\n         * walks up from each exactly as node does, and never from the caller's own install location.\n         */\n        readonly searchFrom: readonly string[],\n    ) {}\n}\n\n/** One generator bin, resolved out of the consumer's `node_modules`. Data-only. */\nexport class ConsumerBin {\n    constructor(\n        readonly packageName: string,\n        readonly version: string,\n        /** The installed package.json this was read from. */\n        readonly packageJson: string,\n        /** Absolute path to the bin's entry script. */\n        readonly binPath: string,\n    ) {}\n}\n\n/** A parsed `X.Y.Z[-pre]`. A prerelease sorts BELOW its release, which is what semver says. */\nclass ReleaseVersion {\n    constructor(\n        readonly major: number,\n        readonly minor: number,\n        readonly patch: number,\n        readonly prerelease: boolean,\n    ) {}\n\n    isAtLeast(other: ReleaseVersion): boolean {\n        if (this.major !== other.major) return this.major > other.major;\n        if (this.minor !== other.minor) return this.minor > other.minor;\n        if (this.patch !== other.patch) return this.patch > other.patch;\n        return !this.prerelease || other.prerelease;\n    }\n}\n\n/**\n * Finds a generator bin in the CONSUMER's `node_modules`, never in a copy bundled beside the caller,\n * and refuses one too old to have the capabilities the caller needs.\n *\n * ## Why never a bundled copy\n *\n * The generator reads the decorators the consumer's contracts are written with, so it must be the\n * release the consumer pinned alongside those decorators. A copy shipped inside the nx plugin would be\n * the PLUGIN's release — the rules stream, which a repo deliberately runs one release behind — and would\n * document an app with a reader from a different release. The lookup therefore starts only from the\n * directories the caller names (the consumer's project and workspace), and walks up from each exactly\n * as node's resolution does. It never consults `require.resolve` from this file, which is the one\n * lookup that WOULD find a bundled copy.\n *\n * ## The version handshake\n *\n * A capability always ships in the generator (the server stream) BEFORE a caller relies on it, so an\n * installed generator older than `minimumVersion` is a pin to bump, never a bug to work around. The\n * refusal names the bump: `@webpieces/openapi-generator >= X.Y.Z`.\n */\nexport class ConsumerBinResolver {\n    resolve(request: ConsumerBinRequest): ConsumerBin {\n        const packageJson = this.findPackageJson(request);\n        const manifest = JSON.parse(fs.readFileSync(packageJson, 'utf8')) as JsonObject;\n        const version = typeof manifest['version'] === 'string' ? manifest['version'] : '';\n        this.assertNewEnough(request, packageJson, version);\n        const binPath = this.binPathOf(request, packageJson, manifest);\n        return new ConsumerBin(request.generator.packageName, version, packageJson, binPath);\n    }\n\n    private findPackageJson(request: ConsumerBinRequest): string {\n        for (const start of request.searchFrom) {\n            let dir = path.resolve(start);\n            for (;;) {\n                const candidate = path.join(dir, 'node_modules', ...request.generator.packageName.split('/'), 'package.json');\n                if (fs.existsSync(candidate)) return candidate;\n                const parent = path.dirname(dir);\n                if (parent === dir) break;\n                dir = parent;\n            }\n        }\n        throw new RuleFailError(\n            request.ruleName,\n            `${request.generator.packageName} is not installed in this workspace (looked in node_modules at and above: ` +\n                `${request.searchFrom.join(', ')}). The generator must be the consumer's OWN install — the ` +\n                `release pinned beside the decorators it reads — and is never taken from a bundled copy.`,\n            undefined,\n            undefined,\n            [new Option(`Add it as a devDependency: ${request.generator.packageName} >= ${request.generator.minimumVersion}`, true)],\n        );\n    }\n\n    private assertNewEnough(request: ConsumerBinRequest, packageJson: string, version: string): void {\n        const minimum = this.parseVersion(request.generator.minimumVersion);\n        if (minimum === undefined) {\n            // Our own constant, not the consumer's input — a malformed one is a webpieces bug.\n            throw new Error(`minimumVersion '${request.generator.minimumVersion}' for ${request.generator.packageName} is not X.Y.Z`);\n        }\n        const installed = this.parseVersion(version);\n        if (installed !== undefined && installed.isAtLeast(minimum)) return;\n        throw new RuleFailError(\n            request.ruleName,\n            `${request.generator.packageName} ${version === '' ? '(no version)' : version} is installed at ${packageJson}, ` +\n                `and ${request.ruleName} needs ${request.generator.packageName} >= ${request.generator.minimumVersion}.` +\n                (installed !== undefined && installed.prerelease\n                    ? ' A prerelease such as a workspace link\\'s 0.0.0-dev is not a release and has no compiled bin.'\n                    : ''),\n            undefined,\n            undefined,\n            [new Option(`Bump the devDependency to ${request.generator.packageName} >= ${request.generator.minimumVersion}`, true)],\n        );\n    }\n\n    /** `X.Y.Z[-pre]`, or `undefined` for anything else — which the handshake then refuses. */\n    private parseVersion(text: string): ReleaseVersion | undefined {\n        const match = /^(\\d+)\\.(\\d+)\\.(\\d+)(-.+)?$/.exec(text.trim());\n        if (match === null) return undefined;\n        return new ReleaseVersion(Number(match[1]), Number(match[2]), Number(match[3]), match[4] !== undefined);\n    }\n\n    private binPathOf(request: ConsumerBinRequest, packageJson: string, manifest: JsonObject): string {\n        const bin = manifest['bin'];\n        const declared = typeof bin === 'string'\n            ? bin\n            : (bin !== null && typeof bin === 'object' && !Array.isArray(bin) ? (bin as JsonObject)[request.generator.binName] : undefined);\n        const binPath = typeof declared === 'string' ? path.resolve(path.dirname(packageJson), declared) : '';\n        if (binPath !== '' && fs.existsSync(binPath)) return binPath;\n        throw new RuleFailError(\n            request.ruleName,\n            `${request.generator.packageName} at ${packageJson} declares no runnable '${request.generator.binName}' bin` +\n                (binPath === '' ? '.' : ` (${binPath} does not exist).`),\n            undefined,\n            undefined,\n            [new Option(`Reinstall a published release: ${request.generator.packageName} >= ${request.generator.minimumVersion}`, true)],\n        );\n    }\n}\n"]}

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

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+import type { ProjectConfiguration } from '@nx/devkit';
+import { RuleFailError } from '@webpieces/rules-config';
+/** One project's wiring defect, and the exact project.json edit that fixes it. Data-only. */
+export declare class GenerateWiringProblem {
+    readonly project: string;
+    readonly problem: string;
+    readonly cure: string;
+    constructor(project: string, problem: string, cure: string);
+}
+/** The one field of an nx graph dependency this check reads. Data-only. */
+export declare class ProjectDependency {
+    readonly target: string;
+    constructor(target: string);
+}
+export declare class GenerateWiring {
+    /** nx's RESOLVED project configurations — targetDefaults and inferred targets merged in. */
+    private readonly projects;
+    /** The project graph's dependencies, by source project. */
+    private readonly dependencies;
+    constructor(
+    /** nx's RESOLVED project configurations — targetDefaults and inferred targets merged in. */
+    projects: Readonly<Record<string, ProjectConfiguration>>, 
+    /** The project graph's dependencies, by source project. */
+    dependencies: Readonly<Record<string, readonly ProjectDependency[]>>);
+    /** The projects tagged to generate API documents. */
+    generating(): string[];
+    /** The problems as ONE structured failure: each problem in the message, each fix as an Option. */
+    failure(problems: readonly GenerateWiringProblem[]): RuleFailError;
+    /** Render {@link failure} through the one human renderer, as validate-nx-wiring's report. */
+    report(problems: readonly GenerateWiringProblem[]): void;
+    problems(): GenerateWiringProblem[];
+    /**
+     * 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).
+     */
+    private handWritten;
+    private shapeOf;
+    private dependentsOf;
+    /** Whether `target` dependsOn `wanted` — `^x` for the upstream form, `x` for a sibling. */
+    private names;
+}