@apifuse/provider-sdk 2.2.0-beta.63 → 2.2.0-beta.64

package/src/lint.ts

@@ -1,5 +1,3 @@
-import { createRequire } from "node:module";
-
 import type { ZodType } from "zod";
 
 import {
@@ -12,9 +10,11 @@ import {
 	type HandleFieldMeta,
 	type HandleKindDeclaration,
 	handleFieldDescription,
+	handleFieldNameFor,
+	handleHasDirectionalFieldNames,
 	handleIssuerList,
-	isHandleIssuedBy,
 	isHandleFieldMeta,
+	isHandleIssuedBy,
 } from "./handle-meta.js";
 import { PROVIDER_ERROR_CATALOG_NAMESPACE } from "./i18n/error-messages.js";
 import {
@@ -27,19 +27,10 @@ import {
 	isStealthOwnedHeaderName,
 	SDK_OWNED_CHROME_HEADER_PREFIX,
 } from "./runtime/stealth-owned-headers.js";
+import { lintRuntimeBoundary, scriptKindForSourceFile } from "./runtime-boundary-lint.js";
 import { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_SENSITIVE_META_KEY } from "./schema.js";
 import type { AuthMode, OperationApprovalPolicy, OperationRiskClass } from "./types.js";
-
-const requireModule = createRequire(import.meta.url);
-// `typeof import(...)` keeps the type without emitting a static import: the
-// typescript package is a CLI-only dependency and src/lint.ts is production
-// runtime, which the typescript-import-boundary test enforces.
-let typeScriptModule: typeof import("typescript") | undefined;
-
-function getTypeScript(): typeof import("typescript") {
-	typeScriptModule ??= requireModule("typescript") as typeof import("typescript");
-	return typeScriptModule;
-}
+import { getTypeScript } from "./typescript-module.js";
 
 type AuthModeLike =
 	| "none"
@@ -202,12 +193,17 @@ type ProviderLintOptions = {
 	mode?: ProviderLintMode;
 };
 
+/**
+ * A non-blocking audit line: a finding the author acknowledged with
+ * `// @apifuse-allow <rule>: <reason>`, kept visible in `apifuse check` output.
+ */
 export interface ProviderLintInformation {
 	rule: string;
 	message: string;
 	field?: string;
 }
 
+/** Diagnostics plus the acknowledged findings that accompany them. */
 export interface ProviderLintResult {
 	diagnostics: LintDiagnostic[];
 	information: ProviderLintInformation[];
@@ -1148,14 +1144,17 @@ function isReportedOwnedHeaderName(value: string | undefined): boolean {
 	return name.startsWith(OWNED_CLIENT_HINT_HEADER_PREFIX);
 }
 
-function collectBrowserVersionLiteralFindings(source: string): BrowserVersionLiteralFinding[] {
+function collectBrowserVersionLiteralFindings(
+	fileName: string,
+	source: string,
+): BrowserVersionLiteralFinding[] {
 	const ts = getTypeScript();
 	const sourceFile = ts.createSourceFile(
-		"provider-source.ts",
+		fileName,
 		source,
 		ts.ScriptTarget.Latest,
 		true,
-		ts.ScriptKind.TSX,
+		scriptKindForSourceFile(ts, fileName),
 	);
 	let findings: BrowserVersionLiteralFinding[] = [];
 	const seen = new Set<string>();
@@ -1297,7 +1296,7 @@ function browserVersionLiteralMessage(finding: BrowserVersionLiteralFinding): st
 }
 
 function lintBrowserVersionLiterals(provider: ProviderSourceLike): LintDiagnostic[] {
-	const sources: Array<{ field: string; source: string }> = [];
+	const sources: Array<{ field: string; fileName: string; source: string }> = [];
 	const sourceFiles = Object.entries(provider.providerSourceFiles ?? {}).filter(
 		([filePath]) =>
 			JAVASCRIPT_SOURCE_FILE_PATTERN.test(filePath) &&
@@ -1306,19 +1305,28 @@ function lintBrowserVersionLiterals(provider: ProviderSourceLike): LintDiagnosti
 	);
 	if (sourceFiles.length > 0) {
 		for (const [filePath, source] of sourceFiles) {
-			sources.push({ field: `sourceFiles.${filePath}`, source });
+			sources.push({ field: `sourceFiles.${filePath}`, fileName: filePath, source });
 		}
 	} else {
 		if (provider.authFlowSource)
-			sources.push({ field: "auth.flow", source: provider.authFlowSource });
+			sources.push({
+				field: "auth.flow",
+				fileName: "auth-flow.ts",
+				source: provider.authFlowSource,
+			});
 		for (const [operationKey, operation] of Object.entries(provider.operations ?? {})) {
 			const source = getOperationSource(operation);
-			if (source) sources.push({ field: `operations.${operationKey}.handler`, source });
+			if (source)
+				sources.push({
+					field: `operations.${operationKey}.handler`,
+					fileName: `${operationKey}.ts`,
+					source,
+				});
 		}
 	}
 
-	return sources.flatMap(({ field, source }) =>
-		collectBrowserVersionLiteralFindings(source).map((finding) => ({
+	return sources.flatMap(({ field, fileName, source }) =>
+		collectBrowserVersionLiteralFindings(fileName, source).map((finding) => ({
 			rule: "browser-version-literal",
 			level: "error" as const,
 			field,
@@ -1995,6 +2003,7 @@ function readHandleKindDeclarations(value: unknown): HandleKindDeclaration[] {
 			typeof record.name === "string" &&
 			(record.type === "cursor" || record.type === "draft") &&
 			typeof record.fieldName === "string" &&
+			(record.outputFieldName === undefined || typeof record.outputFieldName === "string") &&
 			(record.issuedBy === undefined || isHandleIssuedBy(record.issuedBy))
 		);
 	});
@@ -2040,7 +2049,13 @@ function lintHandleDeclarations(provider: {
 		for (const { side, fields } of positions) {
 			for (const occurrence of fields) {
 				const field = `operations.${operationKey}.${occurrence.path}`;
-				const { kind, fieldName } = occurrence.meta;
+				const { kind } = occurrence.meta;
+				// A kind may name one handle differently in each direction (the canon's
+				// `cursor` in, `next_cursor` out). The rule is still exact: each side
+				// must use the key declared for THAT side, so the handle's identity
+				// stays readable from the property key and the round trip has exactly
+				// one edge — read `output`, send back under `input`.
+				const expected = handleFieldNameFor(occurrence.meta, side);
 
 				if (!kindByName.has(kind)) {
 					diagnostics.push({
@@ -2051,12 +2066,16 @@ function lintHandleDeclarations(provider: {
 					});
 				}
 
-				if (occurrence.key !== fieldName) {
+				if (occurrence.key !== expected) {
+					const directional = handleHasDirectionalFieldNames(occurrence.meta);
+					const advice = directional
+						? `Use the kind's ${side} fieldName on every ${side} schema; its ${side === "input" ? "output" : "input"} fieldName is "${handleFieldNameFor(occurrence.meta, side === "input" ? "output" : "input")}".`
+						: "Use the same key in every schema so the LLM sees one name.";
 					diagnostics.push({
 						rule: "handle-field-name",
 						level: "error",
 						field,
-						message: `${providerLabel} operation "${operationKey}" ${side} declares handle kind "${kind}" under property "${occurrence.key}" but the kind's fieldName is "${fieldName}". Use the same key in every schema so the LLM sees one name.`,
+						message: `${providerLabel} operation "${operationKey}" ${side} declares handle kind "${kind}" under property "${occurrence.key}" but the kind's ${directional ? `${side} ` : ""}fieldName is "${expected}". ${advice}`,
 					});
 				}
 
@@ -2085,7 +2104,7 @@ function lintHandleDeclarations(provider: {
 				rule: "handle-field-parity",
 				level: "error",
 				field,
-				message: `${providerLabel} handle kind "${kind.name}" is never issued: no operation output contains its field "${kind.fieldName}". Add ${kind.name}.field() to the issuing operation's output.`,
+				message: `${providerLabel} handle kind "${kind.name}" is never issued: no operation output contains its field "${handleFieldNameFor(kind, "output")}". Add ${kind.name}.field() to the issuing operation's output.`,
 			});
 		}
 		if (!accepted) {
@@ -2093,7 +2112,7 @@ function lintHandleDeclarations(provider: {
 				rule: "handle-field-parity",
 				level: "error",
 				field,
-				message: `${providerLabel} handle kind "${kind.name}" is never accepted: no operation input contains its field "${kind.fieldName}". Add ${kind.name}.field() to the consuming operation's input.`,
+				message: `${providerLabel} handle kind "${kind.name}" is never accepted: no operation input contains its field "${handleFieldNameFor(kind, "input")}". Add ${kind.name}.field() to the consuming operation's input.`,
 			});
 		}
 
@@ -2119,7 +2138,7 @@ function lintHandleDeclarations(provider: {
 				rule: "handle-issued-by",
 				level: "error",
 				field,
-				message: `${providerLabel} handle kind "${kind.name}" declares issuedBy "${known[0]}", but that operation's output has no "${kind.fieldName}" handle field.`,
+				message: `${providerLabel} handle kind "${kind.name}" declares issuedBy "${known[0]}", but that operation's output has no "${handleFieldNameFor(kind, "output")}" handle field.`,
 			});
 		} else {
 			diagnostics.push({
@@ -2130,7 +2149,7 @@ function lintHandleDeclarations(provider: {
 					.map((operationKey) => `"${operationKey}"`)
 					.join(
 						", ",
-					)}, but none of those operations' outputs has a "${kind.fieldName}" handle field. At least one listed issuer must output it.`,
+					)}, but none of those operations' outputs has a "${handleFieldNameFor(kind, "output")}" handle field. At least one listed issuer must output it.`,
 			});
 		}
 	}
@@ -2162,7 +2181,7 @@ const LEGACY_CHOICE_IDENTIFIERS = new Set([
  * the provider) while code inside `${}` interpolations still does. Falls back
  * to a raw-source regex when TypeScript is not installed.
  */
-function findLegacyChoiceUsage(source: string): string | undefined {
+function findLegacyChoiceUsage(fileName: string, source: string): string | undefined {
 	let ts: typeof import("typescript");
 	try {
 		ts = getTypeScript();
@@ -2170,11 +2189,11 @@ function findLegacyChoiceUsage(source: string): string | undefined {
 		return LEGACY_CHOICE_USAGE_PATTERN.exec(source)?.[0];
 	}
 	const file = ts.createSourceFile(
-		"provider.ts",
+		fileName,
 		source,
 		ts.ScriptTarget.Latest,
 		false,
-		ts.ScriptKind.TSX,
+		scriptKindForSourceFile(ts, fileName),
 	);
 	let found: string | undefined;
 	const visit = (node: import("typescript").Node): void => {
@@ -2199,23 +2218,27 @@ function findLegacyChoiceUsage(source: string): string | undefined {
 }
 
 function lintLegacyChoiceUsage(provider: ProviderSourceLike): LintDiagnostic[] {
-	const sources: Array<{ field: string; source: string }> = [];
+	const sources: Array<{ field: string; fileName: string; source: string }> = [];
 
 	if (provider.authFlowSource) {
-		sources.push({ field: "auth.flow", source: provider.authFlowSource });
+		sources.push({ field: "auth.flow", fileName: "auth-flow.ts", source: provider.authFlowSource });
 	}
 	for (const [filePath, source] of Object.entries(provider.providerSourceFiles ?? {})) {
-		sources.push({ field: `sourceFiles.${filePath}`, source });
+		sources.push({ field: `sourceFiles.${filePath}`, fileName: filePath, source });
 	}
 	for (const [operationKey, operation] of Object.entries(provider.operations ?? {})) {
 		const source = getOperationSource(operation);
 		if (source) {
-			sources.push({ field: `operations.${operationKey}.handler`, source });
+			sources.push({
+				field: `operations.${operationKey}.handler`,
+				fileName: `${operationKey}.ts`,
+				source,
+			});
 		}
 	}
 
-	return sources.flatMap(({ field, source }) => {
-		const match = findLegacyChoiceUsage(source);
+	return sources.flatMap(({ field, fileName, source }) => {
+		const match = findLegacyChoiceUsage(fileName, source);
 		if (!match) return [];
 		return [
 			{
@@ -2421,6 +2444,10 @@ export function lintProviderWithInformation(
 		...lintLegacyChoiceUsage(provider),
 		...lintHandleDeclarations(provider),
 	];
+	// Runtime boundary rules (process.env, node:fs/net/child_process, raw
+	// fetch) also yield information entries for `@apifuse-allow` acknowledgements.
+	const runtimeBoundary = lintRuntimeBoundary(getTypeScript(), provider, getOperationSource);
+	diagnostics.push(...runtimeBoundary.diagnostics);
 
 	if (provider.operations) {
 		const authMode = provider.auth?.mode;
@@ -2464,7 +2491,10 @@ export function lintProviderWithInformation(
 	}
 
 	if (!provider.operations) {
-		return applyPinnedWireFieldPaths(provider, diagnostics);
+		return withInformation(
+			applyPinnedWireFieldPaths(provider, diagnostics),
+			runtimeBoundary.information,
+		);
 	}
 
 	diagnostics.push(
@@ -2495,5 +2525,16 @@ export function lintProviderWithInformation(
 		),
 	);
 
-	return applyPinnedWireFieldPaths(provider, diagnostics);
+	return withInformation(
+		applyPinnedWireFieldPaths(provider, diagnostics),
+		runtimeBoundary.information,
+	);
+}
+
+function withInformation(
+	result: ProviderLintResult,
+	information: readonly ProviderLintInformation[],
+): ProviderLintResult {
+	if (information.length === 0) return result;
+	return { diagnostics: result.diagnostics, information: [...information, ...result.information] };
 }

package/src/provider.ts

@@ -166,6 +166,8 @@ export {
 	APIFUSE_HANDLE_META_KEY,
 	HANDLE_KIND_NAME_PATTERN,
 	handleFieldDescription,
+	handleFieldNameFor,
+	handleHasDirectionalFieldNames,
 	isHandleFieldMeta,
 } from "./handle-meta.js";
 export {

package/src/runtime/handle.ts

@@ -27,7 +27,7 @@ import {
 	isDraftKind,
 	type ResultOf,
 } from "../handle.js";
-import { formatHandleIssuers } from "../handle-meta.js";
+import { formatHandleIssuers, handleHasDirectionalFieldNames } from "../handle-meta.js";
 import type {
 	ProviderRequestContext,
 	ProviderRuntimeState,
@@ -248,6 +248,14 @@ export function formatNormalizationClasses(classes: readonly string[]): string {
 // ---------------------------------------------------------------------------
 
 function publicCollapsedMessage(kind: HandleKind): string {
+	// "a new one" is unambiguous only while the kind has one name. When it is
+	// issued under `next_cursor` and accepted under `cursor`, the caller has to
+	// be told which field to read, so use the full recovery sentence — it names
+	// both keys and is identical for invalid / expired / not-found, which is
+	// what keeps the public collapse indistinguishable.
+	if (handleHasDirectionalFieldNames(kind)) {
+		return `\`${kind.fieldName}\` is not valid or has expired. ${handleRecoverySentence(kind)}`;
+	}
 	const issuers = formatHandleIssuers(kind.issuedBy);
 	const again = issuers ? `Call ${issuers} again to get a new one.` : "Request a new one.";
 	return `\`${kind.fieldName}\` is not valid or has expired. ${again}`;

package/src/runtime/ocr.ts

@@ -86,6 +86,10 @@ function createErrorOcrClient(options: ErrorOcrClientOptions): OcrContext {
 	};
 	return tagCapability(
 		{
+			// Own data property: `bindOcrTelemetry` re-spreads the context, so a
+			// getter or prototype member would silently vanish before reaching
+			// provider code.
+			available: false,
 			async recognize() {
 				return unavailable();
 			},
@@ -355,6 +359,7 @@ function createOcrClient(
 	recognize: (request: OcrRecognizeRequest) => Promise<OcrResult>,
 ): OcrContext {
 	return {
+		available: true,
 		recognize,
 		async extractCaptchaText(image, options = {}): Promise<OcrCaptchaResult> {
 			const result = await recognize({ image, hint: "captcha" });