@axerity/cli 0.1.4 → 0.2.0

package/src/lib/openapi/generate.ts

@@ -1,629 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { parse as parseYaml } from 'yaml';
-
-interface ApiSource {
-	spec: string;
-	output?: string;
-	title?: string;
-}
-
-interface Schema {
-	$ref?: string;
-	type?: string | string[];
-	format?: string;
-	enum?: unknown[];
-	default?: unknown;
-	example?: unknown;
-	description?: string;
-	deprecated?: boolean;
-	readOnly?: boolean;
-	writeOnly?: boolean;
-	nullable?: boolean;
-	required?: string[];
-	items?: Schema;
-	properties?: Record<string, Schema>;
-	allOf?: Schema[];
-	oneOf?: Schema[];
-	anyOf?: Schema[];
-	minLength?: number;
-	maxLength?: number;
-	minimum?: number;
-	maximum?: number;
-	pattern?: string;
-}
-
-interface MediaType {
-	schema?: Schema;
-	example?: unknown;
-	examples?: Record<string, { value?: unknown }>;
-}
-
-interface Parameter {
-	$ref?: string;
-	name: string;
-	in: string;
-	required?: boolean;
-	deprecated?: boolean;
-	description?: string;
-	schema?: Schema;
-}
-
-interface Header {
-	schema?: Schema;
-	description?: string;
-	required?: boolean;
-}
-
-interface Body {
-	$ref?: string;
-	description?: string;
-	content?: Record<string, MediaType>;
-	headers?: Record<string, Header>;
-}
-
-type SecurityRequirement = Record<string, string[]>;
-
-interface Operation {
-	tags?: string[];
-	summary?: string;
-	description?: string;
-	operationId?: string;
-	deprecated?: boolean;
-	parameters?: Parameter[];
-	requestBody?: Body;
-	responses?: Record<string, Body>;
-	security?: SecurityRequirement[];
-	servers?: { url: string }[];
-}
-
-interface PathItem {
-	servers?: { url: string }[];
-	parameters?: Parameter[];
-	get?: Operation;
-	post?: Operation;
-	put?: Operation;
-	patch?: Operation;
-	delete?: Operation;
-}
-
-interface SecurityScheme {
-	type?: string;
-	name?: string;
-	in?: string;
-	scheme?: string;
-	bearerFormat?: string;
-	description?: string;
-	flows?: Record<string, { scopes?: Record<string, string> }>;
-	openIdConnectUrl?: string;
-}
-
-interface Spec {
-	info?: { title?: string };
-	servers?: { url: string }[];
-	tags?: { name: string }[];
-	security?: SecurityRequirement[];
-	paths?: Record<string, PathItem>;
-	webhooks?: Record<string, PathItem>;
-	components?: {
-		schemas?: Record<string, Schema>;
-		securitySchemes?: Record<string, SecurityScheme>;
-	};
-	[key: string]: unknown;
-}
-
-const METHODS = ['get', 'post', 'put', 'patch', 'delete'] as const;
-const METHOD_ICON: Record<string, string> = {
-	get: 'arrow-down-to-line',
-	post: 'plus',
-	put: 'pencil',
-	patch: 'pencil',
-	delete: 'trash-2'
-};
-
-const isObject = (value: unknown): value is Record<string, unknown> =>
-	typeof value === 'object' && value !== null;
-
-// Escape characters Svelte would otherwise read as markup/expressions in the
-// Markdown body (outside code blocks, which mdsvex already escapes).
-const escapeText = (text: string): string =>
-	text.replace(/[<{}]/g, (c) => ({ '<': '&lt;', '{': '&#123;', '}': '&#125;' })[c] ?? c);
-
-function slugify(value: string): string {
-	return value
-		.replace(/\{[^}]+\}/g, (m) => m.slice(1, -1))
-		.replace(/[^a-zA-Z0-9]+/g, '-')
-		.replace(/^-+|-+$/g, '')
-		.toLowerCase();
-}
-
-const refName = (ref: string): string => ref.slice(ref.lastIndexOf('/') + 1);
-
-function resolve<T>(spec: Spec, node: T): T {
-	let current: unknown = node;
-	const seen = new Set<string>();
-	while (isObject(current) && typeof current.$ref === 'string' && !seen.has(current.$ref)) {
-		seen.add(current.$ref);
-		const parts = current.$ref.replace(/^#\//, '').split('/');
-		current = parts.reduce<unknown>((acc, key) => (isObject(acc) ? acc[key] : undefined), spec);
-	}
-	return (current ?? {}) as T;
-}
-
-// Merge `allOf` into a single object schema; keep oneOf/anyOf for labelling.
-function composed(spec: Spec, schema: Schema): Schema {
-	const s = resolve(spec, schema);
-	if (!s.allOf) return s;
-	const merged: Schema = { type: 'object', properties: {}, required: [] };
-	for (const part of [...s.allOf, s]) {
-		const r = resolve(spec, part);
-		Object.assign(merged.properties!, r.properties);
-		if (r.required) merged.required!.push(...r.required);
-	}
-	return merged;
-}
-
-const baseType = (type?: string | string[]): string | undefined =>
-	Array.isArray(type) ? type.find((t) => t !== 'null') : type;
-
-function typeLabel(spec: Spec, schema?: Schema): string {
-	if (!schema) return 'any';
-	if (schema.$ref) return refName(schema.$ref);
-	if (schema.oneOf || schema.anyOf) {
-		const variants = (schema.oneOf ?? schema.anyOf)!.map((v) => typeLabel(spec, v));
-		return [...new Set(variants)].join(' or ');
-	}
-	if (schema.enum) return 'enum';
-	const type = baseType(schema.type);
-	if (type === 'array') {
-		const items = schema.items?.$ref ? refName(schema.items.$ref) : typeLabel(spec, schema.items);
-		return `array of ${items}`;
-	}
-	return schema.format ?? type ?? 'object';
-}
-
-function describe(schema: Schema): string {
-	const lines: string[] = [];
-	if (schema.description) lines.push(schema.description);
-	const notes: string[] = [];
-	if (schema.enum) notes.push(`one of ${schema.enum.map((v) => `\`${v}\``).join(', ')}`);
-	if (schema.format && !schema.description?.includes(schema.format))
-		notes.push(`format \`${schema.format}\``);
-	if (schema.pattern) notes.push(`pattern \`${schema.pattern}\``);
-	if (schema.minLength !== undefined || schema.maxLength !== undefined) {
-		notes.push(`length ${schema.minLength ?? 0}–${schema.maxLength ?? '∞'}`);
-	}
-	if (schema.minimum !== undefined || schema.maximum !== undefined) {
-		notes.push(`range ${schema.minimum ?? '−∞'}–${schema.maximum ?? '∞'}`);
-	}
-	if (schema.default !== undefined && typeof schema.default !== 'object') {
-		notes.push(`defaults to \`${schema.default}\``);
-	}
-	if (schema.readOnly) notes.push('read-only');
-	if (schema.writeOnly) notes.push('write-only');
-	if (schema.deprecated) notes.push('deprecated');
-	if (notes.length) lines.push(`(${notes.join(', ')})`);
-	return lines.join(' ');
-}
-
-function attrs(spec: Spec, name: string, schema: Schema, required?: boolean): string {
-	const parts = [`name="${name}"`, `type="${typeLabel(spec, schema)}"`];
-	if (required) parts.push('required');
-	if (schema.deprecated) parts.push('deprecated');
-	if (schema.default !== undefined && typeof schema.default !== 'object') {
-		parts.push(`default="${String(schema.default).replace(/"/g, '&quot;')}"`);
-	}
-	return parts.join(' ');
-}
-
-// Render a property list. Inline nested objects/arrays expand inline; $ref types
-// link to their generated schema page.
-function fields(spec: Spec, schema: Schema, group: string, component: string, depth = 0): string {
-	const resolved = composed(spec, schema);
-	const props = resolved.properties ?? {};
-	const required = new Set(resolved.required ?? []);
-	const out: string[] = [];
-	for (const [name, raw] of Object.entries(props)) {
-		const isRef = typeof raw.$ref === 'string';
-		const prop = composed(spec, raw);
-		const link = isRef ? ` typeLink="/${group}/schemas/${slugify(refName(raw.$ref!))}"` : '';
-		const labelSchema = isRef ? ({ $ref: raw.$ref } as Schema) : prop;
-		out.push(`<${component} ${attrs(spec, name, labelSchema, required.has(name))}${link}>`, '');
-		out.push(escapeText(describe(prop)) || 'No description.', '');
-
-		const inlineObject = !isRef && (baseType(prop.type) === 'object' || prop.properties);
-		const arrayItem =
-			!isRef && baseType(prop.type) === 'array' ? composed(spec, prop.items ?? {}) : null;
-		if (inlineObject && depth < 3) {
-			out.push(
-				'<Expandable title="properties">',
-				'',
-				fields(spec, prop, group, component, depth + 1),
-				'</Expandable>',
-				''
-			);
-		} else if (arrayItem && arrayItem.properties && !prop.items?.$ref && depth < 3) {
-			out.push(
-				'<Expandable title="items">',
-				'',
-				fields(spec, arrayItem, group, component, depth + 1),
-				'</Expandable>',
-				''
-			);
-		}
-		out.push(`</${component}>`, '');
-	}
-	return out.join('\n');
-}
-
-function sample(spec: Spec, schema: Schema | undefined, depth = 0): unknown {
-	const s = composed(spec, schema ?? {});
-	if (depth > 5) return null;
-	if (s.example !== undefined) return s.example;
-	if (s.default !== undefined) return s.default;
-	if (s.enum) return s.enum[0];
-	if (s.oneOf || s.anyOf) return sample(spec, (s.oneOf ?? s.anyOf)![0], depth + 1);
-	const type = baseType(s.type);
-	if (type === 'array') return [sample(spec, s.items, depth + 1)].filter((v) => v !== null);
-	if (type === 'object' || s.properties) {
-		const obj: Record<string, unknown> = {};
-		for (const [name, prop] of Object.entries(s.properties ?? {}))
-			obj[name] = sample(spec, prop, depth + 1);
-		return obj;
-	}
-	if (type === 'integer' || type === 'number') return 0;
-	if (type === 'boolean') return true;
-	if (s.format === 'date-time') return '2024-01-01T00:00:00Z';
-	return type === 'string' ? 'string' : null;
-}
-
-function pickMedia(spec: Spec, body?: Body): MediaType | undefined {
-	const content = resolve(spec, body ?? {}).content;
-	if (!content) return undefined;
-	return content['application/json'] ?? content[Object.keys(content)[0]];
-}
-
-function bodyExample(spec: Spec, media?: MediaType): unknown {
-	if (!media) return undefined;
-	if (media.example !== undefined) return media.example;
-	const named = media.examples && Object.values(media.examples)[0];
-	if (named && named.value !== undefined) return named.value;
-	return media.schema ? sample(spec, media.schema) : undefined;
-}
-
-const yamlLine = (text: string): string => JSON.stringify(text.split('\n')[0]);
-
-const SCRIPT_IMPORT =
-	"\timport { Api, Endpoint, ParamField, ResponseField, RequestExample, ResponseExample, ObjectExample, Expandable } from '$lib';";
-
-interface Page {
-	tag: string;
-	slug: string;
-	body: string;
-}
-
-function frontmatter(title: string, description: string, method: string, icon: string): string[] {
-	return [
-		'---',
-		`title: ${yamlLine(title)}`,
-		...(description ? [`description: ${yamlLine(description)}`] : []),
-		'layout: api',
-		...(method ? [`method: ${method}`] : []),
-		`icon: ${icon}`,
-		'---',
-		'',
-		'<script>',
-		SCRIPT_IMPORT,
-		'</script>',
-		''
-	];
-}
-
-function describeScheme(name: string, scheme: SecurityScheme, scopes: string[]): string {
-	if (scheme.type === 'http' && scheme.scheme === 'bearer') {
-		return `a bearer token${scheme.bearerFormat ? ` (${scheme.bearerFormat})` : ''}`;
-	}
-	if (scheme.type === 'http' && scheme.scheme === 'basic') return 'HTTP basic auth';
-	if (scheme.type === 'apiKey') return `an API key in the ${scheme.in} \`${scheme.name}\``;
-	if (scheme.type === 'oauth2') {
-		const flowScopes = Object.keys(Object.values(scheme.flows ?? {})[0]?.scopes ?? {});
-		const all = scopes.length ? scopes : flowScopes;
-		return `OAuth2${all.length ? ` (scopes ${all.map((s) => `\`${s}\``).join(', ')})` : ''}`;
-	}
-	if (scheme.type === 'openIdConnect') return 'OpenID Connect';
-	return name;
-}
-
-function authLines(spec: Spec, op: Operation): string[] {
-	const reqs = op.security ?? spec.security;
-	if (!reqs?.length) return [];
-	const schemes = spec.components?.securitySchemes ?? {};
-	const alternatives = reqs
-		.filter((r) => Object.keys(r).length)
-		.map((r) =>
-			Object.entries(r)
-				.map(([n, scopes]) => (schemes[n] ? describeScheme(n, schemes[n], scopes) : n))
-				.join(' and ')
-		);
-	if (!alternatives.length) return [];
-	const optional = reqs.some((r) => Object.keys(r).length === 0);
-	const text = `Requires ${alternatives.join(' or ')}.${optional ? ' Authentication is optional.' : ''}`;
-	return ['## Authentication', '', escapeText(text), ''];
-}
-
-function operationPage(
-	spec: Spec,
-	specBaseUrl: string,
-	group: string,
-	path: string,
-	method: string,
-	op: Operation,
-	pathItem?: PathItem,
-	defaultTag = 'default'
-): Page {
-	const tag = slugify(op.tags?.[0] ?? defaultTag);
-	const title = op.summary ?? op.operationId ?? `${method.toUpperCase()} ${path}`;
-	const description = op.description ?? op.summary ?? '';
-	const pathExpr = path.includes('{') ? `path={'${path}'}` : `path="${path}"`;
-	const baseUrl = op.servers?.[0]?.url ?? pathItem?.servers?.[0]?.url ?? specBaseUrl;
-
-	const lines: string[] = [
-		...frontmatter(title, description, method.toUpperCase(), METHOD_ICON[method] ?? 'code'),
-		`# ${escapeText(title)}`,
-		'',
-		...(op.deprecated ? ['> This operation is deprecated.', ''] : []),
-		...(description ? [escapeText(description), ''] : []),
-		'<Api>',
-		'',
-		`<Endpoint method="${method.toUpperCase()}" ${pathExpr} baseUrl="${baseUrl}" />`,
-		''
-	];
-
-	lines.push(...authLines(spec, op));
-
-	// Path-level params are shared across operations; the operation's own win.
-	const paramMap = new Map<string, Parameter>();
-	for (const p of [...(pathItem?.parameters ?? []), ...(op.parameters ?? [])].map((x) =>
-		resolve(spec, x)
-	)) {
-		paramMap.set(`${p.in}:${p.name}`, p);
-	}
-	const params = [...paramMap.values()];
-	const groups: Record<string, string> = {
-		path: 'Path parameters',
-		query: 'Query parameters',
-		header: 'Header parameters',
-		cookie: 'Cookie parameters'
-	};
-	for (const where of Object.keys(groups)) {
-		const list = params.filter((p) => p.in === where);
-		if (!list.length) continue;
-		lines.push(`## ${groups[where]}`, '');
-		for (const p of list) {
-			lines.push(`<ParamField ${attrs(spec, p.name, p.schema ?? {}, p.required)}>`, '');
-			lines.push(
-				escapeText(describe(p.schema ?? {}) || p.description || '') || 'No description.',
-				''
-			);
-			lines.push('</ParamField>', '');
-		}
-	}
-
-	const reqContent = resolve(spec, op.requestBody ?? {}).content ?? {};
-	const reqTypes = Object.keys(reqContent);
-	const reqKey = reqContent['application/json'] ? 'application/json' : reqTypes[0];
-	const reqMedia = reqKey ? reqContent[reqKey] : undefined;
-	if (reqMedia?.schema) {
-		lines.push('## Body parameters', '');
-		if (reqTypes.length > 1) {
-			lines.push(`Accepts ${reqTypes.map((t) => `\`${t}\``).join(', ')}.`, '');
-		}
-		lines.push(fields(spec, reqMedia.schema, group, 'ParamField'));
-	}
-
-	const reqExample = bodyExample(spec, reqMedia);
-	const curl = [
-		`curl -X ${method.toUpperCase()} ${baseUrl}${path.replace(/\{([^}]+)\}/g, ':$1')}`,
-		reqExample !== undefined
-			? `  -H "Content-Type: ${reqKey}" \\\n  -d '${JSON.stringify(reqExample)}'`
-			: ''
-	]
-		.filter(Boolean)
-		.join(' \\\n');
-	lines.push(
-		'<RequestExample title="cURL">',
-		'',
-		'```bash',
-		curl,
-		'```',
-		'',
-		'</RequestExample>',
-		''
-	);
-
-	const responses = Object.entries(op.responses ?? {}).sort(([a], [b]) => a.localeCompare(b));
-	for (const [code, raw] of responses) {
-		const response = resolve(spec, raw);
-		const media = pickMedia(spec, response);
-		lines.push(`## Response \`${code}\``, '');
-		if (response.description) lines.push(escapeText(response.description), '');
-		if (response.headers) {
-			lines.push('Headers:', '');
-			for (const [hname, hraw] of Object.entries(response.headers)) {
-				const h = resolve(spec, hraw);
-				const desc = h.description ? ` — ${escapeText(h.description)}` : '';
-				lines.push(`- \`${hname}\` ${typeLabel(spec, h.schema)}${desc}`);
-			}
-			lines.push('');
-		}
-		if (media?.schema) lines.push(fields(spec, media.schema, group, 'ResponseField'));
-		const example = bodyExample(spec, media);
-		if (example !== undefined) {
-			lines.push(
-				`<ResponseExample title="${code}">`,
-				'',
-				'```json',
-				JSON.stringify(example, null, 2),
-				'```',
-				'',
-				'</ResponseExample>',
-				''
-			);
-		}
-	}
-
-	lines.push('</Api>', '');
-	return { tag, slug: slugify(op.operationId ?? `${method}-${path}`), body: lines.join('\n') };
-}
-
-function schemaPage(spec: Spec, group: string, name: string, schema: Schema): string {
-	const resolved = composed(spec, schema);
-	return [
-		...frontmatter(name, resolved.description ?? `The ${name} object.`, '', 'box'),
-		`# ${escapeText(name)}`,
-		'',
-		...(resolved.description ? [escapeText(resolved.description), ''] : []),
-		'<Api>',
-		'',
-		'## Attributes',
-		'',
-		fields(spec, resolved, group, 'ResponseField'),
-		'<ObjectExample title={`' + name + '`}>',
-		'',
-		'```json',
-		JSON.stringify(sample(spec, resolved), null, 2),
-		'```',
-		'',
-		'</ObjectExample>',
-		'',
-		'</Api>',
-		''
-	].join('\n');
-}
-
-const titleCase = (value: string): string => value.replace(/(^|\s)\S/g, (c) => c.toUpperCase());
-
-async function loadSpec(spec: string): Promise<Spec> {
-	let text: string;
-	if (/^https?:\/\//.test(spec)) {
-		const res = await fetch(spec);
-		text = await res.text();
-	} else {
-		text = readFileSync(spec, 'utf8');
-	}
-	text = text.trim();
-	return (text.startsWith('{') ? JSON.parse(text) : parseYaml(text)) as Spec;
-}
-
-async function generateOne(source: ApiSource, contentRoot: string): Promise<string[]> {
-	const spec = await loadSpec(source.spec);
-	const baseUrl = spec.servers?.[0]?.url ?? '';
-	const group = source.output || (source.title ? slugify(source.title) : 'api-reference');
-	const root = join(contentRoot, group);
-	rmSync(root, { recursive: true, force: true });
-
-	const byTag = new Map<string, Page[]>();
-	const collect = (entries: Record<string, PathItem> | undefined, defaultTag: string) => {
-		for (const [path, item] of Object.entries(entries ?? {})) {
-			for (const method of METHODS) {
-				const op = item[method];
-				if (!op) continue;
-				const page = operationPage(spec, baseUrl, group, path, method, op, item, defaultTag);
-				if (!byTag.has(page.tag)) byTag.set(page.tag, []);
-				byTag.get(page.tag)!.push(page);
-			}
-		}
-	};
-	collect(spec.paths, 'default');
-	collect(spec.webhooks, 'webhooks');
-
-	const written: string[] = [];
-	const write = (file: string, content: string) => {
-		mkdirSync(dirname(file), { recursive: true });
-		writeFileSync(file, content);
-		written.push(file);
-	};
-
-	const tags = [...byTag.keys()];
-	const schemas = Object.entries(spec.components?.schemas ?? {});
-	const sections = [...tags, ...(schemas.length ? ['schemas'] : [])];
-	const tagTitle = (t: string): string =>
-		titleCase(spec.tags?.find((x) => slugify(x.name) === t)?.name ?? t);
-
-	write(
-		join(root, 'meta.json'),
-		JSON.stringify(
-			{ title: source.title ?? spec.info?.title ?? 'API Reference', icon: 'code', pages: sections },
-			null,
-			'\t'
-		)
-	);
-
-	for (const [tag, pages] of byTag) {
-		write(
-			join(root, tag, 'meta.json'),
-			JSON.stringify({ title: tagTitle(tag), pages: pages.map((p) => p.slug) }, null, '\t')
-		);
-		for (const page of pages) write(join(root, tag, `${page.slug}.md`), page.body);
-	}
-
-	if (schemas.length) {
-		write(
-			join(root, 'schemas', 'meta.json'),
-			JSON.stringify(
-				{ title: 'Schemas', icon: 'box', pages: schemas.map(([name]) => slugify(name)) },
-				null,
-				'\t'
-			)
-		);
-		for (const [name, schema] of schemas) {
-			write(join(root, 'schemas', `${slugify(name)}.md`), schemaPage(spec, group, name, schema));
-		}
-	}
-
-	return written;
-}
-
-// Keep generated reference folders out of git (and prettier/eslint, which read
-// .gitignore) without touching the rest of the file.
-function ignoreGenerated(contentRoot: string, groups: string[]): void {
-	const file = '.gitignore';
-	const start = '# axerity:openapi (generated)';
-	const end = '# end axerity:openapi';
-	const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-	const block = [start, ...groups.map((g) => `${contentRoot}/${g}`), end].join('\n');
-	let content = existsSync(file) ? readFileSync(file, 'utf8') : '';
-	content = content.replace(new RegExp(`\\n*${esc(start)}[\\s\\S]*?${esc(end)}\\n*`, 'g'), '\n');
-	if (groups.length) content = `${content.replace(/\n+$/, '')}\n\n${block}\n`;
-	writeFileSync(file, content);
-}
-
-/**
- * Generate one or more API references (local file or URL, JSON or YAML) into the
- * content folder. An array of sources produces a separate group per spec.
- */
-export async function generateApiDocs(
-	openapi: string | ApiSource | ApiSource[] | undefined,
-	contentRoot: string
-): Promise<string[]> {
-	const sources = (openapi ? (Array.isArray(openapi) ? openapi : [openapi]) : []).map((o) =>
-		typeof o === 'string' ? { spec: o } : o
-	);
-	const written: string[] = [];
-	const groups: string[] = [];
-	for (const source of sources) {
-		if (!source.spec) continue;
-		if (!/^https?:\/\//.test(source.spec) && !existsSync(source.spec)) continue;
-		groups.push(source.output || (source.title ? slugify(source.title) : 'api-reference'));
-		try {
-			written.push(...(await generateOne(source, contentRoot)));
-		} catch (error) {
-			console.warn(`[axerity] OpenAPI generation failed for ${source.spec}:`, error);
-		}
-	}
-	// When the CLI mounts a user's project into the engine, generated pages live
-	// engine-side and never touch the user's repo, so the .gitignore block is
-	// pointless — and rewriting .gitignore mid-run is dangerous. Skip it then.
-	if (!process.env.AXERITY_MOUNTED) ignoreGenerated(contentRoot, groups);
-	return written;
-}