@mxml3gend/gloss 0.1.2 → 0.1.3

package/dist/index.js

@@ -1,12 +1,19 @@
 #!/usr/bin/env node
 import fs from "node:fs/promises";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import open from "open";
+import { resetIssueBaseline, updateIssueBaseline } from "./baseline.js";
+import { clearGlossCaches, getCacheStatus } from "./cache.js";
 import { printGlossCheck, runGlossCheck } from "./check.js";
-import { GlossConfigError, loadGlossConfig } from "./config.js";
+import { GlossConfigError, discoverLocaleDirectoryCandidates, loadGlossConfig, } from "./config.js";
+import { installPreCommitHooks } from "./hooks.js";
 import { startServer } from "./server.js";
 import { generateKeyTypes } from "./typegen.js";
 const DEFAULT_PORT = 5179;
+const GENERATED_CONFIG_FILE = "gloss.config.cjs";
+const projectRoot = () => process.env.INIT_CWD || process.cwd();
 const getVersion = async () => {
     const packagePath = fileURLToPath(new URL("../package.json", import.meta.url));
     const raw = await fs.readFile(packagePath, "utf8");
@@ -20,6 +27,10 @@ Usage:
   gloss [options]
   gloss check [options]
   gloss gen-types [options]
+  gloss init-hooks [options]
+  gloss baseline reset
+  gloss cache status
+  gloss cache clear
   gloss open key <translation-key> [options]
 
 Options:
@@ -28,21 +39,85 @@ Options:
 
 Serve options:
   --no-open                  Do not open browser automatically
+  --no-cache                 Bypass scanner caches for API responses
   -p, --port                 Set server port (default: ${DEFAULT_PORT})
 
 Check options:
   --format <human|json|both> Output format (default: human)
   --json                     Shortcut for --format json
+  --no-cache                 Force full rescan without reading/writing scanner cache
 
 Type generation options:
   --out <path>               Output file for generated key types (default: i18n-keys.d.ts)
 
+Hook options:
+  gloss init-hooks           Install pre-commit hooks for gloss check
+
+Baseline options:
+  gloss baseline reset       Remove the local issue baseline (.gloss/baseline.json)
+
+Cache options:
+  gloss cache status         Show scanner cache status
+  gloss cache clear          Clear in-memory scanner cache and .gloss/cache-metrics.json
+
 Open key options:
   gloss open key <key>       Open Gloss focused on a translation key
+  --no-cache                 Bypass scanner caches while serving
 `);
 };
 const parseArgs = (args) => {
     const firstArg = args[0];
+    if (firstArg === "baseline") {
+        const commandArgs = args.slice(1);
+        const options = {
+            command: "baseline-reset",
+            help: false,
+            version: false,
+        };
+        for (const arg of commandArgs) {
+            if (arg === "-h" || arg === "--help") {
+                options.help = true;
+                continue;
+            }
+            if (arg === "-v" || arg === "--version") {
+                options.version = true;
+                continue;
+            }
+            if (arg === "reset") {
+                continue;
+            }
+            throw new Error(`Unknown argument for gloss baseline: ${arg}`);
+        }
+        if (!options.help && commandArgs[0] !== "reset") {
+            throw new Error("Usage: gloss baseline reset");
+        }
+        return options;
+    }
+    if (firstArg === "cache") {
+        const commandArgs = args.slice(1);
+        const action = commandArgs[0];
+        const restArgs = commandArgs.slice(1);
+        if (action !== "status" && action !== "clear") {
+            throw new Error("Usage: gloss cache <status|clear>");
+        }
+        const options = {
+            command: action === "status" ? "cache-status" : "cache-clear",
+            help: false,
+            version: false,
+        };
+        for (const arg of restArgs) {
+            if (arg === "-h" || arg === "--help") {
+                options.help = true;
+                continue;
+            }
+            if (arg === "-v" || arg === "--version") {
+                options.version = true;
+                continue;
+            }
+            throw new Error(`Unknown argument for gloss cache: ${arg}`);
+        }
+        return options;
+    }
     if (firstArg === "open") {
         const commandArgs = args.slice(1);
         const base = { help: false, version: false };
@@ -50,6 +125,7 @@ const parseArgs = (args) => {
             command: "open-key",
             ...base,
             noOpen: false,
+            noCache: false,
             port: DEFAULT_PORT,
             key: "",
         };
@@ -88,6 +164,10 @@ const parseArgs = (args) => {
                 options.noOpen = true;
                 continue;
             }
+            if (arg === "--no-cache") {
+                options.noCache = true;
+                continue;
+            }
             if (arg === "-p" || arg === "--port") {
                 const nextValue = commandArgs[index + 1];
                 if (!nextValue) {
@@ -106,7 +186,9 @@ const parseArgs = (args) => {
         return options;
     }
     const isCommand = firstArg && !firstArg.startsWith("-");
-    const command = firstArg === "check" || firstArg === "gen-types" ? firstArg : "serve";
+    const command = firstArg === "check" || firstArg === "gen-types" || firstArg === "init-hooks"
+        ? firstArg
+        : "serve";
     const commandArgs = command === "serve" ? args : args.slice(1);
     const base = {
         help: false,
@@ -117,6 +199,7 @@ const parseArgs = (args) => {
             command,
             ...base,
             format: "human",
+            noCache: false,
         };
         for (let index = 0; index < commandArgs.length; index += 1) {
             const arg = commandArgs[index];
@@ -132,6 +215,10 @@ const parseArgs = (args) => {
                 options.format = "json";
                 continue;
             }
+            if (arg === "--no-cache") {
+                options.noCache = true;
+                continue;
+            }
             if (arg === "--format") {
                 const nextValue = commandArgs[index + 1];
                 if (!nextValue) {
@@ -176,6 +263,24 @@ const parseArgs = (args) => {
         }
         return options;
     }
+    if (command === "init-hooks") {
+        const options = {
+            command,
+            ...base,
+        };
+        for (const arg of commandArgs) {
+            if (arg === "-h" || arg === "--help") {
+                options.help = true;
+                continue;
+            }
+            if (arg === "-v" || arg === "--version") {
+                options.version = true;
+                continue;
+            }
+            throw new Error(`Unknown argument for gloss init-hooks: ${arg}`);
+        }
+        return options;
+    }
     if (isCommand && command === "serve" && firstArg !== undefined) {
         throw new Error(`Unknown command: ${firstArg}`);
     }
@@ -183,6 +288,7 @@ const parseArgs = (args) => {
         command: "serve",
         ...base,
         noOpen: false,
+        noCache: false,
         port: DEFAULT_PORT,
     };
     for (let index = 0; index < commandArgs.length; index += 1) {
@@ -199,6 +305,10 @@ const parseArgs = (args) => {
             options.noOpen = true;
             continue;
         }
+        if (arg === "--no-cache") {
+            options.noCache = true;
+            continue;
+        }
         if (arg === "-p" || arg === "--port") {
             const nextValue = commandArgs[index + 1];
             if (!nextValue) {
@@ -231,6 +341,87 @@ const printConfigError = (error) => {
     console.error("Gloss could not start: invalid gloss.config.ts.");
     console.error(error.message);
 };
+const renderGeneratedConfig = (candidatePath, locales) => {
+    const defaultLocale = locales.includes("en") ? "en" : locales[0] ?? "en";
+    const localeList = locales.map((locale) => JSON.stringify(locale)).join(", ");
+    const pathLiteral = JSON.stringify(candidatePath);
+    return `module.exports = {
+  locales: [${localeList}],
+  defaultLocale: ${JSON.stringify(defaultLocale)},
+  path: ${pathLiteral},
+  format: "json",
+};
+`;
+};
+const chooseCandidateInteractive = async (candidates) => {
+    if (candidates.length === 1) {
+        return candidates[0];
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return candidates[0];
+    }
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        console.log("Gloss setup: multiple locale directories were found.");
+        candidates.forEach((candidate, index) => {
+            const marker = index === 0 ? " (recommended)" : "";
+            console.log(`  ${index + 1}. ${candidate.path} -> [${candidate.locales.join(", ")}]${marker}`);
+        });
+        while (true) {
+            const answer = (await rl.question(`Choose a locale directory [1-${candidates.length}] (default 1): `)).trim();
+            if (!answer) {
+                return candidates[0];
+            }
+            const selection = Number.parseInt(answer, 10);
+            if (Number.isFinite(selection) && selection >= 1 && selection <= candidates.length) {
+                return candidates[selection - 1];
+            }
+            console.log(`Please enter a number between 1 and ${candidates.length}.`);
+        }
+    }
+    finally {
+        rl.close();
+    }
+};
+const bootstrapConfigIfMissing = async () => {
+    const cwd = projectRoot();
+    const candidates = await discoverLocaleDirectoryCandidates(cwd);
+    if (candidates.length === 0) {
+        return false;
+    }
+    console.log("No Gloss config found. Starting first-run setup.");
+    const selected = await chooseCandidateInteractive(candidates);
+    const configFilePath = path.join(cwd, GENERATED_CONFIG_FILE);
+    const content = renderGeneratedConfig(selected.path, selected.locales);
+    await fs.writeFile(configFilePath, content, "utf8");
+    console.log(`Created ${GENERATED_CONFIG_FILE} using ${selected.path}.`);
+    console.log("Starting Gloss with the generated config.");
+    return true;
+};
+const formatBytes = (value) => {
+    if (value < 1024) {
+        return `${value} B`;
+    }
+    if (value < 1024 * 1024) {
+        return `${(value / 1024).toFixed(1)} KB`;
+    }
+    return `${(value / (1024 * 1024)).toFixed(1)} MB`;
+};
+const formatAge = (ageMs) => {
+    if (ageMs === null) {
+        return "n/a";
+    }
+    const totalSeconds = Math.max(0, Math.floor(ageMs / 1000));
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    if (minutes === 0) {
+        return `${seconds}s`;
+    }
+    return `${minutes}m ${seconds}s`;
+};
 async function main() {
     const options = parseArgs(process.argv.slice(2));
     if (options.help) {
@@ -241,21 +432,86 @@ async function main() {
         console.log(await getVersion());
         return;
     }
-    const cfg = await loadGlossConfig();
+    if (options.command === "init-hooks") {
+        const result = await installPreCommitHooks(projectRoot());
+        console.log("Gloss hook installation");
+        for (const message of result.messages) {
+            console.log(`- ${message}`);
+        }
+        return;
+    }
+    if (options.command === "baseline-reset") {
+        const result = await resetIssueBaseline(projectRoot());
+        if (result.existed) {
+            console.log(`Removed baseline at ${result.baselinePath}`);
+        }
+        else {
+            console.log(`No baseline found at ${result.baselinePath}`);
+        }
+        return;
+    }
+    if (options.command === "cache-clear") {
+        const result = await clearGlossCaches(projectRoot());
+        console.log("Gloss cache clear");
+        console.log(`- Usage scanner cache: ${result.usage.fileCount} files across ${result.usage.bucketCount} buckets removed`);
+        console.log(`- Key usage cache: ${result.keyUsage.fileCount} files across ${result.keyUsage.bucketCount} buckets removed`);
+        console.log(`- Cache metrics file: ${result.metrics.existed ? "removed" : "not found"} (${result.metrics.path})`);
+        return;
+    }
+    let cfg;
+    try {
+        cfg = await loadGlossConfig();
+    }
+    catch (error) {
+        if (error instanceof GlossConfigError && error.code === "MISSING_CONFIG") {
+            const generated = await bootstrapConfigIfMissing();
+            if (generated) {
+                cfg = await loadGlossConfig();
+            }
+            else {
+                throw error;
+            }
+        }
+        else {
+            throw error;
+        }
+    }
     if (options.command === "check") {
-        const result = await runGlossCheck(cfg);
-        printGlossCheck(result, options.format);
+        const result = await runGlossCheck(cfg, {
+            useCache: !options.noCache,
+        });
+        let baseline;
+        try {
+            baseline = await updateIssueBaseline(projectRoot(), result.summary);
+        }
+        catch (error) {
+            console.error(`Warning: failed to update issue baseline: ${error.message}`);
+        }
+        printGlossCheck(result, options.format, baseline);
         if (!result.ok) {
             process.exit(1);
         }
         return;
     }
+    if (options.command === "cache-status") {
+        const status = await getCacheStatus(projectRoot(), cfg);
+        console.log("Gloss cache status");
+        console.log(`- Metrics file: ${status.metricsFileFound ? "found" : "not found"}${status.metricsUpdatedAt ? ` (updated ${status.metricsUpdatedAt})` : ""}`);
+        console.log(`- Total cached files: ${status.totalCachedFiles} (${formatBytes(status.totalCachedSizeBytes)})`);
+        console.log(`- Oldest cache entry age: ${formatAge(status.oldestEntryAgeMs)}`);
+        console.log(`- Stale relative to config: ${status.staleRelativeToConfig ? "yes" : "no"}`);
+        console.log(`- Usage scanner: ${status.usageScanner.fileCount} files, ${formatBytes(status.usageScanner.totalSizeBytes)}, source=${status.usageScanner.source}`);
+        console.log(`- Key usage: ${status.keyUsage.fileCount} files, ${formatBytes(status.keyUsage.totalSizeBytes)}, source=${status.keyUsage.source}`);
+        return;
+    }
     if (options.command === "gen-types") {
         const result = await generateKeyTypes(cfg, { outFile: options.outFile });
         console.log(`Generated ${result.keyCount} keys in ${result.outFile}`);
         return;
     }
-    const { port } = await startServer(cfg, options.port);
+    const { port } = await startServer(cfg, options.port, {
+        useCache: !options.noCache,
+    });
     const url = options.command === "open-key"
         ? `http://localhost:${port}/?key=${encodeURIComponent(options.key)}`
         : `http://localhost:${port}`;

package/dist/server.js

@@ -3,11 +3,14 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import express from "express";
 import cors from "cors";
+import { updateIssueBaseline } from "./baseline.js";
 import { runGlossCheck } from "./check.js";
-import { readAllTranslations, writeAllTranslations } from "./fs.js";
+import { readAllTranslations, WriteLockError, writeAllTranslations } from "./fs.js";
 import { buildGitKeyDiff } from "./gitDiff.js";
+import { flattenObject, unflattenObject } from "./translationTree.js";
 import { buildKeyUsageMap } from "./usage.js";
 import { inferUsageRoot, scanUsage } from "./usageScanner.js";
+import { buildXliffDocument, parseXliffTargets } from "./xliff.js";
 import { renameKeyUsage } from "./renameKeyUsage.js";
 const resolveUiDistPath = () => {
     const runtimeDir = path.dirname(fileURLToPath(import.meta.url));
@@ -25,24 +28,57 @@ const resolveUiDistPath = () => {
     return null;
 };
 export function createServerApp(cfg) {
+    return createServerAppWithOptions(cfg);
+}
+const shouldBypassCache = (value) => {
+    if (typeof value !== "string") {
+        return false;
+    }
+    return value === "1" || value.toLowerCase() === "true";
+};
+export function createServerAppWithOptions(cfg, runtimeOptions = {}) {
     const app = express();
     app.use(cors());
     app.use(express.json({ limit: "5mb" }));
+    const defaultUseCache = runtimeOptions.useCache !== false;
+    const requestUseCache = (req) => {
+        if (!defaultUseCache) {
+            return false;
+        }
+        const noCacheValue = req.query.noCache;
+        if (Array.isArray(noCacheValue)) {
+            return !noCacheValue.some((entry) => shouldBypassCache(entry));
+        }
+        return !shouldBypassCache(noCacheValue);
+    };
     app.get("/api/config", (_req, res) => res.json(cfg));
     app.get("/api/translations", async (_req, res) => {
         const data = await readAllTranslations(cfg);
         res.json(data);
     });
     app.get("/api/usage", async (_req, res) => {
-        const usage = await scanUsage(inferUsageRoot(cfg), cfg.scan);
+        const usage = await scanUsage(inferUsageRoot(cfg), cfg.scan, {
+            useCache: requestUseCache(_req),
+        });
         res.json(usage);
     });
-    app.get("/api/key-usage", async (_req, res) => {
-        const usage = await buildKeyUsageMap(cfg);
+    app.get("/api/key-usage", async (req, res) => {
+        const usage = await buildKeyUsageMap(cfg, {
+            useCache: requestUseCache(req),
+        });
         res.json(usage);
     });
     app.get("/api/check", async (req, res) => {
-        const result = await runGlossCheck(cfg);
+        const result = await runGlossCheck(cfg, {
+            useCache: requestUseCache(req),
+        });
+        let baseline = null;
+        try {
+            baseline = await updateIssueBaseline(process.env.INIT_CWD || process.cwd(), result.summary);
+        }
+        catch {
+            baseline = null;
+        }
         const summaryValue = typeof req.query.summary === "string" ? req.query.summary : "";
         const summaryOnly = summaryValue === "1" || summaryValue === "true";
         if (summaryOnly) {
@@ -51,10 +87,11 @@ export function createServerApp(cfg) {
                 generatedAt: result.generatedAt,
                 summary: result.summary,
                 hardcodedTexts: result.hardcodedTexts.slice(0, 20),
+                baseline,
             });
             return;
         }
-        res.json(result);
+        res.json({ ...result, baseline });
     });
     app.get("/api/git-diff", async (req, res) => {
         const base = typeof req.query.base === "string" && req.query.base.trim()
@@ -63,10 +100,103 @@ export function createServerApp(cfg) {
         const diff = await buildGitKeyDiff(cfg, base);
         res.json(diff);
     });
+    app.get("/api/xliff/export", async (req, res) => {
+        const locale = typeof req.query.locale === "string" ? req.query.locale.trim() : "";
+        const sourceLocale = typeof req.query.sourceLocale === "string" && req.query.sourceLocale.trim()
+            ? req.query.sourceLocale.trim()
+            : cfg.defaultLocale;
+        if (!locale || !cfg.locales.includes(locale)) {
+            res.status(400).json({
+                ok: false,
+                error: "Query parameter `locale` is required and must be one of configured locales.",
+            });
+            return;
+        }
+        if (!cfg.locales.includes(sourceLocale)) {
+            res.status(400).json({
+                ok: false,
+                error: "Query parameter `sourceLocale` must be one of configured locales when provided.",
+            });
+            return;
+        }
+        const data = await readAllTranslations(cfg);
+        const xml = buildXliffDocument({
+            translations: data,
+            locales: cfg.locales,
+            sourceLocale,
+            targetLocale: locale,
+        });
+        res.setHeader("Content-Type", "application/xliff+xml; charset=utf-8");
+        res.setHeader("Content-Disposition", `attachment; filename="gloss-${locale}.xlf"`);
+        res.send(xml);
+    });
+    app.post("/api/xliff/import", async (req, res) => {
+        const locale = typeof req.query.locale === "string" ? req.query.locale.trim() : "";
+        if (!locale || !cfg.locales.includes(locale)) {
+            res.status(400).json({
+                ok: false,
+                error: "Query parameter `locale` is required and must be one of configured locales.",
+            });
+            return;
+        }
+        const body = req.body;
+        if (typeof body.content !== "string" || body.content.trim().length === 0) {
+            res.status(400).json({
+                ok: false,
+                error: "Request body must include non-empty `content` string.",
+            });
+            return;
+        }
+        try {
+            const parsedTargets = parseXliffTargets(body.content);
+            const updates = Object.entries(parsedTargets).filter(([key]) => key.trim().length > 0);
+            if (updates.length === 0) {
+                res.status(400).json({
+                    ok: false,
+                    error: "No translatable units found in XLIFF content.",
+                });
+                return;
+            }
+            const data = await readAllTranslations(cfg);
+            const localeFlat = flattenObject(data[locale] ?? {});
+            for (const [key, value] of updates) {
+                localeFlat[key] = value;
+            }
+            data[locale] = unflattenObject(localeFlat);
+            await writeAllTranslations(cfg, data);
+            res.json({
+                ok: true,
+                locale,
+                updated: updates.length,
+            });
+        }
+        catch (error) {
+            if (error instanceof WriteLockError) {
+                res.status(409).json({ ok: false, error: error.message });
+                return;
+            }
+            res.status(400).json({
+                ok: false,
+                error: error.message || "Failed to parse XLIFF content.",
+            });
+        }
+    });
     app.post("/api/translations", async (req, res) => {
         const data = req.body;
-        await writeAllTranslations(cfg, data);
-        res.json({ ok: true });
+        try {
+            await writeAllTranslations(cfg, data);
+            res.json({ ok: true });
+        }
+        catch (error) {
+            if (error instanceof WriteLockError) {
+                res.status(409).json({ ok: false, error: error.message });
+                return;
+            }
+            res.status(500).json({
+                ok: false,
+                error: "Failed to write translation files.",
+            });
+        }
     });
     app.post("/api/rename-key", async (req, res) => {
         const body = req.body;
@@ -105,8 +235,8 @@ export function createServerApp(cfg) {
     }
     return app;
 }
-export async function startServer(cfg, port = 5179) {
-    const app = createServerApp(cfg);
+export async function startServer(cfg, port = 5179, runtimeOptions = {}) {
+    const app = createServerAppWithOptions(cfg, runtimeOptions);
     const server = await new Promise((resolve) => {
         const nextServer = app.listen(port, () => resolve(nextServer));
     });

package/dist/translationTree.js

@@ -20,3 +20,23 @@ export const flattenObject = (obj) => {
     visit(obj, "");
     return result;
 };
+export const unflattenObject = (flat) => {
+    const root = {};
+    for (const [key, value] of Object.entries(flat)) {
+        const parts = key.split(".").filter((part) => part.length > 0);
+        if (parts.length === 0) {
+            continue;
+        }
+        let cursor = root;
+        for (let index = 0; index < parts.length - 1; index += 1) {
+            const part = parts[index];
+            const existing = cursor[part];
+            if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
+                cursor[part] = {};
+            }
+            cursor = cursor[part];
+        }
+        cursor[parts[parts.length - 1]] = value;
+    }
+    return root;
+};