@apifuse/provider-sdk 2.1.0-beta.2 → 2.1.0-beta.4

package/bin/apifuse-submit-check.ts

@@ -0,0 +1,1052 @@
+#!/usr/bin/env bun
+
+import { existsSync, readFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { z } from "zod";
+
+import packageJson from "../package.json";
+import type { ProviderDefinition } from "../src";
+import {
+	loadProviderLocaleCatalogs,
+	type ProviderLocale,
+	validateProviderLocaleCatalogs,
+} from "../src/i18n";
+import { APIFUSE_DESCRIPTION_KEY_META_KEY } from "../src/schema";
+import { type CheckResult, runChecks } from "./apifuse-check";
+
+const TIERS = ["bronze", "silver", "gold", "diamond"] as const;
+const TIER_VALUES: ReadonlySet<string> = new Set(TIERS);
+type BountyTier = (typeof TIERS)[number];
+
+type CheckLevel = "blocker" | "warn" | "info";
+type CheckStatus = "pass" | "fail" | "warn" | "not_applicable";
+type Verdict = "ready" | "reviewable_with_warnings" | "blocked";
+
+export type SubmitCheck = {
+	id: string;
+	category: string;
+	level: CheckLevel;
+	status: CheckStatus;
+	points: number;
+	maxPoints: number;
+	message: string;
+	remediation?: string;
+	evidence?: string[];
+};
+
+export type SubmitCheckReport = {
+	schemaVersion: 1;
+	generatedAt: string;
+	provider: {
+		id: string;
+		version: string;
+		runtime: string;
+		authMode: string;
+		sdkVersion: string;
+		tier?: BountyTier;
+	};
+	score: {
+		total: number;
+		max: 100;
+		verdict: Verdict;
+	};
+	summary: {
+		blockers: number;
+		warnings: number;
+		passed: number;
+	};
+	checks: SubmitCheck[];
+};
+
+type CliArgs = {
+	isJson: boolean;
+	markdownPath?: string;
+	providerPath?: string;
+	smokeNote?: string;
+	tier?: BountyTier;
+};
+
+type SecretFinding = {
+	label: string;
+	file: string;
+};
+
+const CATEGORY_MAX_POINTS = {
+	definition: 15,
+	operations: 15,
+	fixtures: 15,
+	health: 15,
+	smoke: 10,
+	auth: 10,
+	security: 10,
+	docs: 10,
+} as const;
+
+const REQUIRED_PUBLIC_PROVIDER_LOCALES = [
+	"en",
+	"ko",
+] as const satisfies readonly ProviderLocale[];
+
+const HELP_TEXT = `Usage: apifuse submit-check [path] [--tier bronze|silver|gold|diamond] [--json] [--markdown <path>] [--smoke-note <text>]
+Alias: apifuse bounty-check [path]
+Default: apifuse submit-check .`;
+
+export async function main() {
+	try {
+		const args = parseArgs(normalizeArgs(process.argv.slice(2)));
+
+		if (args.isJson && process.argv.includes("--help")) {
+			console.log(JSON.stringify({ help: HELP_TEXT }));
+			return;
+		}
+
+		const providerRoot = resolveProviderRoot(args.providerPath ?? ".");
+		const report = await buildSubmitCheckReport(providerRoot, args);
+
+		if (args.markdownPath) {
+			await writeFile(
+				resolve(process.cwd(), args.markdownPath),
+				renderMarkdown(report),
+			);
+		}
+
+		if (args.isJson) {
+			console.log(JSON.stringify(report, null, 2));
+		} else {
+			console.log(renderText(report));
+			if (args.markdownPath) {
+				console.log(`\nMarkdown report: ${args.markdownPath}`);
+			}
+		}
+
+		if (report.score.verdict === "blocked") {
+			process.exit(1);
+		}
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	}
+}
+
+function normalizeArgs(argv: string[]): string[] {
+	const [command, ...rest] = argv;
+	return command === "submit-check" || command === "bounty-check" ? rest : argv;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+	const args: CliArgs = { isJson: false };
+
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (!arg) continue;
+
+		if (arg === "--help" || arg === "-h") {
+			console.log(HELP_TEXT);
+			process.exit(0);
+		}
+
+		if (arg === "--json") {
+			args.isJson = true;
+			continue;
+		}
+
+		if (arg === "--markdown") {
+			args.markdownPath = requireValue(argv, index, arg);
+			index += 1;
+			continue;
+		}
+
+		if (arg.startsWith("--markdown=")) {
+			args.markdownPath = arg.slice("--markdown=".length);
+			continue;
+		}
+
+		if (arg === "--smoke-note") {
+			args.smokeNote = requireValue(argv, index, arg);
+			index += 1;
+			continue;
+		}
+
+		if (arg.startsWith("--smoke-note=")) {
+			args.smokeNote = arg.slice("--smoke-note=".length);
+			continue;
+		}
+
+		if (arg === "--tier") {
+			args.tier = parseTier(requireValue(argv, index, arg));
+			index += 1;
+			continue;
+		}
+
+		if (arg.startsWith("--tier=")) {
+			args.tier = parseTier(arg.slice("--tier=".length));
+			continue;
+		}
+
+		if (arg.startsWith("-")) {
+			throw new Error(`Unknown option: ${arg}`);
+		}
+
+		if (!args.providerPath) {
+			args.providerPath = arg;
+			continue;
+		}
+
+		throw new Error(`Unexpected argument: ${arg}`);
+	}
+
+	return args;
+}
+
+function requireValue(argv: string[], index: number, label: string): string {
+	const value = argv[index + 1];
+	if (!value) {
+		throw new Error(`Missing value for ${label}.`);
+	}
+	return value;
+}
+
+function parseTier(value: string): BountyTier {
+	if (isBountyTier(value)) {
+		return value;
+	}
+	throw new Error(
+		`Invalid --tier "${value}". Expected one of: ${TIERS.join(", ")}`,
+	);
+}
+
+function isBountyTier(value: string): value is BountyTier {
+	return TIER_VALUES.has(value);
+}
+
+export async function buildSubmitCheckReport(
+	providerRoot: string,
+	args: { smokeNote?: string; tier?: BountyTier } = {},
+): Promise<SubmitCheckReport> {
+	const checks: SubmitCheck[] = [];
+	const baseChecks = await safeRunChecks(providerRoot);
+	const provider = await safeLoadProvider(providerRoot);
+
+	checks.push(...scoreBaseChecks(baseChecks));
+
+	if (provider) {
+		checks.push(scoreLocaleCatalog(providerRoot, provider));
+		checks.push(scoreOperationMetadata(provider));
+		checks.push(scoreFixtureCoverage(provider));
+		checks.push(scoreHealthCoverage(provider));
+		checks.push(scoreAuthSafety(provider));
+		checks.push(scoreSmokeEvidence(args.smokeNote));
+		checks.push(...scoreProviderDocs(providerRoot));
+		checks.push(scoreSecrets(providerRoot));
+	} else {
+		checks.push(
+			blocker(
+				"provider-load",
+				"definition",
+				"Provider could not be loaded.",
+				"Fix index.ts so it default-exports defineProvider(...).",
+				CATEGORY_MAX_POINTS.definition,
+			),
+		);
+	}
+
+	const total = clamp(
+		Math.round(checks.reduce((sum, check) => sum + check.points, 0)),
+		0,
+		100,
+	);
+	const blockers = checks.filter(
+		(check) => check.level === "blocker" && check.status === "fail",
+	).length;
+	const warnings = checks.filter((check) => check.status === "warn").length;
+	const passed = checks.filter((check) => check.status === "pass").length;
+	const verdict: Verdict =
+		blockers > 0
+			? "blocked"
+			: total >= 90 && warnings === 0
+				? "ready"
+				: "reviewable_with_warnings";
+
+	return {
+		schemaVersion: 1,
+		generatedAt: new Date().toISOString(),
+		provider: {
+			id: provider?.id ?? basename(providerRoot),
+			version: provider?.version ?? "unknown",
+			runtime: provider?.runtime ?? "unknown",
+			authMode: provider?.auth?.mode ?? "none",
+			sdkVersion: packageJson.version,
+			...(args.tier ? { tier: args.tier } : {}),
+		},
+		score: { total, max: 100, verdict },
+		summary: { blockers, warnings, passed },
+		checks,
+	};
+}
+
+async function safeRunChecks(providerRoot: string): Promise<CheckResult[]> {
+	try {
+		return await runChecks(providerRoot);
+	} catch (error) {
+		return [
+			{
+				message: "Base provider checks can run",
+				passed: false,
+				details: [error instanceof Error ? error.message : String(error)],
+			},
+		];
+	}
+}
+
+function scoreBaseChecks(results: CheckResult[]): SubmitCheck[] {
+	const failed = results.filter((result) => !result.passed);
+	if (failed.length > 0) {
+		return [
+			{
+				id: "base-checks",
+				category: "definition",
+				level: "blocker",
+				status: "fail",
+				points: 0,
+				maxPoints: CATEGORY_MAX_POINTS.definition,
+				message: "Base provider checks failed.",
+				remediation:
+					"Run `bun run check` and fix every failing item before bounty submission.",
+				evidence: failed.map((result) =>
+					redact(`${result.message}: ${(result.details ?? []).join("; ")}`),
+				),
+			},
+		];
+	}
+
+	return [
+		{
+			id: "base-checks",
+			category: "definition",
+			level: "info",
+			status: "pass",
+			points: CATEGORY_MAX_POINTS.definition,
+			maxPoints: CATEGORY_MAX_POINTS.definition,
+			message: "Base provider checks passed.",
+			evidence: results.map((result) => result.message),
+		},
+	];
+}
+
+function scoreLocaleCatalog(
+	providerRoot: string,
+	provider: ProviderDefinition,
+): SubmitCheck {
+	const requiredKeys = collectProviderRequiredLocaleKeys(provider);
+	if (requiredKeys.length === 0) {
+		return pass(
+			"locale-catalog",
+			"operations",
+			"No key-owned provider metadata or operation metadata requires locale catalog validation.",
+			0,
+		);
+	}
+
+	try {
+		const availableLocales = REQUIRED_PUBLIC_PROVIDER_LOCALES.filter((locale) =>
+			existsSync(join(providerRoot, "locales", `${locale}.json`)),
+		);
+		const catalogs = loadProviderLocaleCatalogs({
+			providerDir: providerRoot,
+			locales: availableLocales,
+		});
+		const validation = validateProviderLocaleCatalogs({
+			catalogs,
+			requiredLocales: REQUIRED_PUBLIC_PROVIDER_LOCALES,
+			requiredKeys,
+		});
+		if (!validation.ok) {
+			return blocker(
+				"locale-catalog",
+				"operations",
+				"Provider locale catalog is missing required public-provider copy.",
+				"Add provider-local locales/en.json and locales/ko.json values for every provider metadata key, operation descriptionKey, and .describeKey() or describeKey() schema field.",
+				0,
+				validation.issues.map(
+					(issue) => `${issue.locale}:${issue.key}: ${issue.message}`,
+				),
+			);
+		}
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return blocker(
+			"locale-catalog",
+			"operations",
+			"Provider locale catalog is missing required public-provider copy.",
+			"Add provider-local locales/en.json and locales/ko.json values for every provider metadata key, operation descriptionKey, and .describeKey() or describeKey() schema field.",
+			0,
+			[`*:*: ${message}`],
+		);
+	}
+
+	return pass(
+		"locale-catalog",
+		"operations",
+		"Required provider and operation locale keys resolve in locales/en.json and locales/ko.json.",
+		0,
+	);
+}
+
+function collectProviderRequiredLocaleKeys(
+	provider: ProviderDefinition,
+): string[] {
+	const keys = new Set<string>();
+
+	addLocaleKeys(keys, [
+		provider.meta.descriptionKey,
+		provider.meta.docTitleKey,
+		provider.meta.docDescriptionKey,
+		provider.meta.docSummaryKey,
+		provider.meta.docMarkdownKey,
+	]);
+
+	const publicProfile = provider.meta.publicProfile;
+	if (publicProfile) {
+		addLocaleKeys(keys, [
+			publicProfile.displayNameKey,
+			publicProfile.shortDescriptionKey,
+			publicProfile.longDescriptionKey,
+			publicProfile.setupSummaryKey,
+			...(publicProfile.capabilityKeys ?? []),
+			...(publicProfile.examplePromptKeys ?? []),
+			...(publicProfile.requirementKeys ?? []),
+			...(publicProfile.limitationKeys ?? []),
+		]);
+	}
+
+	for (const operation of Object.values(provider.operations)) {
+		addLocaleKeys(keys, [
+			operation.descriptionKey,
+			operation.docs?.titleKey,
+			operation.docs?.descriptionKey,
+			operation.docs?.summaryKey,
+			operation.docs?.markdownKey,
+			...(operation.whenToUseKeys ?? []),
+			...(operation.whenNotToUseKeys ?? []),
+			...collectSchemaDescriptionKeys(operation.input),
+			...collectSchemaDescriptionKeys(operation.output),
+		]);
+	}
+
+	return Array.from(keys);
+}
+
+function addLocaleKeys(keys: Set<string>, values: readonly unknown[]): void {
+	for (const key of values) {
+		if (typeof key === "string" && key.length > 0) {
+			keys.add(key);
+		}
+	}
+}
+
+function collectSchemaDescriptionKeys(schema: unknown): string[] {
+	if (!(schema instanceof z.ZodType)) {
+		return [];
+	}
+	const jsonSchema = z.toJSONSchema(schema);
+	if (!isRecord(jsonSchema)) {
+		return [];
+	}
+	const keys: string[] = [];
+	collectJsonSchemaDescriptionKeys(jsonSchema, keys);
+	return keys;
+}
+
+function collectJsonSchemaDescriptionKeys(
+	schema: Record<string, unknown>,
+	keys: string[],
+): void {
+	const descriptionKey = schema[APIFUSE_DESCRIPTION_KEY_META_KEY];
+	if (typeof descriptionKey === "string" && descriptionKey.length > 0) {
+		keys.push(descriptionKey);
+	}
+
+	for (const value of Object.values(schema)) {
+		if (isRecord(value)) {
+			collectJsonSchemaDescriptionKeys(value, keys);
+		} else if (Array.isArray(value)) {
+			for (const item of value) {
+				if (isRecord(item)) {
+					collectJsonSchemaDescriptionKeys(item, keys);
+				}
+			}
+		}
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function scoreOperationMetadata(provider: ProviderDefinition): SubmitCheck {
+	const operations = Object.entries(provider.operations);
+	const weakDescriptions = operations
+		.filter(([, operation]) => {
+			// Hard-cut providers move operation copy into locale catalogs via
+			// descriptionKey instead of raw inline prose; the resolved text length
+			// is enforced at registry catalog-build time, matching how lintOperation
+			// skips the raw-description min-length rule when a descriptionKey is set.
+			const hasDescriptionKey =
+				typeof operation.descriptionKey === "string" &&
+				operation.descriptionKey.length > 0;
+			if (hasDescriptionKey) return false;
+			return true;
+		})
+		.map(([operationId]) => operationId);
+	const missingAnnotations = operations
+		.filter(([, operation]) => !operation.annotations)
+		.map(([operationId]) => operationId);
+
+	if (weakDescriptions.length > 0) {
+		return {
+			id: "operation-metadata",
+			category: "operations",
+			level: "blocker",
+			status: "fail",
+			points: 0,
+			maxPoints: CATEGORY_MAX_POINTS.operations,
+			message: "One or more operations have weak descriptions.",
+			remediation:
+				"Add 150+ character English descriptions explaining when to use, when not to use, outputs, and caveats.",
+			evidence: weakDescriptions,
+		};
+	}
+
+	const points =
+		missingAnnotations.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",
+		points,
+		maxPoints: CATEGORY_MAX_POINTS.operations,
+		message:
+			missingAnnotations.length > 0
+				? "Operations are described, but some are missing safety annotations."
+				: "Operation descriptions and metadata are review-ready.",
+		remediation:
+			missingAnnotations.length > 0
+				? "Add annotations such as readOnly, destructive, idempotent, openWorld, rateLimit, or timeoutMs where applicable."
+				: undefined,
+		evidence:
+			missingAnnotations.length > 0
+				? missingAnnotations.map(
+						(operationId) => `${operationId}: missing annotations`,
+					)
+				: operations.map(([operationId]) => operationId),
+	};
+}
+
+function scoreFixtureCoverage(provider: ProviderDefinition): SubmitCheck {
+	const missing = Object.entries(provider.operations)
+		.filter(
+			([, operation]) =>
+				!operation.fixtures?.request || !operation.fixtures?.response,
+		)
+		.map(([operationId]) => operationId);
+	if (missing.length > 0) {
+		return blocker(
+			"fixtures",
+			"fixtures",
+			"One or more operations are missing bidirectional fixtures.",
+			"Add fixtures.request and fixtures.response that parse against operation schemas.",
+			CATEGORY_MAX_POINTS.fixtures,
+			missing,
+		);
+	}
+	return pass(
+		"fixtures",
+		"fixtures",
+		"All operations include bidirectional fixtures.",
+		CATEGORY_MAX_POINTS.fixtures,
+	);
+}
+
+function scoreHealthCoverage(provider: ProviderDefinition): SubmitCheck {
+	const operations = Object.entries(provider.operations);
+	const missing: string[] = [];
+	const placeholder: string[] = [];
+	const unsupported: string[] = [];
+	const generatedStarter: string[] = [];
+
+	for (const [operationId, operation] of operations) {
+		const hasCheck = operation.healthCheck !== undefined;
+		const hasUnsupported = operation.healthCheckUnsupported !== undefined;
+		if (!hasCheck && !hasUnsupported) {
+			missing.push(operationId);
+			continue;
+		}
+		if (hasUnsupported) {
+			const reason = operation.healthCheckUnsupported?.reason ?? "";
+			unsupported.push(operationId);
+			if (/generated local-only scaffold/i.test(reason)) {
+				generatedStarter.push(operationId);
+			}
+			if (
+				/(todo|later|tbd|test fixture|unit test|placeholder|not sure|skip for test)/i.test(
+					reason,
+				)
+			) {
+				placeholder.push(operationId);
+			}
+		}
+	}
+
+	if (missing.length > 0) {
+		return blocker(
+			"health-coverage",
+			"health",
+			"One or more operations lack healthCheck or healthCheckUnsupported.",
+			"Declare a safe healthCheck for read-only upstream probes or a specific healthCheckUnsupported.reason.",
+			CATEGORY_MAX_POINTS.health,
+			missing,
+		);
+	}
+
+	if (placeholder.length > 0) {
+		return {
+			id: "health-coverage",
+			category: "health",
+			level: "warn",
+			status: "warn",
+			points: 8,
+			maxPoints: CATEGORY_MAX_POINTS.health,
+			message: "Some healthCheckUnsupported reasons look placeholder-like.",
+			remediation:
+				"Replace placeholder rationale with a specific reason such as destructive mutation, paid call, credential sensitivity, or upstream flakiness.",
+			evidence: placeholder,
+		};
+	}
+
+	if (generatedStarter.length > 0) {
+		return {
+			id: "health-coverage",
+			category: "health",
+			level: "warn",
+			status: "warn",
+			points: 10,
+			maxPoints: CATEGORY_MAX_POINTS.health,
+			message:
+				"Generated starter operation health rationale is present; replace starter logic before bounty submission.",
+			remediation:
+				"Replace `ping` with real upstream-backed operations and prefer real healthCheck for safe read-only probes.",
+			evidence: generatedStarter,
+		};
+	}
+
+	if (unsupported.length > 0) {
+		return {
+			id: "health-coverage",
+			category: "health",
+			level: "warn",
+			status: "warn",
+			points: 12,
+			maxPoints: CATEGORY_MAX_POINTS.health,
+			message:
+				"Health coverage is declared, with one or more unsupported probes.",
+			remediation:
+				"Reviewers prefer real healthCheck for safe read-only upstream operations.",
+			evidence: unsupported.map(
+				(operationId) => `${operationId}: healthCheckUnsupported`,
+			),
+		};
+	}
+
+	return pass(
+		"health-coverage",
+		"health",
+		"All operations declare real health checks.",
+		CATEGORY_MAX_POINTS.health,
+	);
+}
+
+function scoreSmokeEvidence(smokeNote: string | undefined): SubmitCheck {
+	if (smokeNote?.trim()) {
+		return {
+			id: "local-smoke",
+			category: "smoke",
+			level: "info",
+			status: "pass",
+			points: CATEGORY_MAX_POINTS.smoke,
+			maxPoints: CATEGORY_MAX_POINTS.smoke,
+			message: "Local smoke evidence was provided.",
+			evidence: [redact(smokeNote.trim())],
+		};
+	}
+
+	return {
+		id: "local-smoke",
+		category: "smoke",
+		level: "warn",
+		status: "warn",
+		points: 5,
+		maxPoints: CATEGORY_MAX_POINTS.smoke,
+		message: "No local smoke evidence was provided.",
+		remediation:
+			"Start `bun run dev`, call `/health` and at least one `POST /v1/{operation}`, then rerun with `--smoke-note` or paste notes in the assigned workspace PR.",
+	};
+}
+
+function scoreAuthSafety(provider: ProviderDefinition): SubmitCheck {
+	const authMode = provider.auth?.mode ?? "none";
+	const credentialKeys = provider.credential?.keys ?? [];
+	if (authMode === "credentials" && credentialKeys.length === 0) {
+		return blocker(
+			"auth-safety",
+			"auth",
+			"Credential-backed auth mode is missing credential.keys.",
+			"Declare credential.keys and document local-only connection.secrets debugging.",
+			CATEGORY_MAX_POINTS.auth,
+		);
+	}
+
+	if (authMode === "oauth2" && credentialKeys.length === 0) {
+		return {
+			id: "auth-safety",
+			category: "auth",
+			level: "warn",
+			status: "warn",
+			points: 7,
+			maxPoints: CATEGORY_MAX_POINTS.auth,
+			message: "OAuth auth mode does not declare persisted credential.keys.",
+			remediation:
+				"Generated OAuth starters may begin without keys, but bounty-ready OAuth providers should declare persisted token keys once the real token exchange is implemented.",
+		};
+	}
+
+	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:
+					"Confirm auth.mode and operation annotations match the actual upstream auth model.",
+				evidence: securedOperations.map(([operationId]) => operationId),
+			};
+		}
+	}
+
+	return pass(
+		"auth-safety",
+		"auth",
+		"Auth and credential declarations are internally consistent.",
+		CATEGORY_MAX_POINTS.auth,
+	);
+}
+
+function scoreProviderDocs(providerRoot: string): SubmitCheck[] {
+	const readmePath = resolve(providerRoot, "README.md");
+	if (!existsSync(readmePath)) {
+		return [
+			{
+				id: "submission-docs",
+				category: "docs",
+				level: "warn",
+				status: "warn",
+				points: 4,
+				maxPoints: CATEGORY_MAX_POINTS.docs,
+				message: "Provider README.md is missing.",
+				remediation:
+					"Add README sections for parameters, response shape, examples, auth/env setup, health coverage, and known upstream constraints.",
+			},
+		];
+	}
+
+	const readme = readFileSync(readmePath, "utf8").toLowerCase();
+	const missing = [
+		["parameters", "Parameters"],
+		["response", "Response"],
+		["example", "Example"],
+	].filter(([needle]) => !readme.includes(needle));
+	const mentionsSubmitCheck = readme.includes("submit-check");
+
+	const points = Math.max(
+		0,
+		CATEGORY_MAX_POINTS.docs -
+			missing.length * 2 -
+			(mentionsSubmitCheck ? 0 : 1),
+	);
+
+	return [
+		{
+			id: "submission-docs",
+			category: "docs",
+			level: missing.length > 0 || !mentionsSubmitCheck ? "warn" : "info",
+			status: missing.length > 0 || !mentionsSubmitCheck ? "warn" : "pass",
+			points,
+			maxPoints: CATEGORY_MAX_POINTS.docs,
+			message:
+				missing.length > 0 || !mentionsSubmitCheck
+					? "Provider README is present but missing some submission evidence guidance."
+					: "Provider README includes expected submission guidance.",
+			remediation:
+				missing.length > 0 || !mentionsSubmitCheck
+					? "Include Parameters, Response, Example, and submit-check evidence guidance."
+					: undefined,
+			evidence: [
+				...missing.map(([, label]) => `missing ${label}`),
+				...(mentionsSubmitCheck ? [] : ["missing submit-check mention"]),
+			],
+		},
+	];
+}
+
+function scoreSecrets(providerRoot: string): SubmitCheck {
+	const findings = findSecretFindings(providerRoot);
+	if (findings.length > 0) {
+		return {
+			id: "secret-scan",
+			category: "security",
+			level: "blocker",
+			status: "fail",
+			points: 0,
+			maxPoints: CATEGORY_MAX_POINTS.security,
+			message:
+				"Potential real credential material was found in shareable files.",
+			remediation:
+				"Remove real secrets from source, README, and fixtures. Use environment variables and local-only connection.secrets instead.",
+			evidence: findings.map((finding) => `${finding.file}: ${finding.label}`),
+		};
+	}
+
+	return pass(
+		"secret-scan",
+		"security",
+		"No high-confidence secrets were found in README, source, package, or fixtures.",
+		CATEGORY_MAX_POINTS.security,
+	);
+}
+
+function findSecretFindings(providerRoot: string): SecretFinding[] {
+	const candidateFiles = [
+		"README.md",
+		"index.ts",
+		"package.json",
+		"__fixtures__/raw.json",
+		"__fixtures__/transform.snap.json",
+	];
+	const findings: SecretFinding[] = [];
+
+	for (const relativePath of candidateFiles) {
+		const filePath = resolve(providerRoot, relativePath);
+		if (!existsSync(filePath)) continue;
+		const content = readFileSync(filePath, "utf8");
+		for (const [label, pattern] of SECRET_PATTERNS) {
+			if (pattern.test(content)) {
+				findings.push({ label, file: relativePath });
+			}
+		}
+	}
+
+	return findings;
+}
+
+const SECRET_PATTERNS: Array<[string, RegExp]> = [
+	[
+		"JWT-like token",
+		/eyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{10,}/,
+	],
+	["GitHub token", /gh[pousr]_[A-Za-z0-9_]{30,}/],
+	["Stripe live key", /(?:sk|rk)_live_[A-Za-z0-9]{20,}/],
+	["Bearer token", /Bearer\s+[A-Za-z0-9._~+/=-]{32,}/i],
+	[
+		"credential field",
+		/"(?:apiKey|api_key|accessToken|access_token|refreshToken|refresh_token|password|secret|sessionCookie|cookie)"\s*:\s*"(?!dev-only|local|example|sample|your-|replace|<)[^"]{16,}"/i,
+	],
+];
+
+async function safeLoadProvider(
+	providerRoot: string,
+): Promise<ProviderDefinition | undefined> {
+	try {
+		return await loadProvider(providerRoot);
+	} catch {
+		return undefined;
+	}
+}
+
+async function loadProvider(
+	providerRoot: string,
+): Promise<ProviderDefinition | undefined> {
+	const entryPath = resolve(providerRoot, "index.ts");
+	if (!existsSync(entryPath)) {
+		return undefined;
+	}
+	const module = (await import(pathToFileURL(entryPath).href)) as {
+		default?: ProviderDefinition;
+	};
+	return module.default;
+}
+
+function resolveProviderRoot(inputPath: string): string {
+	let current = resolve(process.cwd(), inputPath);
+	if (!existsSync(current)) {
+		throw new Error(`Provider path not found: ${inputPath}`);
+	}
+	if (!existsSync(resolve(current, "index.ts"))) {
+		current = dirname(current);
+	}
+	while (!existsSync(resolve(current, "index.ts"))) {
+		const parent = dirname(current);
+		if (parent === current) {
+			throw new Error(`Could not find provider root for: ${inputPath}`);
+		}
+		current = parent;
+	}
+	return current;
+}
+
+function pass(
+	id: string,
+	category: string,
+	message: string,
+	points: number,
+	evidence?: string[],
+): SubmitCheck {
+	return {
+		id,
+		category,
+		level: "info",
+		status: "pass",
+		points,
+		maxPoints: points,
+		message,
+		...(evidence ? { evidence } : {}),
+	};
+}
+
+function blocker(
+	id: string,
+	category: string,
+	message: string,
+	remediation: string,
+	maxPoints: number,
+	evidence?: string[],
+): SubmitCheck {
+	return {
+		id,
+		category,
+		level: "blocker",
+		status: "fail",
+		points: 0,
+		maxPoints,
+		message,
+		remediation,
+		...(evidence ? { evidence: evidence.map(redact) } : {}),
+	};
+}
+
+export function renderText(report: SubmitCheckReport): string {
+	const lines = [
+		`APIFuse Provider Submission Score: ${report.score.total} / ${report.score.max}`,
+		`Verdict: ${report.score.verdict.toUpperCase()}`,
+		`Provider: ${report.provider.id}@${report.provider.version} (${report.provider.runtime}, auth: ${report.provider.authMode})`,
+		`Blockers: ${report.summary.blockers}  Warnings: ${report.summary.warnings}  Passed: ${report.summary.passed}`,
+		"",
+		"Checklist:",
+	];
+
+	for (const check of report.checks) {
+		const marker =
+			check.status === "pass" ? "✓" : check.status === "warn" ? "⚠" : "✗";
+		lines.push(
+			`${marker} [${check.category}] ${check.message} (${check.points}/${check.maxPoints})`,
+		);
+		if (check.remediation) {
+			lines.push(`  Fix: ${check.remediation}`);
+		}
+		for (const evidence of check.evidence ?? []) {
+			lines.push(`  - ${redact(evidence)}`);
+		}
+	}
+
+	return lines.join("\n");
+}
+
+export function renderMarkdown(report: SubmitCheckReport): string {
+	const lines = [
+		"# APIFuse Provider Submission Report",
+		"",
+		`- **Provider**: ${report.provider.id}@${report.provider.version}`,
+		`- **SDK**: ${report.provider.sdkVersion}`,
+		`- **Runtime/Auth**: ${report.provider.runtime} / ${report.provider.authMode}`,
+		...(report.provider.tier
+			? [`- **Bounty tier**: ${report.provider.tier}`]
+			: []),
+		`- **Score**: ${report.score.total}/${report.score.max}`,
+		`- **Verdict**: ${report.score.verdict}`,
+		`- **Blockers**: ${report.summary.blockers}`,
+		`- **Warnings**: ${report.summary.warnings}`,
+		"",
+		"## Checklist",
+		"",
+		"| Status | Category | Check | Points | Remediation |",
+		"|---|---|---|---:|---|",
+	];
+
+	for (const check of report.checks) {
+		const status =
+			check.status === "pass"
+				? "PASS"
+				: check.status === "warn"
+					? "WARN"
+					: "FAIL";
+		lines.push(
+			`| ${status} | ${escapeMarkdown(check.category)} | ${escapeMarkdown(check.message)} | ${check.points}/${check.maxPoints} | ${escapeMarkdown(check.remediation ?? "")} |`,
+		);
+	}
+
+	const evidence = report.checks.flatMap((check) =>
+		(check.evidence ?? []).map((item) => `- **${check.id}**: ${redact(item)}`),
+	);
+	if (evidence.length > 0) {
+		lines.push("", "## Evidence", "", ...evidence);
+	}
+
+	lines.push("");
+	return `${lines.join("\n")}\n`;
+}
+
+function escapeMarkdown(value: string): string {
+	return redact(value).replaceAll("|", "\\|").replaceAll("\n", " ");
+}
+
+function redact(value: string): string {
+	let output = value;
+	for (const [, pattern] of SECRET_PATTERNS) {
+		output = output.replace(toGlobalRegex(pattern), "[REDACTED]");
+	}
+	return output;
+}
+
+function toGlobalRegex(pattern: RegExp): RegExp {
+	return pattern.global
+		? pattern
+		: new RegExp(pattern.source, `${pattern.flags}g`);
+}
+
+function clamp(value: number, min: number, max: number): number {
+	return Math.min(max, Math.max(min, value));
+}
+
+if (import.meta.main) {
+	await main();
+}