@mxml3gend/gloss 0.1.1 → 0.1.3

package/README.md

@@ -35,6 +35,12 @@ export default {
   defaultLocale: "en",
   path: "src/i18n",
   format: "json",
+  scan: {
+    include: ["src/**/*.{ts,tsx,js,jsx}"],
+    exclude: ["**/*.test.tsx"],
+    mode: "regex", // or "ast" for strict parsing
+  },
+  strictPlaceholders: true, // default true; set false to treat placeholder mismatches as warnings
 };
 ```
 
@@ -46,6 +52,10 @@ module.exports = {
   defaultLocale: "en",
   path: "src/i18n",
   format: "json",
+  scan: {
+    mode: "ast",
+  },
+  strictPlaceholders: false,
 };
 ```
 
@@ -55,5 +65,69 @@ module.exports = {
 gloss --help
 gloss --version
 gloss --no-open
+gloss --no-cache
 gloss --port 5179
+gloss open key auth.login.title
+gloss check --no-cache
+gloss cache status
+gloss cache clear
+npm run test:perf
+```
+
+## CI Guardrails
+
+Run project checks for missing/orphan/invalid keys, placeholder mismatches, and potential hardcoded UI text:
+
+```bash
+gloss check
+```
+
+Machine-readable output:
+
+```bash
+gloss check --format json
+gloss check --format both
+```
+
+`gloss check` exits with code `1` when issues are found, so it is CI-friendly.
+
+The local UI also consumes this data through `/api/check` and shows a hardcoded-text status chip.
+
+## Performance Regression Gate
+
+Gloss ships with a deterministic 1000-key fixture regression test for scanner performance.
+
+```bash
+npm run test:perf
+```
+
+Optional environment overrides:
+
+```bash
+GLOSS_PERF_COLD_MAX_MS=5000
+GLOSS_PERF_WARM_MAX_MS=3500
+```
+
+## Typed Key Generation
+
+Generate `i18n-keys.d.ts` from current translation keys:
+
+```bash
+gloss gen-types
+```
+
+Use the generated `I18nKey` type in your app's `t(...)` signature to get key autocomplete while typing.
+
+Custom output path:
+
+```bash
+gloss gen-types --out src/types/i18n-keys.d.ts
+```
+
+## Deep-Link Open
+
+Open Gloss directly focused on a key:
+
+```bash
+gloss open key auth.login.title
 ```

package/dist/baseline.js

@@ -0,0 +1,118 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const BASELINE_DIRECTORY = ".gloss";
+const BASELINE_FILENAME = "baseline.json";
+const SUMMARY_KEYS = [
+    "missingTranslations",
+    "orphanKeys",
+    "invalidKeys",
+    "placeholderMismatches",
+    "hardcodedTexts",
+    "errorIssues",
+    "warningIssues",
+    "totalIssues",
+];
+const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+const emptyDelta = () => ({
+    missingTranslations: 0,
+    orphanKeys: 0,
+    invalidKeys: 0,
+    placeholderMismatches: 0,
+    hardcodedTexts: 0,
+    errorIssues: 0,
+    warningIssues: 0,
+    totalIssues: 0,
+});
+const normalizeSummary = (value) => {
+    if (!value || typeof value !== "object") {
+        return null;
+    }
+    const source = value;
+    const next = {};
+    for (const key of SUMMARY_KEYS) {
+        const entry = source[key];
+        if (!isFiniteNumber(entry)) {
+            return null;
+        }
+        next[key] = entry;
+    }
+    return next;
+};
+const baselineFilePath = (rootDir) => path.join(rootDir, BASELINE_DIRECTORY, BASELINE_FILENAME);
+const readBaselineFile = async (rootDir) => {
+    const filePath = baselineFilePath(rootDir);
+    try {
+        const raw = await fs.readFile(filePath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed.schemaVersion !== 1 || typeof parsed.updatedAt !== "string") {
+            return null;
+        }
+        const summary = normalizeSummary(parsed.summary);
+        if (!summary) {
+            return null;
+        }
+        return {
+            schemaVersion: 1,
+            updatedAt: parsed.updatedAt,
+            summary,
+        };
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT") {
+            return null;
+        }
+        return null;
+    }
+};
+const computeDelta = (current, previous) => {
+    if (!previous) {
+        return emptyDelta();
+    }
+    const delta = {};
+    for (const key of SUMMARY_KEYS) {
+        delta[key] = current[key] - previous[key];
+    }
+    return delta;
+};
+export async function updateIssueBaseline(rootDir, summary) {
+    const previous = await readBaselineFile(rootDir);
+    const delta = computeDelta(summary, previous?.summary ?? null);
+    const currentUpdatedAt = new Date().toISOString();
+    const baseline = {
+        schemaVersion: 1,
+        updatedAt: currentUpdatedAt,
+        summary,
+    };
+    const filePath = baselineFilePath(rootDir);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(`${filePath}.tmp`, `${JSON.stringify(baseline, null, 2)}\n`, "utf8");
+    await fs.rename(`${filePath}.tmp`, filePath);
+    return {
+        hasPrevious: Boolean(previous),
+        baselinePath: path.relative(rootDir, filePath) || filePath,
+        previousUpdatedAt: previous?.updatedAt ?? null,
+        currentUpdatedAt,
+        delta,
+    };
+}
+export async function resetIssueBaseline(rootDir) {
+    const filePath = baselineFilePath(rootDir);
+    let existed = true;
+    try {
+        await fs.rm(filePath);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT") {
+            existed = false;
+        }
+        else {
+            throw error;
+        }
+    }
+    return {
+        existed,
+        baselinePath: path.relative(rootDir, filePath) || filePath,
+    };
+}

package/dist/cache.js

@@ -0,0 +1,78 @@
+import { clearCacheMetrics, readCacheMetrics, } from "./cacheMetrics.js";
+import { clearKeyUsageCache, getKeyUsageCacheStatus, keyUsageCacheKey, } from "./usage.js";
+import { clearUsageScannerCache, getUsageScannerCacheStatus, inferUsageRoot, usageScannerCacheKey, } from "./usageScanner.js";
+const fromMetricsEntry = (cacheKey, entry, staleRelativeToConfig) => {
+    if (!entry) {
+        return {
+            cacheKey,
+            fileCount: 0,
+            totalSizeBytes: 0,
+            oldestMtimeMs: null,
+            staleRelativeToConfig,
+            source: "missing",
+        };
+    }
+    return {
+        cacheKey,
+        fileCount: entry.fileCount,
+        totalSizeBytes: entry.totalSizeBytes,
+        oldestMtimeMs: entry.oldestMtimeMs,
+        staleRelativeToConfig,
+        source: "metrics",
+    };
+};
+export const getCacheStatus = async (rootDir, cfg) => {
+    const usageKey = usageScannerCacheKey(inferUsageRoot(cfg), cfg.scan);
+    const keyUsageKey = keyUsageCacheKey(cfg);
+    const metrics = await readCacheMetrics(rootDir);
+    const metricsUsage = metrics?.usageScanner?.[usageKey] ?? null;
+    const metricsKeyUsage = metrics?.keyUsage?.[keyUsageKey] ?? null;
+    const usageStale = !metricsUsage;
+    const keyUsageStale = !metricsKeyUsage;
+    const usageBucket = metricsUsage
+        ? fromMetricsEntry(usageKey, metricsUsage, usageStale)
+        : (() => {
+            const memory = getUsageScannerCacheStatus(inferUsageRoot(cfg), cfg.scan);
+            return {
+                ...memory,
+                staleRelativeToConfig: memory.fileCount === 0,
+                source: "memory",
+            };
+        })();
+    const keyUsageBucket = metricsKeyUsage
+        ? fromMetricsEntry(keyUsageKey, metricsKeyUsage, keyUsageStale)
+        : (() => {
+            const memory = getKeyUsageCacheStatus(cfg);
+            return {
+                ...memory,
+                staleRelativeToConfig: memory.fileCount === 0,
+                source: "memory",
+            };
+        })();
+    const totalCachedFiles = usageBucket.fileCount + keyUsageBucket.fileCount;
+    const totalCachedSizeBytes = usageBucket.totalSizeBytes + keyUsageBucket.totalSizeBytes;
+    const oldestMtimeCandidates = [usageBucket.oldestMtimeMs, keyUsageBucket.oldestMtimeMs]
+        .filter((value) => typeof value === "number" && Number.isFinite(value));
+    const oldestMtimeMs = oldestMtimeCandidates.length > 0 ? Math.min(...oldestMtimeCandidates) : null;
+    const oldestEntryAgeMs = oldestMtimeMs === null ? null : Math.max(0, Date.now() - oldestMtimeMs);
+    return {
+        metricsFileFound: metrics !== null,
+        metricsUpdatedAt: metrics?.updatedAt ?? null,
+        usageScanner: usageBucket,
+        keyUsage: keyUsageBucket,
+        totalCachedFiles,
+        totalCachedSizeBytes,
+        oldestEntryAgeMs,
+        staleRelativeToConfig: usageBucket.staleRelativeToConfig || keyUsageBucket.staleRelativeToConfig,
+    };
+};
+export const clearGlossCaches = async (rootDir) => {
+    const usage = clearUsageScannerCache();
+    const keyUsage = clearKeyUsageCache();
+    const metrics = await clearCacheMetrics(rootDir);
+    return {
+        usage,
+        keyUsage,
+        metrics,
+    };
+};

package/dist/cacheMetrics.js

@@ -0,0 +1,120 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const CACHE_DIRECTORY = ".gloss";
+const CACHE_METRICS_FILENAME = "cache-metrics.json";
+const metricsFilePath = (rootDir) => path.join(rootDir, CACHE_DIRECTORY, CACHE_METRICS_FILENAME);
+const emptyMetrics = () => ({
+    schemaVersion: 1,
+    updatedAt: new Date().toISOString(),
+    usageScanner: {},
+    keyUsage: {},
+});
+const normalizeEntry = (value) => {
+    if (!value || typeof value !== "object") {
+        return null;
+    }
+    const source = value;
+    if (typeof source.cacheKey !== "string" || source.cacheKey.trim().length === 0) {
+        return null;
+    }
+    if (typeof source.fileCount !== "number" ||
+        !Number.isFinite(source.fileCount) ||
+        source.fileCount < 0) {
+        return null;
+    }
+    if (typeof source.totalSizeBytes !== "number" ||
+        !Number.isFinite(source.totalSizeBytes) ||
+        source.totalSizeBytes < 0) {
+        return null;
+    }
+    if (source.oldestMtimeMs !== null &&
+        (typeof source.oldestMtimeMs !== "number" || !Number.isFinite(source.oldestMtimeMs))) {
+        return null;
+    }
+    if (typeof source.updatedAt !== "string") {
+        return null;
+    }
+    return {
+        cacheKey: source.cacheKey,
+        fileCount: source.fileCount,
+        totalSizeBytes: source.totalSizeBytes,
+        oldestMtimeMs: source.oldestMtimeMs,
+        updatedAt: source.updatedAt,
+    };
+};
+const normalizeEntries = (value) => {
+    if (!value || typeof value !== "object") {
+        return {};
+    }
+    const source = value;
+    const entries = {};
+    for (const [key, rawEntry] of Object.entries(source)) {
+        const entry = normalizeEntry(rawEntry);
+        if (entry) {
+            entries[key] = entry;
+        }
+    }
+    return entries;
+};
+export const readCacheMetrics = async (rootDir) => {
+    const filePath = metricsFilePath(rootDir);
+    try {
+        const raw = await fs.readFile(filePath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed.schemaVersion !== 1 || typeof parsed.updatedAt !== "string") {
+            return null;
+        }
+        return {
+            schemaVersion: 1,
+            updatedAt: parsed.updatedAt,
+            usageScanner: normalizeEntries(parsed.usageScanner),
+            keyUsage: normalizeEntries(parsed.keyUsage),
+        };
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT") {
+            return null;
+        }
+        return null;
+    }
+};
+export const updateCacheMetrics = async (rootDir, kind, entry) => {
+    const existing = (await readCacheMetrics(rootDir)) ?? emptyMetrics();
+    const updatedAt = new Date().toISOString();
+    const next = {
+        ...existing,
+        updatedAt,
+        [kind]: {
+            ...existing[kind],
+            [entry.cacheKey]: {
+                ...entry,
+                updatedAt,
+            },
+        },
+    };
+    const filePath = metricsFilePath(rootDir);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(`${filePath}.tmp`, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+    await fs.rename(`${filePath}.tmp`, filePath);
+};
+export const clearCacheMetrics = async (rootDir) => {
+    const filePath = metricsFilePath(rootDir);
+    let existed = true;
+    try {
+        await fs.rm(filePath);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT") {
+            existed = false;
+        }
+        else {
+            throw error;
+        }
+    }
+    return {
+        existed,
+        path: path.relative(rootDir, filePath) || filePath,
+    };
+};