locai 2.6.1 → 2.7.0

package/dist/utils/quality/code-block-checker.d.ts

@@ -1,8 +1,19 @@
+/** Details for a code block count mismatch */
+export interface CodeBlockCountDetails {
+    sourceCount: number;
+    translatedCount: number;
+}
+/** Details for a code block whose content changed */
+export interface CodeBlockModifiedDetails {
+    index: number;
+    sourceCode: string;
+    translatedCode: string;
+}
 export interface CodeBlockIssue {
     type: "code-block-count" | "code-block-modified" | "code-block-restore";
     severity: "error" | "critical";
     message: string;
-    details?: any;
+    details?: CodeBlockCountDetails | CodeBlockModifiedDetails;
 }
 export interface CodeBlockFixResult {
     text: string;
@@ -40,10 +51,7 @@ declare class CodeBlockChecker {
     /**
      * Restore missing code blocks from source.
      */
-    restoreCodeBlocks(sourceText: string, translatedText: string, sourceCodeBlocks: CodeBlock[]): {
-        text: string;
-        appliedFixes: any[];
-    };
+    restoreCodeBlocks(sourceText: string, translatedText: string, sourceCodeBlocks: CodeBlock[]): Pick<CodeBlockFixResult, "text" | "appliedFixes">;
     /**
      * Protect code blocks before translation.
      * Replaces code blocks with tokens to prevent translation.

package/dist/utils/quality/index.d.ts

@@ -1,4 +1,5 @@
 import BaseChecker, { CheckerOptions, FixResult, ValidationResult } from "./base-checker.js";
+import { LengthCheckOptions } from "./length-checker.js";
 /**
  * Main Quality Checker Class.
  * Orchestrates various quality checks and fixes for translated text.
@@ -26,7 +27,7 @@ declare class QualityChecker extends BaseChecker {
     /**
      * Validate translated text against source text.
      */
-    validate(sourceText: string, translatedText: string, options?: Record<string, any>): ValidationResult;
+    validate(sourceText: string, translatedText: string, options?: LengthCheckOptions): ValidationResult;
     /**
      * Validate and attempt to fix translated text.
      */

package/dist/utils/quality/index.js

@@ -43,7 +43,10 @@ class QualityChecker extends BaseChecker {
         this.lengthChecker = new LengthChecker();
         this.textSanitizer = new TextSanitizer();
         this.quoteBalanceChecker = new QuoteBalanceChecker();
-        this.styleGuideChecker = new StyleGuideChecker(this.styleGuide);
+        this.styleGuideChecker = new StyleGuideChecker({
+            ...this.styleGuide,
+            conventions: this.rules.styleGuide?.conventions,
+        });
         this.markdownChecker = new MarkdownChecker();
         this.codeBlockChecker = new CodeBlockChecker();
         this.specialCharactersChecker = new SpecialCharactersChecker();
@@ -54,51 +57,37 @@ class QualityChecker extends BaseChecker {
     validate(sourceText, translatedText, options = {}) {
         const issues = [];
         if (this.rules.placeholderConsistency) {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             issues.push(...this.placeholderChecker.checkPlaceholders(sourceText, translatedText));
         }
         if (this.rules.htmlTagsConsistency) {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             issues.push(...this.htmlTagChecker.checkHtmlTags(sourceText, translatedText));
         }
         if (this.rules.punctuationCheck) {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             issues.push(...this.punctuationChecker.checkPunctuation(sourceText, translatedText));
         }
         // Quote balance validation
         if (this.rules.quoteBalanceCheck !== false) {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             issues.push(...this.quoteBalanceChecker.checkQuoteBalance(translatedText));
-            issues.push(
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            ...this.quoteBalanceChecker.validateQuoteConsistency(sourceText, translatedText));
+            issues.push(...this.quoteBalanceChecker.validateQuoteConsistency(sourceText, translatedText));
         }
         if (this.rules.lengthValidation) {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             issues.push(...this.lengthChecker.checkLength(sourceText, translatedText, options));
         }
         // Style guide validation
         if (this.styleGuide && this.styleGuideChecker) {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             issues.push(...this.styleGuideChecker.checkStyleGuide(sourceText, translatedText));
         }
         // Markdown preservation
         if (this.rules.markdownPreservation) {
-            issues.push(
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            ...this.markdownChecker.checkMarkdownPreservation(sourceText, translatedText));
+            issues.push(...this.markdownChecker.checkMarkdownPreservation(sourceText, translatedText));
         }
         // Code block preservation
         if (this.rules.codeBlockPreservation) {
-            issues.push(
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            ...this.codeBlockChecker.checkCodeBlockPreservation(sourceText, translatedText));
+            issues.push(...this.codeBlockChecker.checkCodeBlockPreservation(sourceText, translatedText));
         }
         // Special characters preservation
         if (this.rules.specialCharacters) {
-            issues.push(
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            ...this.specialCharactersChecker.checkSpecialCharacters(sourceText, translatedText));
+            issues.push(...this.specialCharactersChecker.checkSpecialCharacters(sourceText, translatedText));
         }
         if (this.rules.sanitizeOutput) {
             translatedText = this.sanitizeTranslation(translatedText);
@@ -124,21 +113,18 @@ class QualityChecker extends BaseChecker {
         if (this.rules.placeholderConsistency) {
             const result = this.placeholderChecker.fixPlaceholders(sourceText, fixedText);
             fixedText = result.text;
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             issues.push(...result.foundIssues);
             fixes.push(...result.appliedFixes);
         }
         if (this.rules.htmlTagsConsistency) {
             const result = this.htmlTagChecker.fixHtmlTags(sourceText, fixedText);
             fixedText = result.text;
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             issues.push(...result.foundIssues);
             fixes.push(...result.appliedFixes);
         }
         if (this.rules.punctuationCheck) {
             const result = this.punctuationChecker.fixPunctuation(sourceText, fixedText);
             fixedText = result.text;
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             issues.push(...result.foundIssues);
             fixes.push(...result.appliedFixes);
         }
@@ -146,7 +132,6 @@ class QualityChecker extends BaseChecker {
         if (this.rules.quoteBalanceCheck !== false) {
             const result = this.quoteBalanceChecker.fixQuoteBalance(fixedText);
             fixedText = result.text;
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             issues.push(...result.foundIssues);
             fixes.push(...result.appliedFixes);
         }
@@ -154,7 +139,6 @@ class QualityChecker extends BaseChecker {
         if (this.styleGuide && this.styleGuideChecker) {
             const result = this.styleGuideChecker.fixStyleGuide(sourceText, fixedText);
             fixedText = result.text;
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             issues.push(...result.foundIssues);
             fixes.push(...result.appliedFixes);
         }
@@ -162,7 +146,6 @@ class QualityChecker extends BaseChecker {
         if (this.rules.markdownPreservation) {
             const result = this.markdownChecker.fixMarkdownPreservation(sourceText, fixedText);
             fixedText = result.text;
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             issues.push(...result.foundIssues);
             fixes.push(...result.appliedFixes);
         }
@@ -170,7 +153,6 @@ class QualityChecker extends BaseChecker {
         if (this.rules.codeBlockPreservation) {
             const result = this.codeBlockChecker.fixCodeBlockPreservation(sourceText, fixedText);
             fixedText = result.text;
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             issues.push(...result.foundIssues);
             fixes.push(...result.appliedFixes);
         }
@@ -178,7 +160,6 @@ class QualityChecker extends BaseChecker {
         if (this.rules.specialCharacters) {
             const result = this.specialCharactersChecker.fixSpecialCharacters(sourceText, fixedText);
             fixedText = result.text;
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             issues.push(...result.foundIssues);
             fixes.push(...result.appliedFixes);
         }

package/dist/utils/quality/length-checker.d.ts

@@ -1,5 +1,35 @@
+export type LengthMode = "strict" | "flexible" | "exact" | "relaxed" | "smart";
+/** Modes whose tolerance is a single symmetric deviation */
+export type StandardLengthMode = Exclude<LengthMode, "smart">;
+/** Allowed deviation as a fraction of the source length (e.g. max 0.2 = up to 20% longer) */
+export interface LengthDeviationBounds {
+    min?: number;
+    max?: number;
+}
+export interface SmartLengthRules {
+    /** Symmetric tolerance used when no language/context bound applies */
+    default?: number;
+    byLanguage?: Record<string, LengthDeviationBounds>;
+    byContext?: Record<string, LengthDeviationBounds>;
+}
+export interface LengthControlRules extends Partial<Record<StandardLengthMode, number>> {
+    smart?: SmartLengthRules;
+}
+/** The `lengthControl` section of the configuration */
+export interface LengthControlOptions {
+    mode?: LengthMode;
+    rules?: LengthControlRules;
+}
+/** Options consulted by {@link LengthChecker.checkLength} */
+export interface LengthCheckOptions {
+    lengthControl?: LengthControlOptions;
+    targetLang?: string;
+    detectedContext?: {
+        category?: string;
+    };
+}
 export interface LengthConfig {
-    mode: "strict" | "flexible" | "exact" | "relaxed" | "smart";
+    mode: LengthMode;
     maxDeviation: number;
     minDeviation: number;
     targetLang?: string;
@@ -34,7 +64,7 @@ declare class LengthChecker {
     /**
      * Check if translated text length is acceptable.
      */
-    checkLength(source: string, translated: string, options?: any): LengthIssue[];
+    checkLength(source: string, translated: string, options?: LengthCheckOptions): LengthIssue[];
     /**
      * Calculate length of text ignoring whitespace.
      */
@@ -42,15 +72,15 @@ declare class LengthChecker {
     /**
      * Get configuration for length check.
      */
-    getConfig(options: any): LengthConfig;
+    getConfig(options: LengthCheckOptions): LengthConfig;
     /**
      * Get configuration for smart mode.
      */
-    getSmartModeConfig(lengthControl: any, targetLang: string, context: string): LengthConfig;
+    getSmartModeConfig(lengthControl: LengthControlOptions, targetLang: string, context: string): LengthConfig;
     /**
      * Get configuration for standard mode.
      */
-    getStandardModeConfig(lengthControl: any, mode: any, targetLang: string, context: string): LengthConfig;
+    getStandardModeConfig(lengthControl: LengthControlOptions, mode: StandardLengthMode, targetLang: string, context: string): LengthConfig;
     /**
      * Calculate allowed length ratio range.
      */

package/dist/utils/quality/length-checker.js

@@ -52,7 +52,7 @@ class LengthChecker {
                     type: "length",
                     severity: "error",
                     message: "Length validation failed due to technical error",
-                    details: { error: error.message },
+                    details: { error: error instanceof Error ? error.message : String(error) },
                 },
             ];
         }
@@ -100,8 +100,7 @@ class LengthChecker {
     getStandardModeConfig(lengthControl, mode, targetLang, context) {
         const deviation = lengthControl.rules?.[mode] || this.defaultConfig.maxDeviation;
         return {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            mode: mode,
+            mode,
             targetLang,
             context,
             maxDeviation: deviation,

package/dist/utils/quality/markdown-checker.d.ts

@@ -3,8 +3,19 @@ export interface MarkdownIssue {
     severity: "error" | "warning" | "critical";
     message: string;
     pattern?: string;
-    details?: any;
+    details?: {
+        sourceCount: number;
+        translatedCount: number;
+    };
+}
+/** A markdown link captured from source text */
+export interface MarkdownLink {
+    full: string;
+    text: string;
+    url: string;
 }
+/** A captured markdown element: the matched text, or the parts of a link */
+export type MarkdownElement = string | MarkdownLink;
 export interface MarkdownFixResult {
     text: string;
     foundIssues: MarkdownIssue[];
@@ -35,15 +46,11 @@ declare class MarkdownChecker {
     /**
      * Extract markdown elements from text.
      */
-    extractMarkdownElements(text: string): Record<string, any[]>;
+    extractMarkdownElements(text: string): Record<string, MarkdownElement[]>;
     /**
      * Restore markdown elements that were lost in translation.
      */
-    restoreMarkdownElements(text: string, elements: any[], type: string): {
-        text: string;
-        foundIssues: MarkdownIssue[];
-        appliedFixes: any[];
-    };
+    restoreMarkdownElements(text: string, elements: MarkdownElement[], type: string): MarkdownFixResult;
     /**
      * Fix broken markdown links.
      */

package/dist/utils/quality/special-characters-checker.d.ts

@@ -1,9 +1,26 @@
+/** Details for a per-category character count mismatch */
+export interface SpecialCharCountDetails {
+    sourceChars: string[];
+    translatedChars: string[];
+    missing: string[];
+    extra: string[];
+}
+/** Details for a special character that disappeared from the translation */
+export interface SpecialCharSubstitutionDetails {
+    originalChar: string;
+    charCode: number;
+}
+/** Details for an emoji count mismatch */
+export interface EmojiDetails {
+    sourceEmojis: string[];
+    translatedEmojis: string[];
+}
 export interface SpecialCharIssue {
     type: "special-characters" | "special-character-substitution" | "emoji-preservation" | "missing-special-chars" | "character-substitution";
     category?: string;
     severity: "error" | "warning";
     message: string;
-    details?: any;
+    details?: SpecialCharCountDetails | SpecialCharSubstitutionDetails | EmojiDetails;
 }
 export interface SpecialCharFixResult {
     text: string;

package/dist/utils/quality/special-characters-checker.js

@@ -200,7 +200,6 @@ class SpecialCharactersChecker {
             if (check && fixedText.includes(wrong)) {
                 const count = (fixedText.match(new RegExp(wrong, "g")) || []).length;
                 foundIssues.push({
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
                     type: "character-substitution",
                     severity: "warning", // Added severity
                     message: `Found ${count} instances of "${wrong}" that should be "${correct}"`,

package/dist/utils/quality/style-guide-checker.d.ts

@@ -8,7 +8,7 @@ export interface StyleGuideConfig {
     conventions?: {
         useOxfordComma?: boolean;
         useSentenceCase?: boolean;
-        [key: string]: any;
+        [convention: string]: boolean | undefined;
     };
 }
 export interface StyleIssue {

package/dist/utils/quality/style-guide-checker.js

@@ -21,7 +21,6 @@ class StyleGuideChecker {
     /**
      * Check if text follows style guide conventions.
      */
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     checkStyleGuide(_sourceText, translatedText) {
         const issues = [];
         if (this.styleGuide.conventions.useOxfordComma) {
@@ -85,7 +84,6 @@ class StyleGuideChecker {
     /**
      * Fix style guide issues.
      */
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     fixStyleGuide(sourceText, translatedText) {
         let fixedText = translatedText;
         const foundIssues = [];

package/dist/utils/quality/tone-verifier.js

@@ -14,7 +14,7 @@ export class ToneVerifier {
             // Try to get a specific "judge" provider if configured, otherwise default
             this.provider = ProviderFactory.getProvider(providerName, true);
         }
-        catch (error) {
+        catch {
             // If specific provider fails, might fall back to any available
             const available = ProviderFactory.getAvailableProviders();
             if (available.length > 0) {

package/dist/utils/rate-limiter.d.ts

@@ -7,6 +7,22 @@ export interface RateLimiterConfig {
         concurrency?: number;
     }>;
 }
+export interface ProviderStatus {
+    queueSize: number;
+    processing: number;
+    requestsUsed: number;
+    requestsLimit: number;
+    resetIn: number;
+    errorRate: number;
+    adjustments: {
+        rpm: number;
+        concurrency: number;
+    };
+    config: {
+        maxConcurrent: number;
+        rpm: number;
+    };
+}
 /**
  * Handles API rate limiting and request throttling.
  * Supports provider-specific limits and adaptive throttling.
@@ -57,7 +73,7 @@ declare class RateLimiter {
      * Get complete rate limiter status.
      * @returns Status object including active metrics.
      */
-    getStatus(): Record<string, any>;
+    getStatus(): Record<string, ProviderStatus>;
     /**
      * Get current configuration.
      * @returns Configuration object.

package/dist/utils/rate-limiter.js

@@ -122,7 +122,6 @@ class RateLimiter {
      * @param priority - Task priority (higher is better).
      * @returns Task result.
      */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     async enqueue(provider, task, priority = 0) {
         provider = provider.toLowerCase();
         if (!this.providers[provider]) {
@@ -131,7 +130,8 @@ class RateLimiter {
         return new Promise((resolve, reject) => {
             const queueItem = {
                 task,
-                resolve,
+                // Only ever called with this item's own task result, which is a T.
+                resolve: resolve,
                 reject,
                 timestamp: Date.now(),
                 priority,
@@ -194,7 +194,7 @@ class RateLimiter {
                             item.reject(new Error(`Request timed out in queue after ${this.config.queueTimeout}ms`));
                         }
                         catch (error) {
-                            console.error(`Failed to reject timed out request: ${error.message}`);
+                            console.error(`Failed to reject timed out request: ${error instanceof Error ? error.message : String(error)}`);
                         }
                     });
                 });
@@ -228,12 +228,15 @@ class RateLimiter {
             }
             catch (error) {
                 this._trackErrorRate(provider, true);
-                console.error(`Provider ${provider} task failed:`, {
-                    error: error.message,
-                    queueTime: queueTime,
-                    processingTime: performance.now() - startTime,
-                    queueSize: queue.length,
-                });
+                // The caller reports the failure; the per-attempt details are for --debug
+                if (process.env.DEBUG === "true") {
+                    console.error(`Provider ${provider} task failed:`, {
+                        error: error instanceof Error ? error.message : String(error),
+                        queueTime: queueTime,
+                        processingTime: performance.now() - startTime,
+                        queueSize: queue.length,
+                    });
+                }
                 reject(error);
             }
             finally {
@@ -337,9 +340,7 @@ class RateLimiter {
      * Get complete rate limiter status.
      * @returns Status object including active metrics.
      */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     getStatus() {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const status = {};
         Object.entries(this.providers).forEach(([name, config]) => {
             const errorRates = this.metrics.errorRates[name];

package/dist/utils/retry-helper.d.ts

@@ -1,6 +1,24 @@
 /**
  * Retry helper for API operations with exponential backoff
  */
+/**
+ * Error-like value thrown by a retried operation. The retry logic reads
+ * `status` / `code` / `message` and annotates the error with retry metadata.
+ */
+export interface RetryableError {
+    status?: number;
+    code?: string;
+    message?: string;
+    retryInfo?: RetryInfo;
+    retryStats?: RetryStats;
+}
+export interface RetryInfo {
+    attemptNumber: number;
+    maxRetries: number;
+    willRetry: boolean;
+    context: Record<string, unknown>;
+    provider?: string;
+}
 export interface RetryOptions {
     provider?: string;
     perProviderRetry?: Record<string, Partial<RetryConfig>>;
@@ -9,8 +27,8 @@ export interface RetryOptions {
     initialDelay?: number;
     maxDelay?: number;
     context?: string;
-    logContext?: Record<string, any>;
-    retryCondition?: (error: any, attempts: number, maxRetries: number) => boolean | Promise<boolean>;
+    logContext?: Record<string, unknown>;
+    retryCondition?: (error: RetryableError, attempts: number, maxRetries: number) => boolean | Promise<boolean>;
 }
 export interface RetryConfig {
     maxRetries: number;
@@ -40,7 +58,7 @@ declare class RetryHelper {
      * Default retry condition based on error type.
      * Checks against retryableErrors list.
      */
-    static defaultRetryCondition(error: any, retryableErrors?: string[]): boolean;
+    static defaultRetryCondition(error: RetryableError, retryableErrors?: string[]): boolean;
     /**
      * Promise-based delay.
      */

package/dist/utils/retry-helper.js

@@ -60,7 +60,12 @@ class RetryHelper {
                 }
                 return result;
             }
-            catch (error) {
+            catch (caught) {
+                // Errors are annotated with retry metadata below, which a primitive rejection
+                // (a thrown string, undefined) cannot hold; wrap those so the message survives.
+                const error = typeof caught === "object" && caught !== null
+                    ? caught
+                    : new Error(String(caught));
                 attempts++;
                 lastError = error;
                 if (!error.retryInfo) {
@@ -126,7 +131,10 @@ class RetryHelper {
             return true;
         }
         // Check for server errors (5xx)
-        if (retryableErrors.includes("server") && error.status >= 500 && error.status < 600) {
+        if (retryableErrors.includes("server") &&
+            error.status !== undefined &&
+            error.status >= 500 &&
+            error.status < 600) {
             return true;
         }
         // Check for unknown/general errors
@@ -152,7 +160,7 @@ class RetryHelper {
                 error.message?.includes("connection")) {
                 return true;
             }
-            return error.status >= 500 || !error.status;
+            return (error.status !== undefined && error.status >= 500) || !error.status;
         }
         return false;
     }

package/dist/utils/review-queue.d.ts

@@ -0,0 +1,45 @@
+import type { ConfidenceResult } from "./confidence-scorer.js";
+/** One key in one target language. */
+export interface TranslationRef {
+    language: string;
+    key: string;
+}
+/** A translation flagged by confidence scoring, queued for `locai review`. */
+export interface ReviewQueueItem extends TranslationRef {
+    source: string;
+    translation: string;
+    confidence: ConfidenceResult;
+    sourceLang: string;
+    category: string;
+    /** Scored below rejectThreshold, so the translation was not written to the locale file. */
+    rejected: boolean;
+    timestamp: string;
+}
+/** Content of `.localize-cache/review-queue.json`. */
+export interface ReviewQueueFile {
+    timestamp: string;
+    items: ReviewQueueItem[];
+}
+/** The review queue file of the project in the working directory. */
+export declare const reviewQueuePath: () => string;
+/**
+ * Read the review queue.
+ * @returns The queued items, or null when there is no queue file.
+ */
+export declare function readReviewQueue(): ReviewQueueItem[] | null;
+/**
+ * Add the flagged translations of a run to the review queue. Queued items for translations the
+ * run scored again are dropped first: the new score replaces them.
+ * @param scored - Every translation the run scored.
+ * @param flagged - The translations the run flagged for review or rejected.
+ * @returns The queue file and the number of items it now holds.
+ */
+export declare function updateReviewQueue(scored: TranslationRef[], flagged: ReviewQueueItem[]): {
+    file: string;
+    size: number;
+};
+/**
+ * Remove reviewed translations from the review queue.
+ * @param reviewed - The translations a review approved, edited or rejected.
+ */
+export declare function removeFromReviewQueue(reviewed: TranslationRef[]): void;

package/dist/utils/review-queue.js

@@ -0,0 +1,53 @@
+import fs from "fs";
+import path from "path";
+/** The review queue file of the project in the working directory. */
+export const reviewQueuePath = () => path.join(process.cwd(), ".localize-cache", "review-queue.json");
+/** Identity of a queued translation: its language and key. */
+const refId = ({ language, key }) => JSON.stringify([language, key]);
+/**
+ * Read the review queue.
+ * @returns The queued items, or null when there is no queue file.
+ */
+export function readReviewQueue() {
+    const file = reviewQueuePath();
+    if (!fs.existsSync(file)) {
+        return null;
+    }
+    const data = JSON.parse(fs.readFileSync(file, "utf8"));
+    return data.items || [];
+}
+/** Write `items` as the review queue. */
+function writeReviewQueue(items) {
+    const file = reviewQueuePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const data = { timestamp: new Date().toISOString(), items };
+    fs.writeFileSync(file, JSON.stringify(data, null, 2));
+    return file;
+}
+/**
+ * Add the flagged translations of a run to the review queue. Queued items for translations the
+ * run scored again are dropped first: the new score replaces them.
+ * @param scored - Every translation the run scored.
+ * @param flagged - The translations the run flagged for review or rejected.
+ * @returns The queue file and the number of items it now holds.
+ */
+export function updateReviewQueue(scored, flagged) {
+    const rescored = new Set(scored.map(refId));
+    const items = [
+        ...(readReviewQueue() || []).filter((item) => !rescored.has(refId(item))),
+        ...flagged,
+    ];
+    return { file: writeReviewQueue(items), size: items.length };
+}
+/**
+ * Remove reviewed translations from the review queue.
+ * @param reviewed - The translations a review approved, edited or rejected.
+ */
+export function removeFromReviewQueue(reviewed) {
+    const items = readReviewQueue();
+    if (!items || reviewed.length === 0) {
+        return;
+    }
+    const done = new Set(reviewed.map(refId));
+    writeReviewQueue(items.filter((item) => !done.has(refId(item))));
+}