@atcute/lex-cli 2.4.0 → 2.5.0

package/src/codegen.ts

@@ -49,6 +49,33 @@ type Literal = string | number | boolean;
 
 const lit: (val: Literal | Literal[]) => string = JSON.stringify;
 
+interface LexPath {
+	nsid: string;
+	defId: string;
+}
+
+const toLexUri = (path: LexPath): string => {
+	const { nsid, defId } = path;
+	return defId === 'main' ? nsid : `${nsid}#${defId}`;
+};
+
+const resolvePath = (from: LexPath, ref: string): LexPath => {
+	const index = ref.indexOf('#');
+
+	// nsid (no hash)
+	if (index === -1) {
+		return { nsid: ref, defId: 'main' };
+	}
+
+	// #defId (local ref)
+	if (index === 0) {
+		return { nsid: from.nsid, defId: ref.slice(1) };
+	}
+
+	// nsid#defId (full ref)
+	return { nsid: ref.slice(0, index), defId: ref.slice(index + 1) };
+};
+
 const resolveExternalImport = (nsid: string, mappings: ImportMapping[]): ImportMapping | undefined => {
 	return mappings.find((mapping) => {
 		return mapping.nsid.some((pattern) => {
@@ -111,7 +138,7 @@ export const generateLexiconApi = async (opts: LexiconApiOptions): Promise<Lexic
 
 		for (const defId of sortedDefIds) {
 			const def = doc.defs[defId];
-			const defUri = `${doc.id}#${defId}`;
+			const path: LexPath = { nsid: doc.id, defId };
 
 			const camelcased = toCamelCase(defId);
 			const varname = `${camelcased}Schema`;
@@ -119,59 +146,59 @@ export const generateLexiconApi = async (opts: LexiconApiOptions): Promise<Lexic
 			let result: string;
 			switch (def.type) {
 				case 'query': {
-					result = generateXrpcQuery(imports, defUri, def);
+					result = generateXrpcQuery(imports, path, def);
 
 					file.imports += `import type {} from '@atcute/lexicons/ambient';\n`;
 
 					file.ambients += `declare module '@atcute/lexicons/ambient' {\n`;
 					file.ambients += `  interface XRPCQueries {\n`;
-					file.ambients += `    ${lit(stripMainHash(defUri))}: ${camelcased}Schema;\n`;
+					file.ambients += `    ${lit(toLexUri(path))}: ${camelcased}Schema;\n`;
 					file.ambients += `  }\n`;
 					file.ambients += `}`;
 					break;
 				}
 				case 'procedure': {
-					result = generateXrpcProcedure(imports, defUri, def);
+					result = generateXrpcProcedure(imports, path, def);
 
 					file.imports += `import type {} from '@atcute/lexicons/ambient';\n`;
 
 					file.ambients += `declare module '@atcute/lexicons/ambient' {\n`;
 					file.ambients += `  interface XRPCProcedures {\n`;
-					file.ambients += `    ${lit(stripMainHash(defUri))}: ${camelcased}Schema;\n`;
+					file.ambients += `    ${lit(toLexUri(path))}: ${camelcased}Schema;\n`;
 					file.ambients += `  }\n`;
 					file.ambients += `}`;
 					break;
 				}
 				case 'subscription': {
-					result = generateXrpcSubscription(imports, defUri, def);
+					result = generateXrpcSubscription(imports, path, def);
 
 					file.imports += `import type {} from '@atcute/lexicons/ambient';\n`;
 
 					file.ambients += `declare module '@atcute/lexicons/ambient' {\n`;
 					file.ambients += `  interface XRPCSubscriptions {\n`;
-					file.ambients += `    ${lit(stripMainHash(defUri))}: ${camelcased}Schema;\n`;
+					file.ambients += `    ${lit(toLexUri(path))}: ${camelcased}Schema;\n`;
 					file.ambients += `  }\n`;
 					file.ambients += `}`;
 					break;
 				}
 				case 'object': {
-					result = generateObject(imports, defUri, def);
+					result = generateObject(imports, path, def);
 					break;
 				}
 				case 'record': {
-					result = generateRecord(imports, defUri, def);
+					result = generateRecord(imports, path, def);
 
 					file.imports += `import type {} from '@atcute/lexicons/ambient';\n`;
 
 					file.ambients += `declare module '@atcute/lexicons/ambient' {\n`;
 					file.ambients += `  interface Records {\n`;
-					file.ambients += `    ${lit(stripMainHash(defUri))}: ${camelcased}Schema;\n`;
+					file.ambients += `    ${lit(toLexUri(path))}: ${camelcased}Schema;\n`;
 					file.ambients += `  }\n`;
 					file.ambients += `}`;
 					break;
 				}
 				case 'token': {
-					result = `${PURE} v.literal(${lit(stripMainHash(defUri))})`;
+					result = `${PURE} v.literal(${lit(toLexUri(path))})`;
 					break;
 				}
 				case 'permission-set': {
@@ -179,7 +206,7 @@ export const generateLexiconApi = async (opts: LexiconApiOptions): Promise<Lexic
 					continue;
 				}
 				default: {
-					result = generateType(imports, defUri, def);
+					result = generateType(imports, path, def);
 					break;
 				}
 			}
@@ -372,42 +399,42 @@ export const generateLexiconApi = async (opts: LexiconApiOptions): Promise<Lexic
 	return { files };
 };
 
-const generateXrpcQuery = (imports: ImportSet, defUri: string, spec: LexXrpcQuery): string => {
-	const params = generateXrpcParameters(imports, defUri, spec.parameters);
-	const output = generateXrpcBody(imports, defUri, spec.output);
+const generateXrpcQuery = (imports: ImportSet, path: LexPath, spec: LexXrpcQuery): string => {
+	const params = generateXrpcParameters(imports, path, spec.parameters);
+	const output = generateXrpcBody(imports, path, spec.output);
 
-	return `${PURE} v.query(${lit(stripMainHash(defUri))}, {\n"params": ${params}, "output": ${output} })`;
+	return `${PURE} v.query(${lit(toLexUri(path))}, {\n"params": ${params}, "output": ${output} })`;
 };
 
-const generateXrpcProcedure = (imports: ImportSet, defUri: string, spec: LexXrpcProcedure): string => {
-	const params = generateXrpcParameters(imports, defUri, spec.parameters);
-	const input = generateXrpcBody(imports, defUri, spec.input);
-	const output = generateXrpcBody(imports, defUri, spec.output);
+const generateXrpcProcedure = (imports: ImportSet, path: LexPath, spec: LexXrpcProcedure): string => {
+	const params = generateXrpcParameters(imports, path, spec.parameters);
+	const input = generateXrpcBody(imports, path, spec.input);
+	const output = generateXrpcBody(imports, path, spec.output);
 
-	return `${PURE} v.procedure(${lit(stripMainHash(defUri))}, {\n"params": ${params}, "input": ${input}, "output": ${output} })`;
+	return `${PURE} v.procedure(${lit(toLexUri(path))}, {\n"params": ${params}, "input": ${input}, "output": ${output} })`;
 };
 
-const generateXrpcSubscription = (imports: ImportSet, defUri: string, spec: LexXrpcSubscription): string => {
+const generateXrpcSubscription = (imports: ImportSet, path: LexPath, spec: LexXrpcSubscription): string => {
 	const schema = spec.message?.schema;
 
-	const params = generateXrpcParameters(imports, defUri, spec.parameters);
+	const params = generateXrpcParameters(imports, path, spec.parameters);
 
 	let inner = ``;
 
 	inner += `"params": ${params},`;
 
 	if (schema) {
-		const res = generateType(imports, defUri, schema);
+		const res = generateType(imports, path, schema);
 
 		inner += `get "message" () { return ${res} },`;
 	} else {
 		inner += `"message": null,`;
 	}
 
-	return `${PURE} v.subscription(${lit(stripMainHash(defUri))}, {\n${inner}})`;
+	return `${PURE} v.subscription(${lit(toLexUri(path))}, {\n${inner}})`;
 };
 
-const generateXrpcBody = (imports: ImportSet, defUri: string, spec: LexXrpcBody | undefined): string => {
+const generateXrpcBody = (imports: ImportSet, path: LexPath, spec: LexXrpcBody | undefined): string => {
 	if (spec === undefined) {
 		return `null`;
 	}
@@ -421,11 +448,11 @@ const generateXrpcBody = (imports: ImportSet, defUri: string, spec: LexXrpcBody
 		inner += `"type": "lex",`;
 
 		if (schema.type === 'object') {
-			const res = generateObject(imports, defUri, schema, 'none');
+			const res = generateObject(imports, path, schema, 'none');
 
 			inner += `"schema": ${res},`;
 		} else {
-			const res = generateType(imports, defUri, schema);
+			const res = generateType(imports, path, schema);
 
 			inner += `get "schema" () { return ${res} },`;
 		}
@@ -452,7 +479,7 @@ const generateXrpcBody = (imports: ImportSet, defUri: string, spec: LexXrpcBody
 
 const generateXrpcParameters = (
 	imports: ImportSet,
-	defUri: string,
+	path: LexPath,
 	spec: LexXrpcParameters | undefined,
 ): string => {
 	if (spec === undefined) {
@@ -489,11 +516,11 @@ const generateXrpcParameters = (
 		properties: transformedProperties ?? originalProperties,
 	};
 
-	return generateObject(imports, defUri, mask, 'none');
+	return generateObject(imports, path, mask, 'none');
 };
 
-const generateRecord = (imports: ImportSet, defUri: string, spec: LexRecord): string => {
-	const schema = generateObject(imports, defUri, spec.record, 'required');
+const generateRecord = (imports: ImportSet, path: LexPath, spec: LexRecord): string => {
+	const schema = generateObject(imports, path, spec.record, 'required');
 
 	let key = `${PURE} v.string()`;
 	if (spec.key) {
@@ -511,7 +538,7 @@ const generateRecord = (imports: ImportSet, defUri: string, spec: LexRecord): st
 
 const generateObject = (
 	imports: ImportSet,
-	defUri: string,
+	path: LexPath,
 	spec: LexObject,
 	writeType: 'required' | 'optional' | 'none' = 'optional',
 ): string => {
@@ -522,11 +549,11 @@ const generateObject = (
 
 	switch (writeType) {
 		case 'optional': {
-			inner += `"$type": ${PURE} v.optional(${PURE} v.literal(${lit(stripMainHash(defUri))})),`;
+			inner += `"$type": ${PURE} v.optional(${PURE} v.literal(${lit(toLexUri(path))})),`;
 			break;
 		}
 		case 'required': {
-			inner += `"$type": ${PURE} v.literal(${lit(stripMainHash(defUri))}),`;
+			inner += `"$type": ${PURE} v.literal(${lit(toLexUri(path))}),`;
 			break;
 		}
 	}
@@ -544,10 +571,10 @@ const generateObject = (
 
 	for (const [prop, propSpec] of sortedEntries) {
 		const lazy = isRefVariant(propSpec.type === 'array' ? propSpec.items : propSpec);
-		const optional = !required.has(prop) && !('default' in propSpec);
+		const optional = !required.has(prop) && !('default' in propSpec && propSpec.default !== undefined);
 		const nulled = nullable.has(prop);
 
-		let call = generateType(imports, defUri, propSpec, lazy);
+		let call = generateType(imports, path, propSpec, lazy);
 
 		if (nulled) {
 			call = `${PURE} v.nullable(${call})`;
@@ -678,62 +705,50 @@ const generateJsdocField = (spec: LexUserType | LexRefVariant | LexUnknown) => {
 	return res;
 };
 
-const generateType = (imports: ImportSet, defUri: string, spec: LexDefinableField, lazy = false): string => {
+const generateType = (imports: ImportSet, path: LexPath, spec: LexDefinableField, lazy = false): string => {
 	switch (spec.type) {
 		// LexRefVariant
 		case 'ref': {
-			const ref = spec.ref;
-
-			if (ref.startsWith('#')) {
-				const id = ref.slice(1);
-
-				return `${toCamelCase(id)}Schema`;
-			} else {
-				const [ns, id = 'main'] = ref.split('#');
-				if (ns === stripHash(defUri)) {
-					return `${toCamelCase(id)}Schema`;
-				}
-
-				imports.add(ns);
+			const refPath = resolvePath(path, spec.ref);
 
-				return `${toTitleCase(ns)}.${toCamelCase(id)}Schema`;
+			if (refPath.nsid === path.nsid) {
+				return `${toCamelCase(refPath.defId)}Schema`;
 			}
+
+			imports.add(refPath.nsid);
+			return `${toTitleCase(refPath.nsid)}.${toCamelCase(refPath.defId)}Schema`;
 		}
 		case 'union': {
-			const normalizedRefs = spec.refs
-				.map((ref): string => {
-					if (ref.startsWith('#')) {
-						return ref;
+			const refs = spec.refs
+				.map((ref) => {
+					const refPath = resolvePath(path, ref);
+					return { path: refPath, uri: toLexUri(refPath) };
+				})
+				.sort((a, b) => {
+					if (a.uri < b.uri) {
+						return -1;
 					}
-
-					const [ns, id = 'main'] = ref.split('#');
-					if (ns === stripHash(defUri)) {
-						return `#${id}`;
+					if (a.uri > b.uri) {
+						return 1;
 					}
 
-					return `${ns}#${id}`;
+					return 0;
 				})
-				.sort();
-
-			const refs = normalizedRefs.map((ref): string => {
-				if (ref.startsWith('#')) {
-					const id = ref.slice(1);
-
-					return `${toCamelCase(id)}Schema`;
-				} else {
-					const [ns, id = 'main'] = ref.split('#');
-					imports.add(ns);
+				.map(({ path: refPath }): string => {
+					if (refPath.nsid === path.nsid) {
+						return `${toCamelCase(refPath.defId)}Schema`;
+					}
 
-					return `${toTitleCase(ns)}.${toCamelCase(id)}Schema`;
-				}
-			});
+					imports.add(refPath.nsid);
+					return `${toTitleCase(refPath.nsid)}.${toCamelCase(refPath.defId)}Schema`;
+				});
 
 			return `${PURE} v.variant([${refs.join(', ')}]${spec.closed ? `, true` : ``})`;
 		}
 
 		// LexArray
 		case 'array': {
-			let item = generateType(imports, defUri, spec.items);
+			let item = generateType(imports, path, spec.items);
 			if (!lazy && (spec.items.type === 'ref' || spec.items.type === 'union')) {
 				item = `(() => { return ${item}; })`;
 			}
@@ -924,19 +939,6 @@ const isRefVariant = (spec: LexDefinableField): spec is LexRefVariant => {
 	return type === 'ref' || type === 'union';
 };
 
-const stripHash = (defUri: string): string => {
-	const index = defUri.indexOf('#');
-	if (index === -1) {
-		return defUri;
-	}
-
-	return defUri.slice(0, index);
-};
-
-const stripMainHash = (defUri: string): string => {
-	return defUri.endsWith('#main') ? defUri.slice(0, -'#main'.length) : defUri;
-};
-
 const toTitleCase = (v: string): string => {
 	v = v.replace(/^([a-z])/gi, (_, g) => g.toUpperCase());
 	v = v.replace(/[.#-]([a-z])/gi, (_, g) => g.toUpperCase());

package/src/commands/export.ts

@@ -0,0 +1,106 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+import type { LexiconDoc } from '@atcute/lexicon-doc';
+import { merge, object } from '@optique/core/constructs';
+import { message } from '@optique/core/message';
+import { type InferValue } from '@optique/core/parser';
+import { command, constant } from '@optique/core/primitives';
+import pc from 'picocolors';
+import prettier from 'prettier';
+
+import { loadConfig, type ExportConfig, type NormalizedConfig } from '../config.js';
+import { loadLexicons } from '../lexicon-loader.js';
+import { sharedOptions } from '../shared-options.js';
+
+export const exportCommandSchema = command(
+	'export',
+	merge(
+		object({
+			type: constant('export'),
+		}),
+		sharedOptions,
+	),
+	{
+		brief: message`export lexicon documents as JSON files`,
+		description: message`exports lexicon documents (from JSON or builder files) to JSON format for publishing or distribution.`,
+	},
+);
+
+export type ExportCommand = InferValue<typeof exportCommandSchema>;
+
+/**
+ * ensures export configuration is present
+ * @param config the normalized config
+ * @returns the export config
+ */
+const ensureExportConfig = (config: NormalizedConfig): ExportConfig => {
+	if (!config.export) {
+		console.error(pc.bold(pc.red(`export configuration missing`)));
+		process.exit(1);
+	}
+
+	return config.export;
+};
+
+/**
+ * writes a lexicon document to disk as formatted JSON
+ * @param outdir output directory
+ * @param nsid the NSID of the lexicon
+ * @param doc the lexicon document
+ * @param prettierConfig prettier configuration
+ */
+const writeLexicon = async (
+	outdir: string,
+	nsid: string,
+	doc: LexiconDoc,
+	prettierConfig: prettier.Options | null,
+): Promise<void> => {
+	const nsidPath = nsid.replaceAll('.', '/');
+	const target = path.join(outdir, `${nsidPath}.json`);
+	const dirname = path.dirname(target);
+
+	const code = await prettier.format(JSON.stringify(doc, null, 2), {
+		...(prettierConfig ?? {}),
+		parser: 'json',
+	});
+
+	await fs.mkdir(dirname, { recursive: true });
+	await fs.writeFile(target, code);
+};
+
+/**
+ * runs the export command to write lexicon documents as JSON files
+ * @param args parsed command arguments
+ */
+export const runExport = async (args: ExportCommand): Promise<void> => {
+	const config = await loadConfig(args.config);
+	const exportConfig = ensureExportConfig(config);
+
+	// use export.files if specified, otherwise fall back to root files config
+	const files = exportConfig.files ?? config.files;
+	const outdir = path.resolve(config.root, exportConfig.outdir);
+	const prettierConfig = await prettier.resolveConfig(config.root, { editorconfig: true });
+
+	// load lexicons from files
+	const loaded = await loadLexicons(files, config.root);
+
+	if (loaded.length === 0) {
+		console.warn(pc.yellow(`warning: no lexicons found to export`));
+		return;
+	}
+
+	// clean output directory if requested
+	if (exportConfig.clean) {
+		await fs.rm(outdir, { recursive: true, force: true });
+	}
+
+	await fs.mkdir(outdir, { recursive: true });
+
+	// write each lexicon as JSON
+	for (const { nsid, doc } of loaded) {
+		await writeLexicon(outdir, nsid, doc, prettierConfig);
+	}
+
+	console.log(pc.green(`exported ${loaded.length} lexicon(s) to ${outdir}`));
+};

package/src/commands/generate.ts

@@ -0,0 +1,170 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+import { merge, object } from '@optique/core/constructs';
+import { message } from '@optique/core/message';
+import { type InferValue } from '@optique/core/parser';
+import { command, constant } from '@optique/core/primitives';
+import pc from 'picocolors';
+
+import { generateLexiconApi, type ImportMapping } from '../codegen.js';
+import { loadConfig } from '../config.js';
+import { loadLexicons } from '../lexicon-loader.js';
+import { packageJsonSchema } from '../lexicon-metadata.js';
+import { sharedOptions } from '../shared-options.js';
+
+/**
+ * resolves package imports to ImportMapping[]
+ */
+const resolveImportsToMappings = async (
+	imports: string[],
+	configDirname: string,
+): Promise<ImportMapping[]> => {
+	const mappings: ImportMapping[] = [];
+
+	for (const packageName of imports) {
+		// walk up from config directory to find package in node_modules
+		let packageJson: unknown;
+		let currentDir = configDirname;
+		let found = false;
+
+		while (currentDir !== path.dirname(currentDir)) {
+			const candidatePath = path.join(currentDir, 'node_modules', packageName, 'package.json');
+			try {
+				const content = await fs.readFile(candidatePath, 'utf8');
+				packageJson = JSON.parse(content);
+				found = true;
+				break;
+			} catch (err: any) {
+				// only continue to parent if file not found
+				if (err.code !== 'ENOENT') {
+					console.error(pc.bold(pc.red(`failed to read package.json for "${packageName}":`)));
+					console.error(err);
+					process.exit(1);
+				}
+
+				// not found, try parent directory
+				currentDir = path.dirname(currentDir);
+			}
+		}
+
+		if (!found) {
+			console.error(pc.bold(pc.red(`failed to resolve package "${packageName}"`)));
+			console.error(`Could not find package in node_modules starting from ${configDirname}`);
+			process.exit(1);
+		}
+
+		// validate package.json
+		const result = packageJsonSchema.try(packageJson, { mode: 'passthrough' });
+		if (!result.ok) {
+			console.error(pc.bold(pc.red(`invalid atcute:lexicons in "${packageName}":`)));
+			console.error(result.message);
+
+			for (const issue of result.issues) {
+				console.log(`- ${issue.code} at .${issue.path.join('.')}`);
+			}
+
+			process.exit(1);
+		}
+
+		const lexicons = result.value['atcute:lexicons'];
+		if (!lexicons?.mappings) {
+			continue;
+		}
+
+		// convert mapping to ImportMapping[]
+		for (const [pattern, entry] of Object.entries(lexicons.mappings)) {
+			const isWildcard = pattern.endsWith('.*');
+
+			mappings.push({
+				nsid: [pattern],
+				imports: (nsid: string) => {
+					// check if pattern matches
+					if (isWildcard) {
+						if (!nsid.startsWith(pattern.slice(0, -1))) {
+							throw new Error(`NSID ${nsid} does not match pattern ${pattern}`);
+						}
+					} else {
+						if (nsid !== pattern) {
+							throw new Error(`NSID ${nsid} does not match pattern ${pattern}`);
+						}
+					}
+
+					const nsidPrefix = isWildcard ? pattern.slice(0, -2) : pattern;
+					const nsidRemainder = isWildcard ? nsid.slice(nsidPrefix.length + 1) : '';
+
+					let expandedPath = entry.path
+						.replaceAll('{{nsid}}', nsid.replaceAll('.', '/'))
+						.replaceAll('{{nsid_remainder}}', nsidRemainder.replaceAll('.', '/'))
+						.replaceAll('{{nsid_prefix}}', nsidPrefix.replaceAll('.', '/'));
+
+					if (expandedPath === '.') {
+						expandedPath = packageName;
+					} else if (expandedPath.startsWith('./')) {
+						expandedPath = `${packageName}/${expandedPath.slice(2)}`;
+					}
+
+					return {
+						type: entry.type,
+						from: expandedPath,
+					};
+				},
+			});
+		}
+	}
+
+	return mappings;
+};
+
+export const generateCommandSchema = command(
+	'generate',
+	merge(
+		object({
+			type: constant('generate'),
+		}),
+		sharedOptions,
+	),
+	{
+		brief: message`generate type definitions from lexicon documents`,
+		description: message`reads lexicon documents from the configured files and generates TypeScript type definitions and runtime validators.`,
+	},
+);
+
+export type GenerateCommand = InferValue<typeof generateCommandSchema>;
+
+/**
+ * runs the generate command to create type definitions from lexicon documents
+ * @param args parsed command arguments
+ */
+export const runGenerate = async (args: GenerateCommand): Promise<void> => {
+	const config = await loadConfig(args.config);
+
+	// resolve imports to mappings
+	const importMappings = config.imports ? await resolveImportsToMappings(config.imports, config.root) : [];
+	const allMappings = [...importMappings, ...(config.mappings ?? [])];
+
+	// load lexicons from files
+	const loaded = await loadLexicons(config.files, config.root);
+	const documents = loaded.map((l) => l.doc);
+
+	const generationResult = await generateLexiconApi({
+		documents: documents,
+		mappings: allMappings,
+		modules: {
+			importSuffix: config.modules?.importSuffix ?? '.js',
+		},
+		prettier: {
+			cwd: process.cwd(),
+		},
+	});
+
+	const outdir = path.join(config.root, config.outdir);
+
+	for (const file of generationResult.files) {
+		const filename = path.join(outdir, file.filename);
+		const dirname = path.dirname(filename);
+
+		await fs.mkdir(dirname, { recursive: true });
+		await fs.writeFile(filename, file.code);
+	}
+};