@kopynator/cli 1.5.1 → 1.6.1

package/src/commands/check.ts

@@ -1,43 +1,151 @@
 import chalk from 'chalk';
 import fs from 'fs';
 import path from 'path';
+import { detectFramework, getSourceRoot, getTranslationDir } from '../lib/project';
+import {
+  findGlobalDuplicates,
+  flatten,
+  gitShowFile,
+  isProtectedByPrefix,
+  loadBaseline,
+  loadSafelist,
+  saveBaseline,
+  scanUsedKeys,
+  walkSourceFiles,
+} from '../lib/i18n-guardian';
+
+export interface CheckOptions {
+  baseRef?: string;
+  updateBaseline?: boolean;
+  all?: boolean;
+}
+
+export async function checkCommand(opts: CheckOptions = {}) {
+  if (process.env.KOPYNATOR_I18N_SKIP === '1') {
+    console.log(chalk.yellow('⚠️  KOPYNATOR_I18N_SKIP=1 — skipping i18n check.'));
+    return;
+  }
 
-export async function checkCommand() {
   console.log(chalk.bold.blue('\n🔍 Validating JSON translation files...\n'));
 
-  const assetsDir = path.join(process.cwd(), 'src/assets/i18n'); // Default angular structural assumption for demo
+  const cwd = process.cwd();
+  const framework = detectFramework();
+  const assetsDir = getTranslationDir(framework);
 
   if (!fs.existsSync(assetsDir)) {
     console.log(chalk.red(`❌ Could not find directory: ${assetsDir}`));
     console.log(chalk.yellow('Make sure you are running this from your project root.'));
-    return;
+    process.exit(1);
   }
 
   const files = fs.readdirSync(assetsDir).filter(f => f.endsWith('.json'));
 
   if (files.length === 0) {
-    console.log(chalk.yellow('⚠️ No JSON files found in assets/i18n.'));
+    console.log(chalk.yellow('⚠️ No JSON files found in ' + assetsDir + '.'));
     return;
   }
 
-  let hasErrors = false;
+  let hasJsonErrors = false;
+  const parsed: Record<string, any> = {};
 
   files.forEach(file => {
     try {
       const content = fs.readFileSync(path.join(assetsDir, file), 'utf-8');
-      JSON.parse(content);
+      parsed[file] = JSON.parse(content);
       console.log(chalk.green(`✓ ${file} is valid JSON.`));
     } catch (e: any) {
-      hasErrors = true;
+      hasJsonErrors = true;
       console.log(chalk.red(`❌ ${file} has syntax errors:`));
       console.log(chalk.red(`   ${e.message}`));
     }
   });
 
-  if (hasErrors) {
+  if (hasJsonErrors) {
     console.log(chalk.red('\n💥 Validation failed. Please fix the errors above.'));
     process.exit(1);
-  } else {
-    console.log(chalk.bold.green('\n✨ All files are valid! You are ready to go.'));
   }
+
+  console.log(chalk.bold.blue('\n🛡️  Guarding against broken references and duplicate keys...\n'));
+
+  // Defined keys: union across every locale file (a key only needs to exist somewhere).
+  const definedKeys = new Set<string>();
+  for (const file of files) {
+    Object.keys(flatten(parsed[file])).forEach(k => definedKeys.add(k));
+  }
+
+  // Reference locale for value-based duplicate detection: prefer en.json, else first alphabetically.
+  const refFile = files.includes('en.json') ? 'en.json' : files.sort()[0];
+  const refValues = flatten(parsed[refFile]);
+
+  // Scan app source for key usage + inline `kopynator-keys: prefix.*` declarations.
+  const sourceRoot = getSourceRoot(framework);
+  const sourceFiles = walkSourceFiles(sourceRoot);
+  const { used, dynamicPrefixes: magicPrefixes } = scanUsedKeys(sourceFiles);
+
+  const safelist = loadSafelist(cwd);
+  const protectedPrefixes = new Set([...(safelist.dynamicPrefixes || []), ...magicPrefixes]);
+
+  // --- Broken references: used in code, not defined in any locale file ---
+  const missing = [...used.keys()]
+    .filter(k => !definedKeys.has(k))
+    .filter(k => !isProtectedByPrefix(k, protectedPrefixes));
+
+  const baseline = loadBaseline(cwd);
+  const baselineSet = new Set(baseline.keys);
+  const freshMissing = missing.filter(k => !baselineSet.has(k));
+  const staleBaseline = baseline.keys.filter(k => !missing.includes(k));
+
+  if (opts.updateBaseline) {
+    saveBaseline(cwd, missing);
+    console.log(chalk.green(`✅ Baseline updated: ${missing.length} accepted missing key(s) written to kopynator.i18n-baseline.json`));
+    return;
+  }
+
+  if (opts.all) {
+    console.log(chalk.bold(`\nAll missing keys (${missing.length}):`));
+    missing
+      .slice()
+      .sort()
+      .forEach(k => {
+        const tag = baselineSet.has(k) ? chalk.gray('[baseline]') : chalk.red('[NEW]');
+        console.log(`  ${tag} ${k} ${chalk.gray(`(used ${used.get(k)}x)`)}`);
+      });
+  }
+
+  // --- Duplicate-of-global values: only flag keys that are new since the base ref ---
+  const baseRef = opts.baseRef || 'master';
+  const oldRefContent = gitShowFile(cwd, baseRef, path.relative(cwd, path.join(assetsDir, refFile)));
+  const oldRefValues = oldRefContent ? flatten(JSON.parse(oldRefContent)) : {};
+  const duplicates = findGlobalDuplicates(refValues, new Set(used.keys())).filter(
+    d => oldRefValues[d.key] === undefined || oldRefValues[d.key] !== refValues[d.key]
+  );
+
+  let hasFailures = false;
+
+  if (freshMissing.length) {
+    hasFailures = true;
+    console.log(chalk.red(`\n❌ ${freshMissing.length} translation key(s) used in code but missing from ${assetsDir}:`));
+    freshMissing.sort().forEach(k => console.log(chalk.red(`   - ${k} ${chalk.gray(`(used ${used.get(k)}x)`)}`)));
+  }
+
+  if (duplicates.length) {
+    hasFailures = true;
+    console.log(chalk.red(`\n❌ ${duplicates.length} key(s) duplicate an existing global value:`));
+    duplicates.forEach(d =>
+      console.log(chalk.red(`   - "${d.key}" duplicates "${d.canonical}"${d.canonicalIsNew ? chalk.gray(' (not created yet — proposed)') : ''} → "${d.value}"`))
+    );
+  }
+
+  if (staleBaseline.length) {
+    console.log(
+      chalk.blue(`\nℹ️  i18n: ${staleBaseline.length} baseline key(s) no longer missing; regenerate: kopynator check --update-baseline`)
+    );
+  }
+
+  if (hasFailures) {
+    console.log(chalk.red('\n💥 i18n check failed. Fix the issues above, or run with --update-baseline to accept current debt.'));
+    process.exit(1);
+  }
+
+  console.log(chalk.bold.green(`\n✨ i18n check passed (${files.length} locale file(s); baseline=${baselineSet.size}; scanned ${sourceFiles.length} source file(s)).`));
 }

package/src/commands/limits.ts

@@ -72,7 +72,7 @@ export async function limitsCommand(): Promise<void> {
   const url = `${base}/tokens/limits?token=${encodeURIComponent(resolved.apiKey)}`;
 
   try {
-    const res = await fetch(url, { headers: { 'x-kopynator-version': '1.5.0' } });
+    const res = await fetch(url, { headers: { 'x-kopynator-version': '1.6.1' } });
     if (!res.ok) {
       const body = await res.text().catch(() => '');
       console.log(chalk.red(`\n✖ Could not fetch limits (HTTP ${res.status}). ${body}\n`));

package/src/commands/sync.ts

@@ -3,6 +3,7 @@ import fs from 'fs';
 import path from 'path';
 import inquirer from 'inquirer';
 import ora from 'ora';
+import { detectFramework, getTranslationDir } from '../lib/project';
 
 interface KopyConfig {
   apiKey: string;
@@ -16,54 +17,6 @@ interface SyncConfig {
   indent: '2' | '4' | 'tab';
 }
 
-/**
- * Detect the framework being used in the current project
- */
-function detectFramework(): 'Angular' | 'React' | 'Vue' | 'Other' {
-  const angularJson = path.join(process.cwd(), 'angular.json');
-  const packageJson = path.join(process.cwd(), 'package.json');
-
-  // Check for Angular
-  if (fs.existsSync(angularJson)) {
-    return 'Angular';
-  }
-
-  // Check package.json for React/Vue
-  if (fs.existsSync(packageJson)) {
-    try {
-      const pkg = JSON.parse(fs.readFileSync(packageJson, 'utf-8'));
-      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-      
-      if (deps['@angular/core']) return 'Angular';
-      if (deps['react']) return 'React';
-      if (deps['vue']) return 'Vue';
-    } catch (e) {
-      // Ignore parse errors
-    }
-  }
-
-  return 'Other';
-}
-
-/**
- * Get the translation directory path based on framework
- */
-function getTranslationDir(framework: string): string {
-  switch (framework) {
-    case 'Angular':
-      return path.join(process.cwd(), 'src/assets/i18n');
-    case 'React':
-      // Common React patterns, can be customized later
-      return path.join(process.cwd(), 'public/locales');
-    case 'Vue':
-      // Common Vue patterns, can be customized later
-      return path.join(process.cwd(), 'public/locales');
-    default:
-      // Default fallback
-      return path.join(process.cwd(), 'locales');
-  }
-}
-
 /**
  * API key del proyecto primero (no hace falta en el comando), luego env para CI.
  * Order: app.config.ts -> app.module.ts -> kopynator.config.json -> KOPYNATOR_API_KEY
@@ -212,7 +165,7 @@ export async function syncCommand() {
   // Get sync configuration
   const syncConfig = await getSyncConfig();
 
-  const baseUrl = config.baseUrl || 'https://api.kopynator.com/api/tokens';
+  const baseUrl = config.baseUrl || 'https://api.kopynator.com/tokens';
   const token = config.apiKey;
 
   const spinner = ora('📡 Connecting to Kopynator Cloud...').start();
@@ -223,7 +176,7 @@ export async function syncCommand() {
     const languagesUrl = `${baseUrl}/languages?token=${token}`;
     const languagesResponse = await fetch(languagesUrl, {
       headers: {
-        'x-kopynator-version': '1.4.1'
+        'x-kopynator-version': '1.6.1'
       }
     });
     if (!languagesResponse.ok) {
@@ -249,7 +202,7 @@ export async function syncCommand() {
       try {
         const translationResponse = await fetch(fetchUrl, {
           headers: {
-            'x-kopynator-version': '1.4.1'
+            'x-kopynator-version': '1.6.1'
           }
         });
 

package/src/commands/upload.ts

@@ -164,7 +164,7 @@ export async function uploadCommand(options: { file?: string; lang?: string }) {
         headers: {
           'Content-Type': 'application/json',
           'x-api-token': token,
-          'x-kopynator-version': '1.4.1',
+          'x-kopynator-version': '1.6.1',
         },
         body: JSON.stringify({ lang, data: batches[i] }),
       });

package/src/index.ts

@@ -8,7 +8,7 @@ const program = new Command();
 program
   .name('kopynator')
   .description('Kopynator CLI - Manage your i18n workflow')
-  .version('1.5.1', '-v, --version')
+  .version('1.6.1', '-v, --version')
   .helpOption('-h, --help', 'Display help for command')
   .addHelpText('beforeAll', chalk.blue('\n👋 Welcome to Kopynator CLI!\n'));
 
@@ -19,8 +19,11 @@ program
 
 program
   .command('check')
-  .description('Validate your local JSON translation files')
-  .action(checkCommand);
+  .description('Validate translation files: JSON syntax, broken references and duplicate global keys')
+  .option('--base-ref <ref>', 'Git ref to diff against when detecting new duplicate keys', 'master')
+  .option('--update-baseline', 'Accept all currently-missing keys as backlog (writes kopynator.i18n-baseline.json)')
+  .option('--all', 'List every missing key, including ones already accepted in the baseline')
+  .action((opts) => checkCommand({ baseRef: opts.baseRef, updateBaseline: opts.updateBaseline, all: opts.all }));
 
 program
   .command('sync')

package/src/lib/i18n-guardian.ts

@@ -0,0 +1,190 @@
+import fs from 'fs';
+import path from 'path';
+import { execFileSync } from 'child_process';
+
+export interface SafelistConfig {
+  dynamicPrefixes?: string[];
+}
+
+export interface BaselineConfig {
+  keys: string[];
+}
+
+export interface UsedKey {
+  key: string;
+  count: number;
+}
+
+export interface DuplicateFinding {
+  key: string;
+  value: string;
+  canonical: string;
+  canonicalIsNew: boolean;
+}
+
+const SAFELIST_FILE = 'kopynator.i18n-safelist.json';
+const BASELINE_FILE = 'kopynator.i18n-baseline.json';
+const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.html', '.vue'];
+const EXCLUDED_DIRS = new Set(['node_modules', 'dist', 'build', '.git', '.angular', 'coverage', '.next', '.nuxt', 'out']);
+
+const KEY = `[\\w.:-]+`;
+const USE_PATTERNS: { re: RegExp; group: number }[] = [
+  // {{ 'key' | kopy }} — Angular pipe
+  { re: new RegExp(`(['"\`])(${KEY})\\1\\s*\\|\\s*kopy`, 'g'), group: 2 },
+  // [kopy]="'key'" — Angular directive with a string literal binding
+  { re: new RegExp(`\\[kopy\\]\\s*=\\s*"'(${KEY})'"`, 'g'), group: 1 },
+  // .translate('key') / .t('key') — @kopynator/core & @kopynator/react API
+  { re: new RegExp(`\\.(?:translate|t)\\(\\s*(['"\`])(${KEY})\\1`, 'g'), group: 2 },
+];
+
+const MAGIC_RE = /kopynator-keys\s*:\s*([^\n]+)/g;
+
+/** Recursively flattens a nested translation object into dot-notation keys. */
+export function flatten(obj: Record<string, any>, prefix = ''): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(obj || {})) {
+    const key = prefix ? `${prefix}.${k}` : k;
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+      Object.assign(out, flatten(v, key));
+    } else {
+      out[key] = String(v);
+    }
+  }
+  return out;
+}
+
+export function walkSourceFiles(rootDir: string): string[] {
+  if (!fs.existsSync(rootDir)) return [];
+  const results: string[] = [];
+
+  function walk(dir: string) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (EXCLUDED_DIRS.has(entry.name)) continue;
+        walk(path.join(dir, entry.name));
+      } else if (SOURCE_EXTENSIONS.includes(path.extname(entry.name))) {
+        results.push(path.join(dir, entry.name));
+      }
+    }
+  }
+
+  walk(rootDir);
+  return results;
+}
+
+/** Scans source files for translation key usage and inline `kopynator-keys:` dynamic-prefix declarations. */
+export function scanUsedKeys(files: string[]): { used: Map<string, number>; dynamicPrefixes: Set<string> } {
+  const used = new Map<string, number>();
+  const dynamicPrefixes = new Set<string>();
+
+  for (const file of files) {
+    const content = fs.readFileSync(file, 'utf-8');
+
+    for (const { re, group } of USE_PATTERNS) {
+      re.lastIndex = 0;
+      let match: RegExpExecArray | null;
+      while ((match = re.exec(content))) {
+        const key = match[group];
+        used.set(key, (used.get(key) || 0) + 1);
+      }
+    }
+
+    MAGIC_RE.lastIndex = 0;
+    let magicMatch: RegExpExecArray | null;
+    while ((magicMatch = MAGIC_RE.exec(content))) {
+      for (const raw of magicMatch[1].split(',')) {
+        const prefix = raw.trim().replace(/\*$/, '');
+        if (prefix) dynamicPrefixes.add(prefix);
+      }
+    }
+  }
+
+  return { used, dynamicPrefixes };
+}
+
+export function loadSafelist(cwd: string): SafelistConfig {
+  const p = path.join(cwd, SAFELIST_FILE);
+  if (!fs.existsSync(p)) return { dynamicPrefixes: [] };
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf-8'));
+  } catch {
+    return { dynamicPrefixes: [] };
+  }
+}
+
+export function loadBaseline(cwd: string): BaselineConfig {
+  const p = path.join(cwd, BASELINE_FILE);
+  if (!fs.existsSync(p)) return { keys: [] };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    return { keys: Array.isArray(parsed.keys) ? parsed.keys : [] };
+  } catch {
+    return { keys: [] };
+  }
+}
+
+export function saveBaseline(cwd: string, keys: string[]): void {
+  const p = path.join(cwd, BASELINE_FILE);
+  fs.writeFileSync(p, JSON.stringify({ keys: keys.sort() }, null, 2) + '\n');
+}
+
+export function isProtectedByPrefix(key: string, prefixes: Set<string> | string[]): boolean {
+  for (const prefix of prefixes) {
+    if (key.startsWith(prefix)) return true;
+  }
+  return false;
+}
+
+/** Reads a file's content at a given git ref, or null if git/ref/file is unavailable. */
+export function gitShowFile(cwd: string, ref: string, relPath: string): string | null {
+  try {
+    return execFileSync('git', ['show', `${ref}:${relPath}`], { cwd, stdio: ['pipe', 'pipe', 'ignore'] }).toString('utf-8');
+  } catch {
+    return null;
+  }
+}
+
+export function slugify(value: string, maxLen = 40): string {
+  return String(value)
+    .replace(/<[^>]+>/g, '')
+    .replace(/\{\{[^}]+\}\}/g, '')
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, maxLen) || 'value';
+}
+
+/** Picks the canonical key among a group of keys sharing the same value: prefers a category-segmented `global.*` key, else the shortest `global.*`, else null (no existing canonical). */
+export function pickGlobal(keys: string[]): string | null {
+  const globals = keys.filter(k => k.startsWith('global.'));
+  if (!globals.length) return null;
+  const segmented = globals.filter(k => /^global\.(status|error|action)\./.test(k));
+  const pool = segmented.length ? segmented : globals;
+  return pool.reduce((shortest, k) => (k.length < shortest.length ? k : shortest), pool[0]);
+}
+
+/** Finds keys whose value duplicates an existing (or proposable) `global.*` canonical, restricted to keys actually used in source. */
+export function findGlobalDuplicates(values: Record<string, string>, usedKeys: Set<string>): DuplicateFinding[] {
+  const byValue = new Map<string, string[]>();
+  for (const [key, value] of Object.entries(values)) {
+    const trimmed = value.trim();
+    if (!trimmed) continue;
+    const group = byValue.get(trimmed) || [];
+    group.push(key);
+    byValue.set(trimmed, group);
+  }
+
+  const findings: DuplicateFinding[] = [];
+  for (const [value, keys] of byValue) {
+    if (keys.length < 2) continue;
+    const canonical = pickGlobal(keys) || `global.${slugify(value)}`;
+    for (const key of keys) {
+      if (key === canonical) continue;
+      if (!usedKeys.has(key)) continue;
+      findings.push({ key, value, canonical, canonicalIsNew: !keys.includes(canonical) });
+    }
+  }
+  return findings;
+}

package/src/lib/project.ts

@@ -0,0 +1,60 @@
+import fs from 'fs';
+import path from 'path';
+
+export type Framework = 'Angular' | 'React' | 'Vue' | 'Other';
+
+/**
+ * Detect the framework being used in the current project
+ */
+export function detectFramework(): Framework {
+  const angularJson = path.join(process.cwd(), 'angular.json');
+  const packageJson = path.join(process.cwd(), 'package.json');
+
+  if (fs.existsSync(angularJson)) {
+    return 'Angular';
+  }
+
+  if (fs.existsSync(packageJson)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(packageJson, 'utf-8'));
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+      if (deps['@angular/core']) return 'Angular';
+      if (deps['react']) return 'React';
+      if (deps['vue']) return 'Vue';
+    } catch (e) {
+      // Ignore parse errors
+    }
+  }
+
+  return 'Other';
+}
+
+/**
+ * Get the translation directory path based on framework
+ */
+export function getTranslationDir(framework: Framework): string {
+  switch (framework) {
+    case 'Angular':
+      return path.join(process.cwd(), 'src/assets/i18n');
+    case 'React':
+    case 'Vue':
+      return path.join(process.cwd(), 'public/locales');
+    default:
+      return path.join(process.cwd(), 'locales');
+  }
+}
+
+/**
+ * Get the app source root to scan for translation key usage.
+ */
+export function getSourceRoot(framework: Framework): string {
+  switch (framework) {
+    case 'Angular':
+    case 'React':
+    case 'Vue':
+      return path.join(process.cwd(), 'src');
+    default:
+      return process.cwd();
+  }
+}