@edgekits/i18n-core 0.2.1 → 0.3.0

package/dist/cli/generate.js

@@ -6,11 +6,14 @@ const HEADER = `// Auto-generated by @edgekits/astro-i18n (edgekits-i18n CLI)
 // `FALLBACK_<NAMESPACE>` identifier, so its file name is restricted to what is valid in
 // all three: segments of [a-z0-9_], joined by single dots (`app.billing`).
 export const NAMESPACE_NAME = /^[a-z0-9][a-z0-9_]*(\.[a-z0-9][a-z0-9_]*)*$/;
+// `fallbacks.generated.ts` exports FALLBACK_LOCALE (the default locale's code) beside one
+// FALLBACK_<NAMESPACE> per namespace: a namespace `locale` would export it twice.
+const RESERVED_NAMESPACES = new Set(['locale']);
 /**
  * Throws, naming the offender, when a locale folder is not one of the config's
- * `languages`, a namespace file name does not match NAMESPACE_NAME, or two namespaces
- * compile to the same fallback identifier (`app.billing` and `app__billing`). Run on the
- * collected tree before anything is generated or pushed.
+ * `languages`, a namespace file name does not match NAMESPACE_NAME or is reserved
+ * (`locale`), or two namespaces compile to the same fallback identifier (`app.billing` and
+ * `app__billing`). Run on the collected tree before anything is generated or pushed.
  */
 export function assertValidNames(collected, languages) {
     const configured = Object.keys(languages);
@@ -24,6 +27,11 @@ export function assertValidNames(collected, languages) {
                 throw new Error(`Namespace "${ns}" (${locale}/${ns}.json) must match ${NAMESPACE_NAME}: ` +
                     'segments of lowercase letters, digits and underscores, joined by single dots.');
             }
+            if (RESERVED_NAMESPACES.has(ns)) {
+                throw new Error(`Namespace "${ns}" (${locale}/${ns}.json) is reserved: its fallback would be exported as ` +
+                    `${fallbackIdentifier(ns)}, which fallbacks.generated.ts already exports (the default locale's code). ` +
+                    'Rename the file.');
+            }
             const identifier = fallbackIdentifier(ns);
             const other = identifiers.get(identifier);
             if (other !== undefined) {
@@ -34,6 +42,43 @@ export function assertValidNames(collected, languages) {
         }
     }
 }
+function nullValueError(keyPath, file) {
+    return new Error(`Key "${keyPath}" (${file}) is null: it would override the default locale's text with null. ` +
+        'Remove the key to fall back, or give it a value.');
+}
+// The first null in `value`, as a key path below `keyPath` (`a.b`, `list[2]`), or null.
+function findNull(value, keyPath) {
+    if (value === null)
+        return keyPath;
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            const found = findNull(value[i], `${keyPath}[${i}]`);
+            if (found !== null)
+                return found;
+        }
+    }
+    else if (isTree(value)) {
+        for (const [key, child] of Object.entries(value)) {
+            const found = findNull(child, `${keyPath}.${key}`);
+            if (found !== null)
+                return found;
+        }
+    }
+    return null;
+}
+/**
+ * Throws, naming the key path and the file, on the first `null` in any locale: merged over
+ * the compiled fallback, a null replaces the default locale's text.
+ */
+export function assertNoNullValues(collected) {
+    for (const [locale, namespaces] of Object.entries(collected)) {
+        for (const [ns, json] of Object.entries(namespaces)) {
+            const found = findNull(json, ns);
+            if (found !== null)
+                throw nullValueError(found, `${locale}/${ns}.json`);
+        }
+    }
+}
 /**
  * A single-quoted TS string literal, escaped by JSON.stringify. For every name the
  * validation accepts it is byte-identical to the plain `'name'` the CLI always wrote, so
@@ -77,39 +122,93 @@ function jsonKind(value) {
         return 'array';
     return typeof value;
 }
+// A scalar leaf's TS type: numbers and booleans as such, everything else `string`.
+function scalarType(value) {
+    if (typeof value === 'number')
+        return 'number';
+    if (typeof value === 'boolean')
+        return 'boolean';
+    return 'string';
+}
 /**
- * The TS type of one JSON value. Objects become object types; arrays become `string[]`
- * (strings, other scalars, or empty) or `Array<…>` typed from their first element
- * (objects, nested arrays); every other leaf stays `string`. `keyPath` and `file` name the
- * value in the error a mixed array raises.
+ * Throws, naming the key path (with element indexes) and the file, on what the schema
+ * cannot type: a null, or an array that mixes kinds of elements (strings and objects).
  */
-function generateSchemaTs(value, indent, keyPath, file) {
+function assertTypeable(value, keyPath, file) {
+    if (value === null)
+        throw nullValueError(keyPath, file);
     if (Array.isArray(value)) {
-        if (value.length === 0)
-            return 'string[]';
+        const nullAt = value.indexOf(null);
+        if (nullAt !== -1)
+            throw nullValueError(`${keyPath}[${nullAt}]`, file);
         const kinds = [...new Set(value.map(jsonKind))];
         if (kinds.length > 1) {
             throw new Error(`Key "${keyPath}" (${file}) is an array that mixes ${kinds.join(', ')} elements: ` +
                 'I18n.Schema cannot type it. Use one kind of element per array.');
         }
-        const first = value[0];
-        if (!isTree(first) && !Array.isArray(first))
-            return 'string[]';
-        return `Array<${generateSchemaTs(first, indent, `${keyPath}[0]`, file)}>`;
+        value.forEach((element, i) => assertTypeable(element, `${keyPath}[${i}]`, file));
+    }
+    else if (isTree(value)) {
+        for (const [key, child] of Object.entries(value))
+            assertTypeable(child, `${keyPath}.${key}`, file);
     }
-    if (!isTree(value))
-        return 'string';
-    const entries = Object.entries(value);
-    if (entries.length === 0)
+}
+/**
+ * The TS type of the values found at one place in the tree (one value, or the same key
+ * across the elements of an array), checked by assertTypeable first. Objects merge into one
+ * object type, arrays into one array type, and the distinct kinds that remain form a union
+ * (`string | number` for a key that is a string in one element and a number in another).
+ */
+function typeOfValues(values, indent) {
+    const objects = values.filter(isTree);
+    const arrays = values.filter(Array.isArray);
+    const scalars = [...new Set(values.filter((value) => !isTree(value) && !Array.isArray(value)).map(scalarType))];
+    return [
+        ...(objects.length > 0 ? [objectType(objects, indent)] : []),
+        ...(arrays.length > 0 ? [arrayType(arrays, indent)] : []),
+        ...scalars,
+    ].join(' | ');
+}
+/**
+ * One object type for a list of objects (one object, or every element of an array): each
+ * key in first-seen order, required when every object has it, optional (`?:`) otherwise,
+ * typed by typeOfValues over the objects that have it.
+ */
+function objectType(objects, indent) {
+    const keys = [...new Set(objects.flatMap((object) => Object.keys(object)))];
+    if (keys.length === 0)
         return '{}';
     const pad = ' '.repeat(indent);
     const padInner = ' '.repeat(indent + 2);
-    const lines = entries.map(([key, child]) => `${padInner}${JSON.stringify(key)}: ${generateSchemaTs(child, indent + 2, `${keyPath}.${key}`, file)}`);
+    const lines = keys.map((key) => {
+        const present = objects.filter((object) => Object.hasOwn(object, key));
+        const optional = present.length < objects.length ? '?' : '';
+        return `${padInner}${JSON.stringify(key)}${optional}: ${typeOfValues(present.map((object) => object[key]), indent + 2)}`;
+    });
     return `{\n${lines.join(';\n')};\n${pad}}`;
 }
+/**
+ * One array type for a list of arrays (one array, or the same key's arrays across the
+ * elements of an outer one): the elements of all of them typed together. `string[]` when
+ * they are all empty, `<scalar>[]` for one scalar kind, `Array<…>` otherwise.
+ */
+function arrayType(arrays, indent) {
+    const elements = arrays.flat(1);
+    if (elements.length === 0)
+        return 'string[]';
+    const elementType = typeOfValues(elements, indent);
+    return elements.every((element) => !isTree(element) && !Array.isArray(element)) && !elementType.includes('|')
+        ? `${elementType}[]`
+        : `Array<${elementType}>`;
+}
+/** The TS type of one namespace's JSON (see typeOfValues). */
+function generateSchemaTs(value, indent, keyPath, file) {
+    assertTypeable(value, keyPath, file);
+    return typeOfValues([value], indent);
+}
 /**
  * `src/i18n.generated.d.ts`: the global `I18n.Schema`, from the schema source locale.
- * Throws, naming the key, when an array in it mixes kinds of elements.
+ * Throws, naming the key, when an array in it mixes kinds of elements or a value is null.
  */
 export function buildTypesContent(collected, defaultLocale) {
     const source = schemaSourceLocale(collected, defaultLocale);
@@ -169,3 +268,55 @@ export function buildFallbacksContent(collected, defaultLocale) {
     }
     return lines.join('\n');
 }
+// Leaf key paths in `tree` that `base` lacks: a key missing from `base` counts once, with
+// whatever it holds; arrays are leaves.
+function extraKeyPaths(tree, base, prefix = '') {
+    const paths = [];
+    for (const [key, child] of Object.entries(tree)) {
+        const keyPath = prefix ? `${prefix}.${key}` : key;
+        if (!Object.hasOwn(base, key)) {
+            paths.push(keyPath);
+        }
+        else {
+            const baseChild = base[key];
+            if (isTree(child) && isTree(baseChild))
+                paths.push(...extraKeyPaths(child, baseChild, keyPath));
+        }
+    }
+    return paths;
+}
+/**
+ * Warnings about what I18n.Schema and the fallbacks will not cover, compared with the
+ * default locale: a namespace no default-locale file has, and keys a locale's file has
+ * that the default locale's lacks (a count per file, the first three paths). Empty when
+ * the default locale has no translations (the CLI warns about that on its own).
+ */
+export function translationWarnings(collected, defaultLocale) {
+    const base = collected[defaultLocale];
+    if (!base)
+        return [];
+    const orphans = new Map();
+    const extraKeys = [];
+    for (const [locale, namespaces] of Object.entries(collected)) {
+        if (locale === defaultLocale)
+            continue;
+        for (const [ns, tree] of Object.entries(namespaces)) {
+            const baseTree = base[ns];
+            if (baseTree === undefined) {
+                orphans.set(ns, [...(orphans.get(ns) ?? []), locale]);
+                continue;
+            }
+            const extra = isTree(tree) && isTree(baseTree) ? extraKeyPaths(tree, baseTree) : [];
+            if (extra.length > 0) {
+                const shownPaths = extra.slice(0, 3).join(', ') + (extra.length > 3 ? ', …' : '');
+                extraKeys.push(`${locale}/${ns}.json has ${extra.length} ${extra.length === 1 ? 'key' : 'keys'} that ` +
+                    `${defaultLocale}/${ns}.json lacks (not in I18n.Schema): ${shownPaths}`);
+            }
+        }
+    }
+    return [
+        ...[...orphans].map(([ns, locales]) => `Namespace "${ns}" exists only in ${locales.join(', ')} (no ${defaultLocale}/${ns}.json): ` +
+            'it is not in I18n.Schema and has no fallback.'),
+        ...extraKeys,
+    ];
+}

package/dist/cli/hashes.d.ts

@@ -1,10 +1,12 @@
 import type { CollectedData } from './generate.ts';
 /**
- * Per-namespace content hashes and the change diff that drives the cache purge.
- * Pure apart from hashing. Same algorithm as the site's `scripts/bundle-translations.ts`,
- * so an existing `.i18n-hashes.json` stays a valid baseline.
+ * Per-namespace content hashes, the change diff that drives the cache purge, and the
+ * baseline file. Pure apart from hashing. The site's `scripts/bundle-translations.ts`
+ * algorithm, with keys sorted by code point instead of `localeCompare` (same order for
+ * lowercase ASCII keys; mixed-case keys hash differently once, ADR-0034).
  */
 export type HashMap = Record<string, string>;
+export type BaselineFile = Record<string, HashMap>;
 export declare function stableStringify(value: unknown): string;
 export declare function computeHash(value: unknown): string;
 /**
@@ -15,5 +17,23 @@ export declare function diffHashes(collected: CollectedData, previousHashes: Has
     currentHashes: HashMap;
     changedKeys: string[];
 };
+/** KV keys of "<locale>:<namespace>" pairs (the removed ones, for the bulk delete). */
+export declare function kvKeysFor(hashKeys: readonly string[], keyPrefix: string): string[];
 /** Purge API URLs for the changed "<locale>:<namespace>" pairs. */
 export declare function purgeUrlsFor(changedKeys: readonly string[], keyPrefix: string): string[];
+/** Pairs in `previous` that `current` no longer has: translation files removed since. */
+export declare function removedKeys(previous: HashMap, current: HashMap): string[];
+/**
+ * The baseline of KV namespace `kvId` in a parsed `.i18n-hashes.json` (`undefined`: no
+ * file). A file in the old flat shape is the baseline of `flatOwner`, the top-level
+ * TRANSLATIONS id (0.2.x wrote it, and had no `--env`); another `kvId` gets none (`{}`).
+ * Without a `flatOwner` it is `kvId`'s. With no `kvId` (bundle, which reads no wrangler
+ * config) the only baseline the file holds, or `undefined` when it holds several.
+ */
+export declare function readBaseline(file: unknown, kvId?: string, flatOwner?: string): HashMap | undefined;
+/**
+ * The file with `kvId`'s baseline replaced. An old flat file stays the baseline of its
+ * owner (`flatOwner`, see readBaseline): `{ [kvId]: hashes }` when that is `kvId`,
+ * `{ [flatOwner]: flat, [kvId]: hashes }` otherwise.
+ */
+export declare function writeBaseline(file: unknown, kvId: string, hashes: HashMap, flatOwner?: string): BaselineFile;

package/dist/cli/hashes.js

@@ -1,5 +1,5 @@
 import crypto from 'node:crypto';
-import { formatTranslationCacheUrl } from "../key-format.js";
+import { formatTranslationCacheUrl, formatTranslationKvKey } from "../key-format.js";
 export function stableStringify(value) {
     if (value === null || typeof value !== 'object') {
         return JSON.stringify(value);
@@ -7,7 +7,8 @@ export function stableStringify(value) {
     if (Array.isArray(value)) {
         return '[' + value.map(stableStringify).join(',') + ']';
     }
-    const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+    // Code point order: the same on every machine, whatever its ICU data and locale.
+    const entries = Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
     return '{' + entries.map(([k, v]) => JSON.stringify(k) + ':' + stableStringify(v)).join(',') + '}';
 }
 export function computeHash(value) {
@@ -33,6 +34,13 @@ export function diffHashes(collected, previousHashes) {
     }
     return { currentHashes, changedKeys };
 }
+/** KV keys of "<locale>:<namespace>" pairs (the removed ones, for the bulk delete). */
+export function kvKeysFor(hashKeys, keyPrefix) {
+    return hashKeys.map((hashKey) => {
+        const [locale, ns] = hashKey.split(':');
+        return formatTranslationKvKey(keyPrefix, locale, ns);
+    });
+}
 /** Purge API URLs for the changed "<locale>:<namespace>" pairs. */
 export function purgeUrlsFor(changedKeys, keyPrefix) {
     return changedKeys.map((hashKey) => {
@@ -40,3 +48,49 @@ export function purgeUrlsFor(changedKeys, keyPrefix) {
         return formatTranslationCacheUrl(keyPrefix, locale, ns);
     });
 }
+/** Pairs in `previous` that `current` no longer has: translation files removed since. */
+export function removedKeys(previous, current) {
+    return Object.keys(previous).filter((key) => !Object.hasOwn(current, key));
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// The pre-0.3 shape: one flat baseline, every value a hash string.
+function isFlatBaseline(file) {
+    const values = Object.values(file);
+    return values.length > 0 && values.every((value) => typeof value === 'string');
+}
+/**
+ * The baseline of KV namespace `kvId` in a parsed `.i18n-hashes.json` (`undefined`: no
+ * file). A file in the old flat shape is the baseline of `flatOwner`, the top-level
+ * TRANSLATIONS id (0.2.x wrote it, and had no `--env`); another `kvId` gets none (`{}`).
+ * Without a `flatOwner` it is `kvId`'s. With no `kvId` (bundle, which reads no wrangler
+ * config) the only baseline the file holds, or `undefined` when it holds several.
+ */
+export function readBaseline(file, kvId, flatOwner) {
+    if (!isRecord(file))
+        return {};
+    if (isFlatBaseline(file))
+        return kvId === undefined || kvId === (flatOwner ?? kvId) ? file : {};
+    const baselines = file;
+    if (kvId !== undefined)
+        return baselines[kvId] ?? {};
+    const ids = Object.keys(baselines);
+    if (ids.length > 1)
+        return undefined;
+    return ids.length === 1 ? baselines[ids[0]] : {};
+}
+/**
+ * The file with `kvId`'s baseline replaced. An old flat file stays the baseline of its
+ * owner (`flatOwner`, see readBaseline): `{ [kvId]: hashes }` when that is `kvId`,
+ * `{ [flatOwner]: flat, [kvId]: hashes }` otherwise.
+ */
+export function writeBaseline(file, kvId, hashes, flatOwner) {
+    if (!isRecord(file))
+        return { [kvId]: hashes };
+    if (isFlatBaseline(file)) {
+        const owner = flatOwner ?? kvId;
+        return owner === kvId ? { [kvId]: hashes } : { [owner]: file, [kvId]: hashes };
+    }
+    return { ...file, [kvId]: hashes };
+}