ai-localize-codemods 2.0.0 → 2.0.1

package/src/codemod-runner.ts

@@ -22,14 +22,26 @@ export interface CodemodRunSummary {
 
 /**
  * Orchestrates codemods across all detected files.
- * Groups detected texts by file and applies the appropriate codemod
- * based on the project framework.
+ *
+ * Groups detected texts by file and applies the appropriate codemod based on
+ * the project framework.  Codemod behaviour (import package, hook name,
+ * translation function, namespace, accessor style) is driven by `config.codemods`
+ * so the user can override defaults in their ai-localize.config.json.
+ *
+ * ### Local hook import path resolution
+ * When `config.codemods.importPackage` is a project-relative path (e.g.
+ * `"src/Locales/translate"`), `cwd` is forwarded to `applyReactCodemod` so it
+ * can compute the correct relative import path for each individual file:
+ *   src/components/Button.tsx      → `"../../Locales/translate"`
+ *   src/pages/dashboard/Header.tsx → `"../../../Locales/translate"`
  */
 export class CodemodRunner {
   private config: LocalizationConfig;
+  private cwd: string;
 
-  constructor(config: LocalizationConfig) {
+  constructor(config: LocalizationConfig, cwd = process.cwd()) {
     this.config = config;
+    this.cwd = cwd;
   }
 
   async run(
@@ -37,43 +49,43 @@ export class CodemodRunner {
     options: CodemodRunOptions = {}
   ): Promise<CodemodRunSummary> {
     const startTime = Date.now();
-    const { dryRun = false, onProgress } = options;
+const { dryRun = false, onProgress } = options;
 
     // Group texts by file
     const fileTextMap = new Map<string, DetectedText[]>();
     for (const dt of detectedTexts) {
       const existing = fileTextMap.get(dt.filePath) || [];
-    existing.push(dt);
-      fileTextMap.set(dt.filePath, existing);
-  }
+      existing.push(dt);
+  fileTextMap.set(dt.filePath, existing);
+    }
 
     const results: CodemodResult[] = [];
     let totalReplacements = 0;
     let importInjections = 0;
     let hookInjections = 0;
 
-    for (const [filePath, texts] of fileTextMap) {
+ for (const [filePath, texts] of fileTextMap) {
       let result: CodemodResult;
- const framework = this.config.framework;
+      const framework = this.config.framework;
 
       try {
         result = this.applyCodemod(filePath, texts, framework, dryRun);
       } catch (err) {
         result = {
-          filePath,
-    originalContent: '',
-        transformedContent: '',
+   filePath,
+          originalContent: '',
+       transformedContent: '',
           changed: false,
-          injectedImport: false,
+ injectedImport: false,
           injectedHook: false,
-          replacedTexts: 0,
-  };
-  }
+ replacedTexts: 0,
+        };
+      }
 
       results.push(result);
-totalReplacements += result.replacedTexts;
-      if (result.injectedImport) importInjections++;
-   if (result.injectedHook) hookInjections++;
+      totalReplacements += result.replacedTexts;
+if (result.injectedImport) importInjections++;
+      if (result.injectedHook) hookInjections++;
 
       onProgress?.(filePath, result);
     }
@@ -82,10 +94,10 @@ totalReplacements += result.replacedTexts;
       totalFiles: fileTextMap.size,
       changedFiles: results.filter((r) => r.changed).length,
       totalReplacements,
- importInjections,
-      hookInjections,
-    results,
-      duration: Date.now() - startTime,
+      importInjections,
+    hookInjections,
+      results,
+  duration: Date.now() - startTime,
     };
   }
 
@@ -96,22 +108,25 @@ totalReplacements += result.replacedTexts;
     dryRun: boolean
   ): CodemodResult {
     const ext = path.extname(filePath).toLowerCase();
+    const codemodConfig = this.config.codemods;
 
     // Vue SFCs
     if (ext === '.vue') {
-      return applyVueCodemod(filePath, texts, dryRun);
+      return applyVueCodemod(filePath, texts, dryRun, codemodConfig);
     }
 
     // Angular templates or TS
-    if (
+  if (
       framework === 'angular' ||
       framework === 'angular-ngx' ||
       framework === 'angular-i18n'
-    ) {
-    return applyAngularCodemod(filePath, texts, dryRun);
+  ) {
+      return applyAngularCodemod(filePath, texts, dryRun, codemodConfig);
     }
 
     // React (default for .tsx, .ts, .jsx, .js)
-    return applyReactCodemod(filePath, texts, dryRun);
+    // Pass cwd so the codemod can resolve per-file relative import paths
+    // for local hook files (e.g. "src/Locales/translate").
+    return applyReactCodemod(filePath, texts, dryRun, codemodConfig, this.cwd);
   }
 }

package/src/react-codemod.ts

@@ -1,10 +1,11 @@
 import * as fs from 'fs';
+import * as nodePath from 'path';
 import * as parser from '@babel/parser';
 import traverse from '@babel/traverse';
 import generate from '@babel/generator';
 import * as t from '@babel/types';
 
-import type { DetectedText } from 'ai-localize-shared';
+import type { DetectedText, CodemodConfig } from 'ai-localize-shared';
 
 export interface CodemodResult {
   filePath: string;
@@ -16,60 +17,96 @@ export interface CodemodResult {
   replacedTexts: number;
 }
 
-const USE_TRANSLATION_IMPORT = 'react-i18next';
-const USE_TRANSLATION_HOOK = 'useTranslation';
+const DEFAULT_IMPORT_PACKAGE = 'react-i18next';
+const DEFAULT_HOOK_NAME = 'useTranslation';
+const DEFAULT_TRANSLATION_FN = 't';
+const DEFAULT_ACCESSOR_STYLE = 'function';
 
 /**
- * React i18n codemod: wraps hardcoded JSX text / string literals with t() calls.
+ * React i18n codemod: wraps hardcoded JSX text / string literals with t() or t[''] calls.
  * Preserves formatting, comments, and import order.
+ *
+ * ### Local hook import paths
+ *
+ * When `codemodConfig.importPackage` is a project-relative path (e.g. `"src/Locales/translate"`),
+ * the codemod computes the correct **relative import path for each file** it transforms:
+ *
+ *   src/components/Button.tsx      → `"../../Locales/translate"`
+ *   src/pages/dashboard/Header.tsx → `"../../../Locales/translate"`
+ *
+ * npm package names (no `/` prefix, not starting with `.`) are injected verbatim.
+ *
+ * ### Accessor styles
+ *   accessorStyle "function" (default) → t('key')
+ *   accessorStyle "bracket"  → t['key']
  */
 export class ReactCodemod {
   private filePath: string;
   private content: string;
   private texts: DetectedText[];
+  /** Resolved import specifier string (may differ per file for local paths) */
+  private importSpecifier: string;
+  private hookName: string;
+  private translationFn: string;
+  private namespace?: string;
+  private accessorStyle: 'function' | 'bracket';
 
-  constructor(filePath: string, content: string, texts: DetectedText[]) {
+  constructor(
+  filePath: string,
+    content: string,
+    texts: DetectedText[],
+    codemodConfig?: CodemodConfig,
+    cwd = process.cwd()
+  ) {
     this.filePath = filePath;
     this.content = content;
- this.texts = texts;
-  }
+    this.texts = texts;
+      this.hookName = codemodConfig?.hookName ?? DEFAULT_HOOK_NAME;
+    this.translationFn = codemodConfig?.translationFunction ?? DEFAULT_TRANSLATION_FN;
+    this.namespace = codemodConfig?.namespace;
+    this.accessorStyle = codemodConfig?.accessorStyle ?? DEFAULT_ACCESSOR_STYLE;
+
+    // Resolve import specifier: npm package → verbatim, local path → per-file relative
+    const pkg = codemodConfig?.importPackage ?? DEFAULT_IMPORT_PACKAGE;
+    this.importSpecifier = resolveImportSpecifier(pkg, filePath, cwd);
+}
 
   transform(): CodemodResult {
     if (this.texts.length === 0) {
       return {
-        filePath: this.filePath,
+      filePath: this.filePath,
 originalContent: this.content,
         transformedContent: this.content,
-     changed: false,
-        injectedImport: false,
+        changed: false,
+   injectedImport: false,
         injectedHook: false,
-  replacedTexts: 0,
+        replacedTexts: 0,
       };
-    }
+}
 
     let ast: t.File;
     try {
-      ast = parser.parse(this.content, {
+    ast = parser.parse(this.content, {
         sourceType: 'module',
         plugins: [
-          'jsx',
-          'typescript',
+  'jsx',
+     'typescript',
           'decorators-legacy',
-       'classProperties',
-   'optionalChaining',
+          'classProperties',
+          'optionalChaining',
           'nullishCoalescingOperator',
-      ],
+        ],
         errorRecovery: true,
       });
     } catch {
-    return {
- filePath: this.filePath,
+      return {
+        filePath: this.filePath,
         originalContent: this.content,
-        transformedContent: this.content,
+ transformedContent: this.content,
         changed: false,
         injectedImport: false,
-    injectedHook: false,
-     replacedTexts: 0,
+      injectedHook: false,
+        replacedTexts: 0,
  };
     }
 
@@ -80,144 +117,153 @@ originalContent: this.content,
     }
 
     let replacedTexts = 0;
-    let hasUseTranslationImport = false;
-    let hasUseTranslationHook = false;
+    let hasImport = false;
+    let hasHook = false;
     let injectedImport = false;
     let injectedHook = false;
 
-    // Check existing imports
-    traverse(ast, {
-      ImportDeclaration(nodePath) {
-        if (nodePath.node.source.value === USE_TRANSLATION_IMPORT) {
-          hasUseTranslationImport = true;
+    const translationFn = this.translationFn;
+    const hookName = this.hookName;
+    const importSpecifier = this.importSpecifier;
+    const accessorStyle = this.accessorStyle;
+
+    /**
+     * Builds the translation expression for a key.
+ *   "function" style: t('some.key')
+ *   "bracket"  style: t['some.key']
+     */
+    const buildTranslationExpr = (key: string): t.Expression => {
+      if (accessorStyle === 'bracket') {
+        return t.memberExpression(
+          t.identifier(translationFn),
+          t.stringLiteral(key),
+          true /* computed */
+        );
       }
+    return t.callExpression(t.identifier(translationFn), [t.stringLiteral(key)]);
+ };
+
+    // First pass: detect existing imports and hook usage
+ traverse(ast, {
+      ImportDeclaration(nodePath) {
+        if (nodePath.node.source.value === importSpecifier) {
+          hasImport = true;
+        }
       },
-      // Check if useTranslation hook already destructured
       VariableDeclarator(nodePath) {
-    const id = nodePath.node.id;
-      if (
- t.isObjectPattern(id) &&
- id.properties.some(
-            (p) =>
-              t.isObjectProperty(p) &&
- t.isIdentifier(p.key) &&
-         p.key.name === 't'
-  )
+        const id = nodePath.node.id;
+        if (
+   t.isObjectPattern(id) &&
+          id.properties.some(
+  (p) =>
+        t.isObjectProperty(p) &&
+     t.isIdentifier(p.key) &&
+   p.key.name === translationFn
+          )
         ) {
-          hasUseTranslationHook = true;
- }
+          hasHook = true;
+   }
       },
     });
 
     // Second pass: replace hardcoded texts
-  traverse(ast, {
+    traverse(ast, {
       JSXText(nodePath) {
         const text = nodePath.node.value.trim();
         if (!text) return;
         const key = textKeyMap.get(text);
         if (!key) return;
-
-        // Replace with {t('key')}
-   const tCall = t.jsxExpressionContainer(
-          t.callExpression(t.identifier('t'), [t.stringLiteral(key)])
-);
-        nodePath.replaceWith(tCall);
+      nodePath.replaceWith(t.jsxExpressionContainer(buildTranslationExpr(key)));
         replacedTexts++;
       },
 
-      StringLiteral(nodePath) {
+    StringLiteral(nodePath) {
         const text = nodePath.node.value;
-        const key = textKeyMap.get(text);
+     const key = textKeyMap.get(text);
         if (!key) return;
         if (t.isImportDeclaration(nodePath.parent)) return;
-        if (t.isObjectProperty(nodePath.parent) && nodePath.parent.key === nodePath.node) return;
-      if (t.isJSXAttribute(nodePath.parent)) return;
-
-        const tCall = t.callExpression(t.identifier('t'), [t.stringLiteral(key)]);
-        nodePath.replaceWith(tCall);
+  if (t.isObjectProperty(nodePath.parent) && nodePath.parent.key === nodePath.node) return;
+        if (t.isJSXAttribute(nodePath.parent)) return;
+     nodePath.replaceWith(buildTranslationExpr(key));
         replacedTexts++;
       },
 
       JSXAttribute(nodePath) {
         const valueNode = nodePath.node.value;
-   if (!t.isStringLiteral(valueNode)) return;
-      const text = valueNode.value;
+        if (!t.isStringLiteral(valueNode)) return;
+        const text = valueNode.value;
         const key = textKeyMap.get(text);
         if (!key) return;
-
-        // Replace string with {t('key')} expression
- nodePath.node.value = t.jsxExpressionContainer(
-          t.callExpression(t.identifier('t'), [t.stringLiteral(key)])
-   );
-        replacedTexts++;
+        nodePath.node.value = t.jsxExpressionContainer(buildTranslationExpr(key));
+  replacedTexts++;
       },
     });
 
-    if (replacedTexts === 0) {
+  if (replacedTexts === 0) {
       return {
-        filePath: this.filePath,
-   originalContent: this.content,
-   transformedContent: this.content,
-      changed: false,
-    injectedImport: false,
+ filePath: this.filePath,
+        originalContent: this.content,
+        transformedContent: this.content,
+     changed: false,
+ injectedImport: false,
         injectedHook: false,
-        replacedTexts: 0,
+      replacedTexts: 0,
       };
     }
 
- // Inject import if needed
-    if (!hasUseTranslationImport) {
+  // Inject import if needed (uses the per-file resolved import specifier)
+    if (!hasImport) {
       const importDecl = t.importDeclaration(
-   [t.importSpecifier(t.identifier(USE_TRANSLATION_HOOK), t.identifier(USE_TRANSLATION_HOOK))],
-      t.stringLiteral(USE_TRANSLATION_IMPORT)
+ [t.importSpecifier(t.identifier(hookName), t.identifier(hookName))],
+        t.stringLiteral(importSpecifier)
       );
-  ast.program.body.unshift(importDecl);
-injectedImport = true;
+      ast.program.body.unshift(importDecl);
+      injectedImport = true;
     }
 
     // Inject hook at the top of function components
-    if (!hasUseTranslationHook) {
-      this.injectUseTranslationHook(ast);
-      injectedHook = true;
+    if (!hasHook) {
+this.injectHook(ast);
+   injectedHook = true;
     }
 
     // Generate output preserving formatting
- const output = generate(
+    const output = generate(
       ast,
-      {
-        retainLines: false,
-    comments: true,
-        compact: false,
-      },
-      this.content
-);
+      { retainLines: false, comments: true, compact: false },
+    this.content
+    );
 
     return {
       filePath: this.filePath,
       originalContent: this.content,
       transformedContent: output.code,
       changed: true,
-injectedImport,
+      injectedImport,
       injectedHook,
       replacedTexts,
     };
   }
 
-  private injectUseTranslationHook(ast: t.File): void {
+  private injectHook(ast: t.File): void {
+    const hookName = this.hookName;
+    const translationFn = this.translationFn;
+    const namespace = this.namespace;
+
     traverse(ast, {
       FunctionDeclaration(nodePath) {
         if (!isReactComponent(nodePath.node.id?.name)) return;
- injectHookIntoBody(nodePath.node.body);
+        injectHookIntoBody(nodePath.node.body, hookName, translationFn, namespace);
         nodePath.stop();
       },
- ArrowFunctionExpression(nodePath) {
+  ArrowFunctionExpression(nodePath) {
         if (!isReactComponentParent(nodePath)) return;
-        const body = nodePath.node.body;
+   const body = nodePath.node.body;
         if (t.isBlockStatement(body)) {
-    injectHookIntoBody(body);
-      nodePath.stop();
+          injectHookIntoBody(body, hookName, translationFn, namespace);
+          nodePath.stop();
         }
-      },
+  },
     });
   }
 }
@@ -232,38 +278,138 @@ function isReactComponentParent(nodePath: any): boolean {
   const parent = nodePath.parent;
   if (t.isVariableDeclarator(parent)) {
     const id = parent.id;
-    if (t.isIdentifier(id) && /^[A-Z]/.test(id.name)) return true;
+  if (t.isIdentifier(id) && /^[A-Z]/.test(id.name)) return true;
   }
   return false;
 }
 
-function injectHookIntoBody(body: t.BlockStatement): void {
-  // const { t } = useTranslation();
+function injectHookIntoBody(
+  body: t.BlockStatement,
+  hookName: string,
+  translationFn: string,
+  namespace?: string
+): void {
+  const hookArgs: t.Expression[] = namespace ? [t.stringLiteral(namespace)] : [];
   const hookDecl = t.variableDeclaration('const', [
     t.variableDeclarator(
       t.objectPattern([
-    t.objectProperty(t.identifier('t'), t.identifier('t'), false, true),
+        t.objectProperty(t.identifier(translationFn), t.identifier(translationFn), false, true),
       ]),
-      t.callExpression(t.identifier('useTranslation'), [])
+      t.callExpression(t.identifier(hookName), hookArgs)
     ),
   ]);
   body.body.unshift(hookDecl);
 }
 
+/**
+ * Determines the import specifier string to inject for a given `importPackage`
+ * config value and the file being transformed.
+ *
+ * Rules:
+ *   1. If `importPackage` looks like an npm package name (no leading `.` or `/`
+ *      and no path separators in a way that suggests a local path starting with
+ *      a known directory like `src/`) → return verbatim.
+ *
+ *   2. If `importPackage` is an absolute path → compute `path.relative(fileDir, importPackage)`
+ *  and ensure it starts with `./` or `../`.
+ *
+ *   3. If `importPackage` is a project-relative path (starts with `src/`, `app/`,
+ *      `lib/`, `hooks/`, `utils/`, or any path without a leading `.`) that is NOT
+ *      a bare npm package name → resolve it relative to `cwd` first, then compute
+ *      `path.relative(fileDir, resolvedPath)`.
+ *
+ *   4. If `importPackage` starts with `./` or `../` → treat as a path relative to
+ *    `cwd` (config file location), resolve it, then compute relative to each file.
+ */
+export function resolveImportSpecifier(
+  importPackage: string,
+  filePath: string,
+  cwd: string
+): string {
+  // Bare npm package name — no slashes that indicate a local path, or scoped @org/pkg
+  if (isNpmPackage(importPackage)) {
+    return importPackage;
+  }
+
+  // Resolve the hook file to an absolute path
+  let absoluteHookPath: string;
+  if (nodePath.isAbsolute(importPackage)) {
+    absoluteHookPath = importPackage;
+  } else {
+    // Project-relative (e.g. "src/Locales/translate") or relative (e.g. "../../hooks/t")
+    absoluteHookPath = nodePath.resolve(cwd, importPackage);
+  }
+
+  // Compute relative path from the directory of the file being transformed
+  const fileDir = nodePath.dirname(filePath);
+  let rel = nodePath.relative(fileDir, absoluteHookPath).replace(/\\/g, '/');
+
+  // Ensure it starts with ./ or ../
+  if (!rel.startsWith('.')) {
+    rel = `./${rel}`;
+  }
+
+  return rel;
+}
+
+/**
+ * Returns true if the string looks like a bare npm package name rather than a
+ * local file path.
+ *
+ * npm package names:
+ *   - Do not start with `.` or `/`
+ *   - Scoped packages start with `@` followed by `org/pkg`
+ *   - Do NOT look like project-relative source paths such as `src/...`, `app/...`
+ *
+ * We consider a string a local path if it:
+ *   - Starts with `.` (relative: `./hooks/t`, `../../hooks/t`)
+ *- Starts with `/` (absolute)
+ *   - Contains a `/` AND its first segment looks like a source directory
+ *     (`src`, `app`, `lib`, `hooks`, `utils`, `pages`, `components`, `features`,
+ *      `shared`, `common`, `locales`, `i18n`, `services`, `store`)
+ */
+function isNpmPackage(pkg: string): boolean {
+  if (pkg.startsWith('.') || pkg.startsWith('/')) return false;
+
+  // Scoped npm package: @scope/name — always npm
+  if (pkg.startsWith('@') && pkg.includes('/')) {
+    // @/alias paths used in bundlers (e.g. "@/hooks/useT") are NOT npm packages
+    if (pkg.startsWith('@/')) return false;
+    return true;
+  }
+
+  // If no slash at all → bare npm package name (e.g. "i18next", "react-i18next")
+  if (!pkg.includes('/')) return true;
+
+  // Has a slash — check if the first segment is a known source directory name
+  const firstSegment = pkg.split('/')[0].toLowerCase();
+  const sourceDirectories = new Set([
+    'src', 'app', 'lib', 'hooks', 'utils', 'pages', 'components',
+    'features', 'shared', 'common', 'locales', 'i18n', 'services',
+    'store', 'helpers', 'core', 'modules',
+  ]);
+  if (sourceDirectories.has(firstSegment)) return false;
+
+  // Everything else (e.g. "lodash/fp", "date-fns/locale") → npm package
+  return true;
+}
+
 /**
  * Applies the React codemod to a file in-place.
  */
 export function applyReactCodemod(
   filePath: string,
   texts: DetectedText[],
-  dryRun = false
+  dryRun = false,
+  codemodConfig?: CodemodConfig,
+  cwd = process.cwd()
 ): CodemodResult {
   const content = fs.readFileSync(filePath, 'utf-8');
-  const codemod = new ReactCodemod(filePath, content, texts);
+  const codemod = new ReactCodemod(filePath, content, texts, codemodConfig, cwd);
   const result = codemod.transform();
 
   if (result.changed && !dryRun) {
-    fs.writeFileSync(filePath, result.transformedContent, 'utf-8');
+ fs.writeFileSync(filePath, result.transformedContent, 'utf-8');
   }
 
   return result;