Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
6.5 KB
Raw Blame
#!/usr/bin/env tsx
// SPDX-License-Identifier: AGPL-3.0-or-later
import * as fs from 'node:fs';
import * as path from 'node:path';
import type {OpenAPIGenerationStats, SkippedRoute} from '@fluxer/openapi/src/OpenAPIGenerationTypes';
import {OpenAPIGenerator} from '@fluxer/openapi/src/OpenAPIGenerator';
import {printValidationResult, validateSpec} from '@fluxer/openapi/src/output/SpecValidator';
import {
	getAdminOutputPath,
	getApiPackageOutputPath,
	readSpec,
	type WritableOpenAPISpec,
	writeSpec,
} from '@fluxer/openapi/src/output/SpecWriter';

type GenerateTarget = 'admin' | 'public';
interface GenerateOptions {
	validateOnly: boolean;
	outputPath: string | null;
	target: GenerateTarget | null;
}
interface GeneratedTargetSpec {
	target: GenerateTarget;
	outputPath: string;
	spec: WritableOpenAPISpec;
}
const API_DESCRIPTION =
	'API for Fluxer, a free and open source instant messaging and VoIP chat app built for friends, groups, and communities.';
function parseArgs(): GenerateOptions {
	const args = process.argv.slice(2);
	let validateOnly = false;
	let outputPath: string | null = null;
	let target: GenerateTarget | null = null;
	for (let i = 0; i < args.length; i++) {
		const arg = args[i];
		if (arg === '--validate-only' || arg === '-v') {
			validateOnly = true;
		} else if (arg === '--output' || arg === '-o') {
			const value = args[++i];
			if (!value || value.startsWith('-')) {
				throw new Error('--output requires a file path.');
			}
			outputPath = value;
		} else if (arg === '--target' || arg === '-t') {
			const value = args[++i];
			if (value !== 'admin' && value !== 'public') {
				throw new Error(`Invalid --target "${value}". Expected "public" or "admin".`);
			}
			target = value;
		} else {
			throw new Error(`Unknown argument: ${arg}`);
		}
	}
	return {validateOnly, outputPath, target};
}
function findRepositoryRoot(): string {
	let dir = process.cwd();
	for (;;) {
		const workspacePath = path.join(dir, 'pnpm-workspace.yaml');
		if (fs.existsSync(workspacePath)) {
			return dir;
		}
		const parent = path.dirname(dir);
		if (parent === dir) {
			break;
		}
		dir = parent;
	}
	throw new Error('Could not find repository root (no pnpm-workspace.yaml found)');
}
function getTargetOutputPath(basePath: string, target: GenerateTarget, customOutputPath: string | null): string {
	if (customOutputPath) {
		return customOutputPath;
	}
	return target === 'admin' ? getAdminOutputPath(basePath) : getApiPackageOutputPath(basePath);
}
function reportRoutesLeftOut(target: GenerateTarget, stats: OpenAPIGenerationStats): void {
	const groups: Array<[string, ReadonlyArray<SkippedRoute>]> = [
		['registered but not written to the spec', stats.skippedRoutes],
		['registered but not expressible as an OpenAPI path', stats.untemplatableRoutes],
	];
	for (const [title, routes] of groups) {
		if (routes.length === 0) {
			continue;
		}
		console.log(`${target} routes ${title}: ${routes.length.toString()}`);
		for (const route of [...routes].sort((a, b) => `${a.path} ${a.method}`.localeCompare(`${b.path} ${b.method}`))) {
			console.log(`  ${route.method} ${route.path}  ${route.reason}  (${route.source})`);
		}
	}
}
async function buildTargetSpec(basePath: string, target: GenerateTarget): Promise<WritableOpenAPISpec> {
	const generator = new OpenAPIGenerator({
		basePath,
		title: 'Fluxer API',
		version: '1.0.0',
		description: API_DESCRIPTION,
		serverUrl: 'https://api.fluxer.app/v1',
		routeScope: target,
		schemaTarget: target === 'admin' ? 'openapi-3.0' : 'draft-2020-12',
	});
	const {document, stats} = await generator.generateWithStats();
	reportRoutesLeftOut(target, stats);
	return document;
}
async function validateTargetSpec(target: GenerateTarget, spec: unknown): Promise<boolean> {
	const validationResult = await validateSpec(spec, {
		allowedOpenAPIVersions: target === 'admin' ? ['3.0.3'] : ['3.1.0'],
	});
	printValidationResult(validationResult);
	return validationResult.valid;
}
function printSummary(target: GenerateTarget, spec: WritableOpenAPISpec): void {
	const {
		paths,
		components: {schemas},
	} = spec;
	let operationCount = 0;
	for (const pathItem of Object.values(paths)) {
		operationCount += Object.keys(pathItem).length;
	}
	console.log(`Target: ${target}`);
	console.log(`Paths: ${Object.keys(paths).length}`);
	console.log(`Operations: ${operationCount}`);
	console.log(`Schemas: ${Object.keys(schemas).length}`);
}
async function main(): Promise<void> {
	const {validateOnly, outputPath: customOutputPath, target: requestedTarget} = parseArgs();
	const basePath = findRepositoryRoot();
	if (customOutputPath && !requestedTarget) {
		throw new Error('--output requires --target when generating or validating multiple specs.');
	}
	const targets: Array<GenerateTarget> = requestedTarget ? [requestedTarget] : ['public', 'admin'];
	console.log('Fluxer OpenAPI Specification Generator');
	console.log('======================================');
	console.log(`Base path: ${basePath}`);
	console.log(`Targets: ${targets.join(', ')}`);
	console.log('');
	if (validateOnly) {
		console.log('Running validation only...');
		let valid = true;
		for (const target of targets) {
			const outputPath = getTargetOutputPath(basePath, target, customOutputPath);
			console.log('');
			console.log(`Validating ${target} specification at ${outputPath}...`);
			try {
				const spec = readSpec(outputPath);
				valid = (await validateTargetSpec(target, spec)) && valid;
			} catch (error) {
				console.error(`Failed to validate ${target} specification:`, error);
				valid = false;
			}
		}
		process.exit(valid ? 0 : 1);
	}
	try {
		const generated: Array<GeneratedTargetSpec> = [];
		for (const target of targets) {
			const outputPath = getTargetOutputPath(basePath, target, customOutputPath);
			console.log(`Generating ${target} specification...`);
			const spec = await buildTargetSpec(basePath, target);
			console.log(`Validating ${target} specification...`);
			const valid = await validateTargetSpec(target, spec);
			if (!valid) {
				throw new Error(`${target} specification has validation errors; no specifications were written.`);
			}
			generated.push({target, outputPath, spec});
		}
		for (const {target, outputPath, spec} of generated) {
			console.log(`Writing ${target} specification to ${outputPath}...`);
			writeSpec(spec, outputPath);
			printSummary(target, spec);
			console.log('');
		}
		console.log('OpenAPI specifications generated successfully.');
	} catch (error) {
		console.error('Failed to generate specification:', error);
		process.exit(1);
	}
}
main().catch((error) => {
	console.error('Unhandled error:', error);
	process.exit(1);
});