@gtkx/cli 0.21.0 → 1.0.0-rc.1

package/src/settings/parser.ts

@@ -0,0 +1,154 @@
+import { XMLParser } from "fast-xml-parser";
+
+export type ParsedKey = {
+    name: string;
+    variantType: string | null;
+    enumId: string | null;
+    flagsId: string | null;
+    choices: string[];
+    summary: string | null;
+};
+
+export type ParsedSchema = {
+    id: string;
+    path: string | null;
+    keys: ParsedKey[];
+};
+
+export type ParsedSchemaFile = {
+    fileName: string;
+    schemas: ParsedSchema[];
+    enums: Map<string, string[]>;
+    flags: Map<string, string[]>;
+};
+
+export class SchemaParseError extends Error {}
+
+type RawNode = Record<string, unknown>;
+
+const MULTI_TAGS: Set<string> = new Set(["schema", "key", "enum", "flags", "value", "choice"]);
+
+const PARSER = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+    parseAttributeValue: false,
+    parseTagValue: false,
+    trimValues: true,
+    isArray: (name) => MULTI_TAGS.has(name),
+});
+
+const isRawNode = (value: unknown): value is RawNode => typeof value === "object" && value !== null;
+
+const attr = (node: RawNode, name: string): string | null => {
+    const value = node[`@_${name}`];
+    return typeof value === "string" ? value : null;
+};
+
+const text = (node: RawNode, name: string): string | null => {
+    const value = node[name];
+    return typeof value === "string" && value.length > 0 ? value : null;
+};
+
+const children = (node: RawNode, name: string): RawNode[] => {
+    const value = node[name];
+    if (!Array.isArray(value)) return [];
+    return value.filter(isRawNode);
+};
+
+const parseNicks = (definition: RawNode): string[] =>
+    children(definition, "value")
+        .map((value) => attr(value, "nick"))
+        .filter((nick): nick is string => nick !== null);
+
+const parseDefinitions = (schemalist: RawNode, tag: string): Map<string, string[]> => {
+    const definitions = new Map<string, string[]>();
+    for (const definition of children(schemalist, tag)) {
+        const id = attr(definition, "id");
+        if (id !== null) definitions.set(id, parseNicks(definition));
+    }
+    return definitions;
+};
+
+const parseChoices = (key: RawNode): string[] => {
+    const choices = key.choices;
+    if (!isRawNode(choices)) return [];
+    return children(choices, "choice")
+        .map((choice) => attr(choice, "value"))
+        .filter((value): value is string => value !== null);
+};
+
+const parseKey = (key: RawNode, fileName: string): ParsedKey => {
+    const name = attr(key, "name");
+    if (name === null) {
+        throw new SchemaParseError(`A <key> in ${fileName} has no name attribute`);
+    }
+    return {
+        name,
+        variantType: attr(key, "type"),
+        enumId: attr(key, "enum"),
+        flagsId: attr(key, "flags"),
+        choices: parseChoices(key),
+        summary: text(key, "summary"),
+    };
+};
+
+type RawSchema = {
+    id: string;
+    path: string | null;
+    extendsId: string | null;
+    keys: ParsedKey[];
+};
+
+const parseRawSchema = (schema: RawNode, fileName: string): RawSchema => {
+    const id = attr(schema, "id");
+    if (id === null) {
+        throw new SchemaParseError(`A <schema> in ${fileName} has no id attribute`);
+    }
+    return {
+        id,
+        path: attr(schema, "path"),
+        extendsId: attr(schema, "extends"),
+        keys: children(schema, "key").map((key) => parseKey(key, fileName)),
+    };
+};
+
+const mergeInheritedKeys = (schema: RawSchema, byId: Map<string, RawSchema>): ParsedKey[] => {
+    const merged = new Map<string, ParsedKey>();
+    const visited = new Set<string>();
+    const collect = (current: RawSchema): void => {
+        if (visited.has(current.id)) return;
+        visited.add(current.id);
+        if (current.extendsId !== null) {
+            const parent = byId.get(current.extendsId);
+            if (parent !== undefined) collect(parent);
+        }
+        for (const key of current.keys) merged.set(key.name, key);
+    };
+    collect(schema);
+    return [...merged.values()];
+};
+
+export const parseSchemaXml = (xml: string, fileName: string): ParsedSchemaFile => {
+    let document: unknown;
+    try {
+        document = PARSER.parse(xml);
+    } catch (error) {
+        throw new SchemaParseError(`Failed to parse ${fileName} as XML: ${String(error)}`, { cause: error });
+    }
+    if (!isRawNode(document) || !("schemalist" in document)) {
+        throw new SchemaParseError(`${fileName} has no <schemalist> root element`);
+    }
+    const schemalist = isRawNode(document.schemalist) ? document.schemalist : {};
+    const rawSchemas = children(schemalist, "schema").map((schema) => parseRawSchema(schema, fileName));
+    const byId = new Map(rawSchemas.map((schema) => [schema.id, schema]));
+    return {
+        fileName,
+        schemas: rawSchemas.map((schema) => ({
+            id: schema.id,
+            path: schema.path,
+            keys: mergeInheritedKeys(schema, byId),
+        })),
+        enums: parseDefinitions(schemalist, "enum"),
+        flags: parseDefinitions(schemalist, "flags"),
+    };
+};

package/src/settings/render.ts

@@ -0,0 +1,167 @@
+import { upperFirst } from "@gtkx/utils";
+import type { ParsedKey, ParsedSchema, ParsedSchemaFile } from "./parser.js";
+
+const GTKX_ENV_MODULE_HEADER = `/**
+ * GSettings schema modules generated by GTKX from the project's
+ * \`.gschema.xml\` files. Regenerated by \`gtkx codegen\`, \`gtkx dev\`, and
+ * \`gtkx build\`; do not edit.
+ */`;
+
+const VARIANT_TS_TYPES: Record<string, string> = {
+    b: "boolean",
+    i: "number",
+    u: "number",
+    x: "number",
+    t: "number",
+    d: "number",
+    s: "string",
+    as: "string[]",
+};
+
+const VARIANT_FALLBACK_TS_TYPE = `import("@gtkx/gi/glib").Variant`;
+
+const ENUM_KIND = "enum";
+const FLAGS_KIND = "flags";
+
+const toJsStringLiteral = (value: string): string =>
+    JSON.stringify(value).replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029");
+
+const exportNameFor = (schemaId: string): string => schemaId.replaceAll(".", "_");
+
+const unionOf = (values: string[]): string => values.map(toJsStringLiteral).join(" | ");
+
+const tsTypeForKey = (key: ParsedKey, file: ParsedSchemaFile): string => {
+    if (key.enumId !== null) {
+        const nicks = file.enums.get(key.enumId);
+        return nicks !== undefined && nicks.length > 0 ? unionOf(nicks) : "string";
+    }
+    if (key.flagsId !== null) {
+        const nicks = file.flags.get(key.flagsId);
+        return nicks !== undefined && nicks.length > 0 ? `(${unionOf(nicks)})[]` : "string[]";
+    }
+    if (key.variantType === "s" && key.choices.length > 0) {
+        return unionOf(key.choices);
+    }
+    return VARIANT_TS_TYPES[key.variantType ?? ""] ?? VARIANT_FALLBACK_TS_TYPE;
+};
+
+const runtimeKindForKey = (key: ParsedKey): string => {
+    if (key.enumId !== null) return ENUM_KIND;
+    if (key.flagsId !== null) return FLAGS_KIND;
+    return key.variantType ?? "";
+};
+
+const runtimeKeysFor = (schema: ParsedSchema): string => {
+    const entries = schema.keys.map(
+        (key) => `${toJsStringLiteral(key.name)}: ${toJsStringLiteral(runtimeKindForKey(key))}`,
+    );
+    return `{ ${entries.join(", ")} }`;
+};
+
+export const renderRuntimeModule = (file: ParsedSchemaFile): string => {
+    const lines: string[] = [];
+    file.schemas.forEach((schema, index) => {
+        const keysName = `keys_${index}`;
+        const id = toJsStringLiteral(schema.id);
+        lines.push(`const ${keysName} = ${runtimeKeysFor(schema)};`);
+        if (schema.path === null) {
+            lines.push(
+                `export const ${exportNameFor(schema.id)} = { id: ${id}, keys: ${keysName}, at: (path) => ({ id: ${id}, path, keys: ${keysName} }) };`,
+            );
+        } else {
+            lines.push(`export const ${exportNameFor(schema.id)} = { id: ${id}, path: null, keys: ${keysName} };`);
+        }
+    });
+    const first = file.schemas[0];
+    if (first !== undefined) {
+        lines.push(`export default ${exportNameFor(first.id)};`);
+    }
+    return lines.join("\n");
+};
+
+const sanitizeSummary = (summary: string): string => summary.replaceAll("*/", "*\\/");
+
+const interfaceNameFor = (schemaId: string, usedNames: Set<string>): string => {
+    const base = `${schemaId
+        .split(/[^a-zA-Z0-9]+/)
+        .filter((part) => part.length > 0)
+        .map(upperFirst)
+        .join("")}Keys`;
+    let name = base;
+    let suffix = 2;
+    while (usedNames.has(name)) {
+        name = `${base}${suffix}`;
+        suffix += 1;
+    }
+    usedNames.add(name);
+    return name;
+};
+
+const renderKeysType = (name: string, schema: ParsedSchema, file: ParsedSchemaFile): string[] => {
+    const lines = [`    type ${name} = {`];
+    for (const key of schema.keys) {
+        if (key.summary !== null) {
+            lines.push(`        /** ${sanitizeSummary(key.summary)} */`);
+        }
+        lines.push(`        ${toJsStringLiteral(key.name)}: ${tsTypeForKey(key, file)};`);
+    }
+    lines.push("    };");
+    return lines;
+};
+
+const boundRefTypeLines = (interfaceName: string, indent: string): string[] => [
+    `${indent}id: string;`,
+    `${indent}path: string | null;`,
+    `${indent}keys: { [P in keyof ${interfaceName}]: string };`,
+    `${indent}__keys__?: ${interfaceName};`,
+];
+
+const renderSchemaConst = (schema: ParsedSchema, interfaceName: string): string[] => {
+    const exportName = exportNameFor(schema.id);
+    if (schema.path !== null) {
+        return [
+            `    const ${exportName}: {`,
+            `        id: ${toJsStringLiteral(schema.id)};`,
+            ...boundRefTypeLines(interfaceName, "        ").slice(1),
+            "    };",
+        ];
+    }
+    return [
+        `    const ${exportName}: {`,
+        `        id: ${JSON.stringify(schema.id)};`,
+        `        keys: { [P in keyof ${interfaceName}]: string };`,
+        `        __keys__?: ${interfaceName};`,
+        "        at(path: string): {",
+        ...boundRefTypeLines(interfaceName, "            "),
+        "        };",
+        "    };",
+    ];
+};
+
+const renderFileModule = (file: ParsedSchemaFile, usedNames: Set<string>): string[] => {
+    const lines = [`declare module "${file.fileName}" {`];
+    const exportNames: string[] = [];
+    file.schemas.forEach((schema, index) => {
+        if (index > 0) lines.push("");
+        const interfaceName = interfaceNameFor(schema.id, usedNames);
+        lines.push(...renderKeysType(interfaceName, schema, file));
+        lines.push("");
+        lines.push(...renderSchemaConst(schema, interfaceName));
+        exportNames.push(exportNameFor(schema.id));
+    });
+    if (exportNames.length > 0) {
+        lines.push("");
+        lines.push(`    export { ${exportNames.join(", ")} };`);
+        lines.push(`    export default ${exportNames[0]};`);
+    }
+    lines.push("}");
+    return lines;
+};
+
+export const renderEnvModule = (files: ParsedSchemaFile[]): string => {
+    const usedNames = new Set<string>();
+    const blocks = files
+        .filter((file) => file.schemas.length > 0)
+        .map((file) => renderFileModule(file, usedNames).join("\n"));
+    return `${[GTKX_ENV_MODULE_HEADER, ...blocks].join("\n\n")}\n`;
+};

package/src/settings/schema.ts

@@ -0,0 +1,115 @@
+import { createHash } from "node:crypto";
+import { copyFileSync, type Dirent, mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative } from "node:path";
+import { sortStrings, warn } from "@gtkx/utils";
+import { DATA_IMPORT_PREFIX } from "../internal/data-dir.js";
+import { removeTempDir } from "../internal/staging-dir.js";
+import { compileSchemas } from "./compile.js";
+import { type ParsedSchemaFile, parseSchemaXml, SchemaParseError } from "./parser.js";
+import { renderEnvModule } from "./render.js";
+
+export const SCHEMA_SUFFIX = ".gschema.xml";
+
+export const prependSchemaDir = (dir: string, existing: string | undefined): string => {
+    if (existing === undefined || existing.length === 0) return dir;
+    if (existing.split(":").includes(dir)) return existing;
+    return `${dir}:${existing}`;
+};
+
+const STAGED_NAME_LENGTH = 16;
+
+const stagedSchemaName = (filePath: string): string =>
+    `${createHash("sha1").update(filePath).digest("hex").slice(0, STAGED_NAME_LENGTH)}${SCHEMA_SUFFIX}`;
+
+export const stageSchema = (dir: string, filePath: string): void => {
+    copyFileSync(filePath, join(dir, stagedSchemaName(filePath)));
+};
+
+const toForwardSlashes = (value: string): string => value.replaceAll(/[/\\]/g, "/");
+
+const moduleSpecifierFor = (dataDirAbs: string, filePath: string): string =>
+    `${DATA_IMPORT_PREFIX}/${toForwardSlashes(relative(dataDirAbs, filePath))}`;
+
+type SchemaEnvResult = {
+    path: string;
+    written: boolean;
+};
+
+const readVisibleEntries = (dir: string): Dirent[] => {
+    try {
+        return readdirSync(dir, { withFileTypes: true }).filter((entry) => !entry.name.startsWith("."));
+    } catch {
+        return [];
+    }
+};
+
+const isSchemaFile = (entry: Dirent): boolean => entry.isFile() && entry.name.endsWith(SCHEMA_SUFFIX);
+
+export const findSchemaFiles = (dataDir: string): string[] => {
+    const found: string[] = [];
+    const walk = (dir: string): void => {
+        for (const entry of readVisibleEntries(dir)) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            } else if (isSchemaFile(entry)) {
+                found.push(full);
+            }
+        }
+    };
+    walk(dataDir);
+    return sortStrings(found);
+};
+
+export const stageAndCompileProjectSchemas = (root: string, dataDir: string | null): string | null => {
+    if (dataDir === null) return null;
+    const schemaFiles = findSchemaFiles(join(root, dataDir));
+    if (schemaFiles.length === 0) return null;
+
+    const dir = mkdtempSync(join(tmpdir(), "gtkx-schemas-"));
+    for (const filePath of schemaFiles) stageSchema(dir, filePath);
+    compileSchemas(dir);
+    process.once("exit", () => removeTempDir(dir));
+
+    return dir;
+};
+
+export const schemaEnvPath = (rootDir: string): string => join(rootDir, "node_modules", ".gtkx", "env.d.ts");
+
+const parseProjectSchemas = (schemaFiles: string[], dataDirAbs: string): ParsedSchemaFile[] => {
+    const parsed: ParsedSchemaFile[] = [];
+    for (const filePath of schemaFiles) {
+        const specifier = moduleSpecifierFor(dataDirAbs, filePath);
+        try {
+            parsed.push(parseSchemaXml(readFileSync(filePath, "utf-8"), specifier));
+        } catch (error) {
+            if (!(error instanceof SchemaParseError)) throw error;
+            warn(`Skipping ${filePath} in schema type generation: ${error.message}`);
+        }
+    }
+    return parsed;
+};
+
+const writeIfChanged = (path: string, content: string): boolean => {
+    let existing: string | null = null;
+    try {
+        existing = readFileSync(path, "utf-8");
+    } catch {
+        existing = null;
+    }
+    if (existing === content) return false;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+    return true;
+};
+
+export const emitSchemaEnv = (rootDir: string, dataDir: string | null): SchemaEnvResult => {
+    const dataDirAbs = dataDir === null ? null : join(rootDir, dataDir);
+    const schemaFiles = dataDirAbs === null ? [] : findSchemaFiles(dataDirAbs);
+    const parsed = dataDirAbs === null ? [] : parseProjectSchemas(schemaFiles, dataDirAbs);
+    const content = renderEnvModule(parsed);
+    const path = schemaEnvPath(rootDir);
+    const written = writeIfChanged(path, content);
+    return { path, written };
+};

package/src/vite-plugins/asset-extensions.ts

@@ -0,0 +1,28 @@
+export const ASSET_EXTENSIONS = [
+    "png",
+    "jpg",
+    "jpeg",
+    "gif",
+    "svg",
+    "webp",
+    "webm",
+    "mp4",
+    "ogg",
+    "mp3",
+    "wav",
+    "flac",
+    "aac",
+    "woff",
+    "woff2",
+    "eot",
+    "ttf",
+    "otf",
+    "ico",
+    "avif",
+    "data",
+    "gpa",
+];
+
+export const ASSET_RE = new RegExp(String.raw`\.(?:${ASSET_EXTENSIONS.join("|")})$`, "i");
+
+export const ASSET_PATH_RE = new RegExp(String.raw`\.(?:${ASSET_EXTENSIONS.join("|")})(?:\?.*)?$`, "i");

package/src/{vite-plugin-gtkx-built-url.ts → vite-plugins/built-url.ts}

@@ -1,23 +1,9 @@
 import type { Plugin } from "vite";
 
-/**
- * Vite plugin that configures `renderBuiltUrl` for resolving asset imports
- * to filesystem paths at runtime.
- *
- * When `assetBase` is provided, assets resolve relative to the executable
- * directory using `path.join(path.dirname(process.execPath), assetBase, filename)`.
- * This supports FHS-compliant layouts where assets live in `../share/<app>/`.
- *
- * When `assetBase` is omitted, assets resolve relative to the bundle file
- * via `import.meta.url`, which works when assets are co-located with the
- * executable.
- *
- * Only applies when the user has not already configured
- * `experimental.renderBuiltUrl` in their Vite config.
- */
 export function gtkxBuiltUrl(assetBase?: string): Plugin {
     return {
         name: "gtkx:built-url",
+        apply: "build",
 
         config(userConfig) {
             if (userConfig.experimental?.renderBuiltUrl) {
@@ -37,8 +23,9 @@ export function gtkxBuiltUrl(assetBase?: string): Plugin {
                             };
                         }
 
+                        const filenameLiteral = JSON.stringify(`./${filename}`);
                         return {
-                            runtime: `new URL(${JSON.stringify(`./${filename}`)}, import.meta.url).pathname`,
+                            runtime: `new URL(${filenameLiteral}, import.meta.url).pathname`,
                         };
                     },
                 },

package/src/vite-plugins/css.ts

@@ -0,0 +1,38 @@
+import { readFileSync } from "node:fs";
+import type { Plugin } from "vite";
+import { createVirtualNamespace } from "./virtual-module.js";
+
+const CSS_RE = /\.css$/i;
+const INJECT_SUFFIX = "?inject";
+const VIRTUAL_PREFIX = "\0gtkx-css:";
+const { isVirtual, fromVirtualId, resolveToVirtual } = createVirtualNamespace(VIRTUAL_PREFIX);
+
+export function gtkxCss(): Plugin {
+    return {
+        name: "gtkx:css",
+        enforce: "pre",
+
+        async resolveId(source, importer, options) {
+            if (!CSS_RE.test(source)) {
+                return;
+            }
+
+            const virtualId = await resolveToVirtual(this, { source, importer, options });
+            if (virtualId === undefined) return;
+
+            return virtualId + INJECT_SUFFIX;
+        },
+
+        load(id) {
+            if (isVirtual(id) && id.endsWith(INJECT_SUFFIX)) {
+                const filePath = fromVirtualId(id.slice(0, -INJECT_SUFFIX.length));
+                const content = readFileSync(filePath, "utf-8");
+                return [`import { injectGlobal } from "@gtkx/css";`, `injectGlobal(${JSON.stringify(content)});`].join(
+                    "\n",
+                );
+            }
+
+            return;
+        },
+    };
+}

package/src/vite-plugins/fast-refresh/refresh-filter.ts

@@ -0,0 +1,18 @@
+export const REFRESH_REG = "$RefreshReg$";
+
+export const REFRESH_SIG = "$RefreshSig$";
+
+export const REFRESH_RUNTIME_SPECIFIER = "@gtkx/cli/refresh-runtime";
+
+const REFRESH_INCLUDE = /\.[tj]sx?$/;
+const REFRESH_EXCLUDE = /node_modules|[/\\]dist[/\\]|[/\\]\.gtkx[/\\]/;
+
+export const shouldTransformForRefresh = (
+    id: string,
+    transformOptions: { ssr?: boolean | undefined } | undefined,
+): boolean => {
+    if (!transformOptions?.ssr) return false;
+    if (!REFRESH_INCLUDE.test(id)) return false;
+    if (REFRESH_EXCLUDE.test(id)) return false;
+    return true;
+};

package/src/vite-plugins/fast-refresh/swc-refresh.ts

@@ -0,0 +1,79 @@
+import { fileURLToPath } from "node:url";
+import { type Options as SwcOptions, transform } from "@swc/core";
+import type { Plugin } from "vite";
+import { REFRESH_REG, REFRESH_RUNTIME_SPECIFIER, REFRESH_SIG, shouldTransformForRefresh } from "./refresh-filter.js";
+
+export function gtkxSwcRefresh(): Plugin {
+    return {
+        name: "gtkx:swc-refresh",
+        enforce: "pre",
+        apply: "serve",
+
+        async transform(code, id, transformOptions) {
+            if (!shouldTransformForRefresh(id, transformOptions)) {
+                return;
+            }
+
+            const isTsx = id.endsWith(".tsx");
+            const isTs = id.endsWith(".ts") || isTsx;
+
+            const swcOptions: SwcOptions = {
+                filename: id,
+                sourceFileName: id,
+                sourceMaps: true,
+                jsc: {
+                    parser: isTs ? { syntax: "typescript", tsx: isTsx } : { syntax: "ecmascript", jsx: true },
+                    transform: {
+                        react: {
+                            runtime: "automatic",
+                            development: true,
+                            refresh: true,
+                        },
+                    },
+                    target: "es2022",
+                },
+            };
+
+            const result = await transform(code, swcOptions);
+
+            return result.map === undefined ? { code: result.code } : { code: result.code, map: result.map };
+        },
+    };
+}
+
+export function gtkxRefreshRuntime(): Plugin {
+    return {
+        name: "gtkx:refresh-runtime",
+        enforce: "post",
+        apply: "serve",
+
+        resolveId(id) {
+            if (id !== REFRESH_RUNTIME_SPECIFIER) return undefined;
+            return fileURLToPath(import.meta.resolve(REFRESH_RUNTIME_SPECIFIER));
+        },
+
+        transform(code, id, transformOptions) {
+            if (!shouldTransformForRefresh(id, transformOptions)) {
+                return;
+            }
+
+            if (!code.includes(REFRESH_REG) && !code.includes(REFRESH_SIG)) {
+                return;
+            }
+
+            const moduleIdJson = JSON.stringify(id);
+
+            const header = `
+import { createModuleRegistration as __createModuleRegistration__ } from "${REFRESH_RUNTIME_SPECIFIER}";
+const { ${REFRESH_REG}, ${REFRESH_SIG} } = __createModuleRegistration__(${moduleIdJson});
+`;
+
+            return {
+                code: header + code,
+                map: null,
+            };
+        },
+    };
+}
+
+export const gtkxFastRefresh = (): Plugin[] => [gtkxSwcRefresh(), gtkxRefreshRuntime()];