locai 2.1.0

package/dist/utils/file-manager.js

@@ -0,0 +1,357 @@
+import { promises as fs } from "fs";
+import path from "path";
+import { FormatFactory } from "../core/adapters/factory.js";
+/**
+ * FileManager - Modern asynchronous file operations
+ * Handles multiple file formats via Adapter pattern.
+ */
+class FileManager {
+    /**
+     * Default options for file operations
+     */
+    static defaultOptions = {
+        atomic: true,
+        createMissingDirs: true,
+        backupFiles: true,
+        backupDir: "./backups",
+        encoding: "utf8",
+        jsonIndent: 4,
+    };
+    static options = null;
+    /**
+     * Configure global options for file operations
+     * @param options - File operation options
+     */
+    static configure(options) {
+        if (!options)
+            return;
+        this.options = {
+            ...this.defaultOptions,
+            ...options,
+        };
+    }
+    /**
+     * Get current configuration
+     * @returns Current configuration
+     */
+    static getConfig() {
+        return this.options || this.defaultOptions;
+    }
+    /**
+     * Find locale files in the specified directory
+     * @param localesDir - Directory containing locale files
+     * @param sourceLang - Source language code
+     * @returns Array of file paths
+     */
+    static async findLocaleFiles(localesDir, sourceLang) {
+        try {
+            // Find any file with the source language name (ignoring extension)
+            const files = await fs.readdir(localesDir);
+            const sourceFiles = files
+                .filter((file) => file.startsWith(`${sourceLang}.`))
+                .map((file) => path.join(localesDir, file));
+            if (sourceFiles.length === 0) {
+                throw new Error(`Source language file not found for '${sourceLang}' in ${localesDir}`);
+            }
+            // Return the first match, or maybe prioritize JSON?
+            // For now, return all matches, but usually there's only one.
+            return sourceFiles;
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                throw new Error(`Locales directory not found: ${localesDir}`);
+            }
+            throw new Error(`Source language file search error: ${err.message}`);
+        }
+    }
+    /**
+     * Read structured data file asynchronously (JSON, YAML, etc.)
+     * @param filePath - Path to the file
+     * @param options - Options for reading
+     * @returns Parsed data
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static async readFile(filePath, options = {}) {
+        const config = { ...this.getConfig(), ...options };
+        try {
+            const content = await fs.readFile(filePath, config.encoding);
+            const adapter = options.format && options.format !== "auto"
+                ? FormatFactory.getAdapterByFormat(options.format)
+                : FormatFactory.getAdapter(filePath);
+            return await adapter.parse(content);
+        }
+        catch (err) {
+            throw new Error(`File read error (${filePath}): ${err.message}`);
+        }
+    }
+    /**
+     * Write data to file asynchronously
+     * @param filePath - Path to write the file
+     * @param data - Data to write
+     * @param options - Options for writing
+     * @returns Success status
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static async writeFile(filePath, data, options = {}) {
+        const config = { ...this.getConfig(), ...options };
+        try {
+            // Create target directory if it doesn't exist
+            const dir = path.dirname(filePath);
+            if (config.createMissingDirs) {
+                await this.ensureDir(dir);
+            }
+            // Create backup directory if needed
+            if (config.backupFiles && config.backupDir) {
+                await this.ensureDir(config.backupDir);
+            }
+            // Create backup of existing file
+            if (config.backupFiles && config.backupDir) {
+                try {
+                    await fs.access(filePath);
+                    const backupPath = path.join(config.backupDir, `${path.basename(filePath)}.${Date.now()}.bak`);
+                    await fs.copyFile(filePath, backupPath);
+                }
+                catch (err) {
+                    // Ignore if file doesn't exist
+                    if (err.code !== "ENOENT") {
+                        console.error(`Backup failed (${filePath}): ${err.message}`);
+                    }
+                }
+            }
+            // Serialize content
+            const adapter = options.format && options.format !== "auto"
+                ? FormatFactory.getAdapterByFormat(options.format)
+                : FormatFactory.getAdapter(filePath);
+            const content = await adapter.serialize(data, {
+                indent: options.indent || config.jsonIndent,
+                compact: config.compact,
+            });
+            // Use atomic write if configured
+            if (config.atomic) {
+                const tempFile = this._generateTempFilePath(filePath);
+                let tempFileCreated = false;
+                try {
+                    await fs.writeFile(tempFile, content, config.encoding);
+                    tempFileCreated = true;
+                    await fs.rename(tempFile, filePath);
+                    tempFileCreated = false;
+                }
+                catch (renameError) {
+                    if (tempFileCreated) {
+                        try {
+                            await fs.unlink(tempFile);
+                        }
+                        catch {
+                            /* ignore cleanup error */
+                        }
+                    }
+                    throw new Error(`Atomic write failed (${filePath}): ${renameError.message}`);
+                }
+            }
+            else {
+                await fs.writeFile(filePath, content, config.encoding);
+            }
+            return true;
+        }
+        catch (err) {
+            throw new Error(`File write error (${filePath}): ${err.message}`);
+        }
+    }
+    // Legacy method aliases for backward compatibility
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static async readJSON(filePath, options = {}) {
+        return this.readFile(filePath, { ...options, format: "json" });
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static async writeJSON(filePath, data, options = {}) {
+        return this.writeFile(filePath, data, { ...options, format: "json" });
+    }
+    /**
+     * Generate a unique temporary file path
+     */
+    static _generateTempFilePath(filePath) {
+        const timestamp = Date.now();
+        const random = Math.random().toString(36).substring(2, 8);
+        return `${filePath}.tmp.${timestamp}.${random}`;
+    }
+    /**
+     * Ensure directory exists
+     */
+    static async ensureDir(dir) {
+        try {
+            await fs.mkdir(dir, { recursive: true });
+        }
+        catch (err) {
+            if (err.code !== "EEXIST") {
+                throw err;
+            }
+        }
+    }
+    /**
+     * Scan for locale files
+     */
+    static async scanLocaleFiles(localesDir, pattern = /.*/) {
+        try {
+            const files = await fs.readdir(localesDir);
+            return files
+                .filter((file) => pattern.test(file))
+                .map((file) => path.join(localesDir, file));
+        }
+        catch (err) {
+            throw new Error(`Error scanning locale directory: ${err.message}`);
+        }
+    }
+    /**
+     * Get file modification time
+     */
+    static async getModifiedTime(filePath) {
+        try {
+            const stats = await fs.stat(filePath);
+            return stats.mtime;
+        }
+        catch (err) {
+            throw new Error(`Error getting file stats: ${err.message}`);
+        }
+    }
+    /**
+     * Check if file exists
+     */
+    static async exists(filePath) {
+        try {
+            await fs.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Delete file
+     * @param filePath - Path to the file
+     * @param options - Options for deletion
+     * @returns Success status
+     */
+    static async deleteFile(filePath, options = {}) {
+        const config = { ...this.getConfig(), ...options };
+        try {
+            // Create backup before deletion if backups are enabled
+            if (config.backupFiles && config.backupDir) {
+                try {
+                    await fs.access(filePath);
+                    await this.ensureDir(config.backupDir);
+                    const backupPath = path.join(config.backupDir, `${path.basename(filePath)}.deleted.${Date.now()}.bak`);
+                    await fs.copyFile(filePath, backupPath);
+                }
+                catch (err) {
+                    console.error(`Backup failed (${filePath}): ${err.message}`);
+                }
+            }
+            await fs.unlink(filePath);
+            return true;
+        }
+        catch (err) {
+            throw new Error(`File deletion error (${filePath}): ${err.message}`);
+        }
+    }
+    /**
+     * Validate JSON file structure
+     * @param filePath - Path to the JSON file
+     * @returns Validation result
+     */
+    static async validateJSONFile(filePath) {
+        try {
+            const content = await fs.readFile(filePath, "utf8");
+            JSON.parse(content); // Throws if invalid
+            return {
+                valid: true,
+                filePath,
+            };
+        }
+        catch (error) {
+            return {
+                valid: false,
+                filePath,
+                error: error.message,
+                position: this._extractErrorPosition(error),
+            };
+        }
+    }
+    /**
+     * Extract error position from JSON parse error
+     * @param error - JSON parse error
+     * @returns Error position details
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static _extractErrorPosition(error) {
+        const message = error.message;
+        const positionMatch = message.match(/position (\d+)/);
+        const lineMatch = message.match(/line (\d+)/);
+        if (positionMatch || lineMatch) {
+            return {
+                position: positionMatch ? parseInt(positionMatch[1]) : null,
+                line: lineMatch ? parseInt(lineMatch[1]) : null,
+            };
+        }
+        return null;
+    }
+    /**
+     * Validate translation value can be safely added to JSON
+     * @param key - Translation key
+     * @param value - Translation value
+     * @returns Validation result
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static validateTranslationValue(key, value) {
+        try {
+            // Test if value can be part of valid JSON
+            const testObject = { [key]: value };
+            JSON.stringify(testObject);
+            JSON.parse(JSON.stringify(testObject)); // Round-trip test
+            return {
+                valid: true,
+                key,
+                value,
+            };
+        }
+        catch (error) {
+            return {
+                valid: false,
+                key,
+                value,
+                error: `JSON validation failed: ${error.message}`,
+            };
+        }
+    }
+    /**
+     * List files in a directory
+     * @param dirPath - Directory path
+     * @returns Array of file paths
+     */
+    static async listFiles(dirPath) {
+        try {
+            const entries = await fs.readdir(dirPath, { withFileTypes: true });
+            const files = entries
+                .filter((entry) => entry.isFile())
+                .map((entry) => path.join(dirPath, entry.name));
+            return files;
+        }
+        catch (err) {
+            throw new Error(`Directory read error (${dirPath}): ${err.message}`);
+        }
+    }
+    /**
+     * Ensure directory exists, create if it doesn't
+     * @param dirPath - Directory path
+     * @returns True if directory exists or was created
+     */
+    static async ensureDirectoryExists(dirPath) {
+        try {
+            await fs.mkdir(dirPath, { recursive: true });
+            return true;
+        }
+        catch (err) {
+            throw new Error(`Failed to create directory (${dirPath}): ${err.message}`);
+        }
+    }
+}
+export { FileManager };

package/dist/utils/glossary-manager.js

@@ -0,0 +1,194 @@
+/**
+ * Glossary Manager
+ * Manages brand terminology and ensures consistent translations
+ */
+class GlossaryManager {
+    glossary;
+    enabled;
+    caseSensitive;
+    preserveFormatting;
+    constructor(config = {}) {
+        this.glossary = config.glossary || {};
+        this.enabled = config.enabled !== false;
+        this.caseSensitive = config.caseSensitive !== false;
+        this.preserveFormatting = config.preserveFormatting !== false;
+    }
+    /**
+     * Apply glossary terms to source text before translation
+     * Replaces terms with protected tokens to preserve them
+     */
+    protectTerms(text, sourceLang, targetLang) {
+        if (!this.enabled || !text || typeof text !== "string") {
+            return { protectedText: text, termMap: new Map() };
+        }
+        const termMap = new Map();
+        let protectedText = text;
+        let tokenIndex = 0;
+        // Get applicable glossary entries
+        const entries = this.getApplicableEntries(sourceLang, targetLang);
+        // Sort by length (longest first) to avoid partial matches
+        const sortedEntries = entries.sort((a, b) => b.term.length - a.term.length);
+        for (const entry of sortedEntries) {
+            const { term, translation, caseSensitive } = entry;
+            const isCaseSensitive = caseSensitive ?? this.caseSensitive;
+            // Create regex for finding the term
+            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);
+                });
+            }
+        }
+        return { protectedText, termMap };
+    }
+    /**
+     * Restore protected terms in translated text
+     */
+    restoreTerms(translatedText, termMap) {
+        if (!this.enabled || !termMap || termMap.size === 0) {
+            return translatedText;
+        }
+        let restoredText = translatedText;
+        // Replace tokens with translations
+        for (const [token, data] of termMap.entries()) {
+            restoredText = restoredText.replace(new RegExp(token, "g"), data.translation);
+        }
+        return restoredText;
+    }
+    /**
+     * Get applicable glossary entries for language pair
+     */
+    getApplicableEntries(sourceLang, targetLang) {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const entries = [];
+        for (const [term, config] of Object.entries(this.glossary)) {
+            // Simple format: { "API": "API" }
+            if (typeof config === "string") {
+                entries.push({
+                    term,
+                    translation: config,
+                    caseSensitive: this.caseSensitive,
+                });
+            }
+            // Advanced format: { "API": { translation: "API", caseSensitive: true } }
+            else if (typeof config === "object" && config.translation) {
+                entries.push({
+                    term,
+                    translation: config.translation,
+                    caseSensitive: config.caseSensitive ?? this.caseSensitive,
+                    languages: config.languages,
+                });
+            }
+            // Language-specific format
+            else if (typeof config === "object" && config[targetLang]) {
+                entries.push({
+                    term,
+                    translation: config[targetLang],
+                    caseSensitive: this.caseSensitive,
+                });
+            }
+        }
+        return entries;
+    }
+    /**
+     * Match formatting (capitalization) from original to translation
+     */
+    matchFormatting(original, translation) {
+        // All caps
+        if (original === original.toUpperCase()) {
+            return translation.toUpperCase();
+        }
+        // Title case (first letter uppercase)
+        if (original[0] === original[0].toUpperCase() &&
+            original.slice(1) === original.slice(1).toLowerCase()) {
+            return translation.charAt(0).toUpperCase() + translation.slice(1).toLowerCase();
+        }
+        // First char uppercase
+        if (original[0] === original[0].toUpperCase()) {
+            return translation.charAt(0).toUpperCase() + translation.slice(1);
+        }
+        return translation;
+    }
+    /**
+     * Escape special regex characters
+     */
+    escapeRegex(string) {
+        return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+    /**
+     * Validate glossary configuration
+     */
+    validate() {
+        const errors = [];
+        const warnings = [];
+        if (!this.glossary || typeof this.glossary !== "object") {
+            errors.push("Glossary must be an object");
+            return { valid: false, errors, warnings };
+        }
+        for (const [term, config] of Object.entries(this.glossary)) {
+            if (!term || typeof term !== "string") {
+                errors.push(`Invalid term: ${term}`);
+                continue;
+            }
+            // Validate simple format
+            if (typeof config === "string" && !config) {
+                warnings.push(`Empty translation for term: ${term}`);
+            }
+            // Validate object format
+            if (typeof config === "object") {
+                if (!config.translation && !Object.keys(config).some((key) => key.length === 2)) {
+                    errors.push(`Invalid glossary entry for term: ${term}`);
+                }
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings,
+        };
+    }
+    /**
+     * Get statistics about glossary
+     */
+    getStats() {
+        const terms = Object.keys(this.glossary);
+        return {
+            totalTerms: terms.length,
+            enabled: this.enabled,
+            caseSensitive: this.caseSensitive,
+            preserveFormatting: this.preserveFormatting,
+            terms: terms,
+        };
+    }
+    /**
+     * Load glossary from file
+     */
+    static async loadFromFile(filePath) {
+        try {
+            const { readFile } = await import("fs/promises");
+            const content = await readFile(filePath, "utf8");
+            const glossary = JSON.parse(content);
+            return new GlossaryManager({ glossary, enabled: true });
+        }
+        catch (error) {
+            throw new Error(`Failed to load glossary from ${filePath}: ${error.message}`);
+        }
+    }
+}
+export default GlossaryManager;

package/dist/utils/graceful-shutdown.js

@@ -0,0 +1,118 @@
+import rateLimiter from "./rate-limiter.js";
+class GracefulShutdown {
+    options;
+    isShuttingDown;
+    shutdownCallbacks;
+    logger;
+    constructor(options = {}) {
+        this.options = {
+            shutdownTimeout: 5000,
+            waitForPending: true,
+            ...options,
+        };
+        this.isShuttingDown = false;
+        this.shutdownCallbacks = [];
+        this.logger = options.logger || console;
+    }
+    registerCallback(callback) {
+        if (typeof callback === "function") {
+            this.shutdownCallbacks.push(callback);
+        }
+    }
+    unregisterCallback(callback) {
+        if (typeof callback === "function") {
+            const index = this.shutdownCallbacks.indexOf(callback);
+            if (index > -1) {
+                this.shutdownCallbacks.splice(index, 1);
+            }
+        }
+    }
+    init() {
+        process.on("SIGTERM", () => this.handleSignal("SIGTERM"));
+        process.on("SIGINT", () => this.handleSignal("SIGINT"));
+        process.on("uncaughtException", (err) => {
+            this.logger.error("Uncaught Exception:", err);
+            this.shutdown(1);
+        });
+        process.on("unhandledRejection", (reason, promise) => {
+            this.logger.error("Unhandled Rejection at:", promise, "reason:", reason);
+            this.shutdown(1);
+        });
+        this.logger.info("Graceful shutdown handlers initialized");
+    }
+    async handleSignal(signal) {
+        this.logger.info(`Received ${signal}, initiating graceful shutdown...`);
+        await this.shutdown(0);
+    }
+    async shutdown(exitCode = 0) {
+        if (this.isShuttingDown) {
+            return;
+        }
+        this.isShuttingDown = true;
+        this.logger.info("Starting graceful shutdown...");
+        const timeoutPromise = new Promise((resolve) => {
+            setTimeout(() => {
+                this.logger.warn(`Shutdown timeout (${this.options.shutdownTimeout}ms) exceeded, forcing exit`);
+                resolve();
+            }, this.options.shutdownTimeout);
+        });
+        const shutdownProcess = this.performShutdown();
+        try {
+            await Promise.race([shutdownProcess, timeoutPromise]);
+        }
+        catch (error) {
+            this.logger.error("Error during shutdown:", error);
+        }
+        finally {
+            process.exit(exitCode);
+        }
+    }
+    async performShutdown() {
+        const startTime = Date.now();
+        try {
+            this.logger.info("Executing shutdown callbacks...");
+            for (const callback of this.shutdownCallbacks) {
+                try {
+                    await callback();
+                }
+                catch (error) {
+                    this.logger.warn("Error in shutdown callback:", error);
+                }
+            }
+            if (this.options.waitForPending) {
+                this.logger.info("Waiting for pending operations...");
+                await this.waitForPendingOperations();
+            }
+            const duration = Date.now() - startTime;
+            this.logger.info(`Graceful shutdown completed in ${duration}ms`);
+        }
+        catch (error) {
+            this.logger.error("Error during shutdown process:", error);
+        }
+    }
+    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)) {
+            if (status.queueSize > 0 || status.processing > 0) {
+                hasPending = true;
+                this.logger.info(`Waiting for ${status.queueSize} queued and ${status.processing} processing operations for ${provider}`);
+            }
+        }
+        if (hasPending) {
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+            try {
+                rateLimiter.clearAllQueues();
+                this.logger.info("Forced queue cleanup completed");
+            }
+            catch (error) {
+                this.logger.warn("Error during forced queue cleanup:", error.message);
+            }
+        }
+    }
+}
+const gracefulShutdown = new GracefulShutdown();
+// Can't auto-init if we want to test or configure it, but existing code did this.
+gracefulShutdown.init();
+export default gracefulShutdown;