locai 2.6.1 → 2.7.0

package/dist/utils/glossary-manager.d.ts

@@ -13,12 +13,28 @@ export interface ProtectedTerm {
     translation: string;
     term: string;
 }
+/**
+ * Advanced format: `{ "API": { translation: "API", caseSensitive: true, languages: ["de"] } }`.
+ * A non-empty `languages` list restricts the entry to those target languages.
+ */
+export type GlossaryEntryConfig = Partial<Omit<GlossaryEntry, "term">>;
+/** Language-specific format: `{ "API": { tr: "API", de: "API" } }` */
+export type LanguageTranslations = Record<string, string>;
+/** Simple format (`{ "API": "API" }`), advanced entry, or per-language translations. */
+export type GlossaryTermConfig = string | GlossaryEntryConfig | LanguageTranslations;
 export interface GlossaryConfig {
-    glossary?: Record<string, string | Partial<GlossaryEntry> | Record<string, string>>;
+    glossary?: Record<string, GlossaryTermConfig>;
     enabled?: boolean;
     caseSensitive?: boolean;
     preserveFormatting?: boolean;
 }
+export interface GlossaryStats {
+    totalTerms: number;
+    enabled: boolean;
+    caseSensitive: boolean;
+    preserveFormatting: boolean;
+    terms: string[];
+}
 declare class GlossaryManager {
     private glossary;
     enabled: boolean;
@@ -38,7 +54,10 @@ declare class GlossaryManager {
      */
     restoreTerms(translatedText: string, termMap: Map<string, ProtectedTerm>): string;
     /**
-     * Get applicable glossary entries for language pair
+     * Get applicable glossary entries for language pair.
+     * An advanced entry with a non-empty `languages` list applies only when `targetLang` is in
+     * that list. Codes are compared as whole tags, ignoring case: `"pt-br"` matches `"pt-BR"`,
+     * but `"zh"` does not match `"zh-CN"`.
      */
     getApplicableEntries(sourceLang: string, targetLang: string): GlossaryEntry[];
     /**
@@ -60,7 +79,7 @@ declare class GlossaryManager {
     /**
      * Get statistics about glossary
      */
-    getStats(): any;
+    getStats(): GlossaryStats;
     /**
      * Load glossary from file
      */

package/dist/utils/glossary-manager.js

@@ -2,13 +2,26 @@
  * Glossary Manager
  * Manages brand terminology and ensures consistent translations
  */
+/** An object entry with a truthy `translation` is an advanced entry ... */
+const isEntryConfig = (config) => Boolean(config.translation);
+/** ... any other object entry is a per-language map. */
+const isLanguageMap = (config) => !isEntryConfig(config);
 class GlossaryManager {
     glossary;
     enabled;
     caseSensitive;
     preserveFormatting;
     constructor(config = {}) {
-        this.glossary = config.glossary || {};
+        // Config files are plain JS/JSON, so a term can map to `null`; skip it instead of
+        // crashing on every translation.
+        this.glossary = {};
+        for (const [term, entry] of Object.entries(config.glossary || {})) {
+            if (entry === null) {
+                console.warn(`Warning: glossary entry "${term}" is null; skipping it.`);
+                continue;
+            }
+            this.glossary[term] = entry;
+        }
         this.enabled = config.enabled !== false;
         this.caseSensitive = config.caseSensitive !== false;
         this.preserveFormatting = config.preserveFormatting !== false;
@@ -35,25 +48,21 @@ class GlossaryManager {
             const flags = isCaseSensitive ? "g" : "gi";
             const escapedTerm = this.escapeRegex(term);
             const regex = new RegExp(`\\b${escapedTerm}\\b`, flags);
-            // Find all matches
-            const matches = protectedText.match(regex);
-            if (matches) {
-                matches.forEach((match) => {
-                    const token = `__GLOSSARY_TOKEN_${tokenIndex}__`;
-                    tokenIndex++;
-                    // Preserve original formatting if needed
-                    const preservedTranslation = this.preserveFormatting
-                        ? this.matchFormatting(match, translation)
-                        : translation;
-                    termMap.set(token, {
-                        original: match,
-                        translation: preservedTranslation,
-                        term: term,
-                    });
-                    // Replace with token
-                    protectedText = protectedText.replace(match, token);
+            // Replace each whole-word match in place with its own token
+            protectedText = protectedText.replace(regex, (match) => {
+                const token = `__GLOSSARY_TOKEN_${tokenIndex}__`;
+                tokenIndex++;
+                // Preserve original formatting if needed
+                const preservedTranslation = this.preserveFormatting
+                    ? this.matchFormatting(match, translation)
+                    : translation;
+                termMap.set(token, {
+                    original: match,
+                    translation: preservedTranslation,
+                    term: term,
                 });
-            }
+                return token;
+            });
         }
         return { protectedText, termMap };
     }
@@ -65,18 +74,21 @@ class GlossaryManager {
             return translatedText;
         }
         let restoredText = translatedText;
-        // Replace tokens with translations
+        // Replace tokens with translations; a replacer function keeps `$` patterns literal
         for (const [token, data] of termMap.entries()) {
-            restoredText = restoredText.replace(new RegExp(token, "g"), data.translation);
+            restoredText = restoredText.replace(new RegExp(token, "g"), () => data.translation);
         }
         return restoredText;
     }
     /**
-     * Get applicable glossary entries for language pair
+     * Get applicable glossary entries for language pair.
+     * An advanced entry with a non-empty `languages` list applies only when `targetLang` is in
+     * that list. Codes are compared as whole tags, ignoring case: `"pt-br"` matches `"pt-BR"`,
+     * but `"zh"` does not match `"zh-CN"`.
      */
     getApplicableEntries(sourceLang, targetLang) {
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
         const entries = [];
+        const target = targetLang.toLowerCase();
         for (const [term, config] of Object.entries(this.glossary)) {
             // Simple format: { "API": "API" }
             if (typeof config === "string") {
@@ -86,17 +98,23 @@ class GlossaryManager {
                     caseSensitive: this.caseSensitive,
                 });
             }
-            // Advanced format: { "API": { translation: "API", caseSensitive: true } }
-            else if (typeof config === "object" && config.translation) {
+            // Advanced format: { "API": { translation: "API", caseSensitive: true, languages: ["de"] } }
+            else if (typeof config === "object" && isEntryConfig(config)) {
+                const { languages } = config;
+                if (Array.isArray(languages) &&
+                    languages.length > 0 &&
+                    !languages.some((lang) => String(lang).toLowerCase() === target)) {
+                    continue;
+                }
                 entries.push({
                     term,
                     translation: config.translation,
                     caseSensitive: config.caseSensitive ?? this.caseSensitive,
-                    languages: config.languages,
+                    languages,
                 });
             }
             // Language-specific format
-            else if (typeof config === "object" && config[targetLang]) {
+            else if (typeof config === "object" && isLanguageMap(config) && config[targetLang]) {
                 entries.push({
                     term,
                     translation: config[targetLang],
@@ -187,7 +205,8 @@ class GlossaryManager {
             return new GlossaryManager({ glossary, enabled: true });
         }
         catch (error) {
-            throw new Error(`Failed to load glossary from ${filePath}: ${error.message}`);
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to load glossary from ${filePath}: ${message}`);
         }
     }
 }

package/dist/utils/graceful-shutdown.d.ts

@@ -1,8 +1,14 @@
 export type ShutdownCallback = () => Promise<void> | void;
+/** Minimal logging surface used during shutdown; satisfied by `console` and our `Logger`. */
+export interface ShutdownLogger {
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
 export interface ShutdownOptions {
     shutdownTimeout?: number;
     waitForPending?: boolean;
-    logger?: Console | any;
+    logger?: ShutdownLogger;
 }
 declare class GracefulShutdown {
     private options;

package/dist/utils/graceful-shutdown.js

@@ -91,7 +91,6 @@ class GracefulShutdown {
         }
     }
     async waitForPendingOperations() {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const providerStatus = rateLimiter.getStatus();
         let hasPending = false;
         for (const [provider, status] of Object.entries(providerStatus)) {
@@ -107,7 +106,7 @@ class GracefulShutdown {
                 this.logger.info("Forced queue cleanup completed");
             }
             catch (error) {
-                this.logger.warn("Error during forced queue cleanup:", error.message);
+                this.logger.warn("Error during forced queue cleanup:", error instanceof Error ? error.message : String(error));
             }
         }
     }

package/dist/utils/input-validator.d.ts

@@ -2,10 +2,13 @@
  * Input validation utility for security and data integrity.
  * Defines regex patterns, limits, and validation methods.
  */
+import type { FileOptions } from "./file-manager.js";
+import type { QualityRules } from "./quality/base-checker.js";
+import type { LengthControlOptions } from "./quality/length-checker.js";
 export interface ApiProviderConfig {
     temperature?: number;
     maxTokens?: number;
-    [key: string]: any;
+    [key: string]: unknown;
 }
 export interface RateLimiterProviderLimit {
     rpm?: number;
@@ -28,17 +31,13 @@ export interface ContextConfig {
         threshold?: number;
         minConfidence?: number;
     };
-    categories?: Record<string, any>;
+    categories?: Record<string, unknown>;
 }
 export interface QualityChecksConfig {
-    rules?: Record<string, any>;
+    rules?: QualityRules;
     enabled?: boolean;
     autoFix?: boolean;
 }
-export interface LengthControlConfig {
-    mode?: "strict" | "flexible" | "exact" | "relaxed" | "smart";
-    rules?: Record<string, any>;
-}
 export interface AdvancedConfig {
     timeoutMs?: number;
     maxKeyLength?: number;
@@ -58,70 +57,78 @@ export interface AppConfig {
     retryOptions?: RetryOptions;
     context?: ContextConfig;
     qualityChecks?: QualityChecksConfig;
-    lengthControl?: LengthControlConfig;
+    lengthControl?: LengthControlOptions;
     advanced?: AdvancedConfig;
-    fileOperations?: Record<string, any>;
+    fileOperations?: FileOptions;
     debug?: boolean;
     verbose?: boolean;
-    [key: string]: any;
+    [key: string]: unknown;
 }
+/** A config section that is an object but whose fields have not been validated yet */
+type UnvalidatedSection = Record<string, unknown>;
 declare class InputValidator {
+    /**
+     * Well-formed BCP 47 language tag, limited to the subtags locai supports:
+     * a 2-3 letter language, an optional 4-letter script and an optional
+     * 2-letter or 3-digit region (e.g. "en", "fil", "pt-BR", "zh-Hant-TW", "es-419").
+     * Matching is case-insensitive; see validateLanguageCode for canonical casing.
+     */
     static LANGUAGE_CODE_PATTERN: RegExp;
     static VALID_PROVIDERS: string[];
     static MAX_TEXT_LENGTH: number;
     static MAX_KEY_LENGTH: number;
     static MAX_PATH_LENGTH: number;
     static MAX_CONFIG_DEPTH: number;
-    static DANGEROUS_PATTERNS: RegExp[];
-    private static _requestCounts?;
     /**
-     * Validate and sanitize language code.
-     * @param {string} langCode - Language code to validate.
+     * Validate a BCP 47 language tag and return it in canonical casing:
+     * lowercase language, title-case script, uppercase region
+     * (e.g. "ZH-hant-tw" -> "zh-Hant-TW", "PT-br" -> "pt-BR").
+     * @param {unknown} langCode - Language tag to validate.
      * @param {string} [paramName="language"] - Parameter name for error messages.
-     * @returns {string} - Sanitized language code.
+     * @returns {string} - Canonical language tag.
      * @throws {Error} If validation fails.
      */
-    static validateLanguageCode(langCode: string, paramName?: string): string;
+    static validateLanguageCode(langCode: unknown, paramName?: string): string;
     /**
      * Validate array of language codes.
-     * @param {string[]} langCodes - Array of language codes.
+     * @param {unknown} langCodes - Array of language codes.
      * @param {string} [paramName="languages"] - Parameter name for errors.
      * @returns {string[]} - Sanitized array of language codes.
      * @throws {Error} If array is empty or contains invalid codes.
      */
-    static validateLanguageCodes(langCodes: string[], paramName?: string): string[];
+    static validateLanguageCodes(langCodes: unknown, paramName?: string): string[];
     /**
      * Validate and sanitize directory path.
-     * @param {string} dirPath - Directory path.
+     * @param {unknown} dirPath - Directory path.
      * @param {string} [paramName="directory"] - Parameter name for errors.
      * @returns {string} - Resolved and validated absolute path.
      * @throws {Error} If path is invalid or outside working directory.
      */
-    static validateDirectoryPath(dirPath: string, paramName?: string): string;
+    static validateDirectoryPath(dirPath: unknown, paramName?: string): string;
     /**
      * Validate translation text.
-     * @param {string} text - Text to validate.
+     * @param {unknown} text - Text to validate.
      * @param {string} [paramName="text"] - Parameter name for errors.
      * @returns {string} - Validated text.
      * @throws {Error} If text is invalid or too long.
      */
-    static validateText(text: string, paramName?: string): string;
+    static validateText(text: unknown, paramName?: string): string;
     /**
      * Validate translation key.
-     * @param {string} key - Key to validate.
+     * @param {unknown} key - Key to validate.
      * @param {string} [paramName="key"] - Parameter name.
      * @returns {string} - Validated key.
      * @throws {Error} If key is invalid, too long, or contains traversal.
      */
-    static validateKey(key: string, paramName?: string): string;
+    static validateKey(key: unknown, paramName?: string): string;
     /**
      * Validate API provider name.
-     * @param {string} provider - Provider name.
+     * @param {unknown} provider - Provider name.
      * @param {string} [fieldName="API provider"] - Parameter name.
      * @returns {string} - Normalized provider name.
      * @throws {Error} If provider is unknown.
      */
-    static validateProvider(provider: string, fieldName?: string): string;
+    static validateProvider(provider: unknown, fieldName?: string): string;
     /**
      * Sanitize filename to prevent path traversal.
      * @param {string} filename - Filename to sanitize.
@@ -140,88 +147,68 @@ declare class InputValidator {
     static createSafeFilePath(baseDir: string, filename: string): string;
     /**
      * Validate configuration object.
-     * @param {any} config - Configuration object to validate.
+     * Rewrites `source` and `targets` in place to canonical BCP 47 casing so that
+     * file lookups and per-language settings all see the same tag.
+     * @param {unknown} config - Configuration object to validate.
      * @returns {AppConfig} - Validated configuration.
      * @throws {Error} If configuration is invalid.
      */
-    static validateConfig(config: any): AppConfig;
+    static validateConfig(config: unknown): AppConfig;
     /**
      * Validate API config for each provider.
-     * @param {Record<string, ApiProviderConfig>} apiConfig - API configuration object.
+     * @param {Record<string, unknown>} apiConfig - Raw API configuration object.
      * @param {string[]} errors - Array to push errors to.
      * @param {string[]} warnings - Array to push warnings to.
      */
-    static validateApiConfig(apiConfig: Record<string, ApiProviderConfig>, errors: string[], warnings: string[]): void;
+    static validateApiConfig(apiConfig: UnvalidatedSection, errors: string[], warnings: string[]): void;
     /**
      * Validate rate limiter configuration.
-     * @param {RateLimiterConfig} rateLimiter - Rate limiter configuration.
+     * @param {Record<string, unknown>} rateLimiter - Raw rate limiter configuration.
      * @param {string[]} errors - Array to push errors to.
      * @param {string[]} warnings - Array to push warnings to.
      */
-    static validateRateLimiterConfig(rateLimiter: RateLimiterConfig, errors: string[], _warnings: string[]): void;
+    static validateRateLimiterConfig(rateLimiter: UnvalidatedSection, errors: string[], _warnings: string[]): void;
     /**
      * Validate retry options.
-     * @param {RetryOptions} retryOptions - Retry options.
+     * @param {Record<string, unknown>} retryOptions - Raw retry options.
      * @param {string[]} errors - Array to push errors to.
      * @param {string[]} warnings - Array to push warnings to.
      */
-    static validateRetryOptions(retryOptions: RetryOptions, errors: string[], _warnings: string[]): void;
+    static validateRetryOptions(retryOptions: UnvalidatedSection, errors: string[], _warnings: string[]): void;
     /**
      * Validate context configuration.
-     * @param {ContextConfig} context - Context configuration.
+     * @param {Record<string, unknown>} context - Raw context configuration.
      * @param {string[]} errors - Array to push errors to.
      * @param {string[]} warnings - Array to push warnings to.
      */
-    static validateContextConfig(context: ContextConfig, errors: string[], warnings: string[]): void;
+    static validateContextConfig(context: UnvalidatedSection, errors: string[], warnings: string[]): void;
     /**
      * Validate quality checks configuration.
-     * @param {QualityChecksConfig} qualityChecks - Quality checks configuration.
+     * @param {Record<string, unknown>} qualityChecks - Raw quality checks configuration.
      * @param {string[]} errors - Array to push errors to.
      * @param {string[]} warnings - Array to push warnings to.
      */
-    static validateQualityChecks(qualityChecks: QualityChecksConfig, errors: string[], warnings: string[]): void;
+    static validateQualityChecks(qualityChecks: UnvalidatedSection, errors: string[], warnings: string[]): void;
     /**
      * Validate length control configuration.
-     * @param {LengthControlConfig} lengthControl - Length control configuration.
+     * @param {Record<string, unknown>} lengthControl - Raw length control configuration.
      * @param {string[]} errors - Array to push errors to.
      */
-    static validateLengthControl(lengthControl: LengthControlConfig, errors: string[]): void;
+    static validateLengthControl(lengthControl: UnvalidatedSection, errors: string[]): void;
     /**
      * Validate advanced configuration.
-     * @param {AdvancedConfig} advanced - Advanced configuration.
+     * @param {Record<string, unknown>} advanced - Raw advanced configuration.
      * @param {string[]} errors - Array to push errors to.
      */
-    static validateAdvancedConfig(advanced: AdvancedConfig, errors: string[]): void;
-    /**
-     * Sanitize translation text for security.
-     * @param {string | null} text - Text to sanitize.
-     * @returns {string | null} - Sanitized text.
-     */
-    static sanitizeTranslationText(text: string | null): string | null;
-    /**
-     * Validate API key format.
-     * @param {string} apiKey - API key to validate.
-     * @param {string} providerName - Provider name.
-     * @returns {boolean} - True if valid.
-     * @throws {Error} If key is invalid.
-     */
-    static validateApiKeyFormat(apiKey: string, providerName: string): boolean;
+    static validateAdvancedConfig(advanced: UnvalidatedSection, errors: string[]): void;
     /**
      * Validate object depth to prevent circular references and deep nesting.
-     * @param {any} obj - Object to validate.
+     * @param {unknown} obj - Object to validate.
      * @param {number} [maxDepth=10] - Maximum depth.
      * @param {number} [currentDepth=0] - Current depth.
      * @returns {boolean} - True if valid.
      * @throws {Error} If depth exceeded.
      */
-    static validateObjectDepth(obj: any, maxDepth?: number, currentDepth?: number): boolean;
-    /**
-     * Validate request rate for an identifier.
-     * @param {string} identifier - Identifier (e.g., user ID or IP).
-     * @param {number} [maxRequestsPerMinute=60] - Max requests per minute.
-     * @returns {boolean} - True if allowed.
-     * @throws {Error} If rate limit exceeded.
-     */
-    static validateRequestRate(identifier: string, maxRequestsPerMinute?: number): boolean;
+    static validateObjectDepth(obj: unknown, maxDepth?: number, currentDepth?: number): boolean;
 }
 export default InputValidator;