@gtkx/cli 1.6.0 → 2.0.0-beta.2

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/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,99 @@
+import { isPathInside, isRecord } from "@gtkx/utils";
+import { lstatSync, readdirSync } from "node:fs";
+import { 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 buildOutputError = (root: string): Error =>
+    new Error(`Build output must be an empty directory or an earlier GTKX build below the project root ${root}`);
+
+const assertSafeBuildLocation = (root: string, outDir: string): void => {
+    if (!isPathInside(root, outDir) || hasSymlinkComponent(root, outDir)) {
+        throw buildOutputError(root);
+    }
+};
+
+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 buildOutputError(root);
+    }
+
+    return outDir;
+};
+
+const prepareBuildOutDir = (root: string, outDir: string): PreparedBuildOutDir => {
+    assertSafeBuildLocation(root, outDir);
+    const prepared = prepareOutputDirectory(root, outDir, isReusableBuildDirectory);
+
+    if (prepared.status === "unsafe") {
+        throw buildOutputError(root);
+    }
+
+    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/docs-elements.ts

@@ -7,13 +7,13 @@ type DocsElements = {
 };
 
 const resolveDocsElements = async (cwd: string): Promise<DocsElements> => {
-    const { gi, reactSubexports } = resolveStore(cwd);
+    const { gi } = resolveStore(cwd);
 
     if (!existsSync(gi.storeDir)) {
         return { props: {}, omittedProps: {} };
     }
 
-    const { props, omittedProps } = await readBuiltinElements(reactSubexports, gi.storeDir);
+    const { props, omittedProps } = await readBuiltinElements();
 
     return { props, omittedProps };
 };

package/src/internal/entry-arg.ts

@@ -14,6 +14,13 @@ const cwdArg: { cwd: StringArgDef } = {
     },
 };
 
+const configArg: { config: StringArgDef } = {
+    config: {
+        type: "string",
+        description: "Project-relative configuration file (default: gtkx.config.*)",
+    },
+};
+
 const entryArg: { entry: PositionalArgDef; cwd: StringArgDef } = {
     entry: {
         type: "positional",
@@ -57,4 +64,4 @@ const resolveGivenEntry = (cwd: string, entry: string): string => {
 const resolveEntry = (cwd: string, entry: string | undefined): string =>
     entry ? resolveGivenEntry(cwd, entry) : resolveDefaultEntry(cwd);
 
-export { cwdArg, entryArg, resolveCwd, resolveEntry };
+export { configArg, cwdArg, entryArg, resolveCwd, resolveEntry };

package/src/internal/icon-path.ts

@@ -1,5 +1,6 @@
-import { type Stats, statSync } from "node:fs";
-import { basename, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { isPathInside } from "@gtkx/utils";
+import { statSync } from "node:fs";
+import { basename, extname, isAbsolute, join, resolve } from "node:path";
 
 type ResolvedApplicationIcon = { kind: "file"; path: string } |
     { kind: "none" } |
@@ -10,20 +11,6 @@ const SCALABLE_DIR = "hicolor/scalable/apps";
 const SIZE_PATTERN = /^(?<width>[1-9]\d{0,3})x(?<height>[1-9]\d{0,3})$/;
 const SIZE_SEPARATORS = /[-_.]/;
 
-const isInside = (parent: string, candidate: string): boolean => {
-    const rel = relative(parent, candidate);
-
-    return rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel);
-};
-
-const getStats = (path: string): Stats | undefined => {
-    try {
-        return statSync(path, { throwIfNoEntry: false });
-    } catch {
-        return undefined;
-    }
-};
-
 const iconExtension = (file: string): string => {
     const extension = extname(file).toLowerCase();
 
@@ -37,7 +24,7 @@ const iconExtension = (file: string): string => {
 const defaultIconFiles = (root: string, applicationId: string): string[] =>
     [...ICON_EXTENSIONS]
         .map((extension) => join(root, `${applicationId}${extension}`))
-        .filter((path) => getStats(path)?.isFile() === true);
+        .filter((path) => statSync(path, { throwIfNoEntry: false })?.isFile() === true);
 
 const resolveDefaultApplicationIcon = (root: string, applicationId: string): ResolvedApplicationIcon => {
     const files = defaultIconFiles(root, applicationId);
@@ -76,11 +63,11 @@ const resolveApplicationIcon = (
 
     const path = resolve(root, configured);
 
-    if (!isInside(root, path)) {
+    if (!isPathInside(root, path)) {
         throw new Error(`Cannot use "${configured}" as the application icon: it is outside ${root}`);
     }
 
-    const stats = getStats(path);
+    const stats = statSync(path, { throwIfNoEntry: false });
 
     if (stats?.isDirectory() === true) {
         return { kind: "theme", path };