@saykit/config 0.0.0 → 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# @saykit/config
+
+> Configuration schema and CLI for [SayKit](https://saykit.js.org).
+
+Provides the `defineConfig` helper, the Zod-validated schema for `saykit.config.ts`, and the `saykit` CLI used to extract messages from your source.
+
+## Install
+
+```sh
+pnpm add -D @saykit/config
+```
+
+## Configuration
+
+```ts title="saykit.config.ts"
+import { defineConfig } from '@saykit/config';
+import po from '@saykit/format-po';
+import js from '@saykit/transform-js';
+
+export default defineConfig({
+  locales: ['en', 'fr'],
+  buckets: [
+    {
+      include: ['src/**/*.ts'],
+      output: 'src/locales/{locale}.{extension}',
+      formatter: po(),
+      transformer: js(),
+    },
+  ],
+});
+```
+
+## CLI
+
+```sh
+saykit extract           # extract messages once
+saykit extract --watch   # extract and watch for changes
+```
+
+## Documentation
+
+Full configuration guide and CLI reference at [saykit.js.org](https://saykit.js.org).

package/dist/commands/index.cjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+require("../index.cjs");
+const require_loader = require("../loader-DnWt_9U2.cjs");
+const require_hash = require("../hash-CDfMT76E.cjs");
+let _commander_js_extra_typings = require("@commander-js/extra-typings");
+let node_path = require("node:path");
+let node_async_hooks = require("node:async_hooks");
+let node_fs_promises = require("node:fs/promises");
+//#region src/features/logger.ts
+const RESET = "\x1B[0m";
+const DIM = "\x1B[2m";
+const BRIGHT = "\x1B[1m";
+const RED = "\x1B[31m";
+const GREEN = "\x1B[32m";
+const YELLOW = "\x1B[33m";
+const BLUE = "\x1B[34m";
+var Logger = class {
+	#quiet;
+	#verbose;
+	constructor(options = {}) {
+		this.#quiet = options.quiet ?? false;
+		this.#verbose = options.verbose ?? false;
+	}
+	log(...args) {
+		if (!this.#quiet) console.log(...args);
+	}
+	info(...args) {
+		this.log(`${BLUE}🛈${RESET}`, ...args);
+	}
+	warn(...args) {
+		this.log(`${YELLOW}⚠${RESET}`, ...args);
+	}
+	error(...args) {
+		this.log(`${RED}✖${RESET}`, ...args);
+	}
+	success(...args) {
+		this.log(`${GREEN}✔${RESET}`, ...args);
+	}
+	header(message) {
+		this.log(`${BRIGHT}${message}${RESET}`);
+	}
+	step(message) {
+		if (this.#verbose) this.log(` ${DIM}→ ${message}${RESET}`);
+	}
+};
+new node_async_hooks.AsyncLocalStorage({ defaultValue: new Logger() });
+//#endregion
+//#region src/features/catalogue/extractor.ts
+async function extractMessagesFromFile(path, bucket) {
+	const content = await (0, node_fs_promises.readFile)(path, "utf8").catch(() => "");
+	if (!content) return [];
+	return bucket.transformer.extract(content, path).map((message) => ({
+		...message,
+		translation: message.translation ?? message.message,
+		references: message.references.map((reference) => (0, node_path.relative)(process.cwd(), reference).replaceAll("\\", "/"))
+	}));
+}
+//#endregion
+//#region src/features/catalogue/merge.ts
+function mergeUnique(...items) {
+	return Array.from(new Set(items.flat()));
+}
+function getMessageKey(message) {
+	return message.id ?? require_hash.generateHash(message.message, message.context);
+}
+function mergeExtractedMessages(messages) {
+	const mergedMessages = messages.reduce((map, message) => {
+		const key = getMessageKey(message);
+		const existing = map.get(key) ?? message;
+		map.set(key, {
+			...existing,
+			comments: mergeUnique(...existing.comments, ...message.comments),
+			references: mergeUnique(...existing.references, ...message.references)
+		});
+		return map;
+	}, /* @__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: message.message,
+			translation: void 0,
+			...existingMessage,
+			id: message.id,
+			context: message.context,
+			comments: message.comments,
+			references: message.references
+		});
+		return map;
+	}, /* @__PURE__ */ new Map());
+	return Array.from(reconciledMessages.values());
+}
+//#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)));
+}
+function expandBucketOutputIgnoreDirectory(bucket) {
+	const [prefix] = bucket.output.split("{locale}");
+	return (0, node_path.resolve)(prefix || ".");
+}
+//#endregion
+//#region src/features/catalogue/storage.ts
+const DECLARATION_CONTENT = `
+declare const translations: Record<string, string>;
+export default translations;
+`.trim();
+async function readCatalogueMessages(bucket, locale, path = expandBucketOutputPath(bucket, locale)) {
+	const content = await (0, node_fs_promises.readFile)(path, "utf8").catch(() => "");
+	if (!content) return [];
+	return bucket.formatter.parse(content);
+}
+async function writeCatalogueMessages(bucket, locale, messages, path = expandBucketOutputPath(bucket, locale)) {
+	const existingContent = await (0, node_fs_promises.readFile)(path, "utf8").catch(() => void 0);
+	const catalogueContent = bucket.formatter.stringify(messages, {
+		locale,
+		existingContent
+	});
+	const declarationPath = `${path}.d.ts`;
+	const ignoreDirectory = expandBucketOutputIgnoreDirectory(bucket);
+	const ignorePath = (0, node_path.join)(ignoreDirectory, ".gitignore");
+	const ignoreContent = `.gitignore\n*.${bucket.formatter.extension.slice(1)}.d.ts`;
+	await (0, node_fs_promises.mkdir)((0, node_path.dirname)(path), { recursive: true });
+	await (0, node_fs_promises.mkdir)(ignoreDirectory, { recursive: true });
+	await Promise.all([
+		(0, node_fs_promises.writeFile)(path, catalogueContent),
+		(0, node_fs_promises.writeFile)(declarationPath, DECLARATION_CONTENT),
+		(0, node_fs_promises.writeFile)(ignorePath, ignoreContent)
+	]);
+}
+//#endregion
+//#region src/features/watch.ts
+/**
+* Expand a buckets include and exclude patterns into a flat list of file paths.
+*/
+async function globBucket(bucket) {
+	const paths = [];
+	for await (const file of (0, node_fs_promises.glob)(bucket.include, {
+		exclude: bucket.exclude,
+		withFileTypes: true
+	})) if (file.isFile()) paths.push((0, node_path.join)(file.parentPath, file.name));
+	return paths;
+}
+/**
+* Watches a path for changes, emitting a debounced event every set delay.
+*
+* Unlike Node's native `fs.watch` method, this:
+*  - coalesces rapid consecutive events per file
+*  - emits only the final event after `delay` ms of inactivity
+*  - deduplicates events by filename
+*/
+async function* watchDebounced(path, options, delay = 300) {
+	const timers = /* @__PURE__ */ new Map();
+	const queue = /* @__PURE__ */ new Map();
+	const resolvers = /* @__PURE__ */ new Map();
+	(async () => {
+		for await (const event of (0, node_fs_promises.watch)(path, options)) {
+			const key = event.filename ?? "__unknown__";
+			if (timers.has(key)) clearTimeout(timers.get(key));
+			if (!queue.has(key)) queue.set(key, new Promise((r) => resolvers.set(key, r)));
+			timers.set(key, setTimeout(() => {
+				resolvers.get(key)?.(event);
+				timers.delete(key);
+				resolvers.delete(key);
+			}, delay));
+		}
+	})();
+	while (true) if (queue.size) {
+		const next = await Promise.race(queue.values());
+		queue.delete(next.filename ?? "__unknown__");
+		yield next;
+	} else await new Promise((r) => setTimeout(r, 10));
+}
+//#endregion
+//#region src/features/workers/shared.ts
+function normalisePathForLogs(path) {
+	return (0, node_path.relative)(process.cwd(), path).replaceAll("\\", "/");
+}
+var BucketWorker = class {
+	config;
+	bucket;
+	logger;
+	constructor(config, bucket, logger) {
+		this.config = config;
+		this.bucket = bucket;
+		this.logger = logger;
+	}
+};
+//#endregion
+//#region src/features/workers/extract-worker.ts
+var BucketExtractWorker = class extends BucketWorker {
+	#indexedMessagesByPath = /* @__PURE__ */ new Map();
+	get #indexedMessages() {
+		return Array.from(this.#indexedMessagesByPath.values()).flat();
+	}
+	async #indexPath(path) {
+		const relativePath = normalisePathForLogs(path);
+		this.logger.step(`Processing ${relativePath}`);
+		const messages = await extractMessagesFromFile(path, this.bucket);
+		if (!messages.length) {
+			if (this.#indexedMessagesByPath.has(path)) {
+				this.#indexedMessagesByPath.delete(path);
+				this.logger.step(`Removed stale entries for ${relativePath}`);
+				return true;
+			}
+			return false;
+		}
+		this.#indexedMessagesByPath.set(path, messages);
+		this.logger.step(`Found ${messages.length} message(s) in ${relativePath}`);
+		return true;
+	}
+	async scan() {
+		this.logger.info(`Scanning bucket: ${this.bucket.include}`);
+		const paths = await globBucket(this.bucket);
+		this.logger.step(`Found ${paths.length} file(s)`);
+		await Promise.all(paths.map((p) => this.#indexPath(p)));
+		this.logger.info(`Total extracted messages: ${this.#indexedMessages.length}`);
+	}
+	async write() {
+		const mergedMessages = mergeExtractedMessages(this.#indexedMessages);
+		this.logger.info(`Writing ${mergedMessages.length} messages to locales`);
+		for (const locale of this.config.locales) {
+			this.logger.step(`Writing locale file for ${locale} to disk`);
+			const existingMessages = await readCatalogueMessages(this.bucket, locale);
+			const nextMessages = locale === this.config.locales[0] ? mergedMessages : reconcileLocaleMessages(existingMessages, mergedMessages);
+			await writeCatalogueMessages(this.bucket, locale, nextMessages);
+		}
+		this.logger.success(`Extraction complete for bucket: ${this.bucket.include}`);
+	}
+	async update(path) {
+		const changed = await this.#indexPath(path);
+		if (changed) await this.write();
+		return changed;
+	}
+	async watch() {
+		this.logger.header(`👀 Watching bucket for changes: ${this.bucket.include}`);
+		for await (const event of watchDebounced(".", { recursive: true })) {
+			if (!event.filename || !this.bucket.match(event.filename)) continue;
+			const path = (0, node_path.join)(process.cwd(), event.filename);
+			await this.update(path);
+		}
+	}
+};
+//#endregion
+//#region src/commands/extract.ts
+var extract_default = new _commander_js_extra_typings.Command("extract").description("Extract messages from source files").option("-v, --verbose", "enable verbose logging", false).option("-q, --quiet", "suppress all logging", false).option("-w, --watch", "watch source files for changes", false).action(async (options) => {
+	const config = require_loader.resolveConfig();
+	const logger = new Logger(options);
+	logger.header("🛠 Extracting Messages");
+	const workers = config.buckets.map((b) => new BucketExtractWorker(config, b, logger));
+	await Promise.all(workers.map((w) => w.scan().then(() => w.write())));
+	if (options.watch) await Promise.all(workers.map((w) => w.watch()));
+});
+//#endregion
+//#region src/commands/index.ts
+_commander_js_extra_typings.program.name("saykit").helpOption("-h, --help", "Display help for command").helpCommand("help [command]", "Display help for command").addCommand(extract_default).parse();
+//#endregion

package/dist/commands/index.d.cts

@@ -0,0 +1 @@
+export { };

package/dist/commands/index.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/commands/index.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+import { t as resolveConfig } from "../loader-CGuahnrc.mjs";
+import { t as generateHash } from "../hash-Cs0dRdGf.mjs";
+import { Command, program } from "@commander-js/extra-typings";
+import { dirname, join, relative, resolve } from "node:path";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { glob, mkdir, readFile, watch, writeFile } from "node:fs/promises";
+//#region src/features/logger.ts
+const RESET = "\x1B[0m";
+const DIM = "\x1B[2m";
+const BRIGHT = "\x1B[1m";
+const RED = "\x1B[31m";
+const GREEN = "\x1B[32m";
+const YELLOW = "\x1B[33m";
+const BLUE = "\x1B[34m";
+var Logger = class {
+	#quiet;
+	#verbose;
+	constructor(options = {}) {
+		this.#quiet = options.quiet ?? false;
+		this.#verbose = options.verbose ?? false;
+	}
+	log(...args) {
+		if (!this.#quiet) console.log(...args);
+	}
+	info(...args) {
+		this.log(`${BLUE}🛈${RESET}`, ...args);
+	}
+	warn(...args) {
+		this.log(`${YELLOW}⚠${RESET}`, ...args);
+	}
+	error(...args) {
+		this.log(`${RED}✖${RESET}`, ...args);
+	}
+	success(...args) {
+		this.log(`${GREEN}✔${RESET}`, ...args);
+	}
+	header(message) {
+		this.log(`${BRIGHT}${message}${RESET}`);
+	}
+	step(message) {
+		if (this.#verbose) this.log(` ${DIM}→ ${message}${RESET}`);
+	}
+};
+new AsyncLocalStorage({ defaultValue: new Logger() });
+//#endregion
+//#region src/features/catalogue/extractor.ts
+async function extractMessagesFromFile(path, bucket) {
+	const content = await readFile(path, "utf8").catch(() => "");
+	if (!content) return [];
+	return bucket.transformer.extract(content, path).map((message) => ({
+		...message,
+		translation: message.translation ?? message.message,
+		references: message.references.map((reference) => relative(process.cwd(), reference).replaceAll("\\", "/"))
+	}));
+}
+//#endregion
+//#region src/features/catalogue/merge.ts
+function mergeUnique(...items) {
+	return Array.from(new Set(items.flat()));
+}
+function getMessageKey(message) {
+	return message.id ?? generateHash(message.message, message.context);
+}
+function mergeExtractedMessages(messages) {
+	const mergedMessages = messages.reduce((map, message) => {
+		const key = getMessageKey(message);
+		const existing = map.get(key) ?? message;
+		map.set(key, {
+			...existing,
+			comments: mergeUnique(...existing.comments, ...message.comments),
+			references: mergeUnique(...existing.references, ...message.references)
+		});
+		return map;
+	}, /* @__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: message.message,
+			translation: void 0,
+			...existingMessage,
+			id: message.id,
+			context: message.context,
+			comments: message.comments,
+			references: message.references
+		});
+		return map;
+	}, /* @__PURE__ */ new Map());
+	return Array.from(reconciledMessages.values());
+}
+//#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)));
+}
+function expandBucketOutputIgnoreDirectory(bucket) {
+	const [prefix] = bucket.output.split("{locale}");
+	return resolve(prefix || ".");
+}
+//#endregion
+//#region src/features/catalogue/storage.ts
+const DECLARATION_CONTENT = `
+declare const translations: Record<string, string>;
+export default translations;
+`.trim();
+async function readCatalogueMessages(bucket, locale, path = expandBucketOutputPath(bucket, locale)) {
+	const content = await readFile(path, "utf8").catch(() => "");
+	if (!content) return [];
+	return bucket.formatter.parse(content);
+}
+async function writeCatalogueMessages(bucket, locale, messages, path = expandBucketOutputPath(bucket, locale)) {
+	const existingContent = await readFile(path, "utf8").catch(() => void 0);
+	const catalogueContent = bucket.formatter.stringify(messages, {
+		locale,
+		existingContent
+	});
+	const declarationPath = `${path}.d.ts`;
+	const ignoreDirectory = expandBucketOutputIgnoreDirectory(bucket);
+	const ignorePath = join(ignoreDirectory, ".gitignore");
+	const ignoreContent = `.gitignore\n*.${bucket.formatter.extension.slice(1)}.d.ts`;
+	await mkdir(dirname(path), { recursive: true });
+	await mkdir(ignoreDirectory, { recursive: true });
+	await Promise.all([
+		writeFile(path, catalogueContent),
+		writeFile(declarationPath, DECLARATION_CONTENT),
+		writeFile(ignorePath, ignoreContent)
+	]);
+}
+//#endregion
+//#region src/features/watch.ts
+/**
+* Expand a buckets include and exclude patterns into a flat list of file paths.
+*/
+async function globBucket(bucket) {
+	const paths = [];
+	for await (const file of glob(bucket.include, {
+		exclude: bucket.exclude,
+		withFileTypes: true
+	})) if (file.isFile()) paths.push(join(file.parentPath, file.name));
+	return paths;
+}
+/**
+* Watches a path for changes, emitting a debounced event every set delay.
+*
+* Unlike Node's native `fs.watch` method, this:
+*  - coalesces rapid consecutive events per file
+*  - emits only the final event after `delay` ms of inactivity
+*  - deduplicates events by filename
+*/
+async function* watchDebounced(path, options, delay = 300) {
+	const timers = /* @__PURE__ */ new Map();
+	const queue = /* @__PURE__ */ new Map();
+	const resolvers = /* @__PURE__ */ new Map();
+	(async () => {
+		for await (const event of watch(path, options)) {
+			const key = event.filename ?? "__unknown__";
+			if (timers.has(key)) clearTimeout(timers.get(key));
+			if (!queue.has(key)) queue.set(key, new Promise((r) => resolvers.set(key, r)));
+			timers.set(key, setTimeout(() => {
+				resolvers.get(key)?.(event);
+				timers.delete(key);
+				resolvers.delete(key);
+			}, delay));
+		}
+	})();
+	while (true) if (queue.size) {
+		const next = await Promise.race(queue.values());
+		queue.delete(next.filename ?? "__unknown__");
+		yield next;
+	} else await new Promise((r) => setTimeout(r, 10));
+}
+//#endregion
+//#region src/features/workers/shared.ts
+function normalisePathForLogs(path) {
+	return relative(process.cwd(), path).replaceAll("\\", "/");
+}
+var BucketWorker = class {
+	config;
+	bucket;
+	logger;
+	constructor(config, bucket, logger) {
+		this.config = config;
+		this.bucket = bucket;
+		this.logger = logger;
+	}
+};
+//#endregion
+//#region src/features/workers/extract-worker.ts
+var BucketExtractWorker = class extends BucketWorker {
+	#indexedMessagesByPath = /* @__PURE__ */ new Map();
+	get #indexedMessages() {
+		return Array.from(this.#indexedMessagesByPath.values()).flat();
+	}
+	async #indexPath(path) {
+		const relativePath = normalisePathForLogs(path);
+		this.logger.step(`Processing ${relativePath}`);
+		const messages = await extractMessagesFromFile(path, this.bucket);
+		if (!messages.length) {
+			if (this.#indexedMessagesByPath.has(path)) {
+				this.#indexedMessagesByPath.delete(path);
+				this.logger.step(`Removed stale entries for ${relativePath}`);
+				return true;
+			}
+			return false;
+		}
+		this.#indexedMessagesByPath.set(path, messages);
+		this.logger.step(`Found ${messages.length} message(s) in ${relativePath}`);
+		return true;
+	}
+	async scan() {
+		this.logger.info(`Scanning bucket: ${this.bucket.include}`);
+		const paths = await globBucket(this.bucket);
+		this.logger.step(`Found ${paths.length} file(s)`);
+		await Promise.all(paths.map((p) => this.#indexPath(p)));
+		this.logger.info(`Total extracted messages: ${this.#indexedMessages.length}`);
+	}
+	async write() {
+		const mergedMessages = mergeExtractedMessages(this.#indexedMessages);
+		this.logger.info(`Writing ${mergedMessages.length} messages to locales`);
+		for (const locale of this.config.locales) {
+			this.logger.step(`Writing locale file for ${locale} to disk`);
+			const existingMessages = await readCatalogueMessages(this.bucket, locale);
+			const nextMessages = locale === this.config.locales[0] ? mergedMessages : reconcileLocaleMessages(existingMessages, mergedMessages);
+			await writeCatalogueMessages(this.bucket, locale, nextMessages);
+		}
+		this.logger.success(`Extraction complete for bucket: ${this.bucket.include}`);
+	}
+	async update(path) {
+		const changed = await this.#indexPath(path);
+		if (changed) await this.write();
+		return changed;
+	}
+	async watch() {
+		this.logger.header(`👀 Watching bucket for changes: ${this.bucket.include}`);
+		for await (const event of watchDebounced(".", { recursive: true })) {
+			if (!event.filename || !this.bucket.match(event.filename)) continue;
+			const path = join(process.cwd(), event.filename);
+			await this.update(path);
+		}
+	}
+};
+//#endregion
+//#region src/commands/extract.ts
+var extract_default = new Command("extract").description("Extract messages from source files").option("-v, --verbose", "enable verbose logging", false).option("-q, --quiet", "suppress all logging", false).option("-w, --watch", "watch source files for changes", false).action(async (options) => {
+	const config = resolveConfig();
+	const logger = new Logger(options);
+	logger.header("🛠 Extracting Messages");
+	const workers = config.buckets.map((b) => new BucketExtractWorker(config, b, logger));
+	await Promise.all(workers.map((w) => w.scan().then(() => w.write())));
+	if (options.watch) await Promise.all(workers.map((w) => w.watch()));
+});
+//#endregion
+//#region src/commands/index.ts
+program.name("saykit").helpOption("-h, --help", "Display help for command").helpCommand("help [command]", "Display help for command").addCommand(extract_default).parse();
+//#endregion
+export {};

package/dist/features/loader/index.cjs

@@ -0,0 +1,3 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_loader = require("../../loader-DnWt_9U2.cjs");
+exports.resolveConfig = require_loader.resolveConfig;

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

@@ -0,0 +1,6 @@
+import { n as Config } from "../../shapes-CJyTfZXd.cjs";
+
+//#region src/features/loader/resolve.d.ts
+declare function resolveConfig(name?: string): Config;
+//#endregion
+export { resolveConfig };

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

@@ -0,0 +1,6 @@
+import { n as Config } from "../../shapes-DETrtvZf.mjs";
+
+//#region src/features/loader/resolve.d.ts
+declare function resolveConfig(name?: string): Config;
+//#endregion
+export { resolveConfig };

package/dist/features/loader/index.mjs

@@ -0,0 +1,2 @@
+import { t as resolveConfig } from "../../loader-CGuahnrc.mjs";
+export { resolveConfig };