@chipmobilesdk/rn-i18n 0.1.2 → 0.2.0

package/src/tooling/sync.ts

@@ -1,198 +1,193 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import type {
-	LocaleSyncResult,
-	RuntimeEntryConfig,
-	SyncConfig,
-	TranslationTemplate,
-} from './types.ts';
-
-type JsonValue = string | { [key: string]: JsonValue };
-
-const PLURAL_CATEGORIES = new Set(['zero', 'one', 'two', 'few', 'many', 'other']);
-
-/**
- * Mirrors the runtime plural-group leaf rule (translation/plurals.ts) so a
- * plural variant object is synchronized as one key, not per category.
- */
-function isPluralGroupValue(value: JsonValue): boolean {
-	if (typeof value !== 'object' || value === null) {
-		return false;
-	}
-	const keys = Object.keys(value);
-	return (
-		keys.length > 0 &&
-		'other' in value &&
-		keys.every(
-			key => PLURAL_CATEGORIES.has(key) && typeof value[key] === 'string',
-		)
-	);
-}
-
-/** Flattens nested locale JSON into dot-path keys with leaf values. */
-export function flattenTranslations(
-	node: JsonValue,
-	prefix = '',
-	into: Map<string, JsonValue> = new Map(),
-): Map<string, JsonValue> {
-	if (typeof node === 'string' || isPluralGroupValue(node)) {
-		into.set(prefix, node);
-		return into;
-	}
-	for (const [key, value] of Object.entries(node)) {
-		flattenTranslations(value, prefix ? `${prefix}.${key}` : key, into);
-	}
-	return into;
-}
-
-function sortValue(value: JsonValue): JsonValue {
-	if (typeof value === 'string') {
-		return value;
-	}
-	const sorted: { [key: string]: JsonValue } = {};
-	for (const key of Object.keys(value).sort((a, b) => a.localeCompare(b, 'en'))) {
-		sorted[key] = sortValue(value[key]);
-	}
-	return sorted;
-}
-
-/** Rebuilds the nested JSON object with deterministically sorted keys. */
-export function nestTranslations(flat: Map<string, JsonValue>): JsonValue {
-	const root: { [key: string]: JsonValue } = {};
-	const sortedKeys = [...flat.keys()].sort((a, b) => a.localeCompare(b, 'en'));
-	for (const flatKey of sortedKeys) {
-		const segments = flatKey.split('.');
-		let node = root;
-		for (let index = 0; index < segments.length - 1; index += 1) {
-			const segment = segments[index];
-			const next = node[segment];
-			if (typeof next !== 'object' || next === null || isPluralGroupValue(next)) {
-				node[segment] = {};
-			}
-			node = node[segment] as { [key: string]: JsonValue };
-		}
-		node[segments[segments.length - 1]] = sortValue(flat.get(flatKey)!);
-	}
-	return root;
-}
-
-function placeholderValue(
-	config: SyncConfig,
-	locale: string,
-	key: string,
-	defaultText: string | undefined,
-): string {
-	const placeholder = config.placeholder ?? 'template';
-	if (placeholder === 'template') {
-		return defaultText ?? key;
-	}
-	if (typeof placeholder === 'string') {
-		return placeholder;
-	}
-	return placeholder[locale] ?? defaultText ?? key;
-}
-
-function writeLocaleFile(filePath: string, content: JsonValue): void {
-	// Atomic per-file write: a failed run never leaves a partial locale file.
-	const json = `${JSON.stringify(content, null, '\t')}\n`;
-	const temporaryPath = `${filePath}.tmp`;
-	fs.writeFileSync(temporaryPath, json, 'utf8');
-	fs.renameSync(temporaryPath, filePath);
-}
-
-/**
- * Synchronizes every configured locale JSON file against the scanned
- * template: creates missing files, adds missing keys with the configured
- * placeholder, preserves existing translations verbatim, removes stale keys,
- * and protects declared runtime-only entries (FR-027…FR-030, FR-034/FR-035).
- * Conflicted keys are never added or overwritten while the conflict is open.
- */
-export function syncLocaleFiles(
-	rootDir: string,
-	config: SyncConfig,
-	template: TranslationTemplate,
-	runtimeEntries: readonly RuntimeEntryConfig[],
-): LocaleSyncResult[] {
-	const templateByKey = new Map(template.keys.map(key => [key.key, key]));
-	const conflictedKeys = new Set(template.conflicts.map(conflict => conflict.key));
-	const runtimeByKey = new Map(runtimeEntries.map(entry => [entry.key, entry]));
-	const results: LocaleSyncResult[] = [];
-
-	for (const locale of config.locales) {
-		const filePath = path.join(rootDir, config.localesDir, `${locale}.json`);
-		const result: LocaleSyncResult = {
-			locale,
-			filePath,
-			created: false,
-			addedKeys: [],
-			preservedKeys: [],
-			removedKeys: [],
-			runtimePreserved: [],
-			runtimeAdded: [],
-			runtimeReported: [],
-		};
-		results.push(result);
-
-		let existing = new Map<string, JsonValue>();
-		if (fs.existsSync(filePath)) {
-			try {
-				const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8')) as JsonValue;
-				existing = flattenTranslations(parsed);
-			} catch (error) {
-				result.error = `Malformed locale file ${locale}.json: ${String(error)}`;
-				continue;
-			}
-		} else {
-			result.created = true;
-		}
-
-		const next = new Map<string, JsonValue>();
-
-		for (const [key, templateKey] of templateByKey) {
-			const current = existing.get(key);
-			if (current !== undefined) {
-				next.set(key, current);
-				result.preservedKeys.push(key);
-				continue;
-			}
-			if (conflictedKeys.has(key)) {
-				// Reported for manual review; never silently added (FR-031).
-				continue;
-			}
-			next.set(
-				key,
-				placeholderValue(config, locale, key, templateKey.defaultText),
-			);
-			result.addedKeys.push(key);
-		}
-
-		for (const [key, entry] of runtimeByKey) {
-			const current = existing.get(key);
-			if (current !== undefined) {
-				next.set(key, current);
-				result.runtimePreserved.push(key);
-				continue;
-			}
-			if ((entry.policy ?? 'report') === 'add') {
-				next.set(key, placeholderValue(config, locale, key, entry.defaultText));
-				result.runtimeAdded.push(key);
-			} else {
-				result.runtimeReported.push(key);
-			}
-		}
-
-		for (const key of existing.keys()) {
-			if (!next.has(key) && !runtimeByKey.has(key) && !conflictedKeys.has(key)) {
-				result.removedKeys.push(key);
-			}
-		}
-
-		fs.mkdirSync(path.dirname(filePath), { recursive: true });
-		writeLocaleFile(filePath, nestTranslations(next));
-		result.addedKeys.sort((a, b) => a.localeCompare(b, 'en'));
-		result.preservedKeys.sort((a, b) => a.localeCompare(b, 'en'));
-		result.removedKeys.sort((a, b) => a.localeCompare(b, 'en'));
-	}
-
-	return results;
-}
+import fs from 'node:fs';
+import path from 'node:path';
+import type {
+	LocaleSyncResult,
+	RuntimeEntryConfig,
+	SyncConfig,
+	TranslationTemplate,
+} from './types.ts';
+
+type JsonValue = string | { [key: string]: JsonValue };
+
+const PLURAL_CATEGORIES = new Set(['zero', 'one', 'two', 'few', 'many', 'other']);
+
+/**
+ * Mirrors the runtime plural-group leaf rule (translation/plurals.ts) so a
+ * plural variant object is synchronized as one key, not per category.
+ */
+function isPluralGroupValue(value: JsonValue): boolean {
+	if (typeof value !== 'object' || value === null) {
+		return false;
+	}
+	const keys = Object.keys(value);
+	return (
+		keys.length > 0 &&
+		'other' in value &&
+		keys.every(key => PLURAL_CATEGORIES.has(key) && typeof value[key] === 'string')
+	);
+}
+
+/** Flattens nested locale JSON into dot-path keys with leaf values. */
+export function flattenTranslations(
+	node: JsonValue,
+	prefix = '',
+	into: Map<string, JsonValue> = new Map(),
+): Map<string, JsonValue> {
+	if (typeof node === 'string' || isPluralGroupValue(node)) {
+		into.set(prefix, node);
+		return into;
+	}
+	for (const [key, value] of Object.entries(node)) {
+		flattenTranslations(value, prefix ? `${prefix}.${key}` : key, into);
+	}
+	return into;
+}
+
+function sortValue(value: JsonValue): JsonValue {
+	if (typeof value === 'string') {
+		return value;
+	}
+	const sorted: { [key: string]: JsonValue } = {};
+	for (const key of Object.keys(value).sort((a, b) => a.localeCompare(b, 'en'))) {
+		sorted[key] = sortValue(value[key]);
+	}
+	return sorted;
+}
+
+/** Rebuilds the nested JSON object with deterministically sorted keys. */
+export function nestTranslations(flat: Map<string, JsonValue>): JsonValue {
+	const root: { [key: string]: JsonValue } = {};
+	const sortedKeys = [...flat.keys()].sort((a, b) => a.localeCompare(b, 'en'));
+	for (const flatKey of sortedKeys) {
+		const segments = flatKey.split('.');
+		let node = root;
+		for (let index = 0; index < segments.length - 1; index += 1) {
+			const segment = segments[index];
+			const next = node[segment];
+			if (typeof next !== 'object' || next === null || isPluralGroupValue(next)) {
+				node[segment] = {};
+			}
+			node = node[segment] as { [key: string]: JsonValue };
+		}
+		node[segments[segments.length - 1]] = sortValue(flat.get(flatKey)!);
+	}
+	return root;
+}
+
+function placeholderValue(
+	config: SyncConfig,
+	locale: string,
+	key: string,
+	defaultText: string | undefined,
+): string {
+	const placeholder = config.placeholder ?? 'template';
+	if (placeholder === 'template') {
+		return defaultText ?? key;
+	}
+	if (typeof placeholder === 'string') {
+		return placeholder;
+	}
+	return placeholder[locale] ?? defaultText ?? key;
+}
+
+function writeLocaleFile(filePath: string, content: JsonValue): void {
+	// Atomic per-file write: a failed run never leaves a partial locale file.
+	const json = `${JSON.stringify(content, null, '\t')}\n`;
+	const temporaryPath = `${filePath}.tmp`;
+	fs.writeFileSync(temporaryPath, json, 'utf8');
+	fs.renameSync(temporaryPath, filePath);
+}
+
+/**
+ * Synchronizes every configured locale JSON file against the scanned
+ * template: creates missing files, adds missing keys with the configured
+ * placeholder, preserves existing translations verbatim, removes stale keys,
+ * and protects declared runtime-only entries (FR-027…FR-030, FR-034/FR-035).
+ * Conflicted keys are never added or overwritten while the conflict is open.
+ */
+export function syncLocaleFiles(
+	rootDir: string,
+	config: SyncConfig,
+	template: TranslationTemplate,
+	runtimeEntries: readonly RuntimeEntryConfig[],
+): LocaleSyncResult[] {
+	const templateByKey = new Map(template.keys.map(key => [key.key, key]));
+	const conflictedKeys = new Set(template.conflicts.map(conflict => conflict.key));
+	const runtimeByKey = new Map(runtimeEntries.map(entry => [entry.key, entry]));
+	const results: LocaleSyncResult[] = [];
+
+	for (const locale of config.locales) {
+		const filePath = path.join(rootDir, config.localesDir, `${locale}.json`);
+		const result: LocaleSyncResult = {
+			locale,
+			filePath,
+			created: false,
+			addedKeys: [],
+			preservedKeys: [],
+			removedKeys: [],
+			runtimePreserved: [],
+			runtimeAdded: [],
+			runtimeReported: [],
+		};
+		results.push(result);
+
+		let existing = new Map<string, JsonValue>();
+		if (fs.existsSync(filePath)) {
+			try {
+				const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8')) as JsonValue;
+				existing = flattenTranslations(parsed);
+			} catch (error) {
+				result.error = `Malformed locale file ${locale}.json: ${String(error)}`;
+				continue;
+			}
+		} else {
+			result.created = true;
+		}
+
+		const next = new Map<string, JsonValue>();
+
+		for (const [key, templateKey] of templateByKey) {
+			const current = existing.get(key);
+			if (current !== undefined) {
+				next.set(key, current);
+				result.preservedKeys.push(key);
+				continue;
+			}
+			if (conflictedKeys.has(key)) {
+				// Reported for manual review; never silently added (FR-031).
+				continue;
+			}
+			next.set(key, placeholderValue(config, locale, key, templateKey.defaultText));
+			result.addedKeys.push(key);
+		}
+
+		for (const [key, entry] of runtimeByKey) {
+			const current = existing.get(key);
+			if (current !== undefined) {
+				next.set(key, current);
+				result.runtimePreserved.push(key);
+				continue;
+			}
+			if ((entry.policy ?? 'report') === 'add') {
+				next.set(key, placeholderValue(config, locale, key, entry.defaultText));
+				result.runtimeAdded.push(key);
+			} else {
+				result.runtimeReported.push(key);
+			}
+		}
+
+		for (const key of existing.keys()) {
+			if (!next.has(key) && !runtimeByKey.has(key) && !conflictedKeys.has(key)) {
+				result.removedKeys.push(key);
+			}
+		}
+
+		fs.mkdirSync(path.dirname(filePath), { recursive: true });
+		writeLocaleFile(filePath, nestTranslations(next));
+		result.addedKeys.sort((a, b) => a.localeCompare(b, 'en'));
+		result.preservedKeys.sort((a, b) => a.localeCompare(b, 'en'));
+		result.removedKeys.sort((a, b) => a.localeCompare(b, 'en'));
+	}
+
+	return results;
+}

package/src/tooling/types.ts

@@ -1,119 +1,119 @@
-/**
- * Shared contracts for the Node-only extraction and synchronization tooling.
- * This module must stay free of React Native imports; it is consumed through
- * the `@chipmobilesdk/rn-i18n/tooling` entrypoint and the CLI.
- */
-
-export interface PatternConfig {
-	/**
-	 * Regex source with a named `key` capture group for statically resolvable
-	 * keys, and an optional named `defaultText` group for template values.
-	 */
-	regex: string;
-	/** Extra regex flags; `g` is always applied. */
-	flags?: string;
-	/**
-	 * Optional regex matching dynamic usages of the same call style. Matches
-	 * that do not overlap a static key match are reported as ambiguous.
-	 */
-	ambiguousRegex?: string;
-}
-
-export interface SyncConfig {
-	/** Globs relative to the project root, e.g. `src/**\/*.{ts,tsx}`. */
-	sourceGlobs: string[];
-	patterns: PatternConfig[];
-	/** Directory containing `<locale>.json` files. */
-	localesDir: string;
-	locales: string[];
-	/** Module exporting the declared runtime-only entries. */
-	runtimeEntriesFile?: string;
-	/**
-	 * Value written for newly added keys: `template` uses the discovered
-	 * default text (falling back to the key), a string is used verbatim, and
-	 * a map selects per locale. Default: `template`.
-	 */
-	placeholder?: 'template' | string | Record<string, string>;
-	/** Optional JSON report output path. */
-	reportPath?: string;
-	/** Generated typed key artifact path, e.g. `src/i18n/keys.generated.ts`. */
-	generateKeysFile?: string;
-	/** Exported key type name. Default: `AppI18nKey`. */
-	keysTypeName?: string;
-}
-
-export interface RuntimeEntryConfig {
-	key: string;
-	defaultText: string;
-	policy?: 'add' | 'report';
-	description?: string;
-}
-
-export interface SourceLocation {
-	file: string;
-	line: number;
-}
-
-export interface TemplateKey {
-	key: string;
-	defaultText?: string;
-	locations: SourceLocation[];
-}
-
-export interface AmbiguousUsage {
-	file: string;
-	line: number;
-	snippet: string;
-}
-
-export interface KeyConflict {
-	key: string;
-	values: { text: string; location: SourceLocation }[];
-}
-
-export interface TranslationTemplate {
-	/** Discovered keys sorted by key name. */
-	keys: TemplateKey[];
-	ambiguous: AmbiguousUsage[];
-	conflicts: KeyConflict[];
-	scannedFiles: number;
-}
-
-export interface LocaleSyncResult {
-	locale: string;
-	filePath: string;
-	created: boolean;
-	addedKeys: string[];
-	preservedKeys: string[];
-	removedKeys: string[];
-	runtimePreserved: string[];
-	runtimeAdded: string[];
-	runtimeReported: string[];
-	/** Set when the locale file is malformed; no write happened. */
-	error?: string;
-}
-
-export type ReportOutcome = 'success' | 'completedWithWarnings' | 'failed';
-
-export interface ExtractionReport {
-	outcome: ReportOutcome;
-	discovered: {
-		key: string;
-		defaultText?: string;
-		locations: string[];
-	}[];
-	createdLocaleFiles: { locale: string; filePath: string }[];
-	addedKeys: Record<string, string[]>;
-	preservedKeys: Record<string, string[]>;
-	removedStaleKeys: Record<string, string[]>;
-	missingPerLocale: Record<string, string[]>;
-	runtimeOnly: {
-		declared: string[];
-		preserved: Record<string, string[]>;
-		added: Record<string, string[]>;
-		reported: Record<string, string[]>;
-	};
-	ambiguous: AmbiguousUsage[];
-	conflicts: KeyConflict[];
-	errors: string[];
-}
+/**
+ * Shared contracts for the Node-only extraction and synchronization tooling.
+ * This module must stay free of React Native imports; it is consumed through
+ * the `@chipmobilesdk/rn-i18n/tooling` entrypoint and the CLI.
+ */
+
+export interface PatternConfig {
+	/**
+	 * Regex source with a named `key` capture group for statically resolvable
+	 * keys, and an optional named `defaultText` group for template values.
+	 */
+	regex: string;
+	/** Extra regex flags; `g` is always applied. */
+	flags?: string;
+	/**
+	 * Optional regex matching dynamic usages of the same call style. Matches
+	 * that do not overlap a static key match are reported as ambiguous.
+	 */
+	ambiguousRegex?: string;
+}
+
+export interface SyncConfig {
+	/** Globs relative to the project root, e.g. `src/**\/*.{ts,tsx}`. */
+	sourceGlobs: string[];
+	patterns: PatternConfig[];
+	/** Directory containing `<locale>.json` files. */
+	localesDir: string;
+	locales: string[];
+	/** Module exporting the declared runtime-only entries. */
+	runtimeEntriesFile?: string;
+	/**
+	 * Value written for newly added keys: `template` uses the discovered
+	 * default text (falling back to the key), a string is used verbatim, and
+	 * a map selects per locale. Default: `template`.
+	 */
+	placeholder?: 'template' | string | Record<string, string>;
+	/** Optional JSON report output path. */
+	reportPath?: string;
+	/** Generated typed key artifact path, e.g. `src/i18n/keys.generated.ts`. */
+	generateKeysFile?: string;
+	/** Exported key type name. Default: `AppI18nKey`. */
+	keysTypeName?: string;
+}
+
+export interface RuntimeEntryConfig {
+	key: string;
+	defaultText: string;
+	policy?: 'add' | 'report';
+	description?: string;
+}
+
+export interface SourceLocation {
+	file: string;
+	line: number;
+}
+
+export interface TemplateKey {
+	key: string;
+	defaultText?: string;
+	locations: SourceLocation[];
+}
+
+export interface AmbiguousUsage {
+	file: string;
+	line: number;
+	snippet: string;
+}
+
+export interface KeyConflict {
+	key: string;
+	values: { text: string; location: SourceLocation }[];
+}
+
+export interface TranslationTemplate {
+	/** Discovered keys sorted by key name. */
+	keys: TemplateKey[];
+	ambiguous: AmbiguousUsage[];
+	conflicts: KeyConflict[];
+	scannedFiles: number;
+}
+
+export interface LocaleSyncResult {
+	locale: string;
+	filePath: string;
+	created: boolean;
+	addedKeys: string[];
+	preservedKeys: string[];
+	removedKeys: string[];
+	runtimePreserved: string[];
+	runtimeAdded: string[];
+	runtimeReported: string[];
+	/** Set when the locale file is malformed; no write happened. */
+	error?: string;
+}
+
+export type ReportOutcome = 'success' | 'completedWithWarnings' | 'failed';
+
+export interface ExtractionReport {
+	outcome: ReportOutcome;
+	discovered: {
+		key: string;
+		defaultText?: string;
+		locations: string[];
+	}[];
+	createdLocaleFiles: { locale: string; filePath: string }[];
+	addedKeys: Record<string, string[]>;
+	preservedKeys: Record<string, string[]>;
+	removedStaleKeys: Record<string, string[]>;
+	missingPerLocale: Record<string, string[]>;
+	runtimeOnly: {
+		declared: string[];
+		preserved: Record<string, string[]>;
+		added: Record<string, string[]>;
+		reported: Record<string, string[]>;
+	};
+	ambiguous: AmbiguousUsage[];
+	conflicts: KeyConflict[];
+	errors: string[];
+}