specli 0.0.1

package/fixtures/openapi-auth.json

@@ -0,0 +1,34 @@
+{
+	"openapi": "3.0.3",
+	"info": {
+		"title": "Auth API",
+		"version": "1.0.0"
+	},
+	"servers": [{ "url": "https://api.example.com" }],
+	"components": {
+		"securitySchemes": {
+			"bearerAuth": {
+				"type": "http",
+				"scheme": "bearer",
+				"bearerFormat": "JWT"
+			},
+			"apiKeyAuth": {
+				"type": "apiKey",
+				"in": "header",
+				"name": "X-API-Key"
+			}
+		}
+	},
+	"paths": {
+		"/ping": {
+			"get": {
+				"operationId": "Ping.Get",
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		}
+	}
+}

package/fixtures/openapi-body.json

@@ -0,0 +1,41 @@
+{
+	"openapi": "3.0.3",
+	"info": {
+		"title": "Body API",
+		"version": "1.0.0"
+	},
+	"servers": [{ "url": "https://api.example.com" }],
+	"paths": {
+		"/contacts": {
+			"post": {
+				"operationId": "Contacts.Create",
+				"tags": ["Contacts"],
+				"requestBody": {
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": {
+								"type": "object",
+								"properties": {
+									"name": { "type": "string" }
+								},
+								"required": ["name"]
+							}
+						},
+						"application/x-www-form-urlencoded": {
+							"schema": {
+								"type": "object",
+								"properties": {
+									"name": { "type": "string" }
+								}
+							}
+						}
+					}
+				},
+				"responses": {
+					"200": { "description": "OK" }
+				}
+			}
+		}
+	}
+}

package/fixtures/openapi-collision.json

@@ -0,0 +1,21 @@
+{
+	"openapi": "3.0.3",
+	"info": {
+		"title": "Collision API",
+		"version": "1.0.0"
+	},
+	"paths": {
+		"/contacts": {
+			"get": {
+				"operationId": "Contacts.List",
+				"responses": { "200": { "description": "OK" } }
+			}
+		},
+		"/contacts/search": {
+			"get": {
+				"operationId": "Contacts.List",
+				"responses": { "200": { "description": "OK" } }
+			}
+		}
+	}
+}

package/fixtures/openapi-oauth.json

@@ -0,0 +1,54 @@
+{
+	"openapi": "3.0.3",
+	"info": {
+		"title": "OAuth API",
+		"version": "1.0.0"
+	},
+	"servers": [{ "url": "https://api.example.com" }],
+	"security": [
+		{
+			"oauth": ["read:ping"]
+		},
+		{}
+	],
+	"components": {
+		"securitySchemes": {
+			"oauth": {
+				"type": "oauth2",
+				"flows": {
+					"authorizationCode": {
+						"authorizationUrl": "https://example.com/oauth/authorize",
+						"tokenUrl": "https://example.com/oauth/token",
+						"scopes": {
+							"read:ping": "read ping"
+						}
+					},
+					"clientCredentials": {
+						"tokenUrl": "https://example.com/oauth/token",
+						"scopes": {
+							"read:ping": "read ping",
+							"write:ping": "write ping"
+						}
+					}
+				}
+			}
+		}
+	},
+	"paths": {
+		"/ping": {
+			"get": {
+				"operationId": "Ping.Get",
+				"security": [
+					{
+						"oauth": ["read:ping"]
+					}
+				],
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		}
+	}
+}

package/fixtures/openapi-servers.json

@@ -0,0 +1,35 @@
+{
+	"openapi": "3.0.3",
+	"info": {
+		"title": "Servers API",
+		"version": "1.0.0"
+	},
+	"servers": [
+		{
+			"url": "https://{region}.api.example.com/{basePath}",
+			"description": "Regional server",
+			"variables": {
+				"region": {
+					"default": "us",
+					"enum": ["us", "eu"],
+					"description": "Region code"
+				},
+				"basePath": {
+					"default": "v1"
+				}
+			}
+		}
+	],
+	"paths": {
+		"/ping": {
+			"get": {
+				"operationId": "Ping.Get",
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		}
+	}
+}

package/fixtures/openapi.json

@@ -0,0 +1,87 @@
+{
+	"openapi": "3.0.3",
+	"info": {
+		"title": "Contacts API",
+		"version": "1.0.0"
+	},
+	"servers": [
+		{
+			"url": "https://api.example.com"
+		}
+	],
+	"paths": {
+		"/contacts": {
+			"get": {
+				"operationId": "Contacts.List",
+				"tags": ["Contacts"],
+				"summary": "List contacts",
+				"parameters": [
+					{
+						"in": "query",
+						"name": "limit",
+						"schema": { "type": "integer", "minimum": 1, "maximum": 100 },
+						"description": "Max items to return"
+					},
+					{
+						"in": "query",
+						"name": "tag",
+						"schema": { "type": "array", "items": { "type": "string" } },
+						"description": "Filter by tags"
+					}
+				],
+				"responses": {
+					"200": {
+						"description": "OK",
+						"content": {
+							"application/json": {
+								"schema": {
+									"type": "array",
+									"items": {
+										"type": "object",
+										"properties": {
+											"id": { "type": "string" },
+											"name": { "type": "string" }
+										},
+										"required": ["id", "name"]
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/contacts/{id}": {
+			"get": {
+				"operationId": "Contacts.Get",
+				"tags": ["Contacts"],
+				"summary": "Get contact",
+				"parameters": [
+					{
+						"in": "path",
+						"name": "id",
+						"required": true,
+						"schema": { "type": "string" }
+					}
+				],
+				"responses": {
+					"200": {
+						"description": "OK",
+						"content": {
+							"application/json": {
+								"schema": {
+									"type": "object",
+									"properties": {
+										"id": { "type": "string" },
+										"name": { "type": "string" }
+									},
+									"required": ["id", "name"]
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

package/index.ts

@@ -0,0 +1 @@
+export { main } from "./src/cli/main.ts";

package/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "specli",
+	"module": "index.ts",
+	"type": "module",
+	"version": "0.0.1",
+	"bin": {
+		"opencli": "./cli.ts"
+	},
+	"scripts": {
+		"lint": "biome ci",
+		"lint:check": "biome check --write --unsafe",
+		"lint:format": "biome format --write",
+		"typecheck": "tsgo"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.11",
+		"@types/bun": "^1.3.6",
+		"@typescript/native-preview": "^7.0.0-dev.20260120.1"
+	},
+	"dependencies": {
+		"@apidevtools/swagger-parser": "^12.1.0",
+		"ajv": "^8.17.1",
+		"ajv-formats": "^3.0.1",
+		"commander": "^14.0.2",
+		"openapi-types": "^12.1.3"
+	}
+}

package/scripts/smoke-specs.ts

@@ -0,0 +1,64 @@
+#!/usr/bin/env bun
+
+const specs = [
+	{
+		name: "vercel",
+		url: "https://api.vercel.com/copper/_openapi.json",
+	},
+	{
+		name: "digitalocean",
+		url: "https://raw.githubusercontent.com/digitalocean/openapi/main/specification/DigitalOcean-public.v2.yaml",
+	},
+	// {
+	// 	name: "stripe",
+	// 	url: "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.yaml",
+	// },
+	// NOTE: OpenAI spec is not reliably fetchable via raw.githubusercontent.com
+	// in some environments (intermittent 404). Keep it out of the default smoke
+	// list to avoid flaky CI.
+	// {
+	// 	name: "openai",
+	// 	url: "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml",
+	// },
+] as const;
+
+type Result = {
+	spec: string;
+	ok: boolean;
+	ms: number;
+	error?: string;
+};
+
+const results: Result[] = [];
+
+for (const spec of specs) {
+	const start = performance.now();
+	try {
+		console.log(spec.url);
+		await Bun.$`bun ./cli.ts exec ${spec.url} __schema --json --min > /dev/null`;
+		results.push({
+			spec: spec.name,
+			ok: true,
+			ms: Math.round(performance.now() - start),
+		});
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		results.push({
+			spec: spec.name,
+			ok: false,
+			ms: Math.round(performance.now() - start),
+			error: message,
+		});
+	}
+}
+
+const allOk = results.every((r) => r.ok);
+for (const r of results) {
+	if (r.ok) {
+		process.stdout.write(`ok  ${r.spec} (${r.ms}ms)\n`);
+	} else {
+		process.stdout.write(`fail ${r.spec} (${r.ms}ms)\n${r.error}\n`);
+	}
+}
+
+process.exitCode = allOk ? 0 : 1;

package/src/cli/auth-requirements.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test";
+
+import { summarizeAuth } from "./auth-requirements.ts";
+import type { AuthScheme } from "./auth-schemes.ts";
+
+describe("summarizeAuth", () => {
+	test("uses operation-level security when present", () => {
+		const schemes: AuthScheme[] = [{ key: "oauth", kind: "oauth2" }];
+
+		const summary = summarizeAuth(
+			[{ oauth: ["read:ping"] }],
+			[{ oauth: ["read:other"] }],
+			schemes,
+		);
+
+		expect(summary.alternatives).toEqual([
+			[{ key: "oauth", scopes: ["read:ping"] }],
+		]);
+	});
+
+	test("empty operation security disables auth", () => {
+		const schemes: AuthScheme[] = [{ key: "oauth", kind: "oauth2" }];
+
+		const summary = summarizeAuth([], [{ oauth: ["read:other"] }], schemes);
+		expect(summary.alternatives).toEqual([]);
+	});
+});

package/src/cli/auth-requirements.ts

@@ -0,0 +1,91 @@
+import type { AuthScheme } from "./auth-schemes.ts";
+import type { SecurityRequirement } from "./types.ts";
+
+export type AuthRequirement = {
+	key: string;
+	scopes: string[];
+};
+
+export type AuthSummary = {
+	// Alternatives: any one of these sets is sufficient.
+	alternatives: AuthRequirement[][];
+};
+
+function isSecurityRequirement(value: unknown): value is SecurityRequirement {
+	if (!value || typeof value !== "object") return false;
+	if (Array.isArray(value)) return false;
+
+	for (const [k, v] of Object.entries(value)) {
+		if (typeof k !== "string") return false;
+		if (!Array.isArray(v)) return false;
+		if (!v.every((s) => typeof s === "string")) return false;
+	}
+
+	return true;
+}
+
+function normalizeSecurity(value: unknown): {
+	requirements: SecurityRequirement[];
+	source: "none" | "empty" | "non-empty";
+} {
+	if (value == null) return { requirements: [], source: "none" };
+	if (!Array.isArray(value)) return { requirements: [], source: "none" };
+
+	const reqs = value.filter(isSecurityRequirement);
+	if (reqs.length === 0) return { requirements: [], source: "empty" };
+	return { requirements: reqs, source: "non-empty" };
+}
+
+export function summarizeAuth(
+	operationSecurity: unknown,
+	globalSecurity: unknown,
+	knownSchemes: AuthScheme[],
+): AuthSummary {
+	// Per spec:
+	// - operation security overrides root
+	// - empty array [] means "no auth"
+	const op = normalizeSecurity(operationSecurity);
+	if (op.source === "non-empty") {
+		return { alternatives: toAlternatives(op.requirements, knownSchemes) };
+	}
+	if (op.source === "empty") {
+		return { alternatives: [] };
+	}
+
+	const global = normalizeSecurity(globalSecurity);
+	if (global.source === "non-empty") {
+		return { alternatives: toAlternatives(global.requirements, knownSchemes) };
+	}
+
+	return { alternatives: [] };
+}
+
+function toAlternatives(
+	requirements: SecurityRequirement[],
+	knownSchemes: AuthScheme[],
+): AuthRequirement[][] {
+	const known = new Set(knownSchemes.map((s) => s.key));
+
+	return requirements.map((req) => {
+		const out: AuthRequirement[] = [];
+		for (const [key, scopes] of Object.entries(req)) {
+			out.push({
+				key,
+				scopes: Array.isArray(scopes) ? scopes : [],
+			});
+		}
+
+		// Stable order.
+		out.sort((a, b) => a.key.localeCompare(b.key));
+
+		// Prefer known schemes first.
+		out.sort((a, b) => {
+			const ak = known.has(a.key) ? 0 : 1;
+			const bk = known.has(b.key) ? 0 : 1;
+			if (ak !== bk) return ak - bk;
+			return a.key.localeCompare(b.key);
+		});
+
+		return out;
+	});
+}

package/src/cli/auth-schemes.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from "bun:test";
+
+import { listAuthSchemes } from "./auth-schemes.ts";
+import type { OpenApiDoc } from "./types.ts";
+
+describe("listAuthSchemes", () => {
+	test("parses bearer + apiKey", () => {
+		const doc: OpenApiDoc = {
+			openapi: "3.0.3",
+			components: {
+				securitySchemes: {
+					bearerAuth: {
+						type: "http",
+						scheme: "bearer",
+						bearerFormat: "JWT",
+					},
+					apiKeyAuth: {
+						type: "apiKey",
+						in: "header",
+						name: "X-API-Key",
+					},
+				},
+			},
+		};
+
+		const schemes = listAuthSchemes(doc);
+		expect(schemes).toHaveLength(2);
+
+		const bearer = schemes.find((s) => s.key === "bearerAuth");
+		expect(bearer?.kind).toBe("http-bearer");
+
+		const apiKey = schemes.find((s) => s.key === "apiKeyAuth");
+		expect(apiKey?.kind).toBe("api-key");
+		expect(apiKey?.in).toBe("header");
+		expect(apiKey?.name).toBe("X-API-Key");
+	});
+
+	test("parses oauth2 flows", () => {
+		const doc = {
+			openapi: "3.0.3",
+			components: {
+				securitySchemes: {
+					oauth: {
+						type: "oauth2",
+						flows: {
+							clientCredentials: {
+								tokenUrl: "https://example.com/oauth/token",
+								scopes: {
+									"read:ping": "read ping",
+								},
+							},
+						},
+					},
+				},
+			},
+		} as const;
+
+		const schemes = listAuthSchemes(doc);
+		const oauth = schemes.find((s) => s.key === "oauth");
+		expect(oauth?.kind).toBe("oauth2");
+		expect(oauth?.oauthFlows?.clientCredentials?.tokenUrl).toBe(
+			"https://example.com/oauth/token",
+		);
+		expect(oauth?.oauthFlows?.clientCredentials?.scopes).toEqual(["read:ping"]);
+	});
+});