@cyanheads/mcp-ts-core 0.7.6 → 0.8.0

package/dist/linter/rules/error-contract-rules.js

@@ -0,0 +1,321 @@
+/**
+ * @fileoverview Lint rules for the declarative `errors[]` contract on tool and
+ * resource definitions. Validates structure (codes, reasons), uniqueness,
+ * and (when a contract is present) cross-checks handler bodies for thrown
+ * codes that aren't declared.
+ * @module src/linter/rules/error-contract-rules
+ */
+import { JsonRpcErrorCode } from '../../types-global/errors.js';
+import { stripCommentsAndStrings } from './source-text.js';
+/**
+ * Set of valid `JsonRpcErrorCode` numeric values, computed once at module load.
+ * Used to validate the `code` field on each contract entry.
+ */
+const VALID_CODES = new Set(Object.values(JsonRpcErrorCode).filter((v) => typeof v === 'number'));
+const REASON_RE = /^[a-z][a-z0-9_]*$/;
+/**
+ * Validates the `errors[]` contract on a tool/resource definition.
+ * Checks:
+ *   - `errors` is an array
+ *   - each entry is an object with required `code`, `reason`, `when`
+ *   - `code` is a real `JsonRpcErrorCode` value
+ *   - `reason` is snake_case and unique within the contract
+ *   - `retryable` (when present) is a boolean
+ */
+export function lintErrorContract(errors, definitionType, definitionName) {
+    const diagnostics = [];
+    if (errors === undefined)
+        return diagnostics;
+    if (!Array.isArray(errors)) {
+        diagnostics.push({
+            rule: 'error-contract-type',
+            severity: 'error',
+            message: `${definitionType} '${definitionName}' has 'errors' but it is not an array.`,
+            definitionType,
+            definitionName,
+        });
+        return diagnostics;
+    }
+    if (errors.length === 0) {
+        diagnostics.push({
+            rule: 'error-contract-empty',
+            severity: 'warning',
+            message: `${definitionType} '${definitionName}' declares an empty 'errors: []' contract. ` +
+                'An empty contract is a no-op — drop the field entirely, or declare the actual ' +
+                'failure modes. Empty contracts give clients no useful failure-surface preview.',
+            definitionType,
+            definitionName,
+        });
+        return diagnostics;
+    }
+    const seenReasons = new Set();
+    for (let i = 0; i < errors.length; i++) {
+        const entry = errors[i];
+        const path = `errors[${i}]`;
+        if (typeof entry !== 'object' || entry === null) {
+            diagnostics.push({
+                rule: 'error-contract-entry-type',
+                severity: 'error',
+                message: `${definitionType} '${definitionName}' ${path} must be an object with { code, reason, when }.`,
+                definitionType,
+                definitionName,
+            });
+            continue;
+        }
+        const e = entry;
+        // code
+        if (typeof e.code !== 'number') {
+            diagnostics.push({
+                rule: 'error-contract-code-type',
+                severity: 'error',
+                message: `${definitionType} '${definitionName}' ${path}.code must be a JsonRpcErrorCode value (number).`,
+                definitionType,
+                definitionName,
+            });
+        }
+        else if (!VALID_CODES.has(e.code)) {
+            diagnostics.push({
+                rule: 'error-contract-code-unknown',
+                severity: 'error',
+                message: `${definitionType} '${definitionName}' ${path}.code is ${e.code}, ` +
+                    'which is not a valid JsonRpcErrorCode. Use the enum import.',
+                definitionType,
+                definitionName,
+            });
+        }
+        else if (e.code === JsonRpcErrorCode.UnknownError) {
+            // `UnknownError` is the auto-classifier's giveup fallback — it tells
+            // clients literally nothing. Declaring it in a contract is meaningless;
+            // pick a more specific code (or omit the entry entirely).
+            diagnostics.push({
+                rule: 'error-contract-code-unknown-error',
+                severity: 'warning',
+                message: `${definitionType} '${definitionName}' ${path}.code is JsonRpcErrorCode.UnknownError. ` +
+                    "This is the framework's giveup-fallback code — it conveys no useful information " +
+                    'to clients. Pick a more specific code (e.g. InternalError, ServiceUnavailable) or ' +
+                    'remove the entry.',
+                definitionType,
+                definitionName,
+            });
+        }
+        // reason
+        if (typeof e.reason !== 'string' || e.reason.length === 0) {
+            diagnostics.push({
+                rule: 'error-contract-reason-required',
+                severity: 'error',
+                message: `${definitionType} '${definitionName}' ${path}.reason must be a non-empty string.`,
+                definitionType,
+                definitionName,
+            });
+        }
+        else {
+            if (!REASON_RE.test(e.reason)) {
+                diagnostics.push({
+                    rule: 'error-contract-reason-format',
+                    severity: 'warning',
+                    message: `${definitionType} '${definitionName}' ${path}.reason '${e.reason}' should be snake_case ` +
+                        '(start with a lowercase letter, then lowercase letters/digits/underscores). Treat reasons like API constants.',
+                    definitionType,
+                    definitionName,
+                });
+            }
+            if (seenReasons.has(e.reason)) {
+                diagnostics.push({
+                    rule: 'error-contract-reason-unique',
+                    severity: 'error',
+                    message: `${definitionType} '${definitionName}' has duplicate reason '${e.reason}' in errors[]. Reasons must be unique within a contract.`,
+                    definitionType,
+                    definitionName,
+                });
+            }
+            seenReasons.add(e.reason);
+        }
+        // when
+        if (typeof e.when !== 'string' || e.when.length === 0) {
+            diagnostics.push({
+                rule: 'error-contract-when-required',
+                severity: 'error',
+                message: `${definitionType} '${definitionName}' ${path}.when must be a non-empty human-readable description.`,
+                definitionType,
+                definitionName,
+            });
+        }
+        // retryable (optional)
+        if (e.retryable !== undefined && typeof e.retryable !== 'boolean') {
+            diagnostics.push({
+                rule: 'error-contract-retryable-type',
+                severity: 'warning',
+                message: `${definitionType} '${definitionName}' ${path}.retryable should be a boolean when present.`,
+                definitionType,
+                definitionName,
+            });
+        }
+    }
+    return diagnostics;
+}
+/**
+ * Map from `JsonRpcErrorCode` enum names → numeric values, computed once.
+ * Used by the conformance check to recognize `JsonRpcErrorCode.X` references in
+ * handler source.
+ */
+const CODE_NAME_TO_VALUE = (() => {
+    const out = {};
+    for (const [name, value] of Object.entries(JsonRpcErrorCode)) {
+        if (typeof value === 'number') {
+            out[name] = value;
+        }
+    }
+    return out;
+})();
+/**
+ * Map from factory function names → the codes they produce. Used by the
+ * conformance check to recognize `notFound(...)` style throws.
+ */
+const FACTORY_TO_CODE = {
+    invalidParams: JsonRpcErrorCode.InvalidParams,
+    invalidRequest: JsonRpcErrorCode.InvalidRequest,
+    notFound: JsonRpcErrorCode.NotFound,
+    forbidden: JsonRpcErrorCode.Forbidden,
+    unauthorized: JsonRpcErrorCode.Unauthorized,
+    validationError: JsonRpcErrorCode.ValidationError,
+    conflict: JsonRpcErrorCode.Conflict,
+    rateLimited: JsonRpcErrorCode.RateLimited,
+    timeout: JsonRpcErrorCode.Timeout,
+    serviceUnavailable: JsonRpcErrorCode.ServiceUnavailable,
+    configurationError: JsonRpcErrorCode.ConfigurationError,
+    internalError: JsonRpcErrorCode.InternalError,
+    serializationError: JsonRpcErrorCode.SerializationError,
+    databaseError: JsonRpcErrorCode.DatabaseError,
+};
+/**
+ * Codes that bubble up from anywhere — services, framework utilities,
+ * the auto-classifier — and are implicitly always-possible on any tool.
+ * The conformance check skips them so the contract can stay focused on
+ * the tool's *intentional* failure surface, not exhaustive infrastructure.
+ *
+ * Modeled after how OpenAPI-driven frameworks treat 5xx: implicit, not
+ * required to be enumerated per-endpoint.
+ */
+const BASELINE_CONFORMANCE_CODES = new Set([
+    JsonRpcErrorCode.InternalError,
+    JsonRpcErrorCode.ServiceUnavailable,
+    JsonRpcErrorCode.Timeout,
+    JsonRpcErrorCode.ValidationError,
+    JsonRpcErrorCode.SerializationError,
+]);
+/**
+ * Cross-checks a definition's declared `errors[]` contract against the codes
+ * that appear textually in its `handler` body. Fires only when a contract is
+ * present — definitions without an `errors[]` field are silently skipped.
+ *
+ * **Two distinct findings:**
+ *
+ * - `error-contract-conformance` — handler throws a non-baseline code that
+ *   isn't in the contract. Suggests adding it to `errors[]`.
+ * - `error-contract-prefer-fail` — handler throws a code that IS in the
+ *   contract directly (via factory or `new McpError`) instead of via
+ *   `ctx.fail(reason, …)`. Encourages routing through the typed helper so
+ *   observers see consistent `data.reason` values.
+ *
+ * **Baseline codes** (`InternalError`, `ServiceUnavailable`, `Timeout`,
+ * `ValidationError`, `SerializationError`) are skipped — they bubble from
+ * anywhere and don't need to be enumerated per-tool.
+ *
+ * Heuristic only: scans handler source text for `JsonRpcErrorCode.X` references
+ * and factory calls. Codes thrown from called services are invisible — so this
+ * is always a warning, never an error.
+ */
+export function lintErrorContractConformance(def, definitionType, definitionName) {
+    const diagnostics = [];
+    if (!Array.isArray(def.errors) || def.errors.length === 0)
+        return diagnostics;
+    if (typeof def.handler !== 'function')
+        return diagnostics;
+    let source;
+    try {
+        source = def.handler.toString();
+    }
+    catch {
+        return diagnostics;
+    }
+    // Strip strings/comments so a comment like `// throws NotFound` doesn't pollute.
+    const cleaned = stripCommentsAndStrings(source);
+    const observed = new Set();
+    // Direct references: `JsonRpcErrorCode.NotFound`
+    for (const m of cleaned.matchAll(/JsonRpcErrorCode\.(\w+)/g)) {
+        const value = m[1] ? CODE_NAME_TO_VALUE[m[1]] : undefined;
+        if (value !== undefined)
+            observed.add(value);
+    }
+    // Factory calls: `throw notFound(...)`, `throw serviceUnavailable(...)`
+    const factoryRe = new RegExp(String.raw `\bthrow\s+(${Object.keys(FACTORY_TO_CODE).join('|')})\s*\(`, 'g');
+    for (const m of cleaned.matchAll(factoryRe)) {
+        const code = m[1] ? FACTORY_TO_CODE[m[1]] : undefined;
+        if (code !== undefined)
+            observed.add(code);
+    }
+    // Build code → reason map from the contract so we can suggest the right
+    // ctx.fail('reason') call when a declared code is thrown directly.
+    const codeToReasons = new Map();
+    for (const entry of def.errors) {
+        if (entry && typeof entry.code === 'number' && typeof entry.reason === 'string') {
+            const reasons = codeToReasons.get(entry.code) ?? [];
+            reasons.push(entry.reason);
+            codeToReasons.set(entry.code, reasons);
+        }
+    }
+    const undeclared = [];
+    const declaredButDirect = [];
+    for (const code of observed) {
+        if (BASELINE_CONFORMANCE_CODES.has(code))
+            continue;
+        const reasons = codeToReasons.get(code);
+        if (reasons && reasons.length > 0) {
+            declaredButDirect.push({ codeName: jsonRpcErrorCodeName(code), reasons });
+        }
+        else {
+            undeclared.push(jsonRpcErrorCodeName(code));
+        }
+    }
+    if (undeclared.length > 0) {
+        diagnostics.push({
+            rule: 'error-contract-conformance',
+            severity: 'warning',
+            message: `${definitionType} '${definitionName}' handler throws codes not in errors[]: ` +
+                `${undeclared.join(', ')}. Add them to the contract (with a stable reason) so ` +
+                '`tools/list` accurately advertises this failure mode. ' +
+                'Baseline codes (InternalError, ServiceUnavailable, Timeout, ValidationError, ' +
+                'SerializationError) are auto-allowed — only domain-specific codes need declaring.',
+            definitionType,
+            definitionName,
+        });
+    }
+    for (const entry of declaredButDirect) {
+        const reasonHint = entry.reasons.length === 1
+            ? `'${entry.reasons[0]}'`
+            : `one of ${entry.reasons.map((r) => `'${r}'`).join(' / ')}`;
+        diagnostics.push({
+            rule: 'error-contract-prefer-fail',
+            severity: 'warning',
+            message: `${definitionType} '${definitionName}' throws ${entry.codeName} directly, but the ` +
+                `contract declares this code as reason ${reasonHint}. Consider routing through ` +
+                `\`ctx.fail(${reasonHint}, …)\` so observers see consistent \`data.reason\` values ` +
+                'and the failure is correlated with the contract entry.',
+            definitionType,
+            definitionName,
+        });
+    }
+    return diagnostics;
+}
+/**
+ * Returns the enum name for a `JsonRpcErrorCode` value, or `String(code)` when
+ * the value is not a known member.
+ */
+function jsonRpcErrorCodeName(code) {
+    for (const [name, value] of Object.entries(JsonRpcErrorCode)) {
+        if (value === code)
+            return name;
+    }
+    return String(code);
+}
+//# sourceMappingURL=error-contract-rules.js.map

package/dist/linter/rules/error-contract-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-contract-rules.js","sourceRoot":"","sources":["../../../src/linter/rules/error-contract-rules.ts"],"names":[],"mappings":"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"}

package/dist/linter/rules/handler-body-rules.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Heuristic source-text lint rules that scan the body of a
+ * tool/resource handler for common error-handling anti-patterns. These rules
+ * are intentionally cautious — false positives are warnings, not errors, and
+ * each rule fires at most once per definition to avoid noisy reports.
+ * @module src/linter/rules/handler-body-rules
+ */
+import type { LintDefinitionType, LintDiagnostic } from '../types.js';
+/**
+ * Runs all handler-body lint rules against a tool or resource definition.
+ * Operates on `handler.toString()` — heuristic but adequate for catching the
+ * common anti-patterns documented in the framework conventions.
+ */
+export declare function lintHandlerBody(def: {
+    handler?: unknown;
+    name?: string;
+}, definitionType: LintDefinitionType): LintDiagnostic[];
+//# sourceMappingURL=handler-body-rules.d.ts.map

package/dist/linter/rules/handler-body-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-body-rules.d.ts","sourceRoot":"","sources":["../../../src/linter/rules/handler-body-rules.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAiCtE;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EACzC,cAAc,EAAE,kBAAkB,GACjC,cAAc,EAAE,CAoGlB"}

package/dist/linter/rules/handler-body-rules.js

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview Heuristic source-text lint rules that scan the body of a
+ * tool/resource handler for common error-handling anti-patterns. These rules
+ * are intentionally cautious — false positives are warnings, not errors, and
+ * each rule fires at most once per definition to avoid noisy reports.
+ * @module src/linter/rules/handler-body-rules
+ */
+import { stripCommentsAndStrings } from './source-text.js';
+/**
+ * Map from `JsonRpcErrorCode.X` enum names to their factory function names.
+ * Used by `prefer-error-factory` to suggest the right replacement.
+ */
+const CODE_TO_FACTORY = {
+    InvalidParams: 'invalidParams',
+    InvalidRequest: 'invalidRequest',
+    NotFound: 'notFound',
+    Forbidden: 'forbidden',
+    Unauthorized: 'unauthorized',
+    ValidationError: 'validationError',
+    Conflict: 'conflict',
+    RateLimited: 'rateLimited',
+    Timeout: 'timeout',
+    ServiceUnavailable: 'serviceUnavailable',
+    ConfigurationError: 'configurationError',
+    InternalError: 'internalError',
+    SerializationError: 'serializationError',
+    DatabaseError: 'databaseError',
+};
+/**
+ * Names of factory functions and the `McpError` constructor — used to detect
+ * "is this a throw of a structured framework error?" inside a catch block.
+ */
+const FACTORY_NAMES = Object.values(CODE_TO_FACTORY).join('|');
+const STRUCTURED_THROW_RE = new RegExp(String.raw `throw\s+(?:new\s+McpError\s*\(|(?:${FACTORY_NAMES})\s*\()`);
+/**
+ * Runs all handler-body lint rules against a tool or resource definition.
+ * Operates on `handler.toString()` — heuristic but adequate for catching the
+ * common anti-patterns documented in the framework conventions.
+ */
+export function lintHandlerBody(def, definitionType) {
+    const diagnostics = [];
+    const definitionName = typeof def.name === 'string' && def.name ? def.name : '<unnamed>';
+    if (typeof def.handler !== 'function')
+        return diagnostics;
+    let source;
+    try {
+        source = def.handler.toString();
+    }
+    catch {
+        /* Some bound/native functions reject toString — nothing to lint. */
+        return diagnostics;
+    }
+    // Strip line/block comments and string contents so we don't fire on commented-out
+    // code or strings containing `throw new Error(`. Best-effort — preserves quote
+    // structure but blanks the inner text.
+    const cleaned = stripCommentsAndStrings(source);
+    // ── Rule 1: prefer-mcp-error-in-handler ──────────────────────────────────
+    // Plain `throw new Error(...)` doesn't carry a JSON-RPC code.
+    if (/throw\s+new\s+Error\s*\(/.test(cleaned)) {
+        diagnostics.push({
+            rule: 'prefer-mcp-error-in-handler',
+            severity: 'warning',
+            message: `${definitionType} '${definitionName}' throws a plain Error. ` +
+                'Use McpError or a factory (e.g. notFound(), serviceUnavailable(), serializationError()) ' +
+                'so the framework returns a specific JSON-RPC error code instead of the generic InternalError fallback.',
+            definitionType,
+            definitionName,
+        });
+    }
+    // ── Rule 2: prefer-error-factory ─────────────────────────────────────────
+    // `new McpError(JsonRpcErrorCode.X, ...)` when `xFactory(...)` exists is verbose.
+    const factoryMatch = /new\s+McpError\s*\(\s*JsonRpcErrorCode\.(\w+)/.exec(cleaned);
+    if (factoryMatch) {
+        const codeName = factoryMatch[1];
+        const factory = codeName ? CODE_TO_FACTORY[codeName] : undefined;
+        if (factory) {
+            diagnostics.push({
+                rule: 'prefer-error-factory',
+                severity: 'warning',
+                message: `${definitionType} '${definitionName}' uses 'new McpError(JsonRpcErrorCode.${codeName}, …)'. ` +
+                    `Prefer the factory '${factory}(…)' from @cyanheads/mcp-ts-core/errors for consistency and readability.`,
+                definitionType,
+                definitionName,
+            });
+        }
+    }
+    // ── Rule 3: preserve-cause-on-rethrow ────────────────────────────────────
+    // For each `catch (E)` block, if it throws a structured error without
+    // `{ cause: E }`, the original error chain is lost.
+    for (const catchMatch of cleaned.matchAll(/catch\s*\(\s*(\w+)/g)) {
+        const errorVar = catchMatch[1];
+        if (!errorVar || catchMatch.index === undefined)
+            continue;
+        // Bound the scan to the next ~800 chars — enough for a typical block,
+        // bounded so a long handler with many `catch` blocks doesn't compound.
+        const blockStart = catchMatch.index + catchMatch[0].length;
+        const block = cleaned.slice(blockStart, blockStart + 800);
+        if (!STRUCTURED_THROW_RE.test(block))
+            continue;
+        // `cause: errorVar` or `cause: e` somewhere in the block satisfies the rule.
+        const causeRe = new RegExp(String.raw `cause\s*:\s*${errorVar}\b`);
+        if (causeRe.test(block))
+            continue;
+        diagnostics.push({
+            rule: 'preserve-cause-on-rethrow',
+            severity: 'warning',
+            message: `${definitionType} '${definitionName}' wraps caught '${errorVar}' in McpError ` +
+                `without { cause: ${errorVar} }. Pass the cause via the 4th constructor arg ` +
+                '(or factory options) to preserve the error chain — observability platforms ' +
+                'and pino-pretty surface causes automatically.',
+            definitionType,
+            definitionName,
+        });
+        break;
+    }
+    // ── Rule 4: no-stringify-upstream-error ──────────────────────────────────
+    // `throw new Error(\`... ${JSON.stringify(upstreamError)} ...\`)` risks leaking
+    // raw upstream blobs (stack traces, internal structure) into client-visible messages.
+    // Bound the scan length so unrelated calls in long handlers don't trigger false positives.
+    if (/throw\s+[^;]{0,400}?JSON\.stringify\s*\(/.test(cleaned)) {
+        diagnostics.push({
+            rule: 'no-stringify-upstream-error',
+            severity: 'warning',
+            message: `${definitionType} '${definitionName}' throws a message containing JSON.stringify(...). ` +
+                'Stringifying caught or upstream error blobs into the message risks leaking internal ' +
+                'traces (e.g., NCBI C++ exceptions, AWS internal ARNs) to clients. Sanitize first, or ' +
+                "attach the raw blob to the McpError's 'data' payload — never the message.",
+            definitionType,
+            definitionName,
+        });
+    }
+    return diagnostics;
+}
+//# sourceMappingURL=handler-body-rules.js.map

package/dist/linter/rules/handler-body-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-body-rules.js","sourceRoot":"","sources":["../../../src/linter/rules/handler-body-rules.ts"],"names":[],"mappings":"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"}

package/dist/linter/rules/index.d.ts

@@ -2,6 +2,8 @@
  * @fileoverview Barrel export for all lint rule modules.
  * @module src/linter/rules/index
  */
+export { lintErrorContract, lintErrorContractConformance } from './error-contract-rules.js';
+export { lintHandlerBody } from './handler-body-rules.js';
 export { checkDuplicateNames, checkNameRequired, checkToolNameFormat } from './name-rules.js';
 export { lintPromptDefinition } from './prompt-rules.js';
 export { lintResourceDefinition } from './resource-rules.js';

package/dist/linter/rules/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/linter/rules/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,0BAA0B,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/linter/rules/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,iBAAiB,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AAC5F,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,0BAA0B,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/linter/rules/index.js

@@ -2,6 +2,8 @@
  * @fileoverview Barrel export for all lint rule modules.
  * @module src/linter/rules/index
  */
+export { lintErrorContract, lintErrorContractConformance } from './error-contract-rules.js';
+export { lintHandlerBody } from './handler-body-rules.js';
 export { checkDuplicateNames, checkNameRequired, checkToolNameFormat } from './name-rules.js';
 export { lintPromptDefinition } from './prompt-rules.js';
 export { lintResourceDefinition } from './resource-rules.js';

package/dist/linter/rules/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/linter/rules/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,0BAA0B,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/linter/rules/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,iBAAiB,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AAC5F,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,0BAA0B,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/linter/rules/resource-rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource-rules.d.ts","sourceRoot":"","sources":["../../../src/linter/rules/resource-rules.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AASlD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,EAAE,CAkGrE"}
+{"version":3,"file":"resource-rules.d.ts","sourceRoot":"","sources":["../../../src/linter/rules/resource-rules.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAWlD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,EAAE,CAiHrE"}

package/dist/linter/rules/resource-rules.js

@@ -3,6 +3,8 @@
  * Validates resource definitions against MCP spec and framework conventions.
  * @module src/linter/rules/resource-rules
  */
+import { lintErrorContract, lintErrorContractConformance } from './error-contract-rules.js';
+import { lintHandlerBody } from './handler-body-rules.js';
 import { checkNameRequired } from './name-rules.js';
 import { checkFieldDescriptions, checkIsZodObject, checkSchemaSerializable, } from './schema-rules.js';
 import { lintAuthScopes } from './tool-rules.js';
@@ -102,6 +104,13 @@ export function lintResourceDefinition(def) {
                 diagnostics.push(outputSerial);
         }
     }
+    // Handler body heuristic checks (error-handling anti-patterns)
+    diagnostics.push(...lintHandlerBody(d, 'resource'));
+    // Declarative error contract validation
+    if (d?.errors !== undefined) {
+        diagnostics.push(...lintErrorContract(d.errors, 'resource', displayName));
+        diagnostics.push(...lintErrorContractConformance(d, 'resource', displayName));
+    }
     return diagnostics;
 }
 /** Extracts variable names from an RFC 6570 URI template (strips operators like +, #, ?, &, etc.). */

package/dist/linter/rules/resource-rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"resource-rules.js","sourceRoot":"","sources":["../../../src/linter/rules/resource-rules.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resource-rules.js","sourceRoot":"","sources":["../../../src/linter/rules/resource-rules.ts"],"names":[],"mappings":"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"}

package/dist/linter/rules/source-text.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Shared text utilities for handler-source heuristic lint rules.
+ * @module src/linter/rules/source-text
+ */
+/**
+ * Replaces the contents of single-line comments, block comments, and string
+ * literals with same-length whitespace runs. Preserves line structure (so any
+ * future line-aware diagnostics still align) without falsely matching
+ * anti-pattern regexes against documentation or sample text inside literals.
+ *
+ * Used by the handler-body and error-contract conformance rules so a comment
+ * like `// throws NotFound` doesn't pollute the scan.
+ *
+ * Limitations: regex literals are not stripped. If a regex contains the literal
+ * text `throw new Error(`, it would still trigger a false positive — but that is
+ * a deliberate trade-off; full lexing is overkill for a heuristic warning.
+ */
+export declare function stripCommentsAndStrings(source: string): string;
+//# sourceMappingURL=source-text.d.ts.map

package/dist/linter/rules/source-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-text.d.ts","sourceRoot":"","sources":["../../../src/linter/rules/source-text.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAiF9D"}