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

package/AUTHORING.md

@@ -900,8 +900,13 @@ Provider runtime code reaches the outside world through the context only:
 `ctx.env.get()` / `ctx.credential` for configuration and secrets, `ctx.files` /
 `ctx.cache` / `ctx.state` for data that must outlive a request. Ambient Node
 and Bun globals bypass `allowedHosts`, proxy policy, retries, redaction, the
-secret presence gate, and telemetry. `apifuse check` reports them (**warn** in
-this release; the level is raised once the fleet is clean):
+secret presence gate, and telemetry. `apifuse check` reports them at **error**
+level — a finding fails `apifuse check` and `apifuse submit-check`, in the
+official and the bounty `standalone` mode alike (the level was `warn` for one
+release as a migration window; the window closed once the fleet's request-path
+hits were fixed or acknowledged — a provider that still carries one sees
+`apifuse check` fail on its next SDK bump and fixes or acknowledges it in that
+same PR):
 
 - `process-env-direct-read` — `process.env.X`, `process.env["X"]`, a bare
   `process.env` object use, `Bun.env`. The `APIFUSE__RUNTIME__*` bootstrap
@@ -931,11 +936,14 @@ Scope is runtime source only: tests, recorded fixtures, `.d.ts`, the root
 `dev.ts` / `start.ts` / `deploy.ts` entrypoints, and the `scripts/`, `tools/`,
 `bin/` directories at the provider root are not scanned. Keep fixture
 recorders, smoke scripts, and other operator tooling under `scripts/`, and do
-not import from there in request-path modules.
+not import from there in request-path modules. `apifuse check` also leaves out
+any directory that is itself a git checkout (a linked worktree such as
+`.worktree/<branch>/`, a nested clone, an initialised submodule): its files are
+another revision, checked in that checkout, not this provider's runtime source.
 
 Acknowledge a deliberate exception on the finding line or the comment-only
 line above it with `// @apifuse-allow <rule>: <reason>`; the finding then
-appears as an `INFO` audit line instead of a warning.
+appears as an `INFO` audit line instead of an error, and the check passes.
 
 ```ts
 // Before: request-path module reads the ambient environment and the disk

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.66
+
+- Release candidate for main commit e7f93a6c71e3bca3a680861c0968e22dbe5d1d40.
+
+## 2.2.0-beta.65
+
+- Release candidate for main commit 4731ac76145caf85a6c340ad0c446371bd24b052.
+
 ## 2.2.0-beta.64
 
 - Release candidate for main commit 0505a938340d08db3ea3e2302cab5f6b5dd2b4e5.

package/bin/apifuse-check.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
 import { z } from "zod";
@@ -226,6 +226,21 @@ function isScannableProviderSourceFile(relativePath: string): boolean {
 	);
 }
 
+/**
+ * A directory under the provider root that is itself a git checkout — a linked
+ * worktree (`.worktree/<branch>/`, whose `.git` is a file pointing at the main
+ * repository), a nested clone (`.git` directory), or an initialised submodule.
+ * Its files are another revision of some repository, not this provider's
+ * runtime source: an older copy of `upstream/` or `scripts/` there would be
+ * linted as if it were request-path code at the root (the tooling-directory
+ * exemption is anchored at the provider root), and its `apifuse check` is run
+ * in that checkout, not here. Git refuses to track a path named `.git`, so the
+ * marker cannot be planted in a committed tree to hide a file from the scan.
+ */
+function isNestedCheckout(directory: string): boolean {
+	return existsSync(join(directory, ".git"));
+}
+
 function collectProviderSourceFiles(providerRoot: string): Record<string, string> {
 	const sources: Record<string, string> = {};
 	// `.agents`/`.apifuse` are deliberately not skipped: managed content there
@@ -236,7 +251,7 @@ function collectProviderSourceFiles(providerRoot: string): Record<string, string
 		for (const entry of readdirSync(directory, { withFileTypes: true })) {
 			const path = resolve(directory, entry.name);
 			if (entry.isDirectory()) {
-				if (!skipDirectories.has(entry.name)) {
+				if (!skipDirectories.has(entry.name) && !isNestedCheckout(path)) {
 					visit(path);
 				}
 				continue;
@@ -573,12 +588,56 @@ function checkPackageJson(packageJsonPath: string): CheckResult {
 
 export const PROVIDER_JSON_CHECK_MESSAGE = "provider.json exists with a valid declaration";
 
+/**
+ * Markets a provider may declare as its primary, and the locales the platform
+ * catalogs can carry.
+ *
+ * These mirror `scripts/provider-deploy/provider-locale-coverage.mjs` in the
+ * APIFuse monorepo, which is the policy's source of truth. The duplication is
+ * deliberate and bounded: the monorepo cannot be imported from a provider
+ * checkout, and a *closed* mirror is the point — it keeps a typo
+ * (`primaryMarket: "jp-JP"`) a local failure instead of one that only surfaces
+ * in the monorepo's contract validator days later.
+ */
+const PROVIDER_PRIMARY_MARKETS = ["jp", "kr", "global"] as const;
+const PROVIDER_COVERAGE_LOCALES = ["en", "ko", "ja"] as const;
+const PROVIDER_BASELINE_LOCALE = "en";
+
+/**
+ * Declared locale coverage, optional at schemaVersion 1.
+ *
+ * `apifuse provider declare-locale-coverage` writes this block, and the
+ * monorepo declaration schema has accepted it since the rollout landed. This
+ * check used to close `provider.json` over four keys, which made the only
+ * documented way to clear the monorepo's `LOCALE_COVERAGE_UNDECLARED` finding
+ * turn a green `bun run check` red — the declaration was unfixable from either
+ * side. The fix is to mirror the monorepo schema rather than to stop
+ * validating: the block stays closed over its own two keys so a misspelled
+ * field is still caught here, at authoring time.
+ */
+const providerI18nDeclarationSchema = z
+	.object({
+		primaryMarket: z.enum(PROVIDER_PRIMARY_MARKETS),
+		locales: z
+			.array(z.enum(PROVIDER_COVERAGE_LOCALES))
+			.nonempty()
+			.refine((locales) => new Set(locales).size === locales.length, {
+				message: "i18n.locales must not repeat a locale",
+			})
+			.refine((locales) => locales.includes(PROVIDER_BASELINE_LOCALE), {
+				message: `i18n.locales must include "${PROVIDER_BASELINE_LOCALE}": it is the fallback every other locale resolves through`,
+			})
+			.optional(),
+	})
+	.strict();
+
 const providerDeclarationSchema = z
 	.object({
 		schemaVersion: z.literal(1),
 		providerId: z.string(),
 		owner: z.string(),
 		lifecycle: z.enum(["draft", "ready", "live", "retired"]),
+		i18n: providerI18nDeclarationSchema.optional(),
 	})
 	.strict();
 
@@ -609,7 +668,17 @@ function checkProviderJson(providerJsonPath: string, packageJsonPath: string): C
 		return {
 			message: PROVIDER_JSON_CHECK_MESSAGE,
 			passed: true,
-			details: [`providerId: ${declaration.providerId}`, `lifecycle: ${declaration.lifecycle}`],
+			details: [
+				`providerId: ${declaration.providerId}`,
+				`lifecycle: ${declaration.lifecycle}`,
+				...(declaration.i18n
+					? [
+							`locale coverage: primaryMarket ${declaration.i18n.primaryMarket}${
+								declaration.i18n.locales ? ` (locales: ${declaration.i18n.locales.join(", ")})` : ""
+							}`,
+						]
+					: []),
+			],
 		};
 	} catch (error) {
 		return {