localewarden 0.1.1 → 0.3.0

package/dist/llm.js

@@ -1,4 +1,5 @@
 import { sleep } from './util.js';
+export { BudgetExceededError } from './budget.js';
 export class ModelError extends Error {
     status;
     retryAfterMs;
@@ -79,28 +80,21 @@ export class OpenAICompatibleModel {
         return { text: content.trim(), tokens: data.usage?.total_tokens ?? 0 };
     }
 }
-export class BudgetExceededError extends Error {
-}
 /**
- * Wraps a Model with retries, spacing between requests and the per-run token budget.
+ * Wraps a Model with retries, spacing between requests and the shared token budget.
  * The budget is checked before each request; the request that crosses it still completes.
  */
 export class Client {
     model;
-    maxTokens;
+    budget;
     options;
-    tokens = 0;
-    requests = 0;
     lastStart = 0;
     queue = Promise.resolve();
-    constructor(model, maxTokens, options = {}) {
+    constructor(model, budget, options = {}) {
         this.model = model;
-        this.maxTokens = maxTokens;
+        this.budget = budget;
         this.options = options;
     }
-    get budgetExceeded() {
-        return this.tokens >= this.maxTokens;
-    }
     /** Enforces a minimum gap between request starts across all parallel workers. */
     spacing() {
         const gap = this.options.minSpacingMs ?? 200;
@@ -116,13 +110,11 @@ export class Client {
     async complete(system, user, timeoutMs) {
         const retries = this.options.retries ?? 3;
         for (let attempt = 1;; attempt++) {
-            if (this.budgetExceeded)
-                throw new BudgetExceededError(`token budget of ${this.maxTokens.toLocaleString('en')} reached`);
+            this.budget.check();
             await this.spacing();
             try {
-                this.requests++;
                 const result = await this.model.complete(system, user, { timeoutMs });
-                this.tokens += result.tokens;
+                this.budget.record(result.tokens);
                 return result.text;
             }
             catch (error) {

package/dist/lock.d.ts

@@ -0,0 +1,13 @@
+export declare class LockError extends Error {
+}
+/**
+ * Takes <stateDir>/run.lock so two runs (say, CI and a local run), or a run and an edit in the
+ * web interface, cannot write the same state at once. Only one holder at a time, including
+ * within one process. A lock is stale when its process no longer exists on this machine, or
+ * when it was written on another machine (a lock file committed by mistake); a stale lock is
+ * taken over with an atomic rename, so two processes cannot both take it. Returns the
+ * function that releases it.
+ */
+export declare function acquireLock(stateDir: string): () => void;
+/** Runs `fn` while holding the lock (for short writes like review approvals and edits). */
+export declare function withLock<T>(stateDir: string, fn: () => T): T;

package/dist/lock.js

@@ -0,0 +1,91 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export class LockError extends Error {
+}
+const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM: the process exists but belongs to someone else.
+        return error.code === 'EPERM';
+    }
+};
+const readHolder = (file) => {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Takes <stateDir>/run.lock so two runs (say, CI and a local run), or a run and an edit in the
+ * web interface, cannot write the same state at once. Only one holder at a time, including
+ * within one process. A lock is stale when its process no longer exists on this machine, or
+ * when it was written on another machine (a lock file committed by mistake); a stale lock is
+ * taken over with an atomic rename, so two processes cannot both take it. Returns the
+ * function that releases it.
+ */
+export function acquireLock(stateDir) {
+    const file = path.join(stateDir, 'run.lock');
+    fs.mkdirSync(stateDir, { recursive: true });
+    const me = { pid: process.pid, host: os.hostname(), started: new Date().toISOString() };
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            const fd = fs.openSync(file, 'wx');
+            fs.writeSync(fd, JSON.stringify(me));
+            fs.closeSync(fd);
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                const holder = readHolder(file);
+                if (holder && holder.pid === me.pid && holder.started === me.started)
+                    fs.rmSync(file, { force: true });
+            };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const holder = readHolder(file);
+            const sameHost = !holder?.host || holder.host === os.hostname();
+            if (holder && holder.pid && sameHost && alive(holder.pid)) {
+                throw new LockError(`Another localewarden run is active (pid ${holder.pid}, started ${holder.started ?? 'at an unknown time'}). ` +
+                    `Wait for it to finish; if no run is active, delete ${file}.`);
+            }
+            // Stale: move it aside atomically. If another process got there first, the rename fails
+            // and the next attempt sees their fresh lock.
+            const aside = `${file}.stale-${process.pid}-${attempt}`;
+            try {
+                fs.renameSync(file, aside);
+                const moved = readHolder(aside);
+                if (moved && holder && (moved.pid !== holder.pid || moved.started !== holder.started)) {
+                    // We moved someone's fresh lock: put it back and stop.
+                    fs.renameSync(aside, file);
+                    throw new LockError(`Another localewarden run just started (pid ${moved.pid}).`);
+                }
+                fs.rmSync(aside, { force: true });
+            }
+            catch (renameError) {
+                if (renameError instanceof LockError)
+                    throw renameError;
+                // ENOENT: someone else took it over; try again.
+            }
+        }
+    }
+    throw new LockError(`Could not take the lock ${file}.`);
+}
+/** Runs `fn` while holding the lock (for short writes like review approvals and edits). */
+export function withLock(stateDir, fn) {
+    const release = acquireLock(stateDir);
+    try {
+        return fn();
+    }
+    finally {
+        release();
+    }
+}

package/dist/output.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Cleaning model answers. Models sometimes wrap a translation in commentary ("Here is the
+ * translation:"), code fences or quotes. That is stripped before the checks run; anything
+ * left over is caught by them.
+ */
+/** A model answer with lead-in commentary, code fences and wrapping quotes removed. */
+export declare function cleanOutput(source: string, text: string): string;
+/**
+ * A JSON array of `expected` elements from a model answer, or null. An element that is not a
+ * string or number (null, an object) is returned as null: that string is translated again on
+ * its own instead of becoming the text "null".
+ */
+export declare function parseArray(raw: string, expected: number): (string | null)[] | null;
+/**
+ * Splits a long text into chunks of at most `max` characters at paragraph breaks (or line
+ * breaks, if a paragraph is longer). The separators are kept so joining restores the layout.
+ */
+export declare function splitLongText(text: string, max: number): {
+    parts: string[];
+    separators: string[];
+};

package/dist/output.js

@@ -0,0 +1,76 @@
+/**
+ * Cleaning model answers. Models sometimes wrap a translation in commentary ("Here is the
+ * translation:"), code fences or quotes. That is stripped before the checks run; anything
+ * left over is caught by them.
+ */
+// "Here is the translation:" anywhere at the start; a bare "Translation:" only when it stands on
+// its own line, so a string that really starts with "Translation: …" is left alone.
+const LEAD_IN = /^\s*(?:(?:sure|certainly|of course)[,!.]?\s*)?(?:here(?:'s| is) (?:the|your|my) (?:translation|translated text)(?: in [^:\n]+)?\s*:\s*\n*|(?:translation|translated text)\s*:[ \t]*\n+)/i;
+/** A model answer with lead-in commentary, code fences and wrapping quotes removed. */
+export function cleanOutput(source, text) {
+    let out = text.trim();
+    const fenced = /^```[\w-]*\n([\s\S]*?)\n```$/.exec(out);
+    if (fenced && !source.includes('```'))
+        out = fenced[1].trim();
+    // Never strip what the source itself says.
+    if (!LEAD_IN.test(source))
+        out = out.replace(LEAD_IN, '');
+    const quoted = /^(["“«„「])([\s\S]*)(["”»“」])$/.exec(out);
+    const sourceQuoted = /^\s*["“«„「]/.test(source) && /["”»“」]\s*$/.test(source);
+    if (quoted && !sourceQuoted && !quoted[2].includes(quoted[1]))
+        out = quoted[2].trim();
+    return out;
+}
+/**
+ * A JSON array of `expected` elements from a model answer, or null. An element that is not a
+ * string or number (null, an object) is returned as null: that string is translated again on
+ * its own instead of becoming the text "null".
+ */
+export function parseArray(raw, expected) {
+    const json = raw.trim().replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '');
+    try {
+        const parsed = JSON.parse(json);
+        if (!Array.isArray(parsed) || parsed.length !== expected)
+            return null;
+        return parsed.map(value => (typeof value === 'string' ? value : typeof value === 'number' ? String(value) : null));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Splits a long text into chunks of at most `max` characters at paragraph breaks (or line
+ * breaks, if a paragraph is longer). The separators are kept so joining restores the layout.
+ */
+export function splitLongText(text, max) {
+    // Paragraph breaks first; a single paragraph longer than `max` is split at line breaks.
+    const byParagraph = text.split(/(\n\s*\n)/);
+    const pieces = [];
+    for (let i = 0; i < byParagraph.length; i += 2) {
+        const paragraph = byParagraph[i];
+        const lines = paragraph.length > max ? paragraph.split(/(\n)/) : [paragraph];
+        pieces.push(...lines);
+        if (i + 1 < byParagraph.length)
+            pieces.push(byParagraph[i + 1]);
+    }
+    const parts = [];
+    const separators = [];
+    let current = '';
+    let pendingSeparator = '';
+    for (let i = 0; i < pieces.length; i += 2) {
+        const paragraph = pieces[i];
+        const separator = pieces[i + 1] ?? '';
+        if (current && (current + pendingSeparator + paragraph).length > max) {
+            parts.push(current);
+            separators.push(pendingSeparator);
+            current = paragraph;
+        }
+        else {
+            current = current ? current + pendingSeparator + paragraph : paragraph;
+        }
+        pendingSeparator = separator;
+    }
+    if (current)
+        parts.push(current);
+    return { parts, separators };
+}

package/dist/placeholders.js

@@ -6,7 +6,8 @@
 export const DEFAULT_PLACEHOLDER_PATTERNS = [
     '\\{\\{\\s*[\\w.-]+\\s*\\}\\}', // {{name}}       i18next, Handlebars, vue-i18n
     '\\{\\s*[\\w.-]+\\s*\\}', //        {name}         ICU, react-intl, i18next (custom)
-    '%(?:\\d+\\$)?[-+0#]*\\d*(?:\\.\\d+)?[sdifuxXeEgGc@]', // %s %d %1$s %.2f  printf, Android, iOS
+    // Not followed by a letter: Hungarian writes suffixes after percent signs ("100%-ig").
+    '%(?:\\d+\\$)?[-+0#]*\\d*(?:\\.\\d+)?[sdifuxXeEgGc@](?![A-Za-z\\u00C0-\\u024F])', // %s %d %1$s %.2f  printf, Android, iOS
     '%\\([\\w.-]+\\)[sdif]', //        %(name)s       Python
     '%\\{[\\w.-]+\\}', //               %{name}        Ruby, rails-i18n
     '\\$\\{[\\w.-]+\\}', //             ${name}        template literals

package/dist/plugins.d.ts

@@ -0,0 +1,72 @@
+import type { Config } from './config.js';
+/**
+ * Plugins add project rules without forking localewarden: extra checks, prompt notes,
+ * post-processing of model output, and the order in which files are translated.
+ * A plugin is an ES module whose default export is a plugin object, or a function that
+ * receives the options from the config and returns one.
+ *
+ *   "plugins": ["./tools/my-rules.mjs", { "module": "./tools/blog.mjs", "options": { "today": "2026-10-09" } }]
+ *
+ * This interface is experimental in 0.x: it may change in a minor version.
+ */
+export interface StringContext {
+    lang: string;
+    key: string;
+    /** File id: the path pattern with {lang}, e.g. "locales/{lang}/common.json". */
+    file: string;
+    source: string;
+    text: string;
+}
+export interface PluginIssue {
+    /** Check name, shown in `localewarden check` (e.g. "regional-term"). */
+    check: string;
+    note?: string;
+    /** "error" blocks writing a translation and fails `check`; default "warning". */
+    severity?: 'error' | 'warning';
+    /** May `--fix-flagged` ask the model to fix it? Default false. */
+    fixable?: boolean;
+}
+export interface FileInfo {
+    /** File id with {lang}. */
+    id: string;
+    /** Path of the source-language file, relative to the project. */
+    sourcePath: string;
+}
+export interface Plugin {
+    name: string;
+    /** Extra findings for one translated string. */
+    checks?(ctx: StringContext): PluginIssue[] | void;
+    /** Extra prompt text for a batch of strings (e.g. meanings of terms they contain). */
+    promptNotes?(ctx: {
+        lang: string;
+        items: {
+            key: string;
+            source: string;
+        }[];
+    }): string | void;
+    /** Rewrites a model answer before it is checked and written (e.g. number formats). */
+    postProcess?(ctx: StringContext): string | void;
+    /** Reorders or filters the source files of a group (e.g. newest blog posts first). */
+    order?(files: FileInfo[], ctx: {
+        group?: string;
+    }): FileInfo[] | void;
+}
+export type PluginSpec = string | {
+    module: string;
+    options?: unknown;
+};
+/** Loads the plugins listed in the config, relative to the config file. */
+export declare function loadPlugins(config: Pick<Config, 'plugins' | 'root'>): Promise<Plugin[]>;
+/** Calls plugin hooks; an exception names the plugin that threw it. */
+export declare class PluginHost {
+    readonly plugins: Plugin[];
+    constructor(plugins?: Plugin[]);
+    private call;
+    checks(ctx: StringContext): PluginIssue[];
+    promptNotes(lang: string, items: {
+        key: string;
+        source: string;
+    }[]): string;
+    postProcess(ctx: StringContext): string;
+    order(files: FileInfo[], group?: string): FileInfo[];
+}

package/dist/plugins.js

@@ -0,0 +1,71 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** Loads the plugins listed in the config, relative to the config file. */
+export async function loadPlugins(config) {
+    const plugins = [];
+    for (const spec of config.plugins ?? []) {
+        const modulePath = typeof spec === 'string' ? spec : spec.module;
+        const options = typeof spec === 'string' ? undefined : spec.options;
+        const file = path.resolve(config.root, modulePath);
+        let exported;
+        try {
+            exported = (await import(pathToFileURL(file).href)).default;
+        }
+        catch (error) {
+            throw new Error(`Could not load plugin ${modulePath}: ${error.message}`);
+        }
+        const plugin = (typeof exported === 'function' ? await exported(options) : exported);
+        if (!plugin || typeof plugin !== 'object' || typeof plugin.name !== 'string') {
+            throw new Error(`Plugin ${modulePath} must export a plugin object with a "name" (or a function returning one).`);
+        }
+        plugins.push(plugin);
+    }
+    return plugins;
+}
+/** Calls plugin hooks; an exception names the plugin that threw it. */
+export class PluginHost {
+    plugins;
+    constructor(plugins = []) {
+        this.plugins = plugins;
+    }
+    call(plugin, hook, fn) {
+        try {
+            return fn();
+        }
+        catch (error) {
+            throw new Error(`Plugin "${plugin.name}" failed in ${hook}: ${error.message}`);
+        }
+    }
+    checks(ctx) {
+        return this.plugins.flatMap(p => (p.checks ? this.call(p, 'checks', () => p.checks(ctx)) ?? [] : []));
+    }
+    promptNotes(lang, items) {
+        return this.plugins
+            .map(p => (p.promptNotes ? this.call(p, 'promptNotes', () => p.promptNotes({ lang, items })) : undefined))
+            .filter((note) => Boolean(note))
+            .map(note => ` ${note.trim()}`)
+            .join('');
+    }
+    postProcess(ctx) {
+        let text = ctx.text;
+        for (const p of this.plugins) {
+            if (!p.postProcess)
+                continue;
+            const next = this.call(p, 'postProcess', () => p.postProcess({ ...ctx, text }));
+            if (typeof next === 'string')
+                text = next;
+        }
+        return text;
+    }
+    order(files, group) {
+        let result = files;
+        for (const p of this.plugins) {
+            if (!p.order)
+                continue;
+            const next = this.call(p, 'order', () => p.order(result, { group }));
+            if (Array.isArray(next))
+                result = next;
+        }
+        return result;
+    }
+}

package/dist/project.d.ts

@@ -1,8 +1,12 @@
 import { type CheckName } from './checks.js';
-import type { Config } from './config.js';
+import { type Config } from './config.js';
+import { type Plugin } from './plugins.js';
 export interface Finding {
     lang: string;
-    check: CheckName;
+    /** Built-in check name or a plugin's check name. */
+    check: CheckName | (string & {});
+    /** Group name, when the config has groups. */
+    group?: string;
     severity: 'error' | 'warning';
     file: string;
     key: string;
@@ -10,9 +14,33 @@ export interface Finding {
     note?: string;
 }
 /**
- * Runs the quality checks over every translated string. Approved hand edits are skipped
- * except for placeholder and script errors, which break the app either way.
+ * Short sibling strings (same parent key) that differ in the source but got the same
+ * translation: answer options, tabs or menu items the user can no longer tell apart.
  */
-export declare function checkProject(config: Config, languages?: string[]): Finding[];
+export declare function collapsedSiblings(source: Map<string, string>, target: Map<string, string>): {
+    key: string;
+    note: string;
+}[];
+export interface CheckOptions {
+    /** Subset of the target languages. */
+    languages?: string[];
+    /** Only these groups (by name). */
+    groups?: string[];
+    /** Loaded plugins (see loadPlugins); their checks run too. */
+    plugins?: Plugin[];
+}
+/**
+ * Runs the quality checks over every translated string of every group. Approved strings are
+ * skipped except for errors (placeholder, unsafe, script, plugin errors), which break the
+ * software either way.
+ */
+export declare function checkProject(config: Config, optionsOrLanguages?: CheckOptions | string[]): Finding[];
+/**
+ * Repairs placeholder findings that have exactly one possible fix: the source has one
+ * placeholder and the translation one brace token with another name ("{heures}" for
+ * "{hours}"). The file text is edited in place, so its formatting stays as it is.
+ * Returns the repaired findings.
+ */
+export declare function fixPlaceholders(config: Config, findings: Finding[]): Finding[];
 /** Table of finding counts per language and check. */
 export declare function summaryTable(findings: Finding[], languages: string[]): string;