@vouchington/localization-compiler 0.0.0 → 0.0.2

package/README.md

@@ -4,6 +4,35 @@ Node-only compiler for `@vouchington/localization`. It validates namespace-shard
 requires complete `en-US` with sparse partial locales, emits an immutable read-only SQLite
 artifact, and exposes the same consumer/locale/selector resolver used by application CLIs.
 
+Catalog shards must be a JSON array with one compact message per line (`id` first, sorted).
+`compile` rejects any other layout. Line tools never parse the shard as a JSON document:
+
+```bash
+vouchington-localization upsert --file localization/catalog/common.json --message '{"id":"common.ok","consumers":["web"],"descriptor":null,"translations":{"en-US":"OK"}}'
+vouchington-localization remove --file localization/catalog/common.json --id common.ok
+vouchington-localization format --source localization/catalog
+```
+
+Git merge is 3-way by message id, then by field (configure once per clone). Adding `es` on one
+branch and `fr` on the other auto-merges when both sides keep a compile-valid shape. An empty
+`%O` (add/add of a new shard) is treated as `[]`. Both sides changing the same locale,
+descriptor, or deleting vs editing the same id is a conflict.
+
+```gitattributes
+localization/catalog/*.json merge=vouchington-localization text eol=lf
+localization/catalog/tags.json merge=text
+```
+
+```gitconfig
+[merge "vouchington-localization"]
+  name = Merge localization catalog shards by message id and locale
+  driver = vouchington-localization git-merge %O %A %B
+```
+
+On conflict the driver writes conflict markers into `%A` (`<<<<<<< ours` / `=======` /
+`>>>>>>> theirs`) and exits non-zero. Resolve the markers, then `format` or `compile` — a
+conflicted shard is not canonical.
+
 CSV import/export is interchange only: never source of truth and never compiled directly to
 SQLite. Native resource helpers emit strings, RESX, and typed key/descriptor files from the
 same resolved catalog without product path assumptions.

package/dist/cli-shard.d.mts

@@ -0,0 +1,2 @@
+export declare function runShardCli(command: string, args: readonly string[]): string | undefined;
+export declare function shardUsage(): string;

package/dist/cli-shard.mjs

@@ -0,0 +1,82 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { CatalogMergeConflict, mergeCatalogShards, parseCatalogShardText, removeCatalogLine, serializeCatalogShard, upsertCatalogLine, } from '@vouchington/localization';
+import { parseCatalogFile } from './validate.mjs';
+export function runShardCli(command, args) {
+    if (command === 'upsert') {
+        const path = requiredPath(args, '--file');
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, upsertCatalogLine(readShard(path), required(args, '--message')));
+        return undefined;
+    }
+    if (command === 'remove') {
+        const path = requiredPath(args, '--file');
+        writeFileSync(path, removeCatalogLine(readFileSync(path, 'utf8'), required(args, '--id')));
+        return undefined;
+    }
+    if (command === 'git-merge') {
+        const [ancestor, ours, theirs] = args;
+        if (ancestor === undefined || ours === undefined || theirs === undefined) {
+            throw new TypeError(shardUsage());
+        }
+        try {
+            writeFileSync(ours, mergeCatalogShards(readFileSync(ancestor, 'utf8'), readFileSync(ours, 'utf8'), readFileSync(theirs, 'utf8')));
+        }
+        catch (error) {
+            if (error instanceof CatalogMergeConflict)
+                writeFileSync(ours, error.text);
+            throw error;
+        }
+        return undefined;
+    }
+    if (command === 'format')
+        return formatCatalogDirectory(required(args, '--source'));
+    throw new TypeError(shardUsage());
+}
+export function shardUsage() {
+    return [
+        'Usage: vouchington-localization upsert --file <file> --message <json>',
+        'Usage: vouchington-localization remove --file <file> --id <id>',
+        'Usage: vouchington-localization git-merge <ancestor> <ours> <theirs>',
+        'Usage: vouchington-localization format --source <dir>',
+    ].join('\n');
+}
+function formatCatalogDirectory(directory) {
+    const names = readdirSync(directory).filter((name) => name.endsWith('.json') && name !== 'tags.json');
+    for (const name of names) {
+        const path = join(directory, name);
+        try {
+            writeFileSync(path, serializeCatalogShard(messagesFromUnknownText(readFileSync(path, 'utf8'))));
+        }
+        catch (error) {
+            throw new TypeError(`${path}: ${error.message}`);
+        }
+    }
+    return `${names.length} files`;
+}
+function required(args, flag) {
+    const index = args.indexOf(flag);
+    const value = index === -1 ? undefined : args[index + 1];
+    if (value === undefined || value.startsWith('--'))
+        throw new TypeError(shardUsage());
+    return value;
+}
+function requiredPath(args, flag) {
+    return resolve(required(args, flag));
+}
+function messagesFromUnknownText(text) {
+    try {
+        return parseCatalogShardText(text);
+    }
+    catch (shardError) {
+        try {
+            return parseCatalogFile(JSON.parse(text));
+        }
+        catch {
+            throw shardError;
+        }
+    }
+}
+function readShard(path) {
+    return existsSync(path) ? readFileSync(path, 'utf8') : '[]\n';
+}

package/dist/cli.mjs

@@ -7,8 +7,18 @@ import { exportLocalizationCsv, importLocalizationCsv } from './csv.mjs';
 import { loadCatalogDirectory } from './load.mjs';
 import { openLocalizationDatabase } from './open.mjs';
 import { explainLocalizationPlan, resolveLocalizationBatch } from './resolve.mjs';
+import { runShardCli, shardUsage } from './cli-shard.mjs';
 export async function runLocalizationCli(argv, write = console.log) {
     const [command, ...rest] = argv;
+    if (command === 'upsert' ||
+        command === 'remove' ||
+        command === 'git-merge' ||
+        command === 'format') {
+        const result = runShardCli(command, rest);
+        if (typeof result === 'string')
+            write(result);
+        return;
+    }
     if (command === 'compile') {
         const loaded = await loadCatalogDirectory(required(rest, '--source'));
         write(compileLocalizationSqlite(loaded.messages, required(rest, '--output'), loaded.tags));
@@ -75,5 +85,6 @@ function usage() {
         'Usage: vouchington-localization inspect --db <file>',
         'Usage: vouchington-localization csv-export --source <dir> [--output <file>]',
         'Usage: vouchington-localization csv-import --input <file> --output <dir>',
+        shardUsage(),
     ].join('\n');
 }

package/dist/compile.mjs

@@ -2,7 +2,7 @@ import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } from 'node:
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
-import { canonicalJson, compareCodePoints, LOCALIZATION_WIRE_CONTRACT, } from '@vouchington/localization';
+import { canonicalJson, compareCodePoints, LOCALIZATION_WIRE_CONTRACT, serializeCatalogShard, } from '@vouchington/localization';
 import { assertSqliteIntegrity } from './integrity.mjs';
 import { catalogRevision } from './revision.mjs';
 import { SQLITE_SCHEMA } from './schema.mjs';
@@ -31,7 +31,7 @@ export function compileLocalizationSqlite(messages, outputPath, tags = {}) {
     return revision;
 }
 export function writeJsonCatalog(messages, path) {
-    writeFileSync(path, `${JSON.stringify({ messages }, null, 2)}\n`);
+    writeFileSync(path, serializeCatalogShard(messages));
 }
 function insertMetadata(database, revision) {
     const insert = database.prepare('INSERT INTO metadata (key, value) VALUES (?, ?)');
@@ -42,7 +42,7 @@ function insertMessages(database, messages) {
     const insertMessage = database.prepare('INSERT INTO messages (id, descriptor_json) VALUES (?, ?)');
     const insertTranslation = database.prepare('INSERT INTO translations (locale, message_id, value_json) VALUES (?, ?, ?)');
     const insertConsumer = database.prepare('INSERT INTO consumer_membership (consumer, message_id) VALUES (?, ?)');
-    for (const message of [...messages].toSorted((left, right) => (left.id < right.id ? -1 : 1))) {
+    for (const message of [...messages].toSorted((left, right) => compareCodePoints(left.id, right.id))) {
         insertMessage.run(message.id, canonicalJson(message.descriptor));
         for (const consumer of message.consumers)
             insertConsumer.run(consumer, message.id);

package/dist/load.mjs

@@ -1,7 +1,7 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { compareCodePoints } from '@vouchington/localization';
-import { parseCatalogFile, validateCatalogMessages } from './validate.mjs';
+import { compareCodePoints, parseCatalogShardText, } from '@vouchington/localization';
+import { validateCatalogMessages } from './validate.mjs';
 export async function loadCatalogDirectory(directory) {
     const names = (await readdir(directory))
         .filter((name) => name.endsWith('.json'))
@@ -11,12 +11,12 @@ export async function loadCatalogDirectory(directory) {
     const messages = [];
     let tags = {};
     for (const name of names) {
-        const parsed = JSON.parse(await readFile(join(directory, name), 'utf8'));
+        const text = await readFile(join(directory, name), 'utf8');
         if (name === 'tags.json') {
-            tags = parseTags(parsed);
+            tags = parseTags(JSON.parse(text));
             continue;
         }
-        messages.push(...parseCatalogFile(parsed));
+        messages.push(...parseCatalogShardText(text));
     }
     if (messages.length === 0)
         throw new TypeError(`No catalog messages in "${directory}"`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vouchington/localization-compiler",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "description": "Node compiler for localization JSON catalogs, immutable SQLite artifacts, and CLI resolution.",
   "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/localization-compiler#readme",
   "bugs": {
@@ -34,15 +34,14 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsc --project tsconfig.build.json",
-    "prepack": "pnpm run build"
-  },
   "dependencies": {
     "@vouchington/csv": "^0.0.1",
-    "@vouchington/localization": "^0.0.0"
+    "@vouchington/localization": "^0.0.1"
   },
   "engines": {
     "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json"
   }
-}
+}

package/dist/test-helpers.d.mts

@@ -1,3 +0,0 @@
-import type { CatalogMessage } from '@vouchington/localization';
-export declare function sampleMessages(): CatalogMessage[];
-export declare function writeCatalog(files: Record<string, unknown>): string;

package/dist/test-helpers.mjs

@@ -1,49 +0,0 @@
-import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-export function sampleMessages() {
-    return [
-        {
-            id: 'nav.home',
-            descriptor: null,
-            consumers: ['web', 'swift'],
-            translations: { 'en-US': 'Home', es: 'Inicio' },
-        },
-        {
-            id: 'common.save',
-            descriptor: null,
-            consumers: ['web'],
-            translations: { 'en-US': 'Save "{name}"' },
-        },
-        {
-            id: 'settings.count',
-            descriptor: { kind: 'plural', valueParameter: 'count' },
-            consumers: ['web', 'dotnet'],
-            translations: {
-                'en-US': { one: '{count} item', other: '{count} items' },
-                es: { one: '{count} artículo', other: '{count} artículos' },
-            },
-        },
-        {
-            id: 'settings.ago',
-            descriptor: {
-                kind: 'select-plural',
-                valueParameter: 'value',
-                selectParameter: 'unit',
-                cases: ['day'],
-            },
-            consumers: ['email'],
-            translations: {
-                'en-US': { day: { one: '{value} day ago', other: '{value} days ago' } },
-            },
-        },
-    ];
-}
-export function writeCatalog(files) {
-    const directory = mkdtempSync(join(tmpdir(), 'catalog-'));
-    mkdirSync(directory, { recursive: true });
-    for (const [name, value] of Object.entries(files)) {
-        writeFileSync(join(directory, name), `${JSON.stringify(value, null, 2)}\n`);
-    }
-    return directory;
-}