@webpieces/openapi-generator 0.0.1

package/src/emit/ArtifactWriter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArtifactWriter.js","sourceRoot":"","sources":["../../../../../../packages/docs/openapi-generator/src/emit/ArtifactWriter.ts"],"names":[],"mappings":";;;;AAAA,oDAA8B;AAC9B,wDAAkC;AAElC,mDAAgD;AAChD,mDAAgD;AAEhD,6EAA6E;AAC7E,MAAa,iBAAiB;IAEb;IACA;IAFb,YACa,QAAgB,EAChB,IAAY;QADZ,aAAQ,GAAR,QAAQ,CAAQ;QAChB,SAAI,GAAJ,IAAI,CAAQ;IACtB,CAAC;CACP;AALD,8CAKC;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAa,cAAc;IACN,IAAI,GAAG,IAAI,uBAAU,EAAE,CAAC;IACxB,IAAI,GAAG,IAAI,uBAAU,EAAE,CAAC;IAEzC,SAAS,CAAC,SAA6B,EAAE,MAAoB;QACzD,MAAM,SAAS,GAAwB,EAAE,CAAC;QAC1C,KAAK,MAAM,SAAS,IAAI,SAAS,CAAC,SAAS,EAAE,CAAC;YAC1C,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;gBACpB,SAAS,CAAC,IAAI,CACV,IAAI,iBAAiB,CACjB,GAAG,SAAS,CAAC,QAAQ,OAAO,EAC5B,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,CACtC,CACJ,CAAC;YACN,CAAC;YACD,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;gBACpB,SAAS,CAAC,IAAI,CACV,IAAI,iBAAiB,CACjB,GAAG,SAAS,CAAC,QAAQ,OAAO,EAC5B,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,CACtC,CACJ,CAAC;YACN,CAAC;QACL,CAAC;QACD,OAAO,SAAS,CAAC;IACrB,CAAC;IAED,kGAAkG;IAClG,KAAK,CAAC,MAAc,EAAE,SAAuC;QACzD,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1C,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC,QAA2B,EAAE,EAAE;YACjD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAClD,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC9C,OAAO,IAAI,CAAC;QAChB,CAAC,CAAC,CAAC;IACP,CAAC;IAED,kFAAkF;IAClF,WAAW,CAAC,SAA6B;QACrC,OAAO,SAAS,CAAC,SAAS,CAAC;IAC/B,CAAC;CACJ;AAzCD,wCAyCC","sourcesContent":["import * as fs from 'node:fs';\nimport * as path from 'node:path';\nimport { GeneratedDocument, GeneratedDocuments } from '../generate/GenerationInputs';\nimport { JsonWriter } from '../json/JsonWriter';\nimport { YamlWriter } from '../json/YamlWriter';\n\n/** One file this generation pass produces: its name, and its exact bytes. */\nexport class GeneratedArtifact {\n    constructor(\n        readonly fileName: string,\n        readonly text: string,\n    ) {}\n}\n\n/** Which serializations to write. Orthogonal to WHICH documents `@ApiType` selected. */\nexport type OutputFormat = 'json' | 'yaml' | 'both';\n\n/**\n * The generated documents, serialized.\n *\n * | file | audience |\n * |---|---|\n * | `full-private-openapi.json` | internal. Every contract declaring `SVC_TO_SVC`, hidden methods included. Nothing renders it for humans |\n * | `public-openapi.json` | customers. Contracts declaring `EXTERNAL_CUSTOMER`, minus every `{ hidden: true }` method |\n * | `mcp-openapi.json` | agents. Contracts declaring `MCP`, carrying the `x-mcp-*` extensions |\n *\n * A document is written only when some contract declared its type, which is decided by the generator\n * — this class writes what it is given. `--format` then chooses `.json`, `.yaml` or both from the\n * SAME in-memory document, so the two serializations cannot disagree.\n *\n * ## Why the goldens commit JSON only\n *\n * Committing both would double the review surface every decorator change has to be diffed against,\n * for a second file that is the first one restated. One spec parses each emitted YAML and asserts\n * deep equality with its JSON counterpart instead, which proves the YAML is correct without asking\n * anybody to read it.\n *\n * ## Why the JSON documents ARE committed\n *\n * `diff full-private-openapi.json public-openapi.json` is the complete list of what these contracts\n * do not show a customer. That only works as a review device if both files are in the tree, so hiding\n * a method shows up as a diff in the PR that hides it.\n */\nexport class ArtifactWriter {\n    private readonly json = new JsonWriter();\n    private readonly yaml = new YamlWriter();\n\n    artifacts(documents: GeneratedDocuments, format: OutputFormat): readonly GeneratedArtifact[] {\n        const artifacts: GeneratedArtifact[] = [];\n        for (const generated of documents.documents) {\n            if (format !== 'yaml') {\n                artifacts.push(\n                    new GeneratedArtifact(\n                        `${generated.fileName}.json`,\n                        this.json.write(generated.document),\n                    ),\n                );\n            }\n            if (format !== 'json') {\n                artifacts.push(\n                    new GeneratedArtifact(\n                        `${generated.fileName}.yaml`,\n                        this.yaml.write(generated.document),\n                    ),\n                );\n            }\n        }\n        return artifacts;\n    }\n\n    /** Write them all, creating `outDir` if it does not exist. Returns the absolute paths written. */\n    write(outDir: string, artifacts: readonly GeneratedArtifact[]): readonly string[] {\n        fs.mkdirSync(outDir, { recursive: true });\n        return artifacts.map((artifact: GeneratedArtifact) => {\n            const file = path.join(outDir, artifact.fileName);\n            fs.writeFileSync(file, artifact.text, 'utf8');\n            return file;\n        });\n    }\n\n    /** The document objects, for a caller that wants them rather than their bytes. */\n    documentsOf(documents: GeneratedDocuments): readonly GeneratedDocument[] {\n        return documents.documents;\n    }\n}\n"]}

package/src/generate/DocumentSelection.d.ts

@@ -0,0 +1,96 @@
+import { ApiDocModel, DocumentedEndpoint } from '@webpieces/api-doc-model';
+import { ApiTypeKind } from '@webpieces/core-util';
+/** The one line that says a document is not the customer contract. It appears in exactly one. */
+export declare const INTERNAL_ONLY_LINE = "INTERNAL \u2014 service-to-service use only. This document lists every endpoint these services serve, including ones no customer is meant to see. It is not the customer contract and must never be handed to one.";
+/**
+ * The retry contract, published ONCE per document rather than as booleans stamped on every operation.
+ *
+ * Each operation's own `description` ends with one derived sentence saying whether it is safe to
+ * retry; this table says where that sentence comes from. Three vendor-extension booleans per
+ * operation would have been invisible to a human — Swagger UI and most themes do not render `x-`
+ * extensions, and no standard generator reads `x-webpieces-*` — and would have tripled golden churn
+ * the day the mapping changed.
+ */
+export declare const OPERATION_SEMANTICS: string;
+/**
+ * WHICH contracts and operations a document contains, and what prose it stamps. The ONLY thing that
+ * differs between the three generated documents.
+ *
+ * ## Two orthogonal decisions, at two levels
+ *
+ * - `@ApiType(SVC_TO_SVC, EXTERNAL_CUSTOMER)` on the CONTRACT selects which FILES it feeds. A document
+ *   is written at all only when some contract declares its type, so no contract declaring `MCP` means
+ *   no `mcp-openapi.json` — there is no second emptiness rule to keep in step with that one.
+ * - `{ hidden: true }` on ONE `@Endpoint` subtracts that method from the CUSTOMER document only. It
+ *   stays in the private document, and in the MCP document when it is a tool.
+ *
+ * The per-method case is real and cannot be said at class level: a NEW endpoint on an
+ * already-published API, built on main before it is announced. The per-contract case is the one that
+ * must not default to permissive, and at class level naming it costs one token per contract.
+ *
+ * ## Select, then render — never render, then filter
+ *
+ * One render function takes one of these and is called once per document. It builds
+ * `components.schemas` by walking OUTWARD from the operations this selection accepted, so an
+ * unselected operation's DTOs are never constructed at all.
+ *
+ * That asymmetry is about what a BUG does. Build-then-filter puts an unreleased feature's full
+ * request and response schemas into the document and then relies on a removal pass to take them out
+ * again — so a defect in the visibility logic SHIPS them, named and fully shaped, with only the URL
+ * missing, to customers who were told the feature was withheld. Select-then-render cannot do that:
+ * no code path can emit a schema that was never built.
+ *
+ * The usual objection to rendering more than once — that the passes drift in how each renders the
+ * same endpoint — applies to separate code paths. This is ONE function, so same code, same input,
+ * same output.
+ *
+ * ## The thing that bites: map ordering
+ *
+ * Collecting schemas during a walk makes the key order of `components.schemas` depend on which
+ * operations were walked, so two documents would list identical schemas in different orders and the
+ * goldens would churn on unrelated changes. The renderer SORTS the schema keys before emitting.
+ * Orders that carry MEANING are left alone and said so where they are built: `apis[]` order is the
+ * published sidebar, and the security-scheme order is the order the credentials are declared in.
+ */
+export declare class DocumentSelection {
+    /** The file name this document is written to, and the name a failure uses for it. */
+    readonly fileName: string;
+    /** The `@ApiType` a contract must declare to appear in this document. */
+    readonly apiType: ApiTypeKind;
+    /** Drop methods marked `{ hidden: true }`. True for the customer document alone. */
+    readonly dropHidden: boolean;
+    /** Stamp `x-mcp-tool` and its siblings. Only the MCP document has a reader for them. */
+    readonly includeMcpExtensions: boolean;
+    /**
+     * Prepend {@link INTERNAL_ONLY_LINE} to `info.description`, and say what TRIGGERS each
+     * operation. Both are internal facts: a customer calls what they are given a url for, and
+     * whether ours fires on a clock or off a queue is our business.
+     */
+    readonly internalNotice: boolean;
+    private constructor();
+    /** Every contract declaring `SVC_TO_SVC` — which, by the fail-closed default, is every contract. */
+    static internal(): DocumentSelection;
+    /** Every contract declaring `EXTERNAL_CUSTOMER`, minus its hidden methods. */
+    static customer(): DocumentSelection;
+    /**
+     * Every contract declaring `MCP`. A HIDDEN method is kept — an internal endpoint that is an agent
+     * tool is still a tool, and requiring it to be published to customers in order to be one would be
+     * exactly the wrong coupling.
+     */
+    static mcp(): DocumentSelection;
+    /** Every document this generator knows how to write, in the order it writes them. */
+    static all(): readonly DocumentSelection[];
+    acceptsContract(model: ApiDocModel): boolean;
+    /**
+     * `{ hidden: true }` subtracts a method from the CUSTOMER document, and `@WpAuthLocalOnly`
+     * subtracts it from ALL of them.
+     *
+     * A local-only endpoint is not registered as a route at all once the process is deployed, so it
+     * exists nowhere any reader of any of these documents could call it. Publishing it even in the
+     * private one would document a route that does not exist in any deployed environment — worse
+     * than omitting it, because a reader would reasonably try to call it.
+     */
+    acceptsEndpoint(endpoint: DocumentedEndpoint): boolean;
+    /** `info.description`: the manifest's prose, plus whatever this document adds to it. */
+    description(manifestDescription: string | undefined): string | undefined;
+}

package/src/generate/DocumentSelection.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocumentSelection = exports.OPERATION_SEMANTICS = exports.INTERNAL_ONLY_LINE = void 0;
+const core_util_1 = require("@webpieces/core-util");
+/** The one line that says a document is not the customer contract. It appears in exactly one. */
+exports.INTERNAL_ONLY_LINE = 'INTERNAL — service-to-service use only. This document lists every endpoint these services serve, including ones no customer is meant to see. It is not the customer contract and must never be handed to one.';
+/**
+ * The retry contract, published ONCE per document rather than as booleans stamped on every operation.
+ *
+ * Each operation's own `description` ends with one derived sentence saying whether it is safe to
+ * retry; this table says where that sentence comes from. Three vendor-extension booleans per
+ * operation would have been invisible to a human — Swagger UI and most themes do not render `x-`
+ * extensions, and no standard generator reads `x-webpieces-*` — and would have tripled golden churn
+ * the day the mapping changed.
+ */
+exports.OPERATION_SEMANTICS = [
+    "Every operation states whether it is safe to retry, derived from the endpoint's declared",
+    'side-effect contract:',
+    '',
+    '| declared operation | read-only | destructive | idempotent |',
+    '|---|---|---|---|',
+    '| read | yes | no | yes |',
+    '| write-idempotent | no | yes | yes |',
+    '| write | no | yes | no |',
+].join('\n');
+/**
+ * WHICH contracts and operations a document contains, and what prose it stamps. The ONLY thing that
+ * differs between the three generated documents.
+ *
+ * ## Two orthogonal decisions, at two levels
+ *
+ * - `@ApiType(SVC_TO_SVC, EXTERNAL_CUSTOMER)` on the CONTRACT selects which FILES it feeds. A document
+ *   is written at all only when some contract declares its type, so no contract declaring `MCP` means
+ *   no `mcp-openapi.json` — there is no second emptiness rule to keep in step with that one.
+ * - `{ hidden: true }` on ONE `@Endpoint` subtracts that method from the CUSTOMER document only. It
+ *   stays in the private document, and in the MCP document when it is a tool.
+ *
+ * The per-method case is real and cannot be said at class level: a NEW endpoint on an
+ * already-published API, built on main before it is announced. The per-contract case is the one that
+ * must not default to permissive, and at class level naming it costs one token per contract.
+ *
+ * ## Select, then render — never render, then filter
+ *
+ * One render function takes one of these and is called once per document. It builds
+ * `components.schemas` by walking OUTWARD from the operations this selection accepted, so an
+ * unselected operation's DTOs are never constructed at all.
+ *
+ * That asymmetry is about what a BUG does. Build-then-filter puts an unreleased feature's full
+ * request and response schemas into the document and then relies on a removal pass to take them out
+ * again — so a defect in the visibility logic SHIPS them, named and fully shaped, with only the URL
+ * missing, to customers who were told the feature was withheld. Select-then-render cannot do that:
+ * no code path can emit a schema that was never built.
+ *
+ * The usual objection to rendering more than once — that the passes drift in how each renders the
+ * same endpoint — applies to separate code paths. This is ONE function, so same code, same input,
+ * same output.
+ *
+ * ## The thing that bites: map ordering
+ *
+ * Collecting schemas during a walk makes the key order of `components.schemas` depend on which
+ * operations were walked, so two documents would list identical schemas in different orders and the
+ * goldens would churn on unrelated changes. The renderer SORTS the schema keys before emitting.
+ * Orders that carry MEANING are left alone and said so where they are built: `apis[]` order is the
+ * published sidebar, and the security-scheme order is the order the credentials are declared in.
+ */
+class DocumentSelection {
+    fileName;
+    apiType;
+    dropHidden;
+    includeMcpExtensions;
+    internalNotice;
+    constructor(
+    /** The file name this document is written to, and the name a failure uses for it. */
+    fileName, 
+    /** The `@ApiType` a contract must declare to appear in this document. */
+    apiType, 
+    /** Drop methods marked `{ hidden: true }`. True for the customer document alone. */
+    dropHidden, 
+    /** Stamp `x-mcp-tool` and its siblings. Only the MCP document has a reader for them. */
+    includeMcpExtensions, 
+    /**
+     * Prepend {@link INTERNAL_ONLY_LINE} to `info.description`, and say what TRIGGERS each
+     * operation. Both are internal facts: a customer calls what they are given a url for, and
+     * whether ours fires on a clock or off a queue is our business.
+     */
+    internalNotice) {
+        this.fileName = fileName;
+        this.apiType = apiType;
+        this.dropHidden = dropHidden;
+        this.includeMcpExtensions = includeMcpExtensions;
+        this.internalNotice = internalNotice;
+    }
+    /** Every contract declaring `SVC_TO_SVC` — which, by the fail-closed default, is every contract. */
+    // webpieces-disable no-function-outside-class -- static factory; the private constructor is what stops a fourth, unnamed selection being invented at a call site
+    static internal() {
+        return new DocumentSelection('full-private-openapi', core_util_1.SVC_TO_SVC, false, false, true);
+    }
+    /** Every contract declaring `EXTERNAL_CUSTOMER`, minus its hidden methods. */
+    // webpieces-disable no-function-outside-class -- static factory of this class
+    static customer() {
+        return new DocumentSelection('public-openapi', core_util_1.EXTERNAL_CUSTOMER, true, false, false);
+    }
+    /**
+     * Every contract declaring `MCP`. A HIDDEN method is kept — an internal endpoint that is an agent
+     * tool is still a tool, and requiring it to be published to customers in order to be one would be
+     * exactly the wrong coupling.
+     */
+    // webpieces-disable no-function-outside-class -- static factory of this class
+    static mcp() {
+        return new DocumentSelection('mcp-openapi', core_util_1.MCP, false, true, false);
+    }
+    /** Every document this generator knows how to write, in the order it writes them. */
+    // webpieces-disable no-function-outside-class -- static factory of this class
+    static all() {
+        return [
+            DocumentSelection.internal(),
+            DocumentSelection.customer(),
+            DocumentSelection.mcp(),
+        ];
+    }
+    acceptsContract(model) {
+        return model.apiTypes.includes(this.apiType);
+    }
+    /**
+     * `{ hidden: true }` subtracts a method from the CUSTOMER document, and `@WpAuthLocalOnly`
+     * subtracts it from ALL of them.
+     *
+     * A local-only endpoint is not registered as a route at all once the process is deployed, so it
+     * exists nowhere any reader of any of these documents could call it. Publishing it even in the
+     * private one would document a route that does not exist in any deployed environment — worse
+     * than omitting it, because a reader would reasonably try to call it.
+     */
+    acceptsEndpoint(endpoint) {
+        if (endpoint.auth?.decorator === core_util_1.WpAuthLocalOnly.name) {
+            return false;
+        }
+        return !this.dropHidden || !endpoint.hidden;
+    }
+    /** `info.description`: the manifest's prose, plus whatever this document adds to it. */
+    description(manifestDescription) {
+        const parts = [];
+        if (this.internalNotice) {
+            parts.push(exports.INTERNAL_ONLY_LINE);
+        }
+        if (manifestDescription !== undefined) {
+            parts.push(manifestDescription);
+        }
+        parts.push(exports.OPERATION_SEMANTICS);
+        return parts.join('\n\n');
+    }
+}
+exports.DocumentSelection = DocumentSelection;
+//# sourceMappingURL=DocumentSelection.js.map

package/src/generate/DocumentSelection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocumentSelection.js","sourceRoot":"","sources":["../../../../../../packages/docs/openapi-generator/src/generate/DocumentSelection.ts"],"names":[],"mappings":";;;AACA,oDAM8B;AAE9B,iGAAiG;AACpF,QAAA,kBAAkB,GAC3B,+MAA+M,CAAC;AAEpN;;;;;;;;GAQG;AACU,QAAA,mBAAmB,GAAG;IAC/B,0FAA0F;IAC1F,uBAAuB;IACvB,EAAE;IACF,+DAA+D;IAC/D,mBAAmB;IACnB,2BAA2B;IAC3B,uCAAuC;IACvC,2BAA2B;CAC9B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAa,iBAAiB;IAGb;IAEA;IAEA;IAEA;IAMA;IAdb;IACI,qFAAqF;IAC5E,QAAgB;IACzB,yEAAyE;IAChE,OAAoB;IAC7B,oFAAoF;IAC3E,UAAmB;IAC5B,wFAAwF;IAC/E,oBAA6B;IACtC;;;;OAIG;IACM,cAAuB;QAZvB,aAAQ,GAAR,QAAQ,CAAQ;QAEhB,YAAO,GAAP,OAAO,CAAa;QAEpB,eAAU,GAAV,UAAU,CAAS;QAEnB,yBAAoB,GAApB,oBAAoB,CAAS;QAM7B,mBAAc,GAAd,cAAc,CAAS;IACjC,CAAC;IAEJ,oGAAoG;IACpG,iKAAiK;IACjK,MAAM,CAAC,QAAQ;QACX,OAAO,IAAI,iBAAiB,CAAC,sBAAsB,EAAE,sBAAU,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IACzF,CAAC;IAED,8EAA8E;IAC9E,8EAA8E;IAC9E,MAAM,CAAC,QAAQ;QACX,OAAO,IAAI,iBAAiB,CAAC,gBAAgB,EAAE,6BAAiB,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IAC1F,CAAC;IAED;;;;OAIG;IACH,8EAA8E;IAC9E,MAAM,CAAC,GAAG;QACN,OAAO,IAAI,iBAAiB,CAAC,aAAa,EAAE,eAAG,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACzE,CAAC;IAED,qFAAqF;IACrF,8EAA8E;IAC9E,MAAM,CAAC,GAAG;QACN,OAAO;YACH,iBAAiB,CAAC,QAAQ,EAAE;YAC5B,iBAAiB,CAAC,QAAQ,EAAE;YAC5B,iBAAiB,CAAC,GAAG,EAAE;SAC1B,CAAC;IACN,CAAC;IAED,eAAe,CAAC,KAAkB;QAC9B,OAAO,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACjD,CAAC;IAED;;;;;;;;OAQG;IACH,eAAe,CAAC,QAA4B;QACxC,IAAI,QAAQ,CAAC,IAAI,EAAE,SAAS,KAAK,2BAAe,CAAC,IAAI,EAAE,CAAC;YACpD,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;IAChD,CAAC;IAED,wFAAwF;IACxF,WAAW,CAAC,mBAAuC;QAC/C,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,0BAAkB,CAAC,CAAC;QACnC,CAAC;QACD,IAAI,mBAAmB,KAAK,SAAS,EAAE,CAAC;YACpC,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QACpC,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,2BAAmB,CAAC,CAAC;QAChC,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;CACJ;AAlFD,8CAkFC","sourcesContent":["import { ApiDocModel, DocumentedEndpoint } from '@webpieces/api-doc-model';\nimport {\n    ApiTypeKind,\n    EXTERNAL_CUSTOMER,\n    MCP,\n    SVC_TO_SVC,\n    WpAuthLocalOnly,\n} from '@webpieces/core-util';\n\n/** The one line that says a document is not the customer contract. It appears in exactly one. */\nexport const INTERNAL_ONLY_LINE =\n    'INTERNAL — service-to-service use only. This document lists every endpoint these services serve, including ones no customer is meant to see. It is not the customer contract and must never be handed to one.';\n\n/**\n * The retry contract, published ONCE per document rather than as booleans stamped on every operation.\n *\n * Each operation's own `description` ends with one derived sentence saying whether it is safe to\n * retry; this table says where that sentence comes from. Three vendor-extension booleans per\n * operation would have been invisible to a human — Swagger UI and most themes do not render `x-`\n * extensions, and no standard generator reads `x-webpieces-*` — and would have tripled golden churn\n * the day the mapping changed.\n */\nexport const OPERATION_SEMANTICS = [\n    \"Every operation states whether it is safe to retry, derived from the endpoint's declared\",\n    'side-effect contract:',\n    '',\n    '| declared operation | read-only | destructive | idempotent |',\n    '|---|---|---|---|',\n    '| read | yes | no | yes |',\n    '| write-idempotent | no | yes | yes |',\n    '| write | no | yes | no |',\n].join('\\n');\n\n/**\n * WHICH contracts and operations a document contains, and what prose it stamps. The ONLY thing that\n * differs between the three generated documents.\n *\n * ## Two orthogonal decisions, at two levels\n *\n * - `@ApiType(SVC_TO_SVC, EXTERNAL_CUSTOMER)` on the CONTRACT selects which FILES it feeds. A document\n *   is written at all only when some contract declares its type, so no contract declaring `MCP` means\n *   no `mcp-openapi.json` — there is no second emptiness rule to keep in step with that one.\n * - `{ hidden: true }` on ONE `@Endpoint` subtracts that method from the CUSTOMER document only. It\n *   stays in the private document, and in the MCP document when it is a tool.\n *\n * The per-method case is real and cannot be said at class level: a NEW endpoint on an\n * already-published API, built on main before it is announced. The per-contract case is the one that\n * must not default to permissive, and at class level naming it costs one token per contract.\n *\n * ## Select, then render — never render, then filter\n *\n * One render function takes one of these and is called once per document. It builds\n * `components.schemas` by walking OUTWARD from the operations this selection accepted, so an\n * unselected operation's DTOs are never constructed at all.\n *\n * That asymmetry is about what a BUG does. Build-then-filter puts an unreleased feature's full\n * request and response schemas into the document and then relies on a removal pass to take them out\n * again — so a defect in the visibility logic SHIPS them, named and fully shaped, with only the URL\n * missing, to customers who were told the feature was withheld. Select-then-render cannot do that:\n * no code path can emit a schema that was never built.\n *\n * The usual objection to rendering more than once — that the passes drift in how each renders the\n * same endpoint — applies to separate code paths. This is ONE function, so same code, same input,\n * same output.\n *\n * ## The thing that bites: map ordering\n *\n * Collecting schemas during a walk makes the key order of `components.schemas` depend on which\n * operations were walked, so two documents would list identical schemas in different orders and the\n * goldens would churn on unrelated changes. The renderer SORTS the schema keys before emitting.\n * Orders that carry MEANING are left alone and said so where they are built: `apis[]` order is the\n * published sidebar, and the security-scheme order is the order the credentials are declared in.\n */\nexport class DocumentSelection {\n    private constructor(\n        /** The file name this document is written to, and the name a failure uses for it. */\n        readonly fileName: string,\n        /** The `@ApiType` a contract must declare to appear in this document. */\n        readonly apiType: ApiTypeKind,\n        /** Drop methods marked `{ hidden: true }`. True for the customer document alone. */\n        readonly dropHidden: boolean,\n        /** Stamp `x-mcp-tool` and its siblings. Only the MCP document has a reader for them. */\n        readonly includeMcpExtensions: boolean,\n        /**\n         * Prepend {@link INTERNAL_ONLY_LINE} to `info.description`, and say what TRIGGERS each\n         * operation. Both are internal facts: a customer calls what they are given a url for, and\n         * whether ours fires on a clock or off a queue is our business.\n         */\n        readonly internalNotice: boolean,\n    ) {}\n\n    /** Every contract declaring `SVC_TO_SVC` — which, by the fail-closed default, is every contract. */\n    // webpieces-disable no-function-outside-class -- static factory; the private constructor is what stops a fourth, unnamed selection being invented at a call site\n    static internal(): DocumentSelection {\n        return new DocumentSelection('full-private-openapi', SVC_TO_SVC, false, false, true);\n    }\n\n    /** Every contract declaring `EXTERNAL_CUSTOMER`, minus its hidden methods. */\n    // webpieces-disable no-function-outside-class -- static factory of this class\n    static customer(): DocumentSelection {\n        return new DocumentSelection('public-openapi', EXTERNAL_CUSTOMER, true, false, false);\n    }\n\n    /**\n     * Every contract declaring `MCP`. A HIDDEN method is kept — an internal endpoint that is an agent\n     * tool is still a tool, and requiring it to be published to customers in order to be one would be\n     * exactly the wrong coupling.\n     */\n    // webpieces-disable no-function-outside-class -- static factory of this class\n    static mcp(): DocumentSelection {\n        return new DocumentSelection('mcp-openapi', MCP, false, true, false);\n    }\n\n    /** Every document this generator knows how to write, in the order it writes them. */\n    // webpieces-disable no-function-outside-class -- static factory of this class\n    static all(): readonly DocumentSelection[] {\n        return [\n            DocumentSelection.internal(),\n            DocumentSelection.customer(),\n            DocumentSelection.mcp(),\n        ];\n    }\n\n    acceptsContract(model: ApiDocModel): boolean {\n        return model.apiTypes.includes(this.apiType);\n    }\n\n    /**\n     * `{ hidden: true }` subtracts a method from the CUSTOMER document, and `@WpAuthLocalOnly`\n     * subtracts it from ALL of them.\n     *\n     * A local-only endpoint is not registered as a route at all once the process is deployed, so it\n     * exists nowhere any reader of any of these documents could call it. Publishing it even in the\n     * private one would document a route that does not exist in any deployed environment — worse\n     * than omitting it, because a reader would reasonably try to call it.\n     */\n    acceptsEndpoint(endpoint: DocumentedEndpoint): boolean {\n        if (endpoint.auth?.decorator === WpAuthLocalOnly.name) {\n            return false;\n        }\n        return !this.dropHidden || !endpoint.hidden;\n    }\n\n    /** `info.description`: the manifest's prose, plus whatever this document adds to it. */\n    description(manifestDescription: string | undefined): string | undefined {\n        const parts: string[] = [];\n        if (this.internalNotice) {\n            parts.push(INTERNAL_ONLY_LINE);\n        }\n        if (manifestDescription !== undefined) {\n            parts.push(manifestDescription);\n        }\n        parts.push(OPERATION_SEMANTICS);\n        return parts.join('\\n\\n');\n    }\n}\n"]}

package/src/generate/GenerationInputs.d.ts

@@ -0,0 +1,67 @@
+import { ApiDocModel } from '@webpieces/api-doc-model';
+import { JsonObject } from '../json/JsonObject';
+import { ApiEntry, OpenApiManifest } from '../manifest/OpenApiManifest';
+/** One manifest entry, paired with the model extracted from the file it names. */
+export declare class ContractModel {
+    readonly entry: ApiEntry;
+    readonly model: ApiDocModel;
+    /** Absolute path to the contract, so a refusal can name a file somebody can open. */
+    readonly file: string;
+    constructor(entry: ApiEntry, model: ApiDocModel, 
+    /** Absolute path to the contract, so a refusal can name a file somebody can open. */
+    file: string);
+}
+/**
+ * One response header, with its name already FOLDED out of the constant the manifest named.
+ *
+ * The folding happens before generation, not during it, so the generator is a pure function of
+ * already-established facts: everything that can fail by reading the world has failed by then.
+ */
+export declare class ResolvedResponseHeader {
+    readonly headerName: string;
+    readonly description: string | undefined;
+    constructor(headerName: string, description: string | undefined);
+}
+/**
+ * Everything generation needs, with every file already read and every constant already folded.
+ *
+ * Separating this from {@link OpenApiGenerator} is what makes the generator testable without a
+ * filesystem — and, more usefully, what makes the two documents provably one generation pass: they
+ * are rendered from THIS value, twice, with only the hidden-endpoint filter differing.
+ */
+export declare class GenerationInputs {
+    readonly manifestPath: string;
+    readonly manifest: OpenApiManifest;
+    readonly contracts: readonly ContractModel[];
+    /** The document-wide error body's model, when the manifest declared one. */
+    readonly errorType: ApiDocModel | undefined;
+    readonly responseHeaders: readonly ResolvedResponseHeader[];
+    /** The markdown preamble's TEXT, already read from `descriptionFile`. */
+    readonly description: string | undefined;
+    constructor(manifestPath: string, manifest: OpenApiManifest, contracts: readonly ContractModel[], 
+    /** The document-wide error body's model, when the manifest declared one. */
+    errorType: ApiDocModel | undefined, responseHeaders: readonly ResolvedResponseHeader[], 
+    /** The markdown preamble's TEXT, already read from `descriptionFile`. */
+    description: string | undefined);
+}
+/** ONE rendered document and the name it is written under. */
+export declare class GeneratedDocument {
+    /** Without an extension — `--format` decides whether it is `.json`, `.yaml` or both. */
+    readonly fileName: string;
+    readonly document: JsonObject;
+    constructor(
+    /** Without an extension — `--format` decides whether it is `.json`, `.yaml` or both. */
+    fileName: string, document: JsonObject);
+}
+/**
+ * The documents this generation pass produced — one per `@ApiType` some contract declared, and no
+ * others.
+ *
+ * `diff full-private-openapi.json public-openapi.json` is the complete list of what these contracts
+ * do not show a customer, and both are committed, so hiding a method shows up as a diff in the PR
+ * that hides it. That is the property the pair exists for.
+ */
+export declare class GeneratedDocuments {
+    readonly documents: readonly GeneratedDocument[];
+    constructor(documents: readonly GeneratedDocument[]);
+}

package/src/generate/GenerationInputs.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeneratedDocuments = exports.GeneratedDocument = exports.GenerationInputs = exports.ResolvedResponseHeader = exports.ContractModel = void 0;
+/** One manifest entry, paired with the model extracted from the file it names. */
+class ContractModel {
+    entry;
+    model;
+    file;
+    constructor(entry, model, 
+    /** Absolute path to the contract, so a refusal can name a file somebody can open. */
+    file) {
+        this.entry = entry;
+        this.model = model;
+        this.file = file;
+    }
+}
+exports.ContractModel = ContractModel;
+/**
+ * One response header, with its name already FOLDED out of the constant the manifest named.
+ *
+ * The folding happens before generation, not during it, so the generator is a pure function of
+ * already-established facts: everything that can fail by reading the world has failed by then.
+ */
+class ResolvedResponseHeader {
+    headerName;
+    description;
+    constructor(headerName, description) {
+        this.headerName = headerName;
+        this.description = description;
+    }
+}
+exports.ResolvedResponseHeader = ResolvedResponseHeader;
+/**
+ * Everything generation needs, with every file already read and every constant already folded.
+ *
+ * Separating this from {@link OpenApiGenerator} is what makes the generator testable without a
+ * filesystem — and, more usefully, what makes the two documents provably one generation pass: they
+ * are rendered from THIS value, twice, with only the hidden-endpoint filter differing.
+ */
+class GenerationInputs {
+    manifestPath;
+    manifest;
+    contracts;
+    errorType;
+    responseHeaders;
+    description;
+    constructor(manifestPath, manifest, contracts, 
+    /** The document-wide error body's model, when the manifest declared one. */
+    errorType, responseHeaders, 
+    /** The markdown preamble's TEXT, already read from `descriptionFile`. */
+    description) {
+        this.manifestPath = manifestPath;
+        this.manifest = manifest;
+        this.contracts = contracts;
+        this.errorType = errorType;
+        this.responseHeaders = responseHeaders;
+        this.description = description;
+    }
+}
+exports.GenerationInputs = GenerationInputs;
+/** ONE rendered document and the name it is written under. */
+class GeneratedDocument {
+    fileName;
+    document;
+    constructor(
+    /** Without an extension — `--format` decides whether it is `.json`, `.yaml` or both. */
+    fileName, document) {
+        this.fileName = fileName;
+        this.document = document;
+    }
+}
+exports.GeneratedDocument = GeneratedDocument;
+/**
+ * The documents this generation pass produced — one per `@ApiType` some contract declared, and no
+ * others.
+ *
+ * `diff full-private-openapi.json public-openapi.json` is the complete list of what these contracts
+ * do not show a customer, and both are committed, so hiding a method shows up as a diff in the PR
+ * that hides it. That is the property the pair exists for.
+ */
+class GeneratedDocuments {
+    documents;
+    constructor(documents) {
+        this.documents = documents;
+    }
+}
+exports.GeneratedDocuments = GeneratedDocuments;
+//# sourceMappingURL=GenerationInputs.js.map

package/src/generate/GenerationInputs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GenerationInputs.js","sourceRoot":"","sources":["../../../../../../packages/docs/openapi-generator/src/generate/GenerationInputs.ts"],"names":[],"mappings":";;;AAIA,kFAAkF;AAClF,MAAa,aAAa;IAET;IACA;IAEA;IAJb,YACa,KAAe,EACf,KAAkB;IAC3B,qFAAqF;IAC5E,IAAY;QAHZ,UAAK,GAAL,KAAK,CAAU;QACf,UAAK,GAAL,KAAK,CAAa;QAElB,SAAI,GAAJ,IAAI,CAAQ;IACtB,CAAC;CACP;AAPD,sCAOC;AAED;;;;;GAKG;AACH,MAAa,sBAAsB;IAElB;IACA;IAFb,YACa,UAAkB,EAClB,WAA+B;QAD/B,eAAU,GAAV,UAAU,CAAQ;QAClB,gBAAW,GAAX,WAAW,CAAoB;IACzC,CAAC;CACP;AALD,wDAKC;AAED;;;;;;GAMG;AACH,MAAa,gBAAgB;IAEZ;IACA;IACA;IAEA;IACA;IAEA;IARb,YACa,YAAoB,EACpB,QAAyB,EACzB,SAAmC;IAC5C,4EAA4E;IACnE,SAAkC,EAClC,eAAkD;IAC3D,yEAAyE;IAChE,WAA+B;QAP/B,iBAAY,GAAZ,YAAY,CAAQ;QACpB,aAAQ,GAAR,QAAQ,CAAiB;QACzB,cAAS,GAAT,SAAS,CAA0B;QAEnC,cAAS,GAAT,SAAS,CAAyB;QAClC,oBAAe,GAAf,eAAe,CAAmC;QAElD,gBAAW,GAAX,WAAW,CAAoB;IACzC,CAAC;CACP;AAXD,4CAWC;AAED,8DAA8D;AAC9D,MAAa,iBAAiB;IAGb;IACA;IAHb;IACI,wFAAwF;IAC/E,QAAgB,EAChB,QAAoB;QADpB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,aAAQ,GAAR,QAAQ,CAAY;IAC9B,CAAC;CACP;AAND,8CAMC;AAED;;;;;;;GAOG;AACH,MAAa,kBAAkB;IACN;IAArB,YAAqB,SAAuC;QAAvC,cAAS,GAAT,SAAS,CAA8B;IAAG,CAAC;CACnE;AAFD,gDAEC","sourcesContent":["import { ApiDocModel } from '@webpieces/api-doc-model';\nimport { JsonObject } from '../json/JsonObject';\nimport { ApiEntry, OpenApiManifest } from '../manifest/OpenApiManifest';\n\n/** One manifest entry, paired with the model extracted from the file it names. */\nexport class ContractModel {\n    constructor(\n        readonly entry: ApiEntry,\n        readonly model: ApiDocModel,\n        /** Absolute path to the contract, so a refusal can name a file somebody can open. */\n        readonly file: string,\n    ) {}\n}\n\n/**\n * One response header, with its name already FOLDED out of the constant the manifest named.\n *\n * The folding happens before generation, not during it, so the generator is a pure function of\n * already-established facts: everything that can fail by reading the world has failed by then.\n */\nexport class ResolvedResponseHeader {\n    constructor(\n        readonly headerName: string,\n        readonly description: string | undefined,\n    ) {}\n}\n\n/**\n * Everything generation needs, with every file already read and every constant already folded.\n *\n * Separating this from {@link OpenApiGenerator} is what makes the generator testable without a\n * filesystem — and, more usefully, what makes the two documents provably one generation pass: they\n * are rendered from THIS value, twice, with only the hidden-endpoint filter differing.\n */\nexport class GenerationInputs {\n    constructor(\n        readonly manifestPath: string,\n        readonly manifest: OpenApiManifest,\n        readonly contracts: readonly ContractModel[],\n        /** The document-wide error body's model, when the manifest declared one. */\n        readonly errorType: ApiDocModel | undefined,\n        readonly responseHeaders: readonly ResolvedResponseHeader[],\n        /** The markdown preamble's TEXT, already read from `descriptionFile`. */\n        readonly description: string | undefined,\n    ) {}\n}\n\n/** ONE rendered document and the name it is written under. */\nexport class GeneratedDocument {\n    constructor(\n        /** Without an extension — `--format` decides whether it is `.json`, `.yaml` or both. */\n        readonly fileName: string,\n        readonly document: JsonObject,\n    ) {}\n}\n\n/**\n * The documents this generation pass produced — one per `@ApiType` some contract declared, and no\n * others.\n *\n * `diff full-private-openapi.json public-openapi.json` is the complete list of what these contracts\n * do not show a customer, and both are committed, so hiding a method shows up as a diff in the PR\n * that hides it. That is the property the pair exists for.\n */\nexport class GeneratedDocuments {\n    constructor(readonly documents: readonly GeneratedDocument[]) {}\n}\n"]}

package/src/generate/OpenApiGenerator.d.ts

@@ -0,0 +1,113 @@
+import { GeneratedDocuments, GenerationInputs } from './GenerationInputs';
+/**
+ * {@link GenerationInputs} -> one OpenAPI 3.1.0 document per `@ApiType` some contract declares.
+ *
+ * ## 3.1, because it is what the model can state HONESTLY
+ *
+ * `type: [T, "null"]` instead of a `nullable` keyword; a `description` legal beside a `$ref`; a
+ * top-level `webhooks:` block. Each of those is a fact the model holds that 3.0 would have forced
+ * this renderer to drop or to lie about. 3.1's schema dialect is also JSON Schema 2020-12, which is
+ * what MCP `tools/list` speaks.
+ *
+ * ## ONE render function, called once per document
+ *
+ * ```
+ * ApiDocModel --> render(selection) --+--> full-private-openapi.json  SVC_TO_SVC contracts
+ *                                     +--> public-openapi.json        EXTERNAL_CUSTOMER contracts, minus hidden methods
+ *                                     +--> mcp-openapi.json           MCP contracts
+ * ```
+ *
+ * `components.schemas` is built by walking OUTWARD from the operations the selection accepted, so an
+ * unselected operation's DTOs are never constructed. See {@link DocumentSelection} for why that
+ * asymmetry — a bug emits nothing, rather than shipping an unreleased feature's schemas with only
+ * its URL removed — decides the whole design.
+ *
+ * ## It REFUSES to write an unmapped field
+ *
+ * An unmapped type renders as an empty schema, which in JSON Schema means "anything". Publishing one
+ * is a green build handing a partner a field with no shape, so the guard names the JSON pointer of
+ * every one and exits non-zero. There is deliberately NO flag to switch it off: the cure is at the
+ * contract, by naming the type.
+ */
+export declare class OpenApiGenerator {
+    private readonly security;
+    /**
+     * ONE document per `@ApiType` some contract declares, and no others.
+     *
+     * A document nobody asked for is not written empty — it is not written. That is the ONE
+     * conditional in the whole pipeline, and it lives here rather than in three places: no contract
+     * declaring `MCP` means no `mcp-openapi.json`, with no second "is it empty?" rule to keep in step
+     * with the first.
+     */
+    generate(inputs: GenerationInputs): GeneratedDocuments;
+    /** ONE document, from the operations this selection accepts and nothing else. */
+    private render;
+    /**
+     * A webhook is served by the PARTNER, so neither our failure envelope nor the header we stamp on
+     * our own responses is true of it. Publishing either would document their server, not ours.
+     */
+    private webhookContract;
+    /** One contract's ACCEPTED endpoints, into `paths` or into `webhooks`. */
+    private renderContract;
+    /**
+     * A webhook is keyed by the EVENT NAME, with the `@ApiPath` base deliberately NOT prepended.
+     *
+     * There is no url of ours here — the partner hosts the endpoint, at whatever path they choose —
+     * so publishing `/our-base/delivered` would document a route that exists nowhere. What we are
+     * naming is the event we will send.
+     */
+    private eventName;
+    /**
+     * Every named type from every contract, merged.
+     *
+     * Two contracts declaring DIFFERENT types under one name is a hard failure, not a first-wins
+     * merge: `components.schemas` is keyed by name, so one of the two would be published as the
+     * other's shape, and the operation referring to it would be quietly wrong.
+     */
+    private mergedTypes;
+    /** Enough of a type's shape to tell two same-named types apart without comparing prose. */
+    private signature;
+    /**
+     * The ONE api-key regime this document publishes.
+     *
+     * Two regimes in one document is a hard failure: `securitySchemeNames` is a single ordered list,
+     * so there is no honest way to say which regime a given name belongs to, and a document that
+     * guessed would publish one regime's header names under the other's scheme keys.
+     */
+    private singleApiKey;
+    /**
+     * True when EVERY selected operation demands the credential, which is what licenses hoisting the
+     * requirement to the document. A document that mixes credentialled and uncredentialled routes
+     * stamps it per-operation instead — hoisting there would tell a partner that a public endpoint
+     * needs a key.
+     *
+     * Judged per DOCUMENT, over the operations that document actually contains, because that is the
+     * only question the document's own `security` block answers.
+     */
+    private everyOperationIsCovered;
+    /**
+     * The endpoints this selection accepts that are routes on OUR server. A webhook is somebody
+     * else's route, so it never counts toward our security requirement or our regime.
+     */
+    private selectedEndpoints;
+    /** `info`, whose `description` is the ONE piece of prose that differs between the documents. */
+    private info;
+    private servers;
+    /**
+     * `tags[]` in MANIFEST ORDER, because that order IS the published sidebar — one of the two
+     * orders in this document that carries meaning and is therefore NOT sorted.
+     */
+    private tagList;
+    private tagProse;
+    private errorResponses;
+    private errorSchemaRef;
+    /** `components.headers`, one entry per declared response header. */
+    private headers;
+    /** The `$ref`s every SUCCESS response carries at those headers. */
+    private headerRefs;
+    /**
+     * The guard. An unmapped field is a published partner-facing field with no shape, and there is
+     * deliberately no flag to switch this off — the cure is at the contract, by naming the type.
+     */
+    private refuseUnmappedFields;
+}