react-i18next-scanner 0.1.3 → 0.1.4

package/dist/core/actions/writePossiblyDynamicallyUsedReport.js

@@ -0,0 +1,47 @@
+// src/core/actions/writePossiblyDynamicallyUsedReport.ts
+import fs from "fs/promises";
+import path from "path";
+import { addKey } from "../utils/addKey.js";
+import { sortObject } from "../utils/sortObject.js";
+const DEFAULT_OUTPUT_DIR = path.resolve(process.cwd(), "reports-dynamic");
+export async function writePossiblyDynamicallyUsedReport(keysByFile, jsonFiles, outputDir = DEFAULT_OUTPUT_DIR) {
+    const reportDataByFile = {};
+    for (const file of jsonFiles) {
+        const possibleKeys = keysByFile[file.filePath] ?? [];
+        if (possibleKeys.length === 0) {
+            continue;
+        }
+        const nestedData = {};
+        for (const key of possibleKeys) {
+            const value = getValueByPath(file.data, key);
+            if (value !== undefined) {
+                addKey(nestedData, key, value);
+            }
+        }
+        const relativeTranslationFilePath = path
+            .relative(process.cwd(), file.filePath)
+            .replace(/\\/g, "/");
+        reportDataByFile[relativeTranslationFilePath] = sortObject(nestedData);
+    }
+    if (Object.keys(reportDataByFile).length === 0) {
+        return;
+    }
+    await fs.mkdir(outputDir, { recursive: true });
+    const reportPath = path.join(outputDir, "possibly-dynamically-used.json");
+    await fs.writeFile(reportPath, `${JSON.stringify(sortObject(reportDataByFile), null, 2)}\n`, "utf-8");
+    console.log(`📝 Possibly dynamically used report created: ${reportPath}`);
+}
+function getValueByPath(obj, keyPath) {
+    const parts = keyPath.split(".");
+    let current = obj;
+    for (const part of parts) {
+        if (typeof current !== "object" ||
+            current === null ||
+            Array.isArray(current) ||
+            !(part in current)) {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}

package/dist/core/actions/writeUnusedTranslationsReport.js

@@ -2,18 +2,17 @@ import fs from "fs/promises";
 import path from "path";
 import { addKey } from "../utils/addKey.js";
 import { sortObject } from "../utils/sortObject.js";
-export async function writeUnusedTranslationsReport(result, jsonFiles, outputDir) {
-    const { unusedKeysByFile } = result;
+export async function writeUnusedTranslationsReport(keysByFile, jsonFiles, outputDir) {
     const filesWithUnused = jsonFiles.filter((file) => {
-        const unusedKeys = unusedKeysByFile[file.filePath] ?? [];
-        return unusedKeys.length > 0;
+        const keys = keysByFile[file.filePath] ?? [];
+        return keys.length > 0;
     });
     if (filesWithUnused.length === 0) {
         return;
     }
     await fs.mkdir(outputDir, { recursive: true });
     for (const file of filesWithUnused) {
-        const unusedKeys = unusedKeysByFile[file.filePath] ?? [];
+        const unusedKeys = keysByFile[file.filePath] ?? [];
         const reportData = {};
         for (const key of unusedKeys) {
             const value = getValueByPath(file.data, key);
@@ -22,15 +21,12 @@ export async function writeUnusedTranslationsReport(result, jsonFiles, outputDir
             }
         }
         const sorted = sortObject(reportData);
-        const reportFileName = getUnusedReportFileName(file.filePath);
+        const reportFileName = `unused.${path.basename(file.filePath)}`;
         const reportPath = path.join(outputDir, reportFileName);
         await fs.writeFile(reportPath, JSON.stringify(sorted, null, 2), "utf-8");
         console.log(`📝 Unused report created: ${reportPath}`);
     }
 }
-function getUnusedReportFileName(filePath) {
-    return `unused.${path.basename(filePath)}`;
-}
 function getValueByPath(obj, keyPath) {
     const parts = keyPath.split(".");
     let current = obj;

package/dist/core/analysis/deepVerifyUnusedKeys.js

@@ -0,0 +1,266 @@
+import fs from "fs/promises";
+import ts from "typescript";
+const KEY_REGEX = /^[A-Za-z0-9_-]+(?:[.:][A-Za-z0-9_-]+)*$/;
+function getScriptKind(filePath) {
+    if (filePath.endsWith(".tsx"))
+        return ts.ScriptKind.TSX;
+    if (filePath.endsWith(".ts"))
+        return ts.ScriptKind.TS;
+    if (filePath.endsWith(".jsx"))
+        return ts.ScriptKind.JSX;
+    return ts.ScriptKind.JS;
+}
+function createSourceFile(filePath, content) {
+    return ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, getScriptKind(filePath));
+}
+function isTranslationCall(node) {
+    if (ts.isIdentifier(node.expression)) {
+        return node.expression.text === "t";
+    }
+    if (ts.isPropertyAccessExpression(node.expression)) {
+        return node.expression.name.text === "t";
+    }
+    return false;
+}
+function isDirectLiteral(node) {
+    return ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node);
+}
+function isTransTagName(name) {
+    return ts.isIdentifier(name) && name.text === "Trans";
+}
+function getJsxAttribute(attributes, attributeName) {
+    for (const prop of attributes.properties) {
+        if (ts.isJsxAttribute(prop) &&
+            ts.isIdentifier(prop.name) &&
+            prop.name.text === attributeName) {
+            return prop;
+        }
+    }
+    return undefined;
+}
+function getJsxLiteralAttributeValue(attribute) {
+    if (!attribute?.initializer) {
+        return undefined;
+    }
+    if (ts.isStringLiteral(attribute.initializer)) {
+        return attribute.initializer.text;
+    }
+    if (ts.isJsxExpression(attribute.initializer) &&
+        attribute.initializer.expression &&
+        (ts.isStringLiteral(attribute.initializer.expression) ||
+            ts.isNoSubstitutionTemplateLiteral(attribute.initializer.expression))) {
+        return attribute.initializer.expression.text;
+    }
+    return undefined;
+}
+function splitKey(fullKey) {
+    const firstDotIndex = fullKey.indexOf(".");
+    if (firstDotIndex === -1) {
+        return { localKey: fullKey };
+    }
+    return {
+        namespace: fullKey.slice(0, firstDotIndex),
+        localKey: fullKey.slice(firstDotIndex + 1),
+    };
+}
+function extractNamespaces(sourceFile) {
+    const namespaces = new Set();
+    function visit(node) {
+        if (ts.isCallExpression(node) &&
+            ts.isIdentifier(node.expression) &&
+            node.expression.text === "useTranslation") {
+            const firstArg = node.arguments[0];
+            if (firstArg) {
+                if (ts.isStringLiteral(firstArg) ||
+                    ts.isNoSubstitutionTemplateLiteral(firstArg)) {
+                    namespaces.add(firstArg.text);
+                }
+                if (ts.isArrayLiteralExpression(firstArg)) {
+                    for (const element of firstArg.elements) {
+                        if (ts.isStringLiteral(element) ||
+                            ts.isNoSubstitutionTemplateLiteral(element)) {
+                            namespaces.add(element.text);
+                        }
+                    }
+                }
+            }
+        }
+        if (ts.isJsxSelfClosingElement(node) && isTransTagName(node.tagName)) {
+            const nsValue = getJsxLiteralAttributeValue(getJsxAttribute(node.attributes, "ns"));
+            if (nsValue) {
+                namespaces.add(nsValue);
+            }
+        }
+        if (ts.isJsxOpeningElement(node) && isTransTagName(node.tagName)) {
+            const nsValue = getJsxLiteralAttributeValue(getJsxAttribute(node.attributes, "ns"));
+            if (nsValue) {
+                namespaces.add(nsValue);
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return namespaces;
+}
+function collectLiteralKeys(sourceFile) {
+    const keys = new Set();
+    function visit(node) {
+        if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+            const value = node.text.trim();
+            if (KEY_REGEX.test(value)) {
+                keys.add(value);
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return keys;
+}
+function collectTemplatePrefixes(sourceFile) {
+    const prefixes = new Set();
+    function addPrefix(prefix) {
+        const normalized = prefix.trim();
+        if (!normalized) {
+            return;
+        }
+        prefixes.add(normalized);
+    }
+    function visit(node) {
+        if (ts.isCallExpression(node) && isTranslationCall(node)) {
+            const firstArg = node.arguments[0];
+            if (firstArg && ts.isTemplateExpression(firstArg)) {
+                addPrefix(firstArg.head.text);
+            }
+        }
+        if (ts.isJsxSelfClosingElement(node) && isTransTagName(node.tagName)) {
+            const i18nKeyAttr = getJsxAttribute(node.attributes, "i18nKey");
+            if (i18nKeyAttr?.initializer &&
+                ts.isJsxExpression(i18nKeyAttr.initializer) &&
+                i18nKeyAttr.initializer.expression &&
+                ts.isTemplateExpression(i18nKeyAttr.initializer.expression)) {
+                addPrefix(i18nKeyAttr.initializer.expression.head.text);
+            }
+        }
+        if (ts.isJsxOpeningElement(node) && isTransTagName(node.tagName)) {
+            const i18nKeyAttr = getJsxAttribute(node.attributes, "i18nKey");
+            if (i18nKeyAttr?.initializer &&
+                ts.isJsxExpression(i18nKeyAttr.initializer) &&
+                i18nKeyAttr.initializer.expression &&
+                ts.isTemplateExpression(i18nKeyAttr.initializer.expression)) {
+                addPrefix(i18nKeyAttr.initializer.expression.head.text);
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return [...prefixes];
+}
+function detectDynamicTranslationUsage(sourceFile) {
+    let found = false;
+    function visit(node) {
+        if (found) {
+            return;
+        }
+        if (ts.isCallExpression(node) && isTranslationCall(node)) {
+            const firstArg = node.arguments[0];
+            if (firstArg && !isDirectLiteral(firstArg)) {
+                found = true;
+                return;
+            }
+        }
+        if (ts.isJsxSelfClosingElement(node) && isTransTagName(node.tagName)) {
+            const i18nKeyAttr = getJsxAttribute(node.attributes, "i18nKey");
+            if (i18nKeyAttr?.initializer &&
+                ts.isJsxExpression(i18nKeyAttr.initializer) &&
+                i18nKeyAttr.initializer.expression) {
+                const expr = i18nKeyAttr.initializer.expression;
+                if (!isDirectLiteral(expr)) {
+                    found = true;
+                    return;
+                }
+            }
+        }
+        if (ts.isJsxOpeningElement(node) && isTransTagName(node.tagName)) {
+            const i18nKeyAttr = getJsxAttribute(node.attributes, "i18nKey");
+            if (i18nKeyAttr?.initializer &&
+                ts.isJsxExpression(i18nKeyAttr.initializer) &&
+                i18nKeyAttr.initializer.expression) {
+                const expr = i18nKeyAttr.initializer.expression;
+                if (!isDirectLiteral(expr)) {
+                    found = true;
+                    return;
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return found;
+}
+async function collectFileEvidence(filePath) {
+    const content = await fs.readFile(filePath, "utf-8");
+    const sourceFile = createSourceFile(filePath, content);
+    return {
+        namespaces: extractNamespaces(sourceFile),
+        hasDynamicTranslationUsage: detectDynamicTranslationUsage(sourceFile),
+        literalKeys: collectLiteralKeys(sourceFile),
+        templatePrefixes: collectTemplatePrefixes(sourceFile),
+    };
+}
+function keyMatchesTemplatePrefix(fullKey, localKey, namespace, evidence) {
+    for (const prefix of evidence.templatePrefixes) {
+        if (fullKey.startsWith(prefix)) {
+            return true;
+        }
+        if (namespace &&
+            evidence.namespaces.has(namespace) &&
+            localKey.startsWith(prefix)) {
+            return true;
+        }
+    }
+    return false;
+}
+function keyIsPossiblyDynamic(fullKey, evidenceList) {
+    const { namespace, localKey } = splitKey(fullKey);
+    for (const evidence of evidenceList) {
+        // case 1: full key exists as a string literal somewhere in code/object
+        if (evidence.literalKeys.has(fullKey)) {
+            return true;
+        }
+        // case 2: local key exists and file uses matching namespace + dynamic t/Trans usage
+        if (namespace &&
+            evidence.hasDynamicTranslationUsage &&
+            evidence.namespaces.has(namespace) &&
+            evidence.literalKeys.has(localKey)) {
+            return true;
+        }
+        // case 3: template literal prefix
+        if (keyMatchesTemplatePrefix(fullKey, localKey, namespace, evidence)) {
+            return true;
+        }
+    }
+    return false;
+}
+export async function deepVerifyUnusedKeys(sourceFiles, unusedKeysByFile) {
+    const definitelyUnusedByFile = {};
+    const possiblyDynamicallyUsedByFile = {};
+    const evidenceList = await Promise.all(sourceFiles.map((file) => collectFileEvidence(file)));
+    for (const [translationFilePath, unusedKeys] of Object.entries(unusedKeysByFile)) {
+        const definitelyUnused = [];
+        const possiblyDynamic = [];
+        for (const key of unusedKeys) {
+            if (keyIsPossiblyDynamic(key, evidenceList)) {
+                possiblyDynamic.push(key);
+            }
+            else {
+                definitelyUnused.push(key);
+            }
+        }
+        definitelyUnusedByFile[translationFilePath] = definitelyUnused;
+        possiblyDynamicallyUsedByFile[translationFilePath] = possiblyDynamic;
+    }
+    return {
+        definitelyUnusedByFile,
+        possiblyDynamicallyUsedByFile,
+    };
+}

package/dist/core/scanner.js

@@ -7,6 +7,7 @@ import { writeDynamicTranslationReport } from "./actions/writeDynamicTranslation
 import { syncMissingTranslations } from "./actions/syncMissingTranslations.js";
 import { removeUnusedTranslations } from "./actions/removeUnusedTranslations.js";
 import { writeUnusedTranslationsReport } from "./actions/writeUnusedTranslationsReport.js";
+import { deepVerifyUnusedKeys } from "./analysis/deepVerifyUnusedKeys.js";
 export async function runScanner(config) {
     const files = await getFiles(config.srcPaths);
     const dynamicUsages = await detectDynamicTranslationUsages(files);
@@ -14,12 +15,17 @@ export async function runScanner(config) {
     const usedKeys = await extractKeysFromFiles(files);
     const jsonData = await loadJsonKeys(config.jsonDir);
     const result = analyzeKeys(usedKeys, jsonData);
-    await writeUnusedTranslationsReport(result, jsonData, config.outputDir);
+    const verification = await deepVerifyUnusedKeys(files, result.unusedKeysByFile);
+    await writeUnusedTranslationsReport(verification.definitelyUnusedByFile, jsonData, config.outputDir);
     if (config.syncMissing) {
         await syncMissingTranslations(result, jsonData, config.sortJson);
     }
     if (config.removeUnused) {
-        await removeUnusedTranslations(result, jsonData, config.sortJson);
+        const filteredResult = {
+            ...result,
+            unusedKeysByFile: verification.definitelyUnusedByFile,
+        };
+        await removeUnusedTranslations(filteredResult, jsonData, config.sortJson);
     }
     return result;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-i18next-scanner",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "CLI tool to scan React projects for missing and unused react-i18next translation keys",
   "bin": "./dist/cli/cli.js",
   "scripts": {