@webpieces/api-doc-model 0.4.807 → 0.4.809

package/package.json

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

package/src/extract/ApiDocExtractor.d.ts

@@ -90,15 +90,6 @@ export declare class ApiDocExtractor {
      * 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. */
@@ -125,6 +116,14 @@ export declare class ApiDocExtractor {
      * {@link DocumentedMcpTool}.
      */
     private static mcpToolOf;
+    /**
+     * `@InvalidEndpointForMcp('<reason>')`'s reason, or undefined.
+     *
+     * A reason that will not fold is read as the EMPTY STRING rather than as "no decorator": the
+     * method is still permanently outside MCP, and losing that fact because the argument was written
+     * as a cross-module constant would silently put the endpoint back in the candidate set.
+     */
+    private static invalidForMcpOf;
     /** `@MaskLog({ refreshToken: 'full' })` -> field name -> mask mode. */
     private static maskLogOf;
     private static booleanProperty;

package/src/extract/ApiDocExtractor.js

@@ -9,6 +9,7 @@ const ApiDocExtractionError_1 = require("./ApiDocExtractionError");
 const ConstantFolder_1 = require("./ConstantFolder");
 const JsDoc_1 = require("./JsDoc");
 const SourceLocation_1 = require("./SourceLocation");
+const McpMembership_1 = require("./McpMembership");
 const TypeResolver_1 = require("./TypeResolver");
 /**
  * The decorator names this extractor matches on, taken from the REAL SYMBOLS rather than re-typed as
@@ -38,6 +39,7 @@ 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_INVALID = core_util_1.InvalidEndpointForMcp.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;
@@ -171,7 +173,7 @@ class ApiDocExtractor {
                 endpoints.push(endpoint);
             }
         }
-        this.assertApiTypeMatchesMcpTools(contract, apiTypes, endpoints);
+        (0, McpMembership_1.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());
     }
     /**
@@ -243,7 +245,7 @@ class ApiDocExtractor {
         const literal = options !== undefined && ts.isObjectLiteralExpression(options) ? options : undefined;
         const doc = JsDoc_1.JsDoc.read(member);
         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));
+        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.invalidForMcpOf(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));
     }
     /**
      * One REQUIRED positional argument of `@Endpoint`, folded to the string it denotes.
@@ -287,27 +289,6 @@ class ApiDocExtractor {
         }
         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) {
         const parameter = member.parameters[0];
@@ -398,6 +379,22 @@ class ApiDocExtractor {
         }
         return new ApiDocModel_1.DocumentedMcpTool(folder.tryFoldString(argument) ?? '');
     }
+    /**
+     * `@InvalidEndpointForMcp('<reason>')`'s reason, or undefined.
+     *
+     * A reason that will not fold is read as the EMPTY STRING rather than as "no decorator": the
+     * method is still permanently outside MCP, and losing that fact because the argument was written
+     * as a cross-module constant would silently put the endpoint back in the candidate set.
+     */
+    // webpieces-disable no-function-outside-class -- private static reader of this class
+    static invalidForMcpOf(member, folder) {
+        const call = ApiDocExtractor.decoratorCall(member, MCP_INVALID);
+        if (call === undefined) {
+            return undefined;
+        }
+        const argument = call.arguments[0];
+        return argument === undefined ? '' : (folder.tryFoldString(argument) ?? '');
+    }
     /** `@MaskLog({ refreshToken: 'full' })` -> field name -> mask mode. */
     // webpieces-disable no-function-outside-class -- private static reader of this class
     static maskLogOf(member) {

package/src/extract/ApiDocExtractor.js.map

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

package/src/extract/McpMembership.d.ts

@@ -0,0 +1,19 @@
+import * as ts from 'typescript';
+import { DocumentedEndpoint } from '../model/ApiDocModel';
+/**
+ * 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.
+ *
+ * `@InvalidEndpointForMcp` (#1014) sits OUTSIDE the biconditional and is checked here too. A method
+ * declared permanently unusable as a tool is neither required to carry `@WpMcpTool` nor permitted
+ * to, and a contract whose every endpoint is so declared must not name MCP at all — the cure there
+ * is the opposite one, so it gets its own sentence rather than being folded into "no method carries
+ * @WpMcpTool".
+ *
+ * Split out of `ApiDocExtractor`, which owns the walk and is at its file-size limit.
+ */
+export declare function assertApiTypeMatchesMcpTools(contract: ts.ClassDeclaration, apiTypes: readonly string[], endpoints: readonly DocumentedEndpoint[]): void;

package/src/extract/McpMembership.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertApiTypeMatchesMcpTools = assertApiTypeMatchesMcpTools;
+const core_util_1 = require("@webpieces/core-util");
+const ApiDocExtractionError_1 = require("./ApiDocExtractionError");
+const SourceLocation_1 = require("./SourceLocation");
+/**
+ * The decorator names, taken from the REAL SYMBOLS for the reason `ApiDocExtractor`'s constants give
+ * at length: a literal that stops matching after a rename empties a document with the build green.
+ */
+const API_TYPE = core_util_1.ApiType.name;
+const MCP_TOOL = core_util_1.WpMcpTool.name;
+const MCP_INVALID = core_util_1.InvalidEndpointForMcp.name;
+/**
+ * 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.
+ *
+ * `@InvalidEndpointForMcp` (#1014) sits OUTSIDE the biconditional and is checked here too. A method
+ * declared permanently unusable as a tool is neither required to carry `@WpMcpTool` nor permitted
+ * to, and a contract whose every endpoint is so declared must not name MCP at all — the cure there
+ * is the opposite one, so it gets its own sentence rather than being folded into "no method carries
+ * @WpMcpTool".
+ *
+ * Split out of `ApiDocExtractor`, which owns the walk and is at its file-size limit.
+ */
+// webpieces-disable no-function-outside-class -- module entry point, mirrors the extractor's own split-out helpers
+function assertApiTypeMatchesMcpTools(contract, apiTypes, endpoints) {
+    const tools = endpoints.filter((e) => e.mcpTool !== undefined);
+    const excluded = endpoints.filter((e) => e.invalidForMcp !== undefined);
+    const declaresMcp = apiTypes.includes(core_util_1.MCP);
+    assertNoToolIsAlsoExcluded(contract, tools);
+    if (declaresMcp && tools.length === 0 && excluded.length === endpoints.length) {
+        throw new ApiDocExtractionError_1.ApiDocExtractionError(`@${API_TYPE} names MCP but EVERY endpoint is @${MCP_INVALID}`, SourceLocation_1.SourceLocation.of(contract), `Drop MCP from the @${API_TYPE} list — a contract whose every method is permanently ` +
+            'outside MCP does not feed the MCP document.');
+    }
+    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}('<stable_tool_name>') 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.');
+    }
+}
+/**
+ * `@WpMcpTool` and `@InvalidEndpointForMcp` on ONE method is a contradiction, not a precedence rule.
+ *
+ * Resolving it either way would make the pair a second spelling of a decision that already has one,
+ * and whichever way it resolved, half the readers of that method would be wrong about what it does.
+ */
+// webpieces-disable no-function-outside-class -- private assert of the entry point above, beside it
+function assertNoToolIsAlsoExcluded(contract, tools) {
+    const both = tools
+        .filter((e) => e.invalidForMcp !== undefined)
+        .map((e) => e.methodName);
+    if (both.length === 0)
+        return;
+    throw new ApiDocExtractionError_1.ApiDocExtractionError(`@${MCP_TOOL} and @${MCP_INVALID} are BOTH on ${both.join(', ')}`, SourceLocation_1.SourceLocation.of(contract), 'They contradict each other — one publishes the method to agents and the other declares it ' +
+        'permanently unusable as a tool. Delete whichever one is wrong.');
+}
+//# sourceMappingURL=McpMembership.js.map

package/src/extract/McpMembership.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpMembership.js","sourceRoot":"","sources":["../../../../../../packages/docs/api-doc-model/src/extract/McpMembership.ts"],"names":[],"mappings":";;AA+BA,oEAkCC;AAhED,oDAAsF;AAEtF,mEAAgE;AAChE,qDAAkD;AAElD;;;GAGG;AACH,MAAM,QAAQ,GAAG,mBAAO,CAAC,IAAI,CAAC;AAC9B,MAAM,QAAQ,GAAG,qBAAS,CAAC,IAAI,CAAC;AAChC,MAAM,WAAW,GAAG,iCAAqB,CAAC,IAAI,CAAC;AAE/C;;;;;;;;;;;;;;;GAeG;AACH,mHAAmH;AACnH,SAAgB,4BAA4B,CACxC,QAA6B,EAC7B,QAA2B,EAC3B,SAAwC;IAExC,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAqB,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC;IACnF,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAqB,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC;IAC5F,MAAM,WAAW,GAAG,QAAQ,CAAC,QAAQ,CAAC,eAAG,CAAC,CAAC;IAC3C,0BAA0B,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC5C,IAAI,WAAW,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS,CAAC,MAAM,EAAE,CAAC;QAC5E,MAAM,IAAI,6CAAqB,CAC3B,IAAI,QAAQ,qCAAqC,WAAW,EAAE,EAC9D,+BAAc,CAAC,EAAE,CAAC,QAAQ,CAAC,EAC3B,sBAAsB,QAAQ,uDAAuD;YACjF,6CAA6C,CACpD,CAAC;IACN,CAAC;IACD,IAAI,WAAW,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,6CAAqB,CAC3B,IAAI,QAAQ,qCAAqC,QAAQ,EAAE,EAC3D,+BAAc,CAAC,EAAE,CAAC,QAAQ,CAAC,EAC3B,QAAQ,QAAQ,qEAAqE;YACjF,aAAa,QAAQ,QAAQ,CACpC,CAAC;IACN,CAAC;IACD,IAAI,CAAC,WAAW,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAqB,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5E,MAAM,IAAI,6CAAqB,CAC3B,IAAI,QAAQ,UAAU,KAAK,SAAS,QAAQ,oBAAoB,EAChE,+BAAc,CAAC,EAAE,CAAC,QAAQ,CAAC,EAC3B,mBAAmB,QAAQ,sDAAsD;YAC7E,qEAAqE,CAC5E,CAAC;IACN,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,oGAAoG;AACpG,SAAS,0BAA0B,CAC/B,QAA6B,EAC7B,KAAoC;IAEpC,MAAM,IAAI,GAAG,KAAK;SACb,MAAM,CAAC,CAAC,CAAqB,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,KAAK,SAAS,CAAC;SAChE,GAAG,CAAC,CAAC,CAAqB,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IAClD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAC9B,MAAM,IAAI,6CAAqB,CAC3B,IAAI,QAAQ,SAAS,WAAW,gBAAgB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EACjE,+BAAc,CAAC,EAAE,CAAC,QAAQ,CAAC,EAC3B,4FAA4F;QACxF,gEAAgE,CACvE,CAAC;AACN,CAAC","sourcesContent":["import * as ts from 'typescript';\nimport { ApiType, InvalidEndpointForMcp, MCP, WpMcpTool } from '@webpieces/core-util';\nimport { DocumentedEndpoint } from '../model/ApiDocModel';\nimport { ApiDocExtractionError } from './ApiDocExtractionError';\nimport { SourceLocation } from './SourceLocation';\n\n/**\n * The decorator names, taken from the REAL SYMBOLS for the reason `ApiDocExtractor`'s constants give\n * at length: a literal that stops matching after a rename empties a document with the build green.\n */\nconst API_TYPE = ApiType.name;\nconst MCP_TOOL = WpMcpTool.name;\nconst MCP_INVALID = InvalidEndpointForMcp.name;\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 * `@InvalidEndpointForMcp` (#1014) sits OUTSIDE the biconditional and is checked here too. A method\n * declared permanently unusable as a tool is neither required to carry `@WpMcpTool` nor permitted\n * to, and a contract whose every endpoint is so declared must not name MCP at all — the cure there\n * is the opposite one, so it gets its own sentence rather than being folded into \"no method carries\n * @WpMcpTool\".\n *\n * Split out of `ApiDocExtractor`, which owns the walk and is at its file-size limit.\n */\n// webpieces-disable no-function-outside-class -- module entry point, mirrors the extractor's own split-out helpers\nexport function 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 excluded = endpoints.filter((e: DocumentedEndpoint) => e.invalidForMcp !== undefined);\n    const declaresMcp = apiTypes.includes(MCP);\n    assertNoToolIsAlsoExcluded(contract, tools);\n    if (declaresMcp && tools.length === 0 && excluded.length === endpoints.length) {\n        throw new ApiDocExtractionError(\n            `@${API_TYPE} names MCP but EVERY endpoint is @${MCP_INVALID}`,\n            SourceLocation.of(contract),\n            `Drop MCP from the @${API_TYPE} list — a contract whose every method is permanently ` +\n                'outside MCP does not feed the MCP document.',\n        );\n    }\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}('<stable_tool_name>') to the methods agents may call, or drop MCP ` +\n                `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/**\n * `@WpMcpTool` and `@InvalidEndpointForMcp` on ONE method is a contradiction, not a precedence rule.\n *\n * Resolving it either way would make the pair a second spelling of a decision that already has one,\n * and whichever way it resolved, half the readers of that method would be wrong about what it does.\n */\n// webpieces-disable no-function-outside-class -- private assert of the entry point above, beside it\nfunction assertNoToolIsAlsoExcluded(\n    contract: ts.ClassDeclaration,\n    tools: readonly DocumentedEndpoint[],\n): void {\n    const both = tools\n        .filter((e: DocumentedEndpoint) => e.invalidForMcp !== undefined)\n        .map((e: DocumentedEndpoint) => e.methodName);\n    if (both.length === 0) return;\n    throw new ApiDocExtractionError(\n        `@${MCP_TOOL} and @${MCP_INVALID} are BOTH on ${both.join(', ')}`,\n        SourceLocation.of(contract),\n        'They contradict each other — one publishes the method to agents and the other declares it ' +\n            'permanently unusable as a tool. Delete whichever one is wrong.',\n    );\n}\n"]}

package/src/extract/TypeResolver.js

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