@menapo/vi18n 0.0.0-stage → 0.1.0

package/dist/react-intl-CaBVwJ9u.js

@@ -0,0 +1,519 @@
+import { o as isDiagnosticError } from "./types-D3QGM8XO.js";
+import { n as printICU } from "./codec-DuvU2VQy.js";
+import { l as langFromId, u as parseModule } from "./worker-84U6uYB3.js";
+import { a as attributeExpression, b as stringValue, g as jsxNameNodes, h as jsxName, i as analyzeModule, l as identifierName, o as attributeString, p as jsxAttributes, s as childEntries, t as ModuleBuilder, u as inJsxChildren, v as memberParts, x as unwrap, y as objectProperties } from "./rewrite-CiTRAICl.js";
+import { a as annotateHandlers, g as formatjsId, h as formatjsAstToIcu, l as reactTypes, t as MODULE_EXTENSIONS, v as parseJson } from "./i18next-CrUnKFfh.js";
+import { extname } from "node:path";
+import { readFileSync } from "node:fs";
+//#region src/cli/commands/migrate/react-intl.ts
+/**
+* `vi18n migrate --from react-intl` (INTERNALS §2.14): react-intl and
+* `@formatjs/intl`.
+*
+* Messages are ICU already. The source text is the code's `defaultMessage`
+* (the source catalog's text where a descriptor has none); translations are
+* the catalogs' texts by id: an explicit `id`, else the id
+* `babel-plugin-formatjs` generates (`[sha512:contenthash:base64:6]`).
+* Catalogs are JSON: `{ id: "text" }`, `{ id: { defaultMessage | message |
+* string, description } }`, or `formatjs compile --ast` output.
+* `<FormattedMessage>` and `intl.formatMessage()` become `t()` (`rich()`
+* when values hold elements or tag handlers), `defineMessages` /
+* `defineMessage` become `msg()`, `description` a `context` note.
+* `useIntl()` bindings, imports and `<IntlProvider>` go once unused.
+*/
+function isOldSource(source) {
+	return source === "react-intl" || source.startsWith("react-intl/") || source === "@formatjs/intl";
+}
+/** `fmt` counterparts of the formatting components and `intl.format*` methods. */
+const FORMATTERS = {
+	FormattedNumber: "fmt.number(value, options)",
+	FormattedDate: "fmt.date(value, options)",
+	FormattedTime: "fmt.time(value, options)",
+	FormattedDateParts: "fmt.date(value, options)",
+	FormattedTimeParts: "fmt.time(value, options)",
+	FormattedRelativeTime: "fmt.relative(value, options)",
+	FormattedList: "fmt.list(values, options)",
+	FormattedDisplayName: "Intl.DisplayNames",
+	FormattedPlural: "an ICU plural: t(\"{n, plural, one {…} other {…}}\", { n })",
+	formatNumber: "fmt.number",
+	formatDate: "fmt.date",
+	formatTime: "fmt.time",
+	formatRelativeTime: "fmt.relative",
+	formatList: "fmt.list",
+	formatDisplayName: "Intl.DisplayNames",
+	formatPlural: "an ICU plural"
+};
+function createReactIntlAdapter() {
+	/** locale → id → text. */
+	const catalogs = /* @__PURE__ */ new Map();
+	const referenced = /* @__PURE__ */ new Set();
+	let sourceLocale = "";
+	const readCatalog = (file, env) => {
+		let text;
+		try {
+			text = readFileSync(file.file, "utf8");
+		} catch (error) {
+			env.report("catalog-parse", `cannot read: ${error.message}`, { file: file.file }, "error");
+			return;
+		}
+		const parsed = parseJson(text);
+		if (parsed.problem !== null) {
+			env.report("catalog-parse", parsed.problem.message, {
+				file: file.file,
+				line: parsed.problem.line
+			}, "error");
+			return;
+		}
+		const value = parsed.value;
+		if (typeof value !== "object" || value === null || Array.isArray(value)) {
+			env.report("catalog-parse", "a react-intl catalog is an object of messages by id", { file: file.file }, "error");
+			return;
+		}
+		let texts = catalogs.get(file.locale);
+		if (texts === void 0) catalogs.set(file.locale, texts = /* @__PURE__ */ new Map());
+		const lines = text.split("\n");
+		const lineOf = (id) => {
+			const needle = `${JSON.stringify(id)}:`;
+			return lines.findIndex((l) => l.includes(needle)) + 1;
+		};
+		for (const [id, entry] of Object.entries(value)) {
+			const line = lineOf(id);
+			let message = entry;
+			let description = null;
+			if (typeof entry === "object" && entry !== null && !Array.isArray(entry)) {
+				const record = entry;
+				message = record.defaultMessage ?? record.message ?? record.string ?? record.translation;
+				description = describe(record.description);
+			}
+			if (typeof message === "string") texts.set(id, {
+				text: { icu: message },
+				description,
+				file: file.file,
+				line
+			});
+			else if (Array.isArray(message)) {
+				const nodes = formatjsAstToIcu(message);
+				texts.set(id, {
+					text: nodes === null ? {
+						unconverted: JSON.stringify(message),
+						reason: "a compiled message vi18n cannot print",
+						file: file.file,
+						line
+					} : { icu: printICU(nodes) },
+					description,
+					file: file.file,
+					line
+				});
+			} else env.report("migrate-unconverted", `${id} holds no message text; it was skipped`, {
+				file: file.file,
+				line
+			});
+		}
+	};
+	/** A message for a descriptor; its registry key, or why there is none. */
+	const define = (env, descriptor, file, line) => {
+		const named = descriptor.id !== null;
+		if (descriptor.id === null && descriptor.message === null) return { problem: "a descriptor without id or defaultMessage" };
+		const id = descriptor.id ?? formatjsId(descriptor.message, descriptor.hashed ?? descriptor.description);
+		referenced.add(id);
+		const known = env.message(id);
+		if (known !== void 0) {
+			let same = descriptor.message === null;
+			try {
+				same ||= env.codec.canonicalize(descriptor.message) === known.canonical;
+			} catch {
+				same = false;
+			}
+			if (!same) return { problem: `id ${id} has another defaultMessage at an earlier site (${JSON.stringify(known.source)})` };
+			return { key: id };
+		}
+		const fromCatalog = catalogs.get(sourceLocale)?.get(id);
+		let source = descriptor.message;
+		if (source === null) {
+			if (fromCatalog === void 0) return { problem: `${id} has no defaultMessage and is in no ${sourceLocale} catalog` };
+			if (!("icu" in fromCatalog.text)) return { problem: `${id}: ${fromCatalog.text.reason}` };
+			source = fromCatalog.text.icu;
+		} else if (fromCatalog !== void 0 && "icu" in fromCatalog.text && fromCatalog.text.icu !== source) env.report("migrate-manual", `${id}: the ${sourceLocale} catalog has ${JSON.stringify(fromCatalog.text.icu)}, the code's defaultMessage ${JSON.stringify(source)}; the defaultMessage was kept`, {
+			file: fromCatalog.file,
+			line: fromCatalog.line
+		});
+		const translations = /* @__PURE__ */ new Map();
+		for (const [locale, texts] of catalogs) {
+			if (locale === sourceLocale) continue;
+			const translated = texts.get(id);
+			if (translated !== void 0) translations.set(locale, translated.text);
+		}
+		return env.define({
+			key: id,
+			named,
+			source,
+			context: descriptor.description ?? fromCatalog?.description ?? null,
+			hint: null,
+			translations,
+			file: descriptor.message === null && fromCatalog !== void 0 ? fromCatalog.file : file,
+			line: descriptor.message === null && fromCatalog !== void 0 ? fromCatalog.line : line
+		}) ? { key: id } : { problem: `${id} could not be converted` };
+	};
+	const planModule = (file, text, env) => {
+		let program;
+		try {
+			program = parseModule(text, langFromId(file), file).program;
+		} catch (error) {
+			if (!isDiagnosticError(error)) throw error;
+			env.diagnostics.push({
+				...error.diagnostic,
+				file: env.rel(file)
+			});
+			return null;
+		}
+		const info = analyzeModule(program);
+		const builder = new ModuleBuilder({
+			file,
+			text,
+			info,
+			isOldSource
+		});
+		const tsx = extname(file) === ".tsx";
+		const lineOf = (offset) => text.slice(0, offset).split("\n").length;
+		const imported = (name) => {
+			const locals = /* @__PURE__ */ new Set();
+			for (const declaration of info.imports) {
+				if (!isOldSource(declaration.source)) continue;
+				for (const s of declaration.specifiers) if (s.imported === name) locals.add(s.local);
+			}
+			return locals;
+		};
+		const has = (name, local) => imported(name).has(local);
+		const useIntl = imported("useIntl");
+		const intlBindings = /* @__PURE__ */ new Set();
+		for (const binding of info.bindings) {
+			const init = binding.declarator?.init;
+			if (init === null || init === void 0) continue;
+			const call = unwrap(init);
+			const callee = call.type === "CallExpression" ? identifierName(call.callee) : null;
+			if (callee === null || !useIntl.has(callee)) continue;
+			builder.hooks.push(binding);
+			intlBindings.add(binding);
+		}
+		/** Locals bound to `defineMessages()` / `defineMessage()` results: their members are `msg()` refs now. */
+		const messageTables = /* @__PURE__ */ new Set();
+		for (const binding of info.bindings) {
+			const init = binding.declarator?.init;
+			if (init === null || init === void 0) continue;
+			const call = unwrap(init);
+			const callee = call.type === "CallExpression" ? identifierName(call.callee) : null;
+			if (callee !== null && (has("defineMessages", callee) || has("defineMessage", callee))) messageTables.add(binding.name);
+		}
+		const relativeImports = /* @__PURE__ */ new Set();
+		for (const declaration of info.imports) {
+			if (!declaration.source.startsWith(".")) continue;
+			for (const s of declaration.specifiers) relativeImports.add(s.local);
+		}
+		/** A descriptor object literal, or null when a field is not static. */
+		const readDescriptor = (node) => {
+			const props = objectProperties(node);
+			if (props === null || props.spreads.length > 0) return null;
+			const field = (name) => {
+				const property = props.properties.get(name);
+				if (property === void 0) return null;
+				const value = unwrap(property.value);
+				if (name === "description" && value.type === "ObjectExpression") return describeNode(value)?.note;
+				const s = stringValue(value);
+				return s === null ? void 0 : s;
+			};
+			const id = field("id");
+			const message = field("defaultMessage");
+			const description = field("description");
+			if (id === void 0 || message === void 0 || description === void 0) return null;
+			const object = props.properties.get("description");
+			return {
+				id,
+				message,
+				description,
+				hashed: object !== void 0 && unwrap(object.value).type === "ObjectExpression" ? describeNode(unwrap(object.value))?.json ?? null : description
+			};
+		};
+		/** Whether an expression is a message the migrated code holds as a `msg()` ref. */
+		const isMessageRef = (node) => {
+			let root = unwrap(node);
+			while (root.type === "MemberExpression") root = unwrap(root.object);
+			const name = identifierName(root);
+			return name !== null && (messageTables.has(name) || relativeImports.has(name));
+		};
+		/** Whether values need `rich()`: an element or a function among them. */
+		const needsRich = (values, key) => {
+			if (key !== null) {
+				const message = env.message(key);
+				if (message !== void 0 && hasTag(env.codec.parse(message.canonical))) return true;
+			}
+			if (values === null) return false;
+			const props = objectProperties(values);
+			if (props === null) return false;
+			return props.order.some((p) => {
+				if (p.type === "SpreadElement") return false;
+				const value = unwrap(p.value);
+				return value.type === "ArrowFunctionExpression" || value.type === "FunctionExpression" || value.type === "JSXElement" || value.type === "JSXFragment";
+			});
+		};
+		const call = (r, message, values, rich, types) => {
+			const first = "key" in message ? r.message(message.key) : r.src(message.ref.start, message.ref.end);
+			const rest = values === null ? "" : `, ${r.src(values.start, values.end)}`;
+			if (!rich) return `${r.fn.t}(${first}${rest})`;
+			return `${r.fn.rich}${types === null ? "" : `<${types.node}>`}(${first}${rest})`;
+		};
+		const formattedMessage = (element) => {
+			const attributes = jsxAttributes(element);
+			const attr = (name) => attributes.named.get(name)?.value ?? null;
+			if (attributes.named.has("children") || element.children.length > 0) {
+				builder.note(element.start, "<FormattedMessage> with a render function child was not rewritten: call t() and render the string");
+				return;
+			}
+			let message = null;
+			if (attributes.spreads.length === 1 && !attributes.named.has("id") && !attributes.named.has("defaultMessage")) {
+				const spread = attributes.spreads[0].argument;
+				if (isMessageRef(spread)) message = { ref: spread };
+			} else if (attributes.spreads.length === 0) {
+				const read = (name) => attributes.named.has(name) ? attributeString(attr(name)) ?? void 0 : null;
+				let description = read("description");
+				const descriptionExpr = attributeExpression(attr("description"));
+				let hashed = description;
+				if (description === void 0 && descriptionExpr !== null && unwrap(descriptionExpr).type === "ObjectExpression") {
+					const described = describeNode(unwrap(descriptionExpr));
+					description = described?.note;
+					hashed = described?.json;
+				}
+				const id = read("id");
+				const defaultMessage = read("defaultMessage");
+				if (id !== void 0 && defaultMessage !== void 0 && description !== void 0) {
+					const defined = define(env, {
+						id,
+						message: defaultMessage,
+						description,
+						hashed: hashed ?? null
+					}, file, lineOf(element.start));
+					if ("problem" in defined) {
+						builder.note(element.start, `${defined.problem}; <FormattedMessage> was not rewritten`);
+						return;
+					}
+					message = defined;
+				}
+			}
+			if (message === null) {
+				builder.note(element.start, "<FormattedMessage> with a computed id or defaultMessage was not rewritten");
+				return;
+			}
+			const values = attributeExpression(attr("values"));
+			if (attributes.named.has("values") && (values === null || objectProperties(values) === null)) {
+				builder.note(element.start, "<FormattedMessage values={…}> is not an object literal; not rewritten");
+				return;
+			}
+			const tagName = attributes.named.has("tagName") ? attributeString(attr("tagName")) : null;
+			if (attributes.named.has("tagName") && (tagName === null || !/^[a-z][a-z0-9-]*$/.test(tagName))) {
+				builder.note(element.start, "<FormattedMessage tagName={Component}> was not rewritten: wrap the t() call yourself");
+				return;
+			}
+			const rich = needsRich(values, "key" in message ? message.key : null);
+			const types = rich && tsx ? reactTypes(builder) : null;
+			if (types !== null && values !== null) annotateHandlers(builder, values, types.node);
+			const nested = inJsxChildren(info, element);
+			const resolved = message;
+			builder.site(element, (r) => {
+				const code = call(r, resolved, values, rich, types);
+				if (tagName !== null) return `<${tagName}>{${code}}</${tagName}>`;
+				return nested ? `{${code}}` : code;
+			}, {
+				keys: "key" in message ? [message.key] : [],
+				uses: [rich ? "rich" : "t"],
+				consume: jsxNameNodes(element)
+			});
+		};
+		/** `intl.formatMessage(descriptor, values)` and a destructured `formatMessage(…)`. */
+		const formatMessage = (node) => {
+			const callee = unwrap(node.callee);
+			const member = memberParts(callee);
+			let consume = [];
+			if (member !== null && member.property === "formatMessage") {
+				const object = unwrap(member.object);
+				if (object.type === "Identifier") consume = [object];
+			} else if (callee.type === "Identifier" && [...intlBindings].some((b) => b.name === callee.name)) consume = [callee];
+			else return false;
+			const args = node.arguments;
+			const first = args[0];
+			const values = args[1] ?? null;
+			if (first === void 0 || first.type === "SpreadElement" || args.length > 2) return false;
+			let message = null;
+			if (unwrap(first).type === "ObjectExpression") {
+				const descriptor = readDescriptor(unwrap(first));
+				if (descriptor === null) {
+					builder.note(node.start, "formatMessage() with a computed descriptor was not rewritten");
+					return true;
+				}
+				const defined = define(env, descriptor, file, lineOf(node.start));
+				if ("problem" in defined) {
+					builder.note(node.start, `${defined.problem}; formatMessage() was not rewritten`);
+					return true;
+				}
+				message = defined;
+			} else if (isMessageRef(first)) message = { ref: first };
+			if (message === null) {
+				builder.note(node.start, "formatMessage() with a descriptor vi18n migrate cannot trace was not rewritten: pass a msg() descriptor to t()");
+				return true;
+			}
+			if (values !== null && unwrap(values).type !== "ObjectExpression" && needsRich(null, "key" in message ? message.key : null)) {
+				builder.note(node.start, "formatMessage() with rich values that are not an object literal was not rewritten");
+				return true;
+			}
+			const rich = needsRich(values, "key" in message ? message.key : null);
+			const types = rich && tsx ? reactTypes(builder) : null;
+			if (types !== null && values !== null) annotateHandlers(builder, values, types.node);
+			const resolved = message;
+			builder.site(node, (r) => call(r, resolved, values, rich, types), {
+				keys: "key" in message ? [message.key] : [],
+				uses: [rich ? "rich" : "t"],
+				consume
+			});
+			return true;
+		};
+		/** `defineMessages({ … })` → `{ key: msg(…) }`, `defineMessage({ … })` → `msg(…)`. */
+		const defineCall = (node, kind) => {
+			const callee = unwrap(node.callee);
+			const arg = node.arguments[0];
+			if (arg === void 0) return;
+			if (kind === "defineMessage") {
+				const descriptor = readDescriptor(unwrap(arg));
+				if (descriptor === null) {
+					builder.note(node.start, "defineMessage() with a computed descriptor was not rewritten");
+					return;
+				}
+				const defined = define(env, descriptor, file, lineOf(node.start));
+				if ("problem" in defined) {
+					builder.note(node.start, `${defined.problem}; defineMessage() was not rewritten`);
+					return;
+				}
+				builder.site(node, (r) => `${r.fn.msg}(${r.message(defined.key)})`, {
+					keys: [defined.key],
+					uses: ["msg"],
+					consume: [callee]
+				});
+				return;
+			}
+			const props = objectProperties(arg);
+			if (props === null || props.spreads.length > 0) {
+				builder.note(node.start, "defineMessages() with spreads or computed keys was not rewritten");
+				return;
+			}
+			const entries = [];
+			for (const property of props.order) {
+				const descriptor = readDescriptor(unwrap(property.value));
+				const defined = descriptor === null ? null : define(env, descriptor, file, lineOf(property.start));
+				if (defined === null || "problem" in defined) {
+					builder.note(property.start, `defineMessages(): ${defined === null ? "a computed descriptor" : defined.problem}; the table was not rewritten`);
+					return;
+				}
+				entries.push({
+					property,
+					key: defined.key
+				});
+			}
+			builder.site(node, (r) => {
+				const lines = entries.map(({ property, key }) => {
+					const name = text.slice(property.key.start, property.key.end);
+					return `${property.computed === true ? `[${name}]` : name}: ${r.fn.msg}(${r.message(key)})`;
+				});
+				if (!text.slice(arg.start, arg.end).includes("\n")) return `{ ${lines.join(", ")} }`;
+				const indent = /\n([ \t]*)\S/.exec(text.slice(arg.start, arg.end))?.[1] ?? "  ";
+				const closing = /\n([ \t]*)\}$/.exec(text.slice(arg.start, arg.end))?.[1] ?? "";
+				return `{\n${lines.map((l) => `${indent}${l},`).join("\n")}\n${closing}}`;
+			}, {
+				keys: entries.map((e) => e.key),
+				uses: ["msg"],
+				consume: [callee]
+			});
+		};
+		const unwrapProvider = (element) => {
+			const opening = element.openingElement;
+			const closing = element.closingElement;
+			const children = element.children.filter((c) => !(c.type === "JSXText" && c.value.trim() === ""));
+			builder.consumeRange(opening);
+			builder.consume(jsxNameNodes(element));
+			const nested = inJsxChildren(info, element);
+			builder.replace(element, (r) => {
+				if (closing === null) return nested ? "" : "null";
+				if (nested) return r.src(opening.end, closing.start).trim();
+				if (children.length === 1 && children[0].type === "JSXElement") return r.src(children[0].start, children[0].end);
+				return `<>${r.src(opening.end, closing.start)}</>`;
+			});
+		};
+		const visit = (node) => {
+			if (node.type === "JSXElement") {
+				const name = jsxName(node);
+				if (has("FormattedMessage", name)) formattedMessage(node);
+				else if (has("IntlProvider", name) || has("RawIntlProvider", name)) unwrapProvider(node);
+				else {
+					const imported_ = Object.keys(FORMATTERS).find((f) => has(f, name));
+					if (imported_ !== void 0) builder.note(node.start, `<${name}> is not rewritten: render ${FORMATTERS[imported_]} from @menapo/vi18n`);
+				}
+			} else if (node.type === "CallExpression") {
+				const callee = identifierName(node.callee);
+				if (callee !== null && has("defineMessages", callee)) defineCall(node, "defineMessages");
+				else if (callee !== null && has("defineMessage", callee)) defineCall(node, "defineMessage");
+				else if (callee !== null && has("injectIntl", callee)) builder.note(node.start, "injectIntl() injects intl as a prop: drop it and call t() from @menapo/vi18n");
+				else if (callee !== null && (has("createIntl", callee) || has("createIntlCache", callee))) builder.note(node.start, `${callee}(): use createTranslator(locale) or withLocale() from @menapo/vi18n/server`);
+				else if (!formatMessage(node)) {
+					const member = memberParts(node.callee);
+					if (member !== null && member.property in FORMATTERS && member.property.startsWith("format")) {
+						const object = identifierName(member.object);
+						if (object !== null && [...intlBindings].some((b) => b.name === object)) builder.note(node.start, `intl.${member.property}() is not rewritten: use ${FORMATTERS[member.property]} from @menapo/vi18n`);
+					}
+				}
+			}
+			for (const [, child] of childEntries(node)) visit(child);
+		};
+		visit(program);
+		return builder.finish();
+	};
+	return {
+		catalogExtensions: [".json"],
+		catalogsRequired: false,
+		extensions: MODULE_EXTENSIONS,
+		mentions: (text) => /react-intl|@formatjs\/intl|formatMessage/.test(text),
+		load(files, env) {
+			sourceLocale = env.config.sourceLocale;
+			for (const file of files) readCatalog(file, env);
+		},
+		planFile: planModule,
+		unusedKeys() {
+			return [...catalogs.get(sourceLocale)?.keys() ?? []].filter((id) => !referenced.has(id));
+		}
+	};
+}
+function hasTag(nodes) {
+	return nodes.some((node) => node.type === "tag" || (node.type === "plural" || node.type === "select") && node.options.some((o) => hasTag(o.value)));
+}
+/** A FormatJS `description` as one note: a string as is, an object as `key: value` pairs. */
+function describe(value) {
+	if (typeof value === "string") return value === "" ? null : value;
+	if (typeof value !== "object" || value === null) return null;
+	const parts = Object.entries(value).map(([k, v]) => `${k}: ${typeof v === "string" ? v : JSON.stringify(v)}`);
+	return parts.length === 0 ? null : parts.join("; ");
+}
+/** An object `description` as a note, and as the stable JSON FormatJS hashes. */
+function describeNode(node) {
+	const props = objectProperties(node);
+	if (props === null || props.spreads.length > 0) return void 0;
+	const out = {};
+	for (const [key, property] of props.properties) {
+		const value = unwrap(property.value);
+		const s = stringValue(value);
+		if (s !== null) out[key] = s;
+		else if (value.type === "Literal") out[key] = value.value;
+		else return void 0;
+	}
+	const sorted = Object.fromEntries(Object.keys(out).sort().map((k) => [k, out[k]]));
+	return {
+		note: describe(out),
+		json: JSON.stringify(sorted)
+	};
+}
+//#endregion
+export { createReactIntlAdapter };

package/dist/restore-Btq66Tid.js

@@ -0,0 +1,175 @@
+import { s as parseIdScheme } from "./validate-BxpupdAf.js";
+import { t as createCodec } from "./codec-DuvU2VQy.js";
+import { d as parseCatalogBytes, m as updateCatalogFile } from "./library-D5CWvTQs.js";
+import { t as VERSION } from "./version-BlyLGlOa.js";
+import { c as sourceIndexOf } from "./units-CQ5Q99RC.js";
+import { i as rootRelative, r as plural } from "./output-DsaHKHEt.js";
+import { t as EXIT } from "./types-wSh9fCBY.js";
+import { a as loadCatalogs, o as loadProject, p as targetLocales, t as CliExit, u as readErrors } from "./project-Dwx7iPm6.js";
+import { n as applyRestore } from "./apply-Bre-lY9J.js";
+import { basename, dirname } from "node:path";
+import { promisify } from "node:util";
+import { execFile } from "node:child_process";
+//#region src/cli/commands/restore.ts
+/**
+* `vi18n restore --from <git-rev> [--locale l]… [--dry-run]` (PLAN §4.4,
+* §5.19, INTERNALS §2.6.9): fills entries that are empty now from that
+* revision's catalogs, by exact source text (generated ids) or manual id
+* with the same source text. It undoes what `vi18n extract` rightly did
+* when the code changed back: a reverted text, or a merge whose branch
+* deleted an entry the other branch still uses. Only empty entries are
+* filled, so nothing anyone translated since is overwritten.
+*/
+const run = promisify(execFile);
+/** Catalogs are text, but a large one at an old revision must not hit the default 1 MB buffer. */
+const MAX_BUFFER = 1073741824;
+function gitError(message) {
+	return new CliExit(EXIT.failure, [{
+		code: "restore-git",
+		severity: "error",
+		message
+	}]);
+}
+/** The revision as git sees it; a typo or a missing repository ends the command. */
+async function verifyRevision(cwd, rev) {
+	try {
+		await run("git", [
+			"rev-parse",
+			"--verify",
+			"--quiet",
+			`${rev}^{commit}`
+		], { cwd });
+	} catch (error) {
+		const failure = error;
+		if (failure.code === "ENOENT") throw gitError("git is not installed or not on PATH");
+		const stderr = String(failure.stderr ?? "").trim();
+		throw gitError(/not a git repository/i.test(stderr) ? `${cwd} is not inside a git repository` : `${rev} is not a commit of this repository`);
+	}
+}
+/** A file's bytes at a revision; null when it did not exist there. */
+async function showAt(rev, path) {
+	try {
+		const { stdout } = await run("git", ["show", `${rev}:./${basename(path)}`], {
+			cwd: dirname(path),
+			encoding: "buffer",
+			maxBuffer: MAX_BUFFER
+		});
+		return stdout;
+	} catch {
+		return null;
+	}
+}
+function oldCatalog(bytes, options) {
+	const read = parseCatalogBytes(bytes, options);
+	return {
+		catalog: read.catalog,
+		error: read.diagnostics.find((diagnostic) => diagnostic.severity === "error") ?? null
+	};
+}
+async function restore(ctx, flags) {
+	const project = await loadProject(ctx);
+	const { config, codec, layout } = project;
+	const locales = targetLocales(config, flags.locales);
+	await verifyRevision(config.root, flags.from);
+	const loaded = await loadCatalogs(project);
+	const unreadable = readErrors(loaded.diagnostics);
+	if (unreadable.length > 0) throw new CliExit(EXIT.failure, unreadable);
+	const sourceLoaded = loaded.set.get(config.sourceLocale);
+	const context = {
+		layout,
+		codec,
+		sourceIndex: sourceIndexOf(sourceLoaded?.catalog ?? null, layout, codec)
+	};
+	let oldSource = null;
+	if (layout === "id" && sourceLoaded !== void 0) {
+		const bytes = await showAt(flags.from, sourceLoaded.path);
+		if (bytes !== null) {
+			const read = oldCatalog(bytes, {
+				locale: config.sourceLocale,
+				layout,
+				isSourceLocale: true
+			});
+			if (read.error === null) oldSource = read.catalog;
+		}
+	}
+	const data = {
+		from: flags.from,
+		dryRun: flags.dryRun,
+		locales: [],
+		restored: []
+	};
+	let failed = false;
+	for (const locale of locales) {
+		const target = loaded.set.get(locale);
+		if (target === void 0 || target.catalog === null) continue;
+		const file = rootRelative(config.root, target.path);
+		const bytes = await showAt(flags.from, target.path);
+		if (bytes === null) {
+			ctx.out.note(`vi18n restore: ${file} did not exist at ${flags.from}`);
+			continue;
+		}
+		const old = oldCatalog(bytes, {
+			locale,
+			layout,
+			isSourceLocale: false
+		});
+		if (old.error !== null) {
+			failed = true;
+			ctx.out.report([{
+				...old.error,
+				code: "restore-git",
+				file: target.path,
+				locale,
+				message: `${file} at ${flags.from} cannot be read: ${old.error.message}`
+			}]);
+			continue;
+		}
+		const length = parseIdScheme(old.catalog.header.idScheme ?? "")?.length ?? codec.idLength;
+		const oldCodec = length === codec.idLength ? codec : createCodec(length);
+		const oldContext = {
+			layout,
+			codec: oldCodec,
+			sourceIndex: sourceIndexOf(oldSource, layout, oldCodec)
+		};
+		const apply = (catalog) => applyRestore({
+			catalog,
+			context,
+			old: old.catalog,
+			oldContext,
+			locale
+		});
+		let outcome = null;
+		if (flags.dryRun) outcome = apply(target.catalog);
+		else await updateCatalogFile(target.path, target.hash, (current) => {
+			if (current === null) return null;
+			outcome = apply(current);
+			return outcome.catalog === current ? null : outcome.catalog;
+		}, {
+			locale,
+			layout,
+			isSourceLocale: false,
+			version: VERSION
+		});
+		if (outcome === null) continue;
+		ctx.out.report(outcome.diagnostics.map((diagnostic) => ({
+			...diagnostic,
+			file: target.path
+		})));
+		data.locales.push({
+			locale,
+			file,
+			restored: outcome.restored.length
+		});
+		for (const entry of outcome.restored) data.restored.push({
+			locale,
+			...entry
+		});
+		ctx.out.result(`${locale}: ${plural(outcome.restored.length, "entry", "entries")} ${flags.dryRun ? "to restore" : "restored"} from ${flags.from}`);
+	}
+	return {
+		exitCode: failed ? EXIT.failure : EXIT.ok,
+		data
+	};
+}
+//#endregion
+export { restore };