@saykit/config 0.3.0 → 0.4.0

package/README.md

@@ -43,7 +43,7 @@ export default defineConfig({
 ```sh
 saykit extract           # extract messages once
 saykit extract --watch   # extract and watch for changes
-saykit clean             # reconcile other locales against the source
+saykit clean             # prune dead entries from other locales
 ```
 
 Extraction only writes the **source** locale (the first entry in `locales`). Locales that don't
@@ -54,10 +54,9 @@ At load time (via the unplugin or Babel plugin), each locale module is filled fr
 chain, so an untranslated key resolves to a fallback locale and ultimately the source string — the
 runtime still loads a single locale.
 
-`saykit clean` reconciles every non-source locale against the current source catalogue: it adds
-missing keys (untranslated), drops entries that no longer exist in the source, and preserves any
-existing translations. Use it when you want to propagate source changes into locale files yourself
-rather than leaving it to your TMS.
+`saykit clean` only ever subtracts from non-source locales: it drops entries that no longer exist in
+the source catalogue and entries with an empty translation, and leaves everything else exactly as it
+is. It never adds source keys to a locale file, that stays your TMS's job.
 
 ## Documentation
 

package/dist/commands/index.cjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 require("../index.cjs");
-const require_storage = require("../storage-3BTY8yws.cjs");
+const require_storage = require("../storage-C4rOvLGi.cjs");
 const require_loader = require("../loader-B25O-vF6.cjs");
 let _commander_js_extra_typings = require("@commander-js/extra-typings");
 let node_fs_promises = require("node:fs/promises");
@@ -46,17 +46,20 @@ var Logger = class {
 new node_async_hooks.AsyncLocalStorage({ defaultValue: new Logger() });
 //#endregion
 //#region src/commands/clean.ts
-var clean_default = new _commander_js_extra_typings.Command("clean").description("Reconcile non-source locale files against the source locale").option("-v, --verbose", "enable verbose logging", false).option("-q, --quiet", "suppress all logging", false).action(async (options) => {
+var clean_default = new _commander_js_extra_typings.Command("clean").description("Remove orphaned and untranslated entries from non-source locale files").option("-v, --verbose", "enable verbose logging", false).option("-q, --quiet", "suppress all logging", false).action(async (options) => {
 	const config = require_loader.resolveConfig();
 	const logger = new Logger(options);
 	logger.header("🧹 Cleaning Locales");
 	const [sourceLocale, ...otherLocales] = config.locales;
 	for (const bucket of config.buckets) {
 		const sourceMessages = await require_storage.readCatalogueMessages(bucket, sourceLocale);
-		logger.info(`Reconciling ${otherLocales.length} locale(s) against ${sourceLocale}`);
+		logger.info(`Cleaning ${otherLocales.length} locale(s) against ${sourceLocale}`);
 		for (const locale of otherLocales) {
-			logger.step(`Reconciling ${locale}`);
-			await require_storage.writeCatalogueMessages(bucket, locale, require_storage.reconcileLocaleMessages(await require_storage.readCatalogueMessages(bucket, locale), sourceMessages));
+			logger.step(`Cleaning ${locale}`);
+			const existingMessages = await require_storage.readCatalogueMessages(bucket, locale);
+			const prunedMessages = require_storage.pruneLocaleMessages(existingMessages, sourceMessages);
+			logger.step(`Removed ${existingMessages.length - prunedMessages.length} entries from ${locale}`);
+			await require_storage.writeCatalogueMessages(bucket, locale, prunedMessages);
 		}
 	}
 	logger.success("Locales cleaned");

package/dist/commands/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as reconcileLocaleMessages, i as mergeExtractedMessages, n as writeCatalogueMessages, r as expandBucketOutputPath, t as readCatalogueMessages } from "../storage-C9nzxPtZ.mjs";
+import { a as mergeExtractedMessages, i as expandBucketOutputPath, n as writeCatalogueMessages, o as pruneLocaleMessages, t as readCatalogueMessages } from "../storage-CqKPYfCR.mjs";
 import { t as resolveConfig } from "../loader-C2eolE_1.mjs";
 import { Command, program } from "@commander-js/extra-typings";
 import { access, glob, readFile, watch } from "node:fs/promises";
@@ -45,17 +45,20 @@ var Logger = class {
 new AsyncLocalStorage({ defaultValue: new Logger() });
 //#endregion
 //#region src/commands/clean.ts
-var clean_default = new Command("clean").description("Reconcile non-source locale files against the source locale").option("-v, --verbose", "enable verbose logging", false).option("-q, --quiet", "suppress all logging", false).action(async (options) => {
+var clean_default = new Command("clean").description("Remove orphaned and untranslated entries from non-source locale files").option("-v, --verbose", "enable verbose logging", false).option("-q, --quiet", "suppress all logging", false).action(async (options) => {
 	const config = resolveConfig();
 	const logger = new Logger(options);
 	logger.header("🧹 Cleaning Locales");
 	const [sourceLocale, ...otherLocales] = config.locales;
 	for (const bucket of config.buckets) {
 		const sourceMessages = await readCatalogueMessages(bucket, sourceLocale);
-		logger.info(`Reconciling ${otherLocales.length} locale(s) against ${sourceLocale}`);
+		logger.info(`Cleaning ${otherLocales.length} locale(s) against ${sourceLocale}`);
 		for (const locale of otherLocales) {
-			logger.step(`Reconciling ${locale}`);
-			await writeCatalogueMessages(bucket, locale, reconcileLocaleMessages(await readCatalogueMessages(bucket, locale), sourceMessages));
+			logger.step(`Cleaning ${locale}`);
+			const existingMessages = await readCatalogueMessages(bucket, locale);
+			const prunedMessages = pruneLocaleMessages(existingMessages, sourceMessages);
+			logger.step(`Removed ${existingMessages.length - prunedMessages.length} entries from ${locale}`);
+			await writeCatalogueMessages(bucket, locale, prunedMessages);
 		}
 	}
 	logger.success("Locales cleaned");

package/dist/features/catalogue/index.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../index.cjs");
 const require_hash = require("../../hash-8It7TJpB.cjs");
-const require_storage = require("../../storage-3BTY8yws.cjs");
+const require_storage = require("../../storage-C4rOvLGi.cjs");
 let node_path = require("node:path");
 //#region src/features/catalogue/record.ts
 /**
@@ -44,17 +44,22 @@ function assembleCatalogueRecord(bucket, contents) {
 		if (!content) continue;
 		for (const message of bucket.formatter.parse(content)) {
 			const key = message.id || require_hash.generateHash(message.message, message.context);
-			record[key] = message.translation || message.message;
+			if (message.translation) {
+				record[key] = message.translation;
+				continue;
+			}
+			if (!record[key] && message.message) record[key] = message.message;
 		}
 	}
 	return record;
 }
 //#endregion
 exports.assembleCatalogueRecord = assembleCatalogueRecord;
+exports.declarationPathFor = require_storage.declarationPathFor;
 exports.expandBucketOutputPath = require_storage.expandBucketOutputPath;
 exports.mergeExtractedMessages = require_storage.mergeExtractedMessages;
+exports.pruneLocaleMessages = require_storage.pruneLocaleMessages;
 exports.readCatalogueMessages = require_storage.readCatalogueMessages;
-exports.reconcileLocaleMessages = require_storage.reconcileLocaleMessages;
 exports.resolveCatalogueSources = resolveCatalogueSources;
 exports.resolveFallbackChain = resolveFallbackChain;
 exports.writeCatalogueMessages = require_storage.writeCatalogueMessages;

package/dist/features/catalogue/index.d.cts

@@ -9,7 +9,7 @@ declare function mergeExtractedMessages(messages: Message[]): {
   id?: string | undefined;
   context?: string | undefined;
 }[];
-declare function reconcileLocaleMessages(existingMessages: Message[], nextMessages: Message[]): {
+declare function pruneLocaleMessages(existingMessages: Message[], sourceMessages: Message[]): {
   message: string;
   comments: string[];
   references: string[];
@@ -20,6 +20,15 @@ declare function reconcileLocaleMessages(existingMessages: Message[], nextMessag
 //#endregion
 //#region src/features/catalogue/path.d.ts
 declare function expandBucketOutputPath(bucket: Bucket, locale: string, extension?: `.${string}`): string;
+/**
+ * The declaration file that types a catalogue, e.g. `en.json` -> `en.d.json.ts`.
+ *
+ * TypeScript resolves `./en.json` by stripping the extension and looking for
+ * `en.d.json.ts`; the `en.json.d.ts` form is only consulted for extensions the
+ * resolver does not recognise. Non-JS extensions additionally require
+ * `allowArbitraryExtensions` in the consumer's tsconfig.
+ */
+declare function declarationPathFor(cataloguePath: string): string;
 //#endregion
 //#region src/features/catalogue/record.d.ts
 /**
@@ -56,4 +65,4 @@ declare function readCatalogueMessages(bucket: Bucket, locale: string, path?: st
 }[]>;
 declare function writeCatalogueMessages(bucket: Bucket, locale: string, messages: Message[], path?: string): Promise<void>;
 //#endregion
-export { assembleCatalogueRecord, expandBucketOutputPath, mergeExtractedMessages, readCatalogueMessages, reconcileLocaleMessages, resolveCatalogueSources, resolveFallbackChain, writeCatalogueMessages };
+export { assembleCatalogueRecord, declarationPathFor, expandBucketOutputPath, mergeExtractedMessages, pruneLocaleMessages, readCatalogueMessages, resolveCatalogueSources, resolveFallbackChain, writeCatalogueMessages };

package/dist/features/catalogue/index.d.mts

@@ -9,7 +9,7 @@ declare function mergeExtractedMessages(messages: Message[]): {
   id?: string | undefined;
   context?: string | undefined;
 }[];
-declare function reconcileLocaleMessages(existingMessages: Message[], nextMessages: Message[]): {
+declare function pruneLocaleMessages(existingMessages: Message[], sourceMessages: Message[]): {
   message: string;
   comments: string[];
   references: string[];
@@ -20,6 +20,15 @@ declare function reconcileLocaleMessages(existingMessages: Message[], nextMessag
 //#endregion
 //#region src/features/catalogue/path.d.ts
 declare function expandBucketOutputPath(bucket: Bucket, locale: string, extension?: `.${string}`): string;
+/**
+ * The declaration file that types a catalogue, e.g. `en.json` -> `en.d.json.ts`.
+ *
+ * TypeScript resolves `./en.json` by stripping the extension and looking for
+ * `en.d.json.ts`; the `en.json.d.ts` form is only consulted for extensions the
+ * resolver does not recognise. Non-JS extensions additionally require
+ * `allowArbitraryExtensions` in the consumer's tsconfig.
+ */
+declare function declarationPathFor(cataloguePath: string): string;
 //#endregion
 //#region src/features/catalogue/record.d.ts
 /**
@@ -56,4 +65,4 @@ declare function readCatalogueMessages(bucket: Bucket, locale: string, path?: st
 }[]>;
 declare function writeCatalogueMessages(bucket: Bucket, locale: string, messages: Message[], path?: string): Promise<void>;
 //#endregion
-export { assembleCatalogueRecord, expandBucketOutputPath, mergeExtractedMessages, readCatalogueMessages, reconcileLocaleMessages, resolveCatalogueSources, resolveFallbackChain, writeCatalogueMessages };
+export { assembleCatalogueRecord, declarationPathFor, expandBucketOutputPath, mergeExtractedMessages, pruneLocaleMessages, readCatalogueMessages, resolveCatalogueSources, resolveFallbackChain, writeCatalogueMessages };

package/dist/features/catalogue/index.mjs

@@ -1,5 +1,5 @@
 import { t as generateHash } from "../../hash-DyC8GzMa.mjs";
-import { a as reconcileLocaleMessages, i as mergeExtractedMessages, n as writeCatalogueMessages, r as expandBucketOutputPath, t as readCatalogueMessages } from "../../storage-C9nzxPtZ.mjs";
+import { a as mergeExtractedMessages, i as expandBucketOutputPath, n as writeCatalogueMessages, o as pruneLocaleMessages, r as declarationPathFor, t as readCatalogueMessages } from "../../storage-CqKPYfCR.mjs";
 import { resolve } from "node:path";
 //#region src/features/catalogue/record.ts
 /**
@@ -42,10 +42,14 @@ function assembleCatalogueRecord(bucket, contents) {
 		if (!content) continue;
 		for (const message of bucket.formatter.parse(content)) {
 			const key = message.id || generateHash(message.message, message.context);
-			record[key] = message.translation || message.message;
+			if (message.translation) {
+				record[key] = message.translation;
+				continue;
+			}
+			if (!record[key] && message.message) record[key] = message.message;
 		}
 	}
 	return record;
 }
 //#endregion
-export { assembleCatalogueRecord, expandBucketOutputPath, mergeExtractedMessages, readCatalogueMessages, reconcileLocaleMessages, resolveCatalogueSources, resolveFallbackChain, writeCatalogueMessages };
+export { assembleCatalogueRecord, declarationPathFor, expandBucketOutputPath, mergeExtractedMessages, pruneLocaleMessages, readCatalogueMessages, resolveCatalogueSources, resolveFallbackChain, writeCatalogueMessages };

package/dist/{storage-3BTY8yws.cjs → storage-C4rOvLGi.cjs}

@@ -22,33 +22,33 @@ function mergeExtractedMessages(messages) {
 	}, /* @__PURE__ */ new Map());
 	return Array.from(mergedMessages.values());
 }
-function reconcileLocaleMessages(existingMessages, nextMessages) {
-	const existingMessagesByKey = existingMessages.reduce((map, message) => {
-		map.set(getMessageKey(message), message);
-		return map;
-	}, /* @__PURE__ */ new Map());
-	const reconciledMessages = nextMessages.reduce((map, message) => {
-		const key = getMessageKey(message);
-		const existingMessage = existingMessagesByKey.get(key);
-		map.set(key, {
-			...message,
-			translation: existingMessage?.translation
-		});
-		return map;
-	}, /* @__PURE__ */ new Map());
-	return Array.from(reconciledMessages.values());
+function pruneLocaleMessages(existingMessages, sourceMessages) {
+	const sourceKeys = new Set(sourceMessages.map(getMessageKey));
+	return existingMessages.filter((message) => sourceKeys.has(getMessageKey(message)) && Boolean(message.translation));
 }
 //#endregion
 //#region src/features/catalogue/path.ts
 function expandBucketOutputPath(bucket, locale, extension = bucket.formatter.extension) {
 	return (0, node_path.resolve)(bucket.output.replaceAll("{locale}", locale).replaceAll("{extension}", extension.slice(1)));
 }
+/**
+* The declaration file that types a catalogue, e.g. `en.json` -> `en.d.json.ts`.
+*
+* TypeScript resolves `./en.json` by stripping the extension and looking for
+* `en.d.json.ts`; the `en.json.d.ts` form is only consulted for extensions the
+* resolver does not recognise. Non-JS extensions additionally require
+* `allowArbitraryExtensions` in the consumer's tsconfig.
+*/
+function declarationPathFor(cataloguePath) {
+	const { dir, name, ext } = (0, node_path.parse)(cataloguePath);
+	return (0, node_path.resolve)(dir, `${name}.d${ext}.ts`);
+}
 //#endregion
 //#region src/features/catalogue/storage.ts
 const DECLARATION_CONTENT = `
 declare const messages: Record<string, string>;
 export default messages;
-`.trim();
+`.trimStart();
 async function readCatalogueMessages(bucket, locale, path = expandBucketOutputPath(bucket, locale)) {
 	const content = await (0, node_fs_promises.readFile)(path, "utf8").catch(() => "");
 	if (!content) return [];
@@ -60,11 +60,17 @@ async function writeCatalogueMessages(bucket, locale, messages, path = expandBuc
 		locale,
 		existingContent
 	});
-	const declarationPath = `${path}.d.ts`;
+	const declarationPath = declarationPathFor(path);
 	await (0, node_fs_promises.mkdir)((0, node_path.dirname)(path), { recursive: true });
 	await Promise.all([(0, node_fs_promises.writeFile)(path, catalogueContent), (0, node_fs_promises.writeFile)(declarationPath, DECLARATION_CONTENT)]);
 }
 //#endregion
+Object.defineProperty(exports, "declarationPathFor", {
+	enumerable: true,
+	get: function() {
+		return declarationPathFor;
+	}
+});
 Object.defineProperty(exports, "expandBucketOutputPath", {
 	enumerable: true,
 	get: function() {
@@ -77,16 +83,16 @@ Object.defineProperty(exports, "mergeExtractedMessages", {
 		return mergeExtractedMessages;
 	}
 });
-Object.defineProperty(exports, "readCatalogueMessages", {
+Object.defineProperty(exports, "pruneLocaleMessages", {
 	enumerable: true,
 	get: function() {
-		return readCatalogueMessages;
+		return pruneLocaleMessages;
 	}
 });
-Object.defineProperty(exports, "reconcileLocaleMessages", {
+Object.defineProperty(exports, "readCatalogueMessages", {
 	enumerable: true,
 	get: function() {
-		return reconcileLocaleMessages;
+		return readCatalogueMessages;
 	}
 });
 Object.defineProperty(exports, "writeCatalogueMessages", {

package/dist/{storage-C9nzxPtZ.mjs → storage-CqKPYfCR.mjs}

@@ -1,6 +1,6 @@
 import { t as generateHash } from "./hash-DyC8GzMa.mjs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { dirname, parse, resolve } from "node:path";
 //#region src/features/catalogue/merge.ts
 function mergeUnique(...items) {
 	return Array.from(new Set(items.flat()));
@@ -21,33 +21,33 @@ function mergeExtractedMessages(messages) {
 	}, /* @__PURE__ */ new Map());
 	return Array.from(mergedMessages.values());
 }
-function reconcileLocaleMessages(existingMessages, nextMessages) {
-	const existingMessagesByKey = existingMessages.reduce((map, message) => {
-		map.set(getMessageKey(message), message);
-		return map;
-	}, /* @__PURE__ */ new Map());
-	const reconciledMessages = nextMessages.reduce((map, message) => {
-		const key = getMessageKey(message);
-		const existingMessage = existingMessagesByKey.get(key);
-		map.set(key, {
-			...message,
-			translation: existingMessage?.translation
-		});
-		return map;
-	}, /* @__PURE__ */ new Map());
-	return Array.from(reconciledMessages.values());
+function pruneLocaleMessages(existingMessages, sourceMessages) {
+	const sourceKeys = new Set(sourceMessages.map(getMessageKey));
+	return existingMessages.filter((message) => sourceKeys.has(getMessageKey(message)) && Boolean(message.translation));
 }
 //#endregion
 //#region src/features/catalogue/path.ts
 function expandBucketOutputPath(bucket, locale, extension = bucket.formatter.extension) {
 	return resolve(bucket.output.replaceAll("{locale}", locale).replaceAll("{extension}", extension.slice(1)));
 }
+/**
+* The declaration file that types a catalogue, e.g. `en.json` -> `en.d.json.ts`.
+*
+* TypeScript resolves `./en.json` by stripping the extension and looking for
+* `en.d.json.ts`; the `en.json.d.ts` form is only consulted for extensions the
+* resolver does not recognise. Non-JS extensions additionally require
+* `allowArbitraryExtensions` in the consumer's tsconfig.
+*/
+function declarationPathFor(cataloguePath) {
+	const { dir, name, ext } = parse(cataloguePath);
+	return resolve(dir, `${name}.d${ext}.ts`);
+}
 //#endregion
 //#region src/features/catalogue/storage.ts
 const DECLARATION_CONTENT = `
 declare const messages: Record<string, string>;
 export default messages;
-`.trim();
+`.trimStart();
 async function readCatalogueMessages(bucket, locale, path = expandBucketOutputPath(bucket, locale)) {
 	const content = await readFile(path, "utf8").catch(() => "");
 	if (!content) return [];
@@ -59,9 +59,9 @@ async function writeCatalogueMessages(bucket, locale, messages, path = expandBuc
 		locale,
 		existingContent
 	});
-	const declarationPath = `${path}.d.ts`;
+	const declarationPath = declarationPathFor(path);
 	await mkdir(dirname(path), { recursive: true });
 	await Promise.all([writeFile(path, catalogueContent), writeFile(declarationPath, DECLARATION_CONTENT)]);
 }
 //#endregion
-export { reconcileLocaleMessages as a, mergeExtractedMessages as i, writeCatalogueMessages as n, expandBucketOutputPath as r, readCatalogueMessages as t };
+export { mergeExtractedMessages as a, expandBucketOutputPath as i, writeCatalogueMessages as n, pruneLocaleMessages as o, declarationPathFor as r, readCatalogueMessages as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saykit/config",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "CLI and configuration tooling for saykit",
   "keywords": [
     "cli",