@webpieces/api-doc-model 0.4.803 → 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';
@@ -18,4 +20,19 @@ model.types; // ReadonlyMap<string, DocumentedType> — a renderer's $ref target
 model.unmapped; // UnmappedType[] — recorded, never dropped
 ```
 
-It depends on `typescript` and nothing else, so it can be pointed at any project's contract. See `responsibilities.md` for what is in and out of scope, why that dependency constraint is the product rather than tidiness, and why both `Integer` and `@WpInt()` are accepted spellings of integer-ness.
+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.803",
+  "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,6 +23,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@webpieces/core-util": "0.4.805",
     "typescript": "5.9.3"
   }
 }

package/src/extract/ApiDocExtractor.d.ts

@@ -12,13 +12,12 @@ import { ApiDocModel } from '../model/ApiDocModel';
  * made of, so the only place they exist is the source, and the only honest way to read the source is
  * the compiler.
  *
- * ## Why it imports NO webpieces package
+ * ## Why it IMPORTS `@webpieces/core-util`
  *
- * It depends on `typescript` and nothing else, so it can be pointed at ANY upstream project's
- * contract — which is the whole point of shipping it as a package rather than as a script in this
- * repo. Decorators are therefore matched BY NAME on the syntax, never by importing the real
- * decorator. One `@webpieces/core-util` import here would make the package unusable by anybody whose
- * webpieces version differs from ours, which is everybody.
+ * Decorators are matched BY NAME on the syntax — they must be, because this reads a contract and
+ * never executes it. The NAMES come from the real symbols (`Endpoint.name`), so a rename in
+ * `core-util` is a compile error here instead of a literal that quietly stops matching. The full
+ * argument, and why the import is not the coupling it looks like, is at those constants.
  *
  * ## What it does NOT do
  *
@@ -36,19 +35,93 @@ 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.
+     *
+     * This exists for a type nothing in a contract points at but a document still publishes — the
+     * document-wide error body a renderer's manifest names. Reading it with the SAME resolver is the
+     * point: a second reader would be a second answer to "what shape is this type", and the two
+     * would drift the first time a field changed.
+     *
+     * @throws ApiDocExtractionError when the file does not declare that name.
+     */
+    extractType(entryFile: string, typeName: string, compilerOptions?: ts.CompilerOptions): ApiDocModel;
+    /** The interface / class / type alias / enum declared under `name` at the file's top level. */
+    private static declarationNamed;
     /** The one `@ApiPath` class in the file. Zero is a hard failure; the FIRST wins if there are two. */
     private findContract;
     /** One `@Endpoint` method. Members without the decorator are not part of the contract. */
     private endpointOf;
+    /**
+     * One REQUIRED positional argument of `@Endpoint`, folded to the string it denotes.
+     *
+     * Every one of the four is an enum member (`POST`, `READ`, `RPC`) as often as it is a literal,
+     * and the folder resolves both — a document that printed `RPC` where the trigger goes would be
+     * worse than no document. A missing one is a hard failure naming the position, because the
+     * alternative is a document quietly missing a verb.
+     */
+    private requiredArgument;
+    /**
+     * `@ApiType(...)` on the contract, folded to the real values.
+     *
+     * A value that is not one of the three documents is a HARD FAILURE rather than a silent drop: a
+     * contract that named `CUSTOMER` by mistake would otherwise feed nothing, which looks exactly
+     * like a contract somebody deliberately kept internal.
+     */
+    private declaredApiTypes;
+    /**
+     * MCP membership has exactly ONE spelling, and this is the build-time half of enforcing it
+     * (`assertApiTypeMatchesMcpTools` in `@webpieces/core-util` is the wiring-time half).
+     *
+     * Declared in two places, the two can disagree — and the disagreement is invisible, because each
+     * declaration is individually valid. That is the defect this whole epic exists to remove, so it
+     * fails the DOCUMENT build rather than producing one that quietly lists the wrong tools.
+     */
+    private assertApiTypeMatchesMcpTools;
     /** The FIRST parameter's declared type. An endpoint with no parameter has no request document. */
     private requestOf;
     /** The declared return type, unwrapped from `Promise<...>` by the resolver. */
     private responseOf;
     /** `@WpAuthPublic()`, `@WpAuthJwt({...})`, … — recorded verbatim; this package rules on nothing. */
     private static authOf;
-    /** `@WpMcpTool({ name, readOnly, ... })` — the name plus whichever hints were declared. */
+    /**
+     * `@WpAuthApiKey(regime, [{in: 'header', name: 'x-api-key', description: '…'}, …])`, parsed.
+     *
+     * A malformed declaration FAILS rather than yielding a half-parsed regime: the credentials are
+     * what a published document's security block is made of, and a document that silently omitted
+     * one would tell a partner they need fewer credentials than the running hook demands.
+     */
+    private static apiKeyOf;
+    /** ONE `{ in: …, name?: …, description?: … }` credential. */
+    private static credentialOf;
+    /**
+     * `@WpMcpTool({ name, openWorldHint })` — the two facts the source cannot otherwise state.
+     *
+     * `description` is NOT read: the method's JSDoc is the description for the agent and the partner
+     * alike. The three side-effect hints are not read either — they are computed from the endpoint's
+     * `operation`. See {@link DocumentedMcpTool} for why both of those are deliberate.
+     */
     private static mcpToolOf;
     /** `@MaskLog({ refreshToken: 'full' })` -> field name -> mask mode. */
     private static maskLogOf;

package/src/extract/ApiDocExtractor.js

@@ -3,21 +3,77 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiDocExtractor = void 0;
 const tslib_1 = require("tslib");
 const ts = tslib_1.__importStar(require("typescript"));
+const core_util_1 = require("@webpieces/core-util");
 const ApiDocModel_1 = require("../model/ApiDocModel");
 const ApiDocExtractionError_1 = require("./ApiDocExtractionError");
 const ConstantFolder_1 = require("./ConstantFolder");
 const JsDoc_1 = require("./JsDoc");
 const SourceLocation_1 = require("./SourceLocation");
 const TypeResolver_1 = require("./TypeResolver");
-/** The decorator names this extractor reads, by NAME. It imports none of them — see the class doc. */
-const API_PATH = 'ApiPath';
-const ENDPOINT = 'Endpoint';
-const MASK_LOG = 'MaskLog';
-const MCP_TOOL = 'WpMcpTool';
-const MCP_AUTH = 'WpMcpAuthJwt';
+/**
+ * The decorator names this extractor matches on, taken from the REAL SYMBOLS rather than re-typed as
+ * string literals.
+ *
+ * ## Why `.name` and not `'Endpoint'`
+ *
+ * The extractor matches decorators by NAME on the syntax — it must, because it reads a contract with
+ * the compiler and never executes it. The question is only where that name comes from, and a literal
+ * has a silent failure mode that a symbol does not: rename `@WpMcpTool` in `core-util` and a literal
+ * simply stops matching. The extractor then finds zero MCP tools, the MCP document is correctly not
+ * written because it has no tools in it, and the BUILD IS GREEN. A partner-facing document silently
+ * loses a section with nothing red anywhere (issue #1001).
+ *
+ * `Endpoint.name` makes that rename a COMPILE ERROR here, which in this repo is the delivery
+ * mechanism for a migration rather than an obstacle to one: a compile break names the new spelling
+ * and an agent applies it in one pass, where a green build teaches nobody anything.
+ *
+ * ## Why importing `@webpieces/core-util` is not the coupling it looks like
+ *
+ * Any contract carrying `@Endpoint` already depends on `core-util` by definition, so there is no
+ * upstream project this import could shut out. It is build-time only, it creates no cycle, and it
+ * costs a browser bundle nothing because nothing in a bundle imports this package. The direction that
+ * WOULD be fatal is `core-util` depending on the TypeScript compiler, and that is not this.
+ */
+const API_PATH = core_util_1.ApiPath.name;
+const ENDPOINT = core_util_1.Endpoint.name;
+const MASK_LOG = core_util_1.MaskLog.name;
+const MCP_TOOL = core_util_1.WpMcpTool.name;
+const MCP_AUTH = core_util_1.WpMcpAuthJwt.name;
+const API_KEY_AUTH = core_util_1.WpAuthApiKey.name;
+const API_TYPE = core_util_1.ApiType.name;
+/**
+ * The prefix shared by every credential decorator. A PREFIX genuinely has no symbol to take a name
+ * from, so it stays a literal — but the set it selects is pinned below, which is what stops it
+ * quietly matching nothing.
+ */
 const AUTH_PREFIX = 'WpAuth';
-/** The MCP tool hints a renderer surfaces to an agent. */
-const TOOL_HINTS = ['readOnly', 'destructive', 'idempotent', 'openWorld'];
+/** Every credential decorator, by real symbol, so a rename of any of them fails to compile here. */
+const AUTH_DECORATORS = new Set([
+    core_util_1.WpAuthPublic.name,
+    core_util_1.WpAuthJwt.name,
+    core_util_1.WpAuthOidc.name,
+    core_util_1.WpAuthSharedSecret.name,
+    core_util_1.WpAuthWebhook.name,
+    core_util_1.WpAuthApiKey.name,
+    core_util_1.WpAuthLocalOnly.name,
+]);
+/** The REAL trigger kinds and side-effect contracts, so a contract cannot declare one that is not. */
+const ENDPOINT_KINDS = [core_util_1.RPC, core_util_1.CLOUDTASKS, core_util_1.CRON, core_util_1.EXTERNAL];
+const ENDPOINT_OPERATIONS = [core_util_1.READ, core_util_1.WRITE_IDEMPOTENT, core_util_1.WRITE];
+const HTTP_METHODS = [core_util_1.GET, core_util_1.POST];
+/** `@Endpoint`'s four required positions, named so a failure can say which one is missing. */
+const ARGUMENT_NAMES = ['http method', 'path', 'operation', 'trigger kind'];
+/** The allowed values of each required position, in the same order, for the same failure. */
+const ARGUMENT_VALUES = [
+    HTTP_METHODS,
+    [],
+    ENDPOINT_OPERATIONS,
+    ENDPOINT_KINDS,
+];
+/** The REAL document types, so a contract cannot name a document that does not exist. */
+const API_TYPES = [core_util_1.SVC_TO_SVC, core_util_1.EXTERNAL_CUSTOMER, core_util_1.MCP];
+/** The fail-closed default: a contract that declares nothing feeds only the internal document. */
+const DEFAULT_API_TYPES = [core_util_1.SVC_TO_SVC];
 /**
  * ONE contract file -> ONE {@link ApiDocModel}. The single extraction pass both the OpenAPI documents
  * and the MCP tool list (#982) are rendered from.
@@ -30,13 +86,12 @@ const TOOL_HINTS = ['readOnly', 'destructive', 'idempotent', 'openWorld'];
  * made of, so the only place they exist is the source, and the only honest way to read the source is
  * the compiler.
  *
- * ## Why it imports NO webpieces package
+ * ## Why it IMPORTS `@webpieces/core-util`
  *
- * It depends on `typescript` and nothing else, so it can be pointed at ANY upstream project's
- * contract — which is the whole point of shipping it as a package rather than as a script in this
- * repo. Decorators are therefore matched BY NAME on the syntax, never by importing the real
- * decorator. One `@webpieces/core-util` import here would make the package unusable by anybody whose
- * webpieces version differs from ours, which is everybody.
+ * Decorators are matched BY NAME on the syntax — they must be, because this reads a contract and
+ * never executes it. The NAMES come from the real symbols (`Endpoint.name`), so a rename in
+ * `core-util` is a compile error here instead of a literal that quietly stops matching. The full
+ * argument, and why the import is not the coupling it looks like, is at those constants.
  *
  * ## What it does NOT do
  *
@@ -61,17 +116,54 @@ 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
             ? ''
             : folder.foldString(basePathArgument, '@ApiPath argument');
+        const apiTypes = this.declaredApiTypes(contract, folder);
         const endpoints = [];
         for (const member of contract.members) {
             const endpoint = this.endpointOf(member, folder, resolver);
@@ -79,7 +171,46 @@ class ApiDocExtractor {
                 endpoints.push(endpoint);
             }
         }
-        return new ApiDocModel_1.ApiDocModel(contract.name?.text ?? '<anonymous>', basePath, JsDoc_1.JsDoc.read(contract).description, endpoints, resolver.collectedTypes(), resolver.collectedUnmapped());
+        this.assertApiTypeMatchesMcpTools(contract, apiTypes, endpoints);
+        return new ApiDocModel_1.ApiDocModel(contract.name?.text ?? '<anonymous>', apiTypes, basePath, JsDoc_1.JsDoc.read(contract).description, endpoints, resolver.collectedTypes(), resolver.collectedUnmapped());
+    }
+    /**
+     * Extract ONE named type and everything it reaches, from a file that holds NO contract.
+     *
+     * This exists for a type nothing in a contract points at but a document still publishes — the
+     * document-wide error body a renderer's manifest names. Reading it with the SAME resolver is the
+     * point: a second reader would be a second answer to "what shape is this type", and the two
+     * would drift the first time a field changed.
+     *
+     * @throws ApiDocExtractionError when the file does not declare that name.
+     */
+    extractType(entryFile, typeName, 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.');
+        }
+        const resolver = new TypeResolver_1.TypeResolver(program.getTypeChecker());
+        const declaration = ApiDocExtractor.declarationNamed(source, typeName);
+        if (declaration === undefined) {
+            throw new ApiDocExtractionError_1.ApiDocExtractionError(`no type named '${typeName}' is declared in this file`, entryFile, `Declare and export '${typeName}' there, or name the file that does.`);
+        }
+        resolver.resolveDeclaration(typeName, declaration, typeName);
+        return new ApiDocModel_1.ApiDocModel(typeName, DEFAULT_API_TYPES, '', '', [], resolver.collectedTypes(), resolver.collectedUnmapped());
+    }
+    /** The interface / class / type alias / enum declared under `name` at the file's top level. */
+    // webpieces-disable no-function-outside-class -- private static reader of this class
+    static declarationNamed(source, name) {
+        for (const statement of source.statements) {
+            const named = ts.isInterfaceDeclaration(statement) ||
+                ts.isClassDeclaration(statement) ||
+                ts.isTypeAliasDeclaration(statement) ||
+                ts.isEnumDeclaration(statement);
+            if (named && statement.name?.text === name) {
+                return statement;
+            }
+        }
+        return undefined;
     }
     /** The one `@ApiPath` class in the file. Zero is a hard failure; the FIRST wins if there are two. */
     findContract(source) {
@@ -101,20 +232,81 @@ class ApiDocExtractor {
             return undefined;
         }
         const methodName = member.name.text;
-        const pathArgument = call.arguments[0];
-        if (pathArgument === undefined) {
-            throw new ApiDocExtractionError_1.ApiDocExtractionError(`@Endpoint on '${methodName}' declares no path`, SourceLocation_1.SourceLocation.of(call), "Give it a path: @Endpoint('/thing', 'rpc').");
-        }
-        const path = folder.foldString(pathArgument, `@Endpoint path on '${methodName}'`);
-        const kindArgument = call.arguments[1];
-        if (kindArgument === undefined) {
-            throw new ApiDocExtractionError_1.ApiDocExtractionError(`@Endpoint on '${methodName}' declares no kind`, SourceLocation_1.SourceLocation.of(call), "State what triggers it: 'rpc', 'cloudtasks', 'cron' or 'external'.");
-        }
-        const kind = folder.foldString(kindArgument, `@Endpoint kind on '${methodName}'`);
-        const options = call.arguments[2];
+        // `@Endpoint(httpMethod, path, operation, kind, options?)` — METHOD-FIRST, five positions.
+        // The positions are read here and nowhere else, so the one place that has to change when the
+        // decorator changes is this block plus `ARGUMENT_NAMES` beside it.
+        const httpMethod = this.requiredArgument(call, methodName, 0, folder);
+        const path = this.requiredArgument(call, methodName, 1, folder);
+        const operation = this.requiredArgument(call, methodName, 2, folder);
+        const kind = this.requiredArgument(call, methodName, 3, folder);
+        const options = call.arguments[4];
         const literal = options !== undefined && ts.isObjectLiteralExpression(options) ? options : undefined;
         const doc = JsDoc_1.JsDoc.read(member);
-        return new ApiDocModel_1.DocumentedEndpoint(methodName, path, kind, ApiDocExtractor.booleanProperty(literal, 'hidden'), new ApiDocModel_1.DocumentedEndpointOptions(ApiDocExtractor.booleanProperty(literal, 'formPost'), ApiDocExtractor.stringProperty(literal, 'calledBy', folder), ApiDocExtractor.stringProperty(literal, 'callerKind', folder)), ApiDocExtractor.authOf(member), ApiDocExtractor.mcpToolOf(member, folder), ApiDocExtractor.decoratorCall(member, MCP_AUTH)?.arguments[0]?.getText(), ApiDocExtractor.maskLogOf(member), doc.description, doc.mcp, this.requestOf(member, methodName, resolver), this.responseOf(member, methodName, resolver));
+        const mcpTool = ApiDocExtractor.mcpToolOf(member, folder);
+        return new ApiDocModel_1.DocumentedEndpoint(methodName, httpMethod, path, operation, kind, ApiDocExtractor.booleanProperty(literal, 'hidden'), ApiDocExtractor.booleanProperty(literal, 'openWorld'), new ApiDocModel_1.DocumentedEndpointOptions(ApiDocExtractor.booleanProperty(literal, 'formPost'), ApiDocExtractor.stringProperty(literal, 'calledBy', folder), ApiDocExtractor.stringProperty(literal, 'callerKind', folder)), ApiDocExtractor.authOf(member, folder), mcpTool, ApiDocExtractor.decoratorCall(member, MCP_AUTH)?.arguments[0]?.getText(), ApiDocExtractor.maskLogOf(member), doc.description, doc.mcp, this.requestOf(member, methodName, resolver), this.responseOf(member, methodName, resolver));
+    }
+    /**
+     * One REQUIRED positional argument of `@Endpoint`, folded to the string it denotes.
+     *
+     * Every one of the four is an enum member (`POST`, `READ`, `RPC`) as often as it is a literal,
+     * and the folder resolves both — a document that printed `RPC` where the trigger goes would be
+     * worse than no document. A missing one is a hard failure naming the position, because the
+     * alternative is a document quietly missing a verb.
+     */
+    requiredArgument(call, methodName, index, folder) {
+        const argument = call.arguments[index];
+        const what = ARGUMENT_NAMES[index];
+        if (argument === undefined) {
+            throw new ApiDocExtractionError_1.ApiDocExtractionError(`@Endpoint on '${methodName}' declares no ${what}`, SourceLocation_1.SourceLocation.of(call), "Write all four: @Endpoint(POST, '/thing', READ, RPC).");
+        }
+        const value = folder.foldString(argument, `@Endpoint ${what} on '${methodName}'`);
+        const allowed = ARGUMENT_VALUES[index];
+        if (allowed.length > 0 && !allowed.includes(value)) {
+            throw new ApiDocExtractionError_1.ApiDocExtractionError(`@Endpoint on '${methodName}' declares ${what} '${value}', which is not one of ` +
+                allowed.join(', '), SourceLocation_1.SourceLocation.of(argument), `Use one of the exported constants: ${allowed.join(', ')}.`);
+        }
+        return value;
+    }
+    /**
+     * `@ApiType(...)` on the contract, folded to the real values.
+     *
+     * A value that is not one of the three documents is a HARD FAILURE rather than a silent drop: a
+     * contract that named `CUSTOMER` by mistake would otherwise feed nothing, which looks exactly
+     * like a contract somebody deliberately kept internal.
+     */
+    declaredApiTypes(node, folder) {
+        const call = ApiDocExtractor.decoratorCall(node, API_TYPE);
+        if (call === undefined) {
+            return DEFAULT_API_TYPES;
+        }
+        const declared = call.arguments.map((argument) => folder.foldString(argument, `@${API_TYPE} argument`));
+        for (const apiType of declared) {
+            if (!API_TYPES.includes(apiType)) {
+                throw new ApiDocExtractionError_1.ApiDocExtractionError(`@${API_TYPE} names '${apiType}', which is not a generated document`, SourceLocation_1.SourceLocation.of(call), `Use one of the exported constants: ${API_TYPES.join(', ')}.`);
+            }
+        }
+        return declared.length === 0 ? DEFAULT_API_TYPES : declared;
+    }
+    /**
+     * MCP membership has exactly ONE spelling, and this is the build-time half of enforcing it
+     * (`assertApiTypeMatchesMcpTools` in `@webpieces/core-util` is the wiring-time half).
+     *
+     * Declared in two places, the two can disagree — and the disagreement is invisible, because each
+     * declaration is individually valid. That is the defect this whole epic exists to remove, so it
+     * fails the DOCUMENT build rather than producing one that quietly lists the wrong tools.
+     */
+    assertApiTypeMatchesMcpTools(contract, apiTypes, endpoints) {
+        const tools = endpoints.filter((e) => e.mcpTool !== undefined);
+        const declaresMcp = apiTypes.includes(core_util_1.MCP);
+        if (declaresMcp && tools.length === 0) {
+            throw new ApiDocExtractionError_1.ApiDocExtractionError(`@${API_TYPE} names MCP but no method carries @${MCP_TOOL}`, SourceLocation_1.SourceLocation.of(contract), `Add @${MCP_TOOL}({name, description, openWorldHint}) to the methods agents may ` +
+                `call, or drop MCP from the @${API_TYPE} list.`);
+        }
+        if (!declaresMcp && tools.length > 0) {
+            const named = tools.map((e) => e.methodName).join(', ');
+            throw new ApiDocExtractionError_1.ApiDocExtractionError(`@${MCP_TOOL} is on ${named} but @${API_TYPE} does not name MCP`, SourceLocation_1.SourceLocation.of(contract), `Add MCP to the @${API_TYPE} list — membership has ONE spelling, so a tool on a ` +
+                'contract nobody published to agents is a contradiction, not a hint.');
+        }
     }
     /** The FIRST parameter's declared type. An endpoint with no parameter has no request document. */
     requestOf(member, methodName, resolver) {
@@ -133,7 +325,7 @@ class ApiDocExtractor {
     }
     /** `@WpAuthPublic()`, `@WpAuthJwt({...})`, … — recorded verbatim; this package rules on nothing. */
     // webpieces-disable no-function-outside-class -- private static reader of this class
-    static authOf(member) {
+    static authOf(member, folder) {
         const decorators = ts.canHaveDecorators(member) ? (ts.getDecorators(member) ?? []) : [];
         for (const decorator of decorators) {
             const call = decorator.expression;
@@ -141,13 +333,60 @@ class ApiDocExtractor {
                 continue;
             }
             const name = call.expression.text;
-            if (name.startsWith(AUTH_PREFIX) && name !== MCP_AUTH) {
-                return new ApiDocModel_1.DocumentedAuth(name, call.arguments[0]?.getText());
+            if (name.startsWith(AUTH_PREFIX) && AUTH_DECORATORS.has(name)) {
+                return new ApiDocModel_1.DocumentedAuth(name, call.arguments.map((argument) => argument.getText()), name === API_KEY_AUTH ? ApiDocExtractor.apiKeyOf(call, folder) : undefined);
             }
         }
         return undefined;
     }
-    /** `@WpMcpTool({ name, readOnly, ... })` — the name plus whichever hints were declared. */
+    /**
+     * `@WpAuthApiKey(regime, [{in: 'header', name: 'x-api-key', description: '…'}, …])`, parsed.
+     *
+     * A malformed declaration FAILS rather than yielding a half-parsed regime: the credentials are
+     * what a published document's security block is made of, and a document that silently omitted
+     * one would tell a partner they need fewer credentials than the running hook demands.
+     */
+    // webpieces-disable no-function-outside-class -- private static reader of this class
+    static apiKeyOf(call, folder) {
+        const regimeArgument = call.arguments[0];
+        const credentialsArgument = call.arguments[1];
+        if (regimeArgument === undefined || credentialsArgument === undefined) {
+            throw new ApiDocExtractionError_1.ApiDocExtractionError('@WpAuthApiKey needs a regime AND its credentials', SourceLocation_1.SourceLocation.of(call), "Write both: @WpAuthApiKey('partner', [{ in: 'header', name: 'x-api-key' }]).");
+        }
+        const regime = folder.foldString(regimeArgument, '@WpAuthApiKey regime');
+        // FOLLOW a name first: a credential list shared by every method of a contract is written
+        // once as a `const` and named per method, which is better source than a copy per method.
+        const credentialsLiteral = folder.follow(credentialsArgument);
+        if (!ts.isArrayLiteralExpression(credentialsLiteral)) {
+            throw new ApiDocExtractionError_1.ApiDocExtractionError('@WpAuthApiKey credentials is not an array literal', SourceLocation_1.SourceLocation.of(credentialsArgument), 'Write the credentials as an array literal, inline or in a `const`; a value ' +
+                'assembled at runtime cannot appear in a published security scheme.');
+        }
+        const credentials = [];
+        for (const element of credentialsLiteral.elements) {
+            credentials.push(ApiDocExtractor.credentialOf(element, folder));
+        }
+        return new ApiDocModel_1.DocumentedApiKey(regime, credentials);
+    }
+    /** ONE `{ in: …, name?: …, description?: … }` credential. */
+    // webpieces-disable no-function-outside-class -- private static reader of this class
+    static credentialOf(expression, folder) {
+        const element = folder.follow(expression);
+        if (!ts.isObjectLiteralExpression(element)) {
+            throw new ApiDocExtractionError_1.ApiDocExtractionError('an @WpAuthApiKey credential is not an object literal', SourceLocation_1.SourceLocation.of(element), "Write it inline: { in: 'header', name: 'x-api-key' }.");
+        }
+        const location = ApiDocExtractor.stringProperty(element, 'in', folder);
+        if (location === undefined) {
+            throw new ApiDocExtractionError_1.ApiDocExtractionError('an @WpAuthApiKey credential declares no `in`', SourceLocation_1.SourceLocation.of(element), "Say where it rides: `in: 'header'` with a name, or `in: 'bearer'`.");
+        }
+        return new ApiDocModel_1.DocumentedApiKeyCredential(location, ApiDocExtractor.stringProperty(element, 'name', folder), ApiDocExtractor.stringProperty(element, 'description', folder));
+    }
+    /**
+     * `@WpMcpTool({ name, openWorldHint })` — the two facts the source cannot otherwise state.
+     *
+     * `description` is NOT read: the method's JSDoc is the description for the agent and the partner
+     * alike. The three side-effect hints are not read either — they are computed from the endpoint's
+     * `operation`. See {@link DocumentedMcpTool} for why both of those are deliberate.
+     */
     // webpieces-disable no-function-outside-class -- private static reader of this class
     static mcpToolOf(member, folder) {
         const call = ApiDocExtractor.decoratorCall(member, MCP_TOOL);
@@ -155,14 +394,7 @@ class ApiDocExtractor {
         if (argument === undefined || !ts.isObjectLiteralExpression(argument)) {
             return undefined;
         }
-        const hints = new Map();
-        for (const hint of TOOL_HINTS) {
-            const value = ApiDocExtractor.findProperty(argument, hint);
-            if (value !== undefined) {
-                hints.set(hint, value.kind === ts.SyntaxKind.TrueKeyword);
-            }
-        }
-        return new ApiDocModel_1.DocumentedMcpTool(ApiDocExtractor.stringProperty(argument, 'name', folder) ?? '', hints);
+        return new ApiDocModel_1.DocumentedMcpTool(ApiDocExtractor.stringProperty(argument, 'name', folder) ?? '');
     }
     /** `@MaskLog({ refreshToken: 'full' })` -> field name -> mask mode. */
     // webpieces-disable no-function-outside-class -- private static reader of this class