@openfairygui/functions 0.2.0-alpha.0 → 0.2.0-alpha.11

package/src/codegen.ts

@@ -1,7 +1,7 @@
 import {
 	type Component,
-	type GComponent,
 	type Document,
+	type GComponent,
 	type GObject,
 	type Package,
 	ProjectType,
@@ -12,6 +12,7 @@ import {
 	UNITY_BINDER_TEMPLATE,
 	UNITY_COMPONENT_TEMPLATE,
 } from './codegen-templates.js';
+import { formatPluginError, type LoadedPlugin } from './plugins/loader.js';
 import type { CliCodeGenerationSettings, PublishFileSystem, RootProjectSettings } from './shared-types.js';
 
 export const AUTO_GENERATED_CODE_MARK = '/** This is an automatically generated class by FairyGUI. Please do not modify it. **/';
@@ -22,25 +23,15 @@ export interface PublishCodeGenerationOptions {
 	basePath?: string;
 	fs: PublishFileSystem;
 	packages: Package[];
+	plugins?: LoadedPlugin[];
 }
 
-interface ResolvedCodeGenerationSettings {
-	allowGenCode: boolean;
-	classNamePrefix: string;
-	memberNamePrefix: string;
-	packageName: string;
-	ignoreNoname: boolean;
-	getMemberByName: boolean;
-	codePath: string;
-	codeType: string;
-}
-
-interface ResolvedPackageCodegenPlan {
+export interface ResolvedPackageCodegenPlan {
 	outputDir: string;
 	packageFolderName: string;
 	packageNamespace: string;
 	binderClassName: string;
-	settings: ResolvedCodeGenerationSettings;
+	settings: CliCodeGenerationSettings;
 }
 
 interface FguiTypescriptVariant {
@@ -77,16 +68,22 @@ const SHARED_FGUI_TYPESCRIPT_VARIANT: FguiTypescriptVariant = {
 	runtimeNamespace: 'fgui',
 };
 
-interface CodegenMember {
+export interface CodegenMember {
 	index: number;
 	kind: 'child' | 'controller' | 'transition';
 	name: string;
 	originalName: string;
 	type: string;
 	ignored: boolean;
+	referencedComponent?: CodegenReferencedComponent;
 }
 
-interface CodegenClass {
+export interface CodegenReferencedComponent {
+	component: Component;
+	package: Package;
+}
+
+export interface CodegenClass {
 	classId: string;
 	className: string;
 	encodedClassName: string;
@@ -97,14 +94,28 @@ interface CodegenClass {
 	members: CodegenMember[];
 }
 
-export async function publishCodeGeneration(
-	doc: Document,
-	options: PublishCodeGenerationOptions,
-): Promise<void> {
+export async function publishCodeGeneration(doc: Document, options: PublishCodeGenerationOptions): Promise<void> {
 	const logger = doc.getLogger();
 	const settings = resolveCodeGenerationSettings(doc);
 	if (!settings.allowGenCode) return;
 
+	const plugins = options.plugins?.filter((plugin) => typeof plugin.plugin.genCode === 'function') ?? [];
+	if (plugins.length > 0) {
+		let handled = false;
+		for (const plugin of plugins) {
+			try {
+				await plugin.plugin.genCode(doc, settings, options);
+				handled = true;
+				logger.info(`publish: Generated code using plugin "${plugin.name}"`);
+			} catch (error) {
+				logger.warn(`publish: Code generation plugin "${plugin.name}" failed: ${formatPluginError(error)}`);
+			}
+		}
+		if (handled) {
+			return;
+		}
+	}
+
 	for (const pkg of options.packages) {
 		if (!pkg.getGenCode()) continue;
 
@@ -129,7 +140,7 @@ export async function publishCodeGeneration(
 	}
 }
 
-function resolveCodeGenerationSettings(doc: Document): ResolvedCodeGenerationSettings {
+export function resolveCodeGenerationSettings(doc: Document): Required<CliCodeGenerationSettings> {
 	const settings = (doc.getRoot().getSettings?.() ?? {}) as RootProjectSettings;
 	const publish = settings.publish ?? {};
 	const codeGeneration = publish.codeGeneration as CliCodeGenerationSettings | undefined;
@@ -159,11 +170,7 @@ function resolveCodeGenerationSettings(doc: Document): ResolvedCodeGenerationSet
 	};
 }
 
-function resolvePackageCodegenPlan(
-	pkg: Package,
-	settings: ResolvedCodeGenerationSettings,
-	options: PublishCodeGenerationOptions,
-): ResolvedPackageCodegenPlan | null {
+export function resolvePackageCodegenPlan(pkg: Package, settings: CliCodeGenerationSettings, options: PublishCodeGenerationOptions): ResolvedPackageCodegenPlan | null {
 	const rawCodePath = (pkg.getCodePath() || settings.codePath || '').trim();
 	if (!rawCodePath) return null;
 
@@ -276,17 +283,11 @@ async function cleanupGeneratedFiles(directory: string, fs: PublishFileSystem, e
 	}
 }
 
-function buildCodegenClasses(
-	doc: Document,
-	pkg: Package,
-	plan: ResolvedPackageCodegenPlan,
-): CodegenClass[] {
-	const exportedComponents = pkg.listComponents()
-		.filter((component) => component.getExported())
-		.sort((left, right) => left.getId().localeCompare(right.getId()));
+export function buildCodegenClasses(doc: Document, pkg: Package, plan: ResolvedPackageCodegenPlan): CodegenClass[] {
+	const codegenComponents = pkg.listComponents().sort((left, right) => left.getId().localeCompare(right.getId()));
 	const generatedById = new Map<string, CodegenClass>();
 
-	for (const component of exportedComponents) {
+	for (const component of codegenComponents) {
 		const encodedClassName = `${plan.settings.classNamePrefix}${normalizeTypeName(component.getName()) || 'Component'}`;
 		generatedById.set(component.getId(), {
 			classId: component.getId(),
@@ -300,7 +301,19 @@ function buildCodegenClasses(
 		});
 	}
 
-	for (const component of exportedComponents) {
+	for (const component of codegenComponents) {
+		const classInfo = generatedById.get(component.getId());
+		if (!classInfo) continue;
+		classInfo.members = buildCodegenMembers(doc, pkg, component, plan, generatedById);
+	}
+
+	for (const [componentId, classInfo] of generatedById) {
+		if (classInfo.members.every((member) => member.ignored)) {
+			generatedById.delete(componentId);
+		}
+	}
+
+	for (const component of codegenComponents) {
 		const classInfo = generatedById.get(component.getId());
 		if (!classInfo) continue;
 		classInfo.members = buildCodegenMembers(doc, pkg, component, plan, generatedById);
@@ -327,13 +340,17 @@ function buildCodegenMembers(
 	}
 
 	for (const child of component.listChildren()) {
+		if (!isRuntimeChild(child)) continue;
+		const index = childIndex++;
+		const resolvedChild = resolveChildType(doc, pkg, child, generatedById);
 		members.push(createMember(
 			ownerType,
 			'child',
-			resolveChildType(doc, pkg, child, generatedById),
+			resolvedChild.type,
 			child.getName(),
-			childIndex++,
+			index,
 			plan,
+			resolvedChild.referencedComponent,
 		));
 	}
 
@@ -355,6 +372,10 @@ function buildCodegenMembers(
 	return members;
 }
 
+function isRuntimeChild(child: GObject): boolean {
+	return child.propertyType !== 'GGroup' || (child as GObject & { getAdvanced?(): boolean }).getAdvanced?.() === true;
+}
+
 function createMember(
 	ownerType: string,
 	kind: CodegenMember['kind'],
@@ -362,6 +383,7 @@ function createMember(
 	originalName: string,
 	index: number,
 	plan: ResolvedPackageCodegenPlan,
+	referencedComponent?: CodegenReferencedComponent,
 ): CodegenMember {
 	const ignored = plan.settings.ignoreNoname && isDefaultMemberName(ownerType, kind, originalName);
 	return {
@@ -371,43 +393,59 @@ function createMember(
 		originalName,
 		type,
 		ignored,
+		referencedComponent,
 	};
 }
 
+interface ResolvedChildCodegenType {
+	type: string;
+	referencedComponent?: CodegenReferencedComponent;
+}
+
 function resolveChildType(
 	doc: Document,
 	pkg: Package,
 	child: GObject,
 	generatedById: Map<string, CodegenClass>,
-): string {
+): ResolvedChildCodegenType {
 	const src = (child as GObject & { getSrc?(): string }).getSrc?.();
 	if (src) {
-		const localResource = resolveChildSourceComponent(doc, pkg, src);
-		if (localResource) {
-			return generatedById.get(localResource.getId())?.encodedClassName
-				?? resolveComponentBaseType(localResource);
+		let referencedComponent: CodegenReferencedComponent | null = null;
+		if (src.startsWith('ui://')) {
+			const rest = src.slice(5);
+			const pkgId = rest.slice(0, 8);
+			const resourceId = rest.slice(8);
+			const targetPackage = doc.getRoot().listPackages().find((candidate) => candidate.getId() === pkgId);
+			const targetResource = targetPackage?.getResourceById(resourceId);
+			if (targetPackage && targetResource?.propertyType === 'Component') {
+				referencedComponent = { component: targetResource, package: targetPackage };
+			}
+		} else {
+			const packageId = (child as GComponent & { getPackageId?(): string }).getPackageId?.();
+			const targetPackage = packageId
+				? doc.getRoot().listPackages().find((candidate) => candidate.getId() === packageId)
+				: pkg;
+			const targetResource = targetPackage?.getResourceById(src);
+			if (targetPackage && targetResource?.propertyType === 'Component') {
+				referencedComponent = { component: targetResource, package: targetPackage };
+			}
+		}
+
+		if (referencedComponent) {
+			const localGeneratedClass = referencedComponent.package === pkg
+				? generatedById.get(referencedComponent.component.getId())
+				: undefined;
+			return {
+				type: localGeneratedClass?.encodedClassName ?? resolveComponentBaseType(referencedComponent.component),
+				referencedComponent,
+			};
 		}
 	}
 
 	const instanceExtType = (child as GComponent & { getInstanceExtType?(): string }).getInstanceExtType?.();
-	if (instanceExtType) return `G${instanceExtType}`;
-
-	return child.propertyType;
-}
-
-function resolveChildSourceComponent(doc: Document, pkg: Package, src: string): Component | null {
-	if (!src) return null;
-	if (src.startsWith('ui://')) {
-		const rest = src.slice(5);
-		const pkgId = rest.slice(0, 8);
-		const resourceId = rest.slice(8);
-		const targetPackage = doc.getRoot().listPackages().find((candidate) => candidate.getId() === pkgId);
-		const targetResource = targetPackage?.getResourceById(resourceId);
-		return targetResource?.propertyType === 'Component' ? targetResource : null;
-	}
+	if (instanceExtType) return { type: `G${instanceExtType}` };
 
-	const localResource = pkg.getResourceById(src);
-	return localResource?.propertyType === 'Component' ? localResource : null;
+	return { type: child.propertyType };
 }
 
 function resolveComponentBaseType(component: Component): string {
@@ -549,7 +587,7 @@ function resolveCodePath(
 	return projectBasePath ? trimTrailingSlashes(fs.join(projectBasePath, codePath)) : trimTrailingSlashes(codePath);
 }
 
-function resolveProjectBasePath(basePath: string | undefined): string {
+export function resolveProjectBasePath(basePath: string | undefined): string {
 	if (!basePath) return '';
 	const normalized = trimTrailingSlashes(basePath);
 	const assetsMatch = normalized.match(/^(.*)[/\\]assets(?:_[^/\\]+)?$/i);
@@ -578,13 +616,13 @@ function isDefaultMemberName(ownerType: string, kind: CodegenMember['kind'], nam
 	if (kind === 'transition') return false;
 
 	if (ownerType === 'GButton' || ownerType === 'GLabel' || ownerType === 'GComboBox') {
-		return name === 'title' || name === 'icon';
+		if (name === 'title' || name === 'icon') return true;
 	}
 	if (ownerType === 'GProgressBar') {
-		return name === 'bar' || name === 'bar_v' || name === 'title' || name === 'ani';
+		if (name === 'bar' || name === 'bar_v' || name === 'title' || name === 'ani') return true;
 	}
 	if (ownerType === 'GSlider') {
-		return name === 'bar' || name === 'bar_v' || name === 'grip' || name === 'title' || name === 'ani';
+		if (name === 'bar' || name === 'bar_v' || name === 'grip' || name === 'title' || name === 'ani') return true;
 	}
 	return /^n\d+(?:_.*)?$/i.test(name);
 }
@@ -647,10 +685,10 @@ async function writeTextFile(fs: PublishFileSystem, filePath: string, content: s
 	await fs.writeFileRaw(filePath, encodeText(content));
 }
 
-function encodeText(value: string): Uint8Array {
+export function encodeText(value: string): Uint8Array {
 	return new TextEncoder().encode(value);
 }
 
-function decodeText(value: Uint8Array): string {
+export function decodeText(value: Uint8Array): string {
 	return new TextDecoder().decode(value);
 }

package/src/index.ts

@@ -3,7 +3,29 @@ export { validate, type ValidateOptions, type ValidationResult, type ValidationI
 export { prune, type PruneOptions } from './prune.js';
 export { rename, type RenameOptions } from './rename.js';
 export { atlas, type AtlasOptions } from './atlas.js';
-export { publishCodeGeneration, AUTO_GENERATED_CODE_MARK, type PublishCodeGenerationOptions } from './codegen.js';
+export {
+	publishCodeGeneration,
+	AUTO_GENERATED_CODE_MARK,
+	type PublishCodeGenerationOptions,
+	type ResolvedPackageCodegenPlan,
+	resolvePackageCodegenPlan,
+	buildCodegenClasses,
+	type CodegenClass,
+	type CodegenMember,
+	type CodegenReferencedComponent,
+	encodeText,
+	decodeText,
+} from './codegen.js';
+
+
+export type {
+	CodeWriter,
+	ICodeWriterConfig,
+	MaybePromise,
+	Plugin,
+	PluginManifest,
+	PluginModule,
+} from './plugins/types.js';
 export {
 	restore,
 	type RestoreFileSystem,
@@ -24,6 +46,7 @@ export {
 } from './publish.js';
 export {
 	applyUamTransactionApp,
+	type ApplyUamTransactionAppDiagnostic,
 	type ApplyUamTransactionAppError,
 	type ApplyUamTransactionAppInput,
 	type ApplyUamTransactionAppResult,
@@ -39,4 +62,5 @@ export type {
 	PublishDependency,
 	PublishFileSystem,
 	RootProjectSettings,
+	CliCodeGenerationSettings,
 } from './shared-types.js';

package/src/plugins/loader.ts

@@ -0,0 +1,85 @@
+import type { Document } from '@openfairygui/core';
+import { createJiti } from 'jiti';
+import type { Plugin, PluginManifest, PluginModule } from './types.js';
+
+export interface LoadedPlugin {
+	name: string;
+	plugin: Plugin;
+}
+
+interface PluginPackageJson extends Partial<PluginManifest> {
+	name?: string;
+	main?: string;
+}
+
+// Keep Node builtins out of the neutral bundle resolver while still loading plugins in Node.
+const importNative = new Function('id', 'return import(id)') as <T>(id: string) => Promise<T>;
+
+export async function loadPlugins(doc: Document, pluginsDir: string): Promise<LoadedPlugin[]> {
+	if (!pluginsDir) return [];
+
+	const fs = await importNative<typeof import('node:fs/promises')>('node:fs/promises');
+	const path = await importNative<typeof import('node:path')>('node:path');
+	let entries: Array<{ name: string; isDirectory(): boolean }>;
+	try {
+		entries = await fs.readdir(pluginsDir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+
+	const plugins: LoadedPlugin[] = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const pluginDir = path.join(pluginsDir, entry.name);
+		try {
+			const manifest = await readPluginManifest(fs, path, pluginDir);
+			if (!manifest) continue;
+
+			const mainPath = resolvePluginMain(path, pluginDir, manifest);
+			const plugin = await loadPlugin(mainPath);
+			plugins.push({ name: manifest.name, plugin });
+		} catch (error) {
+			doc.getLogger().warn(`publish: Plugin "${entry.name}" was skipped: ${formatPluginError(error)}`);
+		}
+	}
+
+	return plugins;
+}
+
+export function formatPluginError(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+async function readPluginManifest(
+	fs: typeof import('node:fs/promises'),
+	path: typeof import('node:path'),
+	pluginDir: string,
+): Promise<PluginPackageJson | null> {
+	const manifestPath = path.join(pluginDir, 'package.json');
+	const content = await fs.readFile(manifestPath, 'utf-8');
+	const manifest = JSON.parse(content) as PluginPackageJson;
+	if (!manifest.name) throw new Error(`Codegen plugin at ${pluginDir} is missing package.json name.`);
+	if (!manifest.main) throw new Error(`Codegen plugin "${manifest.name}" is missing package.json main.`);
+	return manifest;
+}
+
+function resolvePluginMain(path: typeof import('node:path'), pluginDir: string, manifest: PluginPackageJson): string {
+	const mainPath = path.resolve(pluginDir, manifest.main!);
+	const relative = path.relative(pluginDir, mainPath);
+	if (relative.startsWith('..') || path.isAbsolute(relative)) {
+		throw new Error(`Codegen plugin "${manifest.name}" main must resolve inside its plugin directory.`);
+	}
+	return mainPath;
+}
+
+async function loadPlugin(mainPath: string): Promise<Plugin> {
+	const jiti = createJiti(import.meta.url);
+	const mod = await jiti.import<PluginModule>(mainPath);
+	const defaultExport = mod.default;
+	const plugin = isObject(defaultExport) ? defaultExport : mod;
+	return plugin as Plugin;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === 'object';
+}

package/src/plugins/types.ts

@@ -0,0 +1,47 @@
+import type { Document } from '@openfairygui/core';
+import type { PublishCodeGenerationOptions } from '../codegen.js';
+import type { PublishOptions } from '../publish.js';
+import type { CliCodeGenerationSettings } from '../shared-types.js';
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export interface PluginManifest {
+	name: string;
+	displayName?: string;
+	description?: string;
+	version?: string;
+	author?: {
+		name?: string;
+	};
+	icon?: string;
+	main: string;
+}
+
+export interface ICodeWriterConfig {
+	blockStart?: string;
+	blockEnd?: string;
+	blockFromNewLine?: boolean;
+	usingTabs?: boolean;
+	endOfLine?: string;
+	fileMark?: string;
+}
+
+export interface CodeWriter {
+	writeMark(): void;
+	writeln(fmt?: string, ...args: any[]): CodeWriter;
+	startBlock(): CodeWriter;
+	endBlock(): CodeWriter;
+	incIndent(): CodeWriter;
+	decIndent(): CodeWriter;
+	reset(): void;
+	toString(): string;
+	save(filePath: string): void;
+}
+
+export interface Plugin {
+	genCode?: (doc: Document, settings: Required<CliCodeGenerationSettings>, options: PublishCodeGenerationOptions) => MaybePromise<void>;
+	onPublishStart?: (doc: Document, options: PublishOptions) => MaybePromise<void>;
+	onPublishEnd?: (doc: Document, options: PublishOptions) => MaybePromise<void>;
+}
+
+export type PluginModule = Plugin & { default?: Plugin };