@askills/openapi-explorer-cli 0.0.2 → 0.0.4

package/dist/index.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/index.mjs

@@ -0,0 +1,589 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+//#region src/core/loader.ts
+async function loadSpec(source) {
+	const isUrl = /^https?:\/\//i.test(source);
+	let raw;
+	if (isUrl) {
+		const res = await fetch(source, {
+			headers: { Accept: "application/json, text/plain" },
+			signal: AbortSignal.timeout(3e4)
+		});
+		if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${source}`);
+		raw = await res.text();
+	} else raw = await readFile(resolve(source), "utf-8");
+	const data = JSON.parse(raw);
+	if (!data.openapi && !data.swagger) throw new Error("Not a valid OpenAPI/Swagger spec.");
+	if (!data.info) throw new Error("Invalid spec: missing 'info' field.");
+	data.info.title = data.info.title || "Untitled API";
+	data.info.version = data.info.version || "0.0.0";
+	data.paths = data.paths || {};
+	return data;
+}
+function getServerUrl(spec) {
+	if (spec.servers?.length) {
+		let url = spec.servers[0].url;
+		return url.endsWith("/") ? url.slice(0, -1) : url;
+	}
+	if (spec.host) return `${spec.schemes?.[0] || "https"}://${spec.host}${spec.basePath || ""}`;
+	return "";
+}
+//#endregion
+//#region src/core/queries.ts
+const HTTP_METHODS = [
+	"get",
+	"post",
+	"put",
+	"patch",
+	"delete",
+	"options",
+	"head"
+];
+const METHOD_PRIORITY = {
+	get: 0,
+	post: 1,
+	put: 2,
+	patch: 3,
+	delete: 4,
+	options: 5,
+	head: 6
+};
+function getEndpoints(spec, tag) {
+	const eps = [];
+	for (const [path, pathItem] of Object.entries(spec.paths)) for (const method of HTTP_METHODS) {
+		const op = pathItem[method];
+		if (!op) continue;
+		if (tag && (!op.tags || !op.tags.includes(tag))) continue;
+		eps.push({
+			path,
+			method,
+			summary: op.summary || op.operationId || `${method.toUpperCase()} ${path}`,
+			operationId: op.operationId,
+			tags: op.tags || [],
+			deprecated: op.deprecated || false
+		});
+	}
+	eps.sort((a, b) => {
+		if (a.path !== b.path) return a.path.localeCompare(b.path);
+		return (METHOD_PRIORITY[a.method] ?? 99) - (METHOD_PRIORITY[b.method] ?? 99);
+	});
+	return eps;
+}
+function getTags(spec) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const pathItem of Object.values(spec.paths)) for (const method of HTTP_METHODS) {
+		const op = pathItem[method];
+		if (!op?.tags) continue;
+		for (const tag of op.tags) counts.set(tag, (counts.get(tag) || 0) + 1);
+	}
+	return Array.from(counts.entries()).map(([name, count]) => ({
+		name,
+		count
+	})).sort((a, b) => a.name.localeCompare(b.name));
+}
+function getSchemas(spec) {
+	const schemas = spec.components?.schemas || spec.definitions || {};
+	return Object.entries(schemas).map(([name, s]) => ({
+		name,
+		type: s.type || "object",
+		description: s.description || s.title,
+		properties: s.properties ? Object.keys(s.properties).length : 0
+	})).sort((a, b) => a.name.localeCompare(b.name));
+}
+function getSchemaDetail(spec, name) {
+	return (spec.components?.schemas || spec.definitions || {})[name] || null;
+}
+function getPathParams(path) {
+	const m = path.match(/\{(\w+)\}/g);
+	return m ? m.map((s) => s.slice(1, -1)) : [];
+}
+function searchSpec(spec, query) {
+	const results = [];
+	const lower = query.toLowerCase();
+	for (const [path, pi] of Object.entries(spec.paths)) for (const method of HTTP_METHODS) {
+		const op = pi[method];
+		if (!op) continue;
+		if ([
+			path,
+			method,
+			op.summary,
+			op.operationId,
+			op.description,
+			...op.tags || []
+		].filter(Boolean).join(" ").toLowerCase().includes(lower)) results.push({
+			type: "endpoint",
+			path,
+			method,
+			match: `${method.toUpperCase()} ${path}`,
+			summary: op.summary || op.operationId
+		});
+	}
+	const schemas = spec.components?.schemas || spec.definitions || {};
+	for (const [name, s] of Object.entries(schemas)) {
+		const sAny = s;
+		if ([
+			name,
+			sAny.description,
+			sAny.title
+		].filter(Boolean).join(" ").toLowerCase().includes(lower)) results.push({
+			type: "schema",
+			schemaName: name,
+			match: `Schema: ${name}`,
+			summary: sAny.description
+		});
+		if (sAny.properties) for (const [pn, ps] of Object.entries(sAny.properties)) {
+			const psAny = ps;
+			if ([pn, psAny.description].filter(Boolean).join(" ").toLowerCase().includes(lower)) results.push({
+				type: "property",
+				schemaName: name,
+				propertyName: pn,
+				match: `Schema ${name} > ${pn}`,
+				summary: psAny.description
+			});
+		}
+	}
+	return results;
+}
+//#endregion
+//#region src/commands/info.ts
+async function cmdInfo(source) {
+	const spec = await loadSpec(source);
+	const eps = getEndpoints(spec);
+	const schemas = getSchemas(spec);
+	const tags = getTags(spec);
+	const url = getServerUrl(spec);
+	const sv = spec.openapi || spec.swagger || "unknown";
+	const lines = [
+		`# ${spec.info.title}`,
+		"",
+		`Version: ${spec.info.version}`,
+		`OpenAPI Version: ${sv}`,
+		`Server: \`${url || "Not specified"}\``,
+		"",
+		spec.info.description || "",
+		"",
+		"## Summary",
+		`- Endpoints: ${eps.length}`,
+		`- Schemas: ${schemas.length}`,
+		`- Tags: ${tags.length}`
+	];
+	if (spec.info.contact) {
+		lines.push("", "## Contact");
+		for (const k of [
+			"name",
+			"email",
+			"url"
+		]) {
+			const val = spec.info.contact[k];
+			if (val) lines.push(`- ${k.charAt(0).toUpperCase() + k.slice(1)}: ${val}`);
+		}
+	}
+	if (spec.info.license) {
+		lines.push("", "## License");
+		lines.push(`- Name: ${spec.info.license.name}`);
+		if (spec.info.license.url) lines.push(`- URL: ${spec.info.license.url}`);
+	}
+	return lines.join("\n");
+}
+//#endregion
+//#region src/commands/tags.ts
+async function cmdTags(source) {
+	const tags = getTags(await loadSpec(source));
+	if (!tags.length) return "No tags found.";
+	const lines = [
+		"# Tags",
+		"",
+		"| Tag | Endpoints |",
+		"|-----|-----------|"
+	];
+	for (const t of tags) lines.push(`| \`${t.name}\` | ${t.count} |`);
+	return lines.join("\n");
+}
+//#endregion
+//#region src/commands/paths.ts
+async function cmdPaths(source, tag, limit = 50, offset = 0) {
+	const all = getEndpoints(await loadSpec(source), tag);
+	const paginated = all.slice(offset, offset + limit);
+	if (!paginated.length) return all.length === 0 ? "No endpoints found." : `No more endpoints (offset ${offset} of ${all.length}).`;
+	const hasMore = all.length > offset + paginated.length;
+	const lines = ["# Endpoints"];
+	if (tag) lines.push(`\nFiltered by tag: \`${tag}\``);
+	lines.push(`\n${all.length} total (showing ${paginated.length})`, "");
+	for (const ep of paginated) {
+		lines.push(`### \`${ep.method.toUpperCase()}\` ${ep.path}${ep.deprecated ? " ~~(deprecated)~~" : ""}`);
+		if (ep.summary) lines.push(ep.summary);
+		if (ep.operationId) lines.push(`- Operation ID: \`${ep.operationId}\``);
+		if (ep.tags.length) lines.push(`- Tags: ${ep.tags.map((t) => `\`${t}\``).join(", ")}`);
+		lines.push("");
+	}
+	if (hasMore) lines.push(`> Showing ${paginated.length} of ${all.length}. Use --offset=${offset + paginated.length} to see more.`);
+	return lines.join("\n");
+}
+//#endregion
+//#region src/core/resolve.ts
+function resolveRef(spec, ref) {
+	const parts = ref.replace(/^#\//, "").split("/");
+	let cur = spec;
+	for (const p of parts) if (cur && typeof cur === "object" && p in cur) cur = cur[p];
+	else return null;
+	return cur;
+}
+function deepResolve(schema, spec, visited = /* @__PURE__ */ new Set()) {
+	if (!schema || typeof schema !== "object") return schema;
+	const obj = schema;
+	if (obj.$ref && typeof obj.$ref === "string") {
+		if (visited.has(obj.$ref)) return {
+			$ref: obj.$ref,
+			description: `(circular: ${obj.$ref})`
+		};
+		visited.add(obj.$ref);
+		const resolved = resolveRef(spec, obj.$ref);
+		if (resolved && typeof resolved === "object" && !Array.isArray(resolved)) {
+			const merged = { ...deepResolve(resolved, spec, new Set(visited)) };
+			for (const k of Object.keys(obj)) if (k !== "$ref") merged[k] = obj[k];
+			return merged;
+		}
+		return obj;
+	}
+	const result = {};
+	for (const [k, v] of Object.entries(obj)) if (k === "properties" && v && typeof v === "object") {
+		const props = {};
+		for (const [pn, ps] of Object.entries(v)) props[pn] = deepResolve(ps, spec, new Set(visited));
+		result[k] = props;
+	} else if ((k === "items" || k === "additionalProperties") && v && typeof v === "object" && !Array.isArray(v)) result[k] = deepResolve(v, spec, new Set(visited));
+	else if ([
+		"oneOf",
+		"anyOf",
+		"allOf"
+	].includes(k) && Array.isArray(v)) result[k] = v.map((s) => deepResolve(s, spec, new Set(visited)));
+	else result[k] = v;
+	return result;
+}
+//#endregion
+//#region src/formatters/schema.ts
+function fmtSchema(schema, indent = 0) {
+	const pad = "  ".repeat(indent);
+	if (!schema || typeof schema !== "object") return `${pad}${String(schema)}`;
+	const s = schema;
+	if (s.$ref && typeof s.$ref === "string") return `${pad}$ref: "${s.$ref.split("/").pop()}"`;
+	if (s.enum && Array.isArray(s.enum)) return `${pad}enum: [${s.enum.map((v) => JSON.stringify(v)).join(", ")}]`;
+	for (const kw of [
+		"oneOf",
+		"anyOf",
+		"allOf"
+	]) if (s[kw] && Array.isArray(s[kw])) {
+		const lines = [`${pad}${kw}:`];
+		for (let i = 0; i < s[kw].length; i++) {
+			if (i > 0) lines.push(`${pad}  ---`);
+			lines.push(fmtSchema(s[kw][i], indent + 1));
+		}
+		return lines.join("\n");
+	}
+	const allLines = [];
+	if (s.description && typeof s.description === "string") allLines.push(`${pad}// ${s.description}`);
+	allLines.push(`${pad}type: ${s.type || "any"}${s.format ? `<${s.format}>` : ""}${s.nullable ? " | null" : ""}`);
+	if (s.properties && typeof s.properties === "object") {
+		const req = new Set(Array.isArray(s.required) ? s.required : []);
+		for (const [pn, ps] of Object.entries(s.properties)) {
+			allLines.push(`${pad}${pn}${req.has(pn) ? " (required)" : ""}:`);
+			allLines.push(fmtSchema(ps, indent + 1));
+		}
+	}
+	if (s.items) {
+		allLines.push(`${pad}items:`);
+		allLines.push(fmtSchema(s.items, indent + 1));
+	}
+	if (s.additionalProperties && typeof s.additionalProperties === "object") {
+		allLines.push(`${pad}additionalProperties:`);
+		allLines.push(fmtSchema(s.additionalProperties, indent + 1));
+	}
+	if (s.example !== void 0) allLines.push(`${pad}example: ${JSON.stringify(s.example)}`);
+	if (s.default !== void 0) allLines.push(`${pad}default: ${JSON.stringify(s.default)}`);
+	for (const k of [
+		"minLength",
+		"maxLength",
+		"minimum",
+		"maximum"
+	]) if (s[k] !== void 0) allLines.push(`${pad}${k}: ${s[k]}`);
+	if (s.pattern) allLines.push(`${pad}pattern: ${s.pattern}`);
+	return allLines.join("\n");
+}
+//#endregion
+//#region src/formatters/endpoint.ts
+function fmtEndpoint(ep) {
+	const lines = [`# ${ep.method.toUpperCase()} ${ep.path}`];
+	if (ep.deprecated) lines.push("", "DEPRECATED");
+	if (ep.summary) lines.push("", ep.summary);
+	if (ep.description) lines.push("", ep.description);
+	if (ep.operationId) lines.push("", `Operation ID: \`${ep.operationId}\``);
+	if (ep.tags?.length) lines.push("", `Tags: ${ep.tags.map((t) => `\`${t}\``).join(", ")}`);
+	if (ep.parameters?.length) {
+		lines.push("", "## Parameters", "", "| Name | In | Type | Required | Description |", "|------|----|------|----------|-------------|");
+		for (const p of ep.parameters) lines.push(`| \`${p.name}\` | ${p.in} | ${p.schema?.type || p.type || "string"} | ${p.required ? "Yes" : "No"} | ${p.description || ""} |`);
+	}
+	if (ep.requestBody) {
+		lines.push("", "## Request Body");
+		if (ep.requestBody.required) lines.push("> Required");
+		if (ep.requestBody.description) lines.push("", ep.requestBody.description);
+		for (const [ct, mt] of Object.entries(ep.requestBody.content || {})) lines.push("", `${ct}:`, "```", fmtSchema(mt.schema || {}), "```");
+	}
+	if (ep.responses) {
+		lines.push("", "## Responses");
+		for (const [code, resp] of Object.entries(ep.responses)) {
+			const r = resp;
+			lines.push("", `### ${code}`, r.description);
+			if (r.content) for (const [ct, mt] of Object.entries(r.content)) lines.push("", `${ct}:`, "```", fmtSchema(mt.schema || {}), "```");
+		}
+	}
+	if (ep.security?.length) {
+		lines.push("", "## Security");
+		for (const sec of ep.security) for (const [scheme, scopes] of Object.entries(sec)) lines.push(`- \`${scheme}\`${Array.isArray(scopes) && scopes.length ? ` [${scopes.join(", ")}]` : ""}`);
+	}
+	return lines.join("\n");
+}
+//#endregion
+//#region src/commands/endpoint.ts
+async function cmdEndpoint(source, path, method, full = false) {
+	const spec = await loadSpec(source);
+	method = method.toLowerCase();
+	const op = spec.paths[path]?.[method];
+	if (!op) {
+		const similar = getEndpoints(spec).filter((e) => e.path.includes(path) || path.includes(e.path)).slice(0, 5);
+		const hint = similar.length ? "\n\nDid you mean?\n" + similar.map((e) => `  ${e.method.toUpperCase()} ${e.path}`).join("\n") : "";
+		throw new Error(`No ${method.toUpperCase()} ${path} found.${hint}`);
+	}
+	const paramNames = getPathParams(path);
+	const opParams = op.parameters || [];
+	const bodyParam = opParams.find((p) => p.in === "body");
+	const nonBodyParams = opParams.filter((p) => p.in !== "body");
+	const mergedParams = [...paramNames.map((n) => nonBodyParams.find((p) => p.name === n) || {
+		name: n,
+		in: "path",
+		required: true,
+		description: `Path param: ${n}`,
+		schema: { type: "string" }
+	}), ...nonBodyParams.filter((p) => !paramNames.includes(p.name))];
+	const resolve = (schema) => full && schema ? deepResolve(schema, spec) : schema;
+	let requestBody;
+	if (op.requestBody) requestBody = {
+		description: op.requestBody.description,
+		required: op.requestBody.required,
+		content: Object.fromEntries(Object.entries(op.requestBody.content || {}).map(([ct, mt]) => [ct, { schema: resolve(mt.schema) }]))
+	};
+	else if (bodyParam) {
+		const ct = (op.consumes || spec.consumes || ["application/json"])[0] || "application/json";
+		requestBody = {
+			description: bodyParam.description,
+			required: bodyParam.required,
+			content: { [ct]: { schema: resolve(bodyParam.schema) } }
+		};
+	}
+	const produces = op.produces || spec.produces || ["application/json"];
+	let responses;
+	if (op.responses) responses = Object.fromEntries(Object.entries(op.responses).map(([code, resp]) => {
+		let content;
+		if (resp.content) content = Object.fromEntries(Object.entries(resp.content).map(([ct, mt]) => [ct, { schema: resolve(mt.schema) }]));
+		else if (resp.schema) content = { [produces[0] || "application/json"]: { schema: resolve(resp.schema) } };
+		return [code, {
+			description: resp.description,
+			content
+		}];
+	}));
+	return fmtEndpoint({
+		path,
+		method,
+		summary: op.summary,
+		description: op.description,
+		operationId: op.operationId,
+		tags: op.tags || [],
+		deprecated: op.deprecated || false,
+		parameters: mergedParams.map((p) => ({
+			...p,
+			schema: resolve(p.schema)
+		})),
+		requestBody,
+		responses,
+		security: op.security
+	});
+}
+//#endregion
+//#region src/commands/schemas.ts
+async function cmdSchemas(source, limit = 50, offset = 0) {
+	const all = getSchemas(await loadSpec(source));
+	const paginated = all.slice(offset, offset + limit);
+	if (!paginated.length) return all.length === 0 ? "No schemas defined." : `No more schemas (offset ${offset} of ${all.length}).`;
+	const hasMore = all.length > offset + paginated.length;
+	const lines = [
+		"# Component Schemas",
+		"",
+		`${all.length} total (showing ${paginated.length})`,
+		"",
+		"| Name | Type | Properties | Description |",
+		"|------|------|------------|-------------|"
+	];
+	for (const s of paginated) lines.push(`| \`${s.name}\` | ${s.type} | ${s.properties} | ${(s.description || "").slice(0, 80)} |`);
+	if (hasMore) lines.push(`\n> Showing ${paginated.length} of ${all.length}. Use --offset=${offset + paginated.length} to see more.`);
+	lines.push("\nUse `openapi-explorer schema <source> <schema_name>` for details.");
+	return lines.join("\n");
+}
+//#endregion
+//#region src/commands/schema.ts
+async function cmdSchema(source, schemaName) {
+	const spec = await loadSpec(source);
+	const schema = getSchemaDetail(spec, schemaName);
+	if (!schema) {
+		const suggestions = getSchemas(spec).slice(0, 10).map((s) => s.name);
+		throw new Error(`Schema '${schemaName}' not found.\n\nAvailable:\n${suggestions.map((s) => `  - ${s}`).join("\n")}`);
+	}
+	return [
+		`# Schema: ${schemaName}`,
+		"",
+		"```",
+		fmtSchema(schema),
+		"```"
+	].join("\n");
+}
+//#endregion
+//#region src/commands/search.ts
+async function cmdSearch(source, query) {
+	const results = searchSpec(await loadSpec(source), query);
+	if (!results.length) return `No results for '${query}'.`;
+	const lines = [
+		`# Search Results for '${query}'`,
+		"",
+		`Found ${results.length} matches`,
+		""
+	];
+	const eps = results.filter((r) => r.type === "endpoint");
+	const schemas = results.filter((r) => r.type === "schema");
+	const props = results.filter((r) => r.type === "property");
+	if (eps.length) {
+		lines.push(`## Endpoints (${eps.length})`);
+		for (const e of eps) lines.push(`- ${e.method?.toUpperCase()} \`${e.path}\` - ${e.summary || ""}`);
+		lines.push("");
+	}
+	if (schemas.length) {
+		lines.push(`## Schemas (${schemas.length})`);
+		for (const s of schemas) lines.push(`- ${s.schemaName} - ${s.summary || ""}`);
+		lines.push("");
+	}
+	if (props.length) {
+		lines.push(`## Properties (${props.length})`);
+		for (const p of props) lines.push(`- \`${p.schemaName}.${p.propertyName}\` - ${p.summary || ""}`);
+		lines.push("");
+	}
+	return lines.join("\n");
+}
+//#endregion
+//#region src/cli/args.ts
+function parseArgs(argv) {
+	const args = argv.slice(2);
+	if (!args.length || args[0] === "--help" || args[0] === "-h") return {
+		command: "help",
+		source: "",
+		flags: {},
+		positional: []
+	};
+	const command = args[0] ?? "";
+	const source = args[1] ?? "";
+	const positional = [];
+	const flags = {};
+	let i = 2;
+	while (i < args.length) {
+		const arg = args[i];
+		if (arg.startsWith("--")) {
+			const key = arg.slice(2);
+			if (key === "full") {
+				flags[key] = true;
+				i++;
+			} else if (key === "tag" || key === "limit" || key === "offset") {
+				flags[key] = args[i + 1] ?? "";
+				i += 2;
+			} else {
+				flags[key] = args[i + 1] ?? true;
+				i += 2;
+			}
+		} else {
+			positional.push(arg);
+			i++;
+		}
+	}
+	return {
+		command,
+		source,
+		flags,
+		positional
+	};
+}
+function printHelp() {
+	return `Usage: openapi-explorer <command> <source> [args...]
+
+source can be a URL (https://...) or a local file path.
+
+Commands:
+  info <source>                          API overview
+  tags <source>                          List tag groups
+  paths <source> [--tag <t>] [--limit N] [--offset N]   List endpoints
+  endpoint <source> <path> <method> [--full]             Endpoint detail
+  schemas <source> [--limit N] [--offset N]              List schemas
+  schema <source> <schema_name>                           Schema detail
+  search <source> <query>                                 Full-text search
+
+Examples:
+  openapi-explorer info https://petstore.swagger.io/v2/swagger.json
+  openapi-explorer endpoint ./spec.json /pets/{petId} get --full
+  openapi-explorer paths ./spec.json --tag pets`;
+}
+//#endregion
+//#region src/cli/dispatch.ts
+async function dispatch(argv) {
+	const { command, source, flags, positional } = parseArgs(argv);
+	switch (command) {
+		case "help": return printHelp();
+		case "info":
+			if (!source) throw new Error("Usage: swagger.mjs info <source>");
+			return await cmdInfo(source);
+		case "tags":
+			if (!source) throw new Error("Usage: swagger.mjs tags <source>");
+			return await cmdTags(source);
+		case "paths":
+			if (!source) throw new Error("Usage: swagger.mjs paths <source> [--tag <t>] [--limit N] [--offset N]");
+			return await cmdPaths(source, typeof flags.tag === "string" ? flags.tag : void 0, typeof flags.limit === "string" ? parseInt(flags.limit, 10) || 50 : 50, typeof flags.offset === "string" ? parseInt(flags.offset, 10) || 0 : 0);
+		case "endpoint":
+		case "ep": {
+			const path = positional[0] || flags.path;
+			const method = positional[1] || flags.method;
+			if (!source || !path || !method) throw new Error("Usage: swagger.mjs endpoint <source> <path> <method> [--full]");
+			return await cmdEndpoint(source, path, method, flags.full === true);
+		}
+		case "schemas":
+			if (!source) throw new Error("Usage: swagger.mjs schemas <source> [--limit N] [--offset N]");
+			return await cmdSchemas(source, typeof flags.limit === "string" ? parseInt(flags.limit, 10) || 50 : 50, typeof flags.offset === "string" ? parseInt(flags.offset, 10) || 0 : 0);
+		case "schema": {
+			const schemaName = positional[0] || flags.name;
+			if (!source || !schemaName) throw new Error("Usage: swagger.mjs schema <source> <schema_name>");
+			return await cmdSchema(source, schemaName);
+		}
+		case "search": {
+			const query = positional[0] || flags.query;
+			if (!source || !query) throw new Error("Usage: swagger.mjs search <source> <query>");
+			return await cmdSearch(source, query);
+		}
+		default: throw new Error(`Unknown command: ${command}`);
+	}
+}
+//#endregion
+//#region src/index.ts
+async function main() {
+	const output = await dispatch(process.argv);
+	console.log(output);
+}
+main().catch((err) => {
+	console.error(err instanceof Error ? err.message : String(err));
+	process.exit(1);
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=index.mjs.map