localewarden 0.2.0 → 0.3.0

package/dist/review.js

@@ -1,6 +1,8 @@
 import path from 'node:path';
+import { groupsOf } from './config.js';
 import { findSourceFiles, flatten, parseDoc, readText } from './files.js';
 import { parseReviewId, reviewId, State } from './state.js';
+import { withLock } from './lock.js';
 import { hash, today } from './util.js';
 function currentValue(config, lang, fileId, key) {
     const rel = fileId.split('{lang}').join(lang);
@@ -41,44 +43,48 @@ function matches(selector, lang, key) {
  * Returns the number of entries changed.
  */
 export function updateReview(config, action, selectors) {
-    const state = new State(path.join(config.root, config.stateDir));
-    let changed = 0;
-    for (const [id, entry] of Object.entries(state.review)) {
-        const { lang, file, key } = parseReviewId(id);
-        if (!selectors.some(selector => matches(selector, lang, key)))
-            continue;
-        if (action === 'approve') {
-            const value = currentValue(config, lang, file, key);
-            if (value === undefined)
+    // Under the run lock: a run in progress would otherwise overwrite these changes.
+    return withLock(path.join(config.root, config.stateDir), () => {
+        const state = new State(path.join(config.root, config.stateDir));
+        let changed = 0;
+        for (const [id, entry] of Object.entries(state.review)) {
+            const { lang, file, key } = parseReviewId(id);
+            if (!selectors.some(selector => matches(selector, lang, key)))
                 continue;
-            state.review[id] = { ...entry, status: 'approved', valueHash: hash(value) };
-        }
-        else {
-            delete state.review[id];
-            state.invalidate(lang, file, key);
-        }
-        changed++;
-    }
-    // Approving a string that is not on the list marks it as checked by a person: it is then
-    // protected like a hand edit and the quality check no longer reports warnings for it.
-    if (action === 'approve') {
-        const exact = selectors.filter(sel => sel !== 'all' && !sel.endsWith(':*') && sel.includes(':'));
-        for (const selector of exact) {
-            const colon = selector.indexOf(':');
-            const [lang, key] = [selector.slice(0, colon), selector.slice(colon + 1)];
-            for (const file of findSourceFiles(config.root, config.files, config.sourceLanguage)) {
-                const id = reviewId(lang, file.id, key);
-                if (state.review[id])
-                    continue;
-                const value = currentValue(config, lang, file.id, key);
+            if (action === 'approve') {
+                const value = currentValue(config, lang, file, key);
                 if (value === undefined)
                     continue;
-                state.review[id] = { status: 'approved', reason: 'approved-by-hand', file: file.pathFor(lang), since: today(), valueHash: hash(value) };
-                changed++;
+                state.review[id] = { ...entry, status: 'approved', valueHash: hash(value) };
+            }
+            else {
+                delete state.review[id];
+                state.invalidate(lang, file, key);
             }
+            changed++;
         }
-    }
-    if (changed > 0)
-        state.save();
-    return changed;
+        // Approving a string that is not on the list marks it as checked by a person: it is then
+        // protected like a hand edit and the quality check no longer reports warnings for it.
+        if (action === 'approve') {
+            const exact = selectors.filter(sel => sel !== 'all' && !sel.endsWith(':*') && sel.includes(':'));
+            for (const selector of exact) {
+                const colon = selector.indexOf(':');
+                const [lang, key] = [selector.slice(0, colon), selector.slice(colon + 1)];
+                const files = groupsOf(config).flatMap(group => findSourceFiles(group.root, group.files, group.sourceLanguage));
+                for (const file of files) {
+                    const id = reviewId(lang, file.id, key);
+                    if (state.review[id])
+                        continue;
+                    const value = currentValue(config, lang, file.id, key);
+                    if (value === undefined)
+                        continue;
+                    state.review[id] = { status: 'approved', reason: 'approved-by-hand', file: file.pathFor(lang), since: today(), valueHash: hash(value) };
+                    changed++;
+                }
+            }
+        }
+        if (changed > 0)
+            state.save();
+        return changed;
+    });
 }

package/dist/state.d.ts

@@ -39,13 +39,20 @@ export declare class State {
     review: Record<string, ReviewEntry>;
     repairFailures: Record<string, RepairFailure>;
     constructor(dir: string);
-    /** Hashes recorded for a string, or undefined if localewarden has not seen it yet. */
+    /**
+     * Hashes recorded for a string, or undefined if localewarden has not seen it yet. `date` is
+     * the UTC day (YYYY-MM-DD) localewarden wrote it; empty for adopted existing translations.
+     */
     get(lang: string, fileId: string, key: string): {
         source: string;
         value: string;
+        date: string;
     } | undefined;
-    /** Records that `value` is the current translation of `source`. */
-    set(lang: string, fileId: string, key: string, source: string, value: string): void;
+    /**
+     * Records that `value` is the current translation of `source`, written today; pass
+     * `written: false` for a translation that was adopted or protected, not written by us.
+     */
+    set(lang: string, fileId: string, key: string, source: string, value: string, written?: boolean): void;
     /** Marks a recorded string as needing re-translation (source hash cleared). */
     invalidate(lang: string, fileId: string, key: string): void;
     delete(lang: string, fileId: string, key: string): void;

package/dist/state.js

@@ -1,28 +1,37 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { writeText } from './files.js';
 import { hash, sortObject, today } from './util.js';
 /** "<file id>#<key>" */
 export const stringId = (fileId, key) => `${fileId}#${key}`;
 /** "<lang>|<file id>#<key>" */
 export const reviewId = (lang, fileId, key) => `${lang}|${stringId(fileId, key)}`;
 export function parseReviewId(id) {
+    // File ids are paths and contain no "#"; keys may ("faq.#1"), so split at the first one.
     const bar = id.indexOf('|');
-    const hashMark = id.lastIndexOf('#');
+    const hashMark = id.indexOf('#', bar + 1);
     return { lang: id.slice(0, bar), file: id.slice(bar + 1, hashMark), key: id.slice(hashMark + 1) };
 }
 function readJson(file, fallback) {
+    let text;
     try {
-        return JSON.parse(fs.readFileSync(file, 'utf8'));
+        text = fs.readFileSync(file, 'utf8');
     }
     catch (error) {
         if (error.code === 'ENOENT')
             return fallback;
-        throw new Error(`Could not read ${file}: ${error.message}`);
+        throw error;
+    }
+    try {
+        return JSON.parse(text.replace(/^\uFEFF/, ''));
+    }
+    catch (error) {
+        throw new Error(`${file} is not valid JSON (${error.message}). It is localewarden's own bookkeeping: ` +
+            'restore it from git, or delete it (translations are kept and adopted again; hand edits made since are then not detected).');
     }
 }
 function writeJson(file, value) {
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n', 'utf8');
+    writeText(file, JSON.stringify(value, null, 2) + '\n');
 }
 export class State {
     dir;
@@ -36,17 +45,27 @@ export class State {
         this.review = readJson(path.join(dir, 'review.json'), {});
         this.repairFailures = readJson(path.join(dir, 'repair-failures.json'), {});
     }
-    /** Hashes recorded for a string, or undefined if localewarden has not seen it yet. */
+    /**
+     * Hashes recorded for a string, or undefined if localewarden has not seen it yet. `date` is
+     * the UTC day (YYYY-MM-DD) localewarden wrote it; empty for adopted existing translations.
+     */
     get(lang, fileId, key) {
         const raw = this.entries[lang]?.[stringId(fileId, key)];
         if (!raw)
             return undefined;
-        const [source, value] = raw.split(':');
-        return { source, value };
+        const [source, value, date = ''] = raw.split(':');
+        return { source, value, date: date ? `${date.slice(0, 4)}-${date.slice(4, 6)}-${date.slice(6, 8)}` : '' };
     }
-    /** Records that `value` is the current translation of `source`. */
-    set(lang, fileId, key, source, value) {
-        (this.entries[lang] ??= {})[stringId(fileId, key)] = `${hash(source)}:${hash(value)}`;
+    /**
+     * Records that `value` is the current translation of `source`, written today; pass
+     * `written: false` for a translation that was adopted or protected, not written by us.
+     */
+    set(lang, fileId, key, source, value, written = true) {
+        const id = stringId(fileId, key);
+        const previous = this.get(lang, fileId, key);
+        const keepDate = !written && previous && previous.value === hash(value) ? previous.date.replace(/-/g, '') : '';
+        const date = written ? today().replace(/-/g, '') : keepDate;
+        (this.entries[lang] ??= {})[id] = `${hash(source)}:${hash(value)}${date ? `:${date}` : ''}`;
     }
     /** Marks a recorded string as needing re-translation (source hash cleared). */
     invalidate(lang, fileId, key) {

package/dist/translate.d.ts

@@ -1,50 +1,10 @@
-import type { Config } from './config.js';
-import { type Model } from './llm.js';
-export interface Logger {
-    info(message: string): void;
-    warn(message: string): void;
-    error(message: string): void;
-    debug?(message: string): void;
-}
-export declare const consoleLogger: Logger;
-export interface RunOptions {
-    /** Subset of the configured target languages. */
-    languages?: string[];
-    /** Show what would be translated; no API calls, no writes. */
-    dryRun?: boolean;
-    /** Re-translate every string, not only new and changed ones. Hand edits stay protected. */
-    retranslateAll?: boolean;
-    /** Also replace hand-edited translations. */
-    overwriteManual?: boolean;
-    /** Ask the model to fix strings the quality check flags, changing as little as possible. */
-    fixFlagged?: boolean;
-    /** Overrides maxTokensPerRun from the config. */
-    maxTokens?: number;
-    logger?: Logger;
-    /** Model to use instead of the configured OpenAI-compatible endpoint (tests, other SDKs). */
-    model?: Model;
-}
-export interface LanguageSummary {
-    translated: number;
-    revised: number;
-    repaired: number;
-    failed: number;
-    protected: number;
-    removed: number;
-    planned: number;
-    plannedChars: number;
-}
-export interface RunSummary {
-    languages: Record<string, LanguageSummary>;
-    filesWritten: string[];
-    tokens: number;
-    requests: number;
-    stoppedByBudget: boolean;
-    pendingReview: number;
-    dryRun: boolean;
-}
-/** Words not shared by both texts, counted on the longer side (word-level LCS). */
-export declare function changedWords(before: string, after: string): number;
-/** A targeted repair may change a few words of a short string or a quarter of a long one. */
-export declare function tooManyChanges(before: string, after: string): string | null;
+import { type Config } from './config.js';
+import { type RunOptions, type RunSummary } from './engine/context.js';
+export { consoleLogger, type Logger, type LanguageSummary, type RunOptions, type RunSummary } from './engine/context.js';
+export { changedWords, tooManyChanges } from './engine/repair.js';
+/**
+ * Translates new and changed strings, group by group (in config order), language by language.
+ * Within a language, all files of a group share requests, so many small files do not cost a
+ * request each. See engine/planner.ts for what is translated, revised, adopted or protected.
+ */
 export declare function run(config: Config, options?: RunOptions): Promise<RunSummary>;