@webpieces/api-doc-model 0.4.803 → 0.4.804

package/README.md

@@ -18,4 +18,4 @@ 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/api-doc-model",
-  "version": "0.4.803",
+  "version": "0.4.804",
   "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.804",
     "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
  *
@@ -38,17 +37,72 @@ export declare class ApiDocExtractor {
     extractFile(entryFile: string, compilerOptions?: ts.CompilerOptions): ApiDocModel;
     /** The same extraction against a program the caller already built. */
     extract(program: ts.Program, source: ts.SourceFile): ApiDocModel;
+    /**
+     * 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
  *
@@ -72,6 +127,7 @@ class ApiDocExtractor {
         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 +135,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 +196,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 +289,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 +297,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 +358,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

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    ApiDocModel,\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/** The decorator names this extractor reads, by NAME. It imports none of them — see the class doc. */\nconst API_PATH = 'ApiPath';\nconst ENDPOINT = 'Endpoint';\nconst MASK_LOG = 'MaskLog';\nconst MCP_TOOL = 'WpMcpTool';\nconst MCP_AUTH = 'WpMcpAuthJwt';\nconst AUTH_PREFIX = 'WpAuth';\n\n/** The MCP tool hints a renderer surfaces to an agent. */\nconst TOOL_HINTS = ['readOnly', 'destructive', 'idempotent', 'openWorld'];\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 NO webpieces package\n *\n * It depends on `typescript` and nothing else, so it can be pointed at ANY upstream project's\n * contract — which is the whole point of shipping it as a package rather than as a script in this\n * repo. Decorators are therefore matched BY NAME on the syntax, never by importing the real\n * decorator. One `@webpieces/core-util` import here would make the package unusable by anybody whose\n * webpieces version differs from ours, which is everybody.\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 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\n        return new ApiDocModel(\n            contract.name?.text ?? '<anonymous>',\n            basePath,\n            JsDoc.read(contract).description,\n            endpoints,\n            resolver.collectedTypes(),\n            resolver.collectedUnmapped(),\n        );\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        const pathArgument = call.arguments[0];\n        if (pathArgument === undefined) {\n            throw new ApiDocExtractionError(\n                `@Endpoint on '${methodName}' declares no path`,\n                SourceLocation.of(call),\n                \"Give it a path: @Endpoint('/thing', 'rpc').\",\n            );\n        }\n        const path = folder.foldString(pathArgument, `@Endpoint path on '${methodName}'`);\n\n        const kindArgument = call.arguments[1];\n        if (kindArgument === undefined) {\n            throw new ApiDocExtractionError(\n                `@Endpoint on '${methodName}' declares no kind`,\n                SourceLocation.of(call),\n                \"State what triggers it: 'rpc', 'cloudtasks', 'cron' or 'external'.\",\n            );\n        }\n        const kind = folder.foldString(kindArgument, `@Endpoint kind on '${methodName}'`);\n\n        const options = call.arguments[2];\n        const literal =\n            options !== undefined && ts.isObjectLiteralExpression(options) ? options : undefined;\n\n        const doc = JsDoc.read(member);\n        return new DocumentedEndpoint(\n            methodName,\n            path,\n            kind,\n            ApiDocExtractor.booleanProperty(literal, 'hidden'),\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),\n            ApiDocExtractor.mcpToolOf(member, folder),\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    /** 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): 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) && name !== MCP_AUTH) {\n                return new DocumentedAuth(name, call.arguments[0]?.getText());\n            }\n        }\n        return undefined;\n    }\n\n    /** `@WpMcpTool({ name, readOnly, ... })` — the name plus whichever hints were declared. */\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        const hints = new Map<string, boolean>();\n        for (const hint of TOOL_HINTS) {\n            const value = ApiDocExtractor.findProperty(argument, hint);\n            if (value !== undefined) {\n                hints.set(hint, value.kind === ts.SyntaxKind.TrueKeyword);\n            }\n        }\n        return new DocumentedMcpTool(\n            ApiDocExtractor.stringProperty(argument, 'name', folder) ?? '',\n            hints,\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    /** 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"]}