localewarden 0.2.0 → 0.3.0

package/dist/config.js

@@ -20,7 +20,12 @@ export const DEFAULTS = {
     concurrency: 4,
     batchSize: 20,
     stateDir: '.localewarden',
+    copies: {},
+    chunkChars: 8000,
+    plugins: [],
 };
+/** Settings that apply to the whole run and cannot differ per group. */
+const GLOBAL_ONLY = ['groups', 'stateDir', 'plugins', 'dailyTokenBudget', 'maxTokensPerRun', 'concurrency'];
 export class ConfigError extends Error {
 }
 const isStringRecord = (value) => Boolean(value) &&
@@ -32,7 +37,88 @@ export function resolveConfig(raw, root) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
         throw new ConfigError('The config must be a JSON object.');
     }
-    const input = raw;
+    const { groups, ...rest } = raw;
+    if (groups === undefined)
+        return resolveSingle(rest, root);
+    if (!Array.isArray(groups) || groups.length === 0) {
+        throw new ConfigError('"groups" must be a non-empty list of { "name", "files", ... } objects.');
+    }
+    const names = new Set();
+    const resolved = groups.map((group, i) => {
+        if (!group || typeof group !== 'object' || Array.isArray(group))
+            throw new ConfigError(`groups[${i}] must be an object.`);
+        const g = group;
+        if (typeof g.name !== 'string' || g.name === '')
+            throw new ConfigError(`groups[${i}] needs a "name".`);
+        if (names.has(g.name))
+            throw new ConfigError(`Group name "${g.name}" is used twice.`);
+        names.add(g.name);
+        const global = Object.keys(g).filter(key => GLOBAL_ONLY.includes(key));
+        if (global.length > 0)
+            throw new ConfigError(`groups[${i}] ("${g.name}"): ${global.join(', ')} can only be set at the top level.`);
+        try {
+            return resolveSingle(mergeGroup(rest, g), root);
+        }
+        catch (error) {
+            throw new ConfigError(`Group "${g.name}": ${error.message}`);
+        }
+    });
+    return { ...resolved[0], name: undefined, groups: resolved };
+}
+/** Settings a group merges with the top level instead of replacing. */
+const MERGED_OBJECTS = ['formality', 'termNotes', 'instructions', 'maxLength'];
+const MERGED_LISTS = ['doNotTranslate', 'ignoreKeys', 'exclude'];
+/**
+ * A group's settings on top of the top-level ones: maps (formality, glossary per language,
+ * termNotes, instructions, maxLength) are merged, lists (doNotTranslate, ignoreKeys, exclude)
+ * extended, everything else replaced. `copies` belong to the locales they name: a group with
+ * its own languages does not inherit them.
+ */
+function mergeGroup(base, group) {
+    const merged = { ...base, ...group };
+    const asObject = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});
+    for (const key of MERGED_OBJECTS) {
+        if (key in group && key in base)
+            merged[key] = { ...asObject(base[key]), ...asObject(group[key]) };
+    }
+    if ('glossary' in group && 'glossary' in base) {
+        const glossary = { ...asObject(base.glossary) };
+        for (const [lang, terms] of Object.entries(asObject(group.glossary)))
+            glossary[lang] = { ...asObject(glossary[lang]), ...asObject(terms) };
+        merged.glossary = glossary;
+    }
+    for (const key of MERGED_LISTS) {
+        if (Array.isArray(group[key]) && Array.isArray(base[key]))
+            merged[key] = [...new Set([...base[key], ...group[key]])];
+    }
+    if (!('copies' in group) && ('targetLanguages' in group || 'sourceLanguage' in group))
+        merged.copies = {};
+    return merged;
+}
+/** The groups of a config, or the config itself as its only group. */
+export const groupsOf = (config) => config.groups ?? [config];
+/**
+ * The groups to work on, in config order, limited by name; unknown group or language names
+ * are an error (a typo must not turn into "nothing to do" or a green check).
+ */
+export function selectGroups(config, names, languages) {
+    const groups = groupsOf(config);
+    let selected = groups;
+    if (names?.length) {
+        const unknown = names.filter(name => !groups.some(g => g.name === name));
+        if (unknown.length > 0) {
+            throw new ConfigError(`Unknown group(s): ${unknown.join(', ')}. Groups: ${groups.map(g => g.name ?? '(none)').join(', ')}`);
+        }
+        selected = groups.filter(g => g.name !== undefined && names.includes(g.name));
+    }
+    const targets = new Set(selected.flatMap(g => g.targetLanguages));
+    const unknownLanguages = (languages ?? []).filter(lang => !targets.has(lang));
+    if (unknownLanguages.length > 0) {
+        throw new ConfigError(`Not in targetLanguages: ${unknownLanguages.join(', ')}`);
+    }
+    return selected;
+}
+function resolveSingle(input, root) {
     const config = { ...DEFAULTS, ...input, root };
     const fail = (message) => {
         throw new ConfigError(message);
@@ -94,7 +180,23 @@ export function resolveConfig(raw, root) {
             }
         }
     }
-    for (const key of ['maxTokensPerRun', 'concurrency', 'batchSize']) {
+    if (!isStringRecord(config.copies))
+        fail('"copies" must map locales to the locale they copy, e.g. { "en-GB": "en-US" }.');
+    for (const [target, from] of Object.entries(config.copies)) {
+        if (!isLanguageCode(target))
+            fail(`"copies": "${target}" is not a language code.`);
+        if (config.targetLanguages.includes(target))
+            fail(`"copies": "${target}" is also in targetLanguages.`);
+        if (from !== config.sourceLanguage && !config.targetLanguages.includes(from)) {
+            fail(`"copies.${target}": "${from}" must be the source language or one of targetLanguages.`);
+        }
+    }
+    if (!Array.isArray(config.plugins))
+        fail('"plugins" must be a list of module paths.');
+    if (config.dailyTokenBudget !== undefined && !(Number.isFinite(config.dailyTokenBudget) && config.dailyTokenBudget > 0)) {
+        fail('"dailyTokenBudget" must be a positive number.');
+    }
+    for (const key of ['maxTokensPerRun', 'concurrency', 'batchSize', 'chunkChars']) {
         if (!Number.isFinite(config[key]) || config[key] < 1)
             fail(`"${key}" must be a positive number.`);
     }
@@ -102,7 +204,7 @@ export function resolveConfig(raw, root) {
         if (typeof config[key] !== 'string' || config[key] === '')
             fail(`"${key}" must be a string.`);
     }
-    const known = new Set([...Object.keys(DEFAULTS), 'targetLanguages', 'files', 'context', 'tone', 'temperature', 'reasoningEffort', 'placeholders', '$schema']);
+    const known = new Set([...Object.keys(DEFAULTS), 'targetLanguages', 'files', 'context', 'tone', 'temperature', 'reasoningEffort', 'placeholders', 'dailyTokenBudget', 'name', '$schema']);
     const unknown = Object.keys(input).filter(key => !known.has(key));
     if (unknown.length > 0)
         fail(`Unknown config option(s): ${unknown.join(', ')}`);

package/dist/engine/context.d.ts

@@ -0,0 +1,81 @@
+import { Budget, BudgetExceededError } from '../budget.js';
+import { type Model } from '../llm.js';
+import type { Plugin } from '../plugins.js';
+import { PluginHost } from '../plugins.js';
+import type { State } from '../state.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[];
+    /** Only these groups (by name); default all, in config order. */
+    groups?: 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;
+    /** Re-translate every string of files matching these path patterns (hand edits stay protected). */
+    retranslateFiles?: string[];
+    /** Re-translate strings localewarden last wrote before this day (YYYY-MM-DD), or adopted. */
+    refreshBefore?: string;
+    /** 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;
+    /** Plugins to use instead of loading the ones listed in the config. */
+    plugins?: Plugin[];
+}
+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[];
+    /** Copies written (see `copies` in the config). */
+    filesCopied: string[];
+    tokens: number;
+    requests: number;
+    stoppedByBudget: boolean;
+    /** Why the run stopped early, when it did. */
+    stopReason?: string;
+    pendingReview: number;
+    dryRun: boolean;
+}
+export declare const emptyLanguageSummary: () => LanguageSummary;
+/** What every part of a run shares: options, state, budget, plugins and the summary. */
+export declare class RunContext {
+    readonly options: RunOptions;
+    readonly log: Logger;
+    readonly state: State;
+    readonly budget: Budget;
+    readonly plugins: PluginHost;
+    readonly summary: RunSummary;
+    private fatal;
+    constructor(options: RunOptions, log: Logger, state: State, budget: Budget, plugins: PluginHost);
+    get dryRun(): boolean;
+    counts(lang: string): LanguageSummary;
+    /** True once the budget is used up or the API refused the requests for good. */
+    get stopped(): boolean;
+    /** Records an API error: budget and fatal errors stop the run, others are logged. */
+    handleError(error: unknown, lang: string): void;
+    /** Throws the fatal API error, if there was one. */
+    rethrow(): void;
+}
+export { BudgetExceededError };

package/dist/engine/context.js

@@ -0,0 +1,75 @@
+import { BudgetExceededError } from '../budget.js';
+import { FatalModelError } from '../llm.js';
+export const consoleLogger = {
+    info: message => console.log(message),
+    warn: message => console.warn(`warning: ${message}`),
+    error: message => console.error(`error: ${message}`),
+};
+export const emptyLanguageSummary = () => ({
+    translated: 0,
+    revised: 0,
+    repaired: 0,
+    failed: 0,
+    protected: 0,
+    removed: 0,
+    planned: 0,
+    plannedChars: 0,
+});
+/** What every part of a run shares: options, state, budget, plugins and the summary. */
+export class RunContext {
+    options;
+    log;
+    state;
+    budget;
+    plugins;
+    summary;
+    fatal = null;
+    constructor(options, log, state, budget, plugins) {
+        this.options = options;
+        this.log = log;
+        this.state = state;
+        this.budget = budget;
+        this.plugins = plugins;
+        this.summary = {
+            languages: {},
+            filesWritten: [],
+            filesCopied: [],
+            tokens: 0,
+            requests: 0,
+            stoppedByBudget: false,
+            pendingReview: 0,
+            dryRun: Boolean(options.dryRun),
+        };
+    }
+    get dryRun() {
+        return this.summary.dryRun;
+    }
+    counts(lang) {
+        return (this.summary.languages[lang] ??= emptyLanguageSummary());
+    }
+    /** True once the budget is used up or the API refused the requests for good. */
+    get stopped() {
+        return this.fatal !== null || this.summary.stoppedByBudget;
+    }
+    /** Records an API error: budget and fatal errors stop the run, others are logged. */
+    handleError(error, lang) {
+        if (error instanceof BudgetExceededError) {
+            if (!this.summary.stoppedByBudget)
+                this.log.warn(`${error.message}; stopping. Run again to continue.`);
+            this.summary.stoppedByBudget = true;
+            this.summary.stopReason = error.message;
+        }
+        else if (error instanceof FatalModelError) {
+            this.fatal ??= error;
+        }
+        else {
+            this.log.warn(`[${lang}] ${error.message}`);
+        }
+    }
+    /** Throws the fatal API error, if there was one. */
+    rethrow() {
+        if (this.fatal)
+            throw this.fatal;
+    }
+}
+export { BudgetExceededError };

package/dist/engine/copies.d.ts

@@ -0,0 +1,9 @@
+import type { Config } from '../config.js';
+import { type LocaleFile } from '../files.js';
+import type { RunContext } from './context.js';
+/**
+ * Writes the locales that are copies of another one (`copies` in the config), e.g. store
+ * listings where en-GB is the en-US text. Runs after translating, so copies of target
+ * languages get the new translations. A copy is only written when its content differs.
+ */
+export declare function applyCopies(ctx: RunContext, config: Config, files: LocaleFile[]): void;

package/dist/engine/copies.js

@@ -0,0 +1,31 @@
+import path from 'node:path';
+import { readText, writeText } from '../files.js';
+/**
+ * Writes the locales that are copies of another one (`copies` in the config), e.g. store
+ * listings where en-GB is the en-US text. Runs after translating, so copies of target
+ * languages get the new translations. A copy is only written when its content differs.
+ */
+export function applyCopies(ctx, config, files) {
+    const only = ctx.options.languages;
+    for (const [target, from] of Object.entries(config.copies)) {
+        // With --lang, only copies of (or into) the selected languages.
+        if (only?.length && !only.includes(target) && !only.includes(from))
+            continue;
+        for (const file of files) {
+            const fromRel = file.pathFor(from);
+            const toRel = file.pathFor(target);
+            const toFile = path.join(config.root, toRel);
+            if (!path.resolve(toFile).startsWith(path.resolve(config.root) + path.sep))
+                continue;
+            const text = readText(path.join(config.root, fromRel));
+            if (text === null || readText(toFile) === text)
+                continue;
+            if (ctx.dryRun) {
+                ctx.log.info(`[${target}] ${toRel}: would copy from ${from}`);
+                continue;
+            }
+            writeText(toFile, text);
+            ctx.summary.filesCopied.push(toRel);
+        }
+    }
+}

package/dist/engine/planner.d.ts

@@ -0,0 +1,66 @@
+import type { Checker, Issue } from '../checks.js';
+import type { Config } from '../config.js';
+import { type JsonValue, type Leaf, type LocaleFile } from '../files.js';
+import type { PromptItem } from '../prompt.js';
+import type { Scope } from '../scope.js';
+import type { LanguageSummary, RunContext } from './context.js';
+/** A parsed source-language file. */
+export interface SourceFile {
+    file: LocaleFile;
+    doc: JsonValue;
+    text: string;
+    leaves: Leaf[];
+}
+export interface Repair {
+    key: string;
+    source: string;
+    issues: Issue[];
+}
+/** What to do with one file in one language. */
+export interface Plan {
+    file: LocaleFile;
+    lang: string;
+    counts: LanguageSummary;
+    sourceDoc: JsonValue;
+    sourceText: string;
+    targetRel: string;
+    targetFile: string;
+    targetText: string | null;
+    targetDoc: JsonValue | null;
+    /** Current values by key, updated as translations come in. */
+    values: Map<string, string>;
+    /** Strings to translate (new) or revise (source changed). */
+    work: PromptItem[];
+    repairs: Repair[];
+    removed: string[];
+    pluralExtras: Leaf[];
+    /**
+     * Translations taken into `values` but not yet recorded in the state. They are recorded
+     * only after the file was written, so a failed write is retried, not taken for a hand edit.
+     */
+    pending: {
+        key: string;
+        source: string;
+        value: string;
+    }[];
+}
+/** Everything the planner needs about the group being translated. */
+export interface GroupTools {
+    config: Config;
+    scope: Scope;
+    checker: Checker;
+}
+/**
+ * Decides, per string, whether to translate, revise, repair, adopt or protect it:
+ *
+ *   no translation yet                      -> translate
+ *   translation exists, never seen          -> adopt (unless it is the source copied over)
+ *   source changed since the last write     -> revise from the existing translation
+ *   value differs from what we wrote        -> hand edit: protect, list for review
+ *   --retranslate-all / --retranslate-files -> translate again (hand edits stay protected)
+ *   --refresh-before DATE, written earlier  -> translate again
+ *   --fix-flagged, check finds a problem    -> targeted repair (or revise if content is missing)
+ *
+ * Returns null when the target file cannot be used (outside the project, invalid JSON).
+ */
+export declare function planFile(ctx: RunContext, group: GroupTools, source: SourceFile, lang: string): Plan | null;

package/dist/engine/planner.js

@@ -0,0 +1,167 @@
+import path from 'node:path';
+import { isFixable, isUnchangedProse, muchShorter } from '../checks.js';
+import { flatten, isArbMetadata, missingPluralLeaves, parseDoc, pathPattern, readText, } from '../files.js';
+import { reviewId } from '../state.js';
+import { hash } from '../util.js';
+const matchesAny = (patterns, file, sourceLanguage) => patterns.some(re => re.test(file.id) || re.test(file.pathFor(sourceLanguage)));
+/**
+ * Decides, per string, whether to translate, revise, repair, adopt or protect it:
+ *
+ *   no translation yet                      -> translate
+ *   translation exists, never seen          -> adopt (unless it is the source copied over)
+ *   source changed since the last write     -> revise from the existing translation
+ *   value differs from what we wrote        -> hand edit: protect, list for review
+ *   --retranslate-all / --retranslate-files -> translate again (hand edits stay protected)
+ *   --refresh-before DATE, written earlier  -> translate again
+ *   --fix-flagged, check finds a problem    -> targeted repair (or revise if content is missing)
+ *
+ * Returns null when the target file cannot be used (outside the project, invalid JSON).
+ */
+export function planFile(ctx, group, source, lang) {
+    const { config, scope, checker } = group;
+    const { state, options, log } = ctx;
+    const { file } = source;
+    const counts = ctx.counts(lang);
+    const pluralExtras = missingPluralLeaves(source.leaves, lang);
+    const leaves = [...source.leaves, ...pluralExtras];
+    const sourceKeys = new Set(leaves.map(leaf => leaf.key));
+    const targetRel = file.pathFor(lang);
+    const targetFile = path.join(config.root, targetRel);
+    if (!path.resolve(targetFile).startsWith(path.resolve(config.root) + path.sep)) {
+        log.error(`${targetRel} is outside the project; skipped.`);
+        return null;
+    }
+    const targetText = readText(targetFile);
+    let targetDoc = null;
+    if (targetText !== null) {
+        try {
+            targetDoc = parseDoc(targetRel, targetText);
+        }
+        catch (error) {
+            log.error(`${targetRel} is not valid JSON (${error.message}); skipped. Fix it by hand.`);
+            return null;
+        }
+    }
+    const current = targetDoc === null ? new Map() : flatten(targetDoc);
+    const values = new Map(current);
+    const fresh = [];
+    const revise = [];
+    const repairs = [];
+    const forceFile = matchesAny((options.retranslateFiles ?? []).map(pathPattern), file, config.sourceLanguage);
+    const item = (key, sourceText, extra = {}) => ({
+        key,
+        source: sourceText,
+        maxLength: scope.maxLength(key),
+        file: file.id,
+        ...extra,
+    });
+    for (const { key, value: src } of leaves) {
+        const cur = current.get(key);
+        const entry = state.get(lang, file.id, key);
+        const sourceHash = hash(src);
+        if (src.trim() === '') {
+            values.set(key, src);
+            continue;
+        }
+        if (isArbMetadata(targetRel, key)) {
+            // Flutter ARB: "@@locale" names the target language; other metadata is copied.
+            values.set(key, key === '@@locale' ? lang : cur ?? src);
+            continue;
+        }
+        if (scope.isLiteral(key, src)) {
+            // Not text: keep a localized value someone set (e.g. a /de/ URL), else copy the source.
+            if (cur === undefined || cur.trim() === '')
+                values.set(key, src);
+            continue;
+        }
+        const hasValue = cur !== undefined && cur.trim() !== '';
+        if (hasValue) {
+            const id = reviewId(lang, file.id, key);
+            const review = state.review[id];
+            const curHash = hash(cur);
+            if (options.overwriteManual && (review || (entry && entry.value !== curHash))) {
+                delete state.review[id];
+                fresh.push(item(key, src));
+                continue;
+            }
+            if (review) {
+                // Counted only when something new needs a person's attention, not on every run.
+                if (review.status === 'approved' && review.valueHash !== curHash) {
+                    state.addReview(lang, file.id, key, 'edited-after-approval', cur);
+                    counts.protected++;
+                }
+                else if (entry && entry.source !== sourceHash) {
+                    state.addReview(lang, file.id, key, 'source-changed', cur);
+                    log.warn(`[${lang}] ${key}: source changed, but the translation was edited by hand; kept and listed for review`);
+                    counts.protected++;
+                }
+                state.set(lang, file.id, key, src, cur, false);
+                continue;
+            }
+            if (entry && entry.value !== curHash) {
+                const sourceChanged = entry.source !== sourceHash;
+                state.addReview(lang, file.id, key, sourceChanged ? 'source-changed' : 'manual-edit', cur);
+                state.set(lang, file.id, key, src, cur, false);
+                log.info(`[${lang}] ${key}: edited by hand; protected and listed for review`);
+                counts.protected++;
+                continue;
+            }
+        }
+        const stale = options.refreshBefore !== undefined && hasValue && (!entry || entry.date === '' || entry.date < options.refreshBefore);
+        if (!hasValue || options.retranslateAll || forceFile || stale) {
+            fresh.push(item(key, src));
+        }
+        else if (!entry) {
+            // First time localewarden sees this string: adopt an existing translation, unless
+            // it is just the source text copied over.
+            if (isUnchangedProse(src, cur, checker.placeholderRe))
+                fresh.push(item(key, src));
+            else
+                state.set(lang, file.id, key, src, cur, false);
+        }
+        else if (entry.source !== sourceHash) {
+            revise.push(item(key, src, { previous: cur }));
+        }
+        else if (options.fixFlagged) {
+            const failed = state.repairFailures[reviewId(lang, file.id, key)];
+            if (failed?.valueHash === hash(cur))
+                continue; // this value could not be fixed before
+            // Missing content needs more than a minimal correction: revise from the existing text.
+            if (muchShorter(lang, src, cur)) {
+                revise.push(item(key, src, { previous: cur, completing: true }));
+            }
+            else {
+                const issues = checker.checkString(lang, key, src, cur, file.id).filter(isFixable);
+                if (issues.length > 0)
+                    repairs.push({ key, source: src, issues });
+            }
+        }
+    }
+    // Strings removed from the source.
+    const removed = [...current.keys()].filter(key => !sourceKeys.has(key));
+    for (const key of new Set([...removed, ...state.keys(lang, file.id).filter(key => !sourceKeys.has(key))])) {
+        state.delete(lang, file.id, key);
+        delete state.review[reviewId(lang, file.id, key)];
+    }
+    const work = [...fresh, ...revise];
+    if (work.length + repairs.length + removed.length > 0) {
+        log.info(`[${lang}] ${targetRel}: ${fresh.length} new, ${revise.length} changed${repairs.length ? `, ${repairs.length} to repair` : ''}${removed.length ? `, ${removed.length} to remove` : ''}`);
+    }
+    return {
+        file,
+        lang,
+        counts,
+        sourceDoc: source.doc,
+        sourceText: source.text,
+        targetRel,
+        targetFile,
+        targetText,
+        targetDoc,
+        values,
+        work,
+        repairs,
+        removed,
+        pluralExtras,
+        pending: [],
+    };
+}

package/dist/engine/repair.d.ts

@@ -0,0 +1,16 @@
+import type { Checker } from '../checks.js';
+import type { Scope } from '../scope.js';
+import type { RunContext } from './context.js';
+import type { Plan } from './planner.js';
+import type { Translator } from './translator.js';
+/** 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;
+/**
+ * Targeted repairs (--fix-flagged): the model gets the existing translation and the
+ * findings, and must change only what fixes them. A repair is written only if the same
+ * checks pass afterwards, nothing hard broke and few words changed; a rejected one is
+ * recorded and not retried until the translation changes.
+ */
+export declare function runRepairs(ctx: RunContext, plan: Plan, checker: Checker, scope: Scope, translator: Translator): Promise<void>;

package/dist/engine/repair.js

@@ -0,0 +1,61 @@
+import { repairInstruction } from '../prompt.js';
+import { reviewId } from '../state.js';
+import { hash, today } from '../util.js';
+/** Words not shared by both texts, counted on the longer side (word-level LCS). */
+export function changedWords(before, after) {
+    const split = (text) => text.replace(/<[^>]+>/g, ' ').split(/\s+/).filter(Boolean).map(w => w.toLocaleLowerCase());
+    const a = split(before);
+    const b = split(after);
+    let prev = new Array(b.length + 1).fill(0);
+    for (let i = 1; i <= a.length; i++) {
+        const row = new Array(b.length + 1).fill(0);
+        for (let j = 1; j <= b.length; j++)
+            row[j] = a[i - 1] === b[j - 1] ? prev[j - 1] + 1 : Math.max(prev[j], row[j - 1]);
+        prev = row;
+    }
+    return Math.max(a.length, b.length) - prev[b.length];
+}
+/** A targeted repair may change a few words of a short string or a quarter of a long one. */
+export function tooManyChanges(before, after) {
+    const changed = changedWords(before, after);
+    const allowed = Math.max(6, Math.ceil(before.split(/\s+/).filter(Boolean).length * 0.25));
+    return changed > allowed ? `changed ${changed} words (allowed ${allowed})` : null;
+}
+/**
+ * Targeted repairs (--fix-flagged): the model gets the existing translation and the
+ * findings, and must change only what fixes them. A repair is written only if the same
+ * checks pass afterwards, nothing hard broke and few words changed; a rejected one is
+ * recorded and not retried until the translation changes.
+ */
+export async function runRepairs(ctx, plan, checker, scope, translator) {
+    const { state, log } = ctx;
+    const { lang, file, values, counts } = plan;
+    for (const { key, source, issues } of plan.repairs) {
+        if (ctx.stopped)
+            break;
+        const before = values.get(key) ?? '';
+        const problems = issues.map(issue => (issue.note ? `${issue.check}: ${issue.note}` : issue.check));
+        const after = await translator.translateOne(lang, { key, source, maxLength: scope.maxLength(key), file: file.id }, repairInstruction(before, problems));
+        const id = reviewId(lang, file.id, key);
+        let reason = after === null ? 'no answer' : null;
+        if (after !== null) {
+            const checks = new Set(issues.map(issue => issue.check));
+            const remaining = checker.checkString(lang, key, source, after, file.id).filter(issue => checks.has(issue.check));
+            reason =
+                checker.defect(lang, key, source, after, file.id).hard ??
+                    (remaining.length > 0 ? `still flagged: ${remaining.map(r => r.note ?? r.check).join('; ')}` : null) ??
+                    tooManyChanges(before, after);
+        }
+        if (reason || after === null) {
+            if (after !== null || !ctx.stopped) {
+                state.repairFailures[id] = { valueHash: hash(before), date: today(), problems, reason: reason ?? 'no answer', ...(after ? { attempted: after } : {}) };
+                log.warn(`[${lang}] ${key}: repair rejected (${reason})`);
+            }
+            continue;
+        }
+        delete state.repairFailures[id];
+        values.set(key, after);
+        plan.pending.push({ key, source, value: after });
+        counts.repaired++;
+    }
+}

package/dist/engine/sources.d.ts

@@ -0,0 +1,13 @@
+import type { Config } from '../config.js';
+import { type LocaleFile } from '../files.js';
+import type { PluginHost } from '../plugins.js';
+import type { Scope } from '../scope.js';
+import type { Logger } from './context.js';
+import type { SourceFile } from './planner.js';
+/**
+ * The source files of a group, without excluded ones, in the order plugins choose (they may
+ * also leave files out, e.g. blog posts scheduled for a later date).
+ */
+export declare function listFiles(config: Config, scope: Scope, plugins: PluginHost): LocaleFile[];
+/** Reads and parses the source files; unreadable ones are reported and skipped. */
+export declare function loadSources(config: Config, files: LocaleFile[], log: Logger): SourceFile[];