@gtkx/cli 0.21.0 → 1.0.0-rc.2

package/src/refresh-runtime.ts

@@ -1,22 +1,16 @@
 import RefreshRuntime from "react-refresh/runtime";
+import "./refresh-globals.js";
 
 type ComponentType = (...args: unknown[]) => unknown;
 
-RefreshRuntime.injectIntoGlobalHook(globalThis);
-globalThis.$RefreshReg$ = () => {};
-globalThis.$RefreshSig$ = () => (type: unknown) => type;
-
 /**
- * Creates registration functions for a module's React components.
- *
- * Used internally by the Vite plugin to register components
- * for React Fast Refresh.
+ * Builds the per-module `$RefreshReg$` and `$RefreshSig$` hooks that React Refresh
+ * transformed code expects, scoping every registered component to the given module.
  *
- * @param moduleId - Unique identifier for the module
- * @returns Registration functions for the module
- * @internal
+ * @param moduleId Identifier used to namespace registered component types so they are unique across modules.
+ * @returns An object with `$RefreshReg$` and `$RefreshSig$` to install as module-local globals.
  */
-export function createModuleRegistration(moduleId: string): {
+function createModuleRegistration(moduleId: string): {
     $RefreshReg$: (type: ComponentType, id: string) => void;
     $RefreshSig$: typeof RefreshRuntime.createSignatureFunctionForTransform;
 } {
@@ -28,62 +22,43 @@ export function createModuleRegistration(moduleId: string): {
     };
 }
 
-function isLikelyComponentType(value: unknown): boolean {
-    if (typeof value !== "function") {
-        return false;
-    }
-
-    const func = value as { $$typeof?: symbol };
-
-    if (func.$$typeof === Symbol.for("react.memo") || func.$$typeof === Symbol.for("react.forward_ref")) {
-        return true;
-    }
-
-    const name = (value as { name?: string }).name;
-    if (typeof name === "string" && /^[A-Z]/.test(name)) {
-        return true;
-    }
-
-    return false;
-}
-
 /**
- * Checks if a module's exports form a React Refresh boundary.
- *
- * A module is a refresh boundary if all its exports are React components,
- * allowing for fast refresh without full page reload.
+ * Determines whether a module can act as a React Refresh boundary, meaning every one of
+ * its exports (ignoring `__esModule`) looks like a React component type.
  *
- * @param moduleExports - The module's exports object
- * @returns `true` if the module can be fast-refreshed
- * @internal
+ * @param moduleExports The module's export object to inspect.
+ * @returns `true` when the module qualifies as a refresh boundary, `false` otherwise.
  */
-export function isReactRefreshBoundary(moduleExports: Record<string, unknown>): boolean {
-    if (RefreshRuntime.isLikelyComponentType(moduleExports)) {
-        return true;
-    }
+const isComponentExport = (key: string, value: unknown): boolean =>
+    key === "__esModule" || RefreshRuntime.isLikelyComponentType(value);
 
+const areAllExportsComponents = (moduleExports: Record<string, unknown>): boolean => {
     for (const key in moduleExports) {
-        if (key === "__esModule") {
-            continue;
+        if (!isComponentExport(key, moduleExports[key])) {
+            return false;
         }
+    }
 
-        const value = moduleExports[key];
+    return true;
+};
 
-        if (!isLikelyComponentType(value)) {
-            return false;
-        }
+function isRefreshBoundary(moduleExports: Record<string, unknown>): boolean {
+    if (RefreshRuntime.isLikelyComponentType(moduleExports)) {
+        return true;
+    }
+
+    if (!areAllExportsComponents(moduleExports)) {
+        return false;
     }
 
-    return Object.keys(moduleExports).filter((k) => k !== "__esModule").length > 0;
+    return Object.keys(moduleExports).some((k) => k !== "__esModule");
 }
 
 /**
- * Triggers React Fast Refresh to re-render components.
- *
- * Called after module updates when all exports are React components.
- *
- * @internal
+ * Applies all pending React Refresh updates, re-rendering components whose modules have changed.
  */
-export function performRefresh(): void {
+function performRefresh(): void {
     RefreshRuntime.performReactRefresh();
 }
+
+export { createModuleRegistration, isRefreshBoundary, performRefresh };

package/src/settings/compile.ts

@@ -0,0 +1,22 @@
+import { formatChildProcessError } from "@gtkx/utils";
+import { execFileSync } from "node:child_process";
+import { resolveCliTool } from "../internal/resolve-cli-tool.js";
+
+const SCHEMA_COMPILER = "glib-compile-schemas";
+const SCHEMA_COMPILE_TIMEOUT_MS = 30_000;
+
+const compileSchemas = (dir: string): void => {
+    try {
+        execFileSync(resolveCliTool(SCHEMA_COMPILER), ["--strict", dir], {
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: SCHEMA_COMPILE_TIMEOUT_MS,
+            encoding: "utf8",
+        });
+    } catch (error) {
+        const details = formatChildProcessError(error);
+        const suffix = details ? `:\n${details}` : "";
+        throw new Error(`glib-compile-schemas failed for ${dir}${suffix}`, { cause: error });
+    }
+};
+
+export { compileSchemas };

package/src/settings/parser.ts

@@ -0,0 +1,193 @@
+import { XMLParser } from "fast-xml-parser";
+
+type ParsedKey = {
+    name: string;
+    variantType: string | null;
+    enumId: string | null;
+    flagsId: string | null;
+    choices: string[];
+    summary: string | null;
+};
+
+type ParsedSchema = {
+    id: string;
+    path: string | null;
+    keys: ParsedKey[];
+};
+
+type ParsedSchemaFile = {
+    fileName: string;
+    schemas: ParsedSchema[];
+    enums: Map<string, string[]>;
+    flags: Map<string, string[]>;
+};
+
+type RawNode = Record<string, unknown>;
+
+type RawSchema = {
+    id: string;
+    path: string | null;
+    extendsId: string | null;
+    keys: ParsedKey[];
+};
+
+type MergeContext = {
+    byId: Map<string, RawSchema>;
+    merged: Map<string, ParsedKey>;
+    visited: Set<string>;
+};
+
+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: Map<string, string[]> = new Map();
+
+    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"),
+    };
+};
+
+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 collectInheritedKeys = (context: MergeContext, current: RawSchema): void => {
+    if (context.visited.has(current.id)) {
+        return;
+    }
+
+    context.visited.add(current.id);
+    const parent = current.extendsId === null ? undefined : context.byId.get(current.extendsId);
+
+    if (parent !== undefined) {
+        collectInheritedKeys(context, parent);
+    }
+
+    for (const key of current.keys) {
+        context.merged.set(key.name, key);
+    }
+};
+
+const mergeInheritedKeys = (schema: RawSchema, byId: Map<string, RawSchema>): ParsedKey[] => {
+    const context: MergeContext = { byId, merged: new Map(), visited: new Set() };
+    collectInheritedKeys(context, schema);
+
+    return context.merged.values().toArray();
+};
+
+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"),
+    };
+};
+
+class SchemaParseError extends Error {}
+
+export { parseSchemaXml, SchemaParseError, type ParsedKey, type ParsedSchema, type ParsedSchemaFile };

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 ENUM_KIND = "enum";
+const FLAGS_KIND = "flags";
+
+const toJsStringLiteral = (value: string): string =>
+    JSON.stringify(value).replaceAll("\u{2028}", String.raw`\u2028`).replaceAll("\u{2029}", String.raw`\u2029`);
+
+const getExportName = (schemaId: string): string => schemaId.replaceAll(".", "_");
+
+const runtimeKindForKey = (key: ParsedKey): string => {
+    if (key.enumId !== null) {
+        return ENUM_KIND;
+    }
+
+    if (key.flagsId !== null) {
+        return FLAGS_KIND;
+    }
+
+    return key.variantType ?? "";
+};
+
+const getRuntimeKeys = (schema: ParsedSchema): string => {
+    const entries = schema.keys.map(
+        (key) => `${toJsStringLiteral(key.name)}: ${toJsStringLiteral(runtimeKindForKey(key))}`,
+    );
+
+    return `{ ${entries.join(", ")} }`;
+};
+
+const renderRuntimeModule = (file: ParsedSchemaFile): string => {
+    const lines: string[] = [];
+
+    for (const [index, schema] of file.schemas.entries()) {
+        const keysName = `keys_${String(index)}`;
+        const id = toJsStringLiteral(schema.id);
+        lines.push(`const ${keysName} = ${getRuntimeKeys(schema)};`);
+
+        if (schema.path === null) {
+            lines.push(
+                `export const ${getExportName(schema.id)} = { id: ${id}, keys: ${keysName}, ` +
+                `at: (path) => ({ id: ${id}, path, keys: ${keysName} }) };`,
+            );
+        } else {
+            lines.push(`export const ${getExportName(schema.id)} = { id: ${id}, path: null, keys: ${keysName} };`);
+        }
+    }
+
+    const first = file.schemas[0];
+
+    if (first !== undefined) {
+        lines.push(`export default ${getExportName(first.id)};`);
+    }
+
+    return lines.join("\n");
+};
+
+const sanitizeSummary = (summary: string): string => summary.replaceAll("*/", String.raw`*\/`);
+
+const allocateInterfaceName = (schemaId: string, usedNames: Set<string>): string => {
+    const base = `${schemaId
+        .split(/[^a-zA-Z0-9]+/)
+        .filter((part) => part.length > 0)
+        .map((part) => upperFirst(part))
+        .join("")}Keys`;
+
+    let name = base;
+    let suffix = 2;
+
+    while (usedNames.has(name)) {
+        name = `${base}${String(suffix)}`;
+        suffix += 1;
+    }
+
+    usedNames.add(name);
+
+    return name;
+};
+
+const renderKeysType = (name: string, schema: ParsedSchema): 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)}: ${toJsStringLiteral(runtimeKindForKey(key))};`);
+    }
+
+    lines.push("    };");
+
+    return lines;
+};
+
+const boundRefTypeLines = (interfaceName: string, indent: string): string[] => [
+    `${indent}id: string;`,
+    `${indent}path: string | null;`,
+    `${indent}keys: ${interfaceName};`,
+];
+
+const renderSchemaConst = (schema: ParsedSchema, interfaceName: string): string[] => {
+    const exportName = getExportName(schema.id);
+
+    if (schema.path !== null) {
+        return [
+            `    const ${exportName}: {`,
+            `        id: ${toJsStringLiteral(schema.id)};`,
+            ...boundRefTypeLines(interfaceName, " ".repeat(8)).slice(1),
+            "    };",
+        ];
+    }
+
+    return [
+        `    const ${exportName}: {`,
+        `        id: ${JSON.stringify(schema.id)};`,
+        `        keys: ${interfaceName};`,
+        "        at(path: string): {",
+        ...boundRefTypeLines(interfaceName, " ".repeat(12)),
+        "        };",
+        "    };",
+    ];
+};
+
+const renderFileModule = (file: ParsedSchemaFile, usedNames: Set<string>): string[] => {
+    const lines = [`declare module "${file.fileName}" {`];
+    const exportNames: string[] = [];
+
+    for (const [index, schema] of file.schemas.entries()) {
+        if (index > 0) {
+            lines.push("");
+        }
+
+        const interfaceName = allocateInterfaceName(schema.id, usedNames);
+        lines.push(...renderKeysType(interfaceName, schema), "", ...renderSchemaConst(schema, interfaceName));
+        exportNames.push(getExportName(schema.id));
+    }
+
+    const [firstExport] = exportNames;
+
+    if (firstExport !== undefined) {
+        lines.push("", `    export { ${exportNames.join(", ")} };`, `    export default ${firstExport};`);
+    }
+
+    lines.push("}");
+
+    return lines;
+};
+
+const renderEnvModule = (files: ParsedSchemaFile[]): string => {
+    const usedNames: Set<string> = new Set();
+
+    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`;
+};
+
+export { renderRuntimeModule, renderEnvModule };

package/src/settings/schema.ts

@@ -0,0 +1,169 @@
+import { sortStrings, warn } from "@gtkx/utils";
+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 { 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";
+
+type SchemaEnvResult = {
+    path: string;
+    written: boolean;
+};
+
+const SCHEMA_SUFFIX = ".gschema.xml";
+const STAGED_NAME_LENGTH = 16;
+
+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 stagedSchemaName = (filePath: string): string =>
+    `${createHash("sha1").update(filePath).digest("hex").slice(0, STAGED_NAME_LENGTH)}${SCHEMA_SUFFIX}`;
+
+const stageSchema = (dir: string, filePath: string): void => {
+    copyFileSync(filePath, join(dir, stagedSchemaName(filePath)));
+};
+
+const toForwardSlashes = (value: string): string => value.replaceAll(/[/\\]/g, "/");
+
+const getModuleSpecifier = (dataDirAbs: string, filePath: string): string =>
+    `${DATA_IMPORT_PREFIX}/${toForwardSlashes(relative(dataDirAbs, filePath))}`;
+
+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);
+
+const collectSchemaFiles = (dir: string, found: string[]): void => {
+    for (const entry of readVisibleEntries(dir)) {
+        const full = join(dir, entry.name);
+
+        if (entry.isDirectory()) {
+            collectSchemaFiles(full, found);
+        } else if (isSchemaFile(entry)) {
+            found.push(full);
+        }
+    }
+};
+
+const findSchemaFiles = (dataDir: string): string[] => {
+    const found: string[] = [];
+    collectSchemaFiles(dataDir, found);
+
+    return sortStrings(found);
+};
+
+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;
+};
+
+const schemaEnvPath = (rootDir: string): string => join(rootDir, "node_modules", ".gtkx", "env.d.ts");
+
+const parseSchemaFileOrWarn = (filePath: string, dataDirAbs: string): ParsedSchemaFile | null => {
+    const specifier = getModuleSpecifier(dataDirAbs, filePath);
+
+    try {
+        return parseSchemaXml(readFileSync(filePath, "utf8"), specifier);
+    } catch (error) {
+        if (!(error instanceof SchemaParseError)) {
+            throw error;
+        }
+
+        warn(`Skipping ${filePath} in schema type generation: ${error.message}`);
+
+        return null;
+    }
+};
+
+const parseProjectSchemas = (schemaFiles: string[], dataDirAbs: string): ParsedSchemaFile[] => {
+    const parsed: ParsedSchemaFile[] = [];
+
+    for (const filePath of schemaFiles) {
+        const result = parseSchemaFileOrWarn(filePath, dataDirAbs);
+
+        if (result !== null) {
+            parsed.push(result);
+        }
+    }
+
+    return parsed;
+};
+
+const readFileOrNull = (path: string): string | null => {
+    try {
+        return readFileSync(path, "utf8");
+    } catch {
+        return null;
+    }
+};
+
+const didWriteChanges = (path: string, content: string): boolean => {
+    if (readFileOrNull(path) === content) {
+        return false;
+    }
+
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+
+    return true;
+};
+
+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 isWritten = didWriteChanges(path, content);
+
+    return { path, written: isWritten };
+};
+
+export {
+    SCHEMA_SUFFIX,
+    prependSchemaDir,
+    stageSchema,
+    findSchemaFiles,
+    stageAndCompileProjectSchemas,
+    schemaEnvPath,
+    emitSchemaEnv,
+};

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

@@ -0,0 +1,29 @@
+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",
+];
+
+const ASSET_RE = new RegExp(String.raw`\.(?:${ASSET_EXTENSIONS.join("|")})$`, "i");
+const ASSET_PATH_RE = new RegExp(String.raw`\.(?:${ASSET_EXTENSIONS.join("|")})(?:\?.*)?$`, "i");
+
+export { ASSET_EXTENSIONS, ASSET_RE, ASSET_PATH_RE };