@webpieces/nx-webpieces-rules 0.4.808 → 0.4.810

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

@@ -0,0 +1,298 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DisableComment = exports.ApiDocRule = exports.AFFECTED_PROJECT_MODE = exports.ApiDocRulesFindings = exports.McpExclusion = exports.ApiRuleFindings = exports.ApiContractDefect = exports.EXTERNAL_CUSTOMER_API_TYPE = exports.MCP_RULE = exports.OPENAPI_RULE = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const rules_config_1 = require("@webpieces/rules-config");
+const rule_gate_1 = require("../rule-gate");
+/** As written in a disable comment and as a config key. */
+exports.OPENAPI_RULE = rules_config_1.RULE_NAMES.API_RULES_FOR_OPENAPI;
+exports.MCP_RULE = rules_config_1.RULE_NAMES.API_RULES_FOR_MCP;
+/** The `@ApiType` value that means "a partner reads this document". */
+exports.EXTERNAL_CUSTOMER_API_TYPE = 'external-customer';
+/**
+ * `// webpieces-disable <rule>[, <rule2>] -- <reason>`, with the reason CAPTURED so a reasonless
+ * disable can be told apart from an absent one. Identical to the spelling `root-union-scan` reads.
+ */
+const DISABLE_RE = new RegExp(`//\\s*${rules_config_1.WEBPIECES_DISABLE}\\s+([\\w-]+(?:\\s*,\\s*[\\w-]+)*)(?:\\s*--\\s*(.*))?$`);
+/** How far above a declaration a disable comment may sit before it is somebody else's comment. */
+const DISABLE_LOOKBACK_LINES = 40;
+/**
+ * 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.
+ */
+class ApiContractDefect {
+    api;
+    method;
+    what;
+    at;
+    cure;
+    exposure;
+    constructor(
+    /** The `@ApiPath` contract class. */
+    api, 
+    /** The `@Endpoint` method, or `''` for a contract-level or DTO-level defect. */
+    method, 
+    /** What is wrong, in one line, naming the declaration. */
+    what, 
+    /** `path/to/File.ts:LINE`, workspace-relative. */
+    at, 
+    /** What to do instead, in one sentence. */
+    cure, 
+    /** The contract's `@ApiType` list — `svc-to-svc` when it declares none. */
+    exposure) {
+        this.api = api;
+        this.method = method;
+        this.what = what;
+        this.at = at;
+        this.cure = cure;
+        this.exposure = exposure;
+    }
+    /** True when this contract feeds the PARTNER-facing document. */
+    isExternal() {
+        return this.exposure.includes(exports.EXTERNAL_CUSTOMER_API_TYPE);
+    }
+    /** `Api.method` or `Api` — what a reader opens. */
+    where() {
+        return this.method === '' ? this.api : `${this.api}.${this.method}`;
+    }
+}
+exports.ApiContractDefect = ApiContractDefect;
+/** What ONE rule found: real defects, and disables of it that gave no reason. */
+class ApiRuleFindings {
+    violations;
+    reasonlessDisables;
+    constructor(violations, 
+    /**
+     * 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) {
+        this.violations = violations;
+        this.reasonlessDisables = reasonlessDisables;
+    }
+    isEmpty() {
+        return this.violations.length === 0 && this.reasonlessDisables.length === 0;
+    }
+}
+exports.ApiRuleFindings = ApiRuleFindings;
+/**
+ * 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.
+ */
+class McpExclusion {
+    api;
+    method;
+    reason;
+    at;
+    constructor(api, method, 
+    /** The decorator's reason, verbatim. Empty only when the argument could not be folded. */
+    reason, 
+    /** `path/to/File.ts:LINE`, workspace-relative. */
+    at) {
+        this.api = api;
+        this.method = method;
+        this.reason = reason;
+        this.at = at;
+    }
+}
+exports.McpExclusion = McpExclusion;
+/** Both rules' findings from ONE scan — one program build, two verdicts. */
+class ApiDocRulesFindings {
+    openApi;
+    mcp;
+    mcpExclusions;
+    constructor(openApi, mcp, 
+    /** Every `@InvalidEndpointForMcp` endpoint the MCP rule looked at, in declaration order. */
+    mcpExclusions = []) {
+        this.openApi = openApi;
+        this.mcp = mcp;
+        this.mcpExclusions = mcpExclusions;
+    }
+    // webpieces-disable no-function-outside-class -- static factory of this class
+    static empty() {
+        return new ApiDocRulesFindings(new ApiRuleFindings([], []), new ApiRuleFindings([], []), []);
+    }
+}
+exports.ApiDocRulesFindings = ApiDocRulesFindings;
+/** The mode value that narrows the scan to the projects the diff touched. */
+exports.AFFECTED_PROJECT_MODE = 'AFFECTED_PROJECT';
+/**
+ * ONE rule's switches, resolved from webpieces.config.json once per scan.
+ *
+ * There is NO default (#1017). Both rules are schema'd, so `webpieces.config.json` must carry an
+ * entry for each or the config FAILS TO LOAD naming them — a consumer states `OFF`,
+ * `AFFECTED_PROJECT` or `RUN_EVERY_TIME` out loud. The `off()` a bare constructor or a unit test
+ * gets is not a default; it is what a caller that configured nothing asked for.
+ */
+class ApiDocRule {
+    name;
+    enabled;
+    allowedPaths;
+    changedPaths;
+    constructor(name, enabled, 
+    /** Project roots this rule does not apply to — `allowedPaths` in the config. */
+    allowedPaths, 
+    /**
+     * Workspace-relative paths the diff touched, under `AFFECTED_PROJECT`; `null` under
+     * `RUN_EVERY_TIME`, which means every project is in scope.
+     *
+     * `null` is also what an UNCOMPUTABLE diff resolves to — no merge-base, a shallow clone, no
+     * repository at all. A diff that could not be read is not evidence that nothing changed, and
+     * the only safe reading of "I do not know what changed" is "look at all of it".
+     */
+    changedPaths = null) {
+        this.name = name;
+        this.enabled = enabled;
+        this.allowedPaths = allowedPaths;
+        this.changedPaths = changedPaths;
+    }
+    /** ARMED over every project — what a unit test constructs, and what RUN_EVERY_TIME resolves to. */
+    // webpieces-disable no-function-outside-class -- static factory of this class
+    static armed(name) {
+        return new ApiDocRule(name, true, [], null);
+    }
+    /** ARMED over the projects owning one of `changedPaths` — what AFFECTED_PROJECT resolves to. */
+    // webpieces-disable no-function-outside-class -- static factory of this class
+    static affected(name, changedPaths) {
+        return new ApiDocRule(name, true, [], changedPaths);
+    }
+    // webpieces-disable no-function-outside-class -- static factory of this class
+    static off(name) {
+        return new ApiDocRule(name, false, [], null);
+    }
+    /**
+     * True when this rule scans the contracts of the project rooted at `root`.
+     *
+     * ONE place answers it, for both rules, so `allowedPaths` and the affected-project narrowing can
+     * never be applied by one caller and skipped by another.
+     */
+    coversProject(root) {
+        if (!this.enabled)
+            return false;
+        if ((0, rules_config_1.matchesAnyGlob)(root, this.allowedPaths))
+            return false;
+        if (this.changedPaths === null)
+            return true;
+        const prefix = `${root}/`;
+        return this.changedPaths.some((each) => each.startsWith(prefix));
+    }
+    /** `mode: OFF` and the time-box/branch hatches come from RuleGate, so there is ONE reading. */
+    // webpieces-disable no-function-outside-class -- static factory of this class
+    static fromConfig(workspaceRoot, name) {
+        if (new rule_gate_1.RuleGate().isDisabled(workspaceRoot, name, true)) {
+            return ApiDocRule.off(name);
+        }
+        const rule = (0, rules_config_1.loadAndValidate)(workspaceRoot).resolved.rules.get(name);
+        const allowed = rule?.options['allowedPaths'];
+        const allowedPaths = Array.isArray(allowed) ? allowed : [];
+        const affected = rule?.options['mode'] === exports.AFFECTED_PROJECT_MODE
+            ? ApiDocRule.changedPathsOf(workspaceRoot)
+            : null;
+        return new ApiDocRule(name, true, allowedPaths, affected);
+    }
+    /**
+     * Every path the diff touched, against the base nx itself uses (`NX_BASE`, else the merge-base
+     * with origin/main). NOT ts-only and INCLUDING deletions: a deleted DTO changes what a project's
+     * contracts can express exactly as an added one does, and a `project.json` edit can change which
+     * project owns a contract at all.
+     */
+    // webpieces-disable no-function-outside-class -- private static reader of this class
+    static changedPathsOf(workspaceRoot) {
+        const scope = new rules_config_1.DiffScope();
+        const range = scope.resolveBase(workspaceRoot);
+        if (range.base === undefined)
+            return null;
+        const opts = new rules_config_1.ChangedFilesOptions();
+        opts.tsOnly = false;
+        opts.includeDeletions = true;
+        return scope.getChangedFiles(workspaceRoot, range.base, range.head, opts);
+    }
+}
+exports.ApiDocRule = ApiDocRule;
+/** ONE `webpieces-disable` naming a rule, and whether it gave a reason. */
+class DisableComment {
+    hasReason;
+    constructor(hasReason) {
+        this.hasReason = hasReason;
+    }
+    /**
+     * 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.
+     */
+    // webpieces-disable no-function-outside-class -- static factory of this class
+    static readAt(file, line, rule) {
+        const lines = DisableComment.linesOf(file);
+        if (lines === undefined)
+            return undefined;
+        const start = Math.max(0, line - 1);
+        const onDeclaration = DisableComment.match(lines[start] ?? '', rule);
+        if (onDeclaration !== undefined)
+            return onDeclaration;
+        for (let i = start - 1; i >= 0 && i >= start - DISABLE_LOOKBACK_LINES; i--) {
+            const text = (lines[i] ?? '').trim();
+            const above = DisableComment.match(text, rule);
+            if (above !== undefined)
+                return above;
+            if (!DisableComment.isTrivia(text))
+                return undefined;
+        }
+        return undefined;
+    }
+    /** Leading trivia a disable comment is allowed to sit above: blanks, comments and decorators. */
+    // webpieces-disable no-function-outside-class -- private static predicate of this class
+    static isTrivia(text) {
+        return (text === '' ||
+            text.startsWith('//') ||
+            text.startsWith('*') ||
+            text.startsWith('/*') ||
+            text.startsWith('@'));
+    }
+    // webpieces-disable no-function-outside-class -- private static reader of this class
+    static match(text, rule) {
+        const found = text.trim().match(DISABLE_RE);
+        if (found === null)
+            return undefined;
+        const named = found[1].split(',').map((each) => each.trim());
+        if (!named.includes(rule))
+            return undefined;
+        return new DisableComment((found[2] ?? '').trim() !== '');
+    }
+    /** The file's lines, or undefined when it cannot be read. */
+    // webpieces-disable no-function-outside-class -- private static reader of this class
+    static linesOf(file) {
+        if (!fs.existsSync(file))
+            return undefined;
+        return fs.readFileSync(file, 'utf8').split('\n');
+    }
+}
+exports.DisableComment = DisableComment;
+//# sourceMappingURL=api-doc-rules.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api-doc-rules.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/lib/api-usage/api-doc-rules.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The DATA and the SWITCHES of `api-rules-for-openapi` and `api-rules-for-mcp` (#1011).\n *\n * The scan itself is in `api-doc-rules-scan.ts`; this file holds what a caller reads back and the\n * per-rule config, so a unit test can construct either without touching a config file and so the\n * config is read exactly once per executor run.\n */\n\nimport * as fs from 'fs';\nimport {\n    ChangedFilesOptions,\n    DiffScope,\n    loadAndValidate,\n    matchesAnyGlob,\n    RULE_NAMES,\n    WEBPIECES_DISABLE,\n} from '@webpieces/rules-config';\nimport { RuleGate } from '../rule-gate';\n\n/** As written in a disable comment and as a config key. */\nexport const OPENAPI_RULE = RULE_NAMES.API_RULES_FOR_OPENAPI;\nexport const MCP_RULE = RULE_NAMES.API_RULES_FOR_MCP;\n\n/** The `@ApiType` value that means \"a partner reads this document\". */\nexport const EXTERNAL_CUSTOMER_API_TYPE = 'external-customer';\n\n/**\n * `// webpieces-disable <rule>[, <rule2>] -- <reason>`, with the reason CAPTURED so a reasonless\n * disable can be told apart from an absent one. Identical to the spelling `root-union-scan` reads.\n */\nconst DISABLE_RE = new RegExp(\n    `//\\\\s*${WEBPIECES_DISABLE}\\\\s+([\\\\w-]+(?:\\\\s*,\\\\s*[\\\\w-]+)*)(?:\\\\s*--\\\\s*(.*))?$`,\n);\n\n/** How far above a declaration a disable comment may sit before it is somebody else's comment. */\nconst DISABLE_LOOKBACK_LINES = 40;\n\n/**\n * ONE defect on ONE contract.\n *\n * `exposure` is the contract's `@ApiType` list, and it is carried rather than derived because the\n * SAME defect is louder on a contract that reaches `external-customer`: an unshaped field on a\n * partner document costs a partner something, where the same field on a service-to-service contract\n * costs a colleague a question. The refusal sorts and labels on it.\n */\nexport class ApiContractDefect {\n    constructor(\n        /** The `@ApiPath` contract class. */\n        public readonly api: string,\n        /** The `@Endpoint` method, or `''` for a contract-level or DTO-level defect. */\n        public readonly method: string,\n        /** What is wrong, in one line, naming the declaration. */\n        public readonly what: string,\n        /** `path/to/File.ts:LINE`, workspace-relative. */\n        public readonly at: string,\n        /** What to do instead, in one sentence. */\n        public readonly cure: string,\n        /** The contract's `@ApiType` list — `svc-to-svc` when it declares none. */\n        public readonly exposure: readonly string[],\n    ) {}\n\n    /** True when this contract feeds the PARTNER-facing document. */\n    isExternal(): boolean {\n        return this.exposure.includes(EXTERNAL_CUSTOMER_API_TYPE);\n    }\n\n    /** `Api.method` or `Api` — what a reader opens. */\n    where(): string {\n        return this.method === '' ? this.api : `${this.api}.${this.method}`;\n    }\n}\n\n/** What ONE rule found: real defects, and disables of it that gave no reason. */\nexport class ApiRuleFindings {\n    constructor(\n        public readonly violations: readonly ApiContractDefect[],\n        /**\n         * Sites that named this rule in a disable and wrote no reason. A reasonless disable is\n         * itself a violation: the point of the per-site hatch is the ARGUMENT, which is the only\n         * part the next reader can weigh.\n         */\n        public readonly reasonlessDisables: readonly ApiContractDefect[],\n    ) {}\n\n    isEmpty(): boolean {\n        return this.violations.length === 0 && this.reasonlessDisables.length === 0;\n    }\n}\n\n/**\n * ONE endpoint declared PERMANENTLY outside MCP by `@InvalidEndpointForMcp('<reason>')` (#1014).\n *\n * Not a violation and not a suppression — a DECLARATION, which is why it is carried beside the\n * findings rather than in them. `api-rules-for-mcp` restates the whole list, with reasons, on every\n * run: an exclusion announced once at the moment somebody added it is an exclusion nobody will read\n * again, and a build-time warning at add time would be read exactly as little.\n */\nexport class McpExclusion {\n    constructor(\n        public readonly api: string,\n        public readonly method: string,\n        /** The decorator's reason, verbatim. Empty only when the argument could not be folded. */\n        public readonly reason: string,\n        /** `path/to/File.ts:LINE`, workspace-relative. */\n        public readonly at: string,\n    ) {}\n}\n\n/** Both rules' findings from ONE scan — one program build, two verdicts. */\nexport class ApiDocRulesFindings {\n    constructor(\n        public readonly openApi: ApiRuleFindings,\n        public readonly mcp: ApiRuleFindings,\n        /** Every `@InvalidEndpointForMcp` endpoint the MCP rule looked at, in declaration order. */\n        public readonly mcpExclusions: readonly McpExclusion[] = [],\n    ) {}\n\n    // webpieces-disable no-function-outside-class -- static factory of this class\n    static empty(): ApiDocRulesFindings {\n        return new ApiDocRulesFindings(\n            new ApiRuleFindings([], []),\n            new ApiRuleFindings([], []),\n            [],\n        );\n    }\n}\n\n/** The mode value that narrows the scan to the projects the diff touched. */\nexport const AFFECTED_PROJECT_MODE = 'AFFECTED_PROJECT';\n\n/**\n * ONE rule's switches, resolved from webpieces.config.json once per scan.\n *\n * There is NO default (#1017). Both rules are schema'd, so `webpieces.config.json` must carry an\n * entry for each or the config FAILS TO LOAD naming them — a consumer states `OFF`,\n * `AFFECTED_PROJECT` or `RUN_EVERY_TIME` out loud. The `off()` a bare constructor or a unit test\n * gets is not a default; it is what a caller that configured nothing asked for.\n */\nexport class ApiDocRule {\n    constructor(\n        public readonly name: string,\n        public readonly enabled: boolean,\n        /** Project roots this rule does not apply to — `allowedPaths` in the config. */\n        public readonly allowedPaths: readonly string[],\n        /**\n         * Workspace-relative paths the diff touched, under `AFFECTED_PROJECT`; `null` under\n         * `RUN_EVERY_TIME`, which means every project is in scope.\n         *\n         * `null` is also what an UNCOMPUTABLE diff resolves to — no merge-base, a shallow clone, no\n         * repository at all. A diff that could not be read is not evidence that nothing changed, and\n         * the only safe reading of \"I do not know what changed\" is \"look at all of it\".\n         */\n        public readonly changedPaths: readonly string[] | null = null,\n    ) {}\n\n    /** ARMED over every project — what a unit test constructs, and what RUN_EVERY_TIME resolves to. */\n    // webpieces-disable no-function-outside-class -- static factory of this class\n    static armed(name: string): ApiDocRule {\n        return new ApiDocRule(name, true, [], null);\n    }\n\n    /** ARMED over the projects owning one of `changedPaths` — what AFFECTED_PROJECT resolves to. */\n    // webpieces-disable no-function-outside-class -- static factory of this class\n    static affected(name: string, changedPaths: readonly string[]): ApiDocRule {\n        return new ApiDocRule(name, true, [], changedPaths);\n    }\n\n    // webpieces-disable no-function-outside-class -- static factory of this class\n    static off(name: string): ApiDocRule {\n        return new ApiDocRule(name, false, [], null);\n    }\n\n    /**\n     * True when this rule scans the contracts of the project rooted at `root`.\n     *\n     * ONE place answers it, for both rules, so `allowedPaths` and the affected-project narrowing can\n     * never be applied by one caller and skipped by another.\n     */\n    coversProject(root: string): boolean {\n        if (!this.enabled) return false;\n        if (matchesAnyGlob(root, this.allowedPaths)) return false;\n        if (this.changedPaths === null) return true;\n        const prefix = `${root}/`;\n        return this.changedPaths.some((each: string): boolean => each.startsWith(prefix));\n    }\n\n    /** `mode: OFF` and the time-box/branch hatches come from RuleGate, so there is ONE reading. */\n    // webpieces-disable no-function-outside-class -- static factory of this class\n    static fromConfig(workspaceRoot: string, name: string): ApiDocRule {\n        if (new RuleGate().isDisabled(workspaceRoot, name, true)) {\n            return ApiDocRule.off(name);\n        }\n        const rule = loadAndValidate(workspaceRoot).resolved.rules.get(name);\n        const allowed = rule?.options['allowedPaths'];\n        const allowedPaths = Array.isArray(allowed) ? (allowed as string[]) : [];\n        const affected =\n            rule?.options['mode'] === AFFECTED_PROJECT_MODE\n                ? ApiDocRule.changedPathsOf(workspaceRoot)\n                : null;\n        return new ApiDocRule(name, true, allowedPaths, affected);\n    }\n\n    /**\n     * Every path the diff touched, against the base nx itself uses (`NX_BASE`, else the merge-base\n     * with origin/main). NOT ts-only and INCLUDING deletions: a deleted DTO changes what a project's\n     * contracts can express exactly as an added one does, and a `project.json` edit can change which\n     * project owns a contract at all.\n     */\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static changedPathsOf(workspaceRoot: string): readonly string[] | null {\n        const scope = new DiffScope();\n        const range = scope.resolveBase(workspaceRoot);\n        if (range.base === undefined) return null;\n        const opts = new ChangedFilesOptions();\n        opts.tsOnly = false;\n        opts.includeDeletions = true;\n        return scope.getChangedFiles(workspaceRoot, range.base, range.head, opts);\n    }\n}\n\n/** ONE `webpieces-disable` naming a rule, and whether it gave a reason. */\nexport class DisableComment {\n    constructor(public readonly hasReason: boolean) {}\n\n    /**\n     * The disable naming `rule` on the declaration at `line` (1-based) of `file`, or undefined.\n     *\n     * It walks UPWARD over the declaration's own leading trivia — blank lines, `//` comments, a\n     * JSDoc block, and the decorators between them — because that is where an author writes one, and\n     * it stops at the first line that is none of those, so a directive belonging to the PREVIOUS\n     * declaration can never be read as covering this one.\n     *\n     * Only a directive NAMING this rule counts. An existing `// webpieces-disable no-any-unknown`\n     * therefore does not silence these rules, which is the point: that rule answers \"is this\n     * type-safe?\" and these answer \"is this field PUBLISHED with no shape?\" — different questions\n     * with different right answers, so the second one wants its own, separately argued line.\n     *\n     * A file that cannot be read yields \"no disable\": a defect is still a defect, and inventing a\n     * suppression out of an I/O failure is the one wrong answer.\n     */\n    // webpieces-disable no-function-outside-class -- static factory of this class\n    static readAt(file: string, line: number, rule: string): DisableComment | undefined {\n        const lines = DisableComment.linesOf(file);\n        if (lines === undefined) return undefined;\n        const start = Math.max(0, line - 1);\n        const onDeclaration = DisableComment.match(lines[start] ?? '', rule);\n        if (onDeclaration !== undefined) return onDeclaration;\n        for (let i = start - 1; i >= 0 && i >= start - DISABLE_LOOKBACK_LINES; i--) {\n            const text = (lines[i] ?? '').trim();\n            const above = DisableComment.match(text, rule);\n            if (above !== undefined) return above;\n            if (!DisableComment.isTrivia(text)) return undefined;\n        }\n        return undefined;\n    }\n\n    /** Leading trivia a disable comment is allowed to sit above: blanks, comments and decorators. */\n    // webpieces-disable no-function-outside-class -- private static predicate of this class\n    private static isTrivia(text: string): boolean {\n        return (\n            text === '' ||\n            text.startsWith('//') ||\n            text.startsWith('*') ||\n            text.startsWith('/*') ||\n            text.startsWith('@')\n        );\n    }\n\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static match(text: string, rule: string): DisableComment | undefined {\n        const found = text.trim().match(DISABLE_RE);\n        if (found === null) return undefined;\n        const named = found[1].split(',').map((each: string): string => each.trim());\n        if (!named.includes(rule)) return undefined;\n        return new DisableComment((found[2] ?? '').trim() !== '');\n    }\n\n    /** The file's lines, or undefined when it cannot be read. */\n    // webpieces-disable no-function-outside-class -- private static reader of this class\n    private static linesOf(file: string): string[] | undefined {\n        if (!fs.existsSync(file)) return undefined;\n        return fs.readFileSync(file, 'utf8').split('\\n');\n    }\n}\n"]}

package/src/lib/api-usage/api-scanner.d.ts

@@ -31,6 +31,7 @@ import type { EnhancedGraph } from '../graph-sorter';
 import { ProjectInfo } from '../project-info';
 import { ApiClassInfo, ApiContracts, EmptiedApiContract, NonLiteralDecoratorArg, ProjectApiRelations, UndeclaredExternalCaller, UndeclaredEndpointOperation, UnresolvedApiCall, UnresolvedEndpointPath } from './api-relations';
 import { RootUnionFindings, RootUnionRule } from './root-union-scan';
+import { ApiDocRule, ApiDocRulesFindings } from './api-doc-rules';
 /** The whole-workspace result of a scan. */
 export interface ApiScanResult {
     /** projectName -> { apiLibProject -> relation }; only projects with ≥1 relation appear. */
@@ -76,6 +77,11 @@ export interface ApiScanResult {
     undeclaredEndpointOperations: UndeclaredEndpointOperation[];
     /** `no-root-union-api-type`'s findings. Fatal in buildApiContracts — see root-union-scan.ts. */
     rootUnions: RootUnionFindings;
+    /**
+     * `api-rules-for-openapi` / `api-rules-for-mcp` findings (#1011). Both ship OFF, so this is
+     * EMPTY unless a repo stated otherwise — no rule in this framework has a default (#1017).
+     */
+    apiDocRules: ApiDocRulesFindings;
 }
 /** Statically scans every project for its api-lib implements/uses relationships. */
 export declare class ApiUsageScanner {
@@ -85,6 +91,10 @@ export declare class ApiUsageScanner {
     private readonly externalApiPaths;
     /** `no-root-union-api-type`'s switches — ARMED unless scanAndAttachApiRelations read otherwise. */
     private readonly rootUnionRule;
+    /** `api-rules-for-openapi`'s switches — read from the config, which MUST state them (#1017). */
+    private readonly openApiRule;
+    /** `api-rules-for-mcp`'s switches — read from the config, which MUST state them (#1017). */
+    private readonly mcpRule;
     private readonly locator;
     private readonly relationsByProject;
     private readonly scannedProjects;
@@ -95,7 +105,11 @@ export declare class ApiUsageScanner {
     /** Globs of project roots whose exported `*Api` types are contracts for outside systems. */
     externalApiPaths?: readonly string[], 
     /** `no-root-union-api-type`'s switches — ARMED unless scanAndAttachApiRelations read otherwise. */
-    rootUnionRule?: RootUnionRule);
+    rootUnionRule?: RootUnionRule, 
+    /** `api-rules-for-openapi`'s switches — read from the config, which MUST state them (#1017). */
+    openApiRule?: ApiDocRule, 
+    /** `api-rules-for-mcp`'s switches — read from the config, which MUST state them (#1017). */
+    mcpRule?: ApiDocRule);
     scan(): ApiScanResult;
     private scanProject;
     private visit;

package/src/lib/api-usage/api-scanner.js

@@ -44,6 +44,8 @@ const bindings_1 = require("../di-graph/bindings");
 const api_relations_1 = require("./api-relations");
 const api_contract_errors_1 = require("./api-contract-errors");
 const root_union_scan_1 = require("./root-union-scan");
+const api_doc_rules_1 = require("./api-doc-rules");
+const api_doc_rules_scan_1 = require("./api-doc-rules-scan");
 const api_ast_1 = require("./api-ast");
 const RPC_CLIENT_METHOD = 'createRpcClient';
 const PUBSUB_CLIENT_METHOD = 'createPubSubClient';
@@ -206,6 +208,8 @@ class ApiUsageScanner {
     projectInfos;
     externalApiPaths;
     rootUnionRule;
+    openApiRule;
+    mcpRule;
     locator;
     relationsByProject = new Map();
     scannedProjects = new Set();
@@ -216,11 +220,17 @@ class ApiUsageScanner {
     /** Globs of project roots whose exported `*Api` types are contracts for outside systems. */
     externalApiPaths = [], 
     /** `no-root-union-api-type`'s switches — ARMED unless scanAndAttachApiRelations read otherwise. */
-    rootUnionRule = root_union_scan_1.RootUnionRule.enabledEverywhere()) {
+    rootUnionRule = root_union_scan_1.RootUnionRule.enabledEverywhere(), 
+    /** `api-rules-for-openapi`'s switches — read from the config, which MUST state them (#1017). */
+    openApiRule = api_doc_rules_1.ApiDocRule.off(api_doc_rules_1.OPENAPI_RULE), 
+    /** `api-rules-for-mcp`'s switches — read from the config, which MUST state them (#1017). */
+    mcpRule = api_doc_rules_1.ApiDocRule.off(api_doc_rules_1.MCP_RULE)) {
         this.workspaceRoot = workspaceRoot;
         this.projectInfos = projectInfos;
         this.externalApiPaths = externalApiPaths;
         this.rootUnionRule = rootUnionRule;
+        this.openApiRule = openApiRule;
+        this.mcpRule = mcpRule;
         this.locator = new ProjectLocator(workspaceRoot, projectInfos);
         this.decoratorArgDiagnostics = new api_ast_1.DecoratorArgDiagnostics(workspaceRoot);
     }
@@ -245,6 +255,7 @@ class ApiUsageScanner {
             undeclaredExternalCallers: this.decoratorArgDiagnostics.undeclaredExternalCallers(),
             undeclaredEndpointOperations: this.decoratorArgDiagnostics.undeclaredEndpointOperations(),
             rootUnions: new root_union_scan_1.RootUnionScan(this.workspaceRoot, this.projectInfos, this.rootUnionRule).run(),
+            apiDocRules: new api_doc_rules_scan_1.ApiDocRulesScan(this.workspaceRoot, this.projectInfos, this.openApiRule, this.mcpRule).run(),
         };
     }
     scanProject(info) {
@@ -389,7 +400,7 @@ exports.ApiUsageScanner = ApiUsageScanner;
  */
 // webpieces-disable no-function-outside-class -- module entry point, mirrors generateReducedGraph/collectBindings
 function scanAndAttachApiRelations(workspaceRoot, graph, projectInfos, externalApiPaths = []) {
-    const result = new ApiUsageScanner(workspaceRoot, projectInfos, externalApiPaths, root_union_scan_1.RootUnionRule.fromConfig(workspaceRoot)).scan();
+    const result = new ApiUsageScanner(workspaceRoot, projectInfos, externalApiPaths, root_union_scan_1.RootUnionRule.fromConfig(workspaceRoot), api_doc_rules_1.ApiDocRule.fromConfig(workspaceRoot, api_doc_rules_1.OPENAPI_RULE), api_doc_rules_1.ApiDocRule.fromConfig(workspaceRoot, api_doc_rules_1.MCP_RULE)).scan();
     for (const projectName of result.relationsByProject.keys()) {
         const entry = graph[projectName];
         if (entry)
@@ -432,6 +443,15 @@ function buildApiContracts(scan) {
     // are contracts the scan could not READ at all.
     if (!scan.rootUnions.isEmpty())
         throw new api_contract_errors_1.RootUnionApiTypeError(scan.rootUnions);
+    // Contract shapes that are not PUBLISHABLE, read by the generator's own extractor (#1011).
+    // After the root union, which is the one shape no function-calling API will accept at all, and
+    // before the caller checks below, which are about the architecture graph rather than a document.
+    if (!scan.apiDocRules.openApi.isEmpty()) {
+        throw new api_contract_errors_1.ApiRulesForOpenApiError(scan.apiDocRules.openApi);
+    }
+    if (!scan.apiDocRules.mcp.isEmpty()) {
+        throw new api_contract_errors_1.ApiRulesForMcpError(scan.apiDocRules.mcp, scan.apiDocRules.mcpExclusions);
+    }
     // After the two above: an unreadable path is what empties a contract, and a contract that lost
     // every method has no external endpoint left to complain about.
     if (scan.undeclaredExternalCallers.length > 0) {