@chipmobilesdk/rn-i18n 0.1.0

package/src/tooling/cli.ts

@@ -0,0 +1,78 @@
+/**
+ * Extraction/synchronization CLI. Node-only; run through the root npm
+ * script under Node >= 22.11 with TypeScript type stripping:
+ *
+ *   npm run i18n:sync
+ *   node --experimental-strip-types packages/rn-i18n/src/tooling/cli.ts --config i18n-sync.config.json
+ *
+ * Exit codes: 0 success or warnings, 1 blocking findings (conflicts or
+ * malformed locale files), 2 invalid configuration or internal error.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { renderReport } from './report.ts';
+import { SyncConfigError, runSync } from './runner.ts';
+import type { SyncConfig } from './types.ts';
+
+function parseArgs(argv: readonly string[]): { configPath: string } {
+	let configPath = 'i18n-sync.config.json';
+	for (let index = 0; index < argv.length; index += 1) {
+		if (argv[index] === '--config' && argv[index + 1]) {
+			configPath = argv[index + 1];
+			index += 1;
+		}
+	}
+	return { configPath };
+}
+
+async function main(): Promise<number> {
+	const rootDir = process.cwd();
+	const { configPath } = parseArgs(process.argv.slice(2));
+	const absoluteConfigPath = path.resolve(rootDir, configPath);
+
+	if (!fs.existsSync(absoluteConfigPath)) {
+		console.error(`[rn-i18n] Sync configuration not found: ${configPath}`);
+		return 2;
+	}
+
+	let config: SyncConfig;
+	try {
+		config = JSON.parse(fs.readFileSync(absoluteConfigPath, 'utf8')) as SyncConfig;
+	} catch (error) {
+		console.error(
+			`[rn-i18n] Sync configuration is not valid JSON: ${String(error)}`,
+		);
+		return 2;
+	}
+
+	try {
+		const { report, generatedKeysChanged } = await runSync(rootDir, config);
+		console.log(renderReport(report));
+		if (config.generateKeysFile) {
+			console.log(
+				generatedKeysChanged
+					? `Typed keys regenerated: ${config.generateKeysFile}`
+					: `Typed keys unchanged: ${config.generateKeysFile}`,
+			);
+		}
+		return report.outcome === 'failed' ? 1 : 0;
+	} catch (error) {
+		if (error instanceof SyncConfigError) {
+			console.error(`[rn-i18n] ${error.message}`);
+		} else {
+			console.error(`[rn-i18n] Sync failed: ${String(error)}`);
+		}
+		return 2;
+	}
+}
+
+main().then(
+	code => {
+		process.exitCode = code;
+	},
+	error => {
+		console.error(`[rn-i18n] Unexpected failure: ${String(error)}`);
+		process.exitCode = 2;
+	},
+);

package/src/tooling/generateKeys.ts

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { RuntimeEntryConfig, TranslationTemplate } from './types.ts';
+
+/**
+ * Renders the typed key contract: the union of scanned template keys and
+ * declared runtime-only keys (FR-041). Apps bind lookups to the generated
+ * type so `tsc --noEmit` reports invalid or stale key usage before release.
+ */
+export function renderKeysModule(
+	template: TranslationTemplate,
+	runtimeEntries: readonly RuntimeEntryConfig[],
+	typeName = 'AppI18nKey',
+): string {
+	const templateKeys = template.keys
+		.map(key => key.key)
+		.sort((a, b) => a.localeCompare(b, 'en'));
+	const runtimeKeys = runtimeEntries
+		.map(entry => entry.key)
+		.sort((a, b) => a.localeCompare(b, 'en'));
+
+	const renderList = (keys: readonly string[]) =>
+		keys.length === 0
+			? '[]'
+			: `[\n${keys.map(key => `\t'${key}',`).join('\n')}\n]`;
+
+	return [
+		'// AUTO-GENERATED by @chipmobilesdk/rn-i18n tooling. Do not edit by hand.',
+		'// Regenerate with: npm run i18n:sync',
+		'',
+		`export const I18N_TEMPLATE_KEYS = ${renderList(templateKeys)} as const;`,
+		'',
+		`export const I18N_RUNTIME_ONLY_KEYS = ${renderList(runtimeKeys)} as const;`,
+		'',
+		'export const I18N_KEYS = [',
+		'\t...I18N_TEMPLATE_KEYS,',
+		'\t...I18N_RUNTIME_ONLY_KEYS,',
+		'] as const;',
+		'',
+		`export type ${typeName} = (typeof I18N_KEYS)[number];`,
+		'',
+	].join('\n');
+}
+
+export interface GenerateKeysResult {
+	filePath: string;
+	changed: boolean;
+}
+
+/** Writes the typed key artifact and reports whether it changed (staleness). */
+export function generateKeysFile(
+	rootDir: string,
+	relativePath: string,
+	template: TranslationTemplate,
+	runtimeEntries: readonly RuntimeEntryConfig[],
+	typeName?: string,
+): GenerateKeysResult {
+	const filePath = path.join(rootDir, relativePath);
+	const content = renderKeysModule(template, runtimeEntries, typeName);
+	const previous = fs.existsSync(filePath)
+		? fs.readFileSync(filePath, 'utf8')
+		: undefined;
+	if (previous !== content) {
+		fs.mkdirSync(path.dirname(filePath), { recursive: true });
+		fs.writeFileSync(filePath, content, 'utf8');
+	}
+	return { filePath, changed: previous !== content };
+}

package/src/tooling/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Programmatic surface of the Node-only extraction and synchronization
+ * tooling, exposed as `@chipmobilesdk/rn-i18n/tooling`. This entrypoint must
+ * never be imported from React Native code; the runtime API lives at the
+ * package root (LIB-003).
+ */
+
+export { globToRegExp, listSourceFiles, scanSource } from './scan.ts';
+export { flattenTranslations, nestTranslations, syncLocaleFiles } from './sync.ts';
+export { buildReport, renderReport } from './report.ts';
+export { generateKeysFile, renderKeysModule } from './generateKeys.ts';
+export type { GenerateKeysResult } from './generateKeys.ts';
+export {
+	SyncConfigError,
+	loadRuntimeEntries,
+	runSync,
+	validateSyncConfig,
+} from './runner.ts';
+export type { SyncRunResult } from './runner.ts';
+export type {
+	AmbiguousUsage,
+	ExtractionReport,
+	KeyConflict,
+	LocaleSyncResult,
+	PatternConfig,
+	ReportOutcome,
+	RuntimeEntryConfig,
+	SourceLocation,
+	SyncConfig,
+	TemplateKey,
+	TranslationTemplate,
+} from './types.ts';

package/src/tooling/report.ts

@@ -0,0 +1,117 @@
+import type {
+	ExtractionReport,
+	LocaleSyncResult,
+	ReportOutcome,
+	RuntimeEntryConfig,
+	TranslationTemplate,
+} from './types.ts';
+
+function perLocale(
+	results: readonly LocaleSyncResult[],
+	select: (result: LocaleSyncResult) => string[],
+): Record<string, string[]> {
+	const record: Record<string, string[]> = {};
+	for (const result of results) {
+		record[result.locale] = select(result);
+	}
+	return record;
+}
+
+/**
+ * Assembles the extraction/synchronization report distinguishing scanned
+ * template keys, runtime-only keys, stale removals, ambiguous usages, and
+ * conflicts (FR-026, FR-036).
+ */
+export function buildReport(
+	template: TranslationTemplate,
+	syncResults: readonly LocaleSyncResult[],
+	runtimeEntries: readonly RuntimeEntryConfig[],
+): ExtractionReport {
+	const errors = syncResults
+		.filter(result => result.error)
+		.map(result => result.error!);
+
+	let outcome: ReportOutcome = 'success';
+	if (
+		template.ambiguous.length > 0 ||
+		syncResults.some(
+			result => result.addedKeys.length > 0 || result.runtimeReported.length > 0,
+		)
+	) {
+		outcome = 'completedWithWarnings';
+	}
+	if (errors.length > 0 || template.conflicts.length > 0) {
+		outcome = 'failed';
+	}
+
+	return {
+		outcome,
+		discovered: template.keys.map(key => ({
+			key: key.key,
+			defaultText: key.defaultText,
+			locations: key.locations.map(
+				location => `${location.file}:${location.line}`,
+			),
+		})),
+		createdLocaleFiles: syncResults
+			.filter(result => result.created && !result.error)
+			.map(result => ({ locale: result.locale, filePath: result.filePath })),
+		addedKeys: perLocale(syncResults, result => result.addedKeys),
+		preservedKeys: perLocale(syncResults, result => result.preservedKeys),
+		removedStaleKeys: perLocale(syncResults, result => result.removedKeys),
+		missingPerLocale: perLocale(syncResults, result =>
+			[...result.addedKeys, ...result.runtimeAdded, ...result.runtimeReported].sort(
+				(a, b) => a.localeCompare(b, 'en'),
+			),
+		),
+		runtimeOnly: {
+			declared: runtimeEntries.map(entry => entry.key),
+			preserved: perLocale(syncResults, result => result.runtimePreserved),
+			added: perLocale(syncResults, result => result.runtimeAdded),
+			reported: perLocale(syncResults, result => result.runtimeReported),
+		},
+		ambiguous: template.ambiguous,
+		conflicts: template.conflicts,
+		errors,
+	};
+}
+
+/** Renders the report as readable text for CLI output. */
+export function renderReport(report: ExtractionReport): string {
+	const lines: string[] = [];
+	lines.push(`i18n sync outcome: ${report.outcome}`);
+	lines.push(`Discovered keys: ${report.discovered.length}`);
+	for (const created of report.createdLocaleFiles) {
+		lines.push(`Created locale file: ${created.locale} -> ${created.filePath}`);
+	}
+	for (const [locale, keys] of Object.entries(report.addedKeys)) {
+		if (keys.length > 0) {
+			lines.push(`Added [${locale}]: ${keys.join(', ')}`);
+		}
+	}
+	for (const [locale, keys] of Object.entries(report.removedStaleKeys)) {
+		if (keys.length > 0) {
+			lines.push(`Removed stale [${locale}]: ${keys.join(', ')}`);
+		}
+	}
+	for (const [locale, keys] of Object.entries(report.runtimeOnly.reported)) {
+		if (keys.length > 0) {
+			lines.push(`Runtime-only missing [${locale}]: ${keys.join(', ')}`);
+		}
+	}
+	for (const usage of report.ambiguous) {
+		lines.push(
+			`Ambiguous usage at ${usage.file}:${usage.line}: ${usage.snippet}`,
+		);
+	}
+	for (const conflict of report.conflicts) {
+		const sources = conflict.values
+			.map(value => `"${value.text}" (${value.location.file}:${value.location.line})`)
+			.join(' vs ');
+		lines.push(`Conflict for key "${conflict.key}": ${sources}`);
+	}
+	for (const error of report.errors) {
+		lines.push(`Error: ${error}`);
+	}
+	return lines.join('\n');
+}

package/src/tooling/runner.ts

@@ -0,0 +1,126 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { scanSource } from './scan.ts';
+import { syncLocaleFiles } from './sync.ts';
+import { buildReport } from './report.ts';
+import { generateKeysFile } from './generateKeys.ts';
+import type {
+	ExtractionReport,
+	RuntimeEntryConfig,
+	SyncConfig,
+} from './types.ts';
+
+export class SyncConfigError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'SyncConfigError';
+	}
+}
+
+export function validateSyncConfig(config: SyncConfig): void {
+	const issues: string[] = [];
+	if (!Array.isArray(config.sourceGlobs) || config.sourceGlobs.length === 0) {
+		issues.push('`sourceGlobs` must list at least one glob.');
+	}
+	if (!Array.isArray(config.patterns) || config.patterns.length === 0) {
+		issues.push('`patterns` must list at least one regex pattern.');
+	} else {
+		for (const pattern of config.patterns) {
+			if (!pattern.regex?.includes('(?<key>')) {
+				issues.push(
+					`Pattern "${pattern.regex}" must contain a named (?<key>...) capture group.`,
+				);
+			}
+		}
+	}
+	if (!config.localesDir) {
+		issues.push('`localesDir` is required.');
+	}
+	if (!Array.isArray(config.locales) || config.locales.length === 0) {
+		issues.push('`locales` must list every supported locale.');
+	}
+	if (issues.length > 0) {
+		throw new SyncConfigError(
+			`Invalid i18n sync configuration:\n- ${issues.join('\n- ')}`,
+		);
+	}
+}
+
+/**
+ * Loads declared runtime-only entries from the configured module. Accepts a
+ * default export or a named `runtimeEntries` export. The module must use
+ * type-only imports so it can run under Node's TypeScript type stripping.
+ */
+export async function loadRuntimeEntries(
+	rootDir: string,
+	runtimeEntriesFile: string | undefined,
+): Promise<RuntimeEntryConfig[]> {
+	if (!runtimeEntriesFile) {
+		return [];
+	}
+	const absolutePath = path.resolve(rootDir, runtimeEntriesFile);
+	if (!fs.existsSync(absolutePath)) {
+		throw new SyncConfigError(
+			`Runtime entries file not found: ${runtimeEntriesFile}`,
+		);
+	}
+	const module = (await import(pathToFileURL(absolutePath).href)) as {
+		default?: RuntimeEntryConfig[];
+		runtimeEntries?: RuntimeEntryConfig[];
+	};
+	const entries = module.default ?? module.runtimeEntries;
+	if (!Array.isArray(entries)) {
+		throw new SyncConfigError(
+			`Runtime entries file must export an entry array (default or \`runtimeEntries\`): ${runtimeEntriesFile}`,
+		);
+	}
+	return entries;
+}
+
+export interface SyncRunResult {
+	report: ExtractionReport;
+	generatedKeysChanged: boolean;
+}
+
+/**
+ * Full pipeline: scan the source tree, synchronize every locale JSON file,
+ * regenerate the typed key artifact, and assemble the report.
+ */
+export async function runSync(
+	rootDir: string,
+	config: SyncConfig,
+	runtimeEntriesOverride?: readonly RuntimeEntryConfig[],
+): Promise<SyncRunResult> {
+	validateSyncConfig(config);
+	const runtimeEntries =
+		runtimeEntriesOverride ??
+		(await loadRuntimeEntries(rootDir, config.runtimeEntriesFile));
+
+	const template = scanSource(rootDir, config.sourceGlobs, config.patterns);
+	const syncResults = syncLocaleFiles(rootDir, config, template, runtimeEntries);
+	const report = buildReport(template, syncResults, runtimeEntries);
+
+	let generatedKeysChanged = false;
+	if (config.generateKeysFile) {
+		generatedKeysChanged = generateKeysFile(
+			rootDir,
+			config.generateKeysFile,
+			template,
+			runtimeEntries,
+			config.keysTypeName,
+		).changed;
+	}
+
+	if (config.reportPath) {
+		const reportPath = path.resolve(rootDir, config.reportPath);
+		fs.mkdirSync(path.dirname(reportPath), { recursive: true });
+		fs.writeFileSync(
+			reportPath,
+			`${JSON.stringify(report, null, '\t')}\n`,
+			'utf8',
+		);
+	}
+
+	return { report, generatedKeysChanged };
+}

package/src/tooling/scan.ts

@@ -0,0 +1,210 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type {
+	AmbiguousUsage,
+	KeyConflict,
+	PatternConfig,
+	SourceLocation,
+	TemplateKey,
+	TranslationTemplate,
+} from './types.ts';
+
+const IGNORED_DIRECTORIES = new Set([
+	'node_modules',
+	'.git',
+	'build',
+	'dist',
+	'Pods',
+]);
+
+/** Converts a glob (`**`, `*`, `?`, `{a,b}`) to an anchored RegExp. */
+export function globToRegExp(glob: string): RegExp {
+	let source = '';
+	let index = 0;
+	while (index < glob.length) {
+		const char = glob[index];
+		if (char === '*') {
+			if (glob[index + 1] === '*') {
+				// `**/` matches zero or more directories; trailing `**` matches all.
+				if (glob[index + 2] === '/') {
+					source += '(?:.*/)?';
+					index += 3;
+				} else {
+					source += '.*';
+					index += 2;
+				}
+				continue;
+			}
+			source += '[^/]*';
+		} else if (char === '?') {
+			source += '[^/]';
+		} else if (char === '{') {
+			const end = glob.indexOf('}', index);
+			if (end === -1) {
+				source += '\\{';
+			} else {
+				const alternatives = glob
+					.slice(index + 1, end)
+					.split(',')
+					.map(alternative =>
+						alternative.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'),
+					);
+				source += `(?:${alternatives.join('|')})`;
+				index = end;
+			}
+		} else {
+			source += char.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+		}
+		index += 1;
+	}
+	return new RegExp(`^${source}$`);
+}
+
+function walkDirectory(rootDir: string, current: string, files: string[]): void {
+	for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+		if (entry.isDirectory()) {
+			if (!IGNORED_DIRECTORIES.has(entry.name)) {
+				walkDirectory(rootDir, path.join(current, entry.name), files);
+			}
+			continue;
+		}
+		if (entry.isFile()) {
+			files.push(
+				path.relative(rootDir, path.join(current, entry.name)).replace(/\\/g, '/'),
+			);
+		}
+	}
+}
+
+/** Lists project-relative source files matching the configured globs. */
+export function listSourceFiles(
+	rootDir: string,
+	sourceGlobs: readonly string[],
+): string[] {
+	const allFiles: string[] = [];
+	walkDirectory(rootDir, rootDir, allFiles);
+	const matchers = sourceGlobs.map(globToRegExp);
+	return allFiles
+		.filter(file => matchers.some(matcher => matcher.test(file)))
+		.sort();
+}
+
+function lineOfIndex(text: string, index: number): number {
+	let line = 1;
+	for (let position = 0; position < index && position < text.length; position += 1) {
+		if (text[position] === '\n') {
+			line += 1;
+		}
+	}
+	return line;
+}
+
+interface CompiledPattern {
+	keyRegex: RegExp;
+	ambiguousRegex?: RegExp;
+}
+
+function compilePatterns(patterns: readonly PatternConfig[]): CompiledPattern[] {
+	return patterns.map(pattern => {
+		const flags = [...new Set(`g${pattern.flags ?? ''}`)].join('');
+		return {
+			keyRegex: new RegExp(pattern.regex, flags),
+			ambiguousRegex: pattern.ambiguousRegex
+				? new RegExp(pattern.ambiguousRegex, flags)
+				: undefined,
+		};
+	});
+}
+
+/**
+ * Scans the source tree with the app-configured i18n usage regex patterns and
+ * builds the source-of-truth translation template: discovered keys with
+ * default text and `file:line` locations, ambiguous dynamic usages, and
+ * conflicting duplicate keys (FR-024…FR-026, FR-031).
+ */
+export function scanSource(
+	rootDir: string,
+	sourceGlobs: readonly string[],
+	patterns: readonly PatternConfig[],
+): TranslationTemplate {
+	const compiled = compilePatterns(patterns);
+	const files = listSourceFiles(rootDir, sourceGlobs);
+	const keys = new Map<string, TemplateKey>();
+	const valuesByKey = new Map<string, { text: string; location: SourceLocation }[]>();
+	const ambiguous: AmbiguousUsage[] = [];
+
+	for (const file of files) {
+		const text = fs.readFileSync(path.join(rootDir, file), 'utf8');
+		const matchedSpans: [number, number][] = [];
+
+		for (const pattern of compiled) {
+			pattern.keyRegex.lastIndex = 0;
+			for (const match of text.matchAll(pattern.keyRegex)) {
+				const key = match.groups?.key;
+				if (!key) {
+					continue;
+				}
+				const startIndex = match.index ?? 0;
+				matchedSpans.push([startIndex, startIndex + match[0].length]);
+				const location: SourceLocation = {
+					file,
+					line: lineOfIndex(text, startIndex),
+				};
+				const existing = keys.get(key);
+				if (existing) {
+					existing.locations.push(location);
+				} else {
+					keys.set(key, { key, locations: [location] });
+				}
+				const defaultText = match.groups?.defaultText;
+				if (defaultText !== undefined) {
+					const values = valuesByKey.get(key) ?? [];
+					values.push({ text: defaultText, location });
+					valuesByKey.set(key, values);
+				}
+			}
+		}
+
+		for (const pattern of compiled) {
+			if (!pattern.ambiguousRegex) {
+				continue;
+			}
+			pattern.ambiguousRegex.lastIndex = 0;
+			for (const match of text.matchAll(pattern.ambiguousRegex)) {
+				const start = match.index ?? 0;
+				const overlapsKeyMatch = matchedSpans.some(
+					([from, to]) => start >= from && start < to,
+				);
+				if (overlapsKeyMatch) {
+					continue;
+				}
+				const lineNumber = lineOfIndex(text, start);
+				ambiguous.push({
+					file,
+					line: lineNumber,
+					snippet: text.split('\n')[lineNumber - 1]?.trim() ?? match[0],
+				});
+			}
+		}
+	}
+
+	const conflicts: KeyConflict[] = [];
+	for (const [key, values] of valuesByKey) {
+		const distinct = [...new Set(values.map(value => value.text))];
+		if (distinct.length > 1) {
+			conflicts.push({ key, values });
+		} else {
+			const templateKey = keys.get(key);
+			if (templateKey) {
+				templateKey.defaultText = values[0].text;
+			}
+		}
+	}
+
+	return {
+		keys: [...keys.values()].sort((a, b) => a.key.localeCompare(b.key)),
+		ambiguous,
+		conflicts: conflicts.sort((a, b) => a.key.localeCompare(b.key)),
+		scannedFiles: files.length,
+	};
+}