@webpieces/openapi-generator 0.0.1

package/src/generate/OperationRenderer.js

@@ -0,0 +1,256 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OperationRenderer = exports.ResponseContract = void 0;
+const core_util_1 = require("@webpieces/core-util");
+const JsonObject_1 = require("../json/JsonObject");
+/** What a webhook's `void` return means on the wire, said once. */
+const ACKNOWLEDGE = 'Return any 2xx to acknowledge delivery. The body is ignored.';
+/** `Promise<void>` on the wire, said once. */
+/** The response document, and the responses a document-wide failure contract adds to it. */
+class ResponseContract {
+    errors;
+    errorSchemaRef;
+    headers;
+    constructor(
+    /** Status -> description, from the manifest's `errors.responses`, in declared order. */
+    errors, 
+    /** `$ref` at the error body schema, when the manifest declared one. */
+    errorSchemaRef, 
+    /** Header name -> its `components.headers` `$ref`, on every success response. */
+    headers) {
+        this.errors = errors;
+        this.errorSchemaRef = errorSchemaRef;
+        this.headers = headers;
+    }
+}
+exports.ResponseContract = ResponseContract;
+/**
+ * ONE {@link DocumentedEndpoint} -> one OpenAPI Operation Object.
+ *
+ * ## `summary` is the operation NAME, never a sentence
+ *
+ * A docs theme titles the endpoint's page from `summary` and puts `description` in the body. Writing
+ * the first sentence of the prose into `summary` therefore produces a sidebar of sentences and a page
+ * whose heading repeats its own first line. The method name is what a reader is looking for, and it
+ * is also what the generated client calls the method, so the two agree by construction.
+ *
+ * ## The MCP extensions ride HERE, on the operation
+ *
+ * `x-mcp-tool`, `x-mcp-hints`, `x-mcp-description` and `x-mcp-auth` are stamped on every operation
+ * carrying the tool decorator, hidden or not: an internal endpoint that is an agent tool is a
+ * legitimate agent tool, and requiring it to be published to partners in order to be one would be
+ * exactly the wrong coupling.
+ *
+ * They are stamped on the BASE, which every published document is derived from, and
+ * {@link DocumentDeriver} STRIPS them from the customer document. Stamping-then-stripping rather than
+ * rendering the customer document without them is the same choice the whole deriver rests on: one
+ * render of one operation, so two documents holding it cannot disagree about anything else in it.
+ */
+class OperationRenderer {
+    schemas;
+    includeMcp;
+    includeTrigger;
+    constructor(schemas, 
+    /** True only for the MCP document — see {@link withMcp}. */
+    includeMcp, 
+    /** True only for the private document — see {@link triggerSentence}. */
+    includeTrigger) {
+        this.schemas = schemas;
+        this.includeMcp = includeMcp;
+        this.includeTrigger = includeTrigger;
+    }
+    /** An ordinary served route. */
+    operation(endpoint, contractName, tag, contract, security) {
+        const operation = this.common(endpoint, contractName, tag, contract);
+        // An endpoint that authenticates NOBODY says so explicitly: `security: []` is OpenAPI's
+        // spelling of "no credential required", and leaving the key off instead means "inherit the
+        // document's", which is a different statement that happens to coincide today.
+        const explicit = this.isPublic(endpoint) ? [] : security;
+        operation.set('security', explicit === undefined ? undefined : explicit.slice());
+        return this.withMcp(operation, endpoint);
+    }
+    /**
+     * A call WE make to a PARTNER's server.
+     *
+     * It carries `x-webpieces-webhook: true`, which is the one fact about it a document cannot state
+     * any other way. It gets no trigger sentence and no security at all, because neither is true of
+     * it: nothing of ours triggers it and nothing of ours authenticates it — our api key must never
+     * be published as a guard on somebody else's endpoint.
+     */
+    webhook(endpoint, contractName, tag, contract) {
+        const operation = this.common(endpoint, contractName, tag, contract);
+        return this.withMcp(operation.set('x-webpieces-webhook', true), endpoint);
+    }
+    common(endpoint, contractName, tag, contract) {
+        return new JsonObject_1.JsonObject()
+            .set('operationId', `${contractName}_${endpoint.methodName}`)
+            .set('summary', endpoint.methodName)
+            .set('description', this.describe(endpoint))
+            .set('tags', [tag])
+            .set('requestBody', this.requestBody(endpoint, contractName))
+            .set('responses', this.responses(endpoint, contractName, contract));
+    }
+    /**
+     * The JSDoc body, plus the sentences that are DERIVED rather than written.
+     *
+     * The retry sentence comes from the endpoint's declared `operation`, which every integration
+     * wants to know and most APIs state nowhere. It is a SENTENCE and not a vendor extension because
+     * Swagger UI and most themes do not render `x-` extensions and no standard generator reads
+     * `x-webpieces-*`: an extension would be invisible to the human and unread by the machine. The
+     * mapping it is derived from is published once, in `info.description`, so the rule is stated and
+     * not only its consequences.
+     */
+    describe(endpoint) {
+        const parts = [];
+        const body = this.prose(endpoint.description);
+        if (body !== undefined) {
+            parts.push(body);
+        }
+        parts.push(this.retrySentence(endpoint));
+        if (this.includeTrigger) {
+            parts.push(this.triggerSentence(endpoint));
+        }
+        if (endpoint.openWorld) {
+            parts.push('Reaches beyond this service: it may act on an external system, so its effects ' +
+                'are not all visible here.');
+        }
+        return parts.join('\n\n');
+    }
+    /**
+     * WHAT FIRES this endpoint, in the private document only.
+     *
+     * A customer calls what they are given a url for; whether ours runs off a queue or a clock is our
+     * business and would only invite a question they cannot act on. It is a SENTENCE and not
+     * `x-webpieces-trigger` for the same reason the retry sentence is: Swagger UI and most themes do
+     * not render `x-` extensions, and no standard generator reads `x-webpieces-*`, so an extension is
+     * invisible to the human and unread by the machine.
+     */
+    triggerSentence(endpoint) {
+        if (endpoint.kind === core_util_1.CLOUDTASKS) {
+            return 'Triggered by a queued task, delivered asynchronously.';
+        }
+        if (endpoint.kind === core_util_1.CRON) {
+            return 'Triggered on a schedule, not by a caller.';
+        }
+        if (endpoint.kind === core_util_1.EXTERNAL) {
+            const caller = endpoint.options.calledBy;
+            return caller === undefined
+                ? 'Triggered by an outside system.'
+                : `Triggered by an outside system: ${caller}.`;
+        }
+        return endpoint.kind === core_util_1.RPC
+            ? 'Triggered by a direct call.'
+            : `Triggered by: ${endpoint.kind}.`;
+    }
+    /** An endpoint whose declared credential is "none", said out loud rather than left absent. */
+    isPublic(endpoint) {
+        return endpoint.auth?.decorator === core_util_1.WpAuthPublic.name;
+    }
+    retrySentence(endpoint) {
+        if (endpoint.operation === core_util_1.READ) {
+            return 'Safe to retry: this operation is read-only and idempotent.';
+        }
+        if (endpoint.operation === core_util_1.WRITE_IDEMPOTENT) {
+            return 'Safe to retry: this operation changes state but is idempotent.';
+        }
+        return 'NOT safe to retry: this operation changes state and is not idempotent.';
+    }
+    /**
+     * The MCP extensions, stamped only on the document that has an agent for a reader.
+     *
+     * ## The three side-effect hints are COMPUTED, never declared
+     *
+     * `mcpHintsForOperation` in `@webpieces/core-util` is the one place the mapping from
+     * `READ | WRITE_IDEMPOTENT | WRITE` to `readOnlyHint` / `destructiveHint` / `idempotentHint`
+     * lives, and this calls it rather than reimplementing it. The endpoint's `operation` already
+     * states whether repeating the call is safe; a hand-declared hint would be a second answer to a
+     * question the contract has answered, and the two could disagree. `openWorldHint` is the only one
+     * a human declares, because it is a judgement about the world rather than a consequence of the
+     * operation.
+     *
+     * ## There is no separate MCP description
+     *
+     * The agent reads the operation's `description` — the method's JSDoc — byte-identical to what the
+     * partner reads. `x-mcp-description` appears ONLY when the author wrote an explicit `@mcp` JSDoc
+     * tag, which is a deliberate act rather than a second copy of the same paragraph.
+     */
+    withMcp(operation, endpoint) {
+        if (!this.includeMcp || endpoint.mcpTool === undefined) {
+            return operation;
+        }
+        const hints = (0, core_util_1.mcpHintsForOperation)(this.operationOf(endpoint), endpoint.openWorld);
+        return operation
+            .set('x-mcp-tool', endpoint.mcpTool.name)
+            .set('x-mcp-hints', new JsonObject_1.JsonObject()
+            .set('readOnlyHint', hints.readOnlyHint)
+            .set('destructiveHint', hints.destructiveHint)
+            .set('idempotentHint', hints.idempotentHint)
+            .set('openWorldHint', hints.openWorldHint))
+            .set('x-mcp-description', this.prose(endpoint.mcpDescription))
+            .set('x-mcp-auth', endpoint.mcpAuthText);
+    }
+    /**
+     * The endpoint's operation as the REAL exported constant.
+     *
+     * The model carries it as a string, verbatim from the source, because the model invents no
+     * taxonomy. Matching it back to the constant here — rather than casting — is what makes a rename
+     * of `WRITE_IDEMPOTENT` in `core-util` a compile error in this file.
+     */
+    operationOf(endpoint) {
+        if (endpoint.operation === core_util_1.READ) {
+            return core_util_1.READ;
+        }
+        return endpoint.operation === core_util_1.WRITE_IDEMPOTENT ? core_util_1.WRITE_IDEMPOTENT : core_util_1.WRITE;
+    }
+    /**
+     * The request DTO as a body. Only for `POST`: OpenAPI gives a `GET` body no defined semantics and
+     * most tooling drops it, so publishing one would document a request no generated client sends.
+     */
+    requestBody(endpoint, contractName) {
+        if (endpoint.httpMethod !== 'POST' || endpoint.request === undefined) {
+            return undefined;
+        }
+        const pointer = `#/paths/${contractName}_${endpoint.methodName}/requestBody`;
+        const media = endpoint.options.formPost
+            ? 'application/x-www-form-urlencoded'
+            : 'application/json';
+        return new JsonObject_1.JsonObject()
+            .set('required', true)
+            .set('content', new JsonObject_1.JsonObject().set(media, new JsonObject_1.JsonObject().set('schema', this.schemas.type(endpoint.request, pointer))));
+    }
+    responses(endpoint, contractName, contract) {
+        const responses = new JsonObject_1.JsonObject();
+        responses.set('200', this.success(endpoint, contractName, contract));
+        for (const status of Array.from(contract.errors.keys())) {
+            responses.set(status, this.failure(contract.errors.get(status), contract));
+        }
+        return responses;
+    }
+    success(endpoint, contractName, contract) {
+        const response = new JsonObject_1.JsonObject()
+            .set('description', this.isVoid(endpoint.response) ? ACKNOWLEDGE : 'Success.')
+            .set('headers', contract.headers);
+        if (this.isVoid(endpoint.response)) {
+            return response;
+        }
+        const pointer = `#/paths/${contractName}_${endpoint.methodName}/responses/200`;
+        return response.set('content', new JsonObject_1.JsonObject().set('application/json', new JsonObject_1.JsonObject().set('schema', this.schemas.type(endpoint.response, pointer))));
+    }
+    failure(description, contract) {
+        const response = new JsonObject_1.JsonObject().set('description', description);
+        if (contract.errorSchemaRef === undefined) {
+            return response;
+        }
+        return response.set('content', new JsonObject_1.JsonObject().set('application/json', new JsonObject_1.JsonObject().set('schema', contract.errorSchemaRef)));
+    }
+    /** `Promise<void>` reaches the model as the `unknown` primitive — there is no body to document. */
+    isVoid(response) {
+        return (response === undefined ||
+            (response.kind === 'primitive' && response.primitive === 'unknown'));
+    }
+    prose(text) {
+        return text === undefined || text.trim() === '' ? undefined : text;
+    }
+}
+exports.OperationRenderer = OperationRenderer;
+//# sourceMappingURL=OperationRenderer.js.map

package/src/generate/OperationRenderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OperationRenderer.js","sourceRoot":"","sources":["../../../../../../packages/docs/openapi-generator/src/generate/OperationRenderer.ts"],"names":[],"mappings":"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","sourcesContent":["import { DocumentedEndpoint, TypeRef } from '@webpieces/api-doc-model';\nimport {\n    CLOUDTASKS,\n    CRON,\n    EXTERNAL,\n    mcpHintsForOperation,\n    POST,\n    READ,\n    RPC,\n    WpAuthPublic,\n    WRITE,\n    WRITE_IDEMPOTENT,\n} from '@webpieces/core-util';\nimport { JsonObject, JsonValue } from '../json/JsonObject';\nimport { SchemaRenderer } from './SchemaRenderer';\n\n/** What a webhook's `void` return means on the wire, said once. */\nconst ACKNOWLEDGE = 'Return any 2xx to acknowledge delivery. The body is ignored.';\n\n/** `Promise<void>` on the wire, said once. */\n\n/** The response document, and the responses a document-wide failure contract adds to it. */\nexport class ResponseContract {\n    constructor(\n        /** Status -> description, from the manifest's `errors.responses`, in declared order. */\n        readonly errors: ReadonlyMap<string, string>,\n        /** `$ref` at the error body schema, when the manifest declared one. */\n        readonly errorSchemaRef: JsonObject | undefined,\n        /** Header name -> its `components.headers` `$ref`, on every success response. */\n        readonly headers: JsonObject | undefined,\n    ) {}\n}\n\n/**\n * ONE {@link DocumentedEndpoint} -> one OpenAPI Operation Object.\n *\n * ## `summary` is the operation NAME, never a sentence\n *\n * A docs theme titles the endpoint's page from `summary` and puts `description` in the body. Writing\n * the first sentence of the prose into `summary` therefore produces a sidebar of sentences and a page\n * whose heading repeats its own first line. The method name is what a reader is looking for, and it\n * is also what the generated client calls the method, so the two agree by construction.\n *\n * ## The MCP extensions ride HERE, on the operation\n *\n * `x-mcp-tool`, `x-mcp-hints`, `x-mcp-description` and `x-mcp-auth` are stamped on every operation\n * carrying the tool decorator, hidden or not: an internal endpoint that is an agent tool is a\n * legitimate agent tool, and requiring it to be published to partners in order to be one would be\n * exactly the wrong coupling.\n *\n * They are stamped on the BASE, which every published document is derived from, and\n * {@link DocumentDeriver} STRIPS them from the customer document. Stamping-then-stripping rather than\n * rendering the customer document without them is the same choice the whole deriver rests on: one\n * render of one operation, so two documents holding it cannot disagree about anything else in it.\n */\nexport class OperationRenderer {\n    constructor(\n        private readonly schemas: SchemaRenderer,\n        /** True only for the MCP document — see {@link withMcp}. */\n        private readonly includeMcp: boolean,\n        /** True only for the private document — see {@link triggerSentence}. */\n        private readonly includeTrigger: boolean,\n    ) {}\n\n    /** An ordinary served route. */\n    operation(\n        endpoint: DocumentedEndpoint,\n        contractName: string,\n        tag: string,\n        contract: ResponseContract,\n        security: readonly JsonValue[] | undefined,\n    ): JsonObject {\n        const operation = this.common(endpoint, contractName, tag, contract);\n        // An endpoint that authenticates NOBODY says so explicitly: `security: []` is OpenAPI's\n        // spelling of \"no credential required\", and leaving the key off instead means \"inherit the\n        // document's\", which is a different statement that happens to coincide today.\n        const explicit = this.isPublic(endpoint) ? [] : security;\n        operation.set('security', explicit === undefined ? undefined : explicit.slice());\n        return this.withMcp(operation, endpoint);\n    }\n\n    /**\n     * A call WE make to a PARTNER's server.\n     *\n     * It carries `x-webpieces-webhook: true`, which is the one fact about it a document cannot state\n     * any other way. It gets no trigger sentence and no security at all, because neither is true of\n     * it: nothing of ours triggers it and nothing of ours authenticates it — our api key must never\n     * be published as a guard on somebody else's endpoint.\n     */\n    webhook(\n        endpoint: DocumentedEndpoint,\n        contractName: string,\n        tag: string,\n        contract: ResponseContract,\n    ): JsonObject {\n        const operation = this.common(endpoint, contractName, tag, contract);\n        return this.withMcp(operation.set('x-webpieces-webhook', true), endpoint);\n    }\n\n    private common(\n        endpoint: DocumentedEndpoint,\n        contractName: string,\n        tag: string,\n        contract: ResponseContract,\n    ): JsonObject {\n        return new JsonObject()\n            .set('operationId', `${contractName}_${endpoint.methodName}`)\n            .set('summary', endpoint.methodName)\n            .set('description', this.describe(endpoint))\n            .set('tags', [tag])\n            .set('requestBody', this.requestBody(endpoint, contractName))\n            .set('responses', this.responses(endpoint, contractName, contract));\n    }\n\n    /**\n     * The JSDoc body, plus the sentences that are DERIVED rather than written.\n     *\n     * The retry sentence comes from the endpoint's declared `operation`, which every integration\n     * wants to know and most APIs state nowhere. It is a SENTENCE and not a vendor extension because\n     * Swagger UI and most themes do not render `x-` extensions and no standard generator reads\n     * `x-webpieces-*`: an extension would be invisible to the human and unread by the machine. The\n     * mapping it is derived from is published once, in `info.description`, so the rule is stated and\n     * not only its consequences.\n     */\n    private describe(endpoint: DocumentedEndpoint): string | undefined {\n        const parts: string[] = [];\n        const body = this.prose(endpoint.description);\n        if (body !== undefined) {\n            parts.push(body);\n        }\n        parts.push(this.retrySentence(endpoint));\n        if (this.includeTrigger) {\n            parts.push(this.triggerSentence(endpoint));\n        }\n        if (endpoint.openWorld) {\n            parts.push(\n                'Reaches beyond this service: it may act on an external system, so its effects ' +\n                    'are not all visible here.',\n            );\n        }\n        return parts.join('\\n\\n');\n    }\n\n    /**\n     * WHAT FIRES this endpoint, in the private document only.\n     *\n     * A customer calls what they are given a url for; whether ours runs off a queue or a clock is our\n     * business and would only invite a question they cannot act on. It is a SENTENCE and not\n     * `x-webpieces-trigger` for the same reason the retry sentence is: Swagger UI and most themes do\n     * not render `x-` extensions, and no standard generator reads `x-webpieces-*`, so an extension is\n     * invisible to the human and unread by the machine.\n     */\n    private triggerSentence(endpoint: DocumentedEndpoint): string {\n        if (endpoint.kind === CLOUDTASKS) {\n            return 'Triggered by a queued task, delivered asynchronously.';\n        }\n        if (endpoint.kind === CRON) {\n            return 'Triggered on a schedule, not by a caller.';\n        }\n        if (endpoint.kind === EXTERNAL) {\n            const caller = endpoint.options.calledBy;\n            return caller === undefined\n                ? 'Triggered by an outside system.'\n                : `Triggered by an outside system: ${caller}.`;\n        }\n        return endpoint.kind === RPC\n            ? 'Triggered by a direct call.'\n            : `Triggered by: ${endpoint.kind}.`;\n    }\n\n    /** An endpoint whose declared credential is \"none\", said out loud rather than left absent. */\n    private isPublic(endpoint: DocumentedEndpoint): boolean {\n        return endpoint.auth?.decorator === WpAuthPublic.name;\n    }\n\n    private retrySentence(endpoint: DocumentedEndpoint): string {\n        if (endpoint.operation === READ) {\n            return 'Safe to retry: this operation is read-only and idempotent.';\n        }\n        if (endpoint.operation === WRITE_IDEMPOTENT) {\n            return 'Safe to retry: this operation changes state but is idempotent.';\n        }\n        return 'NOT safe to retry: this operation changes state and is not idempotent.';\n    }\n\n    /**\n     * The MCP extensions, stamped only on the document that has an agent for a reader.\n     *\n     * ## The three side-effect hints are COMPUTED, never declared\n     *\n     * `mcpHintsForOperation` in `@webpieces/core-util` is the one place the mapping from\n     * `READ | WRITE_IDEMPOTENT | WRITE` to `readOnlyHint` / `destructiveHint` / `idempotentHint`\n     * lives, and this calls it rather than reimplementing it. The endpoint's `operation` already\n     * states whether repeating the call is safe; a hand-declared hint would be a second answer to a\n     * question the contract has answered, and the two could disagree. `openWorldHint` is the only one\n     * a human declares, because it is a judgement about the world rather than a consequence of the\n     * operation.\n     *\n     * ## There is no separate MCP description\n     *\n     * The agent reads the operation's `description` — the method's JSDoc — byte-identical to what the\n     * partner reads. `x-mcp-description` appears ONLY when the author wrote an explicit `@mcp` JSDoc\n     * tag, which is a deliberate act rather than a second copy of the same paragraph.\n     */\n    private withMcp(operation: JsonObject, endpoint: DocumentedEndpoint): JsonObject {\n        if (!this.includeMcp || endpoint.mcpTool === undefined) {\n            return operation;\n        }\n        const hints = mcpHintsForOperation(this.operationOf(endpoint), endpoint.openWorld);\n        return operation\n            .set('x-mcp-tool', endpoint.mcpTool.name)\n            .set(\n                'x-mcp-hints',\n                new JsonObject()\n                    .set('readOnlyHint', hints.readOnlyHint)\n                    .set('destructiveHint', hints.destructiveHint)\n                    .set('idempotentHint', hints.idempotentHint)\n                    .set('openWorldHint', hints.openWorldHint),\n            )\n            .set('x-mcp-description', this.prose(endpoint.mcpDescription))\n            .set('x-mcp-auth', endpoint.mcpAuthText);\n    }\n\n    /**\n     * The endpoint's operation as the REAL exported constant.\n     *\n     * The model carries it as a string, verbatim from the source, because the model invents no\n     * taxonomy. Matching it back to the constant here — rather than casting — is what makes a rename\n     * of `WRITE_IDEMPOTENT` in `core-util` a compile error in this file.\n     */\n    private operationOf(\n        endpoint: DocumentedEndpoint,\n    ): typeof READ | typeof WRITE_IDEMPOTENT | typeof WRITE {\n        if (endpoint.operation === READ) {\n            return READ;\n        }\n        return endpoint.operation === WRITE_IDEMPOTENT ? WRITE_IDEMPOTENT : WRITE;\n    }\n\n    /**\n     * The request DTO as a body. Only for `POST`: OpenAPI gives a `GET` body no defined semantics and\n     * most tooling drops it, so publishing one would document a request no generated client sends.\n     */\n    private requestBody(\n        endpoint: DocumentedEndpoint,\n        contractName: string,\n    ): JsonObject | undefined {\n        if (endpoint.httpMethod !== 'POST' || endpoint.request === undefined) {\n            return undefined;\n        }\n        const pointer = `#/paths/${contractName}_${endpoint.methodName}/requestBody`;\n        const media = endpoint.options.formPost\n            ? 'application/x-www-form-urlencoded'\n            : 'application/json';\n        return new JsonObject()\n            .set('required', true)\n            .set(\n                'content',\n                new JsonObject().set(\n                    media,\n                    new JsonObject().set('schema', this.schemas.type(endpoint.request, pointer)),\n                ),\n            );\n    }\n\n    private responses(\n        endpoint: DocumentedEndpoint,\n        contractName: string,\n        contract: ResponseContract,\n    ): JsonObject {\n        const responses = new JsonObject();\n        responses.set('200', this.success(endpoint, contractName, contract));\n        for (const status of Array.from(contract.errors.keys())) {\n            responses.set(status, this.failure(contract.errors.get(status)!, contract));\n        }\n        return responses;\n    }\n\n    private success(\n        endpoint: DocumentedEndpoint,\n        contractName: string,\n        contract: ResponseContract,\n    ): JsonObject {\n        const response = new JsonObject()\n            .set('description', this.isVoid(endpoint.response) ? ACKNOWLEDGE : 'Success.')\n            .set('headers', contract.headers);\n        if (this.isVoid(endpoint.response)) {\n            return response;\n        }\n        const pointer = `#/paths/${contractName}_${endpoint.methodName}/responses/200`;\n        return response.set(\n            'content',\n            new JsonObject().set(\n                'application/json',\n                new JsonObject().set('schema', this.schemas.type(endpoint.response!, pointer)),\n            ),\n        );\n    }\n\n    private failure(description: string, contract: ResponseContract): JsonObject {\n        const response = new JsonObject().set('description', description);\n        if (contract.errorSchemaRef === undefined) {\n            return response;\n        }\n        return response.set(\n            'content',\n            new JsonObject().set(\n                'application/json',\n                new JsonObject().set('schema', contract.errorSchemaRef),\n            ),\n        );\n    }\n\n    /** `Promise<void>` reaches the model as the `unknown` primitive — there is no body to document. */\n    private isVoid(response: TypeRef | undefined): boolean {\n        return (\n            response === undefined ||\n            (response.kind === 'primitive' && response.primitive === 'unknown')\n        );\n    }\n\n    private prose(text: string | undefined): string | undefined {\n        return text === undefined || text.trim() === '' ? undefined : text;\n    }\n}\n"]}

package/src/generate/SchemaRenderer.d.ts

@@ -0,0 +1,89 @@
+import { DocumentedField, DocumentedType, TypeRef } from '@webpieces/api-doc-model';
+import { JsonObject } from '../json/JsonObject';
+/** ONE field the renderer could not give a shape to, and WHERE in the document it would have sat. */
+export declare class UnmappedField {
+    /** A JSON pointer into the document that would have been written. */
+    readonly pointer: string;
+    /** The verbatim TypeScript type text, so the cure names the thing to go and type. */
+    readonly typeText: string;
+    constructor(
+    /** A JSON pointer into the document that would have been written. */
+    pointer: string, 
+    /** The verbatim TypeScript type text, so the cure names the thing to go and type. */
+    typeText: string);
+}
+/**
+ * {@link TypeRef} / {@link DocumentedType} -> JSON Schema 2020-12, which IS OpenAPI 3.1's schema
+ * dialect and IS what MCP `tools/list` speaks. That identity is the reason #982 specifies 3.1 rather
+ * than 3.0: the two are not "similar dialects", they are the same schemas, so the MCP projection
+ * (#984) is a selection and an inline pass, not a translation.
+ *
+ * ## Three things 3.1 lets this renderer state HONESTLY that 3.0 could not
+ *
+ * - `type: [T, "null"]` for a nullable field, instead of 3.0's `nullable: true` keyword, which is not
+ *   JSON Schema at all.
+ * - `description` BESIDE a `$ref`. In 3.0 a sibling of `$ref` is ignored, so a documented field whose
+ *   type is a named DTO simply lost its prose.
+ * - OPTIONAL and NULLABLE as separate facts — absent from `required` versus `"null"` in `type`. `{}`
+ *   and `{x: null}` are different wire documents and a schema that conflates them rejects one.
+ *
+ * ## It records what it cannot map rather than emitting an untyped field
+ *
+ * An unmapped type yields an EMPTY schema, which in JSON Schema means "anything". That is precisely
+ * the green-build-publishes-a-shapeless-field defect the guard exists to stop, so every one is
+ * recorded with the pointer it would have occupied and {@link OpenApiGenerator} refuses on the set.
+ */
+export declare class SchemaRenderer {
+    private readonly types;
+    private readonly reached;
+    private readonly unmappedFields;
+    constructor(types: ReadonlyMap<string, DocumentedType>);
+    /** Named types this renderer has been asked for, directly or through another schema. */
+    reachedTypes(): ReadonlySet<string>;
+    /** Every field with no shape, with its pointer. Empty means the document is fully typed. */
+    unmapped(): readonly UnmappedField[];
+    /**
+     * `components.schemas` for everything reachable from whatever has been rendered so far, expanded
+     * to a FIXPOINT.
+     *
+     * A worklist and not recursion-with-a-guard because rendering a type reaches more types, and the
+     * set has to close over that. It terminates for the same reason the extractor's walk does: a
+     * named type is registered once, so the worklist strictly shrinks.
+     */
+    components(): JsonObject;
+    /** One named type: an object DTO, a string enum, or a union with its DERIVED discriminator. */
+    private namedType;
+    /**
+     * A union, with a `discriminator` ONLY when the model derived one — which it does only when every
+     * branch carries the same property typed as a single string literal. An invented discriminator
+     * would claim a narrowing TypeScript itself cannot do.
+     */
+    private union;
+    /**
+     * One FIELD: its type, plus the prose and the constraints that hang off the field rather than the
+     * type. `@format`, `@WpMin` and `@WpMax` land on the SCALAR — on an array, on the ITEM — because
+     * `minimum` on an array means nothing and a reader would have to guess which half was meant.
+     */
+    field(field: DocumentedField, pointer: string): JsonObject;
+    /** `description`, and the `@mcp` override as `x-mcp-description` when the author wrote one. */
+    private described;
+    private constrain;
+    /** `type: [T, "null"]` where there is a type to widen; `anyOf` where the shape is a `$ref`. */
+    private nullable;
+    /** One resolved type, with no field-level prose or constraints on it. */
+    type(ref: TypeRef, pointer: string): JsonObject;
+    /**
+     * A union, as a `$ref` at the NAMED alias when the model registered one.
+     *
+     * The model records a `type X = A | B` alias as its own entry — carrying the DERIVED
+     * discriminator — while the FIELD that used it holds a bare union of branch names. Rendering the
+     * field's union inline would therefore publish the `oneOf` and silently drop the discriminator,
+     * which is the one part of a union a client actually needs to narrow on. So the alias is looked
+     * up by its branch list and referenced.
+     */
+    private namedUnion;
+    private primitive;
+    private reference;
+    /** Empty prose is ABSENT prose. An empty `description` key is noise in every rendered page. */
+    private prose;
+}

package/src/generate/SchemaRenderer.js

@@ -0,0 +1,236 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaRenderer = exports.UnmappedField = void 0;
+const JsonObject_1 = require("../json/JsonObject");
+/** ONE field the renderer could not give a shape to, and WHERE in the document it would have sat. */
+class UnmappedField {
+    pointer;
+    typeText;
+    constructor(
+    /** A JSON pointer into the document that would have been written. */
+    pointer, 
+    /** The verbatim TypeScript type text, so the cure names the thing to go and type. */
+    typeText) {
+        this.pointer = pointer;
+        this.typeText = typeText;
+    }
+}
+exports.UnmappedField = UnmappedField;
+/**
+ * {@link TypeRef} / {@link DocumentedType} -> JSON Schema 2020-12, which IS OpenAPI 3.1's schema
+ * dialect and IS what MCP `tools/list` speaks. That identity is the reason #982 specifies 3.1 rather
+ * than 3.0: the two are not "similar dialects", they are the same schemas, so the MCP projection
+ * (#984) is a selection and an inline pass, not a translation.
+ *
+ * ## Three things 3.1 lets this renderer state HONESTLY that 3.0 could not
+ *
+ * - `type: [T, "null"]` for a nullable field, instead of 3.0's `nullable: true` keyword, which is not
+ *   JSON Schema at all.
+ * - `description` BESIDE a `$ref`. In 3.0 a sibling of `$ref` is ignored, so a documented field whose
+ *   type is a named DTO simply lost its prose.
+ * - OPTIONAL and NULLABLE as separate facts — absent from `required` versus `"null"` in `type`. `{}`
+ *   and `{x: null}` are different wire documents and a schema that conflates them rejects one.
+ *
+ * ## It records what it cannot map rather than emitting an untyped field
+ *
+ * An unmapped type yields an EMPTY schema, which in JSON Schema means "anything". That is precisely
+ * the green-build-publishes-a-shapeless-field defect the guard exists to stop, so every one is
+ * recorded with the pointer it would have occupied and {@link OpenApiGenerator} refuses on the set.
+ */
+class SchemaRenderer {
+    types;
+    reached = new Set();
+    unmappedFields = [];
+    constructor(types) {
+        this.types = types;
+    }
+    /** Named types this renderer has been asked for, directly or through another schema. */
+    reachedTypes() {
+        return this.reached;
+    }
+    /** Every field with no shape, with its pointer. Empty means the document is fully typed. */
+    unmapped() {
+        return this.unmappedFields;
+    }
+    /**
+     * `components.schemas` for everything reachable from whatever has been rendered so far, expanded
+     * to a FIXPOINT.
+     *
+     * A worklist and not recursion-with-a-guard because rendering a type reaches more types, and the
+     * set has to close over that. It terminates for the same reason the extractor's walk does: a
+     * named type is registered once, so the worklist strictly shrinks.
+     */
+    components() {
+        const rendered = new Map();
+        let grew = true;
+        while (grew) {
+            grew = false;
+            for (const name of Array.from(this.reached)) {
+                if (rendered.has(name)) {
+                    continue;
+                }
+                const type = this.types.get(name);
+                // Rendering it can add MORE names to `reached`, which is what the outer loop is for.
+                rendered.set(name, type === undefined ? undefined : this.namedType(type));
+                grew = true;
+            }
+        }
+        const schemas = new JsonObject_1.JsonObject();
+        // Alphabetical, because `components.schemas` is a lookup table and nothing reads it in order
+        // — whereas discovery order would move every time an operation was added above another.
+        for (const name of Array.from(rendered.keys()).sort()) {
+            schemas.set(name, rendered.get(name));
+        }
+        return schemas;
+    }
+    /** One named type: an object DTO, a string enum, or a union with its DERIVED discriminator. */
+    namedType(type) {
+        const pointer = `#/components/schemas/${type.name}`;
+        if (type.enumValues.length > 0) {
+            return new JsonObject_1.JsonObject()
+                .set('type', 'string')
+                .set('description', this.prose(type.description))
+                .set('enum', type.enumValues.slice());
+        }
+        if (type.unionRefNames.length > 0) {
+            return this.union(type);
+        }
+        const properties = new JsonObject_1.JsonObject();
+        const required = [];
+        for (const field of type.fields) {
+            properties.set(field.name, this.field(field, `${pointer}/properties/${field.name}`));
+            if (!field.optional) {
+                required.push(field.name);
+            }
+        }
+        return new JsonObject_1.JsonObject()
+            .set('type', 'object')
+            .set('description', this.prose(type.description))
+            .set('properties', properties.isEmpty() ? undefined : properties)
+            .set('required', required.length === 0 ? undefined : required)
+            .set('additionalProperties', type.indexSignatureValue === undefined
+            ? undefined
+            : this.type(type.indexSignatureValue, `${pointer}/additionalProperties`));
+    }
+    /**
+     * A union, with a `discriminator` ONLY when the model derived one — which it does only when every
+     * branch carries the same property typed as a single string literal. An invented discriminator
+     * would claim a narrowing TypeScript itself cannot do.
+     */
+    union(type) {
+        const branches = type.unionRefNames.map((name) => this.reference(name));
+        const schema = new JsonObject_1.JsonObject()
+            .set('description', this.prose(type.description))
+            .set('oneOf', branches);
+        if (type.discriminator === undefined) {
+            return schema;
+        }
+        const mapping = new JsonObject_1.JsonObject();
+        for (const branch of type.unionRefNames) {
+            const value = type.discriminator.branchValues.get(branch);
+            if (value !== undefined) {
+                mapping.set(value, `#/components/schemas/${branch}`);
+            }
+        }
+        return schema.set('discriminator', new JsonObject_1.JsonObject()
+            .set('propertyName', type.discriminator.propertyName)
+            .set('mapping', mapping));
+    }
+    /**
+     * One FIELD: its type, plus the prose and the constraints that hang off the field rather than the
+     * type. `@format`, `@WpMin` and `@WpMax` land on the SCALAR — on an array, on the ITEM — because
+     * `minimum` on an array means nothing and a reader would have to guess which half was meant.
+     */
+    field(field, pointer) {
+        const isArray = field.type.kind === 'array';
+        const leafPointer = isArray ? `${pointer}/items` : pointer;
+        const leaf = this.constrain(isArray ? this.type(field.type.items, leafPointer) : this.type(field.type, pointer), field);
+        const schema = isArray
+            ? new JsonObject_1.JsonObject().set('type', 'array').set('items', leaf)
+            : this.nullable(leaf, field.nullable);
+        if (isArray && field.nullable) {
+            return this.described(this.nullable(schema, true), field);
+        }
+        return this.described(schema, field);
+    }
+    /** `description`, and the `@mcp` override as `x-mcp-description` when the author wrote one. */
+    described(schema, field) {
+        return schema
+            .set('description', this.prose(field.description))
+            .set('x-mcp-description', this.prose(field.mcpDescription));
+    }
+    constrain(leaf, field) {
+        return leaf.set('format', field.format).set('minimum', field.min).set('maximum', field.max);
+    }
+    /** `type: [T, "null"]` where there is a type to widen; `anyOf` where the shape is a `$ref`. */
+    nullable(schema, isNullable) {
+        if (!isNullable) {
+            return schema;
+        }
+        const declared = schema.get('type');
+        if (typeof declared === 'string') {
+            return schema.set('type', [declared, 'null']);
+        }
+        return new JsonObject_1.JsonObject().set('anyOf', [schema, new JsonObject_1.JsonObject().set('type', 'null')]);
+    }
+    /** One resolved type, with no field-level prose or constraints on it. */
+    type(ref, pointer) {
+        switch (ref.kind) {
+            case 'primitive':
+                return this.primitive(ref);
+            case 'ref':
+                return this.reference(ref.refName);
+            case 'array':
+                return new JsonObject_1.JsonObject()
+                    .set('type', 'array')
+                    .set('items', this.type(ref.items, `${pointer}/items`));
+            case 'openMap':
+                return new JsonObject_1.JsonObject()
+                    .set('type', 'object')
+                    .set('additionalProperties', this.type(ref.values, `${pointer}/additionalProperties`));
+            case 'enum':
+                return new JsonObject_1.JsonObject().set('type', 'string').set('enum', ref.enumValues.slice());
+            case 'union':
+                return this.namedUnion(ref);
+            default:
+                this.unmappedFields.push(new UnmappedField(pointer, ref.unmappedText ?? '<unknown>'));
+                return new JsonObject_1.JsonObject();
+        }
+    }
+    /**
+     * A union, as a `$ref` at the NAMED alias when the model registered one.
+     *
+     * The model records a `type X = A | B` alias as its own entry — carrying the DERIVED
+     * discriminator — while the FIELD that used it holds a bare union of branch names. Rendering the
+     * field's union inline would therefore publish the `oneOf` and silently drop the discriminator,
+     * which is the one part of a union a client actually needs to narrow on. So the alias is looked
+     * up by its branch list and referenced.
+     */
+    namedUnion(ref) {
+        const branches = ref.unionRefNames.join(',');
+        for (const name of Array.from(this.types.keys())) {
+            if (this.types.get(name).unionRefNames.join(',') === branches) {
+                return this.reference(name);
+            }
+        }
+        return new JsonObject_1.JsonObject().set('oneOf', ref.unionRefNames.map((each) => this.reference(each)));
+    }
+    primitive(ref) {
+        if (ref.primitive === 'unknown') {
+            // No `type` at all: JSON Schema's honest spelling of "any shape". It is only ever reached
+            // by a `void` return, which is why it is not the unmapped refusal.
+            return new JsonObject_1.JsonObject();
+        }
+        return new JsonObject_1.JsonObject().set('type', ref.integer ? 'integer' : ref.primitive);
+    }
+    reference(name) {
+        this.reached.add(name);
+        return new JsonObject_1.JsonObject().set('$ref', `#/components/schemas/${name}`);
+    }
+    /** Empty prose is ABSENT prose. An empty `description` key is noise in every rendered page. */
+    prose(text) {
+        return text === undefined || text.trim() === '' ? undefined : text;
+    }
+}
+exports.SchemaRenderer = SchemaRenderer;
+//# sourceMappingURL=SchemaRenderer.js.map