@gtkx/codegen 0.21.0 → 1.0.0-rc.2

package/src/store/jsx/props.ts

@@ -0,0 +1,274 @@
+import { 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 type { GirCallable } from "../../gir/parameter.js";
+import type { TypeId } from "../../gir/type-id.js";
+import { forEachAncestor } from "../../analysis/inheritance.js";
+import { renderHandlerParameters, renderHandlerResultType } from "../../analysis/param-structure.js";
+import { recordTypeTarget, renderBaseType, type TsTypeTarget } from "../../analysis/ts-type.js";
+import { type GirProperty, isConstructableProperty } from "../../gir/property.js";
+import { renderJsDoc } from "../../writer/doc.js";
+import {
+    giNamespaceAlias,
+    hasExposedMethod,
+    isIntrinsicElementClass,
+    signalHandlerName,
+} from "./intrinsic-elements.js";
+
+type IntrinsicElementPropsEntries = {
+    propLines: string[];
+    imports: Map<string, string>;
+    objectPropNames: string[];
+};
+
+type IntrinsicElementScope = {
+    library: Library;
+    klass: GirClass;
+    namespace: GirNamespace;
+};
+
+type IntrinsicElementPropsOptions = IntrinsicElementScope & {
+    isIntrinsicElementAncestor?: (candidate: GirClass) => boolean;
+};
+
+type PropTypeRenderContext = {
+    library: Library;
+    imports: Map<string, string>;
+};
+
+type SignalRenderOptions = {
+    types: PropTypeRenderContext;
+    signal: GirCallable;
+    selfType: string;
+};
+
+type PropEntryCollector = {
+    propLines: string[];
+    imports: Map<string, string>;
+    objectPropNames: string[];
+    acceptProperty: (property: GirProperty) => void;
+    acceptSignal: (signal: GirCallable) => void;
+};
+
+type PropCollectorState = {
+    owner: IntrinsicElementScope;
+    types: PropTypeRenderContext;
+    propLines: string[];
+    objectPropNames: string[];
+    seen: Set<string>;
+};
+
+type InterfacePropsOptions = {
+    library: Library;
+    iface: GirClass;
+    namespace: GirNamespace;
+};
+
+type IntrinsicElementMemberWalk = IntrinsicElementScope & {
+    isIntrinsicElementAncestor: (candidate: GirClass) => boolean;
+    acceptProperty: (property: GirProperty) => void;
+    acceptSignal: (signal: GirCallable) => void;
+};
+
+const appendPropertyLines = (state: PropCollectorState, property: GirProperty, jsName: string): void => {
+    const tsType = renderReactPropType(state.types, property.type, false);
+    const doc = renderJsDoc(property.doc);
+
+    if (isObjectProp(state.owner, property, jsName)) {
+        state.propLines.push(`${doc}${jsName}?: ${tsType} | ReactElement | null | undefined;`);
+        state.objectPropNames.push(jsName);
+
+        return;
+    }
+
+    const isSettable = isConstructableProperty(property);
+
+    if (isSettable) {
+        state.propLines.push(`${doc}${jsName}?: ${tsType} | null | undefined;`);
+    }
+
+    const handlerType = `((value: ${tsType} | null, self: Self) => void) | null | undefined`;
+    state.propLines.push(`${isSettable ? "" : doc}onNotify${upperFirst(jsName)}?: ${handlerType};`);
+};
+
+const acceptCollectorProperty = (state: PropCollectorState, property: GirProperty): void => {
+    if (!property.introspectable) {
+        return;
+    }
+
+    const jsName = toCamelIdentifier(property.name);
+
+    if (state.seen.has(jsName)) {
+        return;
+    }
+
+    state.seen.add(jsName);
+    appendPropertyLines(state, property, jsName);
+};
+
+const acceptCollectorSignal = (state: PropCollectorState, signal: GirCallable): void => {
+    const handlerName = signalHandlerName(signal.name);
+
+    if (state.seen.has(handlerName)) {
+        return;
+    }
+
+    state.seen.add(handlerName);
+    const signature = renderSignalHandler({ types: state.types, signal, selfType: "Self" });
+    state.propLines.push(`${renderJsDoc(signal.doc)}${handlerName}?: (${signature}) | undefined;`);
+};
+
+const createPropEntryCollector = (owner: IntrinsicElementScope): PropEntryCollector => {
+    const { library } = owner;
+    const imports: Map<string, string> = new Map();
+    const types: PropTypeRenderContext = { library, imports };
+
+    const state: PropCollectorState = {
+        owner,
+        types,
+        propLines: [],
+        objectPropNames: [],
+        seen: new Set<string>(),
+    };
+
+    return {
+        propLines: state.propLines,
+        imports,
+        objectPropNames: state.objectPropNames,
+        acceptProperty: (property) => {
+            acceptCollectorProperty(state, property);
+        },
+        acceptSignal: (signal) => {
+            acceptCollectorSignal(state, signal);
+        },
+    };
+};
+
+const buildElementPropsEntries = (options: IntrinsicElementPropsOptions): IntrinsicElementPropsEntries => {
+    const { library, klass, namespace, isIntrinsicElementAncestor = () => false } = options;
+    const collector = createPropEntryCollector({ library, klass, namespace });
+
+    walkIntrinsicElementMembers({
+        library,
+        klass,
+        namespace,
+        isIntrinsicElementAncestor,
+        acceptProperty: collector.acceptProperty,
+        acceptSignal: collector.acceptSignal,
+    });
+
+    return { propLines: collector.propLines, imports: collector.imports, objectPropNames: collector.objectPropNames };
+};
+
+const buildInterfacePropsEntries = (options: InterfacePropsOptions): IntrinsicElementPropsEntries => {
+    const { library, iface, namespace } = options;
+    const collector = createPropEntryCollector({ library, klass: iface, namespace });
+
+    for (const property of iface.properties) {
+        collector.acceptProperty(property);
+    }
+
+    for (const signal of iface.signals) {
+        collector.acceptSignal(signal);
+    }
+
+    return { propLines: collector.propLines, imports: collector.imports, objectPropNames: collector.objectPropNames };
+};
+
+const walkIntrinsicElementMembers = (walk: IntrinsicElementMemberWalk): void => {
+    const { library, klass, namespace, isIntrinsicElementAncestor, acceptProperty, acceptSignal } = walk;
+
+    const visitMembers = (memberClass: GirClass): void => {
+        for (const property of memberClass.properties) {
+            acceptProperty(property);
+        }
+
+        for (const signal of memberClass.signals) {
+            acceptSignal(signal);
+        }
+    };
+
+    const ancestry = { library, namespace };
+    visitMembers(klass);
+
+    forEachAncestor(ancestry, klass, (ancestor) => {
+        visitMembers(ancestor.klass);
+    }, isIntrinsicElementAncestor);
+};
+
+const isGObjectType = (library: Library, ref: TypeId | undefined): boolean => {
+    if (ref === undefined) {
+        return false;
+    }
+
+    const resolved = library.typeFor(ref);
+
+    if (resolved?.kind === "interface") {
+        return true;
+    }
+
+    if (resolved?.kind !== "class") {
+        return false;
+    }
+
+    return isIntrinsicElementClass(resolved.value, resolved.namespace, library);
+};
+
+const isObjectProp = (owner: IntrinsicElementScope, property: GirProperty, jsName: string): boolean => {
+    if (!property.writable || property.constructOnly) {
+        return false;
+    }
+
+    if (!isGObjectType(owner.library, property.type)) {
+        return false;
+    }
+
+    if (jsName === "child" && hasExposedMethod(owner.klass, owner.namespace, owner.library, "set_child")) {
+        return false;
+    }
+
+    return true;
+};
+
+const renderSignalHandler = (options: SignalRenderOptions): string => {
+    const { types, signal, selfType } = options;
+
+    const params = [
+        ...renderHandlerParameters(signal.parameters, (ref, nullable) => renderReactPropType(types, ref, nullable)),
+        `self: ${selfType}`,
+    ];
+
+    const result = renderHandlerResultType({
+        library: types.library,
+        signal,
+        renderType: (ref, nullable) => renderReactPropType(types, ref, nullable),
+        includeCallerAllocated: false,
+        optOut: true,
+    });
+
+    return `(${params.join(", ")}) => ${result}`;
+};
+
+const reactTarget = (context: PropTypeRenderContext): TsTypeTarget =>
+    recordTypeTarget(
+        context.library,
+        (name) => {
+            context.imports.set(name.namespaceName, giNamespaceAlias(name.namespaceName));
+
+            return `${giNamespaceAlias(name.namespaceName)}.${name.typeName}`;
+        },
+        () => {
+            context.imports.set("GObject", giNamespaceAlias("GObject"));
+
+            return `${giNamespaceAlias("GObject")}.Type`;
+        },
+    );
+
+const renderReactPropType = (context: PropTypeRenderContext, ref: TypeId | undefined, isNullable: boolean): string => {
+    const base = renderBaseType(context.library, reactTarget(context), ref);
+
+    return isNullable ? `${base} | null` : base;
+};
+
+export { buildElementPropsEntries, buildInterfacePropsEntries, isObjectProp, reactTarget };

package/src/store/jsx-store.ts

@@ -0,0 +1,39 @@
+import type { JsxNamespaceFile } from "./jsx/pipeline.js";
+import type { RawFile } from "./store-fs.js";
+import { buildManifest, type StoreOptions, subpathExport, writeStore } from "./store-fs.js";
+
+type JsxStoreOptions = StoreOptions;
+
+const writeJsxStore = (
+    options: JsxStoreOptions,
+    namespaces: JsxNamespaceFile[],
+    metadata: string,
+    fingerprint: RawFile,
+): void => {
+    const exportsMap: Record<string, unknown> = {
+        "./metadata": subpathExport("metadata"),
+    };
+
+    const files = [{ fileName: "metadata.ts", source: metadata }];
+
+    for (const { directory, source } of namespaces) {
+        files.push({ fileName: `${directory}/${directory}.tsx`, source });
+        exportsMap[`./${directory}`] = subpathExport(`${directory}/${directory}`);
+    }
+
+    writeStore({
+        storeDir: options.storeDir,
+        linkDir: options.linkDir,
+        files,
+        manifest: buildManifest({
+            name: "@gtkx/jsx",
+            version: options.version,
+            exports: exportsMap,
+            peerDependencies: { "@gtkx/gi": "*", "@gtkx/react": "*", react: "*" },
+        }),
+        rawFiles: [fingerprint],
+        configEnv: true,
+    });
+};
+
+export { writeJsxStore, type JsxStoreOptions };

package/src/store/store-fs.ts

@@ -0,0 +1,128 @@
+import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { compileStore } from "./compile-store.js";
+
+type StoreOptions = {
+    storeDir: string;
+    linkDir: string;
+    version: string;
+};
+
+type StoreFile = {
+    fileName: string;
+    source: string;
+};
+
+type Manifest = {
+    name: string;
+    type: "module";
+    version: string;
+    sideEffects: true;
+    exports: Record<string, unknown>;
+    peerDependencies?: Record<string, string>;
+};
+
+type ManifestInput = {
+    name: string;
+    version: string;
+    exports: Record<string, unknown>;
+    peerDependencies?: Record<string, string>;
+};
+
+type RawFile = { relativePath: string; content: string };
+
+type WriteStoreParams = {
+    storeDir: string;
+    linkDir: string;
+    files: StoreFile[];
+    manifest: Manifest;
+    rawFiles?: RawFile[];
+    configEnv?: boolean;
+};
+
+const subpathExport = (stem: string): { types: string; default: string } => ({
+    types: `./${stem}.d.ts`,
+    default: `./${stem}.js`,
+});
+
+const buildManifest = (input: ManifestInput): Manifest => {
+    const manifest: Manifest = {
+        name: input.name,
+        type: "module",
+        version: input.version,
+        sideEffects: true,
+        exports: { "./package.json": "./package.json", ...input.exports },
+    };
+
+    if (input.peerDependencies) {
+        manifest.peerDependencies = input.peerDependencies;
+    }
+
+    return manifest;
+};
+
+const writeStore = (params: WriteStoreParams): void => {
+    const tmp = createTempStore(params.storeDir);
+
+    try {
+        for (const file of params.files) {
+            writeSourceFile(tmp, file.fileName, file.source);
+        }
+
+        compileStore({
+            storeDir: tmp,
+            files: params.files,
+            packageName: params.manifest.name,
+            ...(params.configEnv !== undefined && { configEnv: params.configEnv }),
+        });
+
+        writePackageJson(tmp, params.manifest);
+        const rawFiles = params.rawFiles ?? [];
+
+        for (const raw of rawFiles) {
+            writeFileSync(join(tmp, raw.relativePath), raw.content);
+        }
+
+        symlinkRelative(join(tmp, "node_modules", ...params.manifest.name.split("/")), tmp);
+        swapStore(tmp, params.storeDir, params.linkDir);
+    } finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+};
+
+const writeSourceFile = (storeDir: string, fileName: string, source: string): void => {
+    const filePath = join(storeDir, fileName);
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, source);
+};
+
+const symlinkRelative = (linkPath: string, realTarget: string): void => {
+    mkdirSync(dirname(linkPath), { recursive: true });
+    rmSync(linkPath, { recursive: true, force: true });
+    symlinkSync(relative(dirname(linkPath), realTarget), linkPath, "dir");
+};
+
+const writePackageJson = (storeDir: string, manifest: Manifest): void => {
+    writeFileSync(join(storeDir, "package.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+};
+
+const swapStore = (tmp: string, storeDir: string, visibleLink: string): void => {
+    const previous = `${storeDir}.old`;
+    rmSync(previous, { recursive: true, force: true });
+
+    if (existsSync(storeDir)) {
+        renameSync(storeDir, previous);
+    }
+
+    renameSync(tmp, storeDir);
+    rmSync(previous, { recursive: true, force: true });
+    symlinkRelative(visibleLink, storeDir);
+};
+
+const createTempStore = (storeDir: string): string => {
+    mkdirSync(dirname(storeDir), { recursive: true });
+
+    return mkdtempSync(`${storeDir}.tmp-`);
+};
+
+export { subpathExport, buildManifest, writeStore, type StoreOptions, type RawFile };

package/src/writer/context.ts

@@ -0,0 +1,67 @@
+import type { Library } from "../gir/library.js";
+import type { GirNamespace } from "../gir/namespace.js";
+import { ModuleBuilder } from "./module.js";
+
+class ModuleContext {
+    public module: ModuleBuilder = new ModuleBuilder();
+    public namespace: GirNamespace;
+    public library: Library;
+
+    constructor(namespace: GirNamespace, library: Library) {
+        this.namespace = namespace;
+        this.library = library;
+    }
+
+    addRuntimeImport(name: string): void {
+        this.module.imports.addNamed("@gtkx/runtime", name);
+    }
+
+    addRuntimeTypeImport(name: string): void {
+        this.module.imports.addNamed("@gtkx/runtime", name, true);
+    }
+
+    hoistDescriptor(expression: string): string {
+        return this.module.hoistDescriptor(expression);
+    }
+
+    addGObjectBootstrapImports(): void {
+        if (this.namespace.name === "GObject") {
+            return;
+        }
+
+        if (this.namespace.name === "GLib") {
+            return;
+        }
+
+        this.module.imports.addSideEffect("../gobject/overrides/object.js");
+        this.module.imports.addSideEffect("../gobject/overrides/value.js");
+    }
+
+    addCrossNamespaceImport(namespaceName: string): string {
+        if (namespaceName === this.namespace.name) {
+            return namespaceName;
+        }
+
+        const directory = namespaceName.toLowerCase();
+        const isFoundational = directory === "gobject" || directory === "glib";
+        const path = isFoundational ? `../${directory}/${directory}.js` : `../${directory}/index.js`;
+
+        if (!isFoundational) {
+            this.module.imports.addSideEffect(path);
+        }
+
+        this.module.imports.addNamespace(path, namespaceName);
+
+        return namespaceName;
+    }
+
+    qualify(namespaceName: string, typeName: string): string {
+        if (namespaceName === this.namespace.name) {
+            return typeName;
+        }
+
+        return `${this.addCrossNamespaceImport(namespaceName)}.${typeName}`;
+    }
+}
+
+export { ModuleContext };

package/src/writer/doc.ts

@@ -0,0 +1,25 @@
+import { gtkDocToMarkdown } from "./gtk-doc.js";
+
+const escapeCommentTerminators = (doc: string): string => doc.replaceAll("*/", String.raw`*\/`);
+
+const renderJsDocLines = (lines: string[]): string => {
+    const [single, ...rest] = lines;
+
+    if (single !== undefined && rest.length === 0) {
+        return `/** ${single} */\n`;
+    }
+
+    const body = lines.map((line) => (line.length === 0 ? " *" : ` * ${line}`)).join("\n");
+
+    return `/**\n${body}\n */\n`;
+};
+
+const renderJsDoc = (doc: string | undefined): string => {
+    if (doc === undefined || doc.length === 0) {
+        return "";
+    }
+
+    return renderJsDocLines(escapeCommentTerminators(gtkDocToMarkdown(doc)).split("\n"));
+};
+
+export { renderJsDoc };

package/src/writer/emit.ts

@@ -0,0 +1,35 @@
+const indent = (block: string, level: number): string => {
+    if (level <= 0) {
+        return block;
+    }
+
+    const prefix = " ".repeat(4).repeat(level);
+
+    return block
+        .split("\n")
+        .map((line) => (line.length === 0 ? line : `${prefix}${line}`))
+        .join("\n");
+};
+
+const renderBlock = (head: string, body: string): string => `${head} {\n${indent(body, 1)}\n}`;
+const renderBraced = (body: string): string => `{\n${indent(body, 1)}\n}`;
+
+const renderBracedOrEmpty = (head: string, body: string): string =>
+    body.length === 0 ? `${head} {}` : renderBlock(head, body);
+
+const indentMembers = (members: string[]): string => members.map((member) => indent(member, 1)).join("\n\n");
+
+const joinArgs = (parts: (string | undefined)[]): string =>
+    parts.filter((part): part is string => part !== undefined).join(", ");
+
+const arrayLiteral = (elements: string[]): string => {
+    if (elements.length === 0) {
+        return "[]";
+    }
+
+    const lines = elements.map((element) => `    ${element},`);
+
+    return `[\n${lines.join("\n")}\n]`;
+};
+
+export { indent, renderBlock, renderBraced, renderBracedOrEmpty, indentMembers, joinArgs, arrayLiteral };

package/src/writer/gtk-doc.ts

@@ -0,0 +1,101 @@
+import { camelCase } from "@gtkx/utils";
+
+const CONSTANT_MAP: Record<string, string> = { TRUE: "true", FALSE: "false", NULL: "null" };
+const CALLABLE_LINK_KINDS: Set<string> = new Set(["method", "func", "ctor", "vfunc"]);
+const SENTINEL = String.fromCodePoint(0xE0_00);
+const CODE_BLOCK_OPEN = "|[";
+const CODE_BLOCK_CLOSE = "]|";
+const CODE_LANGUAGE_PATTERN = /^\s*<!--\s*language="([^"]*)"\s*-->/;
+const FENCED_BLOCK_PATTERN = /```[\s\S]*?```/g;
+const INLINE_CODE_PATTERN = /`[^`\n]*`/g;
+const LINK_PATTERN = /\[(\w+)@([\w.:%#-]+)\]/g;
+const CONSTANT_PATTERN = /(?<!\w)%(\w+)/g;
+const TYPE_REF_PATTERN = /(?<!\w)#(\w+)/g;
+const PARAM_REF_PATTERN = /(?<!\w)@(\w+)/g;
+const FUNCTION_REF_PATTERN = /\b([a-z_][a-z0-9_]*)\(\)/g;
+
+const renderLink = (kind: string, target: string): string => {
+    const segments = target.split(/::|[.:]/);
+    const lastIndex = segments.length - 1;
+
+    if (kind === "property" || CALLABLE_LINK_KINDS.has(kind)) {
+        segments[lastIndex] = camelCase(segments[lastIndex] ?? "");
+    }
+
+    const symbol = segments.join(".");
+
+    return `\`${symbol}${CALLABLE_LINK_KINDS.has(kind) ? "()" : ""}\``;
+};
+
+const trimTrailingNewlines = (value: string): string => {
+    let end = value.length;
+
+    while (end > 0 && value[end - 1] === "\n") {
+        end -= 1;
+    }
+
+    return value.slice(0, end);
+};
+
+const renderCodeFence = (body: string): string => {
+    const languageMatch = CODE_LANGUAGE_PATTERN.exec(body);
+    const fence = (languageMatch?.[1] ?? "").trim().toLowerCase();
+    const rest = languageMatch === null ? body : body.slice(languageMatch[0].length);
+    const code = trimTrailingNewlines(rest.trimStart());
+
+    return `\`\`\`${fence}\n${code}\n\`\`\``;
+};
+
+const protectCodeBlocks = (raw: string, protect: (value: string) => string): string => {
+    let result = "";
+    let cursor = 0;
+
+    while (cursor < raw.length) {
+        const open = raw.indexOf(CODE_BLOCK_OPEN, cursor);
+
+        if (open === -1) {
+            break;
+        }
+
+        const close = raw.indexOf(CODE_BLOCK_CLOSE, open + CODE_BLOCK_OPEN.length);
+
+        if (close === -1) {
+            break;
+        }
+
+        result += raw.slice(cursor, open);
+        result += protect(renderCodeFence(raw.slice(open + CODE_BLOCK_OPEN.length, close)));
+        cursor = close + CODE_BLOCK_CLOSE.length;
+    }
+
+    return result + raw.slice(cursor);
+};
+
+const gtkDocToMarkdown = (raw: string): string => {
+    const stash: string[] = [];
+
+    const protect = (value: string): string => {
+        const token = `${SENTINEL}${String(stash.length)}${SENTINEL}`;
+        stash.push(value);
+
+        return token;
+    };
+
+    let text = protectCodeBlocks(raw, protect);
+    text = text.replaceAll(FENCED_BLOCK_PATTERN, (block) => protect(block));
+    text = text.replaceAll(INLINE_CODE_PATTERN, (span) => protect(span));
+    text = text.replaceAll(LINK_PATTERN, (_match, kind: string, target: string) => protect(renderLink(kind, target)));
+    text = text.replaceAll(CONSTANT_PATTERN, (_match, name: string) => protect(`\`${CONSTANT_MAP[name] ?? name}\``));
+    text = text.replaceAll(TYPE_REF_PATTERN, (_match, name: string) => protect(`\`${name}\``));
+    text = text.replaceAll(PARAM_REF_PATTERN, (_match, name: string) => protect(`\`${name}\``));
+    text = text.replaceAll(FUNCTION_REF_PATTERN, (_match, name: string) => protect(`\`${name}()\``));
+
+    for (let index = stash.length - 1; index >= 0; index -= 1) {
+        const value = stash[index] ?? "";
+        text = text.replaceAll(`${SENTINEL}${String(index)}${SENTINEL}`, () => value);
+    }
+
+    return text;
+};
+
+export { gtkDocToMarkdown };