@gtkx/cli 1.6.0 → 2.0.0-beta.10

package/src/i18n/types.ts

@@ -1,154 +1,120 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import type { I18nextToolkitConfig, Logger, Plugin } from "i18next-cli";
+import { runTypesGenerator } from "i18next-cli";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import type { SourceMessage } from "./source-messages.js";
-
-type I18nTypesResult = {
-    isWritten: boolean;
-    path: string;
-};
 
+const CONTEXT_SEPARATOR = "\u{4}";
+const DEFAULT_NAMESPACE = "translation";
 const I18N_TYPES_FILENAME = "i18n.d.ts";
-const INTERPOLATION_PATTERN = /\{\{[^{}]+\}\}/u;
-
-const stringType = (values: string[]): string =>
-    [...new Set(values)].map((value) => JSON.stringify(value)).join(" | ");
-
-const contextField = (context: string | null): string =>
-    context === null ? "" : ` context: ${JSON.stringify(context)};`;
-
-const hasInterpolation = (values: string[]): boolean => values.some((value) => INTERPOLATION_PATTERN.test(value));
+const I18N_RESOURCES_FILENAME = "i18n-resources.d.ts";
 
-const pointVariant = (message: SourceMessage): string => {
-    const isRequired = message.context !== null || hasInterpolation([message.msgid]);
-    const isInterpolated = hasInterpolation([message.msgid]);
+const generatedDir = (root: string): string => join(root, "node_modules", ".gtkx");
+const i18nResourceDir = (root: string): string => join(generatedDir(root), "i18n");
+const i18nTypesPath = (root: string): string => join(generatedDir(root), I18N_TYPES_FILENAME);
+const i18nResourcesPath = (root: string): string => join(generatedDir(root), I18N_RESOURCES_FILENAME);
 
-    return (
-        `{${contextField(message.context)} interpolated: ${String(isInterpolated)}; kind: "point"; ` +
-        `required: ${String(isRequired)}; value: ${JSON.stringify(message.msgid)} }`
-    );
+const clearI18nResources = (root: string): void => {
+    rmSync(i18nResourceDir(root), { force: true, recursive: true });
 };
 
-const defaultVariant = (message: SourceMessage): string => {
-    const values = [message.singular];
-    const isInterpolated = hasInterpolation(values);
-    const isRequired = message.context !== null || isInterpolated;
+const i18nToolkitConfig = (
+    root: string,
+    sourceFiles: string[],
+    plugins: Plugin[] = [],
+): I18nextToolkitConfig => ({
+    locales: ["en"],
+    plugins,
+    extract: {
+        contextSeparator: CONTEXT_SEPARATOR,
+        defaultNS: DEFAULT_NAMESPACE,
+        disablePlurals: false,
+        extractFromComments: false,
+        functions: ["t"],
+        generateBasePluralForms: false,
+        input: sourceFiles,
+        keySeparator: ".",
+        nsSeparator: false,
+        output: join(i18nResourceDir(root), "{{language}}", "{{namespace}}.json"),
+        pluralSeparator: "_",
+        primaryLanguage: "en",
+        removeUnusedKeys: true,
+        transComponents: ["Trans", "TransWithoutContext"],
+        useTranslationNames: ["useTranslation"],
+        warnOnConflicts: "error",
+    },
+    types: {
+        input: join(i18nResourceDir(root), "en", "*.json"),
+        output: i18nTypesPath(root),
+        resourcesFile: i18nResourcesPath(root),
+    },
+});
+
+const declarations = (): string => `import type Resources from "./i18n-resources.js";
+
+declare module "@gtkx/i18n" {
+    interface I18nResources extends Resources {}
+}
+`;
+
+const writeChanged = (path: string, content: string): void => {
+    let current: string | null;
 
-    return (
-        `{${contextField(message.context)} defaultValue: ${JSON.stringify(message.singular)}; ` +
-        `interpolated: ${String(isInterpolated)}; kind: "default"; required: ${String(isRequired)}; ` +
-        `value: ${stringType(values)} }`
-    );
-};
-
-const requirePlural = (message: SourceMessage): string => {
-    if (message.plural === null) {
-        throw new Error("Plural translation metadata requires a plural source string");
-    }
-
-    return message.plural;
-};
-
-const pluralVariant = (message: SourceMessage): string => {
-    const plural = requirePlural(message);
-    const values = [message.singular, plural];
-    const isInterpolated = hasInterpolation(values);
-
-    return (
-        `{${contextField(message.context)} defaultValue: ${JSON.stringify(plural)}; ` +
-        `interpolated: ${String(isInterpolated)}; kind: "plural"; required: true; ` +
-        `value: ${stringType(values)} }`
-    );
-};
-
-const pluralDefaultsVariant = (message: SourceMessage): string => {
-    const plural = requirePlural(message);
-    const values = [message.singular, plural];
-    const isInterpolated = hasInterpolation(values);
-
-    return (
-        `{${contextField(message.context)} defaultValueOne: ${JSON.stringify(message.singular)}; ` +
-        `defaultValueOther: ${JSON.stringify(plural)}; interpolated: ${String(isInterpolated)}; ` +
-        `kind: "pluralDefaults"; required: true; value: ${stringType(values)} }`
-    );
-};
-
-const variantsFor = (message: SourceMessage): string[] => {
-    if (message.kind === "plural") {
-        return [pluralVariant(message)];
+    try {
+        current = readFileSync(path, "utf8");
+    } catch {
+        current = null;
     }
 
-    if (message.kind === "pluralDefaults") {
-        return [pluralDefaultsVariant(message)];
+    if (current === content) {
+        return;
     }
 
-    return message.kind === "default" ? [defaultVariant(message)] : [pointVariant(message)];
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
 };
 
-const renderRegistry = (messages: SourceMessage[]): string[] => {
-    const entries: Map<string, Set<string>> = new Map();
-
-    for (const message of messages) {
-        const variants = entries.get(message.msgid) ?? new Set<string>();
-
-        for (const variant of variantsFor(message)) {
-            variants.add(variant);
-        }
-
-        entries.set(message.msgid, variants);
-    }
-
-    return [...entries]
-        .toSorted(([left], [right]) => left.localeCompare(right))
-        .map(([msgid, variants]) => `        ${JSON.stringify(msgid)}: ${[...variants].join(" | ")};`);
+const typegenLogger = (): { errors: string[]; logger: Logger } => {
+    const errors: string[] = [];
+
+    return {
+        errors,
+        logger: {
+            error(value) {
+                errors.push(String(value));
+            },
+            info() {
+                return;
+            },
+            warn() {
+                return;
+            },
+        },
+    };
 };
 
-const generatedHeader = (): string[] => [
-    "/**",
-    " * Translation declarations generated by GTKX. Regenerated by",
-    " * `gtkx codegen`, `gtkx dev`, and `gtkx build`; do not edit.",
-    " */",
-];
+const emitI18nTypes = async (root: string): Promise<void> => {
+    const typesPath = i18nTypesPath(root);
+    const resourcesPath = i18nResourcesPath(root);
+    writeChanged(typesPath, declarations());
+    const { errors, logger } = typegenLogger();
+    await runTypesGenerator(i18nToolkitConfig(root, []), { logger, quiet: true });
 
-const renderI18nTypes = (messages: SourceMessage[], isEnabled = true): string => {
-    if (!isEnabled) {
-        return [...generatedHeader(), "export {};", ""].join("\n");
+    if (errors.length > 0 || !existsSync(typesPath) || !existsSync(resourcesPath)) {
+        throw new Error(errors.join("\n") || "i18next type generation did not produce its outputs");
     }
-
-    return [
-        ...generatedHeader(),
-        'import "@gtkx/i18n";',
-        "",
-        'declare module "@gtkx/i18n" {',
-        "    interface TranslationRegistry {",
-        ...renderRegistry(messages),
-        "    }",
-        "}",
-        "",
-    ].join("\n");
 };
 
-const i18nTypesPath = (root: string): string => join(root, "node_modules", ".gtkx", I18N_TYPES_FILENAME);
-
-const readFileOrNull = (path: string): string | null => {
-    try {
-        return readFileSync(path, "utf8");
-    } catch {
-        return null;
-    }
+const clearI18nTypes = (root: string): void => {
+    rmSync(i18nTypesPath(root), { force: true });
+    rmSync(i18nResourcesPath(root), { force: true });
+    clearI18nResources(root);
 };
 
-const emitI18nTypes = (root: string, messages: SourceMessage[], isEnabled = true): I18nTypesResult => {
-    const path = i18nTypesPath(root);
-    const content = renderI18nTypes(messages, isEnabled);
-
-    if (readFileOrNull(path) === content) {
-        return { isWritten: false, path };
-    }
-
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, content);
-
-    return { isWritten: true, path };
+export {
+    I18N_TYPES_FILENAME,
+    clearI18nResources,
+    clearI18nTypes,
+    emitI18nTypes,
+    i18nToolkitConfig,
+    i18nTypesPath,
 };
-
-export { I18N_TYPES_FILENAME, emitI18nTypes, i18nTypesPath };

package/src/internal/agent-rules.ts

@@ -18,9 +18,13 @@ const TOP_LEVEL_HEADING = /^# /m;
 const rulesBody = (heading: string): string[] => [
     `${heading} GTKX`,
     "",
-    "This is not the GTK you have seen before. Most GTK code in your training data is C, PyGObject, Vala or " +
-    "GJS, and almost none of it is valid here. Check the rules below against what you are about to write.",
+    "GTKX applications are Adwaita-first, with GTK4 underneath. Most GNOME UI code in your training data is C, " +
+    "PyGObject, Vala or GJS, and almost none of it is valid here. Check the rules below against what you are " +
+    "about to write.",
     "",
+    "- Start application shells with `AdwApplication` and `AdwApplicationWindow`. Freeform windows normally use " +
+    "`AdwToolbarView` and `AdwHeaderBar`; navigation containers own their Adwaita chrome. Prefer Adwaita for " +
+    "structure, navigation, dialogs, rows, and adaptive patterns; use GTK4 for lower-level primitives.",
     "- Children are JSX, never `.append()`, `pack_start()`, `set_child()` or `add()`.",
     '- Signals are props: `onClicked`, not `widget.connect("clicked", ...)`.',
     "- Props are camelCase: `marginTop`, not `margin-top` or `margin_top`.",
@@ -37,6 +41,7 @@ const rulesBody = (heading: string): string[] => [
     "| --- | --- |",
     "| `gtkx dev` | Run the app with fast refresh |",
     "| `gtkx codegen` | Regenerate bindings and this reference |",
+    "| `gtkx cleanup` | Remove stale headless runtime and compile cache directories |",
     "| `tsc --noEmit` | Typecheck |",
     "| `vitest run` | Run the tests |",
     "",

package/src/internal/banner.ts

@@ -1,13 +1,34 @@
 import type { Rollup } from "vite";
+import { posix } from "node:path";
 
-const prependBanner = (options: Rollup.OutputOptions, banner: string): Rollup.OutputOptions => {
+type Banner = string | Rollup.AddonFunction;
+
+const renderBanner = async (banner: Banner, chunk: Rollup.RenderedChunk): Promise<string> =>
+    typeof banner === "function" ? banner(chunk) : banner;
+
+const prependBanner = (options: Rollup.OutputOptions, banner: Banner): Rollup.OutputOptions => {
     const existing = options.banner;
 
-    if (typeof existing === "function") {
-        return { ...options, banner: async (chunk) => `${banner}\n${await existing(chunk)}` };
-    }
+    return {
+        ...options,
+        banner: async (chunk) => {
+            const prefix = await renderBanner(banner, chunk);
+            const suffix = existing === undefined ? "" : await renderBanner(existing, chunk);
+
+            if (prefix.length === 0) {
+                return suffix;
+            }
+
+            return suffix.length === 0 ? prefix : `${prefix}\n${suffix}`;
+        },
+    };
+};
+
+const outputRootUrlExpression = (chunk: Rollup.RenderedChunk): string => {
+    const relativeRoot = posix.relative(posix.dirname(chunk.fileName), ".");
+    const specifier = relativeRoot.length === 0 ? "./" : `${relativeRoot}/`;
 
-    return { ...options, banner: existing ? `${banner}\n${existing}` : banner };
+    return `decodeURIComponent(new URL(${JSON.stringify(specifier)}, import.meta.url).pathname)`;
 };
 
-export { prependBanner };
+export { outputRootUrlExpression, prependBanner };

package/src/internal/build-manifest.ts

@@ -1,3 +1,5 @@
+import { createHash } from "node:crypto";
+
 type RecordedPackage = {
     name: string;
     version: string | null;
@@ -7,6 +9,8 @@ type RecordedPackage = {
 type BuildManifest = {
     generator: typeof BUILD_MANIFEST_GENERATOR;
     formatVersion: typeof BUILD_MANIFEST_FORMAT_VERSION;
+    configFile: string;
+    configDigest: string;
     schemas: string[];
     packages: RecordedPackage[];
 };
@@ -17,7 +21,26 @@ type BuildManifestCollector = {
 
 const BUILD_MANIFEST_FILENAME = "gtkx-schemas.json";
 const BUILD_MANIFEST_GENERATOR = "gtkx-build";
-const BUILD_MANIFEST_FORMAT_VERSION = 1;
+const BUILD_MANIFEST_FORMAT_VERSION = 2;
+
+const canonicalConfig = (value: unknown): unknown => {
+    if (Array.isArray(value)) {
+        return value.map((entry) => canonicalConfig(entry));
+    }
+
+    if (typeof value !== "object" || value === null) {
+        return value;
+    }
+
+    return Object.fromEntries(
+        Object.entries(value)
+            .toSorted(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => [key, canonicalConfig(entry)]),
+    );
+};
+
+const configDigest = (config: unknown): string =>
+    createHash("sha256").update(JSON.stringify(canonicalConfig(config))).digest("hex");
 
 const createBuildManifestCollector = (): BuildManifestCollector => ({ schemas: [] });
 
@@ -25,6 +48,7 @@ export {
     BUILD_MANIFEST_FILENAME,
     BUILD_MANIFEST_FORMAT_VERSION,
     BUILD_MANIFEST_GENERATOR,
+    configDigest,
     createBuildManifestCollector,
     type BuildManifest,
     type BuildManifestCollector,

package/src/internal/build-output.ts

@@ -0,0 +1,171 @@
+import { isPathInside, isRecord } from "@gtkx/utils";
+import { lstatSync, readdirSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import {
+    BUILD_MANIFEST_FILENAME,
+    BUILD_MANIFEST_GENERATOR,
+} from "./build-manifest.js";
+import {
+    type OutputDirectoryTransaction,
+    prepareOutputDirectory,
+    readRegularFile,
+} from "./output-directory.js";
+
+const DEFAULT_BUILD_OUT_DIR = "dist";
+const PRESERVED_BUILD_ENTRIES: ReadonlySet<string> = new Set([".git"]);
+
+type PreparedBuildOutDir = Disposable & { commit: () => void; path: string };
+
+const hasSymlinkComponent = (root: string, target: string): boolean => {
+    let current = root;
+
+    for (const segment of relative(root, target).split(sep)) {
+        current = join(current, segment);
+
+        if (lstatSync(current, { throwIfNoEntry: false })?.isSymbolicLink() === true) {
+            return true;
+        }
+    }
+
+    return false;
+};
+
+const isGtkxBuildDirectory = (path: string): boolean => {
+    const manifest = join(path, BUILD_MANIFEST_FILENAME);
+    const contents = readRegularFile(manifest);
+
+    try {
+        const parsed: unknown = contents === null ? null : JSON.parse(contents);
+
+        return isRecord(parsed) && parsed.generator === BUILD_MANIFEST_GENERATOR;
+    } catch {
+        return false;
+    }
+};
+
+const isReusableBuildDirectory = (path: string): boolean => {
+    const stats = lstatSync(path, { throwIfNoEntry: false });
+
+    if (stats === undefined) {
+        return true;
+    }
+
+    return stats.isDirectory() && (readdirSync(path).length === 0 || isGtkxBuildDirectory(path));
+};
+
+const outputName = (root: string, path: string): string => relative(root, path) || ".";
+
+const gtkxBuildAncestor = (root: string, outDir: string): string | null => {
+    let ancestor = dirname(outDir);
+
+    while (isPathInside(root, ancestor)) {
+        if (isGtkxBuildDirectory(ancestor)) {
+            return ancestor;
+        }
+
+        ancestor = dirname(ancestor);
+    }
+
+    return null;
+};
+
+const childDirectories = (parent: string): string[] =>
+    readdirSync(parent, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => join(parent, entry.name));
+
+const gtkxBuildDescendant = (root: string): string | null => {
+    const pending = childDirectories(root);
+
+    while (pending.length > 0) {
+        const path = pending.pop();
+
+        if (path === undefined) {
+            return null;
+        }
+
+        if (isGtkxBuildDirectory(path)) {
+            return path;
+        }
+
+        pending.push(...childDirectories(path));
+    }
+
+    return null;
+};
+
+const assertSafeBuildLocation = (root: string, outDir: string): void => {
+    if (!isPathInside(root, outDir)) {
+        throw new Error(`Build output ${outDir} must be below the project root ${root}`);
+    }
+
+    if (hasSymlinkComponent(root, outDir)) {
+        throw new Error(`Build output ${outputName(root, outDir)} passes through a symbolic link`);
+    }
+
+    const ancestor = gtkxBuildAncestor(root, outDir);
+
+    if (ancestor !== null) {
+        throw new Error(
+            `Build output ${outputName(root, outDir)} is nested inside the earlier GTKX build ` +
+            outputName(root, ancestor),
+        );
+    }
+};
+
+const nonReusableBuildOutputError = (root: string, outDir: string): Error => {
+    const stats = lstatSync(outDir, { throwIfNoEntry: false });
+
+    if (stats?.isDirectory() !== true) {
+        return new Error(`Build output ${outputName(root, outDir)} exists and is not a directory`);
+    }
+
+    const descendant = gtkxBuildDescendant(outDir);
+
+    if (descendant !== null) {
+        return new Error(
+            `Build output ${outputName(root, outDir)} contains the earlier GTKX build ` +
+            outputName(root, descendant),
+        );
+    }
+
+    return new Error(
+        `Build output ${outputName(root, outDir)} is nonempty and is not an earlier GTKX build`,
+    );
+};
+
+const resolveBuildOutDir = (root: string, configured?: string): string => {
+    const selected = configured ?? DEFAULT_BUILD_OUT_DIR;
+    const outDir = resolve(root, selected);
+
+    assertSafeBuildLocation(root, outDir);
+
+    if (!isReusableBuildDirectory(outDir)) {
+        throw nonReusableBuildOutputError(root, outDir);
+    }
+
+    return outDir;
+};
+
+const prepareBuildOutDir = (root: string, outDir: string): PreparedBuildOutDir => {
+    assertSafeBuildLocation(root, outDir);
+    const prepared = prepareOutputDirectory(root, outDir, isReusableBuildDirectory);
+
+    if (prepared.status === "unsafe") {
+        throw new Error(`Build output ${outputName(root, outDir)} became unsafe while preparing it`);
+    }
+
+    const transaction: OutputDirectoryTransaction = prepared.transaction;
+
+    return {
+        path: transaction.path,
+        commit: () => {
+            transaction.commit(PRESERVED_BUILD_ENTRIES, isGtkxBuildDirectory);
+        },
+        [Symbol.dispose]: () => {
+            transaction[Symbol.dispose]();
+        },
+    };
+};
+
+export { prepareBuildOutDir, resolveBuildOutDir };

package/src/internal/cache-root.ts

@@ -0,0 +1,12 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const CACHE_NAMESPACE = "gtkx";
+
+const cacheRoot = (): string => {
+    const base = process.env.XDG_CACHE_HOME;
+
+    return join(base !== undefined && base.length > 0 ? base : join(homedir(), ".cache"), CACHE_NAMESPACE);
+};
+
+export { cacheRoot };

package/src/internal/compile-cache-store.ts

@@ -0,0 +1,50 @@
+import { readdirSync, rmSync } from "node:fs";
+import * as nodeModule from "node:module";
+import { basename, join } from "node:path";
+import { cacheRoot } from "./cache-root.js";
+import { COMPILE_CACHE_SEGMENT } from "./compile-cache.js";
+
+const RUNTIME_PREFIX = `v${process.versions.node}-${process.arch}-`;
+
+const currentNamespace = (): string | undefined => {
+    if (typeof nodeModule.getCompileCacheDir !== "function") {
+        return undefined;
+    }
+
+    const dir = nodeModule.getCompileCacheDir();
+
+    return dir === undefined ? undefined : basename(dir);
+};
+
+const isStale = (name: string, namespace: string | undefined): boolean =>
+    namespace === undefined ? !name.startsWith(RUNTIME_PREFIX) : name !== namespace;
+
+const findStaleCompileCaches = (): string[] => {
+    const namespace = currentNamespace();
+    const dir = join(cacheRoot(), COMPILE_CACHE_SEGMENT);
+
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && isStale(entry.name, namespace))
+            .map((entry) => join(dir, entry.name));
+    } catch {
+        return [];
+    }
+};
+
+const reapStaleCompileCaches = (candidates: string[]): string[] => {
+    const removed: string[] = [];
+
+    for (const candidate of candidates) {
+        try {
+            rmSync(candidate, { recursive: true, force: true });
+            removed.push(candidate);
+        } catch {
+            continue;
+        }
+    }
+
+    return removed;
+};
+
+export { findStaleCompileCaches, reapStaleCompileCaches };

package/src/internal/compile-cache.ts

@@ -0,0 +1,20 @@
+import * as nodeModule from "node:module";
+import { join } from "node:path";
+import { cacheRoot } from "./cache-root.js";
+
+const COMPILE_CACHE_SEGMENT = "compile-cache";
+const DISABLE_COMPILE_CACHE_ENV = "GTKX_DISABLE_COMPILE_CACHE";
+
+const enableToolchainCompileCache = (): void => {
+    if (process.env[DISABLE_COMPILE_CACHE_ENV] === "1") {
+        return;
+    }
+
+    if (typeof nodeModule.enableCompileCache !== "function") {
+        return;
+    }
+
+    nodeModule.enableCompileCache(join(cacheRoot(), COMPILE_CACHE_SEGMENT));
+};
+
+export { COMPILE_CACHE_SEGMENT, enableToolchainCompileCache };

package/src/internal/deploy-out-dir.ts

@@ -0,0 +1,8 @@
+import { resolve } from "node:path";
+
+const DEFAULT_DEPLOY_OUT_DIR = "build";
+
+const deployOutDirFor = (root: string, configured: string | undefined): string =>
+    resolve(root, configured ?? DEFAULT_DEPLOY_OUT_DIR);
+
+export { DEFAULT_DEPLOY_OUT_DIR, deployOutDirFor };

package/src/internal/docs-elements.ts

@@ -1,21 +1,27 @@
-import { type ElementProps, type OmittedProps, readBuiltinElements, resolveStore } from "@gtkx/codegen";
+import {
+    type ElementProps,
+    type OmittedProps,
+    resolveStore,
+} from "@gtkx/codegen";
+import { readBuiltinElementsForDocs } from "@gtkx/codegen/internal";
 import { existsSync } from "node:fs";
 
 type DocsElements = {
     props: ElementProps;
     omittedProps: OmittedProps;
+    acceptedChildTypes: Record<string, string[]>;
 };
 
 const resolveDocsElements = async (cwd: string): Promise<DocsElements> => {
-    const { gi, reactSubexports } = resolveStore(cwd);
+    const { gi } = resolveStore(cwd);
 
     if (!existsSync(gi.storeDir)) {
-        return { props: {}, omittedProps: {} };
+        return { props: {}, omittedProps: {}, acceptedChildTypes: {} };
     }
 
-    const { props, omittedProps } = await readBuiltinElements(reactSubexports, gi.storeDir);
+    const { props, omittedProps, acceptedChildTypes } = await readBuiltinElementsForDocs();
 
-    return { props, omittedProps };
+    return { props, omittedProps, acceptedChildTypes };
 };
 
 export { resolveDocsElements };