i18n-sharpen 0.2.0

package/dist/cli.js

@@ -0,0 +1,1599 @@
+#!/usr/bin/env node
+import * as fs8 from 'fs';
+import * as path3 from 'path';
+import { fileURLToPath } from 'url';
+import { Command } from 'commander';
+import pc5 from 'picocolors';
+import YAML from 'yaml';
+import { z } from 'zod';
+
+// src/core/errors.ts
+var I18nSharpenError = class extends Error {
+  constructor(error, message) {
+    super(message ?? error.message);
+    this.error = error;
+    this.name = "I18nSharpenError";
+  }
+  error;
+};
+
+// src/core/scanner/regex.ts
+function escapeRegex(input) {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function buildKeyRegex(matchFunctions) {
+  const functionsJoined = matchFunctions.map(escapeRegex).join("|");
+  return new RegExp(
+    "\\b(?:" + functionsJoined + ")\\s*\\(\\s*(['\"`])([a-zA-Z0-9_\\-.:]+)\\1",
+    "g"
+  );
+}
+function buildAttrRegex(matchAttributes) {
+  const attrsJoined = matchAttributes.map(escapeRegex).join("|");
+  return new RegExp(
+    "(?:^|[\\s/{(>])(?:" + attrsJoined + ")\\s*=\\s*(['\"`])([a-zA-Z0-9_\\-.:]+)\\1",
+    "g"
+  );
+}
+function buildDynamicCallRegex(matchFunctions) {
+  const functionsJoined = matchFunctions.map(escapeRegex).join("|");
+  return new RegExp("\\b(?:" + functionsJoined + ")\\s*\\(\\s*([^)]*)\\)", "g");
+}
+
+// src/core/scanner/text.ts
+function stripComments(code) {
+  const out = [];
+  const stack = [];
+  let i = 0;
+  const n = code.length;
+  while (i < n) {
+    const ch = code[i];
+    const next = i + 1 < n ? code[i + 1] : "";
+    const top = stack.length > 0 ? stack[stack.length - 1] : null;
+    if (top) {
+      if (top.kind === "template" && ch === "$" && next === "{") {
+        top.templateDepth++;
+        out.push("${");
+        i += 2;
+        continue;
+      }
+      if (top.kind === "template" && top.templateDepth > 0 && ch === "}") {
+        top.templateDepth--;
+        out.push("}");
+        i++;
+        continue;
+      }
+      if (top.kind === "template" && top.templateDepth > 0) ; else {
+        if (ch === "\\" && i + 1 < n) {
+          out.push(ch, code[i + 1]);
+          i += 2;
+          continue;
+        }
+        if (top.kind === "single" && ch === "'" || top.kind === "double" && ch === '"' || top.kind === "template" && ch === "`") {
+          stack.pop();
+          out.push(ch);
+          i++;
+          continue;
+        }
+        out.push(ch);
+        i++;
+        continue;
+      }
+    }
+    if (ch === "/" && next === "*") {
+      i += 2;
+      while (i < n && !(code[i] === "*" && i + 1 < n && code[i + 1] === "/")) {
+        i++;
+      }
+      i += 2;
+      out.push(" ");
+      continue;
+    }
+    if (ch === "/" && next === "/") {
+      i += 2;
+      while (i < n && code[i] !== "\n") {
+        i++;
+      }
+      out.push(" ");
+      continue;
+    }
+    if (ch === "'") {
+      stack.push({ kind: "single", templateDepth: 0 });
+      out.push(ch);
+      i++;
+      continue;
+    }
+    if (ch === '"') {
+      stack.push({ kind: "double", templateDepth: 0 });
+      out.push(ch);
+      i++;
+      continue;
+    }
+    if (ch === "`") {
+      stack.push({ kind: "template", templateDepth: 0 });
+      out.push(ch);
+      i++;
+      continue;
+    }
+    out.push(ch);
+    i++;
+  }
+  return out.join("");
+}
+function isStaticStringLiteral(arg) {
+  const trimmed = arg.trim();
+  if (trimmed.length < 2) return false;
+  const quote = trimmed[0];
+  if (quote !== "'" && quote !== '"' && quote !== "`") return false;
+  let i = 1;
+  while (i < trimmed.length) {
+    const ch = trimmed[i];
+    if (ch === "\\" && i + 1 < trimmed.length) {
+      i += 2;
+      continue;
+    }
+    if (quote === "`" && ch === "$" && trimmed[i + 1] === "{") {
+      return false;
+    }
+    if (ch === quote) {
+      return i === trimmed.length - 1;
+    }
+    i++;
+  }
+  return false;
+}
+function getBaseKey(key, suffixes) {
+  for (const suffix of suffixes) {
+    if (key.endsWith(suffix)) {
+      return key.slice(0, -suffix.length);
+    }
+  }
+  return key;
+}
+function matchWildcard(pattern, key) {
+  if (pattern === "*") return true;
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  const regex = new RegExp(`^${escaped}$`);
+  return regex.test(key);
+}
+function isKeyUsed(key, usedKeys, ignoreKeys, pluralSuffixes) {
+  if (usedKeys.has(key)) return true;
+  if (ignoreKeys) {
+    for (const pattern of ignoreKeys) {
+      if (matchWildcard(pattern, key)) {
+        return true;
+      }
+    }
+  }
+  const baseKey = getBaseKey(key, pluralSuffixes);
+  if (baseKey !== key && usedKeys.has(baseKey)) {
+    return true;
+  }
+  return false;
+}
+function getFiles(dir, extensions, excludeDirs) {
+  const results = [];
+  if (!fs8.existsSync(dir)) return results;
+  let entries;
+  try {
+    entries = fs8.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    if (entry.isSymbolicLink()) continue;
+    const filePath = path3.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!excludeDirs.includes(entry.name)) {
+        results.push(...getFiles(filePath, extensions, excludeDirs));
+      }
+    } else if (entry.isFile()) {
+      if (extensions.includes(path3.extname(entry.name))) {
+        results.push(filePath);
+      }
+    }
+  }
+  return results;
+}
+function scanSourceFiles(config, cwd) {
+  const filesToScan = [];
+  for (const scanDir of config.scanDirs) {
+    const scanDirAbs = path3.resolve(cwd, scanDir);
+    if (fs8.existsSync(scanDirAbs)) {
+      filesToScan.push(
+        ...getFiles(
+          scanDirAbs,
+          config.fileExtensions ?? [],
+          config.excludeDirs ?? []
+        )
+      );
+    }
+  }
+  return filesToScan;
+}
+
+// src/core/scanner/index.ts
+function detectUsedKeys(files, matchFunctions, matchAttributes) {
+  const keyRegex = buildKeyRegex(matchFunctions);
+  const attrRegex = buildAttrRegex(matchAttributes);
+  const fileContents = files.map((file) => {
+    try {
+      const content = fs8.readFileSync(file, "utf8");
+      return stripComments(content);
+    } catch {
+      return "";
+    }
+  });
+  const usedKeys = /* @__PURE__ */ new Set();
+  for (const cleanContent of fileContents) {
+    for (const match of cleanContent.matchAll(keyRegex)) {
+      const key = match[2];
+      if (key.endsWith(".")) continue;
+      usedKeys.add(key);
+    }
+    for (const match of cleanContent.matchAll(attrRegex)) {
+      const key = match[2];
+      if (key.endsWith(".")) continue;
+      usedKeys.add(key);
+    }
+  }
+  return { usedKeys, fileContents };
+}
+
+// src/utils.ts
+var emojiDisabled = typeof process !== "undefined" && !!process.env.NO_EMOJI && process.env.NO_EMOJI !== "0" && process.env.NO_EMOJI.toLowerCase() !== "false";
+var glyphs = {
+  ok: emojiDisabled ? "[OK]" : "\u2705",
+  warn: emojiDisabled ? "[WARN]" : "\u26A0\uFE0F ",
+  err: emojiDisabled ? "[ERR]" : "\u274C"
+};
+var log = {
+  header(title) {
+    console.log(`
+${pc5.bold(pc5.cyan(`=== ${title} ===`))}`);
+  },
+  info(msg) {
+    console.log(msg);
+  },
+  success(msg) {
+    console.log(`${pc5.green(glyphs.ok)} ${msg}`);
+  },
+  warn(msg) {
+    console.log(`${pc5.yellow(`${glyphs.warn} Warning:`)} ${msg}`);
+  },
+  error(msg) {
+    console.error(`${pc5.red(`${glyphs.err} Error:`)} ${msg}`);
+  }
+};
+
+// src/core/locale-io/transform.ts
+var FORBIDDEN_KEY_SEGMENTS = /* @__PURE__ */ new Set([
+  "__proto__",
+  "prototype",
+  "constructor"
+]);
+function flattenObject(obj, prefix = "") {
+  const map = {};
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      if (FORBIDDEN_KEY_SEGMENTS.has(key)) continue;
+      const value = obj[key];
+      const newKey = prefix ? `${prefix}.${key}` : key;
+      if (Object.prototype.hasOwnProperty.call(map, newKey)) {
+        log.warn(
+          `Key collision in locale: '${newKey}' is produced both as a flat key and as a nested path. The later definition wins.`
+        );
+      }
+      if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        Object.assign(
+          map,
+          flattenObject(value, newKey)
+        );
+      } else {
+        map[newKey] = String(value);
+      }
+    }
+  }
+  return map;
+}
+function setNestedValue(obj, keyPath, value) {
+  const parts = keyPath.split(".");
+  for (const part of parts) {
+    if (FORBIDDEN_KEY_SEGMENTS.has(part)) {
+      return;
+    }
+  }
+  let current = obj;
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    if (i === parts.length - 1) {
+      current[part] = value;
+    } else {
+      if (current[part] === void 0 || typeof current[part] !== "object" || current[part] === null) {
+        current[part] = {};
+      }
+      current = current[part];
+    }
+  }
+}
+function buildNestedObject(flatObj) {
+  const result = {};
+  for (const key in flatObj) {
+    if (Object.prototype.hasOwnProperty.call(flatObj, key)) {
+      setNestedValue(result, key, flatObj[key]);
+    }
+  }
+  return result;
+}
+var unflattenObject = buildNestedObject;
+function normalizeDisplayPath(p) {
+  return p.split(path3.sep).join("/");
+}
+function findLocaleFile(localesDir, lang) {
+  const extensions = [".json", ".yaml", ".yml"];
+  const found = extensions.map((ext) => path3.join(localesDir, `${lang}${ext}`)).filter((p) => fs8.existsSync(p));
+  if (found.length === 0) return null;
+  if (found.length > 1) {
+    log.warn(
+      `Multiple locale files found for '${lang}' in ${localesDir}: ${found.map((p) => path3.basename(p)).join(
+        ", "
+      )}. Using '${path3.basename(found[0])}'. Remove the duplicates to silence this warning.`
+    );
+  }
+  return found[0];
+}
+function readLocaleFile(filePath) {
+  const ext = path3.extname(filePath).toLowerCase();
+  let content = fs8.readFileSync(filePath, "utf8");
+  if (content.charCodeAt(0) === 65279) {
+    content = content.slice(1);
+  }
+  const trimmed = content.trim();
+  if (trimmed.length === 0) {
+    return {};
+  }
+  if (ext === ".yaml" || ext === ".yml") {
+    const parsed = YAML.parse(trimmed);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  }
+  const parsedJson = JSON.parse(trimmed);
+  return parsedJson && typeof parsedJson === "object" && !Array.isArray(parsedJson) ? parsedJson : {};
+}
+function writeLocaleFile(filePath, obj) {
+  const ext = path3.extname(filePath).toLowerCase();
+  let content = "";
+  if (ext === ".yaml" || ext === ".yml") {
+    content = YAML.stringify(obj, { indent: 2 });
+  } else {
+    content = JSON.stringify(obj, null, 2);
+  }
+  if (!content.endsWith("\n")) {
+    content += "\n";
+  }
+  const tmpPath = `${filePath}.tmp`;
+  fs8.writeFileSync(tmpPath, content, "utf8");
+  try {
+    fs8.renameSync(tmpPath, filePath);
+  } catch (error) {
+    try {
+      fs8.unlinkSync(tmpPath);
+    } catch {
+    }
+    throw error;
+  }
+}
+function loadAllLocales(localesDir, supportedLanguages, onMissing = () => {
+}) {
+  const locales = {};
+  const localesFlat = {};
+  const localeKeySets = {};
+  const localePaths = {};
+  for (const lang of supportedLanguages) {
+    const langPath = findLocaleFile(localesDir, lang);
+    localePaths[lang] = langPath;
+    if (!langPath) {
+      onMissing(lang, localesDir);
+      locales[lang] = {};
+      localesFlat[lang] = {};
+      localeKeySets[lang] = /* @__PURE__ */ new Set();
+      continue;
+    }
+    const parsed = readLocaleFile(langPath);
+    locales[lang] = parsed;
+    localesFlat[lang] = flattenObject(parsed);
+    localeKeySets[lang] = new Set(Object.keys(localesFlat[lang]));
+  }
+  return { locales, localesFlat, localeKeySets, localePaths };
+}
+function loadNamespacedLocales(localesDir, supportedLanguages, onMissing = () => {
+}) {
+  const locales = {};
+  const localesFlat = {};
+  const localeKeySets = {};
+  const localeNamespaces = {};
+  for (const lang of supportedLanguages) {
+    const langDir = path3.join(localesDir, lang);
+    localeNamespaces[lang] = {};
+    if (!fs8.existsSync(langDir) || !fs8.statSync(langDir).isDirectory()) {
+      onMissing(lang, localesDir);
+      locales[lang] = {};
+      localesFlat[lang] = {};
+      localeKeySets[lang] = /* @__PURE__ */ new Set();
+      continue;
+    }
+    const entries = fs8.readdirSync(langDir, { withFileTypes: true });
+    const merged = {};
+    const mergedFlat = {};
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      const ext = path3.extname(entry.name).toLowerCase();
+      if (ext !== ".json" && ext !== ".yaml" && ext !== ".yml") continue;
+      const ns = path3.basename(entry.name, ext);
+      const filePath = path3.join(langDir, entry.name);
+      localeNamespaces[lang][ns] = filePath;
+      const parsed = readLocaleFile(filePath);
+      merged[ns] = parsed;
+      const nsFlat = flattenObject(parsed);
+      for (const [k, v] of Object.entries(nsFlat)) {
+        mergedFlat[`${ns}:${k}`] = v;
+      }
+    }
+    locales[lang] = merged;
+    localesFlat[lang] = mergedFlat;
+    localeKeySets[lang] = new Set(Object.keys(mergedFlat));
+  }
+  return { locales, localesFlat, localeKeySets, localeNamespaces };
+}
+
+// src/commands/extract.ts
+function extract(config, cwd = process.cwd()) {
+  log.header("I18N-SHARPEN EXTRACTOR");
+  const localesDirAbs = path3.resolve(cwd, config.localesDir);
+  if (!fs8.existsSync(localesDirAbs)) {
+    throw new I18nSharpenError({
+      kind: "filesystem",
+      message: `Locales directory not found: ${localesDirAbs}`,
+      path: localesDirAbs
+    });
+  }
+  const files = scanSourceFiles(config, cwd);
+  const matchFunctions = config.matchFunctions ?? ["t", "getTranslation"];
+  const matchAttributes = config.matchAttributes ?? ["i18nKey", "id"];
+  const { usedKeys } = detectUsedKeys(files, matchFunctions, matchAttributes);
+  log.info(
+    `Found ${pc5.green(usedKeys.size)} unique translation keys referenced in code.`
+  );
+  if (config.localesLayout === "namespaced") {
+    extractNamespaced(config, localesDirAbs, usedKeys);
+  } else {
+    extractFlat(config, localesDirAbs, usedKeys);
+  }
+}
+function extractFlat(config, localesDirAbs, usedKeys) {
+  const writePlans = [];
+  const suffixes = config.pluralSuffixes ?? [];
+  for (const lang of config.supportedLanguages) {
+    let langPath = findLocaleFile(localesDirAbs, lang);
+    let flatJson = {};
+    if (!langPath) {
+      langPath = path3.join(localesDirAbs, `${lang}.json`);
+    } else {
+      try {
+        const langJson = readLocaleFile(langPath);
+        flatJson = flattenObject(langJson);
+      } catch (error) {
+        throw new I18nSharpenError({
+          kind: "parse",
+          message: `Failed to parse locale file '${path3.basename(langPath)}': ${error.message}`,
+          path: langPath
+        });
+      }
+    }
+    const missingKeys = [];
+    for (const key of usedKeys) {
+      let exists = key in flatJson;
+      if (!exists) {
+        for (const suffix of suffixes) {
+          if (key + suffix in flatJson) {
+            exists = true;
+            break;
+          }
+        }
+      }
+      if (!exists) {
+        missingKeys.push(key);
+      }
+    }
+    if (missingKeys.length > 0) {
+      missingKeys.sort();
+      for (const key of missingKeys) {
+        flatJson[key] = key;
+      }
+      const nestedJson = unflattenObject(flatJson);
+      writePlans.push({ lang, langPath, nestedJson, missingKeys });
+    } else {
+      log.info(
+        `\u2728 No new keys to extract for ${pc5.cyan(path3.basename(langPath))}.`
+      );
+    }
+  }
+  let totalExtractedCount = 0;
+  for (const plan of writePlans) {
+    log.info(
+      `\u{1F4E5} Extracting ${pc5.green(plan.missingKeys.length)} new keys to ${pc5.cyan(path3.basename(plan.langPath))}:`
+    );
+    for (const key of plan.missingKeys) {
+      log.info(`  + ${pc5.green(key)}`);
+    }
+    try {
+      writeLocaleFile(plan.langPath, plan.nestedJson);
+      totalExtractedCount += plan.missingKeys.length;
+    } catch (error) {
+      throw new I18nSharpenError({
+        kind: "filesystem",
+        message: `Failed to write to file '${plan.langPath}': ${error.message}`,
+        path: plan.langPath,
+        cause: error
+      });
+    }
+  }
+  if (totalExtractedCount > 0) {
+    log.success("Locale files updated successfully!\n");
+  } else {
+    log.success(
+      "All used translation keys are already present in locale files.\n"
+    );
+  }
+}
+function extractNamespaced(config, localesDirAbs, usedKeys) {
+  const suffixes = config.pluralSuffixes ?? [];
+  const { localesFlat, localeNamespaces } = loadNamespacedLocales(
+    localesDirAbs,
+    config.supportedLanguages
+  );
+  const writePlans = [];
+  for (const lang of config.supportedLanguages) {
+    const existingFlat = localesFlat[lang] ?? {};
+    const nsFilePaths = localeNamespaces[lang] ?? {};
+    const missingByNs = /* @__PURE__ */ new Map();
+    for (const fullKey of usedKeys) {
+      const colonIdx = fullKey.indexOf(":");
+      const ns = colonIdx >= 0 ? fullKey.slice(0, colonIdx) : "default";
+      const keyPath = colonIdx >= 0 ? fullKey.slice(colonIdx + 1) : fullKey;
+      const namespacedKey = `${ns}:${keyPath}`;
+      let exists = namespacedKey in existingFlat;
+      if (!exists) {
+        for (const suffix of suffixes) {
+          if (`${ns}:${keyPath}${suffix}` in existingFlat) {
+            exists = true;
+            break;
+          }
+        }
+      }
+      if (!exists) {
+        let arr = missingByNs.get(ns);
+        if (!arr) {
+          arr = [];
+          missingByNs.set(ns, arr);
+        }
+        arr.push(keyPath);
+      }
+    }
+    for (const [ns, missingKeys] of missingByNs) {
+      missingKeys.sort();
+      const langDir = path3.join(localesDirAbs, lang);
+      const filePath = nsFilePaths[ns] ?? path3.join(langDir, `${ns}.json`);
+      writePlans.push({ lang, ns, filePath, missingKeys });
+    }
+    if (missingByNs.size === 0) {
+      log.info(`\u2728 No new keys to extract for ${pc5.cyan(lang)} (namespaced).`);
+    }
+  }
+  const writeItems = [];
+  for (const plan of writePlans) {
+    const langDir = path3.dirname(plan.filePath);
+    let existingFlat = {};
+    if (fs8.existsSync(plan.filePath)) {
+      try {
+        existingFlat = flattenObject(readLocaleFile(plan.filePath));
+      } catch (error) {
+        throw new I18nSharpenError({
+          kind: "parse",
+          message: `Failed to parse namespace file '${plan.filePath}': ${error.message}`,
+          path: plan.filePath
+        });
+      }
+    } else {
+      fs8.mkdirSync(langDir, { recursive: true });
+    }
+    for (const keyPath of plan.missingKeys) {
+      existingFlat[keyPath] = keyPath;
+    }
+    const nestedJson = unflattenObject(existingFlat);
+    const displayLabel = `${plan.lang}/${plan.ns}.json`;
+    writeItems.push({
+      filePath: plan.filePath,
+      nestedJson,
+      missingKeys: plan.missingKeys,
+      displayLabel
+    });
+  }
+  let totalExtractedCount = 0;
+  for (const item of writeItems) {
+    log.info(
+      `\u{1F4E5} Extracting ${pc5.green(item.missingKeys.length)} new keys to ${pc5.cyan(item.displayLabel)}:`
+    );
+    for (const key of item.missingKeys) {
+      log.info(`  + ${pc5.green(key)}`);
+    }
+    try {
+      writeLocaleFile(item.filePath, item.nestedJson);
+      totalExtractedCount += item.missingKeys.length;
+    } catch (error) {
+      throw new I18nSharpenError({
+        kind: "filesystem",
+        message: `Failed to write to file '${item.filePath}': ${error.message}`,
+        path: item.filePath,
+        cause: error
+      });
+    }
+  }
+  if (totalExtractedCount > 0) {
+    log.success("Locale files updated successfully!\n");
+  } else {
+    log.success(
+      "All used translation keys are already present in locale files.\n"
+    );
+  }
+}
+function executePrunePlans(writePlans, perLocale, dryRun) {
+  let totalPrunedCount = 0;
+  let written = false;
+  if (dryRun) {
+    log.header(
+      writePlans.length === 0 ? "PRUNE PREVIEW (no changes)" : "PRUNE PREVIEW (dry-run \u2014 no files written)"
+    );
+  }
+  for (const plan of writePlans) {
+    const displayName = plan.displayName ?? path3.basename(plan.langPath);
+    const verb = dryRun ? "Would prune" : "Pruning";
+    log.info(
+      `${verb} ${pc5.yellow(plan.prunedKeys.length)} unused keys from ${pc5.cyan(displayName)}`
+    );
+    const sample = plan.prunedKeys.slice(0, 10);
+    for (const k of sample) {
+      log.info(`  - ${pc5.yellow(k)}`);
+    }
+    if (plan.prunedKeys.length > sample.length) {
+      log.info(
+        `  ... and ${plan.prunedKeys.length - sample.length} more (run with verbose flag to see all)`
+      );
+    }
+    if (!dryRun) {
+      try {
+        writeLocaleFile(plan.langPath, plan.nestedJson);
+        totalPrunedCount += plan.prunedKeys.length;
+        written = true;
+      } catch (error) {
+        throw new I18nSharpenError({
+          kind: "filesystem",
+          message: `Failed to write to file '${plan.langPath}': ${error.message}`,
+          path: plan.langPath,
+          cause: error
+        });
+      }
+    } else {
+      totalPrunedCount += plan.prunedKeys.length;
+    }
+  }
+  if (dryRun) {
+    if (totalPrunedCount > 0) {
+      log.warn(
+        `Dry-run: ${totalPrunedCount} key${totalPrunedCount === 1 ? "" : "s"} would be removed. Re-run with --force (or set prune.force: true in config) to apply.
+`
+      );
+    } else {
+      log.success("Dry-run: no unused keys found to prune.\n");
+    }
+  } else if (totalPrunedCount > 0) {
+    log.success(
+      `Files have been successfully cleaned! Total pruned: ${totalPrunedCount} keys.
+`
+    );
+  } else {
+    log.success("No unused keys found to prune.\n");
+  }
+  return { written, dryRun, perLocale, totalPruned: totalPrunedCount };
+}
+function pruneFlat(config, localesDirAbs, usedKeys, fileContents, dryRun) {
+  const allLocaleKeys = /* @__PURE__ */ new Set();
+  const localesFlat = {};
+  const localeFilePaths = {};
+  for (const lang of config.supportedLanguages) {
+    const langPath = findLocaleFile(localesDirAbs, lang);
+    if (langPath) {
+      localeFilePaths[lang] = langPath;
+      try {
+        const parsed = readLocaleFile(langPath);
+        localesFlat[lang] = flattenObject(parsed);
+        Object.keys(localesFlat[lang]).forEach((key) => allLocaleKeys.add(key));
+      } catch (error) {
+        throw new I18nSharpenError({
+          kind: "parse",
+          message: `Failed to parse locale file '${path3.basename(langPath)}': ${error.message}`,
+          path: langPath
+        });
+      }
+    }
+  }
+  if (config.looseKeyMatch) {
+    for (const key of allLocaleKeys) {
+      if (usedKeys.has(key)) continue;
+      const dq = `"${key}"`, sq = `'${key}'`, bq = `\`${key}\``;
+      for (const cleanContent of fileContents) {
+        if (cleanContent.includes(dq) || cleanContent.includes(sq) || cleanContent.includes(bq)) {
+          usedKeys.add(key);
+          break;
+        }
+      }
+    }
+  }
+  const suffixes = config.pluralSuffixes ?? [];
+  const isUsed = (key) => isKeyUsed(key, usedKeys, config.ignoreKeys, suffixes);
+  const writePlans = [];
+  const perLocale = [];
+  for (const lang of config.supportedLanguages) {
+    const langPath = localeFilePaths[lang];
+    if (!langPath) continue;
+    const flatJson = localesFlat[lang];
+    const newFlatJson = {};
+    const prunedKeys = [];
+    for (const key in flatJson) {
+      if (isUsed(key)) {
+        newFlatJson[key] = flatJson[key];
+      } else {
+        prunedKeys.push(key);
+      }
+    }
+    if (prunedKeys.length > 0) {
+      const nestedJson = unflattenObject(newFlatJson);
+      writePlans.push({ lang, langPath, nestedJson, prunedKeys });
+    } else {
+      log.info(
+        `\u2728 No unused keys to prune in ${pc5.cyan(path3.basename(langPath))}.`
+      );
+    }
+    perLocale.push({ lang, file: langPath, prunedKeys });
+  }
+  return executePrunePlans(writePlans, perLocale, dryRun);
+}
+function pruneNamespaced(config, localesDirAbs, usedKeys, fileContents, dryRun) {
+  const suffixes = config.pluralSuffixes ?? [];
+  const { localesFlat, localeNamespaces } = loadNamespacedLocales(
+    localesDirAbs,
+    config.supportedLanguages
+  );
+  const allLocaleKeys = /* @__PURE__ */ new Set();
+  for (const lang of config.supportedLanguages) {
+    for (const key of Object.keys(localesFlat[lang] ?? {})) {
+      allLocaleKeys.add(key);
+    }
+  }
+  if (config.looseKeyMatch) {
+    for (const key of allLocaleKeys) {
+      if (usedKeys.has(key)) continue;
+      const dq = `"${key}"`, sq = `'${key}'`, bq = `\`${key}\``;
+      for (const cleanContent of fileContents) {
+        if (cleanContent.includes(dq) || cleanContent.includes(sq) || cleanContent.includes(bq)) {
+          usedKeys.add(key);
+          break;
+        }
+      }
+    }
+  }
+  const isUsed = (namespacedKey) => isKeyUsed(namespacedKey, usedKeys, config.ignoreKeys, suffixes);
+  const writePlans = [];
+  const perLocale = [];
+  for (const lang of config.supportedLanguages) {
+    const nsFilePaths = localeNamespaces[lang] ?? {};
+    const langFlat = localesFlat[lang] ?? {};
+    const keysByNs = /* @__PURE__ */ new Map();
+    for (const [namespacedKey, value] of Object.entries(langFlat)) {
+      const colonIdx = namespacedKey.indexOf(":");
+      const ns = colonIdx >= 0 ? namespacedKey.slice(0, colonIdx) : "default";
+      const keyPath = colonIdx >= 0 ? namespacedKey.slice(colonIdx + 1) : namespacedKey;
+      let nsObj = keysByNs.get(ns);
+      if (!nsObj) {
+        nsObj = {};
+        keysByNs.set(ns, nsObj);
+      }
+      nsObj[keyPath] = value;
+    }
+    for (const [ns, nsFlatKeys] of keysByNs) {
+      const filePath = nsFilePaths[ns];
+      if (!filePath) continue;
+      const newFlatJson = {};
+      const prunedKeys = [];
+      for (const keyPath of Object.keys(nsFlatKeys)) {
+        const namespacedKey = `${ns}:${keyPath}`;
+        if (isUsed(namespacedKey)) {
+          newFlatJson[keyPath] = nsFlatKeys[keyPath];
+        } else {
+          prunedKeys.push(keyPath);
+        }
+      }
+      if (prunedKeys.length > 0) {
+        const nestedJson = unflattenObject(newFlatJson);
+        writePlans.push({ lang, ns, filePath, nestedJson, prunedKeys });
+      } else {
+        log.info(
+          `\u2728 No unused keys to prune in ${pc5.cyan(`${lang}/${ns}.json`)}.`
+        );
+      }
+      perLocale.push({ lang, file: filePath, prunedKeys });
+    }
+    if (keysByNs.size === 0) {
+      log.info(`\u2728 No locale files found for ${pc5.cyan(lang)}.`);
+    }
+  }
+  const flatPlans = writePlans.map((p) => ({
+    lang: p.lang,
+    langPath: p.filePath,
+    nestedJson: p.nestedJson,
+    prunedKeys: p.prunedKeys,
+    displayName: `${p.lang}/${p.ns}.json`
+  }));
+  return executePrunePlans(flatPlans, perLocale, dryRun);
+}
+
+// src/commands/prune.ts
+function prune(config, cwd = process.cwd(), options = {}) {
+  log.header("I18N-SHARPEN PRUNER");
+  const configForce = config.prune?.force === true;
+  const optForce = options.force === true;
+  const optDryRun = options.dryRun === true;
+  const dryRun = optDryRun ? true : !(optForce || configForce);
+  const localesDirAbs = path3.resolve(cwd, config.localesDir);
+  if (!fs8.existsSync(localesDirAbs)) {
+    throw new I18nSharpenError({
+      kind: "filesystem",
+      message: `Locales directory not found: ${localesDirAbs}`,
+      path: localesDirAbs
+    });
+  }
+  const files = scanSourceFiles(config, cwd);
+  const matchFunctions = config.matchFunctions ?? ["t", "getTranslation"];
+  const matchAttributes = config.matchAttributes ?? ["i18nKey", "id"];
+  const { usedKeys, fileContents } = detectUsedKeys(
+    files,
+    matchFunctions,
+    matchAttributes
+  );
+  log.info(
+    `Found ${pc5.green(usedKeys.size)} unique translation keys referenced in code.`
+  );
+  if (config.localesLayout === "namespaced") {
+    return pruneNamespaced(
+      config,
+      localesDirAbs,
+      usedKeys,
+      fileContents,
+      dryRun
+    );
+  }
+  return pruneFlat(config, localesDirAbs, usedKeys, fileContents, dryRun);
+}
+
+// src/commands/validate/checks.ts
+function findMissingKeys(usedKeys, defaultKeySet, config) {
+  const suffixes = config.pluralSuffixes ?? [];
+  const missing = [];
+  for (const key of usedKeys) {
+    let exists = defaultKeySet.has(key);
+    if (!exists) {
+      for (const suffix of suffixes) {
+        if (defaultKeySet.has(key + suffix)) {
+          exists = true;
+          break;
+        }
+      }
+    }
+    if (!exists) {
+      missing.push(key);
+    }
+  }
+  return missing;
+}
+function findUnusedKeys(defaultKeys, usedKeys, config) {
+  const suffixes = config.pluralSuffixes ?? [];
+  const unused = [];
+  for (const key of defaultKeys) {
+    if (!isKeyUsed(key, usedKeys, config.ignoreKeys, suffixes)) {
+      unused.push(key);
+    }
+  }
+  return unused;
+}
+function findAlignmentMismatches(config, defaultKeys, defaultKeySet, localesFlat, localeKeySets) {
+  const mismatches = [];
+  for (const lang of config.supportedLanguages) {
+    if (lang === config.defaultLanguage) continue;
+    const langKeySet = localeKeySets[lang];
+    const onlyInDefault = defaultKeys.filter((key) => !langKeySet.has(key));
+    const onlyInTarget = Object.keys(localesFlat[lang]).filter(
+      (key) => !defaultKeySet.has(key)
+    );
+    if (onlyInDefault.length > 0) {
+      mismatches.push({
+        from: config.defaultLanguage,
+        to: lang,
+        keys: onlyInDefault
+      });
+    }
+    if (onlyInTarget.length > 0) {
+      mismatches.push({
+        from: lang,
+        to: config.defaultLanguage,
+        keys: onlyInTarget
+      });
+    }
+  }
+  return mismatches;
+}
+function findPlaceholderKeys(config, usedKeys, localesFlat) {
+  const suffixes = config.pluralSuffixes ?? [];
+  const activePlaceholderKeys = [];
+  const unusedPlaceholderKeys = [];
+  for (const lang of config.supportedLanguages) {
+    const flatMap = localesFlat[lang];
+    for (const key in flatMap) {
+      if (flatMap[key] === key) {
+        if (isKeyUsed(key, usedKeys, config.ignoreKeys, suffixes)) {
+          activePlaceholderKeys.push({ key, lang });
+        } else {
+          unusedPlaceholderKeys.push({ key, lang });
+        }
+      }
+    }
+  }
+  return { activePlaceholderKeys, unusedPlaceholderKeys };
+}
+function printValidationResults(results, keyToFilesMap, pluralSuffixes) {
+  const {
+    missingKeys,
+    activePlaceholderKeys,
+    unusedKeys,
+    unusedPlaceholderKeys,
+    keysOnlyInLanguages
+  } = results;
+  const getBK = (key) => getBaseKey(key, pluralSuffixes);
+  log.header("VALIDATION RESULTS");
+  if (missingKeys.length > 0) {
+    log.info(pc5.bold(pc5.red(`\u274C Missing Keys (${missingKeys.length}):`)));
+    missingKeys.sort().forEach((key) => {
+      const files = keyToFilesMap.get(key) ?? [];
+      log.info(`  - ${pc5.red(key)} (referenced in: ${files.join(", ")})`);
+    });
+  } else {
+    log.success("Zero missing keys detected in the source code!");
+  }
+  if (activePlaceholderKeys.length > 0) {
+    log.info(
+      `
+${pc5.bold(pc5.red(`\u274C Active Placeholder/Untranslated Keys Used in Code (${activePlaceholderKeys.length}):`))}`
+    );
+    activePlaceholderKeys.sort((a, b) => a.key.localeCompare(b.key)).forEach(({ key, lang }) => {
+      const direct = keyToFilesMap.get(key);
+      const baseKey = getBK(key);
+      const baseFiles = baseKey !== key ? keyToFilesMap.get(baseKey) : void 0;
+      const files = direct ?? baseFiles ?? [];
+      log.info(
+        `  - [${lang.toUpperCase()}] ${pc5.red(key)} ${files.length > 0 ? `(referenced in: ${files.join(", ")})` : ""}`
+      );
+    });
+  } else {
+    log.success("Zero active placeholder keys detected in the source code!");
+  }
+  if (keysOnlyInLanguages.length > 0) {
+    log.info(`
+${pc5.bold(pc5.red("\u274C Locale Alignment Mismatches:"))}`);
+    for (const mismatch of keysOnlyInLanguages) {
+      log.info(
+        `  ${pc5.yellow(`Keys present in ${mismatch.from} but missing in ${mismatch.to} (${mismatch.keys.length}):`)}`
+      );
+      mismatch.keys.slice().sort().forEach((k) => {
+        log.info(`    - ${k}`);
+      });
+    }
+  } else {
+    log.success("Perfect key alignment across all locale files!");
+  }
+  if (unusedKeys.length > 0) {
+    log.info(
+      `
+${pc5.bold(pc5.yellow(`\u26A0\uFE0F  Unused Keys in locales (${unusedKeys.length}):`))}`
+    );
+    unusedKeys.sort().forEach((key) => {
+      log.info(`  - ${pc5.yellow(key)}`);
+    });
+  } else {
+    log.success(
+      "Zero unused keys detected! All defined keys are referenced in code."
+    );
+  }
+  if (unusedPlaceholderKeys.length > 0) {
+    log.info(
+      `
+${pc5.bold(pc5.yellow(`\u26A0\uFE0F  Unused Placeholder Keys in locales (${unusedPlaceholderKeys.length}):`))}`
+    );
+    unusedPlaceholderKeys.sort((a, b) => a.key.localeCompare(b.key)).forEach(({ key, lang }) => {
+      log.info(`  - [${lang.toUpperCase()}] ${pc5.yellow(key)}`);
+    });
+  }
+  log.header("QUALITY METRICS SUMMARY");
+  log.info(
+    `- Translation Key Coverage (Code -> Locales): ${pc5.bold(results.codeKeyCoverage === "100.00" ? pc5.green(results.codeKeyCoverage + "%") : pc5.red(results.codeKeyCoverage + "%"))}`
+  );
+  log.info(
+    `- Translation Key Utilization (Locales -> Code): ${pc5.bold(pc5.magenta(results.utilizationPercent + "%"))}`
+  );
+  log.info(`- Total Defined Keys: ${pc5.bold(results.totalDefinedKeys)}`);
+  log.info(`- Actually Used in Code: ${pc5.bold(results.usedDefinedKeysCount)}`);
+  log.info(`- Missing/Undefined: ${pc5.bold(missingKeys.length)}`);
+  log.info(`- Unused/Stale: ${pc5.bold(unusedKeys.length)}`);
+}
+function writeMarkdownReport(args) {
+  const reportPath = path3.resolve(args.cwd, args.outputReport);
+  const markdownContent = renderMarkdownReport(args);
+  fs8.mkdirSync(path3.dirname(reportPath), { recursive: true });
+  fs8.writeFileSync(reportPath, markdownContent, "utf8");
+  log.info(
+    `\u{1F4BE} Markdown report saved to: ${pc5.cyan(normalizeDisplayPath(path3.relative(args.cwd, reportPath)))}
+`
+  );
+  return reportPath;
+}
+function renderMarkdownReport(args) {
+  const {
+    missingKeys,
+    activePlaceholderKeys,
+    unusedKeys,
+    unusedPlaceholderKeys,
+    keysOnlyInLanguages,
+    codeKeyCoverage,
+    utilizationPercent,
+    totalDefinedKeys,
+    usedDefinedKeysCount
+  } = args.results;
+  const { keyToFilesMap, getBaseKey: getBaseKey2, defaultBasename } = args;
+  return `# i18n Quality and Coverage Report
+
+Generated on: ${(/* @__PURE__ */ new Date()).toISOString()}
+
+## Quality Metrics Summary
+
+| Metric | Value | Status |
+| :--- | :--- | :--- |
+| **Code Translation Coverage** | ${codeKeyCoverage}% | ${codeKeyCoverage === "100.00" ? "\u{1F7E2} 100% Perfect" : "\u{1F534} Missing Translations"} |
+| **Locales Key Utilization** | ${utilizationPercent}% | ${Number(utilizationPercent) > 90 ? "\u{1F7E2} High" : "\u{1F7E1} Medium"} |
+| **Total Defined Keys** | ${totalDefinedKeys} | - |
+| **Actually Used Keys** | ${usedDefinedKeysCount} | - |
+| **Missing Keys** | ${missingKeys.length} | ${missingKeys.length === 0 ? "\u{1F7E2} Clean" : "\u{1F534} Action Required"} |
+| **Active Placeholders** | ${activePlaceholderKeys.length} | ${activePlaceholderKeys.length === 0 ? "\u{1F7E2} Clean" : "\u{1F534} Action Required"} |
+| **Unused Keys** | ${unusedKeys.length} | ${unusedKeys.length === 0 ? "\u{1F7E2} Optimized" : "\u{1F7E1} Can be pruned"} |
+| **Locale Alignment** | ${keysOnlyInLanguages.length === 0 ? "Align'd" : "Mismatch"} | ${keysOnlyInLanguages.length === 0 ? "\u{1F7E2} Perfect" : "\u{1F534} Action Required"} |
+
+${renderMissingKeysSection(missingKeys, keyToFilesMap, defaultBasename)}
+
+${renderActivePlaceholdersSection(activePlaceholderKeys, keyToFilesMap, getBaseKey2)}
+
+${renderAlignmentSection(keysOnlyInLanguages)}
+
+${renderUnusedKeysSection(unusedKeys)}
+
+${renderUnusedPlaceholdersSection(unusedPlaceholderKeys)}
+`;
+}
+function renderMissingKeysSection(missingKeys, keyToFilesMap, defaultBasename) {
+  if (missingKeys.length === 0) {
+    return "## \u2705 Missing Keys\n\nNo missing translation keys detected in the source code.";
+  }
+  return `## \u274C Missing Keys (${missingKeys.length})
+
+The following keys are used in the source code but are not defined in the main locale file \`${defaultBasename}\`:
+
+${missingKeys.sort().map(
+    (key) => `- **\`${key}\`** (referenced in: ${keyToFilesMap.get(key)?.map((f) => `\`${f}\``).join(", ")})`
+  ).join("\n")}
+`;
+}
+function renderActivePlaceholdersSection(activePlaceholderKeys, keyToFilesMap, getBaseKey2) {
+  if (activePlaceholderKeys.length === 0) {
+    return "## \u2705 Active Placeholders\n\nNo active placeholder keys detected in the source code.";
+  }
+  return `## \u274C Active Placeholders (${activePlaceholderKeys.length})
+
+The following keys are referenced in the source code but only have placeholder values (identical to the key path):
+
+${activePlaceholderKeys.sort((a, b) => a.key.localeCompare(b.key)).map(
+    ({ key, lang }) => `- **\`${key}\`** [\`${lang.toUpperCase()}\`] ${keyToFilesMap.has(key) ? `(referenced in: ${keyToFilesMap.get(key)?.map((f) => `\`${f}\``).join(", ")})` : keyToFilesMap.has(getBaseKey2(key)) ? `(referenced in: ${keyToFilesMap.get(getBaseKey2(key))?.map((f) => `\`${f}\``).join(", ")})` : ""}`
+  ).join("\n")}
+`;
+}
+function renderAlignmentSection(keysOnlyInLanguages) {
+  if (keysOnlyInLanguages.length === 0) {
+    return "## \u2705 Locale Alignment\n\nPerfect key alignment between all locale files.";
+  }
+  return `## \u274C Locale Alignment Mismatches
+
+${keysOnlyInLanguages.map(
+    (m) => `### Keys in ${m.from} but missing in ${m.to} (${m.keys.length})
+${m.keys.slice().sort().map((k) => `- \`${k}\``).join("\n")}
+`
+  ).join("\n")}
+`;
+}
+function renderUnusedKeysSection(unusedKeys) {
+  if (unusedKeys.length === 0) {
+    return "## \u2705 Unused Keys\n\nAll defined translation keys are used in the source code.";
+  }
+  return `## \u26A0\uFE0F Unused Keys (${unusedKeys.length})
+
+These keys are defined in the locale file but are not used anywhere in the source code. They can be safely pruned to reduce bundle size:
+
+${unusedKeys.sort().map((key) => `- \`${key}\``).join("\n")}
+`;
+}
+function renderUnusedPlaceholdersSection(unusedPlaceholderKeys) {
+  if (unusedPlaceholderKeys.length === 0) return "";
+  return `## \u26A0\uFE0F Unused Placeholders (${unusedPlaceholderKeys.length})
+
+These keys have placeholder values but are not currently used in the source code. They should be translated before use:
+
+${unusedPlaceholderKeys.sort((a, b) => a.key.localeCompare(b.key)).map(({ key, lang }) => `- \`${key}\` [\`${lang.toUpperCase()}\`]`).join("\n")}
+`;
+}
+
+// src/commands/validate.ts
+function validate(config, cwd = process.cwd()) {
+  log.header("I18N-SHARPEN VALIDATOR");
+  const localesDirAbs = path3.resolve(cwd, config.localesDir);
+  const { localesFlat, localeKeySets, localePaths } = loadAllLocales(
+    localesDirAbs,
+    config.supportedLanguages,
+    (lang) => {
+      log.warn(
+        `Locale file not found for language '${lang}' in: ${localesDirAbs}`
+      );
+    }
+  );
+  const defaultLocalePath = localePaths[config.defaultLanguage] ?? null;
+  if (!defaultLocalePath) {
+    throw new I18nSharpenError({
+      kind: "filesystem",
+      message: `Default language '${config.defaultLanguage}' locale file not found.`,
+      path: localesDirAbs
+    });
+  }
+  const defaultKeys = Object.keys(localesFlat[config.defaultLanguage]);
+  const defaultKeySet = localeKeySets[config.defaultLanguage];
+  log.info(
+    `Loaded default language '${config.defaultLanguage}' with ${pc5.green(defaultKeys.length)} keys.`
+  );
+  for (const lang of config.supportedLanguages) {
+    if (lang !== config.defaultLanguage) {
+      const keysCount = Object.keys(localesFlat[lang]).length;
+      log.info(`Loaded language '${lang}' with ${pc5.green(keysCount)} keys.`);
+    }
+  }
+  const files = scanSourceFiles(config, cwd);
+  for (const scanDir of config.scanDirs) {
+    const scanDirAbs = path3.resolve(cwd, scanDir);
+    if (fs8.existsSync(scanDirAbs)) {
+      log.info(
+        `Scanning directory: ${pc5.cyan(normalizeDisplayPath(path3.relative(cwd, scanDirAbs)))}`
+      );
+    } else {
+      log.warn(`Scan directory does not exist: ${scanDirAbs}`);
+    }
+  }
+  log.info(`Found ${pc5.green(files.length)} source files to check.`);
+  const matchFunctions = config.matchFunctions ?? ["t", "getTranslation"];
+  const matchAttributes = config.matchAttributes ?? ["i18nKey", "id"];
+  const { usedKeys, fileContents } = detectUsedKeys(
+    files,
+    matchFunctions,
+    matchAttributes
+  );
+  const keyToFilesSet = /* @__PURE__ */ new Map();
+  const keyToFilesMap = {
+    has(key) {
+      return keyToFilesSet.has(key);
+    },
+    get(key) {
+      const s = keyToFilesSet.get(key);
+      return s ? Array.from(s) : void 0;
+    },
+    add(key, file) {
+      let s = keyToFilesSet.get(key);
+      if (!s) {
+        s = /* @__PURE__ */ new Set();
+        keyToFilesSet.set(key, s);
+      }
+      s.add(file);
+    }
+  };
+  const keyRegex = buildKeyRegex(matchFunctions);
+  const attrRegex = buildAttrRegex(matchAttributes);
+  const dynamicCallRegex = buildDynamicCallRegex(matchFunctions);
+  for (let i = 0; i < files.length; i++) {
+    const file = files[i];
+    const cleanContent = fileContents[i];
+    const relativePath = normalizeDisplayPath(path3.relative(cwd, file));
+    for (const match of cleanContent.matchAll(keyRegex)) {
+      const key = match[2];
+      if (key.endsWith(".")) continue;
+      keyToFilesMap.add(key, relativePath);
+    }
+    for (const match of cleanContent.matchAll(attrRegex)) {
+      const key = match[2];
+      if (key.endsWith(".")) continue;
+      keyToFilesMap.add(key, relativePath);
+    }
+    for (const match of cleanContent.matchAll(dynamicCallRegex)) {
+      const arg = match[1].trim();
+      if (arg.length === 0) continue;
+      if (!isStaticStringLiteral(arg)) {
+        log.warn(
+          `Potential dynamic translation key reference in ${pc5.cyan(relativePath)}: ${pc5.yellow(match[0])}`
+        );
+      }
+    }
+  }
+  if (config.looseKeyMatch) {
+    for (const key of defaultKeys) {
+      if (usedKeys.has(key)) continue;
+      const dq = `"${key}"`;
+      const sq = `'${key}'`;
+      const bq = `\`${key}\``;
+      for (let i = 0; i < files.length; i++) {
+        const cleanContent = fileContents[i];
+        if (cleanContent.includes(dq) || cleanContent.includes(sq) || cleanContent.includes(bq)) {
+          usedKeys.add(key);
+          keyToFilesMap.add(
+            key,
+            normalizeDisplayPath(path3.relative(cwd, files[i]))
+          );
+        }
+      }
+    }
+  }
+  log.info(
+    `Found ${pc5.green(usedKeys.size)} unique translation keys used in source code.`
+  );
+  const suffixes = config.pluralSuffixes ?? [];
+  const missingKeys = findMissingKeys(usedKeys, defaultKeySet, config);
+  const unusedKeys = findUnusedKeys(defaultKeys, usedKeys, config);
+  const keysOnlyInLanguages = findAlignmentMismatches(
+    config,
+    defaultKeys,
+    defaultKeySet,
+    localesFlat,
+    localeKeySets
+  );
+  const { activePlaceholderKeys, unusedPlaceholderKeys } = findPlaceholderKeys(
+    config,
+    usedKeys,
+    localesFlat
+  );
+  const totalDefinedKeys = defaultKeys.length;
+  const usedDefinedKeysCount = defaultKeys.length - unusedKeys.length;
+  const utilizationPercent = totalDefinedKeys > 0 ? (usedDefinedKeysCount / totalDefinedKeys * 100).toFixed(2) : "0.00";
+  const codeKeyCoverage = usedKeys.size > 0 ? (usedDefinedKeysCount / usedKeys.size * 100).toFixed(2) : "100.00";
+  const results = {
+    missingKeys,
+    activePlaceholderKeys,
+    unusedKeys,
+    unusedPlaceholderKeys,
+    keysOnlyInLanguages,
+    codeKeyCoverage,
+    utilizationPercent,
+    totalDefinedKeys,
+    usedDefinedKeysCount
+  };
+  printValidationResults(results, keyToFilesMap, suffixes);
+  if (config.outputReport) {
+    writeMarkdownReport({
+      cwd,
+      outputReport: config.outputReport,
+      defaultBasename: path3.basename(defaultLocalePath),
+      results,
+      keyToFilesMap,
+      getBaseKey: (key) => getBaseKey(key, suffixes)
+    });
+  }
+  const hasError = missingKeys.length > 0 || activePlaceholderKeys.length > 0 || keysOnlyInLanguages.length > 0;
+  if (hasError) {
+    log.error(
+      "Validation failed. Please fix the missing keys, active placeholders, or locale mismatches."
+    );
+  } else {
+    log.success("i18n Quality Validation passed successfully!\n");
+  }
+  return results;
+}
+var DEFAULT_CONFIG = {
+  scanDirs: ["src"],
+  localesDir: "src/locales",
+  excludeDirs: [
+    "node_modules",
+    "dist",
+    ".git",
+    ".next",
+    "build",
+    "coverage",
+    ".agent",
+    ".claude"
+  ],
+  fileExtensions: [".ts", ".tsx", ".js", ".jsx", ".vue", ".svelte", ".astro"],
+  matchFunctions: ["t", "getTranslation"],
+  outputReport: "i18n-coverage.md",
+  defaultLanguage: "en",
+  supportedLanguages: ["en"],
+  matchAttributes: ["i18nKey", "id", "i18n", ":label", "v-t", "t:"],
+  ignoreKeys: [],
+  pluralSuffixes: [
+    "_zero",
+    "_one",
+    "_two",
+    "_few",
+    "_many",
+    "_other",
+    "_male",
+    "_female"
+  ],
+  localesLayout: "flat"
+};
+var identifierLikePattern = /^[A-Za-z_$][A-Za-z0-9_$.]*$/;
+var identifierLike = z.string().regex(
+  identifierLikePattern,
+  "must be an identifier-like token matching /^[A-Za-z_$][A-Za-z0-9_$.]*$/"
+);
+var attributeNamePattern = /^[:]?[A-Za-z_$][A-Za-z0-9_$.\-:]*$/;
+var attributeName = z.string().regex(
+  attributeNamePattern,
+  "must match /^[:]?[A-Za-z_$][A-Za-z0-9_$.\\-:]*$/ (HTML/Vue/Astro-style attribute)"
+);
+var languageCodePattern = /^[a-zA-Z0-9_-]+$/;
+var languageCode = z.string().regex(
+  languageCodePattern,
+  "must match /^[a-zA-Z0-9_-]+$/ (no path separators)"
+);
+var I18nSharpenConfigSchema = z.object({
+  scanDirs: z.array(z.string()).nonempty("scanDirs must contain at least one directory path"),
+  localesDir: z.string().nonempty("localesDir must be a non-empty string"),
+  defaultLanguage: languageCode,
+  supportedLanguages: z.array(languageCode).nonempty("supportedLanguages must contain at least one language"),
+  excludeDirs: z.array(z.string()).optional(),
+  fileExtensions: z.array(z.string()).optional(),
+  matchFunctions: z.array(identifierLike).optional(),
+  outputReport: z.string().optional(),
+  matchAttributes: z.array(attributeName).optional(),
+  ignoreKeys: z.array(z.string()).optional(),
+  pluralSuffixes: z.array(z.string()).optional(),
+  looseKeyMatch: z.boolean().optional(),
+  localesLayout: z.enum(["flat", "namespaced"]).optional(),
+  prune: z.object({
+    force: z.boolean().optional()
+  }).optional()
+});
+function loadConfig(cwd = process.cwd(), configPath) {
+  if (!fs8.existsSync(cwd)) {
+    throw new I18nSharpenError({
+      kind: "config",
+      message: `cwd does not exist: ${cwd}`,
+      path: cwd
+    });
+  }
+  if (!fs8.statSync(cwd).isDirectory()) {
+    throw new I18nSharpenError({
+      kind: "config",
+      message: `cwd is not a directory: ${cwd}`,
+      path: cwd
+    });
+  }
+  const configPathJson = path3.join(cwd, "i18n-sharpen.json");
+  const packageJsonPath = path3.join(cwd, "package.json");
+  let fileConfig = {};
+  if (configPath) {
+    const resolved = path3.isAbsolute(configPath) ? configPath : path3.resolve(cwd, configPath);
+    if (!fs8.existsSync(resolved)) {
+      throw new I18nSharpenError({
+        kind: "config",
+        message: `Config file not found: ${resolved}`,
+        path: resolved
+      });
+    }
+    if (!fs8.statSync(resolved).isFile()) {
+      throw new I18nSharpenError({
+        kind: "config",
+        message: `Config path is not a file: ${resolved}`,
+        path: resolved
+      });
+    }
+    try {
+      const content = fs8.readFileSync(resolved, "utf8");
+      fileConfig = JSON.parse(content);
+    } catch (error) {
+      throw new I18nSharpenError({
+        kind: "parse",
+        message: `Failed to parse config file '${resolved}': ${error.message}`,
+        path: resolved
+      });
+    }
+  } else if (fs8.existsSync(configPathJson)) {
+    try {
+      const content = fs8.readFileSync(configPathJson, "utf8");
+      fileConfig = JSON.parse(content);
+    } catch (error) {
+      console.warn(
+        `\u26A0\uFE0F Failed to parse i18n-sharpen.json: ${error.message}`
+      );
+    }
+  } else if (fs8.existsSync(packageJsonPath)) {
+    try {
+      const content = fs8.readFileSync(packageJsonPath, "utf8");
+      const pkg = JSON.parse(content);
+      if (pkg.i18nSharpen) {
+        fileConfig = pkg.i18nSharpen;
+      }
+    } catch (error) {
+      console.warn(
+        `\u26A0\uFE0F Failed to read package.json for i18nSharpen config: ${error.message}`
+      );
+    }
+  }
+  const rawConfig = {
+    scanDirs: fileConfig.scanDirs ?? DEFAULT_CONFIG.scanDirs,
+    localesDir: fileConfig.localesDir ?? DEFAULT_CONFIG.localesDir,
+    defaultLanguage: fileConfig.defaultLanguage ?? DEFAULT_CONFIG.defaultLanguage,
+    supportedLanguages: fileConfig.supportedLanguages ?? DEFAULT_CONFIG.supportedLanguages,
+    excludeDirs: fileConfig.excludeDirs ?? DEFAULT_CONFIG.excludeDirs,
+    fileExtensions: fileConfig.fileExtensions ?? DEFAULT_CONFIG.fileExtensions,
+    matchFunctions: fileConfig.matchFunctions ?? DEFAULT_CONFIG.matchFunctions,
+    outputReport: fileConfig.outputReport ?? DEFAULT_CONFIG.outputReport,
+    matchAttributes: fileConfig.matchAttributes ?? DEFAULT_CONFIG.matchAttributes,
+    ignoreKeys: fileConfig.ignoreKeys ?? DEFAULT_CONFIG.ignoreKeys,
+    pluralSuffixes: fileConfig.pluralSuffixes ?? DEFAULT_CONFIG.pluralSuffixes,
+    looseKeyMatch: fileConfig.looseKeyMatch ?? false,
+    localesLayout: fileConfig.localesLayout ?? DEFAULT_CONFIG.localesLayout,
+    prune: fileConfig.prune ?? { force: false }
+  };
+  const result = I18nSharpenConfigSchema.safeParse(rawConfig);
+  if (!result.success) {
+    const errors = result.error.issues.map((err) => `  - ${err.path.join(".")}: ${err.message}`).join("\n");
+    throw new I18nSharpenError({
+      kind: "config",
+      message: `Invalid configuration:
+${errors}`
+    });
+  }
+  const config = result.data;
+  const cwdResolved = path3.resolve(cwd);
+  const isInsideCwd = (p) => {
+    const rel = path3.relative(cwdResolved, path3.resolve(cwdResolved, p));
+    return !rel.startsWith("..") && !path3.isAbsolute(rel);
+  };
+  if (!isInsideCwd(config.localesDir)) {
+    console.warn(
+      `\u26A0\uFE0F localesDir '${config.localesDir}' resolves outside cwd ('${cwdResolved}').`
+    );
+  }
+  for (const dir of config.scanDirs) {
+    if (!isInsideCwd(dir)) {
+      console.warn(
+        `\u26A0\uFE0F scanDirs entry '${dir}' resolves outside cwd ('${cwdResolved}').`
+      );
+    }
+  }
+  if (config.outputReport && !isInsideCwd(config.outputReport)) {
+    console.warn(
+      `\u26A0\uFE0F outputReport '${config.outputReport}' resolves outside cwd ('${cwdResolved}').`
+    );
+  }
+  if (!config.supportedLanguages.includes(config.defaultLanguage)) {
+    config.supportedLanguages = Array.from(
+      /* @__PURE__ */ new Set([config.defaultLanguage, ...config.supportedLanguages])
+    );
+  }
+  return config;
+}
+
+// src/cli.ts
+function reportError(error) {
+  if (error instanceof I18nSharpenError) {
+    log.error(`[${error.error.kind}] ${error.message}`);
+  } else {
+    log.error(error.message);
+  }
+}
+function readVersion() {
+  try {
+    const here = path3.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+      path3.resolve(here, "..", "package.json"),
+      path3.resolve(here, "..", "..", "package.json")
+    ];
+    for (const c of candidates) {
+      if (fs8.existsSync(c)) {
+        const pkg = JSON.parse(fs8.readFileSync(c, "utf8"));
+        if (typeof pkg.version === "string") return pkg.version;
+      }
+    }
+  } catch {
+  }
+  return "0.0.0";
+}
+var program = new Command();
+program.name("i18n-sharpen").description(
+  "Type-safe, configuration-driven i18n validator, extractor, and pruner CLI tool."
+).version(readVersion()).option(
+  "-c, --config <path>",
+  "Path to configuration file (i18n-sharpen.json)"
+).option("-d, --cwd <path>", "Working directory", process.cwd());
+program.command("validate").description(
+  "Validate translation keys, active placeholders, and cross-locale alignment."
+).action(() => {
+  const opts = program.opts();
+  const cwd = typeof opts.cwd === "string" ? opts.cwd : void 0;
+  const configPath = typeof opts.config === "string" ? opts.config : void 0;
+  try {
+    const config = loadConfig(cwd, configPath);
+    const results = validate(config, cwd);
+    const hasErrors = results.missingKeys.length > 0 || results.activePlaceholderKeys.length > 0 || results.keysOnlyInLanguages.length > 0;
+    process.exitCode = hasErrors ? 1 : 0;
+  } catch (error) {
+    reportError(error);
+    process.exitCode = 1;
+  }
+});
+program.command("extract").description(
+  "Extract new translation keys referenced in code and inject them into JSON files."
+).action(() => {
+  const opts = program.opts();
+  const cwd = typeof opts.cwd === "string" ? opts.cwd : void 0;
+  const configPath = typeof opts.config === "string" ? opts.config : void 0;
+  try {
+    const config = loadConfig(cwd, configPath);
+    extract(config, cwd);
+    process.exitCode = 0;
+  } catch (error) {
+    reportError(error);
+    process.exitCode = 1;
+  }
+});
+program.command("prune").description(
+  "Prune unused translation keys from JSON files (dry-run by default; use --force to actually write)."
+).option(
+  "--dry-run",
+  "Preview only \u2014 never write. Default behavior; flag exists for explicit CI scripts.",
+  false
+).option("--force", "Actually write the pruned locale files to disk.", false).action((cmdOpts) => {
+  const opts = program.opts();
+  const cwd = typeof opts.cwd === "string" ? opts.cwd : void 0;
+  const configPath = typeof opts.config === "string" ? opts.config : void 0;
+  try {
+    const config = loadConfig(cwd, configPath);
+    prune(config, cwd, {
+      force: cmdOpts.force === true,
+      dryRun: cmdOpts.dryRun === true
+    });
+    process.exitCode = 0;
+  } catch (error) {
+    reportError(error);
+    process.exitCode = 1;
+  }
+});
+program.parse(process.argv);
+//# sourceMappingURL=cli.js.map
+//# sourceMappingURL=cli.js.map