@apifuse/provider-sdk 2.2.0-beta.47 → 2.2.0-beta.49

package/bin/apifuse-submit-check.ts

@@ -2947,13 +2947,17 @@ function collectProviderRequiredLocaleKeys(provider: ProviderDefinition): string
 
 	for (const operation of Object.values(provider.operations)) {
 		addLocaleKeys(keys, [
+			operation.titleKey,
 			operation.descriptionKey,
-			operation.docs?.titleKey,
-			operation.docs?.descriptionKey,
-			operation.docs?.summaryKey,
-			operation.docs?.markdownKey,
+			operation.summaryKey,
+			operation.markdownKey,
 			...(operation.whenToUseKeys ?? []),
 			...(operation.whenNotToUseKeys ?? []),
+			...(operation.normalizationNotesKeys ?? []),
+			...(operation.examples ?? []).flatMap((example) => [
+				example.scenarioKey,
+				example.rationaleKey,
+			]),
 			...collectSchemaDescriptionKeys(operation.input),
 			...collectSchemaDescriptionKeys(operation.output),
 		]);
@@ -3020,8 +3024,8 @@ function scoreOperationMetadata(provider: ProviderDefinition): SubmitCheck {
 			return true;
 		})
 		.map(([operationId]) => operationId);
-	const missingAnnotations = operations
-		.filter(([, operation]) => !operation.annotations)
+	const missingRiskClass = operations
+		.filter(([, operation]) => !operation.riskClass)
 		.map(([operationId]) => operationId);
 
 	if (weakDescriptions.length > 0) {
@@ -3033,30 +3037,30 @@ function scoreOperationMetadata(provider: ProviderDefinition): SubmitCheck {
 			points: 0,
 			maxPoints: CATEGORY_MAX_POINTS.operations,
 			message: "One or more operations have weak descriptions.",
-			remediation: `For ${weakDescriptions.join(", ")}, add an operation \`descriptionKey\` backed by \`locales/en.json\` and \`locales/ko.json\`, or add a 150+ character \`description\` explaining when to use it, when not to use it, outputs, and caveats.`,
+			remediation: `For ${weakDescriptions.join(", ")}, add an operation \`descriptionKey\` backed by \`locales/en.json\` and \`locales/ko.json\`.`,
 			evidence: weakDescriptions,
 		};
 	}
 
-	const points = missingAnnotations.length > 0 ? 11 : CATEGORY_MAX_POINTS.operations;
+	const points = missingRiskClass.length > 0 ? 11 : CATEGORY_MAX_POINTS.operations;
 	return {
 		id: "operation-metadata",
 		category: "operations",
-		level: missingAnnotations.length > 0 ? "warn" : "info",
-		status: missingAnnotations.length > 0 ? "warn" : "pass",
+		level: missingRiskClass.length > 0 ? "warn" : "info",
+		status: missingRiskClass.length > 0 ? "warn" : "pass",
 		points,
 		maxPoints: CATEGORY_MAX_POINTS.operations,
 		message:
-			missingAnnotations.length > 0
-				? "Operations are described, but some are missing safety annotations."
+			missingRiskClass.length > 0
+				? "Operations are described, but some are missing a safety classification."
 				: "Operation descriptions and metadata are review-ready.",
 		remediation:
-			missingAnnotations.length > 0
-				? `For ${missingAnnotations.join(", ")}, add \`annotations\` with the applicable safety fields, such as \`readOnly\`, \`destructive\`, \`idempotent\`, \`openWorld\`, \`rateLimit\`, or \`timeoutMs\`.`
+			missingRiskClass.length > 0
+				? `For ${missingRiskClass.join(", ")}, declare the operation's required \`riskClass\` as \`read\`, \`write\`, \`destructive\`, or \`external-send\`.`
 				: undefined,
 		evidence:
-			missingAnnotations.length > 0
-				? missingAnnotations.map((operationId) => `${operationId}: missing annotations`)
+			missingRiskClass.length > 0
+				? missingRiskClass.map((operationId) => `${operationId}: missing riskClass`)
 				: operations.map(([operationId]) => operationId),
 	};
 }
@@ -5332,25 +5336,6 @@ function scoreAuthSafety(provider: ProviderDefinition): SubmitCheck {
 		};
 	}
 
-	if (authMode === "none") {
-		const securedOperations = Object.entries(provider.operations).filter(
-			([, operation]) => operation.annotations?.openWorld === false,
-		);
-		if (securedOperations.length > 0) {
-			return {
-				id: "auth-safety",
-				category: "auth",
-				level: "warn",
-				status: "warn",
-				points: 7,
-				maxPoints: CATEGORY_MAX_POINTS.auth,
-				message: "Provider is no-auth but at least one operation is not marked openWorld.",
-				remediation: `Either set \`auth.mode\` to the upstream auth model, or mark these public no-auth operations with \`annotations.openWorld: true\`: ${securedOperations.map(([operationId]) => operationId).join(", ")}.`,
-				evidence: securedOperations.map(([operationId]) => operationId),
-			};
-		}
-	}
-
 	return pass(
 		"auth-safety",
 		"auth",

package/dist/cli/commands.d.ts

@@ -1,4 +1,4 @@
-export type ApifuseCommandName = "create" | "dev" | "check" | "sync-assets" | "migrate-shape" | "submit-check" | "bounty-check" | "record" | "test" | "perf";
+export type ApifuseCommandName = "create" | "dev" | "check" | "sync-assets" | "migrate-shape" | "migrate-operation-declaration" | "submit-check" | "bounty-check" | "record" | "test" | "perf";
 export type ApifuseCommandManifest = {
     name: ApifuseCommandName;
     summary: string;

package/dist/cli/commands.js

@@ -37,6 +37,16 @@ export const COMMAND_MANIFEST = {
         examples: ["apifuse migrate-shape .", "apifuse migrate-shape . --check"],
         modulePath: "./apifuse-migrate-shape",
     },
+    "migrate-operation-declaration": {
+        name: "migrate-operation-declaration",
+        summary: "Migrate legacy nested operation declarations to the ADR-0009 flat shape, refusing ambiguous safety or metadata.",
+        usage: "apifuse migrate-operation-declaration [path] [--check] [--json]",
+        examples: [
+            "apifuse migrate-operation-declaration .",
+            "apifuse migrate-operation-declaration . --check --json",
+        ],
+        modulePath: "./apifuse-migrate-operation-declaration",
+    },
     "submit-check": {
         name: "submit-check",
         summary: "Score provider bounty submission readiness and emit checklist evidence.",
@@ -89,6 +99,7 @@ export const COMMAND_ORDER = [
     "check",
     "sync-assets",
     "migrate-shape",
+    "migrate-operation-declaration",
     "submit-check",
     "record",
     "test",

package/dist/cli/migrate-operation-declaration.d.ts

@@ -0,0 +1,59 @@
+export type OperationDeclarationRefusalReason = "no_safety" | "safety_conflict" | "locale_key_conflict" | "connection_mode_conflict" | "execution_conflict" | "approval_conflict" | "non_literal" | "unsupported_member" | "factory_composed_operations" | "source_syntax" | "codemod_syntax" | "missing_english_locale" | "operation_id_unresolved" | "examples_conflict" | "locale_todo_conflict";
+export type OperationDeclarationRefusal = {
+    readonly file: string;
+    readonly operationKey: string;
+    readonly reason: OperationDeclarationRefusalReason;
+    readonly detail: string;
+};
+export type LocaleTodo = {
+    readonly localeFile: string;
+    readonly operationKey: string;
+    readonly key: string;
+    readonly originalProse: string;
+};
+export type OperationDeclarationMigration = {
+    readonly status: "migrated";
+    readonly code: string;
+    readonly operations: number;
+    readonly localeTodos: readonly LocaleTodo[];
+} | {
+    readonly status: "unchanged";
+    readonly code: string;
+    readonly operations: number;
+} | {
+    readonly status: "refused";
+    readonly refusals: readonly OperationDeclarationRefusal[];
+};
+export type OperationDeclarationMigrationOptions = {
+    /** Exact operation ids proven from a static operations map, keyed by local binding name. */
+    readonly operationIds?: ReadonlyMap<string, string>;
+    /** Locale paths relative to the provider root. */
+    readonly localeFiles?: readonly string[];
+};
+/**
+ * Rewrite every operation declaration in one TypeScript module.
+ *
+ * The function is file-atomic: a single refusal discards every planned edit.
+ * It uses AST ranges as a string/comment/template-aware brace balancer and
+ * copies every untouched source slice byte-for-byte.
+ */
+export declare function migrateOperationDeclaration(sourceText: string, fileName: string, options?: OperationDeclarationMigrationOptions): OperationDeclarationMigration;
+/** Parse a proposed rewrite and classify a codemod-introduced syntax failure. */
+export declare function verifyOperationDeclarationRewrite(code: string, fileName: string): OperationDeclarationRefusal | undefined;
+export type OperationDeclarationRepositoryResult = {
+    readonly status: "migrated" | "would-migrate" | "unchanged";
+    readonly providerRoot: string;
+    readonly changedFiles: readonly string[];
+    readonly operationCount: number;
+    readonly sidecar?: string;
+    readonly localeTodoCount: number;
+} | {
+    readonly status: "refused";
+    readonly providerRoot: string;
+    readonly refusals: readonly OperationDeclarationRefusal[];
+};
+/** Run the file transform repository-wide, committing writes only if every file is provable. */
+export declare function migrateOperationDeclarationRepository(providerRootInput: string, options?: {
+    readonly check?: boolean;
+}): OperationDeclarationRepositoryResult;
+export declare function renderLocaleTodoSidecar(todos: readonly LocaleTodo[]): string;