@apifuse/provider-sdk 2.1.0-beta.1 → 2.1.0-beta.10

package/src/lint.ts

@@ -1,5 +1,11 @@
 import type { ZodType } from "zod";
 
+import { lintPublicSchemaFieldNames } from "./public-schema-field-lint";
+import {
+	APIFUSE_DESCRIPTION_KEY_META_KEY,
+	APIFUSE_SENSITIVE_META_KEY,
+} from "./schema";
+
 type AuthModeLike =
 	| "none"
 	| "platform-managed"
@@ -14,13 +20,19 @@ type ProviderAuthLike = {
 		continue?: unknown;
 		poll?: unknown;
 		abort?: unknown;
+		refresh?: unknown;
 	};
 };
 
+type ProviderContractMetaLike = {
+	publicSchemaFieldNames?: "normalized";
+};
+
 type SchemaLike = ZodType & {
 	description?: string;
 	def?: Record<string, unknown>;
 	_def?: Record<string, unknown>;
+	meta?: () => Record<string, unknown> | undefined;
 	shape?: Record<string, SchemaLike> | (() => Record<string, SchemaLike>);
 	element?: SchemaLike;
 	items?: SchemaLike[];
@@ -41,9 +53,21 @@ export interface LintDiagnostic {
 	field?: string;
 }
 
+export type ProviderLintMode = "official" | "standalone";
+
+type ProviderLintOptions = {
+	mode?: ProviderLintMode;
+};
+
+type ProviderSourceLike = {
+	authFlowSource?: string;
+	providerSourceFiles?: Record<string, string>;
+	operations?: Record<string, { handler?: unknown; source?: string }>;
+};
+
 function lintAllowedHosts(
 	providerId: string | undefined,
-	allowedHosts: string[] | undefined,
+	allowedHosts: readonly string[] | undefined,
 ): LintDiagnostic[] {
 	const prefix = providerId ? `Provider "${providerId}"` : "Provider";
 
@@ -103,7 +127,7 @@ function lintReviewed(
 	];
 }
 
-function hasReusableSecretKeys(keys: string[] | undefined): boolean {
+function hasReusableSecretKeys(keys: readonly string[] | undefined): boolean {
 	if (!keys) {
 		return false;
 	}
@@ -115,6 +139,18 @@ function hasReusableSecretKeys(keys: string[] | undefined): boolean {
 	);
 }
 
+function hasReusableReloginSecretKeys(
+	keys: readonly string[] | undefined,
+): boolean {
+	if (!keys) {
+		return false;
+	}
+
+	return keys.some((key) =>
+		/(password|passcode|secret|cookie|session)/i.test(key),
+	);
+}
+
 function getAuthFlowSource(provider: {
 	auth?: ProviderAuthLike;
 	authFlowSource?: string;
@@ -128,6 +164,7 @@ function getAuthFlowSource(provider: {
 		provider.auth?.flow?.continue,
 		provider.auth?.flow?.poll,
 		provider.auth?.flow?.abort,
+		provider.auth?.flow?.refresh,
 	];
 
 	return parts
@@ -143,12 +180,12 @@ function lintAuthModel(provider: {
 	id?: string;
 	auth?: ProviderAuthLike;
 	credential?: {
-		keys?: string[];
+		keys?: readonly string[];
 		storesReusableSecret?: boolean;
 		justification?: string;
 	};
 	context?: {
-		keys?: string[];
+		keys?: readonly string[];
 	};
 	authFlowSource?: string;
 }): LintDiagnostic[] {
@@ -200,6 +237,20 @@ function lintAuthModel(provider: {
 		});
 	}
 
+	if (
+		typeof provider.auth?.flow?.refresh === "function" &&
+		hasReusableReloginSecretKeys(credentialKeys) &&
+		(!provider.credential?.storesReusableSecret ||
+			!provider.credential.justification)
+	) {
+		diagnostics.push({
+			rule: "auth-refresh-reusable-secret",
+			level: "error",
+			field: "credential",
+			message: `${providerLabel} must set storesReusableSecret and justification when auth.flow.refresh may silently re-login with reusable credential secrets.`,
+		});
+	}
+
 	if (authMode === "platform-managed" && credentialKeys.length > 0) {
 		diagnostics.push({
 			rule: "platform-managed-no-credential-keys",
@@ -359,7 +410,60 @@ function getChildSchemas(
 	}));
 }
 
-function collectMissingDescriptions(
+function uniqueFields(fields: string[]): string[] {
+	return Array.from(new Set(fields));
+}
+
+function isSensitiveSchema(schema: unknown): boolean {
+	if (!schema || typeof schema !== "object" || !("meta" in schema)) {
+		return false;
+	}
+	const meta = schema.meta;
+	if (typeof meta !== "function") return false;
+	const metadata = meta.call(schema);
+	return (
+		!!metadata &&
+		typeof metadata === "object" &&
+		Reflect.get(metadata, APIFUSE_SENSITIVE_META_KEY) === true
+	);
+}
+
+function getSchemaMetadata(schema: SchemaLike): Record<string, unknown> {
+	return schema.meta?.() ?? {};
+}
+
+function getSchemaDescriptionKey(schema: SchemaLike): string | undefined {
+	const value = Reflect.get(
+		getSchemaMetadata(schema),
+		APIFUSE_DESCRIPTION_KEY_META_KEY,
+	);
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+const SENSITIVE_FIELD_NAMES = new Set([
+	"apikey",
+	"authorization",
+	"cookie",
+	"secret",
+	"secrets",
+	"token",
+	"accesstoken",
+	"refreshtoken",
+	"password",
+	"passwd",
+	"otp",
+	"otpcode",
+	"phone",
+	"phonenumber",
+	"paymenturl",
+]);
+
+function isSensitiveFieldName(name: string): boolean {
+	const normalized = name.toLowerCase().replace(/[-_\s]/g, "");
+	return SENSITIVE_FIELD_NAMES.has(normalized);
+}
+
+function collectUnmarkedSensitiveFields(
 	schema: unknown,
 	basePath: string,
 	seen = new Set<SchemaLike>(),
@@ -367,13 +471,80 @@ function collectMissingDescriptions(
 	if (!isSchema(schema) || seen.has(schema)) {
 		return [];
 	}
+	seen.add(schema);
+	const out: string[] = [];
+	for (const [key, child] of Object.entries(getObjectShape(schema))) {
+		const childPath = basePath ? `${basePath}.${key}` : key;
+		if (isSensitiveFieldName(key) && !isSensitiveSchema(child)) {
+			out.push(childPath);
+		}
+		out.push(...collectUnmarkedSensitiveFields(child, childPath, seen));
+	}
+	for (const child of getChildSchemas(schema)) {
+		if (Object.hasOwn(getObjectShape(schema), child.key)) continue;
+		const isWrapperNode = [
+			"unwrap",
+			"innerType",
+			"sourceType",
+			"schema",
+			"type",
+			"in",
+			"out",
+			"option",
+			"pipe",
+			"payload",
+			"item",
+			"rest",
+			"catchall",
+			"keyType",
+			"valueType",
+		].includes(child.key);
+		const childPath =
+			child.key === "element" || child.key.startsWith("element.")
+				? `${basePath}[]`
+				: isWrapperNode || child.key.startsWith("pipe.")
+					? basePath
+					: basePath
+						? `${basePath}.${child.key}`
+						: child.key;
+		out.push(...collectUnmarkedSensitiveFields(child.schema, childPath, seen));
+	}
+	return out;
+}
+
+function collectSchemaDescriptionKeyDiagnostics(
+	schema: unknown,
+	basePath: string,
+	seen = new Set<SchemaLike>(),
+	requireCurrentDescription = true,
+): LintDiagnostic[] {
+	if (!isSchema(schema) || seen.has(schema)) {
+		return [];
+	}
 
 	seen.add(schema);
-	const missing: string[] = [];
+	const diagnostics: LintDiagnostic[] = [];
 	const currentPath = basePath || "schema";
+	const hasDescriptionKey = getSchemaDescriptionKey(schema) !== undefined;
 
-	if (!schema.description) {
-		missing.push(currentPath);
+	if (schema.description && !hasDescriptionKey) {
+		diagnostics.push({
+			rule: "schema-description-raw-prose",
+			level: "error",
+			field: currentPath,
+			message: `Schema field "${currentPath}" must use .describeKey() or describeKey() instead of raw static prose.`,
+		});
+	}
+
+	if (requireCurrentDescription && !hasDescriptionKey) {
+		diagnostics.push({
+			rule: "schema-description-key-required",
+			level: "error",
+			field: currentPath,
+			message: schema.description
+				? `Schema field "${currentPath}" has a raw description but is missing .describeKey() or describeKey() metadata.`
+				: `Schema field "${currentPath}" is missing .describeKey() or describeKey() metadata.`,
+		});
 	}
 
 	for (const child of getChildSchemas(schema)) {
@@ -383,30 +554,42 @@ function collectMissingDescriptions(
 			"sourceType",
 			"schema",
 			"type",
+			"in",
+			"out",
 			"option",
 			"pipe",
 			"payload",
 			"item",
 			"rest",
 			"catchall",
+			"keyType",
+			"valueType",
 		].includes(child.key);
+		const isStructuralNode =
+			isWrapperNode ||
+			child.key.startsWith("pipe.") ||
+			child.key === "element" ||
+			child.key.startsWith("element.");
 		const childPath = isWrapperNode
 			? currentPath
 			: currentPath === "schema"
 				? child.key
 				: /^\d+$/.test(child.key)
 					? `${currentPath}[${child.key}]`
-					: child.key.startsWith("element")
+					: child.key === "element" || child.key.startsWith("element.")
 						? `${currentPath}[]`
 						: `${currentPath}.${child.key}`;
-		missing.push(...collectMissingDescriptions(child.schema, childPath, seen));
+		diagnostics.push(
+			...collectSchemaDescriptionKeyDiagnostics(
+				child.schema,
+				childPath,
+				seen,
+				!isStructuralNode,
+			),
+		);
 	}
 
-	return missing;
-}
-
-function uniqueFields(fields: string[]): string[] {
-	return Array.from(new Set(fields));
+	return diagnostics;
 }
 
 function isComplexSchema(
@@ -438,60 +621,296 @@ function hasBidirectionalFixtures(fixtures: unknown): boolean {
 	return "request" in fixtures && "response" in fixtures;
 }
 
+function getOperationSource(operation: {
+	handler?: unknown;
+	source?: string;
+}): string {
+	if (operation.source) {
+		return operation.source;
+	}
+	return typeof operation.handler === "function"
+		? operation.handler.toString()
+		: "";
+}
+
+function lintStealthTransportUsage(provider: {
+	id?: string;
+	stealth?: unknown;
+	operations?: Record<string, { handler?: unknown; source?: string }>;
+}): LintDiagnostic[] {
+	if (provider.stealth || !provider.operations) {
+		return [];
+	}
+
+	const providerLabel = provider.id ? `Provider "${provider.id}"` : "Provider";
+	return Object.entries(provider.operations).flatMap(
+		([operationKey, operation]) => {
+			const source = getOperationSource(operation);
+			if (!/\bctx\.stealth\b/.test(source)) {
+				return [];
+			}
+			return [
+				{
+					rule: "stealth-config-required",
+					level: "error" as const,
+					field: `operations.${operationKey}`,
+					message: `${providerLabel} operation "${operationKey}" uses ctx.stealth but provider.stealth is not declared.`,
+				},
+			];
+		},
+	);
+}
+
+function lintCredentialWriteUsage(provider: {
+	operations?: Record<string, { handler?: unknown; source?: string }>;
+}): LintDiagnostic[] {
+	if (!provider.operations) {
+		return [];
+	}
+
+	return Object.entries(provider.operations).flatMap(
+		([operationKey, operation]) => {
+			const source = getOperationSource(operation);
+			if (!/\bctx\.credential\.(?:set|setMany)\s*\(/.test(source)) {
+				return [];
+			}
+
+			return [
+				{
+					rule: "ctx-credential-write-forbidden-in-handler",
+					level: "error" as const,
+					field: `operations.${operationKey}.handler`,
+					message:
+						"Operation handlers must not mutate credentials; return refreshed credentials from auth.flow.refresh instead.",
+				},
+			];
+		},
+	);
+}
+
+function lintPlaywrightDirectImports(provider: {
+	authFlowSource?: string;
+	providerSourceFiles?: Record<string, string>;
+	operations?: Record<string, { handler?: unknown; source?: string }>;
+}): LintDiagnostic[] {
+	const diagnostics: LintDiagnostic[] = [];
+	const importPattern =
+		/(?:import\s+(?:type\s+)?[\s\S]*?\s+from\s+["'](?:playwright|playwright-core)["']|require\(\s*["'](?:playwright|playwright-core)["']\s*\)|import\(\s*["'](?:playwright|playwright-core)["']\s*\))/;
+
+	if (provider.authFlowSource && importPattern.test(provider.authFlowSource)) {
+		diagnostics.push({
+			rule: "playwright-direct-import",
+			level: "warn",
+			field: "auth.flow",
+			message:
+				"Provider auth flow imports playwright directly; use ctx.browser frame-aware methods so the SDK can enforce the CDP pool runtime.",
+		});
+	}
+
+	for (const [filePath, source] of Object.entries(
+		provider.providerSourceFiles ?? {},
+	)) {
+		if (!importPattern.test(source)) {
+			continue;
+		}
+
+		diagnostics.push({
+			rule: "playwright-direct-import",
+			level: "warn",
+			field: `sourceFiles.${filePath}`,
+			message:
+				"Provider source imports playwright directly; use ctx.browser frame-aware methods so the SDK can enforce the CDP pool runtime.",
+		});
+	}
+
+	if (!provider.operations) {
+		return diagnostics;
+	}
+
+	for (const [operationKey, operation] of Object.entries(provider.operations)) {
+		const source = getOperationSource(operation);
+		if (!importPattern.test(source)) {
+			continue;
+		}
+
+		diagnostics.push({
+			rule: "playwright-direct-import",
+			level: "warn",
+			field: `operations.${operationKey}.handler`,
+			message:
+				"Operation source imports playwright directly; use ctx.browser frame-aware methods so the SDK can enforce the CDP pool runtime.",
+		});
+	}
+
+	return diagnostics;
+}
+
+type SelfHostedBrowserPattern = {
+	rule: string;
+	pattern: RegExp;
+	message: string;
+};
+
+const SELF_HOSTED_BROWSER_MESSAGE =
+	"Official browser providers must use ctx.browser backed by the managed CDP Pool; do not launch or connect to provider-local Chrome/CDP runtimes.";
+
+const SELF_HOSTED_BROWSER_PATTERNS: readonly SelfHostedBrowserPattern[] = [
+	{
+		rule: "browser-self-hosted-launch",
+		pattern: /\b(?:playwright|chromium|firefox|webkit|puppeteer)\.launch\s*\(/,
+		message: `${SELF_HOSTED_BROWSER_MESSAGE} Replace direct Playwright/Puppeteer launch calls with ctx.browser.newPage() or ctx.browser.withIsolatedContext().`,
+	},
+	{
+		rule: "browser-self-hosted-child-process",
+		pattern:
+			/(?:\b(?:spawn|spawnSync|exec|execSync|execFile|execFileSync)\s*\([\s\S]{0,240}\b(?:google-chrome|chrome|chromium|chromium-browser)\b|\b(?:Bun\.)?spawn(?:Sync)?\s*\([\s\S]{0,240}\b(?:google-chrome|chrome|chromium|chromium-browser)\b|\$`[\s\S]{0,240}\b(?:google-chrome|chrome|chromium|chromium-browser)\b)/,
+		message: `${SELF_HOSTED_BROWSER_MESSAGE} Provider pods must not start Chrome with child_process, Bun.spawn, or shell commands.`,
+	},
+	{
+		rule: "browser-self-hosted-remote-debugging-port",
+		pattern:
+			/(?:\b(?:google-chrome|chrome|chromium|chromium-browser)\b[\s\S]{0,240}--remote-debugging-port\b|--remote-debugging-port(?:=|\s+))/,
+		message: `${SELF_HOSTED_BROWSER_MESSAGE} Provider entrypoints, Dockerfiles, and scripts must not start Chrome with a remote debugging port; use the managed CDP Pool instead.`,
+	},
+	{
+		rule: "browser-direct-cdp-version-poll",
+		pattern: /\/json\/version\b/,
+		message: `${SELF_HOSTED_BROWSER_MESSAGE} Do not poll /json/version from provider code; the SDK manages CDP leases through APIFUSE__CDP_POOL__URL.`,
+	},
+	{
+		rule: "browser-provider-local-cdp-env",
+		pattern:
+			/\b(?!APIFUSE__CDP_POOL__URL\b)[A-Z][A-Z0-9_]*_CDP_URL\b|process\.env(?:\.(?!APIFUSE__CDP_POOL__URL\b)[A-Z0-9_]*_CDP_URL\b|\[\s*["'`](?!APIFUSE__CDP_POOL__URL\b)[A-Z0-9_]*_CDP_URL["'`]\s*\])/,
+		message: `${SELF_HOSTED_BROWSER_MESSAGE} Do not read provider-local CDP endpoint env vars including AMAZON_CDP_URL or custom *_CDP_URL names; production uses APIFUSE__CDP_POOL__URL through ctx.browser.`,
+	},
+];
+
+function lintSelfHostedBrowserPatterns(
+	provider: ProviderSourceLike,
+	options: ProviderLintOptions,
+): LintDiagnostic[] {
+	const diagnostics: LintDiagnostic[] = [];
+	const level = options.mode === "standalone" ? "warn" : "error";
+	const sources: Array<{ field: string; source: string }> = [];
+
+	if (provider.authFlowSource) {
+		sources.push({ field: "auth.flow", source: provider.authFlowSource });
+	}
+
+	for (const [filePath, source] of Object.entries(
+		provider.providerSourceFiles ?? {},
+	)) {
+		sources.push({ field: `sourceFiles.${filePath}`, source });
+	}
+
+	for (const [operationKey, operation] of Object.entries(
+		provider.operations ?? {},
+	)) {
+		const source = getOperationSource(operation);
+		if (source) {
+			sources.push({
+				field: `operations.${operationKey}.handler`,
+				source,
+			});
+		}
+	}
+
+	for (const { field, source } of sources) {
+		for (const item of SELF_HOSTED_BROWSER_PATTERNS) {
+			item.pattern.lastIndex = 0;
+			if (!item.pattern.test(source)) {
+				continue;
+			}
+			diagnostics.push({
+				rule: item.rule,
+				level,
+				field,
+				message: item.message,
+			});
+		}
+	}
+
+	return diagnostics;
+}
+
 export function lintOperation(op: {
-	description: string;
+	description?: string;
+	descriptionKey?: string;
+	whenToUse?: readonly string[];
+	whenToUseKeys?: readonly string[];
+	whenNotToUse?: readonly string[];
+	whenNotToUseKeys?: readonly string[];
 	input: unknown;
 	output: unknown;
 	fixtures?: unknown;
-	inputExamples?: unknown[];
+	inputExamples?: readonly unknown[];
 	derivations?: Record<string, string>;
 }): LintDiagnostic[] {
 	const diagnostics: LintDiagnostic[] = [];
 	const description = op.description ?? "";
+	const hasDescriptionKey =
+		typeof op.descriptionKey === "string" && op.descriptionKey.length > 0;
 
-	if (description.length < 150) {
+	if (description.trim().length > 0 && !hasDescriptionKey) {
 		diagnostics.push({
-			rule: "description-min-length",
+			rule: "operation-description-raw-prose",
 			level: "error",
 			field: "description",
-			message: "Operation description must be at least 150 characters.",
+			message:
+				"Operation description must use descriptionKey instead of raw static prose.",
 		});
 	}
 
-	const lowerDescription = description.toLowerCase();
-	if (
-		!(lowerDescription.includes("use") && lowerDescription.includes("when"))
-	) {
+	if (!hasDescriptionKey && description.length < 150) {
 		diagnostics.push({
-			rule: "description-has-when-clause",
-			level: "warn",
+			rule: "description-min-length",
+			level: "error",
 			field: "description",
-			message: 'Operation description should include both "use" and "when".',
+			message: "Operation description must be at least 150 characters.",
 		});
 	}
 
-	for (const field of uniqueFields(
-		collectMissingDescriptions(op.input, "input"),
-	)) {
+	if ((op.whenToUse?.length ?? 0) > 0 && !(op.whenToUseKeys?.length ?? 0)) {
 		diagnostics.push({
-			rule: "all-fields-described",
+			rule: "operation-when-to-use-raw-prose",
 			level: "error",
-			field,
-			message: `Schema field "${field}" is missing a description.`,
+			field: "whenToUse",
+			message:
+				"Operation whenToUse must use whenToUseKeys instead of raw static prose.",
 		});
 	}
 
-	for (const field of uniqueFields(
-		collectMissingDescriptions(op.output, "output"),
-	)) {
+	if (
+		(op.whenNotToUse?.length ?? 0) > 0 &&
+		!(op.whenNotToUseKeys?.length ?? 0)
+	) {
 		diagnostics.push({
-			rule: "all-fields-described",
+			rule: "operation-when-not-to-use-raw-prose",
 			level: "error",
-			field,
-			message: `Schema field "${field}" is missing a description.`,
+			field: "whenNotToUse",
+			message:
+				"Operation whenNotToUse must use whenNotToUseKeys instead of raw static prose.",
+		});
+	}
+
+	const lowerDescription = description.toLowerCase();
+	if (
+		!hasDescriptionKey &&
+		!(lowerDescription.includes("use") && lowerDescription.includes("when"))
+	) {
+		diagnostics.push({
+			rule: "description-has-when-clause",
+			level: "warn",
+			field: "description",
+			message: 'Operation description should include both "use" and "when".',
 		});
 	}
 
+	diagnostics.push(
+		...collectSchemaDescriptionKeyDiagnostics(op.input, "input"),
+		...collectSchemaDescriptionKeyDiagnostics(op.output, "output"),
+	);
+
 	if (!hasBidirectionalFixtures(op.fixtures)) {
 		diagnostics.push({
 			rule: "fixtures-both-directions",
@@ -511,39 +930,80 @@ export function lintOperation(op: {
 		});
 	}
 
+	for (const field of uniqueFields(
+		collectUnmarkedSensitiveFields(op.input, "input"),
+	)) {
+		diagnostics.push({
+			rule: "sensitive-field-unmarked",
+			level: "warn",
+			field,
+			message: `Schema field "${field}" looks sensitive; mark it with fields.*(), field(..., { sensitive: true }), or sensitive(...).`,
+		});
+	}
+
+	for (const field of uniqueFields(
+		collectUnmarkedSensitiveFields(op.output, "output"),
+	)) {
+		diagnostics.push({
+			rule: "sensitive-field-unmarked",
+			level: "warn",
+			field,
+			message: `Schema field "${field}" looks sensitive; mark it with fields.*(), field(..., { sensitive: true }), or sensitive(...).`,
+		});
+	}
+
 	return diagnostics;
 }
 
-export function lintProvider(provider: {
-	id?: string;
-	allowedHosts?: string[];
-	auth?: ProviderAuthLike;
-	credential?: {
-		keys?: string[];
-		storesReusableSecret?: boolean;
-		justification?: string;
-	};
-	context?: {
-		keys?: string[];
-	};
-	authFlowSource?: string;
-	operations?: Record<
-		string,
-		{
-			description?: string;
-			input: unknown;
-			output: unknown;
-			fixtures?: unknown;
-			inputExamples?: unknown[];
-			derivations?: Record<string, string>;
-		}
-	>;
-	reviewed?: string;
-}): LintDiagnostic[] {
+export function lintProvider(
+	provider: {
+		id?: string;
+		allowedHosts?: readonly string[];
+		stealth?: unknown;
+		auth?: ProviderAuthLike;
+		credential?: {
+			keys?: readonly string[];
+			storesReusableSecret?: boolean;
+			justification?: string;
+		};
+		context?: {
+			keys?: readonly string[];
+		};
+		authFlowSource?: string;
+		providerSourceFiles?: Record<string, string>;
+		operations?: Record<
+			string,
+			{
+				description?: string;
+				descriptionKey?: string;
+				whenToUse?: readonly string[];
+				whenToUseKeys?: readonly string[];
+				whenNotToUse?: readonly string[];
+				whenNotToUseKeys?: readonly string[];
+				input: unknown;
+				output: unknown;
+				fixtures?: unknown;
+				inputExamples?: readonly unknown[];
+				derivations?: Record<string, string>;
+				handler?: unknown;
+				source?: string;
+			}
+		>;
+		meta?: {
+			contract?: ProviderContractMetaLike;
+		};
+		reviewed?: string;
+	},
+	options: ProviderLintOptions = {},
+): LintDiagnostic[] {
 	const diagnostics: LintDiagnostic[] = [
 		...lintAllowedHosts(provider.id, provider.allowedHosts),
 		...lintReviewed(provider.id, provider.reviewed),
 		...lintAuthModel(provider),
+		...lintStealthTransportUsage(provider),
+		...lintCredentialWriteUsage(provider),
+		...lintPlaywrightDirectImports(provider),
+		...lintSelfHostedBrowserPatterns(provider, options),
 	];
 
 	if (!provider.operations) {
@@ -553,14 +1013,28 @@ export function lintProvider(provider: {
 	diagnostics.push(
 		...Object.entries(provider.operations).flatMap(
 			([operationKey, operation]) =>
-				lintOperation({
-					description: operation.description ?? "",
-					input: operation.input,
-					output: operation.output,
-					fixtures: operation.fixtures,
-					inputExamples: operation.inputExamples,
-					derivations: operation.derivations,
-				}).map((diagnostic) => ({
+				[
+					...lintOperation({
+						description: operation.description ?? "",
+						descriptionKey: operation.descriptionKey,
+						whenToUse: operation.whenToUse,
+						whenToUseKeys: operation.whenToUseKeys,
+						whenNotToUse: operation.whenNotToUse,
+						whenNotToUseKeys: operation.whenNotToUseKeys,
+						input: operation.input,
+						output: operation.output,
+						fixtures: operation.fixtures,
+						inputExamples: operation.inputExamples,
+						derivations: operation.derivations,
+					}),
+					...lintPublicSchemaFieldNames(
+						provider.id,
+						operationKey,
+						operation.input,
+						operation.output,
+						provider.meta?.contract?.publicSchemaFieldNames === "normalized",
+					),
+				].map((diagnostic) => ({
 					...diagnostic,
 					field: diagnostic.field
 						? `operations.${operationKey}.${diagnostic.field}`