@webpieces/api-doc-model 0.4.804 → 0.4.805

package/README.md

@@ -2,7 +2,9 @@
 
 Read a webpieces API contract with the TypeScript compiler API and produce one in-memory `ApiDocModel`.
 
-No renderer, no runtime behaviour, no file output. This is the single extraction pass that OpenAPI documents and MCP tool lists are both rendered from, so the two can never disagree about what the contract says.
+No runtime behaviour and no file output. This is the single extraction pass that OpenAPI documents and MCP tool lists are both rendered from, so the two can never disagree about what the contract says.
+
+It carries ONE renderer of its own, `McpSchemaRenderer`, because the MCP projection is not a document — it is the same `ApiJsonSchema` shape `@webpieces/core-util`'s `DtoSchemaBuilder` already produces at boot from reflect-metadata. Rendering it here is what lets the equivalence gate (#983) assert the two are EQUAL, tool by tool and field by field, before #984 takes the MCP runtime off reflection. The OpenAPI document, which genuinely is a document, is `@webpieces/openapi-generator`'s job.
 
 ```typescript
 import { ApiDocExtractor } from '@webpieces/api-doc-model';
@@ -19,3 +21,18 @@ model.unmapped; // UnmappedType[] — recorded, never dropped
 ```
 
 It depends on `typescript` and `@webpieces/core-util`, from which it takes every decorator NAME it matches on — so renaming a decorator is a compile error here rather than a literal that quietly stops matching and empties a generated document. See `responsibilities.md` for what is in and out of scope, why that import is not the coupling it looks like, and why both `Integer` and `@WpInt()` are accepted spellings of integer-ness.
+
+```typescript
+import { ApiDocExtractor, McpSchemaRenderer } from '@webpieces/api-doc-model';
+
+// Every `@ApiPath` contract in one file — a repo does not obey one-contract-per-file.
+const models = new ApiDocExtractor().extractAll('/abs/path/to/Fixtures.ts', options);
+
+const tools = new McpSchemaRenderer(models[0]).render();
+tools[0].name; // the stable protocol name from @WpMcpTool
+tools[0].description; // the method's JSDoc body, or its `@mcp` tag
+tools[0].hints; // three computed from `operation`, openWorldHint from @Endpoint's options
+tools[0].inputSchema; // ApiJsonSchema, identical to DtoSchemaBuilder's
+```
+
+An MCP header is declared in JSDoc as `@mcpHeader <token>` — the runtime's `WpMcpHeader` argument said the same thing, and #984 deletes it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/api-doc-model",
-  "version": "0.4.804",
+  "version": "0.4.805",
   "description": "TypeScript-compiler-API extractor producing one in-memory ApiDocModel from a webpieces API contract. No renderer, no runtime, no app-specific import.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -23,7 +23,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@webpieces/core-util": "0.4.804",
+    "@webpieces/core-util": "0.4.805",
     "typescript": "5.9.3"
   }
 }

package/src/extract/ApiDocExtractor.d.ts

@@ -35,8 +35,27 @@ export declare class ApiDocExtractor {
      *         must be exact (a path constant, a numeric bound) cannot be established.
      */
     extractFile(entryFile: string, compilerOptions?: ts.CompilerOptions): ApiDocModel;
+    /**
+     * EVERY `@ApiPath` contract in one file, in declaration order.
+     *
+     * {@link extractFile} answers "what is THE contract in this file", which is the shape a manifest
+     * entry and a generated document have: one contract, one file. This answers a different question
+     * — "what does this file declare" — and it exists because a REPO does not obey that convention.
+     * `McpRemoteFixtures.ts` in `@webpieces/mcp-server` declares seven contracts, and the runtime
+     * registers MCP tools from all seven; a sweep that read only the first would report green while
+     * six contracts' worth of tools had never been looked at, which is the exact shape of silent miss
+     * this epic exists to remove.
+     *
+     * A file with no contract yields an EMPTY list rather than throwing: "this file has none" is an
+     * ordinary answer to this question, where it is a failure to answer {@link extractFile}'s.
+     */
+    extractAll(entryFile: string, compilerOptions?: ts.CompilerOptions): readonly ApiDocModel[];
+    /** {@link extractAll} against a program the caller already built. */
+    extractAllFrom(program: ts.Program, source: ts.SourceFile): readonly ApiDocModel[];
     /** The same extraction against a program the caller already built. */
     extract(program: ts.Program, source: ts.SourceFile): ApiDocModel;
+    /** ONE contract class -> ONE model. The single place the walk actually happens. */
+    private extractContract;
     /**
      * Extract ONE named type and everything it reaches, from a file that holds NO contract.
      *

package/src/extract/ApiDocExtractor.js

@@ -116,12 +116,48 @@ class ApiDocExtractor {
         }
         return this.extract(program, source);
     }
+    /**
+     * EVERY `@ApiPath` contract in one file, in declaration order.
+     *
+     * {@link extractFile} answers "what is THE contract in this file", which is the shape a manifest
+     * entry and a generated document have: one contract, one file. This answers a different question
+     * — "what does this file declare" — and it exists because a REPO does not obey that convention.
+     * `McpRemoteFixtures.ts` in `@webpieces/mcp-server` declares seven contracts, and the runtime
+     * registers MCP tools from all seven; a sweep that read only the first would report green while
+     * six contracts' worth of tools had never been looked at, which is the exact shape of silent miss
+     * this epic exists to remove.
+     *
+     * A file with no contract yields an EMPTY list rather than throwing: "this file has none" is an
+     * ordinary answer to this question, where it is a failure to answer {@link extractFile}'s.
+     */
+    extractAll(entryFile, compilerOptions = {}) {
+        const program = ts.createProgram([entryFile], compilerOptions);
+        const source = program.getSourceFile(entryFile);
+        if (source === undefined) {
+            throw new ApiDocExtractionError_1.ApiDocExtractionError('entry file is not part of the program', entryFile, 'Pass an absolute path to a .ts file that exists.');
+        }
+        return this.extractAllFrom(program, source);
+    }
+    /** {@link extractAll} against a program the caller already built. */
+    extractAllFrom(program, source) {
+        const models = [];
+        for (const statement of source.statements) {
+            if (ts.isClassDeclaration(statement) &&
+                ApiDocExtractor.decoratorCall(statement, API_PATH) !== undefined) {
+                models.push(this.extractContract(program, statement));
+            }
+        }
+        return models;
+    }
     /** The same extraction against a program the caller already built. */
     extract(program, source) {
+        return this.extractContract(program, this.findContract(source));
+    }
+    /** ONE contract class -> ONE model. The single place the walk actually happens. */
+    extractContract(program, contract) {
         const checker = program.getTypeChecker();
         const folder = new ConstantFolder_1.ConstantFolder(checker);
         const resolver = new TypeResolver_1.TypeResolver(checker);
-        const contract = this.findContract(source);
         const pathDecorator = ApiDocExtractor.decoratorCall(contract, API_PATH);
         const basePathArgument = pathDecorator.arguments[0];
         const basePath = basePathArgument === undefined

package/src/extract/ApiDocExtractor.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiDocExtractor.js","sourceRoot":"","sources":["../../../../../../packages/docs/api-doc-model/src/extract/ApiDocExtractor.ts"],"names":[],"mappings":"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","sourcesContent":["import * as ts from 'typescript';\nimport {\n    ApiPath,\n    CLOUDTASKS,\n    CRON,\n    Endpoint,\n    EXTERNAL,\n    GET,\n    MaskLog,\n    POST,\n    READ,\n    RPC,\n    WRITE,\n    WRITE_IDEMPOTENT,\n    WpAuthApiKey,\n    WpAuthJwt,\n    WpAuthLocalOnly,\n    WpAuthOidc,\n    WpAuthPublic,\n    WpAuthSharedSecret,\n    WpAuthWebhook,\n    ApiType,\n    EXTERNAL_CUSTOMER,\n    MCP,\n    SVC_TO_SVC,\n    WpMcpAuthJwt,\n    WpMcpTool,\n} from '@webpieces/core-util';\nimport {\n    ApiDocModel,\n    DocumentedApiKey,\n    DocumentedApiKeyCredential,\n    DocumentedAuth,\n    DocumentedEndpoint,\n    DocumentedEndpointOptions,\n    DocumentedMcpTool,\n} from '../model/ApiDocModel';\nimport { TypeRef } from '../model/TypeRef';\nimport { ApiDocExtractionError } from './ApiDocExtractionError';\nimport { ConstantFolder } from './ConstantFolder';\nimport { JsDoc } from './JsDoc';\nimport { SourceLocation } from './SourceLocation';\nimport { TypeResolver } from './TypeResolver';\n\n/**\n * The decorator names this extractor matches on, taken from the REAL SYMBOLS rather than re-typed as\n * string literals.\n *\n * ## Why `.name` and not `'Endpoint'`\n *\n * The extractor matches decorators by NAME on the syntax — it must, because it reads a contract with\n * the compiler and never executes it. The question is only where that name comes from, and a literal\n * has a silent failure mode that a symbol does not: rename `@WpMcpTool` in `core-util` and a literal\n * simply stops matching. The extractor then finds zero MCP tools, the MCP document is correctly not\n * written because it has no tools in it, and the BUILD IS GREEN. A partner-facing document silently\n * loses a section with nothing red anywhere (issue #1001).\n *\n * `Endpoint.name` makes that rename a COMPILE ERROR here, which in this repo is the delivery\n * mechanism for a migration rather than an obstacle to one: a compile break names the new spelling\n * and an agent applies it in one pass, where a green build teaches nobody anything.\n *\n * ## Why importing `@webpieces/core-util` is not the coupling it looks like\n *\n * Any contract carrying `@Endpoint` already depends on `core-util` by definition, so there is no\n * upstream project this import could shut out. It is build-time only, it creates no cycle, and it\n * costs a browser bundle nothing because nothing in a bundle imports this package. The direction that\n * WOULD be fatal is `core-util` depending on the TypeScript compiler, and that is not this.\n */\nconst API_PATH = ApiPath.name;\nconst ENDPOINT = Endpoint.name;\nconst MASK_LOG = MaskLog.name;\nconst MCP_TOOL = WpMcpTool.name;\nconst MCP_AUTH = WpMcpAuthJwt.name;\nconst API_KEY_AUTH = WpAuthApiKey.name;\nconst API_TYPE = ApiType.name;\n\n/**\n * The prefix shared by every credential decorator. A PREFIX genuinely has no symbol to take a name\n * from, so it stays a literal — but the set it selects is pinned below, which is what stops it\n * quietly matching nothing.\n */\nconst AUTH_PREFIX = 'WpAuth';\n\n/** Every credential decorator, by real symbol, so a rename of any of them fails to compile here. */\nconst AUTH_DECORATORS = new Set([\n    WpAuthPublic.name,\n    WpAuthJwt.name,\n    WpAuthOidc.name,\n    WpAuthSharedSecret.name,\n    WpAuthWebhook.name,\n    WpAuthApiKey.name,\n    WpAuthLocalOnly.name,\n]);\n\n/** The REAL trigger kinds and side-effect contracts, so a contract cannot declare one that is not. */\nconst ENDPOINT_KINDS: readonly string[] = [RPC, CLOUDTASKS, CRON, EXTERNAL];\nconst ENDPOINT_OPERATIONS: readonly string[] = [READ, WRITE_IDEMPOTENT, WRITE];\nconst HTTP_METHODS: readonly string[] = [GET, POST];\n\n/** `@Endpoint`'s four required positions, named so a failure can say which one is missing. */\nconst ARGUMENT_NAMES = ['http method', 'path', 'operation', 'trigger kind'];\n\n/** The allowed values of each required position, in the same order, for the same failure. */\nconst ARGUMENT_VALUES: readonly (readonly string[])[] = [\n    HTTP_METHODS,\n    [],\n    ENDPOINT_OPERATIONS,\n    ENDPOINT_KINDS,\n];\n\n/** The REAL document types, so a contract cannot name a document that does not exist. */\nconst API_TYPES: readonly string[] = [SVC_TO_SVC, EXTERNAL_CUSTOMER, MCP];\n\n/** The fail-closed default: a contract that declares nothing feeds only the internal document. */\nconst DEFAULT_API_TYPES: readonly string[] = [SVC_TO_SVC];\n\n/**\n * ONE contract file -> ONE {@link ApiDocModel}. The single extraction pass both the OpenAPI documents\n * and the MCP tool list (#982) are rendered from.\n *\n * ## Why the compiler API at all\n *\n * A DTO field's TYPE IS ERASED AT RUNTIME. Reflection can see that `save` takes one argument; it\n * cannot see that the argument has a `deliveryWindow` that is a discriminated union of two shapes,\n * one of which carries an ISO timestamp. Those are precisely the shapes a partner-grade document is\n * made of, so the only place they exist is the source, and the only honest way to read the source is\n * the compiler.\n *\n * ## Why it IMPORTS `@webpieces/core-util`\n *\n * Decorators are matched BY NAME on the syntax — they must be, because this reads a contract and\n * never executes it. The NAMES come from the real symbols (`Endpoint.name`), so a rename in\n * `core-util` is a compile error here instead of a literal that quietly stops matching. The full\n * argument, and why the import is not the coupling it looks like, is at those constants.\n *\n * ## What it does NOT do\n *\n * It emits nothing. No OpenAPI, no MCP tool definitions, no file — that is #982, and keeping the\n * render out means the two renderers cannot drift apart about what the contract SAYS.\n */\nexport class ApiDocExtractor {\n    /**\n     * Extract the contract in `entryFile`.\n     *\n     * @param entryFile absolute path to the `.ts` file holding the `@ApiPath` class.\n     * @param compilerOptions handed straight to `ts.createProgram`; the caller owns them because\n     *        only the caller knows its own `paths` / `lib` setup.\n     * @throws ApiDocExtractionError when the file holds no `@ApiPath` class, or when something that\n     *         must be exact (a path constant, a numeric bound) cannot be established.\n     */\n    extractFile(entryFile: string, compilerOptions: ts.CompilerOptions = {}): ApiDocModel {\n        const program = ts.createProgram([entryFile], compilerOptions);\n        const source = program.getSourceFile(entryFile);\n        if (source === undefined) {\n            throw new ApiDocExtractionError(\n                'entry file is not part of the program',\n                entryFile,\n                'Pass an absolute path to a .ts file that exists.',\n            );\n        }\n        return this.extract(program, source);\n    }\n\n    /** The same extraction against a program the caller already built. */\n    extract(program: ts.Program, source: ts.SourceFile): ApiDocModel {\n        const checker = program.getTypeChecker();\n        const folder = new ConstantFolder(checker);\n        const resolver = new TypeResolver(checker);\n\n        const contract = this.findContract(source);\n        const pathDecorator = ApiDocExtractor.decoratorCall(contract, API_PATH)!;\n        const basePathArgument = pathDecorator.arguments[0];\n        const basePath =\n            basePathArgument === undefined\n                ? ''\n                : folder.foldString(basePathArgument, '@ApiPath argument');\n\n        const apiTypes = this.declaredApiTypes(contract, folder);\n        const endpoints: DocumentedEndpoint[] = [];\n        for (const member of contract.members) {\n            const endpoint = this.endpointOf(member, folder, resolver);\n            if (endpoint !== undefined) {\n                endpoints.push(endpoint);\n            }\n        }\n        this.assertApiTypeMatchesMcpTools(contract, apiTypes, endpoints);\n\n        return new ApiDocModel(\n            contract.name?.text ?? '<anonymous>',\n            apiTypes,\n            basePath,\n            JsDoc.read(contract).description,\n            endpoints,\n            resolver.collectedTypes(),\n            resolver.collectedUnmapped(),\n        );\n    }\n\n    /**\n     * Extract ONE named type and everything it reaches, from a file that holds NO contract.\n     *\n     * This exists for a type nothing in a contract points at but a document still publishes — the\n     * document-wide error body a renderer's manifest names. Reading it with the SAME resolver is the\n     * point: a second reader would be a second answer to \"what shape is this type\", and the two\n     * would drift the first time a field changed.\n     *\n     * @throws ApiDocExtractionError when the file does not declare that name.\n     */\n    extractType(\n        entryFile: string,\n        typeName: string,\n        compilerOptions: ts.CompilerOptions = {},\n    ): ApiDocModel {\n        const program = ts.createProgram([entryFile], compilerOptions);\n        const source = program.getSourceFile(entryFile);\n        if (source === undefined) {\n            throw new ApiDocExtractionError(\n                'entry file is not part of the program',\n                entryFile,\n                'Pass an absolute path to a .ts file that exists.',\n            );\n        }\n        const resolver = new TypeResolver(program.getTypeChecker());\n        const declaration = ApiDocExtractor.declarationNamed(source, typeName);\n        if (declaration === undefined) {\n            throw new ApiDocExtractionError(\n                `no type named '${typeName}' is declared in this file`,\n                entryFile,\n                `Declare and export '${typeName}' there, or name the file that does.`,\n            );\n        }\n        resolver.resolveDeclaration(typeName, declaration, typeName);\n        return new ApiDocModel(\n            typeName,\n            DEFAULT_API_TYPES,\n            '',\n            '',\n            [],\n            resolver.collectedTypes(),\n            resolver.collectedUnmapped(),\n        );\n    }\n\n    /** The interface / class / type alias / enum declared under `name` at the file's top level. */\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static declarationNamed(\n        source: ts.SourceFile,\n        name: string,\n    ): ts.Declaration | undefined {\n        for (const statement of source.statements) {\n            const named =\n                ts.isInterfaceDeclaration(statement) ||\n                ts.isClassDeclaration(statement) ||\n                ts.isTypeAliasDeclaration(statement) ||\n                ts.isEnumDeclaration(statement);\n            if (named && statement.name?.text === name) {\n                return statement;\n            }\n        }\n        return undefined;\n    }\n\n    /** The one `@ApiPath` class in the file. Zero is a hard failure; the FIRST wins if there are two. */\n    private findContract(source: ts.SourceFile): ts.ClassDeclaration {\n        for (const statement of source.statements) {\n            if (\n                ts.isClassDeclaration(statement) &&\n                ApiDocExtractor.decoratorCall(statement, API_PATH) !== undefined\n            ) {\n                return statement;\n            }\n        }\n        throw new ApiDocExtractionError(\n            'no @ApiPath class in this file',\n            source.fileName,\n            'Point the extractor at the contract file — the one whose class carries @ApiPath.',\n        );\n    }\n\n    /** One `@Endpoint` method. Members without the decorator are not part of the contract. */\n    private endpointOf(\n        member: ts.ClassElement,\n        folder: ConstantFolder,\n        resolver: TypeResolver,\n    ): DocumentedEndpoint | undefined {\n        if (!ts.isMethodDeclaration(member) || !ts.isIdentifier(member.name)) {\n            return undefined;\n        }\n        const call = ApiDocExtractor.decoratorCall(member, ENDPOINT);\n        if (call === undefined) {\n            return undefined;\n        }\n        const methodName = member.name.text;\n\n        // `@Endpoint(httpMethod, path, operation, kind, options?)` — METHOD-FIRST, five positions.\n        // The positions are read here and nowhere else, so the one place that has to change when the\n        // decorator changes is this block plus `ARGUMENT_NAMES` beside it.\n        const httpMethod = this.requiredArgument(call, methodName, 0, folder);\n        const path = this.requiredArgument(call, methodName, 1, folder);\n        const operation = this.requiredArgument(call, methodName, 2, folder);\n        const kind = this.requiredArgument(call, methodName, 3, folder);\n\n        const options = call.arguments[4];\n        const literal =\n            options !== undefined && ts.isObjectLiteralExpression(options) ? options : undefined;\n\n        const doc = JsDoc.read(member);\n        const mcpTool = ApiDocExtractor.mcpToolOf(member, folder);\n        return new DocumentedEndpoint(\n            methodName,\n            httpMethod,\n            path,\n            operation,\n            kind,\n            ApiDocExtractor.booleanProperty(literal, 'hidden'),\n            ApiDocExtractor.booleanProperty(literal, 'openWorld'),\n            new DocumentedEndpointOptions(\n                ApiDocExtractor.booleanProperty(literal, 'formPost'),\n                ApiDocExtractor.stringProperty(literal, 'calledBy', folder),\n                ApiDocExtractor.stringProperty(literal, 'callerKind', folder),\n            ),\n            ApiDocExtractor.authOf(member, folder),\n            mcpTool,\n            ApiDocExtractor.decoratorCall(member, MCP_AUTH)?.arguments[0]?.getText(),\n            ApiDocExtractor.maskLogOf(member),\n            doc.description,\n            doc.mcp,\n            this.requestOf(member, methodName, resolver),\n            this.responseOf(member, methodName, resolver),\n        );\n    }\n\n    /**\n     * One REQUIRED positional argument of `@Endpoint`, folded to the string it denotes.\n     *\n     * Every one of the four is an enum member (`POST`, `READ`, `RPC`) as often as it is a literal,\n     * and the folder resolves both — a document that printed `RPC` where the trigger goes would be\n     * worse than no document. A missing one is a hard failure naming the position, because the\n     * alternative is a document quietly missing a verb.\n     */\n    private requiredArgument(\n        call: ts.CallExpression,\n        methodName: string,\n        index: number,\n        folder: ConstantFolder,\n    ): string {\n        const argument = call.arguments[index];\n        const what = ARGUMENT_NAMES[index];\n        if (argument === undefined) {\n            throw new ApiDocExtractionError(\n                `@Endpoint on '${methodName}' declares no ${what}`,\n                SourceLocation.of(call),\n                \"Write all four: @Endpoint(POST, '/thing', READ, RPC).\",\n            );\n        }\n        const value = folder.foldString(argument, `@Endpoint ${what} on '${methodName}'`);\n        const allowed = ARGUMENT_VALUES[index]!;\n        if (allowed.length > 0 && !allowed.includes(value)) {\n            throw new ApiDocExtractionError(\n                `@Endpoint on '${methodName}' declares ${what} '${value}', which is not one of ` +\n                    allowed.join(', '),\n                SourceLocation.of(argument),\n                `Use one of the exported constants: ${allowed.join(', ')}.`,\n            );\n        }\n        return value;\n    }\n\n    /**\n     * `@ApiType(...)` on the contract, folded to the real values.\n     *\n     * A value that is not one of the three documents is a HARD FAILURE rather than a silent drop: a\n     * contract that named `CUSTOMER` by mistake would otherwise feed nothing, which looks exactly\n     * like a contract somebody deliberately kept internal.\n     */\n    private declaredApiTypes(node: ts.Node, folder: ConstantFolder): readonly string[] {\n        const call = ApiDocExtractor.decoratorCall(node, API_TYPE);\n        if (call === undefined) {\n            return DEFAULT_API_TYPES;\n        }\n        const declared = call.arguments.map((argument: ts.Expression) =>\n            folder.foldString(argument, `@${API_TYPE} argument`),\n        );\n        for (const apiType of declared) {\n            if (!API_TYPES.includes(apiType)) {\n                throw new ApiDocExtractionError(\n                    `@${API_TYPE} names '${apiType}', which is not a generated document`,\n                    SourceLocation.of(call),\n                    `Use one of the exported constants: ${API_TYPES.join(', ')}.`,\n                );\n            }\n        }\n        return declared.length === 0 ? DEFAULT_API_TYPES : declared;\n    }\n\n    /**\n     * MCP membership has exactly ONE spelling, and this is the build-time half of enforcing it\n     * (`assertApiTypeMatchesMcpTools` in `@webpieces/core-util` is the wiring-time half).\n     *\n     * Declared in two places, the two can disagree — and the disagreement is invisible, because each\n     * declaration is individually valid. That is the defect this whole epic exists to remove, so it\n     * fails the DOCUMENT build rather than producing one that quietly lists the wrong tools.\n     */\n    private assertApiTypeMatchesMcpTools(\n        contract: ts.ClassDeclaration,\n        apiTypes: readonly string[],\n        endpoints: readonly DocumentedEndpoint[],\n    ): void {\n        const tools = endpoints.filter((e: DocumentedEndpoint) => e.mcpTool !== undefined);\n        const declaresMcp = apiTypes.includes(MCP);\n        if (declaresMcp && tools.length === 0) {\n            throw new ApiDocExtractionError(\n                `@${API_TYPE} names MCP but no method carries @${MCP_TOOL}`,\n                SourceLocation.of(contract),\n                `Add @${MCP_TOOL}({name, description, openWorldHint}) to the methods agents may ` +\n                    `call, or drop MCP from the @${API_TYPE} list.`,\n            );\n        }\n        if (!declaresMcp && tools.length > 0) {\n            const named = tools.map((e: DocumentedEndpoint) => e.methodName).join(', ');\n            throw new ApiDocExtractionError(\n                `@${MCP_TOOL} is on ${named} but @${API_TYPE} does not name MCP`,\n                SourceLocation.of(contract),\n                `Add MCP to the @${API_TYPE} list — membership has ONE spelling, so a tool on a ` +\n                    'contract nobody published to agents is a contradiction, not a hint.',\n            );\n        }\n    }\n\n    /** The FIRST parameter's declared type. An endpoint with no parameter has no request document. */\n    private requestOf(\n        member: ts.MethodDeclaration,\n        methodName: string,\n        resolver: TypeResolver,\n    ): TypeRef | undefined {\n        const parameter = member.parameters[0];\n        if (parameter?.type === undefined) {\n            return undefined;\n        }\n        return resolver.resolve(parameter.type, `${methodName}.request`);\n    }\n\n    /** The declared return type, unwrapped from `Promise<...>` by the resolver. */\n    private responseOf(\n        member: ts.MethodDeclaration,\n        methodName: string,\n        resolver: TypeResolver,\n    ): TypeRef | undefined {\n        if (member.type === undefined) {\n            return undefined;\n        }\n        return resolver.resolve(member.type, `${methodName}.response`);\n    }\n\n    /** `@WpAuthPublic()`, `@WpAuthJwt({...})`, … — recorded verbatim; this package rules on nothing. */\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static authOf(member: ts.Node, folder: ConstantFolder): DocumentedAuth | undefined {\n        const decorators = ts.canHaveDecorators(member) ? (ts.getDecorators(member) ?? []) : [];\n        for (const decorator of decorators) {\n            const call = decorator.expression;\n            if (!ts.isCallExpression(call) || !ts.isIdentifier(call.expression)) {\n                continue;\n            }\n            const name = call.expression.text;\n            if (name.startsWith(AUTH_PREFIX) && AUTH_DECORATORS.has(name)) {\n                return new DocumentedAuth(\n                    name,\n                    call.arguments.map((argument: ts.Expression) => argument.getText()),\n                    name === API_KEY_AUTH ? ApiDocExtractor.apiKeyOf(call, folder) : undefined,\n                );\n            }\n        }\n        return undefined;\n    }\n\n    /**\n     * `@WpAuthApiKey(regime, [{in: 'header', name: 'x-api-key', description: '…'}, …])`, parsed.\n     *\n     * A malformed declaration FAILS rather than yielding a half-parsed regime: the credentials are\n     * what a published document's security block is made of, and a document that silently omitted\n     * one would tell a partner they need fewer credentials than the running hook demands.\n     */\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static apiKeyOf(call: ts.CallExpression, folder: ConstantFolder): DocumentedApiKey {\n        const regimeArgument = call.arguments[0];\n        const credentialsArgument = call.arguments[1];\n        if (regimeArgument === undefined || credentialsArgument === undefined) {\n            throw new ApiDocExtractionError(\n                '@WpAuthApiKey needs a regime AND its credentials',\n                SourceLocation.of(call),\n                \"Write both: @WpAuthApiKey('partner', [{ in: 'header', name: 'x-api-key' }]).\",\n            );\n        }\n        const regime = folder.foldString(regimeArgument, '@WpAuthApiKey regime');\n        // FOLLOW a name first: a credential list shared by every method of a contract is written\n        // once as a `const` and named per method, which is better source than a copy per method.\n        const credentialsLiteral = folder.follow(credentialsArgument);\n        if (!ts.isArrayLiteralExpression(credentialsLiteral)) {\n            throw new ApiDocExtractionError(\n                '@WpAuthApiKey credentials is not an array literal',\n                SourceLocation.of(credentialsArgument),\n                'Write the credentials as an array literal, inline or in a `const`; a value ' +\n                    'assembled at runtime cannot appear in a published security scheme.',\n            );\n        }\n        const credentials: DocumentedApiKeyCredential[] = [];\n        for (const element of credentialsLiteral.elements) {\n            credentials.push(ApiDocExtractor.credentialOf(element, folder));\n        }\n        return new DocumentedApiKey(regime, credentials);\n    }\n\n    /** ONE `{ in: …, name?: …, description?: … }` credential. */\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static credentialOf(\n        expression: ts.Expression,\n        folder: ConstantFolder,\n    ): DocumentedApiKeyCredential {\n        const element = folder.follow(expression);\n        if (!ts.isObjectLiteralExpression(element)) {\n            throw new ApiDocExtractionError(\n                'an @WpAuthApiKey credential is not an object literal',\n                SourceLocation.of(element),\n                \"Write it inline: { in: 'header', name: 'x-api-key' }.\",\n            );\n        }\n        const location = ApiDocExtractor.stringProperty(element, 'in', folder);\n        if (location === undefined) {\n            throw new ApiDocExtractionError(\n                'an @WpAuthApiKey credential declares no `in`',\n                SourceLocation.of(element),\n                \"Say where it rides: `in: 'header'` with a name, or `in: 'bearer'`.\",\n            );\n        }\n        return new DocumentedApiKeyCredential(\n            location,\n            ApiDocExtractor.stringProperty(element, 'name', folder),\n            ApiDocExtractor.stringProperty(element, 'description', folder),\n        );\n    }\n\n    /**\n     * `@WpMcpTool({ name, openWorldHint })` — the two facts the source cannot otherwise state.\n     *\n     * `description` is NOT read: the method's JSDoc is the description for the agent and the partner\n     * alike. The three side-effect hints are not read either — they are computed from the endpoint's\n     * `operation`. See {@link DocumentedMcpTool} for why both of those are deliberate.\n     */\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static mcpToolOf(\n        member: ts.Node,\n        folder: ConstantFolder,\n    ): DocumentedMcpTool | undefined {\n        const call = ApiDocExtractor.decoratorCall(member, MCP_TOOL);\n        const argument = call?.arguments[0];\n        if (argument === undefined || !ts.isObjectLiteralExpression(argument)) {\n            return undefined;\n        }\n        return new DocumentedMcpTool(\n            ApiDocExtractor.stringProperty(argument, 'name', folder) ?? '',\n        );\n    }\n\n    /** `@MaskLog({ refreshToken: 'full' })` -> field name -> mask mode. */\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static maskLogOf(member: ts.Node): ReadonlyMap<string, string> {\n        const fields = new Map<string, string>();\n        const argument = ApiDocExtractor.decoratorCall(member, MASK_LOG)?.arguments[0];\n        if (argument === undefined || !ts.isObjectLiteralExpression(argument)) {\n            return fields;\n        }\n        for (const property of argument.properties) {\n            if (\n                ts.isPropertyAssignment(property) &&\n                (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) &&\n                ts.isStringLiteralLike(property.initializer)\n            ) {\n                fields.set(property.name.text, property.initializer.text);\n            }\n        }\n        return fields;\n    }\n\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static booleanProperty(\n        literal: ts.ObjectLiteralExpression | undefined,\n        name: string,\n    ): boolean {\n        const value =\n            literal === undefined ? undefined : ApiDocExtractor.findProperty(literal, name);\n        return value?.kind === ts.SyntaxKind.TrueKeyword;\n    }\n\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static stringProperty(\n        literal: ts.ObjectLiteralExpression | undefined,\n        name: string,\n        folder: ConstantFolder,\n    ): string | undefined {\n        const value =\n            literal === undefined ? undefined : ApiDocExtractor.findProperty(literal, name);\n        return value === undefined ? undefined : folder.tryFoldString(value);\n    }\n\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static findProperty(\n        literal: ts.ObjectLiteralExpression,\n        name: string,\n    ): ts.Expression | undefined {\n        for (const property of literal.properties) {\n            if (\n                ts.isPropertyAssignment(property) &&\n                (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) &&\n                property.name.text === name\n            ) {\n                return property.initializer;\n            }\n        }\n        return undefined;\n    }\n\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static decoratorCall(\n        node: ts.Node,\n        decoratorName: string,\n    ): ts.CallExpression | undefined {\n        const decorators = ts.canHaveDecorators(node) ? (ts.getDecorators(node) ?? []) : [];\n        for (const decorator of decorators) {\n            const call = decorator.expression;\n            if (\n                ts.isCallExpression(call) &&\n                ts.isIdentifier(call.expression) &&\n                call.expression.text === decoratorName\n            ) {\n                return call;\n            }\n        }\n        return undefined;\n    }\n}\n"]}
+{"version":3,"file":"ApiDocExtractor.js","sourceRoot":"","sources":["../../../../../../packages/docs/api-doc-model/src/extract/ApiDocExtractor.ts"],"names":[],"mappings":"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","sourcesContent":["import * as ts from 'typescript';\nimport {\n    ApiPath,\n    CLOUDTASKS,\n    CRON,\n    Endpoint,\n    EXTERNAL,\n    GET,\n    MaskLog,\n    POST,\n    READ,\n    RPC,\n    WRITE,\n    WRITE_IDEMPOTENT,\n    WpAuthApiKey,\n    WpAuthJwt,\n    WpAuthLocalOnly,\n    WpAuthOidc,\n    WpAuthPublic,\n    WpAuthSharedSecret,\n    WpAuthWebhook,\n    ApiType,\n    EXTERNAL_CUSTOMER,\n    MCP,\n    SVC_TO_SVC,\n    WpMcpAuthJwt,\n    WpMcpTool,\n} from '@webpieces/core-util';\nimport {\n    ApiDocModel,\n    DocumentedApiKey,\n    DocumentedApiKeyCredential,\n    DocumentedAuth,\n    DocumentedEndpoint,\n    DocumentedEndpointOptions,\n    DocumentedMcpTool,\n} from '../model/ApiDocModel';\nimport { TypeRef } from '../model/TypeRef';\nimport { ApiDocExtractionError } from './ApiDocExtractionError';\nimport { ConstantFolder } from './ConstantFolder';\nimport { JsDoc } from './JsDoc';\nimport { SourceLocation } from './SourceLocation';\nimport { TypeResolver } from './TypeResolver';\n\n/**\n * The decorator names this extractor matches on, taken from the REAL SYMBOLS rather than re-typed as\n * string literals.\n *\n * ## Why `.name` and not `'Endpoint'`\n *\n * The extractor matches decorators by NAME on the syntax — it must, because it reads a contract with\n * the compiler and never executes it. The question is only where that name comes from, and a literal\n * has a silent failure mode that a symbol does not: rename `@WpMcpTool` in `core-util` and a literal\n * simply stops matching. The extractor then finds zero MCP tools, the MCP document is correctly not\n * written because it has no tools in it, and the BUILD IS GREEN. A partner-facing document silently\n * loses a section with nothing red anywhere (issue #1001).\n *\n * `Endpoint.name` makes that rename a COMPILE ERROR here, which in this repo is the delivery\n * mechanism for a migration rather than an obstacle to one: a compile break names the new spelling\n * and an agent applies it in one pass, where a green build teaches nobody anything.\n *\n * ## Why importing `@webpieces/core-util` is not the coupling it looks like\n *\n * Any contract carrying `@Endpoint` already depends on `core-util` by definition, so there is no\n * upstream project this import could shut out. It is build-time only, it creates no cycle, and it\n * costs a browser bundle nothing because nothing in a bundle imports this package. The direction that\n * WOULD be fatal is `core-util` depending on the TypeScript compiler, and that is not this.\n */\nconst API_PATH = ApiPath.name;\nconst ENDPOINT = Endpoint.name;\nconst MASK_LOG = MaskLog.name;\nconst MCP_TOOL = WpMcpTool.name;\nconst MCP_AUTH = WpMcpAuthJwt.name;\nconst API_KEY_AUTH = WpAuthApiKey.name;\nconst API_TYPE = ApiType.name;\n\n/**\n * The prefix shared by every credential decorator. A PREFIX genuinely has no symbol to take a name\n * from, so it stays a literal — but the set it selects is pinned below, which is what stops it\n * quietly matching nothing.\n */\nconst AUTH_PREFIX = 'WpAuth';\n\n/** Every credential decorator, by real symbol, so a rename of any of them fails to compile here. */\nconst AUTH_DECORATORS = new Set([\n    WpAuthPublic.name,\n    WpAuthJwt.name,\n    WpAuthOidc.name,\n    WpAuthSharedSecret.name,\n    WpAuthWebhook.name,\n    WpAuthApiKey.name,\n    WpAuthLocalOnly.name,\n]);\n\n/** The REAL trigger kinds and side-effect contracts, so a contract cannot declare one that is not. */\nconst ENDPOINT_KINDS: readonly string[] = [RPC, CLOUDTASKS, CRON, EXTERNAL];\nconst ENDPOINT_OPERATIONS: readonly string[] = [READ, WRITE_IDEMPOTENT, WRITE];\nconst HTTP_METHODS: readonly string[] = [GET, POST];\n\n/** `@Endpoint`'s four required positions, named so a failure can say which one is missing. */\nconst ARGUMENT_NAMES = ['http method', 'path', 'operation', 'trigger kind'];\n\n/** The allowed values of each required position, in the same order, for the same failure. */\nconst ARGUMENT_VALUES: readonly (readonly string[])[] = [\n    HTTP_METHODS,\n    [],\n    ENDPOINT_OPERATIONS,\n    ENDPOINT_KINDS,\n];\n\n/** The REAL document types, so a contract cannot name a document that does not exist. */\nconst API_TYPES: readonly string[] = [SVC_TO_SVC, EXTERNAL_CUSTOMER, MCP];\n\n/** The fail-closed default: a contract that declares nothing feeds only the internal document. */\nconst DEFAULT_API_TYPES: readonly string[] = [SVC_TO_SVC];\n\n/**\n * ONE contract file -> ONE {@link ApiDocModel}. The single extraction pass both the OpenAPI documents\n * and the MCP tool list (#982) are rendered from.\n *\n * ## Why the compiler API at all\n *\n * A DTO field's TYPE IS ERASED AT RUNTIME. Reflection can see that `save` takes one argument; it\n * cannot see that the argument has a `deliveryWindow` that is a discriminated union of two shapes,\n * one of which carries an ISO timestamp. Those are precisely the shapes a partner-grade document is\n * made of, so the only place they exist is the source, and the only honest way to read the source is\n * the compiler.\n *\n * ## Why it IMPORTS `@webpieces/core-util`\n *\n * Decorators are matched BY NAME on the syntax — they must be, because this reads a contract and\n * never executes it. The NAMES come from the real symbols (`Endpoint.name`), so a rename in\n * `core-util` is a compile error here instead of a literal that quietly stops matching. The full\n * argument, and why the import is not the coupling it looks like, is at those constants.\n *\n * ## What it does NOT do\n *\n * It emits nothing. No OpenAPI, no MCP tool definitions, no file — that is #982, and keeping the\n * render out means the two renderers cannot drift apart about what the contract SAYS.\n */\nexport class ApiDocExtractor {\n    /**\n     * Extract the contract in `entryFile`.\n     *\n     * @param entryFile absolute path to the `.ts` file holding the `@ApiPath` class.\n     * @param compilerOptions handed straight to `ts.createProgram`; the caller owns them because\n     *        only the caller knows its own `paths` / `lib` setup.\n     * @throws ApiDocExtractionError when the file holds no `@ApiPath` class, or when something that\n     *         must be exact (a path constant, a numeric bound) cannot be established.\n     */\n    extractFile(entryFile: string, compilerOptions: ts.CompilerOptions = {}): ApiDocModel {\n        const program = ts.createProgram([entryFile], compilerOptions);\n        const source = program.getSourceFile(entryFile);\n        if (source === undefined) {\n            throw new ApiDocExtractionError(\n                'entry file is not part of the program',\n                entryFile,\n                'Pass an absolute path to a .ts file that exists.',\n            );\n        }\n        return this.extract(program, source);\n    }\n\n    /**\n     * EVERY `@ApiPath` contract in one file, in declaration order.\n     *\n     * {@link extractFile} answers \"what is THE contract in this file\", which is the shape a manifest\n     * entry and a generated document have: one contract, one file. This answers a different question\n     * — \"what does this file declare\" — and it exists because a REPO does not obey that convention.\n     * `McpRemoteFixtures.ts` in `@webpieces/mcp-server` declares seven contracts, and the runtime\n     * registers MCP tools from all seven; a sweep that read only the first would report green while\n     * six contracts' worth of tools had never been looked at, which is the exact shape of silent miss\n     * this epic exists to remove.\n     *\n     * A file with no contract yields an EMPTY list rather than throwing: \"this file has none\" is an\n     * ordinary answer to this question, where it is a failure to answer {@link extractFile}'s.\n     */\n    extractAll(\n        entryFile: string,\n        compilerOptions: ts.CompilerOptions = {},\n    ): readonly ApiDocModel[] {\n        const program = ts.createProgram([entryFile], compilerOptions);\n        const source = program.getSourceFile(entryFile);\n        if (source === undefined) {\n            throw new ApiDocExtractionError(\n                'entry file is not part of the program',\n                entryFile,\n                'Pass an absolute path to a .ts file that exists.',\n            );\n        }\n        return this.extractAllFrom(program, source);\n    }\n\n    /** {@link extractAll} against a program the caller already built. */\n    extractAllFrom(program: ts.Program, source: ts.SourceFile): readonly ApiDocModel[] {\n        const models: ApiDocModel[] = [];\n        for (const statement of source.statements) {\n            if (\n                ts.isClassDeclaration(statement) &&\n                ApiDocExtractor.decoratorCall(statement, API_PATH) !== undefined\n            ) {\n                models.push(this.extractContract(program, statement));\n            }\n        }\n        return models;\n    }\n\n    /** The same extraction against a program the caller already built. */\n    extract(program: ts.Program, source: ts.SourceFile): ApiDocModel {\n        return this.extractContract(program, this.findContract(source));\n    }\n\n    /** ONE contract class -> ONE model. The single place the walk actually happens. */\n    private extractContract(program: ts.Program, contract: ts.ClassDeclaration): ApiDocModel {\n        const checker = program.getTypeChecker();\n        const folder = new ConstantFolder(checker);\n        const resolver = new TypeResolver(checker);\n\n        const pathDecorator = ApiDocExtractor.decoratorCall(contract, API_PATH)!;\n        const basePathArgument = pathDecorator.arguments[0];\n        const basePath =\n            basePathArgument === undefined\n                ? ''\n                : folder.foldString(basePathArgument, '@ApiPath argument');\n\n        const apiTypes = this.declaredApiTypes(contract, folder);\n        const endpoints: DocumentedEndpoint[] = [];\n        for (const member of contract.members) {\n            const endpoint = this.endpointOf(member, folder, resolver);\n            if (endpoint !== undefined) {\n                endpoints.push(endpoint);\n            }\n        }\n        this.assertApiTypeMatchesMcpTools(contract, apiTypes, endpoints);\n\n        return new ApiDocModel(\n            contract.name?.text ?? '<anonymous>',\n            apiTypes,\n            basePath,\n            JsDoc.read(contract).description,\n            endpoints,\n            resolver.collectedTypes(),\n            resolver.collectedUnmapped(),\n        );\n    }\n\n    /**\n     * Extract ONE named type and everything it reaches, from a file that holds NO contract.\n     *\n     * This exists for a type nothing in a contract points at but a document still publishes — the\n     * document-wide error body a renderer's manifest names. Reading it with the SAME resolver is the\n     * point: a second reader would be a second answer to \"what shape is this type\", and the two\n     * would drift the first time a field changed.\n     *\n     * @throws ApiDocExtractionError when the file does not declare that name.\n     */\n    extractType(\n        entryFile: string,\n        typeName: string,\n        compilerOptions: ts.CompilerOptions = {},\n    ): ApiDocModel {\n        const program = ts.createProgram([entryFile], compilerOptions);\n        const source = program.getSourceFile(entryFile);\n        if (source === undefined) {\n            throw new ApiDocExtractionError(\n                'entry file is not part of the program',\n                entryFile,\n                'Pass an absolute path to a .ts file that exists.',\n            );\n        }\n        const resolver = new TypeResolver(program.getTypeChecker());\n        const declaration = ApiDocExtractor.declarationNamed(source, typeName);\n        if (declaration === undefined) {\n            throw new ApiDocExtractionError(\n                `no type named '${typeName}' is declared in this file`,\n                entryFile,\n                `Declare and export '${typeName}' there, or name the file that does.`,\n            );\n        }\n        resolver.resolveDeclaration(typeName, declaration, typeName);\n        return new ApiDocModel(\n            typeName,\n            DEFAULT_API_TYPES,\n            '',\n            '',\n            [],\n            resolver.collectedTypes(),\n            resolver.collectedUnmapped(),\n        );\n    }\n\n    /** The interface / class / type alias / enum declared under `name` at the file's top level. */\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static declarationNamed(\n        source: ts.SourceFile,\n        name: string,\n    ): ts.Declaration | undefined {\n        for (const statement of source.statements) {\n            const named =\n                ts.isInterfaceDeclaration(statement) ||\n                ts.isClassDeclaration(statement) ||\n                ts.isTypeAliasDeclaration(statement) ||\n                ts.isEnumDeclaration(statement);\n            if (named && statement.name?.text === name) {\n                return statement;\n            }\n        }\n        return undefined;\n    }\n\n    /** The one `@ApiPath` class in the file. Zero is a hard failure; the FIRST wins if there are two. */\n    private findContract(source: ts.SourceFile): ts.ClassDeclaration {\n        for (const statement of source.statements) {\n            if (\n                ts.isClassDeclaration(statement) &&\n                ApiDocExtractor.decoratorCall(statement, API_PATH) !== undefined\n            ) {\n                return statement;\n            }\n        }\n        throw new ApiDocExtractionError(\n            'no @ApiPath class in this file',\n            source.fileName,\n            'Point the extractor at the contract file — the one whose class carries @ApiPath.',\n        );\n    }\n\n    /** One `@Endpoint` method. Members without the decorator are not part of the contract. */\n    private endpointOf(\n        member: ts.ClassElement,\n        folder: ConstantFolder,\n        resolver: TypeResolver,\n    ): DocumentedEndpoint | undefined {\n        if (!ts.isMethodDeclaration(member) || !ts.isIdentifier(member.name)) {\n            return undefined;\n        }\n        const call = ApiDocExtractor.decoratorCall(member, ENDPOINT);\n        if (call === undefined) {\n            return undefined;\n        }\n        const methodName = member.name.text;\n\n        // `@Endpoint(httpMethod, path, operation, kind, options?)` — METHOD-FIRST, five positions.\n        // The positions are read here and nowhere else, so the one place that has to change when the\n        // decorator changes is this block plus `ARGUMENT_NAMES` beside it.\n        const httpMethod = this.requiredArgument(call, methodName, 0, folder);\n        const path = this.requiredArgument(call, methodName, 1, folder);\n        const operation = this.requiredArgument(call, methodName, 2, folder);\n        const kind = this.requiredArgument(call, methodName, 3, folder);\n\n        const options = call.arguments[4];\n        const literal =\n            options !== undefined && ts.isObjectLiteralExpression(options) ? options : undefined;\n\n        const doc = JsDoc.read(member);\n        const mcpTool = ApiDocExtractor.mcpToolOf(member, folder);\n        return new DocumentedEndpoint(\n            methodName,\n            httpMethod,\n            path,\n            operation,\n            kind,\n            ApiDocExtractor.booleanProperty(literal, 'hidden'),\n            ApiDocExtractor.booleanProperty(literal, 'openWorld'),\n            new DocumentedEndpointOptions(\n                ApiDocExtractor.booleanProperty(literal, 'formPost'),\n                ApiDocExtractor.stringProperty(literal, 'calledBy', folder),\n                ApiDocExtractor.stringProperty(literal, 'callerKind', folder),\n            ),\n            ApiDocExtractor.authOf(member, folder),\n            mcpTool,\n            ApiDocExtractor.decoratorCall(member, MCP_AUTH)?.arguments[0]?.getText(),\n            ApiDocExtractor.maskLogOf(member),\n            doc.description,\n            doc.mcp,\n            this.requestOf(member, methodName, resolver),\n            this.responseOf(member, methodName, resolver),\n        );\n    }\n\n    /**\n     * One REQUIRED positional argument of `@Endpoint`, folded to the string it denotes.\n     *\n     * Every one of the four is an enum member (`POST`, `READ`, `RPC`) as often as it is a literal,\n     * and the folder resolves both — a document that printed `RPC` where the trigger goes would be\n     * worse than no document. A missing one is a hard failure naming the position, because the\n     * alternative is a document quietly missing a verb.\n     */\n    private requiredArgument(\n        call: ts.CallExpression,\n        methodName: string,\n        index: number,\n        folder: ConstantFolder,\n    ): string {\n        const argument = call.arguments[index];\n        const what = ARGUMENT_NAMES[index];\n        if (argument === undefined) {\n            throw new ApiDocExtractionError(\n                `@Endpoint on '${methodName}' declares no ${what}`,\n                SourceLocation.of(call),\n                \"Write all four: @Endpoint(POST, '/thing', READ, RPC).\",\n            );\n        }\n        const value = folder.foldString(argument, `@Endpoint ${what} on '${methodName}'`);\n        const allowed = ARGUMENT_VALUES[index]!;\n        if (allowed.length > 0 && !allowed.includes(value)) {\n            throw new ApiDocExtractionError(\n                `@Endpoint on '${methodName}' declares ${what} '${value}', which is not one of ` +\n                    allowed.join(', '),\n                SourceLocation.of(argument),\n                `Use one of the exported constants: ${allowed.join(', ')}.`,\n            );\n        }\n        return value;\n    }\n\n    /**\n     * `@ApiType(...)` on the contract, folded to the real values.\n     *\n     * A value that is not one of the three documents is a HARD FAILURE rather than a silent drop: a\n     * contract that named `CUSTOMER` by mistake would otherwise feed nothing, which looks exactly\n     * like a contract somebody deliberately kept internal.\n     */\n    private declaredApiTypes(node: ts.Node, folder: ConstantFolder): readonly string[] {\n        const call = ApiDocExtractor.decoratorCall(node, API_TYPE);\n        if (call === undefined) {\n            return DEFAULT_API_TYPES;\n        }\n        const declared = call.arguments.map((argument: ts.Expression) =>\n            folder.foldString(argument, `@${API_TYPE} argument`),\n        );\n        for (const apiType of declared) {\n            if (!API_TYPES.includes(apiType)) {\n                throw new ApiDocExtractionError(\n                    `@${API_TYPE} names '${apiType}', which is not a generated document`,\n                    SourceLocation.of(call),\n                    `Use one of the exported constants: ${API_TYPES.join(', ')}.`,\n                );\n            }\n        }\n        return declared.length === 0 ? DEFAULT_API_TYPES : declared;\n    }\n\n    /**\n     * MCP membership has exactly ONE spelling, and this is the build-time half of enforcing it\n     * (`assertApiTypeMatchesMcpTools` in `@webpieces/core-util` is the wiring-time half).\n     *\n     * Declared in two places, the two can disagree — and the disagreement is invisible, because each\n     * declaration is individually valid. That is the defect this whole epic exists to remove, so it\n     * fails the DOCUMENT build rather than producing one that quietly lists the wrong tools.\n     */\n    private assertApiTypeMatchesMcpTools(\n        contract: ts.ClassDeclaration,\n        apiTypes: readonly string[],\n        endpoints: readonly DocumentedEndpoint[],\n    ): void {\n        const tools = endpoints.filter((e: DocumentedEndpoint) => e.mcpTool !== undefined);\n        const declaresMcp = apiTypes.includes(MCP);\n        if (declaresMcp && tools.length === 0) {\n            throw new ApiDocExtractionError(\n                `@${API_TYPE} names MCP but no method carries @${MCP_TOOL}`,\n                SourceLocation.of(contract),\n                `Add @${MCP_TOOL}({name, description, openWorldHint}) to the methods agents may ` +\n                    `call, or drop MCP from the @${API_TYPE} list.`,\n            );\n        }\n        if (!declaresMcp && tools.length > 0) {\n            const named = tools.map((e: DocumentedEndpoint) => e.methodName).join(', ');\n            throw new ApiDocExtractionError(\n                `@${MCP_TOOL} is on ${named} but @${API_TYPE} does not name MCP`,\n                SourceLocation.of(contract),\n                `Add MCP to the @${API_TYPE} list — membership has ONE spelling, so a tool on a ` +\n                    'contract nobody published to agents is a contradiction, not a hint.',\n            );\n        }\n    }\n\n    /** The FIRST parameter's declared type. An endpoint with no parameter has no request document. */\n    private requestOf(\n        member: ts.MethodDeclaration,\n        methodName: string,\n        resolver: TypeResolver,\n    ): TypeRef | undefined {\n        const parameter = member.parameters[0];\n        if (parameter?.type === undefined) {\n            return undefined;\n        }\n        return resolver.resolve(parameter.type, `${methodName}.request`);\n    }\n\n    /** The declared return type, unwrapped from `Promise<...>` by the resolver. */\n    private responseOf(\n        member: ts.MethodDeclaration,\n        methodName: string,\n        resolver: TypeResolver,\n    ): TypeRef | undefined {\n        if (member.type === undefined) {\n            return undefined;\n        }\n        return resolver.resolve(member.type, `${methodName}.response`);\n    }\n\n    /** `@WpAuthPublic()`, `@WpAuthJwt({...})`, … — recorded verbatim; this package rules on nothing. */\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static authOf(member: ts.Node, folder: ConstantFolder): DocumentedAuth | undefined {\n        const decorators = ts.canHaveDecorators(member) ? (ts.getDecorators(member) ?? []) : [];\n        for (const decorator of decorators) {\n            const call = decorator.expression;\n            if (!ts.isCallExpression(call) || !ts.isIdentifier(call.expression)) {\n                continue;\n            }\n            const name = call.expression.text;\n            if (name.startsWith(AUTH_PREFIX) && AUTH_DECORATORS.has(name)) {\n                return new DocumentedAuth(\n                    name,\n                    call.arguments.map((argument: ts.Expression) => argument.getText()),\n                    name === API_KEY_AUTH ? ApiDocExtractor.apiKeyOf(call, folder) : undefined,\n                );\n            }\n        }\n        return undefined;\n    }\n\n    /**\n     * `@WpAuthApiKey(regime, [{in: 'header', name: 'x-api-key', description: '…'}, …])`, parsed.\n     *\n     * A malformed declaration FAILS rather than yielding a half-parsed regime: the credentials are\n     * what a published document's security block is made of, and a document that silently omitted\n     * one would tell a partner they need fewer credentials than the running hook demands.\n     */\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static apiKeyOf(call: ts.CallExpression, folder: ConstantFolder): DocumentedApiKey {\n        const regimeArgument = call.arguments[0];\n        const credentialsArgument = call.arguments[1];\n        if (regimeArgument === undefined || credentialsArgument === undefined) {\n            throw new ApiDocExtractionError(\n                '@WpAuthApiKey needs a regime AND its credentials',\n                SourceLocation.of(call),\n                \"Write both: @WpAuthApiKey('partner', [{ in: 'header', name: 'x-api-key' }]).\",\n            );\n        }\n        const regime = folder.foldString(regimeArgument, '@WpAuthApiKey regime');\n        // FOLLOW a name first: a credential list shared by every method of a contract is written\n        // once as a `const` and named per method, which is better source than a copy per method.\n        const credentialsLiteral = folder.follow(credentialsArgument);\n        if (!ts.isArrayLiteralExpression(credentialsLiteral)) {\n            throw new ApiDocExtractionError(\n                '@WpAuthApiKey credentials is not an array literal',\n                SourceLocation.of(credentialsArgument),\n                'Write the credentials as an array literal, inline or in a `const`; a value ' +\n                    'assembled at runtime cannot appear in a published security scheme.',\n            );\n        }\n        const credentials: DocumentedApiKeyCredential[] = [];\n        for (const element of credentialsLiteral.elements) {\n            credentials.push(ApiDocExtractor.credentialOf(element, folder));\n        }\n        return new DocumentedApiKey(regime, credentials);\n    }\n\n    /** ONE `{ in: …, name?: …, description?: … }` credential. */\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static credentialOf(\n        expression: ts.Expression,\n        folder: ConstantFolder,\n    ): DocumentedApiKeyCredential {\n        const element = folder.follow(expression);\n        if (!ts.isObjectLiteralExpression(element)) {\n            throw new ApiDocExtractionError(\n                'an @WpAuthApiKey credential is not an object literal',\n                SourceLocation.of(element),\n                \"Write it inline: { in: 'header', name: 'x-api-key' }.\",\n            );\n        }\n        const location = ApiDocExtractor.stringProperty(element, 'in', folder);\n        if (location === undefined) {\n            throw new ApiDocExtractionError(\n                'an @WpAuthApiKey credential declares no `in`',\n                SourceLocation.of(element),\n                \"Say where it rides: `in: 'header'` with a name, or `in: 'bearer'`.\",\n            );\n        }\n        return new DocumentedApiKeyCredential(\n            location,\n            ApiDocExtractor.stringProperty(element, 'name', folder),\n            ApiDocExtractor.stringProperty(element, 'description', folder),\n        );\n    }\n\n    /**\n     * `@WpMcpTool({ name, openWorldHint })` — the two facts the source cannot otherwise state.\n     *\n     * `description` is NOT read: the method's JSDoc is the description for the agent and the partner\n     * alike. The three side-effect hints are not read either — they are computed from the endpoint's\n     * `operation`. See {@link DocumentedMcpTool} for why both of those are deliberate.\n     */\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static mcpToolOf(\n        member: ts.Node,\n        folder: ConstantFolder,\n    ): DocumentedMcpTool | undefined {\n        const call = ApiDocExtractor.decoratorCall(member, MCP_TOOL);\n        const argument = call?.arguments[0];\n        if (argument === undefined || !ts.isObjectLiteralExpression(argument)) {\n            return undefined;\n        }\n        return new DocumentedMcpTool(\n            ApiDocExtractor.stringProperty(argument, 'name', folder) ?? '',\n        );\n    }\n\n    /** `@MaskLog({ refreshToken: 'full' })` -> field name -> mask mode. */\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static maskLogOf(member: ts.Node): ReadonlyMap<string, string> {\n        const fields = new Map<string, string>();\n        const argument = ApiDocExtractor.decoratorCall(member, MASK_LOG)?.arguments[0];\n        if (argument === undefined || !ts.isObjectLiteralExpression(argument)) {\n            return fields;\n        }\n        for (const property of argument.properties) {\n            if (\n                ts.isPropertyAssignment(property) &&\n                (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) &&\n                ts.isStringLiteralLike(property.initializer)\n            ) {\n                fields.set(property.name.text, property.initializer.text);\n            }\n        }\n        return fields;\n    }\n\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static booleanProperty(\n        literal: ts.ObjectLiteralExpression | undefined,\n        name: string,\n    ): boolean {\n        const value =\n            literal === undefined ? undefined : ApiDocExtractor.findProperty(literal, name);\n        return value?.kind === ts.SyntaxKind.TrueKeyword;\n    }\n\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static stringProperty(\n        literal: ts.ObjectLiteralExpression | undefined,\n        name: string,\n        folder: ConstantFolder,\n    ): string | undefined {\n        const value =\n            literal === undefined ? undefined : ApiDocExtractor.findProperty(literal, name);\n        return value === undefined ? undefined : folder.tryFoldString(value);\n    }\n\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static findProperty(\n        literal: ts.ObjectLiteralExpression,\n        name: string,\n    ): ts.Expression | undefined {\n        for (const property of literal.properties) {\n            if (\n                ts.isPropertyAssignment(property) &&\n                (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) &&\n                property.name.text === name\n            ) {\n                return property.initializer;\n            }\n        }\n        return undefined;\n    }\n\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static decoratorCall(\n        node: ts.Node,\n        decoratorName: string,\n    ): ts.CallExpression | undefined {\n        const decorators = ts.canHaveDecorators(node) ? (ts.getDecorators(node) ?? []) : [];\n        for (const decorator of decorators) {\n            const call = decorator.expression;\n            if (\n                ts.isCallExpression(call) &&\n                ts.isIdentifier(call.expression) &&\n                call.expression.text === decoratorName\n            ) {\n                return call;\n            }\n        }\n        return undefined;\n    }\n}\n"]}

package/src/extract/JsDoc.d.ts

@@ -19,6 +19,16 @@ export declare class JsDoc {
      * the human one" are different facts, and only the first is worth trusting.
      */
     readonly mcp: string | undefined;
+    /**
+     * The `@mcpHeader <token>` block tag — the MCP 2026 SEP-2243 header a PRIMITIVE tool
+     * parameter is mirrored into (`Mcp-Param-{token}`).
+     *
+     * It is a JSDoc tag and not a decorator because it is a DOCUMENTATION fact about one field
+     * of one wire document, and this epic's rule is that documentation has one source. The
+     * runtime spells the same fact as `WpMcpHeader` inside `@WpDtoField`; #984 deletes that
+     * spelling, and the equivalence gate (#983) is what proves the two say the same thing first.
+     */
+    readonly mcpHeader: string | undefined;
     private constructor();
     /** Read the JSDoc attached to one declaration. */
     static read(node: ts.Node): JsDoc;

package/src/extract/JsDoc.js

@@ -15,6 +15,7 @@ class JsDoc {
     description;
     format;
     mcp;
+    mcpHeader;
     constructor(
     /** The body text, links flattened, trimmed. Empty string when undocumented. */
     description, 
@@ -26,10 +27,21 @@ class JsDoc {
      * fallback is NOT applied here: "the author wrote an agent-facing sentence" and "we reused
      * the human one" are different facts, and only the first is worth trusting.
      */
-    mcp) {
+    mcp, 
+    /**
+     * The `@mcpHeader <token>` block tag — the MCP 2026 SEP-2243 header a PRIMITIVE tool
+     * parameter is mirrored into (`Mcp-Param-{token}`).
+     *
+     * It is a JSDoc tag and not a decorator because it is a DOCUMENTATION fact about one field
+     * of one wire document, and this epic's rule is that documentation has one source. The
+     * runtime spells the same fact as `WpMcpHeader` inside `@WpDtoField`; #984 deletes that
+     * spelling, and the equivalence gate (#983) is what proves the two say the same thing first.
+     */
+    mcpHeader) {
         this.description = description;
         this.format = format;
         this.mcp = mcp;
+        this.mcpHeader = mcpHeader;
     }
     /** Read the JSDoc attached to one declaration. */
     // webpieces-disable no-function-outside-class -- static factory; JsDoc has a private constructor so a caller cannot invent prose
@@ -39,6 +51,7 @@ class JsDoc {
         const bodies = [];
         let format;
         let mcp;
+        let mcpHeader;
         for (const block of blocks) {
             bodies.push(JsDoc.flatten(block.comment));
             for (const tag of block.tags ?? []) {
@@ -50,9 +63,12 @@ class JsDoc {
                 else if (name === 'mcp' && text !== '') {
                     mcp = text;
                 }
+                else if (name === 'mcpHeader' && text !== '') {
+                    mcpHeader = text;
+                }
             }
         }
-        return new JsDoc(bodies.join('\n').trim(), format, mcp);
+        return new JsDoc(bodies.join('\n').trim(), format, mcp, mcpHeader);
     }
     /**
      * A comment's text with every inline tag replaced by its own text: `{@link Foo.bar}` -> `Foo.bar`,

package/src/extract/JsDoc.js.map

@@ -1 +1 @@
-{"version":3,"file":"JsDoc.js","sourceRoot":"","sources":["../../../../../../packages/docs/api-doc-model/src/extract/JsDoc.ts"],"names":[],"mappings":";;;;AAAA,uDAAiC;AAQjC;;;;;;;GAOG;AACH,MAAa,KAAK;IAGD;IAEA;IAOA;IAXb;IACI,+EAA+E;IACtE,WAAmB;IAC5B,kEAAkE;IACzD,MAA0B;IACnC;;;;;OAKG;IACM,GAAuB;QATvB,gBAAW,GAAX,WAAW,CAAQ;QAEnB,WAAM,GAAN,MAAM,CAAoB;QAO1B,QAAG,GAAH,GAAG,CAAoB;IACjC,CAAC;IAEJ,kDAAkD;IAClD,iIAAiI;IACjI,MAAM,CAAC,IAAI,CAAC,IAAa;QACrB,MAAM,UAAU,GAAG,IAAoB,CAAC;QACxC,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,IAAI,EAAE,CAAC;QACtC,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,IAAI,MAA0B,CAAC;QAC/B,IAAI,GAAuB,CAAC;QAE5B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YACzB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;YAC1C,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;gBACjC,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC;gBAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBACxC,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;oBACnC,MAAM,GAAG,IAAI,CAAC;gBAClB,CAAC;qBAAM,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;oBACvC,GAAG,GAAG,IAAI,CAAC;gBACf,CAAC;YACL,CAAC;QACL,CAAC;QAED,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5D,CAAC;IAED;;;;;;OAMG;IACH,qFAAqF;IAC7E,MAAM,CAAC,OAAO,CAAC,OAA2D;QAC9E,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,EAAE,CAAC;QACd,CAAC;QACD,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;QAC1B,CAAC;QACD,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YACzB,IAAI,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;gBAChF,kFAAkF;gBAClF,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;gBACtD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACpD,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAC9C,CAAC;iBAAM,CAAC;gBACJ,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC1B,CAAC;QACL,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACjC,CAAC;CACJ;AApED,sBAoEC","sourcesContent":["import * as ts from 'typescript';\n\n/**\n * A node the compiler has attached JSDoc blocks to. `jsDoc` is internal to the TypeScript API and is\n * therefore not on `ts.Node`, so it is named HERE, once, instead of being cast at the use site.\n */\ntype JsDocCarrier = ts.Node & { jsDoc?: ts.JSDoc[] };\n\n/**\n * The PROSE half of the model: the JSDoc body, the `@format` tag and the `@mcp` override.\n *\n * `{@link Foo.bar}` is flattened to `Foo.bar` HERE, at this boundary, and that placement is the\n * point: a link is a TypeScript editor affordance, and every downstream renderer — OpenAPI\n * `description`, an MCP tool description, an HTML page — would otherwise each have to know the inline\n * tag grammar and each get it slightly differently wrong. One flattening, at extraction.\n */\nexport class JsDoc {\n    private constructor(\n        /** The body text, links flattened, trimmed. Empty string when undocumented. */\n        readonly description: string,\n        /** The `@format` block tag's text, e.g. `email` / `date-time`. */\n        readonly format: string | undefined,\n        /**\n         * The `@mcp` block tag's text — the OPTIONAL agent-facing override. Undefined means the\n         * author wrote none, which a renderer answers by falling back to {@link description}. The\n         * fallback is NOT applied here: \"the author wrote an agent-facing sentence\" and \"we reused\n         * the human one\" are different facts, and only the first is worth trusting.\n         */\n        readonly mcp: string | undefined,\n    ) {}\n\n    /** Read the JSDoc attached to one declaration. */\n    // webpieces-disable no-function-outside-class -- static factory; JsDoc has a private constructor so a caller cannot invent prose\n    static read(node: ts.Node): JsDoc {\n        const symbolLike = node as JsDocCarrier;\n        const blocks = symbolLike.jsDoc ?? [];\n        const bodies: string[] = [];\n        let format: string | undefined;\n        let mcp: string | undefined;\n\n        for (const block of blocks) {\n            bodies.push(JsDoc.flatten(block.comment));\n            for (const tag of block.tags ?? []) {\n                const name = tag.tagName.text;\n                const text = JsDoc.flatten(tag.comment);\n                if (name === 'format' && text !== '') {\n                    format = text;\n                } else if (name === 'mcp' && text !== '') {\n                    mcp = text;\n                }\n            }\n        }\n\n        return new JsDoc(bodies.join('\\n').trim(), format, mcp);\n    }\n\n    /**\n     * A comment's text with every inline tag replaced by its own text: `{@link Foo.bar}` -> `Foo.bar`,\n     * `{@link Foo.bar|the widget}` -> `the widget`.\n     *\n     * TypeScript hands a commented node either a plain string or an array of parts, and the link\n     * parts are the ones with structure. Both shapes are handled here so no caller has to.\n     */\n    // webpieces-disable no-function-outside-class -- private static helper of this class\n    private static flatten(comment: string | ts.NodeArray<ts.JSDocComment> | undefined): string {\n        if (comment === undefined) {\n            return '';\n        }\n        if (typeof comment === 'string') {\n            return comment.trim();\n        }\n        const parts: string[] = [];\n        for (const part of comment) {\n            if (ts.isJSDocLink(part) || ts.isJSDocLinkCode(part) || ts.isJSDocLinkPlain(part)) {\n                // `text` is whatever followed the target ('|the widget'); the NAME is the target.\n                const label = part.text.replace(/^[|\\s]+/, '').trim();\n                const target = part.name ? part.name.getText() : '';\n                parts.push(label !== '' ? label : target);\n            } else {\n                parts.push(part.text);\n            }\n        }\n        return parts.join('').trim();\n    }\n}\n"]}
+{"version":3,"file":"JsDoc.js","sourceRoot":"","sources":["../../../../../../packages/docs/api-doc-model/src/extract/JsDoc.ts"],"names":[],"mappings":"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","sourcesContent":["import * as ts from 'typescript';\n\n/**\n * A node the compiler has attached JSDoc blocks to. `jsDoc` is internal to the TypeScript API and is\n * therefore not on `ts.Node`, so it is named HERE, once, instead of being cast at the use site.\n */\ntype JsDocCarrier = ts.Node & { jsDoc?: ts.JSDoc[] };\n\n/**\n * The PROSE half of the model: the JSDoc body, the `@format` tag and the `@mcp` override.\n *\n * `{@link Foo.bar}` is flattened to `Foo.bar` HERE, at this boundary, and that placement is the\n * point: a link is a TypeScript editor affordance, and every downstream renderer — OpenAPI\n * `description`, an MCP tool description, an HTML page — would otherwise each have to know the inline\n * tag grammar and each get it slightly differently wrong. One flattening, at extraction.\n */\nexport class JsDoc {\n    private constructor(\n        /** The body text, links flattened, trimmed. Empty string when undocumented. */\n        readonly description: string,\n        /** The `@format` block tag's text, e.g. `email` / `date-time`. */\n        readonly format: string | undefined,\n        /**\n         * The `@mcp` block tag's text — the OPTIONAL agent-facing override. Undefined means the\n         * author wrote none, which a renderer answers by falling back to {@link description}. The\n         * fallback is NOT applied here: \"the author wrote an agent-facing sentence\" and \"we reused\n         * the human one\" are different facts, and only the first is worth trusting.\n         */\n        readonly mcp: string | undefined,\n        /**\n         * The `@mcpHeader <token>` block tag — the MCP 2026 SEP-2243 header a PRIMITIVE tool\n         * parameter is mirrored into (`Mcp-Param-{token}`).\n         *\n         * It is a JSDoc tag and not a decorator because it is a DOCUMENTATION fact about one field\n         * of one wire document, and this epic's rule is that documentation has one source. The\n         * runtime spells the same fact as `WpMcpHeader` inside `@WpDtoField`; #984 deletes that\n         * spelling, and the equivalence gate (#983) is what proves the two say the same thing first.\n         */\n        readonly mcpHeader: string | undefined,\n    ) {}\n\n    /** Read the JSDoc attached to one declaration. */\n    // webpieces-disable no-function-outside-class -- static factory; JsDoc has a private constructor so a caller cannot invent prose\n    static read(node: ts.Node): JsDoc {\n        const symbolLike = node as JsDocCarrier;\n        const blocks = symbolLike.jsDoc ?? [];\n        const bodies: string[] = [];\n        let format: string | undefined;\n        let mcp: string | undefined;\n        let mcpHeader: string | undefined;\n\n        for (const block of blocks) {\n            bodies.push(JsDoc.flatten(block.comment));\n            for (const tag of block.tags ?? []) {\n                const name = tag.tagName.text;\n                const text = JsDoc.flatten(tag.comment);\n                if (name === 'format' && text !== '') {\n                    format = text;\n                } else if (name === 'mcp' && text !== '') {\n                    mcp = text;\n                } else if (name === 'mcpHeader' && text !== '') {\n                    mcpHeader = text;\n                }\n            }\n        }\n\n        return new JsDoc(bodies.join('\\n').trim(), format, mcp, mcpHeader);\n    }\n\n    /**\n     * A comment's text with every inline tag replaced by its own text: `{@link Foo.bar}` -> `Foo.bar`,\n     * `{@link Foo.bar|the widget}` -> `the widget`.\n     *\n     * TypeScript hands a commented node either a plain string or an array of parts, and the link\n     * parts are the ones with structure. Both shapes are handled here so no caller has to.\n     */\n    // webpieces-disable no-function-outside-class -- private static helper of this class\n    private static flatten(comment: string | ts.NodeArray<ts.JSDocComment> | undefined): string {\n        if (comment === undefined) {\n            return '';\n        }\n        if (typeof comment === 'string') {\n            return comment.trim();\n        }\n        const parts: string[] = [];\n        for (const part of comment) {\n            if (ts.isJSDocLink(part) || ts.isJSDocLinkCode(part) || ts.isJSDocLinkPlain(part)) {\n                // `text` is whatever followed the target ('|the widget'); the NAME is the target.\n                const label = part.text.replace(/^[|\\s]+/, '').trim();\n                const target = part.name ? part.name.getText() : '';\n                parts.push(label !== '' ? label : target);\n            } else {\n                parts.push(part.text);\n            }\n        }\n        return parts.join('').trim();\n    }\n}\n"]}

package/src/extract/TypeResolver.js

@@ -380,7 +380,7 @@ class TypeResolver {
         const min = this.numericArgument(member, MIN_DECORATOR);
         const max = this.numericArgument(member, MAX_DECORATOR);
         this.assertNumericConstraintsFit(member, name, type, min, max);
-        return new ApiDocModel_1.DocumentedField(name, type, optional, nullable, doc.description, doc.mcp, doc.format, min, max);
+        return new ApiDocModel_1.DocumentedField(name, type, optional, nullable, doc.description, doc.mcp, doc.format, min, max, doc.mcpHeader);
     }
     /**
      * `@WpMin` / `@WpMax` on a non-numeric field is a BUILD FAILURE, not a warning. A minimum on a