@gtkx/cli 2.0.0-beta.4 → 2.0.0-beta.5

package/src/deploy/freedesktop/validate.ts

@@ -6,6 +6,12 @@ type ToolResult = {
     status: number;
 };
 
+type Diagnostic = {
+    severity: string;
+    rule: string;
+    detail: string;
+};
+
 type MetainfoResult = {
     subject: string;
     output: string;
@@ -13,6 +19,7 @@ type MetainfoResult = {
     errors: string[];
     warnings: string[];
     rules: string[];
+    notes: string[];
     areWarningsFatal: boolean;
 };
 
@@ -22,12 +29,19 @@ type ToolRequest = {
     subject: string;
 };
 
-const DIAGNOSTIC = /^(?<severity>[EIPW]): \S+ (?<rule>[\w-]+)/;
+const DIAGNOSTIC = /^(?<severity>[EIPW]): \S+ (?<rule>[\w-]+)(?: (?<detail>.*))?$/;
+const SUCCESS_SUMMARY = /^\W*Validation was successful/u;
 const ERROR_SEVERITY = "E";
 const WARNING_SEVERITY = "W";
 const INFO_SEVERITY = "I";
 const FATAL_WARNING_RULES: Set<string> = new Set(["unknown-tag"]);
 
+const FATAL_RULE_NOTES: Record<string, (detail: string) => string> = {
+    "unknown-tag": (element) =>
+        "GTKX treats unknown-tag as fatal for every target, whatever severity appstreamcli assigns it; " +
+        `the unsupported element is <${element}>`,
+};
+
 const REMEDY_FOR_RULE: Record<string, string> = {
     "component-summary-missing": "set `deploy.summary`",
     "description-first-para-too-short": "open `deploy.description` with a paragraph longer than 80 characters",
@@ -49,12 +63,31 @@ const runTool = ({ tool, args, subject }: ToolRequest): ToolResult => {
     return { output: [result.stdout, result.stderr].join("\n").trim(), status: result.status ?? 0 };
 };
 
-const rulesIn = (output: string, severities: string[]): string[] =>
+const parseDiagnostics = (output: string): Diagnostic[] =>
+    output.split("\n").flatMap((line) => {
+        const groups = DIAGNOSTIC.exec(line)?.groups;
+
+        return groups === undefined
+            ? []
+            : [{ severity: groups.severity ?? "", rule: groups.rule ?? "", detail: (groups.detail ?? "").trim() }];
+    });
+
+const rulesIn = (diagnostics: Diagnostic[], severities: string[]): string[] =>
+    diagnostics.filter((diagnostic) => severities.includes(diagnostic.severity)).map((diagnostic) => diagnostic.rule);
+
+const fatalNotes = (diagnostics: Diagnostic[]): string[] =>
+    diagnostics
+        .filter((diagnostic) => diagnostic.severity !== ERROR_SEVERITY && FATAL_WARNING_RULES.has(diagnostic.rule))
+        .map((diagnostic) =>
+            FATAL_RULE_NOTES[diagnostic.rule]?.(diagnostic.detail) ??
+            `GTKX treats ${diagnostic.rule} as fatal for every target`);
+
+const withoutSuccessSummary = (output: string): string =>
     output
         .split("\n")
-        .map((line) => DIAGNOSTIC.exec(line)?.groups)
-        .filter((groups) => groups !== undefined && severities.includes(groups.severity ?? ""))
-        .map((groups) => groups?.rule ?? "");
+        .filter((line) => !SUCCESS_SUMMARY.test(line))
+        .join("\n")
+        .trimEnd();
 
 const remedyLines = (rules: string[]): string[] => {
     const remedies = sortStrings([...new Set(rules)])
@@ -64,8 +97,13 @@ const remedyLines = (rules: string[]): string[] => {
     return remedies.length === 0 ? [] : ["", "Fix it in gtkx.config.ts:", ...remedies];
 };
 
-const invalid = (subject: string, output: string, rules: string[]): Error =>
-    new Error([`${subject} is not valid:`, output.length > 0 ? output : "no output", ...remedyLines(rules)].join("\n"));
+const invalid = (subject: string, output: string, rules: string[], notes: string[]): Error =>
+    new Error([
+        `${subject} is not valid:`,
+        output.length > 0 ? output : "no output",
+        ...notes,
+        ...remedyLines(rules),
+    ].join("\n"));
 
 const isFatalResult = ({ status, errors, warnings, rules, areWarningsFatal }: MetainfoResult): boolean => {
     if (errors.length > 0) {
@@ -85,7 +123,7 @@ const isFatalResult = ({ status, errors, warnings, rules, areWarningsFatal }: Me
 
 const assertNotFatal = (result: MetainfoResult): void => {
     if (isFatalResult(result)) {
-        throw invalid(result.subject, result.output, result.rules);
+        throw invalid(result.subject, result.output, result.rules, result.notes);
     }
 };
 
@@ -109,7 +147,7 @@ const validateDesktopEntry = (path: string): void => {
     });
 
     if (status !== 0 || output.length > 0) {
-        throw invalid("The desktop entry", output, []);
+        throw invalid("The desktop entry", output, [], []);
     }
 };
 
@@ -122,11 +160,22 @@ const validateMetainfo = (path: string, areWarningsFatal: boolean): void => {
         subject,
     });
 
-    const errors = rulesIn(output, [ERROR_SEVERITY]);
-    const warnings = rulesIn(output, [WARNING_SEVERITY]);
-    const infos = rulesIn(output, [INFO_SEVERITY]);
+    const diagnostics = parseDiagnostics(output);
+    const errors = rulesIn(diagnostics, [ERROR_SEVERITY]);
+    const warnings = rulesIn(diagnostics, [WARNING_SEVERITY]);
+    const infos = rulesIn(diagnostics, [INFO_SEVERITY]);
     const rules = [...errors, ...warnings, ...infos];
-    assertNotFatal({ subject, output, status, errors, warnings, rules, areWarningsFatal });
+    const notes = fatalNotes(diagnostics);
+    assertNotFatal({
+        subject,
+        output: withoutSuccessSummary(output),
+        status,
+        errors,
+        warnings,
+        rules,
+        notes,
+        areWarningsFatal,
+    });
     reportDiagnostics(subject, [...warnings, ...infos]);
 };
 

package/src/dev/catalog-writes.ts

@@ -0,0 +1,35 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { WrittenCatalog } from "../i18n/catalogs.js";
+
+type CatalogWrites = {
+    record: (catalogs: WrittenCatalog[]) => void;
+    hasWritten: (path: string) => boolean;
+};
+
+const hasContent = (path: string, content: Buffer): boolean => {
+    try {
+        return readFileSync(path).equals(content);
+    } catch {
+        return false;
+    }
+};
+
+const createCatalogWrites = (): CatalogWrites => {
+    const contents: Map<string, Buffer> = new Map();
+
+    return {
+        record: (catalogs) => {
+            for (const catalog of catalogs) {
+                contents.set(resolve(catalog.path), catalog.content);
+            }
+        },
+        hasWritten: (path) => {
+            const content = contents.get(resolve(path));
+
+            return content !== undefined && hasContent(path, content);
+        },
+    };
+};
+
+export { type CatalogWrites, createCatalogWrites };

package/src/dev/runner-deps.ts

@@ -17,6 +17,7 @@ import { isRefreshBoundary, performRefresh, staleExportName } from "../refresh-r
 import { gtkxFastRefresh } from "../vite-plugins/fast-refresh/swc-refresh.js";
 import { gtkxVitePlugins } from "../vite-plugins/index.js";
 import { gtkxReactDomPrebundle } from "../vite-plugins/react-dom-prebundle.js";
+import { type CatalogWrites, createCatalogWrites } from "./catalog-writes.js";
 
 const DEV_MODE = "development";
 const APPLICATION_POLL_INTERVAL_MS = 50;
@@ -43,7 +44,14 @@ const waitForApplicationId = async (timeoutMs: number, shouldKeepWaiting: () =>
 
 const readFileRevision = (path: string): Promise<string> => readFile(path, "utf8");
 
-const defaultDevRunnerDeps = (configFile: string): DevRunnerDeps => ({
+const devPlugins = (configFile: string, catalogWrites: CatalogWrites): DevRunnerDeps["plugins"] =>
+    (entryPath) => [
+        ...gtkxVitePlugins({ mode: DEV_MODE, entryPath, configFile, onCatalogsWritten: catalogWrites.record }),
+        ...gtkxFastRefresh(),
+        gtkxReactDomPrebundle(),
+    ];
+
+const createDevRunnerDeps = (configFile: string, catalogWrites: CatalogWrites): DevRunnerDeps => ({
     createServer,
     waitForApplicationId,
     getConfiguredApplicationId: async (root: string) => {
@@ -86,13 +94,13 @@ const defaultDevRunnerDeps = (configFile: string): DevRunnerDeps => ({
     isRefreshBoundary,
     staleExportName,
     readFileRevision,
-    plugins: (entryPath) => [
-        ...gtkxVitePlugins({ mode: DEV_MODE, entryPath, configFile }),
-        ...gtkxFastRefresh(),
-        gtkxReactDomPrebundle(),
-    ],
+    hasWrittenCatalog: catalogWrites.hasWritten,
+    plugins: devPlugins(configFile, catalogWrites),
     log: info,
     exit: (code: number): never => process.exit(code),
 });
 
+const defaultDevRunnerDeps = (configFile: string): DevRunnerDeps =>
+    createDevRunnerDeps(configFile, createCatalogWrites());
+
 export { defaultDevRunnerDeps };

package/src/dev/runner.ts

@@ -33,6 +33,7 @@ type DevRunnerDeps = {
     isRefreshBoundary(module: Record<string, unknown>): boolean;
     staleExportName(previous: Record<string, unknown>, current: Record<string, unknown>): string | null;
     readFileRevision(path: string): Promise<string>;
+    hasWrittenCatalog(path: string): boolean;
     plugins(entryPath: string): Plugin[];
     log(message: string): void;
     exit(code: number): never;
@@ -370,14 +371,22 @@ const restartForServerConfig = async (session: DevSession, changedPath: string):
     await requestRestart(session);
 };
 
+const restartForCatalog = async (session: DevSession, changedPath: string): Promise<void> => {
+    if (session.deps.hasWrittenCatalog(changedPath)) {
+        return;
+    }
+
+    session.deps.log(`Translation catalog changed: ${changedPath}`);
+    await requestRestart(session);
+};
+
 const applyChange = async (session: DevSession, change: WatchedChange): Promise<void> => {
     if (session.controller.isShuttingDown()) {
         return;
     }
 
     if (isCatalogSource(session.server.config.root, change.path)) {
-        session.deps.log(`Translation catalog changed: ${change.path}`);
-        await requestRestart(session);
+        await restartForCatalog(session, change.path);
 
         return;
     }

package/src/dev/supervisor.ts

@@ -1,7 +1,7 @@
 import { error, exitCodeForSignal, info, installGracefulShutdown } from "@gtkx/utils";
 import { fork as nodeFork } from "node:child_process";
 import { type FSWatcher, statSync, watch as watchFs } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { DEV_CONFIG_ENV, DEV_ENTRY_ENV } from "./entry-env.js";
 
@@ -30,6 +30,7 @@ type SupervisorState = {
     args: string[];
     watch: DevWatch | undefined;
     watchers: FSWatcher[];
+    changedPaths: Set<string>;
     restartTimer: DebounceTimer;
     fork: ForkRunner;
     child: SupervisedChild | null;
@@ -174,7 +175,7 @@ const reconcileConfigWatchers = (
     paths: string[],
     previous: ReadonlyMap<string, string | null>,
 ): void => {
-    const didChange = didWatchPathsChange(previous, paths);
+    const changed = changedWatchPaths(previous, paths);
 
     closeWatchers(state);
 
@@ -188,11 +189,18 @@ const reconcileConfigWatchers = (
 
     installConfigWatchers(state);
 
-    if (didChange && !state.isRestartPending) {
-        scheduleRestart(state);
+    if (changed.length > 0 && !state.isRestartPending) {
+        scheduleRestart(state, changed);
     }
 };
 
+const consumeChangedPaths = (state: SupervisorState): string => {
+    const changed = [...state.changedPaths].map((path) => relative(state.cwd, path));
+    state.changedPaths.clear();
+
+    return changed.length === 0 ? basename(state.configFile) : changed.join(", ");
+};
+
 const restart = async (state: SupervisorState): Promise<void> => {
     const watch = state.watch;
 
@@ -207,7 +215,7 @@ const restart = async (state: SupervisorState): Promise<void> => {
     }
 
     state.isRestarting = true;
-    info(`${basename(state.configFile)} changed; regenerating bindings...`);
+    info(`${consumeChangedPaths(state)} changed; regenerating bindings...`);
     closeWatchers(state);
     watch.paths = watch.resolvePaths();
     const previous = snapshotWatchPaths(watch.paths);
@@ -246,9 +254,13 @@ const restart = async (state: SupervisorState): Promise<void> => {
     forwardSignal(current, "SIGTERM");
 };
 
-const scheduleRestart = (state: SupervisorState): void => {
+const scheduleRestart = (state: SupervisorState, changedPaths: string[] = []): void => {
     const timer = state.restartTimer;
 
+    for (const path of changedPaths) {
+        state.changedPaths.add(path);
+    }
+
     if (timer.handle !== null) {
         clearTimeout(timer.handle);
     }
@@ -259,12 +271,19 @@ const scheduleRestart = (state: SupervisorState): void => {
     }, CONFIG_DEBOUNCE_MS);
 };
 
-const isWatchedChange = (state: SupervisorState, names: Set<string>, filename: string | Buffer | null): boolean => {
+const watchedChangePath = (
+    state: SupervisorState,
+    directory: string,
+    names: Set<string>,
+    filename: string | Buffer | null,
+): string | undefined => {
     if (filename === null || state.isShuttingDown) {
-        return false;
+        return undefined;
     }
 
-    return names.has(basename(filename.toString()));
+    const name = basename(filename.toString());
+
+    return names.has(name) ? join(directory, name) : undefined;
 };
 
 const isDirectory = (path: string): boolean => {
@@ -315,20 +334,15 @@ const watchPathState = (path: string): string | null => {
 const snapshotWatchPaths = (paths: string[]): Map<string, string | null> =>
     new Map([...watchTargets(paths)].map((path) => [path, watchPathState(path)]));
 
-const didWatchPathsChange = (
+const changedWatchPaths = (
     previous: ReadonlyMap<string, string | null>,
     paths: string[],
-): boolean => {
-    for (const path of watchTargets(paths)) {
+): string[] =>
+    [...watchTargets(paths)].filter((path) => {
         const current = watchPathState(path);
 
-        if (previous.has(path) ? previous.get(path) !== current : current !== null) {
-            return true;
-        }
-    }
-
-    return false;
-};
+        return previous.has(path) ? previous.get(path) !== current : current !== null;
+    });
 
 const groupWatchNamesByDirectory = (paths: string[]): Map<string, Set<string>> => {
     const namesByDirectory: Map<string, Set<string>> = new Map();
@@ -350,8 +364,10 @@ const watchConfigDirectory = (
 ): void => {
     try {
         const watcher = watchFs(directory, (_event, filename) => {
-            if (isWatchedChange(state, names, filename)) {
-                scheduleRestart(state);
+            const changed = watchedChangePath(state, directory, names, filename);
+
+            if (changed !== undefined) {
+                scheduleRestart(state, [changed]);
             }
         });
 
@@ -427,6 +443,7 @@ const runDevSupervisor = async (options: DevSupervisorOptions): Promise<never> =
         args,
         watch,
         watchers: [],
+        changedPaths: new Set(),
         restartTimer: { handle: null },
         fork,
         child: null,

package/src/i18n/catalogs.ts

@@ -28,11 +28,17 @@ type CatalogProject = {
 };
 
 type PreparedCatalog = {
+    content: Buffer;
     isChanged: boolean;
     output: string;
     target: string;
 };
 
+type WrittenCatalog = {
+    content: Buffer;
+    path: string;
+};
+
 const PO_DIRNAME = "po";
 const LOCALE_DIRNAME = "locale";
 const LINGUAS_FILENAME = "LINGUAS";
@@ -165,16 +171,25 @@ const prepareCatalog = (
         initializeCatalog(catalog, template, output);
     }
 
+    const content = readFileSync(output);
+
     return {
-        isChanged: !isExisting || !readFileSync(output).equals(readFileSync(catalog.path)),
+        content,
+        isChanged: !isExisting || !content.equals(readFileSync(catalog.path)),
         output,
         target: catalog.path,
     };
 };
 
-const synchronizeCatalogs = (project: CatalogProject): void => {
+const replaceCatalog = (catalog: PreparedCatalog): WrittenCatalog => {
+    renameSync(catalog.output, catalog.target);
+
+    return { content: catalog.content, path: catalog.target };
+};
+
+const synchronizeCatalogs = (project: CatalogProject): WrittenCatalog[] => {
     if (project.catalogs.length === 0) {
-        return;
+        return [];
     }
 
     const template = join(project.poDir, `${project.domain}.pot`);
@@ -185,11 +200,7 @@ const synchronizeCatalogs = (project: CatalogProject): void => {
         const merged = project.catalogs.map((catalog, index) =>
             prepareCatalog(catalog, index, template, stagingDir));
 
-        for (const catalog of merged) {
-            if (catalog.isChanged) {
-                renameSync(catalog.output, catalog.target);
-            }
-        }
+        return merged.filter((catalog) => catalog.isChanged).map((catalog) => replaceCatalog(catalog));
     } finally {
         rmSync(stagingDir, { recursive: true, force: true });
     }
@@ -215,4 +226,5 @@ export {
     requiresCatalogInitialization,
     resolveCatalogProject,
     synchronizeCatalogs,
+    type WrittenCatalog,
 };

package/src/vite-plugins/i18n.ts

@@ -11,12 +11,23 @@ import {
     LOCALE_DIRNAME,
     resolveCatalogProject,
     synchronizeCatalogs,
+    type WrittenCatalog,
 } from "../i18n/catalogs.js";
 import { extractSourceCatalog, SourceExtractionError } from "../i18n/source-messages.js";
 import { emitI18nTypes } from "../i18n/types.js";
 import { discoverSourceFiles, sourceLanguage } from "../internal/source-imports.js";
 import { stripQuery } from "./strip-query.js";
 
+type CatalogWriteListener = (catalogs: WrittenCatalog[]) => void;
+
+type I18nPluginOptions = {
+    entryPath: string;
+    loadConfig?: ConfigLoader | undefined;
+    onCatalogsWritten?: CatalogWriteListener | undefined;
+    shouldPreserveMetadataMessages?: boolean | undefined;
+    shouldRecoverExtractionErrors?: boolean | undefined;
+};
+
 type I18nState = {
     entryPath: string;
     i18nRoot: string;
@@ -24,6 +35,7 @@ type I18nState = {
     project: CatalogProject | null;
     extraction: Promise<void>;
     hotUpdateTimestamp: number | null;
+    onCatalogsWritten: CatalogWriteListener;
 };
 
 const BOOTSTRAP_SPECIFIER = "@gtkx/i18n/bootstrap";
@@ -110,7 +122,7 @@ const extractProjectMessages = async (
     await extractSourceCatalog(project, sourceFiles, shouldPreserveMetadataMessages);
 
     if (shouldSynchronizeCatalogs) {
-        synchronizeCatalogs(project);
+        state.onCatalogsWritten(synchronizeCatalogs(project));
     }
 
     await emitI18nTypes(project.root);
@@ -184,12 +196,13 @@ const recoverInitialSourceExtraction = async (
     }
 };
 
-const gtkxI18n = (
-    entryPath: string,
-    loadConfig: ConfigLoader = createConfigLoader(),
+const gtkxI18n = ({
+    entryPath,
+    loadConfig = createConfigLoader(),
+    onCatalogsWritten = (): void => undefined,
     shouldPreserveMetadataMessages = true,
     shouldRecoverExtractionErrors = false,
-): Plugin => {
+}: I18nPluginOptions): Plugin => {
     const state: I18nState = {
         entryPath,
         extraction: Promise.resolve(),
@@ -197,6 +210,7 @@ const gtkxI18n = (
         i18nRoot: "",
         outDir: "",
         project: null,
+        onCatalogsWritten,
     };
 
     return {
@@ -241,4 +255,4 @@ const gtkxI18n = (
     };
 };
 
-export { gtkxI18n };
+export { type CatalogWriteListener, gtkxI18n };

package/src/vite-plugins/index.ts

@@ -5,7 +5,7 @@ import type { BuildManifestCollector } from "../internal/build-manifest.js";
 import { gtkxAssetImports } from "./asset-imports.js";
 import { gtkxBuiltUrl } from "./built-url.js";
 import { gtkxCss } from "./css.js";
-import { gtkxI18n } from "./i18n.js";
+import { type CatalogWriteListener, gtkxI18n } from "./i18n.js";
 import { gtkxIcons } from "./icons.js";
 import { gtkxReactCompiler } from "./react-compiler.js";
 import { gtkxResources } from "./resources.js";
@@ -18,11 +18,19 @@ type GtkxVitePluginOptions = {
     configFile?: string | undefined;
     entryPath?: string | undefined;
     mode?: string | undefined;
+    onCatalogsWritten?: CatalogWriteListener | undefined;
     shouldPreserveI18nMetadata?: boolean | undefined;
 };
 
 const gtkxVitePlugins = (options: GtkxVitePluginOptions = {}): Plugin[] => {
-    const { buildManifest, configFile, entryPath, mode, shouldPreserveI18nMetadata = true } = options;
+    const {
+        buildManifest,
+        configFile,
+        entryPath,
+        mode,
+        onCatalogsWritten,
+        shouldPreserveI18nMetadata = true,
+    } = options;
     const loadConfig = createConfigLoader({
         ...(mode !== undefined && { mode }),
         ...(configFile !== undefined && { configFile }),
@@ -32,12 +40,13 @@ const gtkxVitePlugins = (options: GtkxVitePluginOptions = {}): Plugin[] => {
         createConfigPlugin({ name: "gtkx:config", loadConfig }),
         ...(entryPath === undefined
             ? []
-            : [gtkxI18n(
+            : [gtkxI18n({
                     entryPath,
                     loadConfig,
-                    shouldPreserveI18nMetadata,
-                    mode === "development",
-                )]),
+                    onCatalogsWritten,
+                    shouldPreserveMetadataMessages: shouldPreserveI18nMetadata,
+                    shouldRecoverExtractionErrors: mode === "development",
+                })]),
         gtkxStoreLinks(),
         gtkxUndeclaredLibrary(loadConfig),
         gtkxSettings(buildManifest),