i18ntk 4.0.0 → 4.2.0

package/main/i18ntk-usage.js

@@ -42,8 +42,10 @@ const SettingsManager = require('../settings/settings-manager');
 const settingsManager = new SettingsManager();
 const { getUnifiedConfig, parseCommonArgs, displayHelp, validateSourceDir, displayPaths } = require('../utils/config-helper');
 const I18nInitializer = require('./i18ntk-init');
-const JsonOutput = require('../utils/json-output');
-const SetupEnforcer = require('../utils/setup-enforcer');
+const JsonOutput = require('../utils/json-output');
+const SetupEnforcer = require('../utils/setup-enforcer');
+const { resolveUsageSourceDir } = require('../utils/usage-source');
+const { analyzeSourceForUsageInsights } = require('../utils/usage-insights');
 
 // Ensure setup is complete before running
 (async () => {
@@ -61,6 +63,10 @@ async function getConfig() {
   return await getUnifiedConfig('usage');
 }
 
+function toBool(v) {
+  return v === true || v === 'true' || v === '1';
+}
+
 class I18nUsageAnalyzer {
   constructor(config = {}) {
     this.config = config;
@@ -70,9 +76,14 @@ class I18nUsageAnalyzer {
     
     // Initialize class properties
     this.availableKeys = new Set();
-    this.usedKeys = new Set();
-    this.fileUsage = new Map();
-    this.translationFiles = new Map(); // Track all translation files
+    this.usedKeys = new Set();
+    this.fileUsage = new Map();
+    this.keyUsageLocations = new Map();
+    this.hardcodedTextCandidates = [];
+    this.namespaceRecommendations = [];
+    this.unresolvedDynamicReferences = [];
+    this.translationValueIndex = new Map();
+    this.translationFiles = new Map(); // Track all translation files
     this.translationStats = new Map(); // Track translation completeness
     this.extractor = getExtractor(config.extractor);
     this.placeholderKeys = new Set();
@@ -88,6 +99,7 @@ class I18nUsageAnalyzer {
     this.deadKeys = new Map();
     this.cleanupMode = false;
     this.dryRunDelete = false;
+    this._sourceCommentsSet = null;
     
     // Use global translation function
     this.rl = null;
@@ -383,10 +395,10 @@ class I18nUsageAnalyzer {
       console.log('🔍 Debug mode enabled');
     }
     
-    if (args.cleanup) {
+    if (toBool(args.cleanup)) {
       this.cleanupMode = true;
     }
-    if (args.dryRunDelete) {
+    if (toBool(args.dryRunDelete)) {
       this.dryRunDelete = true;
     }
     
@@ -488,30 +500,25 @@ class I18nUsageAnalyzer {
         });
       }
       
-      // Ensure sourceDir points to source code, not locales
-      if (!args.sourceDir && this.config.sourceDir === this.config.i18nDir) {
-        // Default to common source directories if not explicitly provided
-        const possibleSourceDirs = ['src', 'lib', 'app', 'source'];
-        const projectRoot = this.config.projectRoot || '.';
-        
-        for (const dir of possibleSourceDirs) {
-          const testPath = path.resolve(projectRoot, dir);
-          if (SecurityUtils.safeExistsSync(testPath)) {
-            this.config.sourceDir = testPath;
-            this.sourceDir = testPath;
-            break;
-          }
-        }
-        
-        // If no common source directory found, use current directory
-        if (this.config.sourceDir === this.config.i18nDir) {
-          this.config.sourceDir = projectRoot;
-          this.sourceDir = projectRoot;
-        }
-      }
+      const usageSource = resolveUsageSourceDir({
+        sourceDir: this.sourceDir || this.config.sourceDir,
+        i18nDir: this.i18nDir || this.config.i18nDir,
+        projectRoot: this.config.projectRoot || process.cwd(),
+        explicitSourceDir: Boolean(args.sourceDir),
+      });
+      if (usageSource.reason) {
+        console.warn(t('usage.sourceEqualsI18nWarn', { reason: usageSource.reason }) || `Warning: ${usageSource.reason}`);
+      }
+      this.sourceDir = usageSource.sourceDir;
+      this.config.sourceDir = usageSource.sourceDir;
+      if (this.sourceDir) {
+        await configManager.updateConfig({
+          sourceDir: configManager.toRelative(this.sourceDir)
+        });
+      }
 
       // 🚧 prevent scanning locales as source
-      if (path.resolve(this.sourceDir) === path.resolve(this.i18nDir)) {
+      if (this.sourceDir && !args.sourceDir && path.resolve(this.sourceDir) === path.resolve(this.i18nDir)) {
         const fallback = path.resolve(this.config.projectRoot || '.', 'src');
         console.warn(t('usage.sourceEqualsI18nWarn') ||
           `⚠️ sourceDir equals i18nDir (${this.sourceDir}). Falling back to ${fallback} for source scanning.`);
@@ -527,15 +534,12 @@ class I18nUsageAnalyzer {
         });
       }
       
-      console.log(t('usage.detectedSourceDirectory', { sourceDir: this.sourceDir }));
+      console.log(t('usage.detectedSourceDirectory', { sourceDir: this.sourceDir || t('usage.noSourceDirectoryConfigured') || '(none)' }));
       console.log(t('usage.detectedI18nDirectory', { i18nDir: this.i18nDir }));
       
       // Load available translation keys first
       await this.loadAvailableKeys();
       
-      // NEW: Detect framework patterns before analysis
-      await this.detectFrameworkPatterns();
-      
       // Perform usage analysis with enhanced features
       await this.analyzeUsage();
       
@@ -614,6 +618,7 @@ class I18nUsageAnalyzer {
       }
       
       if (this.cleanupMode) {
+        this._buildSourceCommentsSet();
         const deadKeys = this.findDeadKeys();
         console.log('\n' + t('usage.deadKeysDetectionTitle'));
         console.log(t('usage.deadKeysCount', { count: deadKeys.length }));
@@ -703,7 +708,10 @@ Analysis Features (v1.10.1):
   • Framework-specific pattern recognition (React, Vue, Angular)
   • Advanced translation completeness scoring
   • Performance metrics and optimization tracking
-  • Key complexity analysis
+  • Key complexity analysis
+  • Known-key literal matching with source file locations
+  • Namespace/file naming recommendations (for example app/shop -> shop.json)
+  • Hardcoded user-facing text candidates with suggested translation keys
   • Security-enhanced path validation
   • Detailed reporting with validation errors
   • Dead key detection with confidence scoring
@@ -817,11 +825,17 @@ Analysis Features (v1.10.1):
         
         if (value && typeof value === 'object' && !Array.isArray(value)) {
           keys.push(...this.extractKeysFromObject(value, fullKey, namespace));
-        } else {
-          // Add dot notation key (e.g., "pagination.showing")
-          keys.push(fullKey);
-        }
-      }
+        } else {
+          // Add dot notation key (e.g., "pagination.showing")
+          keys.push(fullKey);
+          if (typeof value === 'string') {
+            const normalizedValue = value.replace(/\s+/g, ' ').trim();
+            if (normalizedValue && !this.translationValueIndex.has(normalizedValue)) {
+              this.translationValueIndex.set(normalizedValue, fullKey);
+            }
+          }
+        }
+      }
     } catch (error) {
       // Handle any unexpected errors during key extraction
       console.warn(`⚠️  Error during key extraction: ${error.message}`);
@@ -858,32 +872,85 @@ Analysis Features (v1.10.1):
     }
   }
 
-  // Extract translation keys from source code with enhanced patterns
-  extractKeysFromFile(filePath) {
-    try {
-      const content = SecurityUtils.safeReadFileSync(filePath, path.dirname(filePath), 'utf8');
-      if (!content) return [];
-      
-      // Skip JSON files entirely to prevent scanning translation files
-      if (filePath.endsWith('.json')) return [];
-      const rawPatterns = Array.isArray(this.config.translationPatterns) ? this.config.translationPatterns : [];
-      if (rawPatterns.length === 0) return [];
-
-      return this.extractor.extract(content, rawPatterns);
-      
-      // Null-safe translation patterns handling
-    } catch (error) {
-      console.warn(`${t('usage.failedToExtractKeys')} ${filePath}: ${error.message}`);
-      return [];
-    }
-  }
+  // Extract translation keys from source code with enhanced patterns
+  extractKeysFromFile(filePath) {
+    try {
+      const content = SecurityUtils.safeReadFileSync(filePath, path.dirname(filePath), 'utf8');
+      if (!content) return [];
+      
+      return this.extractKeysFromContent(content, filePath);
+      
+      // Null-safe translation patterns handling
+    } catch (error) {
+      console.warn(`${t('usage.failedToExtractKeys')} ${filePath}: ${error.message}`);
+      return [];
+    }
+  }
+
+  extractKeysFromContent(content, filePath = '') {
+    if (!content) return [];
+    if (filePath && filePath.endsWith('.json')) return [];
+    const rawPatterns = Array.isArray(this.config.translationPatterns) ? this.config.translationPatterns : [];
+    if (rawPatterns.length === 0) return [];
+    return this.extractor.extract(content, rawPatterns);
+  }
+
+  recordUsageInsights(relativePath, insights) {
+    const keys = [];
+    const seen = new Set();
+
+    for (const ref of insights.keyReferences || []) {
+      if (!ref.key || seen.has(ref.key)) continue;
+      seen.add(ref.key);
+      keys.push(ref.key);
+      this.usedKeys.add(ref.key);
+
+      if (!this.keyUsageLocations.has(ref.key)) {
+        this.keyUsageLocations.set(ref.key, []);
+      }
+      this.keyUsageLocations.get(ref.key).push({
+        filePath: relativePath,
+        line: ref.line,
+        column: ref.column,
+        matchType: ref.matchType,
+      });
+    }
+
+    if (keys.length > 0) {
+      this.fileUsage.set(relativePath, keys);
+    }
+
+    if (insights.namespaceRecommendation) {
+      this.namespaceRecommendations.push({
+        filePath: relativePath,
+        ...insights.namespaceRecommendation,
+      });
+    }
+
+    if (Array.isArray(insights.hardcodedTexts) && insights.hardcodedTexts.length > 0) {
+      this.hardcodedTextCandidates.push(...insights.hardcodedTexts);
+    }
+
+    if (Array.isArray(insights.unresolvedDynamicReferences) && insights.unresolvedDynamicReferences.length > 0) {
+      this.unresolvedDynamicReferences.push(...insights.unresolvedDynamicReferences.map(ref => ({
+        filePath: relativePath,
+        ...ref,
+      })));
+    }
+
+    return keys.length;
+  }
 
   // Analyze usage in source files
-  async analyzeUsage() {
-    try {
-      console.log(t('usage.checkUsage.analyzing_source_files'));
-      
-      // Check if source directory exists
+  async analyzeUsage() {
+    try {
+      console.log(t('usage.checkUsage.analyzing_source_files'));
+      if (!this.sourceDir) {
+        console.warn(t('usage.noSourceFilesFound'));
+        return;
+      }
+      
+      // Check if source directory exists
       if (!SecurityUtils.safeExistsSync(this.sourceDir)) {
         throw new Error(this.t('usage.sourceDirectoryDoesNotExist', { dir: this.sourceDir }) || `Source directory not found: ${this.sourceDir}`);
       }
@@ -900,21 +967,25 @@ Analysis Features (v1.10.1):
       let totalKeysFound = 0;
       let processedFiles = 0;
       
-      for (const filePath of sourceFiles) {
-        try {
-          const keys = this.extractKeysFromFile(filePath);
-          
-          if (keys.length > 0) {
-            const relativePath = path.relative(this.sourceDir, filePath);
-            this.fileUsage.set(relativePath, keys);
-            
-            keys.forEach(key => {
-              this.usedKeys.add(key);
-              totalKeysFound++;
-            });
-          }
-          
-          processedFiles++;
+      for (const filePath of sourceFiles) {
+        try {
+          const content = SecurityUtils.safeReadFileSync(filePath, path.dirname(filePath), 'utf8');
+          if (!content) continue;
+
+          const relativePath = path.relative(this.sourceDir, filePath);
+          const directKeys = this.extractKeysFromContent(content, filePath);
+          const insights = analyzeSourceForUsageInsights({
+            content,
+            relativePath,
+            availableKeys: this.availableKeys,
+            directKeys,
+            translationValueIndex: this.translationValueIndex,
+          });
+
+          this.detectFrameworkPatterns(content, relativePath);
+          totalKeysFound += this.recordUsageInsights(relativePath, insights);
+          
+          processedFiles++;
           
           // Progress indicator for large numbers of files
           if (sourceFiles.length > 10 && processedFiles % Math.ceil(sourceFiles.length / 10) === 0) {
@@ -926,10 +997,22 @@ Analysis Features (v1.10.1):
         }
       }
       
-      console.log(t("usage.checkUsage.found_thisusedkeyssize_unique_", { usedKeysSize: this.usedKeys.size }));
-      console.log(t("usage.checkUsage.total_key_usages_totalkeysfoun", { totalKeysFound }));
-      
-    } catch (error) {
+      console.log(t("usage.checkUsage.found_thisusedkeyssize_unique_", { usedKeysSize: this.usedKeys.size }));
+      console.log(t("usage.checkUsage.total_key_usages_totalkeysfoun", { totalKeysFound }));
+      if (this.keyUsageLocations.size > 0) {
+        console.log(`🔎 Indexed ${this.keyUsageLocations.size} keys with source file locations`);
+      }
+      if (this.namespaceRecommendations.length > 0) {
+        console.log(`🧭 Namespace recommendations: ${this.namespaceRecommendations.length}`);
+      }
+      if (this.hardcodedTextCandidates.length > 0) {
+        console.log(`📝 Hardcoded text candidates: ${this.hardcodedTextCandidates.length}`);
+      }
+      if (this.unresolvedDynamicReferences.length > 0) {
+        console.log(`🧩 Unresolved dynamic key expressions: ${this.unresolvedDynamicReferences.length}`);
+      }
+      
+    } catch (error) {
      console.error(t('usage.failedToAnalyzeUsage', { error: error.message }));
       throw error;
     }
@@ -1242,11 +1325,13 @@ Analysis Features (v1.10.1):
     return false;
   }
 
-  _keyInSourceComments(key) {
+  _buildSourceCommentsSet() {
+    if (this._sourceCommentsSet !== null) return;
+    this._sourceCommentsSet = new Set();
+
     const commentPatterns = [
       /\/\/[^\n]*/g,
-      /\/\*[\s\S]*?\*\//g,
-      /\/\*\*[\s\S]*?\*\//g
+      /\/\*[\s\S]*?\*\//g
     ];
 
     try {
@@ -1262,13 +1347,22 @@ Analysis Features (v1.10.1):
           const comments = content.match(pattern);
           if (comments) {
             for (const comment of comments) {
-              if (comment.includes(key)) {
-                return true;
-              }
+              this._sourceCommentsSet.add(comment);
             }
           }
         }
       }
+    } catch (e) {
+      this._sourceCommentsSet = new Set();
+    }
+  }
+
+  _keyInSourceComments(key) {
+    try {
+      if (!this._sourceCommentsSet || this._sourceCommentsSet.size === 0) return false;
+      for (const comment of this._sourceCommentsSet) {
+        if (comment.includes(key)) return true;
+      }
     } catch (e) {
       // Silently fail - comment detection is best-effort
     }
@@ -1333,9 +1427,19 @@ Analysis Features (v1.10.1):
     return filepath;
   }
 
-  // Find files that use specific keys
-  findKeyUsage(searchKey) {
-    const usage = [];
+  // Find files that use specific keys
+  findKeyUsage(searchKey) {
+    if (this.keyUsageLocations && this.keyUsageLocations.has(searchKey)) {
+      return this.keyUsageLocations.get(searchKey).map(location => ({
+        filePath: location.filePath,
+        keys: [searchKey],
+        line: location.line,
+        column: location.column,
+        matchType: location.matchType,
+      }));
+    }
+
+    const usage = [];
     
     for (const [filePath, keys] of this.fileUsage) {
       const matchingKeys = keys.filter(key => {
@@ -1406,13 +1510,14 @@ Analysis Features (v1.10.1):
     // Translation completeness with advanced scoring
     report += `${t('summary.usageReportTranslationCompleteness')}\n`;
     report += `${'='.repeat(50)}\n`;
-    for (const [language, stats] of this.translationStats) {
-      const translations = this.translationsByLanguage[language] || {};
-      const score = this.calculateTranslationScore ? this.calculateTranslationScore(language, translations) : {
-        completeness: ((stats.translated / stats.total) * 100).toFixed(1),
-        quality: ((stats.translated / stats.total) * 100).toFixed(1),
-        placeholderAccuracy: 100
-      };
+    for (const [language, stats] of this.translationStats) {
+      const translations = this.translationsByLanguage ? this.translationsByLanguage[language] : null;
+      const completeness = stats.total > 0 ? ((stats.translated / stats.total) * 100).toFixed(1) : '0.0';
+      const score = translations && this.calculateTranslationScore ? this.calculateTranslationScore(language, translations) : {
+        completeness,
+        quality: completeness,
+        placeholderAccuracy: 100
+      };
       
       report += `${t('summary.usageReportLanguageCompleteness', { language: language.toUpperCase(), completeness: score.completeness, translated: stats.translated, total: stats.total })}\n`;
       report += `  Quality: ${score.quality}%\n`;
@@ -1433,9 +1538,9 @@ Analysis Features (v1.10.1):
     }
     report += `\n`;
     
-    // Key complexity analysis
-    if (this.keyComplexity && this.keyComplexity.size > 0) {
-      report += `🔍 Key Complexity Analysis:\n`;
+    // Key complexity analysis
+    if (this.keyComplexity && this.keyComplexity.size > 0) {
+      report += `🔍 Key Complexity Analysis:\n`;
       const complexityStats = { simple: 0, moderate: 0, complex: 0 };
       this.keyComplexity.forEach((data, key) => {
         complexityStats[data.level]++;
@@ -1443,10 +1548,81 @@ Analysis Features (v1.10.1):
       
       report += `  Simple keys: ${complexityStats.simple}\n`;
       report += `  Moderate keys: ${complexityStats.moderate}\n`;
-      report += `  Complex keys: ${complexityStats.complex}\n\n`;
-    }
-    
-    // Unused keys with complexity
+      report += `  Complex keys: ${complexityStats.complex}\n\n`;
+    }
+
+    const matchCounts = { direct: 0, literal: 0 };
+    for (const locations of this.keyUsageLocations.values()) {
+      for (const location of locations) {
+        matchCounts[location.matchType] = (matchCounts[location.matchType] || 0) + 1;
+      }
+    }
+
+    report += `🔎 Usage Match Index\n`;
+    report += `${'='.repeat(50)}\n`;
+    report += `Direct i18n calls: ${matchCounts.direct || 0}\n`;
+    report += `Known-key literal matches: ${matchCounts.literal || 0}\n`;
+    report += `Resolved dynamic expressions: ${(matchCounts['dynamic-template'] || 0) + (matchCounts['dynamic-variable'] || 0)}\n`;
+    report += `Unresolved dynamic expressions: ${this.unresolvedDynamicReferences.length}\n`;
+    report += `Indexed keys with file locations: ${this.keyUsageLocations.size}\n\n`;
+
+    const indexedKeys = Array.from(this.keyUsageLocations.entries()).slice(0, 100);
+    indexedKeys.forEach(([key, locations]) => {
+      report += `- ${key}\n`;
+      locations.slice(0, 5).forEach(location => {
+        const line = location.line ? `:${location.line}` : '';
+        report += `  - ${location.filePath}${line} (${location.matchType})\n`;
+      });
+      if (locations.length > 5) {
+        report += `  - ... ${locations.length - 5} more locations\n`;
+      }
+    });
+    if (this.keyUsageLocations.size > 100) {
+      report += `... ${this.keyUsageLocations.size - 100} more indexed keys\n`;
+    }
+    report += `\n`;
+
+    if (this.namespaceRecommendations.length > 0) {
+      report += `🧭 Namespace Recommendations\n`;
+      report += `${'='.repeat(50)}\n`;
+      this.namespaceRecommendations.slice(0, 30).forEach(item => {
+        report += `- ${item.filePath}: ${item.message}\n`;
+      });
+      if (this.namespaceRecommendations.length > 30) {
+        report += `... ${this.namespaceRecommendations.length - 30} more recommendations\n`;
+      }
+      report += `\n`;
+    }
+
+    if (this.unresolvedDynamicReferences.length > 0) {
+      report += `🧩 Unresolved Dynamic Key Expressions\n`;
+      report += `${'='.repeat(50)}\n`;
+      report += `These calls could not be resolved to exact keys without executing code. Review them manually or prefer bounded literal maps/arrays for analyzable dynamic keys.\n\n`;
+      this.unresolvedDynamicReferences.slice(0, 50).forEach(item => {
+        const prefix = item.prefix ? ` prefix: ${item.prefix}` : ' no static prefix';
+        report += `- ${item.filePath}:${item.line} ${item.expression} (${prefix})\n`;
+      });
+      if (this.unresolvedDynamicReferences.length > 50) {
+        report += `... ${this.unresolvedDynamicReferences.length - 50} more unresolved expressions\n`;
+      }
+      report += `\n`;
+    }
+
+    if (this.hardcodedTextCandidates.length > 0) {
+      report += `📝 Hardcoded Text Candidates\n`;
+      report += `${'='.repeat(50)}\n`;
+      report += `Inline user-facing text that may be moved into locale files.\n\n`;
+      this.hardcodedTextCandidates.slice(0, 50).forEach(item => {
+        const existing = item.existingKey ? ` existing key: ${item.existingKey}` : ` suggested key: ${item.suggestedKey}`;
+        report += `- ${item.filePath}:${item.line} "${item.text}" (${existing})\n`;
+      });
+      if (this.hardcodedTextCandidates.length > 50) {
+        report += `... ${this.hardcodedTextCandidates.length - 50} more candidates\n`;
+      }
+      report += `\n`;
+    }
+    
+    // Unused keys with complexity
     if (unusedKeys.length > 0) {
       report += `${t('summary.usageReportUnusedTranslationKeys')}\n`;
       report += `${'='.repeat(50)}\n`;
@@ -1936,9 +2112,6 @@ Analysis Features (v1.10.1):
       // Close readline interface to prevent hanging
       this.closeReadline();
       
-      // Return instead of force exit to allow proper cleanup
-      return;
-      
       return {
         success: true,
         stats: {
@@ -1947,15 +2120,22 @@ Analysis Features (v1.10.1):
           dynamicKeys: dynamicKeys.length,
           unusedKeys: unusedKeys.length,
           missingKeys: missingKeys.length,
-          filesScanned: this.fileUsage.size,
-          notTranslatedKeys: notTranslatedStats.total,
-          translationCompleteness: Object.fromEntries(this.translationStats)
-        },
-        unusedKeys,
-        missingKeys,
-        dynamicKeys,
-        notTranslatedStats
-      };
+          filesScanned: this.fileUsage.size,
+          notTranslatedKeys: notTranslatedStats.total,
+          indexedKeys: this.keyUsageLocations.size,
+          namespaceRecommendations: this.namespaceRecommendations.length,
+          hardcodedTextCandidates: this.hardcodedTextCandidates.length,
+          unresolvedDynamicReferences: this.unresolvedDynamicReferences.length,
+          translationCompleteness: Object.fromEntries(this.translationStats)
+        },
+        unusedKeys,
+        missingKeys,
+        dynamicKeys,
+        notTranslatedStats,
+        namespaceRecommendations: this.namespaceRecommendations,
+        hardcodedTextCandidates: this.hardcodedTextCandidates,
+        unresolvedDynamicReferences: this.unresolvedDynamicReferences
+      };
       
     } catch (error) {
       console.error(t("checkUsage.usage_analysis_failed"));
@@ -2013,40 +2193,4 @@ if (require.main === module) {
   }
 }
 
-module.exports = I18nUsageAnalyzer;
-
-// Run if called directly
-if (require.main === module) {
-  async function main() {
-    try {
-      const cliArgs = parseCommonArgs(process.argv.slice(2));
-
-      if (cliArgs.help) {
-        displayHelp('usage');
-        process.exit(0);
-      }
-
-      // Let run() handle full initialization to avoid duplicate setup output
-      const analyzer = new I18nUsageAnalyzer();
-      await analyzer.run();
-    } catch (error) {
-      console.error('Error:', error.message);
-      process.exit(1);
-    }
-  }
-
-  // Check if we're being called from the menu system (stdin has data)
-  const hasStdinData = !process.stdin.isTTY;
-
-  if (hasStdinData) {
-    // When called from menu, consume stdin data and run with defaults
-    process.stdin.resume();
-    process.stdin.on('data', () => {});
-    process.stdin.on('end', () => {
-      main();
-    });
-  } else {
-    // Normal direct execution
-    main();
-  }
-}
+module.exports = I18nUsageAnalyzer;