@gtkx/cli 1.0.0-rc.1 → 1.0.0-rc.3

package/src/mcp/serialize-widget.ts

@@ -3,25 +3,30 @@ import type { SerializedWidget } from "@gtkx/mcp/internal";
 
 type WidgetIdResolver = (widget: Gtk.Widget) => string;
 
-export type WidgetFormatting = {
+type WidgetFormatting = {
     formatRole(role: Gtk.AccessibleRole): string;
     getWidgetNodeText(widget: Gtk.Widget): string | null;
 };
 
-export const serializeWidget = (
+const serializeWidget = (
     widget: Gtk.Widget,
-    idFor: WidgetIdResolver,
+    resolveId: WidgetIdResolver,
     testing: WidgetFormatting,
+    maxDepth = Infinity,
 ): SerializedWidget => {
     const children: SerializedWidget[] = [];
-    let child = widget.getFirstChild();
-    while (child) {
-        children.push(serializeWidget(child, idFor, testing));
-        child = child.getNextSibling();
+
+    if (maxDepth > 0) {
+        let child = widget.getFirstChild();
+
+        while (child) {
+            children.push(serializeWidget(child, resolveId, testing, maxDepth - 1));
+            child = child.getNextSibling();
+        }
     }
 
     return {
-        id: idFor(widget),
+        id: resolveId(widget),
         type: widget.constructor.name,
         role: testing.formatRole(widget.getAccessibleRole()),
         name: widget.getName() || null,
@@ -32,3 +37,5 @@ export const serializeWidget = (
         children,
     };
 };
+
+export { serializeWidget, type WidgetFormatting };

package/src/mcp/testing-loader.ts

@@ -1,32 +1,73 @@
 type TestingModule = typeof import("@gtkx/testing");
+type TestingModuleLoader = () => Promise<TestingModule>;
 
-export type TestingModuleLoader = () => Promise<TestingModule>;
+type TestingModuleCache = {
+    setLoader: (next: TestingModuleLoader | null) => void;
+    load: () => Promise<TestingModule>;
+};
+
+type TestingModuleState = {
+    loader: TestingModuleLoader;
+    testingModule: TestingModule | null;
+    testingLoadError: Error | null;
+};
 
-const defaultLoader: TestingModuleLoader = () => import("@gtkx/testing");
+const { setLoader: setTestingModuleLoader, load: loadTestingModule } = createTestingModuleCache();
 
-let loader: TestingModuleLoader = defaultLoader;
-let testingModule: TestingModule | null = null;
-let testingLoadError: Error | null = null;
+function defaultLoader(): Promise<TestingModule> {
+    return import("@gtkx/testing");
+}
 
-export const setTestingModuleLoader = (next: TestingModuleLoader | null): void => {
-    loader = next ?? defaultLoader;
-    testingModule = null;
-    testingLoadError = null;
-};
+function missingTestingPackageError(cause: unknown): Error {
+    return new Error(
+        "@gtkx/testing is not installed, install it to enable MCP widget interactions: " +
+        `pnpm add -D @gtkx/testing (import failed: ${String(cause)})`,
+        { cause },
+    );
+}
 
-export const loadTestingModule = async (): Promise<TestingModule> => {
-    if (testingModule) return testingModule;
-    if (testingLoadError) throw testingLoadError;
+function replaceLoader(state: TestingModuleState, next: TestingModuleLoader | null): void {
+    state.loader = next ?? defaultLoader;
+    state.testingModule = null;
+    state.testingLoadError = null;
+}
 
+async function importTestingModule(state: TestingModuleState): Promise<TestingModule> {
     try {
-        testingModule = await loader();
-        return testingModule;
-    } catch (cause) {
-        testingLoadError = new Error(
-            "@gtkx/testing is not installed, install it to enable MCP widget interactions: " +
-                `pnpm add -D @gtkx/testing (import failed: ${String(cause)})`,
-            { cause },
-        );
-        throw testingLoadError;
+        state.testingModule = await state.loader();
+
+        return state.testingModule;
+    } catch (error) {
+        state.testingLoadError = missingTestingPackageError(error);
+        throw state.testingLoadError;
     }
-};
+}
+
+function loadCachedTestingModule(state: TestingModuleState): Promise<TestingModule> {
+    if (state.testingModule) {
+        return Promise.resolve(state.testingModule);
+    }
+
+    if (state.testingLoadError) {
+        return Promise.reject(state.testingLoadError);
+    }
+
+    return importTestingModule(state);
+}
+
+function createTestingModuleCache(): TestingModuleCache {
+    const state: TestingModuleState = {
+        loader: defaultLoader,
+        testingModule: null,
+        testingLoadError: null,
+    };
+
+    return {
+        setLoader: (next: TestingModuleLoader | null): void => {
+            replaceLoader(state, next);
+        },
+        load: (): Promise<TestingModule> => loadCachedTestingModule(state),
+    };
+}
+
+export { setTestingModuleLoader, loadTestingModule, type TestingModule, type TestingModuleLoader };

package/src/mcp/widget-registry.ts

@@ -1,14 +1,15 @@
 import * as Gtk from "@gtkx/gi/gtk";
 
-export class WidgetRegistry {
-    private idByWidget = new WeakMap<Gtk.Widget, string>();
+class WidgetRegistry {
+    private idByWidget: WeakMap<Gtk.Widget, string> = new WeakMap();
     private nextId = 0;
-    private widgetById = new Map<string, Gtk.Widget>();
+    private widgetById: Map<string, Gtk.Widget> = new Map();
     private toplevelWindows: Gtk.Window[] = [];
 
     refresh(): void {
         this.widgetById.clear();
         this.toplevelWindows = Gtk.Window.listToplevels() as Gtk.Window[];
+
         for (const window of this.toplevelWindows) {
             this.register(window);
         }
@@ -19,21 +20,24 @@ export class WidgetRegistry {
     }
 
     register(widget: Gtk.Widget): void {
-        const id = this.idFor(widget);
+        const id = this.getOrCreateId(widget);
         this.widgetById.set(id, widget);
         let child = widget.getFirstChild();
+
         while (child) {
             this.register(child);
             child = child.getNextSibling();
         }
     }
 
-    idFor(widget: Gtk.Widget): string {
+    getOrCreateId(widget: Gtk.Widget): string {
         let id = this.idByWidget.get(widget);
+
         if (!id) {
             id = String(this.nextId++);
             this.idByWidget.set(widget, id);
         }
+
         return id;
     }
 
@@ -41,3 +45,5 @@ export class WidgetRegistry {
         return this.widgetById.get(id);
     }
 }
+
+export { WidgetRegistry };

package/src/refresh-globals.ts

@@ -0,0 +1,10 @@
+import RefreshRuntime from "react-refresh/runtime";
+
+const identity = (type: unknown): unknown => type;
+
+RefreshRuntime.injectIntoGlobalHook(globalThis);
+
+Object.assign(globalThis, {
+    $RefreshReg$: (): void => undefined,
+    $RefreshSig$: () => identity,
+});

package/src/refresh-runtime.ts

@@ -1,11 +1,8 @@
 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;
-
 /**
  * Builds the per-module `$RefreshReg$` and `$RefreshSig$` hooks that React Refresh
  * transformed code expects, scoping every registered component to the given module.
@@ -13,7 +10,7 @@ globalThis.$RefreshSig$ = () => (type: unknown) => type;
  * @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;
 } {
@@ -32,21 +29,26 @@ export function createModuleRegistration(moduleId: string): {
  * @param moduleExports The module's export object to inspect.
  * @returns `true` when the module qualifies as a refresh boundary, `false` otherwise.
  */
-export function isRefreshBoundary(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 (!RefreshRuntime.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).some((k) => k !== "__esModule");
@@ -55,6 +57,8 @@ export function isRefreshBoundary(moduleExports: Record<string, unknown>): boole
 /**
  * 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

@@ -1,19 +1,22 @@
-import { execFileSync } from "node:child_process";
 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;
 
-export const compileSchemas = (dir: string): void => {
+const compileSchemas = (dir: string): void => {
     try {
         execFileSync(resolveCliTool(SCHEMA_COMPILER), ["--strict", dir], {
             stdio: ["ignore", "pipe", "pipe"],
             timeout: SCHEMA_COMPILE_TIMEOUT_MS,
-            encoding: "utf-8",
+            encoding: "utf8",
         });
     } catch (error) {
         const details = formatChildProcessError(error);
-        throw new Error(`glib-compile-schemas failed for ${dir}${details ? `:\n${details}` : ""}`, { cause: 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

@@ -1,6 +1,6 @@
 import { XMLParser } from "fast-xml-parser";
 
-export type ParsedKey = {
+type ParsedKey = {
     name: string;
     variantType: string | null;
     enumId: string | null;
@@ -9,23 +9,34 @@ export type ParsedKey = {
     summary: string | null;
 };
 
-export type ParsedSchema = {
+type ParsedSchema = {
     id: string;
     path: string | null;
     keys: ParsedKey[];
 };
 
-export type ParsedSchemaFile = {
+type ParsedSchemaFile = {
     fileName: string;
     schemas: ParsedSchema[];
     enums: Map<string, string[]>;
     flags: Map<string, string[]>;
 };
 
-export class SchemaParseError extends Error {}
-
 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({
@@ -41,17 +52,23 @@ const isRawNode = (value: unknown): value is RawNode => typeof value === "object
 
 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 [];
+
+    if (!Array.isArray(value)) {
+        return [];
+    }
+
     return value.filter(isRawNode);
 };
 
@@ -61,17 +78,26 @@ const parseNicks = (definition: RawNode): string[] =>
         .filter((nick): nick is string => nick !== null);
 
 const parseDefinitions = (schemalist: RawNode, tag: string): Map<string, string[]> => {
-    const definitions = new 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));
+
+        if (id !== null) {
+            definitions.set(id, parseNicks(definition));
+        }
     }
+
     return definitions;
 };
 
 const parseChoices = (key: RawNode): string[] => {
     const choices = key.choices;
-    if (!isRawNode(choices)) return [];
+
+    if (!isRawNode(choices)) {
+        return [];
+    }
+
     return children(choices, "choice")
         .map((choice) => attr(choice, "value"))
         .filter((value): value is string => value !== null);
@@ -79,9 +105,11 @@ const parseChoices = (key: RawNode): string[] => {
 
 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"),
@@ -92,18 +120,13 @@ const parseKey = (key: RawNode, fileName: string): ParsedKey => {
     };
 };
 
-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"),
@@ -112,35 +135,47 @@ const parseRawSchema = (schema: RawNode, fileName: string): RawSchema => {
     };
 };
 
+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 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()];
+    const context: MergeContext = { byId, merged: new Map(), visited: new Set() };
+    collectInheritedKeys(context, schema);
+
+    return context.merged.values().toArray();
 };
 
-export const parseSchemaXml = (xml: string, fileName: string): ParsedSchemaFile => {
+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) => ({
@@ -152,3 +187,7 @@ export const parseSchemaXml = (xml: string, fileName: string): ParsedSchemaFile
         flags: parseDefinitions(schemalist, "flags"),
     };
 };
+
+class SchemaParseError extends Error {}
+
+export { parseSchemaXml, SchemaParseError, type ParsedKey, type ParsedSchema, type ParsedSchemaFile };