@webpieces/nx-webpieces-rules 0.4.807 → 0.4.809

package/src/lib/api-usage/api-doc-rules-verdicts.js

@@ -0,0 +1,308 @@
+"use strict";
+/**
+ * The pure VERDICTS the api-contract rules print, split out of `api-doc-rules-scan.ts`, which owns
+ * the walk and is at its file-size limit.
+ *
+ * Nothing here touches the filesystem or the project graph. Each function answers one question about
+ * ONE declaration the extractor or the renderer has already ruled on, and turns it into the two
+ * halves every webpieces refusal carries — what is wrong, and what to do instead. The DECISION is
+ * never made here: `model.unmapped` is the extractor's and a render failure is the renderer's. What
+ * this file adds is the WORDING, which is the part a generic "no model representation for this type
+ * form" cannot give an author.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VOID_RPC_CURE = exports.ContractLines = exports.Verdict = exports.RPC_KIND = void 0;
+exports.unknownValueCure = unknownValueCure;
+exports.classifyUnmapped = classifyUnmapped;
+exports.carriesUnknown = carriesUnknown;
+exports.isVoidLike = isVoidLike;
+exports.toolFailures = toolFailures;
+exports.contractNamesIn = contractNamesIn;
+exports.contractLinesOf = contractLinesOf;
+const tslib_1 = require("tslib");
+const ts = tslib_1.__importStar(require("typescript"));
+const api_doc_model_1 = require("@webpieces/api-doc-model");
+/**
+ * The one trigger kind an MCP tool may have. A LITERAL, for the same reason `EndpointKind` beside it
+ * is one: this package deliberately does not depend on `@webpieces/core-util` at runtime, and the
+ * set the literal belongs to is pinned by that type.
+ */
+exports.RPC_KIND = 'rpc';
+/** The scalar keywords a MIXED SCALAR union is made of. */
+const SCALAR_KEYWORDS = new Set([
+    ts.SyntaxKind.StringKeyword,
+    ts.SyntaxKind.NumberKeyword,
+    ts.SyntaxKind.BooleanKeyword,
+]);
+/** ONE reason a declaration is refused, in the two halves every refusal prints. */
+class Verdict {
+    what;
+    cure;
+    constructor(what, cure) {
+        this.what = what;
+        this.cure = cure;
+    }
+}
+exports.Verdict = Verdict;
+/** Method name -> the line its declaration starts on, for one contract class. */
+class ContractLines {
+    classLine;
+    byMethod;
+    toolsWithoutEndpoint;
+    constructor(classLine, byMethod, 
+    /** Methods carrying `@WpMcpTool` that do NOT also carry `@Endpoint`. */
+    toolsWithoutEndpoint) {
+        this.classLine = classLine;
+        this.byMethod = byMethod;
+        this.toolsWithoutEndpoint = toolsWithoutEndpoint;
+    }
+    lineOf(methodName) {
+        return this.byMethod.get(methodName) ?? this.classLine;
+    }
+}
+exports.ContractLines = ContractLines;
+/**
+ * The cure for an `unknown` value, for whichever rule is REPORTING it.
+ *
+ * It takes the rule name rather than naming one, because this defect is shared: it blocks the
+ * OpenAPI document, so `DefectSink` routes it to `api-rules-for-openapi` when that rule is running
+ * and to `api-rules-for-mcp` when it is the only one. A hard-coded rule name would then hand an
+ * author, on the mcp-only configuration, a `// webpieces-disable api-rules-for-openapi` line that
+ * the collector reading the site does not look for — a cure that does not cure, which is the one
+ * failure mode a printed cure must not have.
+ */
+// webpieces-disable no-function-outside-class -- pure message builder, beside the verdicts that print it
+function unknownValueCure(rule) {
+    return ('Name the value type — a DTO, an array of one, a string-literal union, or ' +
+        'Record<string, ThatDto>. If the shape really is unknowable (a transport envelope, ' +
+        'arbitrary SQL rows), write the per-site disable and say so: ' +
+        `// webpieces-disable ${rule} -- <why this field is published with no shape>. ` +
+        'An existing no-any-unknown disable does NOT count — that rule asked whether the code is ' +
+        'type-safe, which is a different question from whether a partner is handed a shapeless field.');
+}
+/** The one cure for a `void` RPC. */
+exports.VOID_RPC_CURE = 'Declare a named response DTO and return Promise<That>, even when it has no fields today: an ' +
+    'empty object grows additively forever, and a void response cannot gain a field without ' +
+    'breaking every generated client. Promise<void> stays legal on a cloudtasks or cron endpoint, ' +
+    'where fire-and-forget is the contract.';
+/**
+ * Why the resolver could not map this type, said in the author's vocabulary.
+ *
+ * The DECISION to refuse is the extractor's and is not second-guessed here — every entry in
+ * `model.unmapped` becomes a defect. What this adds is the MESSAGE: an open enum and a mixed scalar
+ * union are the two shapes a real repo actually hits (measured: 6 of 98 endpoints, from exactly
+ * these two), and "no model representation for this type form" tells their author nothing.
+ */
+// webpieces-disable no-function-outside-class -- pure classifier over the extractor's own verdict
+function classifyUnmapped(unmapped) {
+    const branches = unionBranchesOf(unmapped.typeText);
+    if (isOpenEnum(branches)) {
+        return new Verdict(`'${unmapped.typeText}' is an OPEN ENUM — literals unioned with the wide type`, 'Use an enum OR a string, not both. TypeScript COLLAPSES this union to the wide type, ' +
+            'so the literals buy no compile-time safety and a document cannot state them as a ' +
+            "closed set. Either drop the `| string` (`'a' | 'b'` publishes as a real enum), or " +
+            'drop the literals and list the known values in the JSDoc.');
+    }
+    if (isMixedScalarUnion(branches)) {
+        return new Verdict(`'${unmapped.typeText}' is a MIXED SCALAR union`, 'Give the field ONE type. JSON Schema can spell {"type": ["string","number"]}, but ' +
+            'this framework\'s ApiJsonSchema helpers read a type array as "one real type plus ' +
+            'maybe null" (baseTypeOf returns the first non-null member), so publishing it ' +
+            'would VALIDATE WRONGLY — which is worse than refusing it. Pick the type, or wrap ' +
+            'the alternatives in a discriminated union of named objects.');
+    }
+    return new Verdict(`'${unmapped.typeText}' has no shape a document can state — ${unmapped.reason}`, 'Give it a type a document can carry: a named DTO, an array of one, a string-literal ' +
+        'union, a Record<string, ThatDto>, or a primitive. A field with no shape publishes as ' +
+        '"anything".');
+}
+/** The branches of `typeText` when it parses as a union, else an empty list. */
+// webpieces-disable no-function-outside-class -- pure parser used by classifyUnmapped alone
+function unionBranchesOf(typeText) {
+    const parsed = ts.createSourceFile('__unmapped.ts', `type __X = ${typeText};`, ts.ScriptTarget.Latest, true);
+    const alias = parsed.statements[0];
+    if (alias === undefined || !ts.isTypeAliasDeclaration(alias))
+        return [];
+    if (!ts.isUnionTypeNode(alias.type))
+        return [];
+    return alias.type.types.filter((branch) => !isNullishBranch(branch));
+}
+/** `'a' | 'b' | string`, and the numeric equivalent. See #1010 and the decision on #1011. */
+// webpieces-disable no-function-outside-class -- pure predicate beside classifyUnmapped
+function isOpenEnum(branches) {
+    const wide = branches.some((branch) => branch.kind === ts.SyntaxKind.StringKeyword ||
+        branch.kind === ts.SyntaxKind.NumberKeyword);
+    const literals = branches.some((branch) => ts.isLiteralTypeNode(branch));
+    return wide && literals;
+}
+/** `string | number`, `string | boolean | null` — two or more DIFFERENT scalar keywords. */
+// webpieces-disable no-function-outside-class -- pure predicate beside classifyUnmapped
+function isMixedScalarUnion(branches) {
+    if (branches.length < 2)
+        return false;
+    const kinds = new Set();
+    for (const branch of branches) {
+        if (!SCALAR_KEYWORDS.has(branch.kind))
+            return false;
+        kinds.add(branch.kind);
+    }
+    return kinds.size >= 2;
+}
+/** `null` / `undefined` branches — nullability, not composition, exactly as the resolver reads it. */
+// webpieces-disable no-function-outside-class -- pure predicate beside classifyUnmapped
+function isNullishBranch(node) {
+    if (node.kind === ts.SyntaxKind.UndefinedKeyword || node.kind === ts.SyntaxKind.NullKeyword) {
+        return true;
+    }
+    return ts.isLiteralTypeNode(node) && node.literal.kind === ts.SyntaxKind.NullKeyword;
+}
+/**
+ * True when this type PUBLISHES an `unknown` value.
+ *
+ * It looks at the VALUE TYPE wherever it sits — the item of an array, the value of an open map, the
+ * field itself — and never at the `Record<>` spelling, because the real cases in the wild are not
+ * all Records: `params?: unknown[]` is the same defect written differently.
+ *
+ * It does NOT descend through a `ref`: a named DTO is its own entry in the model and its own fields
+ * are judged there, so descending would report the same field once per type that points at it.
+ */
+// webpieces-disable no-function-outside-class -- pure predicate over one TypeRef
+function carriesUnknown(ref) {
+    if (ref.kind === 'primitive')
+        return ref.primitive === 'unknown';
+    if (ref.kind === 'array')
+        return carriesUnknown(ref.items);
+    if (ref.kind === 'openMap')
+        return carriesUnknown(ref.values);
+    return false;
+}
+/**
+ * `void`, `unknown` and `any` all reach the model as the same primitive — the resolver maps the
+ * three keywords onto one, because to a document they say the identical thing: nothing.
+ */
+// webpieces-disable no-function-outside-class -- pure predicate over one TypeRef
+function isVoidLike(ref) {
+    return ref.kind === 'primitive' && ref.primitive === 'unknown';
+}
+/**
+ * Every reason this tool could not be served, in the order `McpToolRegistry` asks them at boot —
+ * unique name, trigger kind, HTTP auth, MCP auth — and then the renderer's own verdict.
+ *
+ * The registry's four are restated from the model rather than driven, because they are decorator
+ * PRESENCE facts the model already carries verbatim; the SCHEMA question is the one with a real
+ * implementation behind it, and that one is driven.
+ */
+// webpieces-disable no-function-outside-class, max-lines-new-methods -- pure judge over one endpoint, and the four boot checks read as one list
+function toolFailures(endpoint, renderer, toolNames, model) {
+    const found = [];
+    const toolName = endpoint.mcpTool.name;
+    const claimed = toolNames.get(toolName);
+    if (claimed === undefined) {
+        toolNames.set(toolName, `${model.contractName}.${endpoint.methodName}`);
+    }
+    else {
+        found.push(new Verdict(`tool name '${toolName}' is already declared by ${claimed}`, 'Tool names are the protocol identity and are globally unique — rename one of the ' +
+            'two @WpMcpTool declarations.'));
+    }
+    if (endpoint.kind !== exports.RPC_KIND) {
+        found.push(new Verdict(`an MCP tool is declared on a '${endpoint.kind}' endpoint`, 'Only an RPC endpoint can be a tool — a cloudtasks, cron or external endpoint is ' +
+            'driven by something other than a caller. Make it RPC, or drop the @WpMcpTool.'));
+    }
+    if (endpoint.auth === undefined) {
+        found.push(new Verdict('an MCP tool declares no HTTP auth', 'Put a @WpAuth... decorator on the method. The MCP server refuses to boot without ' +
+            'one, because a tool with no credential is an unauthenticated endpoint an ' +
+            'agent can call.'));
+    }
+    if (endpoint.mcpAuthText === undefined) {
+        found.push(new Verdict('an MCP tool does not declare @WpMcpAuthJwt(...)', 'Add @WpMcpAuthJwt(...) beside the HTTP auth. MCP authorization is rechecked ' +
+            'before the endpoint boundary and is declared separately on purpose.'));
+    }
+    const rendered = renderFailure(renderer, endpoint);
+    if (rendered !== undefined)
+        found.push(rendered);
+    return found;
+}
+/**
+ * The renderer's own refusal for one tool, or undefined when it renders.
+ *
+ * This is the whole acceptance contract for the MCP half: "passes the rule" and "renders a tool" are
+ * the SAME statement, because the rule asks the renderer. It covers the method's missing JSDoc,
+ * every reachable DTO field's missing JSDoc, a request or response that is not a named object, a
+ * root-level union, a recursive DTO, an `unknown` leaf and a malformed `@mcpHeader` — none of which
+ * is restated here.
+ *
+ * One verdict per tool, because the renderer stops at the first thing it cannot draw. A tool blocked
+ * by several undocumented fields is therefore fixed a round at a time, which is the price of having
+ * exactly one definition of renderable rather than a second walk that could disagree with it.
+ */
+// webpieces-disable no-function-outside-class -- pure judge beside toolFailures
+function renderFailure(renderer, endpoint) {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- the render refusal IS the verdict
+    try {
+        renderer.tool(endpoint);
+        return undefined;
+    }
+    catch (err) {
+        //const error = toError(err);
+        if (!(err instanceof api_doc_model_1.McpRenderError))
+            throw err;
+        return new Verdict(`${err.message} — no MCP schema could be built`, err.cure);
+    }
+}
+/** Every `@ApiPath` class name declared at the top level of a file, in declaration order. */
+// webpieces-disable no-function-outside-class -- pure AST reader
+function contractNamesIn(source) {
+    const names = [];
+    for (const statement of source.statements) {
+        if (!ts.isClassDeclaration(statement) || statement.name === undefined)
+            continue;
+        if (hasDecoratorNamed(statement, 'ApiPath'))
+            names.push(statement.name.text);
+    }
+    return names;
+}
+/**
+ * Where each method of one contract starts, and which of them carry `@WpMcpTool` without
+ * `@Endpoint`.
+ *
+ * The line numbers exist because the MCP failures come from the RENDERER, whose location is a NAME
+ * (`Order.window`) rather than a file offset — it publishes a schema, not a diagnostic. Anchoring
+ * every tool failure at its METHOD is also where an author would write the disable: "this tool is
+ * deliberately not renderable" is a decision about the method, not about a field three DTOs down.
+ */
+// webpieces-disable no-function-outside-class -- pure AST reader beside contractNamesIn
+function contractLinesOf(source, contractName) {
+    for (const statement of source.statements) {
+        if (!ts.isClassDeclaration(statement) || statement.name?.text !== contractName)
+            continue;
+        const byMethod = new Map();
+        const orphanTools = [];
+        for (const member of statement.members) {
+            if (!ts.isMethodDeclaration(member) || !ts.isIdentifier(member.name))
+                continue;
+            byMethod.set(member.name.text, lineOf(source, member));
+            if (hasDecoratorNamed(member, 'WpMcpTool') && !hasDecoratorNamed(member, 'Endpoint')) {
+                orphanTools.push(member.name.text);
+            }
+        }
+        return new ContractLines(lineOf(source, statement), byMethod, orphanTools);
+    }
+    return new ContractLines(1, new Map(), []);
+}
+/** 1-based line of a node's first token, decorators excluded. */
+// webpieces-disable no-function-outside-class -- pure AST reader
+function lineOf(source, node) {
+    return source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
+}
+/** True when `node` carries `@name(...)`. Matched on the syntax, like every reader in this file. */
+// webpieces-disable no-function-outside-class -- pure AST reader
+function hasDecoratorNamed(node, name) {
+    const decorators = ts.canHaveDecorators(node) ? (ts.getDecorators(node) ?? []) : [];
+    for (const decorator of decorators) {
+        const call = decorator.expression;
+        if (ts.isCallExpression(call) &&
+            ts.isIdentifier(call.expression) &&
+            call.expression.text === name) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=api-doc-rules-verdicts.js.map

package/src/lib/api-usage/api-doc-rules-verdicts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-doc-rules-verdicts.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-usage/api-doc-rules-verdicts.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AA8DH,4CASC;AAkBD,4CA2BC;AA6DD,wCAKC;AAOD,gCAEC;AAWD,oCAmDC;AAiCD,0CAOC;AAYD,0CAeC;;AA9TD,uDAAiC;AACjC,4DAOkC;AAGlC;;;;GAIG;AACU,QAAA,QAAQ,GAAiB,KAAK,CAAC;AAE5C,2DAA2D;AAC3D,MAAM,eAAe,GAAG,IAAI,GAAG,CAAgB;IAC3C,EAAE,CAAC,UAAU,CAAC,aAAa;IAC3B,EAAE,CAAC,UAAU,CAAC,aAAa;IAC3B,EAAE,CAAC,UAAU,CAAC,cAAc;CAC/B,CAAC,CAAC;AAEH,mFAAmF;AACnF,MAAa,OAAO;IAEI;IACA;IAFpB,YACoB,IAAY,EACZ,IAAY;QADZ,SAAI,GAAJ,IAAI,CAAQ;QACZ,SAAI,GAAJ,IAAI,CAAQ;IAC7B,CAAC;CACP;AALD,0BAKC;AAGD,iFAAiF;AACjF,MAAa,aAAa;IAEF;IACA;IAEA;IAJpB,YACoB,SAAiB,EACjB,QAAqC;IACrD,wEAAwE;IACxD,oBAAuC;QAHvC,cAAS,GAAT,SAAS,CAAQ;QACjB,aAAQ,GAAR,QAAQ,CAA6B;QAErC,yBAAoB,GAApB,oBAAoB,CAAmB;IACxD,CAAC;IAEJ,MAAM,CAAC,UAAkB;QACrB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC;IAC3D,CAAC;CACJ;AAXD,sCAWC;AAGD;;;;;;;;;GASG;AACH,yGAAyG;AACzG,SAAgB,gBAAgB,CAAC,IAAY;IACzC,OAAO,CACH,2EAA2E;QAC3E,oFAAoF;QACpF,8DAA8D;QAC9D,wBAAwB,IAAI,mDAAmD;QAC/E,0FAA0F;QAC1F,8FAA8F,CACjG,CAAC;AACN,CAAC;AAED,qCAAqC;AACxB,QAAA,aAAa,GACtB,8FAA8F;IAC9F,yFAAyF;IACzF,+FAA+F;IAC/F,wCAAwC,CAAC;AAE7C;;;;;;;GAOG;AACH,kGAAkG;AAClG,SAAgB,gBAAgB,CAAC,QAAsB;IACnD,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACpD,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvB,OAAO,IAAI,OAAO,CACd,IAAI,QAAQ,CAAC,QAAQ,yDAAyD,EAC9E,uFAAuF;YACnF,mFAAmF;YACnF,oFAAoF;YACpF,2DAA2D,CAClE,CAAC;IACN,CAAC;IACD,IAAI,kBAAkB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC/B,OAAO,IAAI,OAAO,CACd,IAAI,QAAQ,CAAC,QAAQ,2BAA2B,EAChD,oFAAoF;YAChF,mFAAmF;YACnF,+EAA+E;YAC/E,mFAAmF;YACnF,6DAA6D,CACpE,CAAC;IACN,CAAC;IACD,OAAO,IAAI,OAAO,CACd,IAAI,QAAQ,CAAC,QAAQ,yCAAyC,QAAQ,CAAC,MAAM,EAAE,EAC/E,sFAAsF;QAClF,uFAAuF;QACvF,aAAa,CACpB,CAAC;AACN,CAAC;AAED,gFAAgF;AAChF,4FAA4F;AAC5F,SAAS,eAAe,CAAC,QAAgB;IACrC,MAAM,MAAM,GAAG,EAAE,CAAC,gBAAgB,CAC9B,eAAe,EACf,cAAc,QAAQ,GAAG,EACzB,EAAE,CAAC,YAAY,CAAC,MAAM,EACtB,IAAI,CACP,CAAC;IACF,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,EAAE,CAAC,sBAAsB,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACxE,IAAI,CAAC,EAAE,CAAC,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAC/C,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,MAAmB,EAAE,EAAE,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC;AACtF,CAAC;AAED,6FAA6F;AAC7F,wFAAwF;AACxF,SAAS,UAAU,CAAC,QAAgC;IAChD,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CACtB,CAAC,MAAmB,EAAE,EAAE,CACpB,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC,UAAU,CAAC,aAAa;QAC3C,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC,UAAU,CAAC,aAAa,CAClD,CAAC;IACF,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAmB,EAAE,EAAE,CAAC,EAAE,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;IACtF,OAAO,IAAI,IAAI,QAAQ,CAAC;AAC5B,CAAC;AAED,4FAA4F;AAC5F,wFAAwF;AACxF,SAAS,kBAAkB,CAAC,QAAgC;IACxD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAiB,CAAC;IACvC,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QACpD,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED,sGAAsG;AACtG,wFAAwF;AACxF,SAAS,eAAe,CAAC,IAAiB;IACtC,IAAI,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC,UAAU,CAAC,gBAAgB,IAAI,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC;QAC1F,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,OAAO,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC;AACzF,CAAC;AAED;;;;;;;;;GASG;AACH,iFAAiF;AACjF,SAAgB,cAAc,CAAC,GAAY;IACvC,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW;QAAE,OAAO,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC;IACjE,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,cAAc,CAAC,GAAG,CAAC,KAAM,CAAC,CAAC;IAC5D,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,cAAc,CAAC,GAAG,CAAC,MAAO,CAAC,CAAC;IAC/D,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,iFAAiF;AACjF,SAAgB,UAAU,CAAC,GAAY;IACnC,OAAO,GAAG,CAAC,IAAI,KAAK,WAAW,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC;AACnE,CAAC;AAED;;;;;;;GAOG;AACH,gJAAgJ;AAChJ,SAAgB,YAAY,CACxB,QAA4B,EAC5B,QAA2B,EAC3B,SAA8B,EAC9B,KAAkB;IAElB,MAAM,KAAK,GAAc,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAQ,CAAC,IAAI,CAAC;IACxC,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACxC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACxB,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,KAAK,CAAC,YAAY,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IAC5E,CAAC;SAAM,CAAC;QACJ,KAAK,CAAC,IAAI,CACN,IAAI,OAAO,CACP,cAAc,QAAQ,4BAA4B,OAAO,EAAE,EAC3D,mFAAmF;YAC/E,8BAA8B,CACrC,CACJ,CAAC;IACN,CAAC;IACD,IAAI,QAAQ,CAAC,IAAI,KAAK,gBAAQ,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CACN,IAAI,OAAO,CACP,iCAAiC,QAAQ,CAAC,IAAI,YAAY,EAC1D,kFAAkF;YAC9E,+EAA+E,CACtF,CACJ,CAAC;IACN,CAAC;IACD,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,KAAK,CAAC,IAAI,CACN,IAAI,OAAO,CACP,mCAAmC,EACnC,mFAAmF;YAC/E,2EAA2E;YAC3E,iBAAiB,CACxB,CACJ,CAAC;IACN,CAAC;IACD,IAAI,QAAQ,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACrC,KAAK,CAAC,IAAI,CACN,IAAI,OAAO,CACP,iDAAiD,EACjD,8EAA8E;YAC1E,qEAAqE,CAC5E,CACJ,CAAC;IACN,CAAC;IACD,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACnD,IAAI,QAAQ,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACjD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,gFAAgF;AAChF,SAAS,aAAa,CAClB,QAA2B,EAC3B,QAA4B;IAE5B,mGAAmG;IACnG,IAAI,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACxB,OAAO,SAAS,CAAC;IACrB,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,6BAA6B;QAC7B,IAAI,CAAC,CAAC,GAAG,YAAY,8BAAc,CAAC;YAAE,MAAM,GAAG,CAAC;QAChD,OAAO,IAAI,OAAO,CAAC,GAAG,GAAG,CAAC,OAAO,iCAAiC,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IAClF,CAAC;AACL,CAAC;AAED,6FAA6F;AAC7F,iEAAiE;AACjE,SAAgB,eAAe,CAAC,MAAqB;IACjD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACxC,IAAI,CAAC,EAAE,CAAC,kBAAkB,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS;YAAE,SAAS;QAChF,IAAI,iBAAiB,CAAC,SAAS,EAAE,SAAS,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;;;;;GAQG;AACH,wFAAwF;AACxF,SAAgB,eAAe,CAAC,MAAqB,EAAE,YAAoB;IACvE,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACxC,IAAI,CAAC,EAAE,CAAC,kBAAkB,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC,IAAI,EAAE,IAAI,KAAK,YAAY;YAAE,SAAS;QACzF,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;QAC3C,MAAM,WAAW,GAAa,EAAE,CAAC;QACjC,KAAK,MAAM,MAAM,IAAI,SAAS,CAAC,OAAO,EAAE,CAAC;YACrC,IAAI,CAAC,EAAE,CAAC,mBAAmB,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC;gBAAE,SAAS;YAC/E,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;YACvD,IAAI,iBAAiB,CAAC,MAAM,EAAE,WAAW,CAAC,IAAI,CAAC,iBAAiB,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,CAAC;gBACnF,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACvC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,IAAI,aAAa,CAAC,CAAC,EAAE,IAAI,GAAG,EAAkB,EAAE,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED,iEAAiE;AACjE,iEAAiE;AACjE,SAAS,MAAM,CAAC,MAAqB,EAAE,IAAa;IAChD,OAAO,MAAM,CAAC,6BAA6B,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;AAChF,CAAC;AAED,oGAAoG;AACpG,iEAAiE;AACjE,SAAS,iBAAiB,CAAC,IAAa,EAAE,IAAY;IAClD,MAAM,UAAU,GAAG,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACpF,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,SAAS,CAAC,UAAU,CAAC;QAClC,IACI,EAAE,CAAC,gBAAgB,CAAC,IAAI,CAAC;YACzB,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC;YAChC,IAAI,CAAC,UAAU,CAAC,IAAI,KAAK,IAAI,EAC/B,CAAC;YACC,OAAO,IAAI,CAAC;QAChB,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC","sourcesContent":["/**\n * The pure VERDICTS the api-contract rules print, split out of `api-doc-rules-scan.ts`, which owns\n * the walk and is at its file-size limit.\n *\n * Nothing here touches the filesystem or the project graph. Each function answers one question about\n * ONE declaration the extractor or the renderer has already ruled on, and turns it into the two\n * halves every webpieces refusal carries — what is wrong, and what to do instead. The DECISION is\n * never made here: `model.unmapped` is the extractor's and a render failure is the renderer's. What\n * this file adds is the WORDING, which is the part a generic \"no model representation for this type\n * form\" cannot give an author.\n */\n\nimport * as ts from 'typescript';\nimport {\n    ApiDocModel,\n    DocumentedEndpoint,\n    McpRenderError,\n    McpSchemaRenderer,\n    TypeRef,\n    UnmappedType,\n} from '@webpieces/api-doc-model';\nimport { EndpointKind } from './api-relations';\n\n/**\n * The one trigger kind an MCP tool may have. A LITERAL, for the same reason `EndpointKind` beside it\n * is one: this package deliberately does not depend on `@webpieces/core-util` at runtime, and the\n * set the literal belongs to is pinned by that type.\n */\nexport const RPC_KIND: EndpointKind = 'rpc';\n\n/** The scalar keywords a MIXED SCALAR union is made of. */\nconst SCALAR_KEYWORDS = new Set<ts.SyntaxKind>([\n    ts.SyntaxKind.StringKeyword,\n    ts.SyntaxKind.NumberKeyword,\n    ts.SyntaxKind.BooleanKeyword,\n]);\n\n/** ONE reason a declaration is refused, in the two halves every refusal prints. */\nexport class Verdict {\n    constructor(\n        public readonly what: string,\n        public readonly cure: string,\n    ) {}\n}\n\n\n/** Method name -> the line its declaration starts on, for one contract class. */\nexport class ContractLines {\n    constructor(\n        public readonly classLine: number,\n        public readonly byMethod: ReadonlyMap<string, number>,\n        /** Methods carrying `@WpMcpTool` that do NOT also carry `@Endpoint`. */\n        public readonly toolsWithoutEndpoint: readonly string[],\n    ) {}\n\n    lineOf(methodName: string): number {\n        return this.byMethod.get(methodName) ?? this.classLine;\n    }\n}\n\n\n/**\n * The cure for an `unknown` value, for whichever rule is REPORTING it.\n *\n * It takes the rule name rather than naming one, because this defect is shared: it blocks the\n * OpenAPI document, so `DefectSink` routes it to `api-rules-for-openapi` when that rule is running\n * and to `api-rules-for-mcp` when it is the only one. A hard-coded rule name would then hand an\n * author, on the mcp-only configuration, a `// webpieces-disable api-rules-for-openapi` line that\n * the collector reading the site does not look for — a cure that does not cure, which is the one\n * failure mode a printed cure must not have.\n */\n// webpieces-disable no-function-outside-class -- pure message builder, beside the verdicts that print it\nexport function unknownValueCure(rule: string): string {\n    return (\n        'Name the value type — a DTO, an array of one, a string-literal union, or ' +\n        'Record<string, ThatDto>. If the shape really is unknowable (a transport envelope, ' +\n        'arbitrary SQL rows), write the per-site disable and say so: ' +\n        `// webpieces-disable ${rule} -- <why this field is published with no shape>. ` +\n        'An existing no-any-unknown disable does NOT count — that rule asked whether the code is ' +\n        'type-safe, which is a different question from whether a partner is handed a shapeless field.'\n    );\n}\n\n/** The one cure for a `void` RPC. */\nexport const VOID_RPC_CURE =\n    'Declare a named response DTO and return Promise<That>, even when it has no fields today: an ' +\n    'empty object grows additively forever, and a void response cannot gain a field without ' +\n    'breaking every generated client. Promise<void> stays legal on a cloudtasks or cron endpoint, ' +\n    'where fire-and-forget is the contract.';\n\n/**\n * Why the resolver could not map this type, said in the author's vocabulary.\n *\n * The DECISION to refuse is the extractor's and is not second-guessed here — every entry in\n * `model.unmapped` becomes a defect. What this adds is the MESSAGE: an open enum and a mixed scalar\n * union are the two shapes a real repo actually hits (measured: 6 of 98 endpoints, from exactly\n * these two), and \"no model representation for this type form\" tells their author nothing.\n */\n// webpieces-disable no-function-outside-class -- pure classifier over the extractor's own verdict\nexport function classifyUnmapped(unmapped: UnmappedType): Verdict {\n    const branches = unionBranchesOf(unmapped.typeText);\n    if (isOpenEnum(branches)) {\n        return new Verdict(\n            `'${unmapped.typeText}' is an OPEN ENUM — literals unioned with the wide type`,\n            'Use an enum OR a string, not both. TypeScript COLLAPSES this union to the wide type, ' +\n                'so the literals buy no compile-time safety and a document cannot state them as a ' +\n                \"closed set. Either drop the `| string` (`'a' | 'b'` publishes as a real enum), or \" +\n                'drop the literals and list the known values in the JSDoc.',\n        );\n    }\n    if (isMixedScalarUnion(branches)) {\n        return new Verdict(\n            `'${unmapped.typeText}' is a MIXED SCALAR union`,\n            'Give the field ONE type. JSON Schema can spell {\"type\": [\"string\",\"number\"]}, but ' +\n                'this framework\\'s ApiJsonSchema helpers read a type array as \"one real type plus ' +\n                'maybe null\" (baseTypeOf returns the first non-null member), so publishing it ' +\n                'would VALIDATE WRONGLY — which is worse than refusing it. Pick the type, or wrap ' +\n                'the alternatives in a discriminated union of named objects.',\n        );\n    }\n    return new Verdict(\n        `'${unmapped.typeText}' has no shape a document can state — ${unmapped.reason}`,\n        'Give it a type a document can carry: a named DTO, an array of one, a string-literal ' +\n            'union, a Record<string, ThatDto>, or a primitive. A field with no shape publishes as ' +\n            '\"anything\".',\n    );\n}\n\n/** The branches of `typeText` when it parses as a union, else an empty list. */\n// webpieces-disable no-function-outside-class -- pure parser used by classifyUnmapped alone\nfunction unionBranchesOf(typeText: string): readonly ts.TypeNode[] {\n    const parsed = ts.createSourceFile(\n        '__unmapped.ts',\n        `type __X = ${typeText};`,\n        ts.ScriptTarget.Latest,\n        true,\n    );\n    const alias = parsed.statements[0];\n    if (alias === undefined || !ts.isTypeAliasDeclaration(alias)) return [];\n    if (!ts.isUnionTypeNode(alias.type)) return [];\n    return alias.type.types.filter((branch: ts.TypeNode) => !isNullishBranch(branch));\n}\n\n/** `'a' | 'b' | string`, and the numeric equivalent. See #1010 and the decision on #1011. */\n// webpieces-disable no-function-outside-class -- pure predicate beside classifyUnmapped\nfunction isOpenEnum(branches: readonly ts.TypeNode[]): boolean {\n    const wide = branches.some(\n        (branch: ts.TypeNode) =>\n            branch.kind === ts.SyntaxKind.StringKeyword ||\n            branch.kind === ts.SyntaxKind.NumberKeyword,\n    );\n    const literals = branches.some((branch: ts.TypeNode) => ts.isLiteralTypeNode(branch));\n    return wide && literals;\n}\n\n/** `string | number`, `string | boolean | null` — two or more DIFFERENT scalar keywords. */\n// webpieces-disable no-function-outside-class -- pure predicate beside classifyUnmapped\nfunction isMixedScalarUnion(branches: readonly ts.TypeNode[]): boolean {\n    if (branches.length < 2) return false;\n    const kinds = new Set<ts.SyntaxKind>();\n    for (const branch of branches) {\n        if (!SCALAR_KEYWORDS.has(branch.kind)) return false;\n        kinds.add(branch.kind);\n    }\n    return kinds.size >= 2;\n}\n\n/** `null` / `undefined` branches — nullability, not composition, exactly as the resolver reads it. */\n// webpieces-disable no-function-outside-class -- pure predicate beside classifyUnmapped\nfunction isNullishBranch(node: ts.TypeNode): boolean {\n    if (node.kind === ts.SyntaxKind.UndefinedKeyword || node.kind === ts.SyntaxKind.NullKeyword) {\n        return true;\n    }\n    return ts.isLiteralTypeNode(node) && node.literal.kind === ts.SyntaxKind.NullKeyword;\n}\n\n/**\n * True when this type PUBLISHES an `unknown` value.\n *\n * It looks at the VALUE TYPE wherever it sits — the item of an array, the value of an open map, the\n * field itself — and never at the `Record<>` spelling, because the real cases in the wild are not\n * all Records: `params?: unknown[]` is the same defect written differently.\n *\n * It does NOT descend through a `ref`: a named DTO is its own entry in the model and its own fields\n * are judged there, so descending would report the same field once per type that points at it.\n */\n// webpieces-disable no-function-outside-class -- pure predicate over one TypeRef\nexport function carriesUnknown(ref: TypeRef): boolean {\n    if (ref.kind === 'primitive') return ref.primitive === 'unknown';\n    if (ref.kind === 'array') return carriesUnknown(ref.items!);\n    if (ref.kind === 'openMap') return carriesUnknown(ref.values!);\n    return false;\n}\n\n/**\n * `void`, `unknown` and `any` all reach the model as the same primitive — the resolver maps the\n * three keywords onto one, because to a document they say the identical thing: nothing.\n */\n// webpieces-disable no-function-outside-class -- pure predicate over one TypeRef\nexport function isVoidLike(ref: TypeRef): boolean {\n    return ref.kind === 'primitive' && ref.primitive === 'unknown';\n}\n\n/**\n * Every reason this tool could not be served, in the order `McpToolRegistry` asks them at boot —\n * unique name, trigger kind, HTTP auth, MCP auth — and then the renderer's own verdict.\n *\n * The registry's four are restated from the model rather than driven, because they are decorator\n * PRESENCE facts the model already carries verbatim; the SCHEMA question is the one with a real\n * implementation behind it, and that one is driven.\n */\n// webpieces-disable no-function-outside-class, max-lines-new-methods -- pure judge over one endpoint, and the four boot checks read as one list\nexport function toolFailures(\n    endpoint: DocumentedEndpoint,\n    renderer: McpSchemaRenderer,\n    toolNames: Map<string, string>,\n    model: ApiDocModel,\n): readonly Verdict[] {\n    const found: Verdict[] = [];\n    const toolName = endpoint.mcpTool!.name;\n    const claimed = toolNames.get(toolName);\n    if (claimed === undefined) {\n        toolNames.set(toolName, `${model.contractName}.${endpoint.methodName}`);\n    } else {\n        found.push(\n            new Verdict(\n                `tool name '${toolName}' is already declared by ${claimed}`,\n                'Tool names are the protocol identity and are globally unique — rename one of the ' +\n                    'two @WpMcpTool declarations.',\n            ),\n        );\n    }\n    if (endpoint.kind !== RPC_KIND) {\n        found.push(\n            new Verdict(\n                `an MCP tool is declared on a '${endpoint.kind}' endpoint`,\n                'Only an RPC endpoint can be a tool — a cloudtasks, cron or external endpoint is ' +\n                    'driven by something other than a caller. Make it RPC, or drop the @WpMcpTool.',\n            ),\n        );\n    }\n    if (endpoint.auth === undefined) {\n        found.push(\n            new Verdict(\n                'an MCP tool declares no HTTP auth',\n                'Put a @WpAuth... decorator on the method. The MCP server refuses to boot without ' +\n                    'one, because a tool with no credential is an unauthenticated endpoint an ' +\n                    'agent can call.',\n            ),\n        );\n    }\n    if (endpoint.mcpAuthText === undefined) {\n        found.push(\n            new Verdict(\n                'an MCP tool does not declare @WpMcpAuthJwt(...)',\n                'Add @WpMcpAuthJwt(...) beside the HTTP auth. MCP authorization is rechecked ' +\n                    'before the endpoint boundary and is declared separately on purpose.',\n            ),\n        );\n    }\n    const rendered = renderFailure(renderer, endpoint);\n    if (rendered !== undefined) found.push(rendered);\n    return found;\n}\n\n/**\n * The renderer's own refusal for one tool, or undefined when it renders.\n *\n * This is the whole acceptance contract for the MCP half: \"passes the rule\" and \"renders a tool\" are\n * the SAME statement, because the rule asks the renderer. It covers the method's missing JSDoc,\n * every reachable DTO field's missing JSDoc, a request or response that is not a named object, a\n * root-level union, a recursive DTO, an `unknown` leaf and a malformed `@mcpHeader` — none of which\n * is restated here.\n *\n * One verdict per tool, because the renderer stops at the first thing it cannot draw. A tool blocked\n * by several undocumented fields is therefore fixed a round at a time, which is the price of having\n * exactly one definition of renderable rather than a second walk that could disagree with it.\n */\n// webpieces-disable no-function-outside-class -- pure judge beside toolFailures\nfunction renderFailure(\n    renderer: McpSchemaRenderer,\n    endpoint: DocumentedEndpoint,\n): Verdict | undefined {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- the render refusal IS the verdict\n    try {\n        renderer.tool(endpoint);\n        return undefined;\n    } catch (err: unknown) {\n        //const error = toError(err);\n        if (!(err instanceof McpRenderError)) throw err;\n        return new Verdict(`${err.message} — no MCP schema could be built`, err.cure);\n    }\n}\n\n/** Every `@ApiPath` class name declared at the top level of a file, in declaration order. */\n// webpieces-disable no-function-outside-class -- pure AST reader\nexport function contractNamesIn(source: ts.SourceFile): string[] {\n    const names: string[] = [];\n    for (const statement of source.statements) {\n        if (!ts.isClassDeclaration(statement) || statement.name === undefined) continue;\n        if (hasDecoratorNamed(statement, 'ApiPath')) names.push(statement.name.text);\n    }\n    return names;\n}\n\n/**\n * Where each method of one contract starts, and which of them carry `@WpMcpTool` without\n * `@Endpoint`.\n *\n * The line numbers exist because the MCP failures come from the RENDERER, whose location is a NAME\n * (`Order.window`) rather than a file offset — it publishes a schema, not a diagnostic. Anchoring\n * every tool failure at its METHOD is also where an author would write the disable: \"this tool is\n * deliberately not renderable\" is a decision about the method, not about a field three DTOs down.\n */\n// webpieces-disable no-function-outside-class -- pure AST reader beside contractNamesIn\nexport function contractLinesOf(source: ts.SourceFile, contractName: string): ContractLines {\n    for (const statement of source.statements) {\n        if (!ts.isClassDeclaration(statement) || statement.name?.text !== contractName) continue;\n        const byMethod = new Map<string, number>();\n        const orphanTools: string[] = [];\n        for (const member of statement.members) {\n            if (!ts.isMethodDeclaration(member) || !ts.isIdentifier(member.name)) continue;\n            byMethod.set(member.name.text, lineOf(source, member));\n            if (hasDecoratorNamed(member, 'WpMcpTool') && !hasDecoratorNamed(member, 'Endpoint')) {\n                orphanTools.push(member.name.text);\n            }\n        }\n        return new ContractLines(lineOf(source, statement), byMethod, orphanTools);\n    }\n    return new ContractLines(1, new Map<string, number>(), []);\n}\n\n/** 1-based line of a node's first token, decorators excluded. */\n// webpieces-disable no-function-outside-class -- pure AST reader\nfunction lineOf(source: ts.SourceFile, node: ts.Node): number {\n    return source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;\n}\n\n/** True when `node` carries `@name(...)`. Matched on the syntax, like every reader in this file. */\n// webpieces-disable no-function-outside-class -- pure AST reader\nfunction hasDecoratorNamed(node: ts.Node, name: string): boolean {\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 === name\n        ) {\n            return true;\n        }\n    }\n    return false;\n}\n"]}

package/src/lib/api-usage/api-doc-rules.d.ts

@@ -0,0 +1,149 @@
+/**
+ * The DATA and the SWITCHES of `api-rules-for-openapi` and `api-rules-for-mcp` (#1011).
+ *
+ * The scan itself is in `api-doc-rules-scan.ts`; this file holds what a caller reads back and the
+ * per-rule config, so a unit test can construct either without touching a config file and so the
+ * config is read exactly once per executor run.
+ */
+/** As written in a disable comment and as a config key. */
+export declare const OPENAPI_RULE: "api-rules-for-openapi";
+export declare const MCP_RULE: "api-rules-for-mcp";
+/** The `@ApiType` value that means "a partner reads this document". */
+export declare const EXTERNAL_CUSTOMER_API_TYPE = "external-customer";
+/**
+ * ONE defect on ONE contract.
+ *
+ * `exposure` is the contract's `@ApiType` list, and it is carried rather than derived because the
+ * SAME defect is louder on a contract that reaches `external-customer`: an unshaped field on a
+ * partner document costs a partner something, where the same field on a service-to-service contract
+ * costs a colleague a question. The refusal sorts and labels on it.
+ */
+export declare class ApiContractDefect {
+    /** The `@ApiPath` contract class. */
+    readonly api: string;
+    /** The `@Endpoint` method, or `''` for a contract-level or DTO-level defect. */
+    readonly method: string;
+    /** What is wrong, in one line, naming the declaration. */
+    readonly what: string;
+    /** `path/to/File.ts:LINE`, workspace-relative. */
+    readonly at: string;
+    /** What to do instead, in one sentence. */
+    readonly cure: string;
+    /** The contract's `@ApiType` list — `svc-to-svc` when it declares none. */
+    readonly exposure: readonly string[];
+    constructor(
+    /** The `@ApiPath` contract class. */
+    api: string, 
+    /** The `@Endpoint` method, or `''` for a contract-level or DTO-level defect. */
+    method: string, 
+    /** What is wrong, in one line, naming the declaration. */
+    what: string, 
+    /** `path/to/File.ts:LINE`, workspace-relative. */
+    at: string, 
+    /** What to do instead, in one sentence. */
+    cure: string, 
+    /** The contract's `@ApiType` list — `svc-to-svc` when it declares none. */
+    exposure: readonly string[]);
+    /** True when this contract feeds the PARTNER-facing document. */
+    isExternal(): boolean;
+    /** `Api.method` or `Api` — what a reader opens. */
+    where(): string;
+}
+/** What ONE rule found: real defects, and disables of it that gave no reason. */
+export declare class ApiRuleFindings {
+    readonly violations: readonly ApiContractDefect[];
+    /**
+     * Sites that named this rule in a disable and wrote no reason. A reasonless disable is
+     * itself a violation: the point of the per-site hatch is the ARGUMENT, which is the only
+     * part the next reader can weigh.
+     */
+    readonly reasonlessDisables: readonly ApiContractDefect[];
+    constructor(violations: readonly ApiContractDefect[], 
+    /**
+     * Sites that named this rule in a disable and wrote no reason. A reasonless disable is
+     * itself a violation: the point of the per-site hatch is the ARGUMENT, which is the only
+     * part the next reader can weigh.
+     */
+    reasonlessDisables: readonly ApiContractDefect[]);
+    isEmpty(): boolean;
+}
+/**
+ * ONE endpoint declared PERMANENTLY outside MCP by `@InvalidEndpointForMcp('<reason>')` (#1014).
+ *
+ * Not a violation and not a suppression — a DECLARATION, which is why it is carried beside the
+ * findings rather than in them. `api-rules-for-mcp` restates the whole list, with reasons, on every
+ * run: an exclusion announced once at the moment somebody added it is an exclusion nobody will read
+ * again, and a build-time warning at add time would be read exactly as little.
+ */
+export declare class McpExclusion {
+    readonly api: string;
+    readonly method: string;
+    /** The decorator's reason, verbatim. Empty only when the argument could not be folded. */
+    readonly reason: string;
+    /** `path/to/File.ts:LINE`, workspace-relative. */
+    readonly at: string;
+    constructor(api: string, method: string, 
+    /** The decorator's reason, verbatim. Empty only when the argument could not be folded. */
+    reason: string, 
+    /** `path/to/File.ts:LINE`, workspace-relative. */
+    at: string);
+}
+/** Both rules' findings from ONE scan — one program build, two verdicts. */
+export declare class ApiDocRulesFindings {
+    readonly openApi: ApiRuleFindings;
+    readonly mcp: ApiRuleFindings;
+    /** Every `@InvalidEndpointForMcp` endpoint the MCP rule looked at, in declaration order. */
+    readonly mcpExclusions: readonly McpExclusion[];
+    constructor(openApi: ApiRuleFindings, mcp: ApiRuleFindings, 
+    /** Every `@InvalidEndpointForMcp` endpoint the MCP rule looked at, in declaration order. */
+    mcpExclusions?: readonly McpExclusion[]);
+    static empty(): ApiDocRulesFindings;
+}
+/**
+ * ONE rule's switches, resolved from webpieces.config.json once per scan.
+ *
+ * The DEFAULT is OFF, and unlike an absent entry elsewhere that is deliberate: `defaultRules` in
+ * `@webpieces/rules-config` carries `mode: 'OFF'` for both, and the argument for it is written
+ * there rather than here so there is one place to read it.
+ */
+export declare class ApiDocRule {
+    readonly name: string;
+    readonly enabled: boolean;
+    /** Project roots this rule does not apply to — `allowedPaths` in the config. */
+    readonly allowedPaths: readonly string[];
+    constructor(name: string, enabled: boolean, 
+    /** Project roots this rule does not apply to — `allowedPaths` in the config. */
+    allowedPaths: readonly string[]);
+    /** ARMED, everywhere — what a unit test constructs, and what an opted-in repo resolves to. */
+    static armed(name: string): ApiDocRule;
+    static off(name: string): ApiDocRule;
+    /** `mode: OFF` and the time-box/branch hatches come from RuleGate, so there is ONE reading. */
+    static fromConfig(workspaceRoot: string, name: string): ApiDocRule;
+}
+/** ONE `webpieces-disable` naming a rule, and whether it gave a reason. */
+export declare class DisableComment {
+    readonly hasReason: boolean;
+    constructor(hasReason: boolean);
+    /**
+     * The disable naming `rule` on the declaration at `line` (1-based) of `file`, or undefined.
+     *
+     * It walks UPWARD over the declaration's own leading trivia — blank lines, `//` comments, a
+     * JSDoc block, and the decorators between them — because that is where an author writes one, and
+     * it stops at the first line that is none of those, so a directive belonging to the PREVIOUS
+     * declaration can never be read as covering this one.
+     *
+     * Only a directive NAMING this rule counts. An existing `// webpieces-disable no-any-unknown`
+     * therefore does not silence these rules, which is the point: that rule answers "is this
+     * type-safe?" and these answer "is this field PUBLISHED with no shape?" — different questions
+     * with different right answers, so the second one wants its own, separately argued line.
+     *
+     * A file that cannot be read yields "no disable": a defect is still a defect, and inventing a
+     * suppression out of an I/O failure is the one wrong answer.
+     */
+    static readAt(file: string, line: number, rule: string): DisableComment | undefined;
+    /** Leading trivia a disable comment is allowed to sit above: blanks, comments and decorators. */
+    private static isTrivia;
+    private static match;
+    /** The file's lines, or undefined when it cannot be read. */
+    private static linesOf;
+}