@gtkx/codegen 0.21.0 → 1.0.0-rc.2

package/src/store/gi-store.ts

@@ -0,0 +1,92 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { FINGERPRINT_FILENAME, type GiFingerprint } from "../fingerprint.js";
+import { buildManifest, type StoreOptions, subpathExport, writeStore } from "./store-fs.js";
+
+type GiStoreOptions = StoreOptions;
+
+type GiNamespaceInput = {
+    directory: string;
+    rawSource: string;
+};
+
+type CollectedFile = {
+    fileName: string;
+    source: string;
+};
+
+const OVERRIDES_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "overrides");
+
+const overrideFiles = (directory: string): string[] => {
+    const dir = join(OVERRIDES_ROOT, directory);
+
+    if (!existsSync(dir)) {
+        return [];
+    }
+
+    return readdirSync(dir).filter((name) => name.endsWith(".ejs") && name !== "index.ts.ejs");
+};
+
+const barrelSource = (directory: string): string => {
+    const overrideIndex = join(OVERRIDES_ROOT, directory, "index.ts.ejs");
+
+    if (!existsSync(overrideIndex)) {
+        return `export * from "./${directory}.js";\n`;
+    }
+
+    return readFileSync(overrideIndex, "utf8");
+};
+
+const collectStoreSources = (
+    namespaces: GiNamespaceInput[],
+): { collected: CollectedFile[]; exportsMap: Record<string, unknown> } => {
+    const exportsMap: Record<string, unknown> = {};
+    const collected: CollectedFile[] = [];
+
+    for (const { directory, rawSource } of namespaces) {
+        collected.push({
+            fileName: `${directory}/${directory}.ts`,
+            source: rawSource,
+        });
+
+        for (const file of overrideFiles(directory)) {
+            collected.push({
+                fileName: `${directory}/overrides/${file.replace(/\.ejs$/, "")}`,
+                source: readFileSync(join(OVERRIDES_ROOT, directory, file), "utf8"),
+            });
+        }
+
+        collected.push({
+            fileName: `${directory}/index.ts`,
+            source: barrelSource(directory),
+        });
+
+        exportsMap[`./${directory}`] = subpathExport(`${directory}/index`);
+    }
+
+    return { collected, exportsMap };
+};
+
+const writeGiStore = (
+    options: GiStoreOptions,
+    namespaces: GiNamespaceInput[],
+    fingerprint: GiFingerprint,
+): void => {
+    const { collected, exportsMap } = collectStoreSources(namespaces);
+
+    writeStore({
+        storeDir: options.storeDir,
+        linkDir: options.linkDir,
+        files: collected,
+        manifest: buildManifest({
+            name: "@gtkx/gi",
+            version: options.version,
+            exports: exportsMap,
+            peerDependencies: { "@gtkx/runtime": "*" },
+        }),
+        rawFiles: [{ relativePath: FINGERPRINT_FILENAME, content: `${JSON.stringify(fingerprint, null, 2)}\n` }],
+    });
+};
+
+export { writeGiStore, type GiStoreOptions, type GiNamespaceInput };

package/src/store/jsx/element-components.ts

@@ -0,0 +1,152 @@
+import { sourceStringLiteral } from "@gtkx/utils";
+import type { Library } from "../../gir/library.js";
+import type { GirNamespace } from "../../gir/namespace.js";
+import type { ImportsBuilder } from "../../writer/imports.js";
+import type { LazyElementSpec } from "./element-prop-types.js";
+import { renderJsDoc } from "../../writer/doc.js";
+import { ancestorGlibNames, type GlibNamedClass } from "./intrinsic-elements.js";
+
+/** A component that wraps a generated element, keyed by GLib type name (built-in or user-provided). */
+type ElementComponent = { module: string; export: string };
+/** Component wrappers keyed by GLib type name; the framework's built-ins merged with the project's own. */
+type ElementComponentOverrides = Record<string, ElementComponent>;
+
+type ExportCollector = {
+    imports: ImportsBuilder;
+    exportedNames: Set<string>;
+    exportLines: string[];
+};
+
+type CandidateExportOptions = {
+    targetNamespace: GirNamespace;
+    library: Library;
+    virtualNames: Set<string>;
+    intrinsicElements: GlibNamedClass[];
+    components: Record<string, ElementComponent>;
+};
+
+const generateElementComponentsSection = (
+    targetNamespace: GirNamespace,
+    library: Library,
+    options: {
+        imports: ImportsBuilder;
+        lazyElements: LazyElementSpec[];
+        intrinsicElements: GlibNamedClass[];
+        components: ElementComponentOverrides;
+    },
+): { source: string; exportedNames: Set<string> } => {
+    const collector: ExportCollector = { imports: options.imports, exportedNames: new Set(), exportLines: [] };
+    const lazyElements = options.lazyElements;
+    const virtualNames = new Set(lazyElements.map((entry) => entry.element));
+
+    collectCandidateExports(collector, {
+        targetNamespace,
+        library,
+        virtualNames,
+        intrinsicElements: options.intrinsicElements,
+        components: options.components,
+    });
+
+    collectLazyElementExports(collector, lazyElements);
+    const source = collector.exportLines.join("\n\n");
+
+    return { source, exportedNames: collector.exportedNames };
+};
+
+const appendCandidateExport = (
+    collector: ExportCollector,
+    candidate: GlibNamedClass,
+    options: CandidateExportOptions,
+): void => {
+    const { targetNamespace, library, virtualNames, components } = options;
+
+    if (candidate.namespace.name !== targetNamespace.name) {
+        return;
+    }
+
+    if (virtualNames.has(candidate.glibName)) {
+        return;
+    }
+
+    const line = renderCandidateExport(candidate, library, collector.imports, components);
+    collector.exportLines.push(line);
+    collector.exportedNames.add(candidate.glibName);
+};
+
+// An abstract GType cannot be instantiated: `g_object_new` on one is a fatal GObject error rather
+// than a NULL return. Its props interface and metadata still have to be emitted, since every
+// concrete subclass extends them, so only the constructible component export is withheld.
+const collectCandidateExports = (collector: ExportCollector, options: CandidateExportOptions): void => {
+    for (const candidate of options.intrinsicElements) {
+        if (candidate.klass.isAbstract) {
+            continue;
+        }
+
+        appendCandidateExport(collector, candidate, options);
+    }
+};
+
+const collectLazyElementExports = (collector: ExportCollector, lazyElements: LazyElementSpec[]): void => {
+    for (const spec of lazyElements) {
+        collector.imports.addNamed("@gtkx/react/internal", "createElementComponent", false);
+        collector.imports.addNamed("react", "ReactNode", true);
+        collector.exportLines.push(renderLazyElementExport(spec));
+        collector.exportedNames.add(spec.element);
+    }
+};
+
+const renderLazyElementExport = (spec: LazyElementSpec): string => {
+    const factory = `createElementComponent(${sourceStringLiteral(spec.element)})`;
+    const component = `export const ${spec.element}: (props: ${spec.typeName}) => ReactNode = ${factory};`;
+
+    return `${spec.typeSource}\n\n${component}`;
+};
+
+const renderCandidateExport = (
+    candidate: GlibNamedClass,
+    library: Library,
+    imports: ImportsBuilder,
+    components: Record<string, ElementComponent>,
+): string => {
+    const { glibName, klass, namespace } = candidate;
+    const ancestry = ancestorGlibNames(klass, namespace, library);
+    const component = resolveElementComponent(ancestry, components);
+    imports.addNamed("@gtkx/react/internal", "createElementComponent", false);
+    imports.addNamed("react", "ReactNode", true);
+
+    if (component !== undefined) {
+        imports.addNamed(component.module, component.export, false);
+    }
+
+    return `${renderJsDoc(klass.doc)}${renderElementComponentExport(glibName, component)}`;
+};
+
+/** The component for the nearest ancestry match, most-derived first; user overrides win on their exact type. */
+const resolveElementComponent = (
+    ancestry: string[],
+    components: Record<string, ElementComponent>,
+): ElementComponent | undefined => {
+    for (const name of ancestry) {
+        const found = components[name];
+
+        if (found !== undefined) {
+            return found;
+        }
+    }
+
+    return undefined;
+};
+
+const renderElementComponentExport = (glibName: string, component: ElementComponent | undefined): string => {
+    const propsType = `${glibName}Props`;
+    const annotation = `(props: ${propsType}) => ReactNode`;
+    const factoryCall = `createElementComponent(${sourceStringLiteral(glibName)})`;
+
+    if (component === undefined) {
+        return `export const ${glibName}: ${annotation} = ${factoryCall};`;
+    }
+
+    return `export const ${glibName}: ${annotation} = ${component.export}(${factoryCall});`;
+};
+
+export { generateElementComponentsSection, type ElementComponent, type ElementComponentOverrides };

package/src/store/jsx/element-prop-imports.ts

@@ -0,0 +1,24 @@
+/** Props interface a generated element's props extend, declared by hand in `@gtkx/react`. */
+type ElementPropTypeRef = { type: string; module: string; export: string };
+/** Base props interface each element extends, keyed by GLib type name (the module exports it). */
+type ElementProps = Record<string, { module: string; export: string }>;
+
+const elementProps: Map<string, { module: string; export: string }> = new Map();
+
+/** Installs the base props each element extends (GLib type name → `{ module, export }`); set once per run. */
+const setElementProps = (props: ElementProps): void => {
+    elementProps.clear();
+
+    for (const [glibName, ref] of Object.entries(props)) {
+        elementProps.set(glibName, ref);
+    }
+};
+
+/** The base props interface an element extends, when its element config declares one. */
+const elementPropTypeFor = (glibName: string): ElementPropTypeRef | undefined => {
+    const ref = elementProps.get(glibName);
+
+    return ref === undefined ? undefined : { type: glibName, module: ref.module, export: ref.export };
+};
+
+export { setElementProps, elementPropTypeFor, type ElementPropTypeRef, type ElementProps };

package/src/store/jsx/element-prop-types.ts

@@ -0,0 +1,59 @@
+import { toCamelIdentifier } from "@gtkx/utils";
+import type { GirClass } from "../../gir/class.js";
+import { getChain, type GirIndex, type GirTypeEntry } from "./gir-index.js";
+import { getGlibName } from "./intrinsic-elements.js";
+
+type LazyElementSpec = {
+    element: string;
+    typeName: string;
+    typeSource: string;
+};
+
+const appendConstructOnlyNames = (klass: GirClass, names: string[]): void => {
+    for (const property of klass.properties) {
+        if (property.constructOnly) {
+            names.push(toCamelIdentifier(property.name));
+        }
+    }
+};
+
+const constructOnlyNames = (context: GirIndex, entry: GirTypeEntry): string[] => {
+    const names: string[] = [];
+
+    for (const klass of getChain(context, entry)) {
+        appendConstructOnlyNames(klass, names);
+    }
+
+    return names;
+};
+
+const createLazyElementSpec = (context: GirIndex, element: string, entry: GirTypeEntry): LazyElementSpec => {
+    const typeName = `${element}ElementProps`;
+    const baseName = getGlibName(entry.klass) ?? element;
+    const omitted = constructOnlyNames(context, entry);
+    const omitUnion = omitted.map((name) => JSON.stringify(name)).join(" | ");
+    const base = omitted.length === 0 ? `${baseName}Props` : `Omit<${baseName}Props, ${omitUnion}>`;
+
+    return { element, typeName, typeSource: `export type ${typeName} = ${base} & { children?: ReactNode };` };
+};
+
+/** Lazy element prop types to emit, grouped by the namespace declaring each element. */
+const lazyElementSpecs = (context: GirIndex, lazyElements: string[]): Map<string, LazyElementSpec[]> => {
+    const specs: Map<string, LazyElementSpec[]> = new Map();
+
+    for (const element of lazyElements) {
+        const entry = context.index.get(element);
+
+        if (entry === undefined) {
+            continue;
+        }
+
+        const list = specs.get(entry.namespace.name) ?? [];
+        list.push(createLazyElementSpec(context, element, entry));
+        specs.set(entry.namespace.name, list);
+    }
+
+    return specs;
+};
+
+export { lazyElementSpecs, type LazyElementSpec };

package/src/store/jsx/gir-index.ts

@@ -0,0 +1,62 @@
+import type { GirClass } from "../../gir/class.js";
+import type { Library } from "../../gir/library.js";
+import type { GirNamespace } from "../../gir/namespace.js";
+import { ancestorChain } from "../../gir/ancestry.js";
+import { getGlibName, implementedInterfaces } from "./intrinsic-elements.js";
+
+type GirTypeEntry = {
+    klass: GirClass;
+    namespace: GirNamespace;
+    isInterface: boolean;
+};
+
+type GirIndex = {
+    library: Library;
+    index: Map<string, GirTypeEntry>;
+};
+
+const indexClasses = (
+    index: Map<string, GirTypeEntry>,
+    classes: Iterable<GirClass>,
+    namespace: GirNamespace,
+    isInterface: boolean,
+): void => {
+    for (const klass of classes) {
+        const glibName = getGlibName(klass);
+
+        if (glibName !== undefined && !index.has(glibName)) {
+            index.set(glibName, { klass, namespace, isInterface });
+        }
+    }
+};
+
+const buildGirIndex = (library: Library): GirIndex => {
+    const index: Map<string, GirTypeEntry> = new Map();
+
+    for (const namespace of library.namespaces.values()) {
+        indexClasses(index, namespace.classes, namespace, false);
+        indexClasses(index, namespace.interfaces, namespace, true);
+    }
+
+    return { library, index };
+};
+
+const getChain = (context: GirIndex, entry: GirTypeEntry): GirClass[] => {
+    if (entry.isInterface) {
+        return [entry.klass];
+    }
+
+    const chain: GirClass[] = [];
+
+    for (const { klass } of ancestorChain(context.library, entry.klass, entry.namespace.name)) {
+        chain.push(klass);
+    }
+
+    for (const iface of implementedInterfaces(entry.klass, entry.namespace, context.library)) {
+        chain.push(iface.klass);
+    }
+
+    return chain;
+};
+
+export { buildGirIndex, getChain, type GirTypeEntry, type GirIndex };

package/src/store/jsx/intrinsic-elements.ts

@@ -0,0 +1,262 @@
+import { sortStringsBy, toCamelIdentifier, upperFirst } from "@gtkx/utils";
+import type { GirClass } from "../../gir/class.js";
+import type { Library } from "../../gir/library.js";
+import type { GirNamespace } from "../../gir/namespace.js";
+import { ancestorChain } from "../../gir/ancestry.js";
+
+type GlibNamedClass = {
+    glibName: string;
+    klass: GirClass;
+    namespace: GirNamespace;
+};
+
+type ResolvedQualifiedInterface = { klass: GirClass; namespace: GirNamespace };
+
+type InterfaceVisitState = {
+    library: Library;
+    visited: Set<string>;
+    result: ResolvedQualifiedInterface[];
+};
+
+type HasContainerProps = (glibName: string | undefined) => boolean;
+
+type InterfacePropsCollector = {
+    library: Library;
+    targetNamespaceName: string;
+    hasContainerProps: HasContainerProps;
+    seen: Set<string>;
+    result: ResolvedQualifiedInterface[];
+};
+
+const signalHandlerName = (signalName: string): string => `on${upperFirst(toCamelIdentifier(signalName))}`;
+
+function* classesWithGlibNameIn(namespace: GirNamespace): IterableIterator<GlibNamedClass> {
+    for (const klass of namespace.classes) {
+        const glibName = getGlibName(klass);
+
+        if (glibName === undefined) {
+            continue;
+        }
+
+        yield { glibName, klass, namespace };
+    }
+}
+
+function* iterateClassesWithGlibName(library: Library): IterableIterator<GlibNamedClass> {
+    for (const namespace of library.namespaces.values()) {
+        yield* classesWithGlibNameIn(namespace);
+    }
+}
+
+function collectImplementedInterface(state: InterfaceVisitState, name: string, fromNamespace: GirNamespace): void {
+    const resolved = state.library.resolveType(fromNamespace.name, name);
+
+    if (resolved?.kind !== "interface") {
+        return;
+    }
+
+    const key = `${resolved.namespace.name}.${resolved.value.name}`;
+
+    if (state.visited.has(key)) {
+        return;
+    }
+
+    state.visited.add(key);
+    state.result.push({ klass: resolved.value, namespace: resolved.namespace });
+    visitImplementedInterfaces(state, resolved.value.prerequisites, resolved.namespace);
+}
+
+function visitImplementedInterfaces(state: InterfaceVisitState, names: string[], fromNamespace: GirNamespace): void {
+    for (const name of names) {
+        collectImplementedInterface(state, name, fromNamespace);
+    }
+}
+
+const implementedInterfaces = (
+    klass: GirClass,
+    namespace: GirNamespace,
+    library: Library,
+): ResolvedQualifiedInterface[] => {
+    const state: InterfaceVisitState = { library, visited: new Set<string>(), result: [] };
+    visitImplementedInterfaces(state, klass.implements, namespace);
+
+    return state.result;
+};
+
+const getGlibName = (klass: GirClass): string | undefined => klass.glibTypeName ?? klass.cType;
+const giNamespaceAlias = (namespaceName: string): string => `${namespaceName}$`;
+const hasNoContainerProps: HasContainerProps = () => false;
+
+const hasInterfacePropsBody = (
+    klass: GirClass,
+    hasContainerProps: HasContainerProps = hasNoContainerProps,
+): boolean => klass.properties.length > 0 || klass.signals.length > 0 || hasContainerProps(getGlibName(klass));
+
+const qualifiedInterfaceKey = (iface: ResolvedQualifiedInterface): string =>
+    `${iface.namespace.name}.${iface.klass.name}`;
+
+const isCollectibleInterface = (
+    iface: ResolvedQualifiedInterface,
+    targetNamespaceName: string,
+    hasContainerProps: HasContainerProps,
+): boolean => hasInterfacePropsBody(iface.klass, hasContainerProps) && iface.namespace.name === targetNamespaceName;
+
+const parentImplementedInterfaceKeys = (klass: GirClass, namespace: GirNamespace, library: Library): Set<string> => {
+    const keys: Set<string> = new Set();
+
+    if (klass.parent === undefined) {
+        return keys;
+    }
+
+    const resolvedParent = library.resolveType(namespace.name, klass.parent);
+
+    if (resolvedParent?.kind !== "class") {
+        return keys;
+    }
+
+    for (const iface of implementedInterfaces(resolvedParent.value, resolvedParent.namespace, library)) {
+        keys.add(qualifiedInterfaceKey(iface));
+    }
+
+    return keys;
+};
+
+const newlyImplementedInterfaces = (
+    klass: GirClass,
+    namespace: GirNamespace,
+    library: Library,
+    hasContainerProps: HasContainerProps = hasNoContainerProps,
+): ResolvedQualifiedInterface[] => {
+    const inherited = parentImplementedInterfaceKeys(klass, namespace, library);
+
+    const own = implementedInterfaces(klass, namespace, library).filter(
+        (iface) =>
+            hasInterfacePropsBody(iface.klass, hasContainerProps) && !inherited.has(qualifiedInterfaceKey(iface)),
+    );
+
+    return sortStringsBy(own, qualifiedInterfaceKey);
+};
+
+const collectInterfacePropsFromElement = (element: GlibNamedClass, collector: InterfacePropsCollector): void => {
+    const { library, targetNamespaceName, hasContainerProps, seen, result } = collector;
+
+    for (const iface of implementedInterfaces(element.klass, element.namespace, library)) {
+        const key = qualifiedInterfaceKey(iface);
+
+        if (seen.has(key)) {
+            continue;
+        }
+
+        seen.add(key);
+
+        if (isCollectibleInterface(iface, targetNamespaceName, hasContainerProps)) {
+            result.push(iface);
+        }
+    }
+};
+
+const collectInterfacePropsClasses = (
+    library: Library,
+    intrinsicElements: GlibNamedClass[],
+    targetNamespaceName: string,
+    hasContainerProps: HasContainerProps = hasNoContainerProps,
+): ResolvedQualifiedInterface[] => {
+    const collector: InterfacePropsCollector = {
+        library,
+        targetNamespaceName,
+        hasContainerProps,
+        seen: new Set<string>(),
+        result: [],
+    };
+
+    for (const element of intrinsicElements) {
+        collectInterfacePropsFromElement(element, collector);
+    }
+
+    return sortStringsBy(collector.result, qualifiedInterfaceKey);
+};
+
+const ancestorGlibNames = (klass: GirClass, namespace: GirNamespace, library: Library): string[] => {
+    const names: string[] = [];
+
+    for (const { klass: ancestor } of ancestorChain(library, klass, namespace.name)) {
+        const glibName = getGlibName(ancestor);
+
+        if (glibName !== undefined) {
+            names.push(glibName);
+        }
+    }
+
+    return names;
+};
+
+const hasMatchingAncestor = (
+    klass: GirClass,
+    namespace: GirNamespace,
+    library: Library,
+    isMatch: (klass: GirClass, glibName: string) => boolean,
+): boolean => {
+    for (const { klass: ancestor } of ancestorChain(library, klass, namespace.name)) {
+        const glibName = getGlibName(ancestor) ?? "";
+
+        if (isMatch(ancestor, glibName)) {
+            return true;
+        }
+    }
+
+    return false;
+};
+
+const hasMatchingAncestorName = (
+    klass: GirClass,
+    namespace: GirNamespace,
+    library: Library,
+    isMatch: (glibName: string) => boolean,
+): boolean => hasMatchingAncestor(klass, namespace, library, (_klass, glibName) => isMatch(glibName));
+
+const hasExposedMethod = (
+    klass: GirClass,
+    namespace: GirNamespace,
+    library: Library,
+    methodName: string,
+): boolean =>
+    hasMatchingAncestor(klass, namespace, library, (current) => current.methods.some((m) => m.name === methodName));
+
+const isIntrinsicElementClass = (klass: GirClass, namespace: GirNamespace, library: Library): boolean =>
+    hasMatchingAncestorName(klass, namespace, library, (glibName) => glibName === "GObject");
+
+const collectIntrinsicElementClasses = (library: Library): GlibNamedClass[] => {
+    const seen: Set<string> = new Set();
+    const entries: GlibNamedClass[] = [];
+
+    for (const candidate of iterateClassesWithGlibName(library)) {
+        const { glibName, klass, namespace } = candidate;
+
+        if (!isIntrinsicElementClass(klass, namespace, library) || seen.has(glibName)) {
+            continue;
+        }
+
+        seen.add(glibName);
+        entries.push(candidate);
+    }
+
+    return sortStringsBy(entries, (entry) => entry.glibName);
+};
+
+export {
+    signalHandlerName,
+    iterateClassesWithGlibName,
+    implementedInterfaces,
+    getGlibName,
+    giNamespaceAlias,
+    hasInterfacePropsBody,
+    newlyImplementedInterfaces,
+    collectInterfacePropsClasses,
+    ancestorGlibNames,
+    hasExposedMethod,
+    isIntrinsicElementClass,
+    collectIntrinsicElementClasses,
+    type GlibNamedClass,
+    type ResolvedQualifiedInterface,
+    type HasContainerProps,
+};