@lang-tag/cli 0.11.2 → 0.12.0

package/algorithms/config-generation/config-keeper.d.ts

@@ -0,0 +1,47 @@
+import { LangTagCLIConfigGenerationEvent } from '../../config.ts';
+export type ConfigKeeperMode = 'namespace' | 'path' | 'both';
+export interface ConfigKeeperOptions {
+    /**
+     * The name of the property in the tag configuration that indicates what should be kept.
+     * @default 'keep'
+     * @example
+     * ```tsx
+     * lang({ click: "Click" }, { namespace: 'common', path: 'button', keep: 'namespace' })
+     * ```
+     */
+    propertyName?: string;
+}
+/**
+ * Creates a config keeper algorithm that preserves original configuration values
+ * when they are marked to be kept using a special property (default: 'keep').
+ *
+ * This algorithm should be applied AFTER other generation algorithms to prevent
+ * them from overwriting values that should be preserved.
+ *
+ * @example
+ * ```ts
+ * const pathAlgorithm = pathBasedConfigGenerator({ ... });
+ * const keeper = configKeeper();
+ *
+ * onConfigGeneration: async (event) => {
+ *   // First, apply path-based generation
+ *   await pathAlgorithm(event);
+ *
+ *   // Then, restore any values marked to be kept
+ *   await keeper(event);
+ * }
+ * ```
+ *
+ * @example Usage in tag:
+ * ```tsx
+ * // This will keep the namespace even if path-based algorithm tries to change it
+ * lang({ click: "Click" }, { namespace: 'common', path: 'button', keep: 'namespace' })
+ *
+ * // This will keep the path even if path-based algorithm tries to change it
+ * lang({ click: "Click" }, { namespace: 'common', path: 'old.path', keep: 'path' })
+ *
+ * // This will keep both namespace and path
+ * lang({ click: "Click" }, { namespace: 'common', path: 'button', keep: 'both' })
+ * ```
+ */
+export declare function configKeeper(options?: ConfigKeeperOptions): (event: LangTagCLIConfigGenerationEvent) => Promise<void>;

package/algorithms/config-generation/index.d.ts

@@ -5,3 +5,4 @@
  * during collection and regeneration.
  */
 export { pathBasedConfigGenerator, type PathBasedConfigGeneratorOptions } from './path-based-config-generator.ts';
+export { configKeeper, type ConfigKeeperOptions, type ConfigKeeperMode } from './config-keeper.ts';

package/algorithms/index.cjs

@@ -19,6 +19,7 @@ function _interopNamespaceDefault(e) {
   return Object.freeze(n);
 }
 const caseLib__namespace = /* @__PURE__ */ _interopNamespaceDefault(caseLib);
+const TRIGGER_NAME$1 = "path-based-config-generator";
 function pathBasedConfigGenerator(options = {}) {
   const {
     includeFileName = false,
@@ -88,7 +89,7 @@ function pathBasedConfigGenerator(options = {}) {
       if (path$1) {
         newConfig.path = path$1;
       } else {
-        event.save(void 0);
+        event.save(null, TRIGGER_NAME$1);
         return;
       }
     } else {
@@ -100,7 +101,7 @@ function pathBasedConfigGenerator(options = {}) {
       }
     }
     if (Object.keys(newConfig).length > 0) {
-      event.save(newConfig);
+      event.save(newConfig, TRIGGER_NAME$1);
     }
   };
 }
@@ -156,4 +157,40 @@ function extractRootDirectoriesFromIncludes(includes) {
   }
   return Array.from(directories);
 }
+const TRIGGER_NAME = "config-keeper";
+function configKeeper(options = {}) {
+  const propertyName = options.propertyName ?? "keep";
+  return async (event) => {
+    if (!event.isSaved) {
+      return;
+    }
+    if (!event.config) {
+      return;
+    }
+    const keepMode = event.config[propertyName];
+    if (!keepMode) {
+      return;
+    }
+    if (keepMode !== "namespace" && keepMode !== "path" && keepMode !== "both") {
+      return;
+    }
+    let restoredConfig;
+    if (event.savedConfig === null) {
+      restoredConfig = { ...event.config };
+      delete restoredConfig.namespace;
+      delete restoredConfig.path;
+    } else {
+      restoredConfig = { ...event.savedConfig };
+    }
+    if ((keepMode === "namespace" || keepMode === "both") && event.config.namespace !== void 0) {
+      restoredConfig.namespace = event.config.namespace;
+    }
+    if ((keepMode === "path" || keepMode === "both") && event.config.path !== void 0) {
+      restoredConfig.path = event.config.path;
+    }
+    restoredConfig[propertyName] = keepMode;
+    event.save(restoredConfig, TRIGGER_NAME);
+  };
+}
+exports.configKeeper = configKeeper;
 exports.pathBasedConfigGenerator = pathBasedConfigGenerator;

package/algorithms/index.d.ts

@@ -4,4 +4,4 @@
  * These algorithms can be used in your lang-tag-cli config file
  * to customize how tags are processed during collection and regeneration.
  */
-export { pathBasedConfigGenerator, type PathBasedConfigGeneratorOptions } from './config-generation/index.ts';
+export * from './config-generation/index.ts';

package/algorithms/index.js

@@ -1,5 +1,6 @@
 import { sep } from "pathe";
 import * as caseLib from "case";
+const TRIGGER_NAME$1 = "path-based-config-generator";
 function pathBasedConfigGenerator(options = {}) {
   const {
     includeFileName = false,
@@ -69,7 +70,7 @@ function pathBasedConfigGenerator(options = {}) {
       if (path) {
         newConfig.path = path;
       } else {
-        event.save(void 0);
+        event.save(null, TRIGGER_NAME$1);
         return;
       }
     } else {
@@ -81,7 +82,7 @@ function pathBasedConfigGenerator(options = {}) {
       }
     }
     if (Object.keys(newConfig).length > 0) {
-      event.save(newConfig);
+      event.save(newConfig, TRIGGER_NAME$1);
     }
   };
 }
@@ -137,6 +138,42 @@ function extractRootDirectoriesFromIncludes(includes) {
   }
   return Array.from(directories);
 }
+const TRIGGER_NAME = "config-keeper";
+function configKeeper(options = {}) {
+  const propertyName = options.propertyName ?? "keep";
+  return async (event) => {
+    if (!event.isSaved) {
+      return;
+    }
+    if (!event.config) {
+      return;
+    }
+    const keepMode = event.config[propertyName];
+    if (!keepMode) {
+      return;
+    }
+    if (keepMode !== "namespace" && keepMode !== "path" && keepMode !== "both") {
+      return;
+    }
+    let restoredConfig;
+    if (event.savedConfig === null) {
+      restoredConfig = { ...event.config };
+      delete restoredConfig.namespace;
+      delete restoredConfig.path;
+    } else {
+      restoredConfig = { ...event.savedConfig };
+    }
+    if ((keepMode === "namespace" || keepMode === "both") && event.config.namespace !== void 0) {
+      restoredConfig.namespace = event.config.namespace;
+    }
+    if ((keepMode === "path" || keepMode === "both") && event.config.path !== void 0) {
+      restoredConfig.path = event.config.path;
+    }
+    restoredConfig[propertyName] = keepMode;
+    event.save(restoredConfig, TRIGGER_NAME);
+  };
+}
 export {
+  configKeeper,
   pathBasedConfigGenerator
 };

package/config.d.ts

@@ -195,11 +195,22 @@ export interface LangTagCLIConfigGenerationEvent {
      */
     readonly config: Readonly<LangTagTranslationsConfig> | undefined;
     readonly langTagConfig: LangTagCLIConfig;
+    /**
+     * Indicates whether the `save()` method has been called during this event.
+     */
+    readonly isSaved: boolean;
+    /**
+     * The updated configuration that was passed to the `save()` method.
+     * - `undefined` if `save()` has not been called yet
+     * - `null` if `save(null)` was called to remove the configuration
+     * - `LangTagTranslationsConfig` object if a new configuration was saved
+     */
+    readonly savedConfig: LangTagTranslationsConfig | null | undefined;
     /**
      * Tells CLI to replace tag configuration
-     * undefined = means configuration will be removed
+     * null = means configuration will be removed
      **/
-    save(config: LangTagTranslationsConfig | undefined): void;
+    save(config: LangTagTranslationsConfig | null, triggerName?: string): void;
 }
 export interface LangTagCLICollectConfigFixEvent {
     config: LangTagTranslationsConfig;

package/index.cjs

@@ -447,35 +447,50 @@ async function checkAndRegenerateFileLangTags(config, logger, file, path$12) {
     return false;
   }
   const replacements = [];
+  let lastUpdatedLine = 0;
   for (let tag of tags) {
     let newConfig = void 0;
     let shouldUpdate = false;
     const frozenConfig = tag.parameterConfig ? deepFreezeObject(tag.parameterConfig) : tag.parameterConfig;
-    await config.onConfigGeneration({
+    const event = {
       langTagConfig: config,
       config: frozenConfig,
       absolutePath: file,
       relativePath: path$12,
       isImportedLibrary: path$12.startsWith(libraryImportsDir),
-      save: (updatedConfig) => {
-        newConfig = updatedConfig || null;
+      isSaved: false,
+      savedConfig: void 0,
+      save: (updatedConfig, triggerName) => {
+        if (!updatedConfig && updatedConfig !== null) throw new Error("Wrong config data");
+        newConfig = updatedConfig;
         shouldUpdate = true;
+        event.isSaved = true;
+        event.savedConfig = updatedConfig;
+        logger.debug('Called save for "{path}" with config "{config}" triggered by: ("{trigger}")', { path: path$12, config: JSON.stringify(updatedConfig), trigger: triggerName || "-" });
       }
-    });
+    };
+    await config.onConfigGeneration(event);
     if (!shouldUpdate) {
       continue;
     }
-    if (JSON5.stringify(tag.parameterConfig) !== JSON5.stringify(newConfig)) {
+    lastUpdatedLine = tag.line;
+    if (!isConfigSame(tag.parameterConfig, newConfig)) {
       replacements.push({ tag, config: newConfig });
     }
   }
   if (replacements.length) {
     const newContent = processor.replaceTags(fileContent, replacements);
     await promises.writeFile(file, newContent, "utf-8");
+    logger.info('Lang tag configurations written for file "{path}" (file://{file}:{line})', { path: path$12, file, line: lastUpdatedLine });
     return true;
   }
   return false;
 }
+function isConfigSame(c1, c2) {
+  if (!c1 && !c2) return true;
+  if (c1 && typeof c1 === "object" && c2 && typeof c2 === "object" && JSON5.stringify(c1) === JSON5.stringify(c2)) return true;
+  return false;
+}
 const CONFIG_FILE_NAME = ".lang-tag.config.js";
 const EXPORTS_FILE_NAME = ".lang-tag.exports.json";
 const LANG_TAG_DEFAULT_CONFIG = {
@@ -994,7 +1009,6 @@ async function $LT_CMD_RegenerateTags() {
     const path2 = file.substring(charactersToSkip);
     const localDirty = await checkAndRegenerateFileLangTags(config, logger, file, path2);
     if (localDirty) {
-      logger.info('Lang tag configurations written for file "{path}"', { path: path2 });
       dirty = true;
     }
   }
@@ -1395,10 +1409,7 @@ async function handleFile(config, logger, cwdRelativeFilePath, event) {
   }
   const cwd = process.cwd();
   const absoluteFilePath = path.join(cwd, cwdRelativeFilePath);
-  const dirty = await checkAndRegenerateFileLangTags(config, logger, absoluteFilePath, cwdRelativeFilePath);
-  if (dirty) {
-    logger.info(`Lang tag configurations written for file "{filePath}"`, { filePath: cwdRelativeFilePath });
-  }
+  await checkAndRegenerateFileLangTags(config, logger, absoluteFilePath, cwdRelativeFilePath);
   const files = await $LT_CollectCandidateFilesWithTags({ filesToScan: [cwdRelativeFilePath], config, logger });
   const namespaces = await $LT_GroupTagsToNamespaces({ logger, files, config });
   const changedNamespaces = await $LT_WriteToNamespaces({ config, namespaces, logger });
@@ -1428,7 +1439,7 @@ async function detectModuleSystem() {
 }
 async function generateDefaultConfig() {
   const moduleSystem = await detectModuleSystem();
-  const importStatement = moduleSystem === "esm" ? `import { pathBasedConfigGenerator } from '@lang-tag/cli/algorithms';` : `const { pathBasedConfigGenerator } = require('@lang-tag/cli/algorithms');`;
+  const importStatement = moduleSystem === "esm" ? `import { pathBasedConfigGenerator, configKeeper } from '@lang-tag/cli/algorithms';` : `const { pathBasedConfigGenerator, configKeeper } = require('@lang-tag/cli/algorithms');`;
   const exportStatement = moduleSystem === "esm" ? "export default config;" : "module.exports = config;";
   return `${importStatement}
 
@@ -1440,6 +1451,7 @@ const generationAlgorithm = pathBasedConfigGenerator({
     clearOnDefaultNamespace: true,
     ignoreDirectories: ['core', 'utils', 'helpers']
 });
+const keeper = configKeeper();
 
 /** @type {import('@lang-tag/cli/config').LangTagCLIConfig} */
 const config = {
@@ -1452,9 +1464,11 @@ const config = {
         // We do not modify imported configurations
         if (event.isImportedLibrary) return;
 
-        if (event.config?.manual) return;
+        if (event.config?.keep === 'both') return;
         
         await generationAlgorithm(event);
+        
+        await keeper(event);
     },
     collect: {
         defaultNamespace: 'common',

package/index.js

@@ -427,35 +427,50 @@ async function checkAndRegenerateFileLangTags(config, logger, file, path2) {
     return false;
   }
   const replacements = [];
+  let lastUpdatedLine = 0;
   for (let tag of tags) {
     let newConfig = void 0;
     let shouldUpdate = false;
     const frozenConfig = tag.parameterConfig ? deepFreezeObject(tag.parameterConfig) : tag.parameterConfig;
-    await config.onConfigGeneration({
+    const event = {
       langTagConfig: config,
       config: frozenConfig,
       absolutePath: file,
       relativePath: path2,
       isImportedLibrary: path2.startsWith(libraryImportsDir),
-      save: (updatedConfig) => {
-        newConfig = updatedConfig || null;
+      isSaved: false,
+      savedConfig: void 0,
+      save: (updatedConfig, triggerName) => {
+        if (!updatedConfig && updatedConfig !== null) throw new Error("Wrong config data");
+        newConfig = updatedConfig;
         shouldUpdate = true;
+        event.isSaved = true;
+        event.savedConfig = updatedConfig;
+        logger.debug('Called save for "{path}" with config "{config}" triggered by: ("{trigger}")', { path: path2, config: JSON.stringify(updatedConfig), trigger: triggerName || "-" });
       }
-    });
+    };
+    await config.onConfigGeneration(event);
     if (!shouldUpdate) {
       continue;
     }
-    if (JSON5.stringify(tag.parameterConfig) !== JSON5.stringify(newConfig)) {
+    lastUpdatedLine = tag.line;
+    if (!isConfigSame(tag.parameterConfig, newConfig)) {
       replacements.push({ tag, config: newConfig });
     }
   }
   if (replacements.length) {
     const newContent = processor.replaceTags(fileContent, replacements);
     await writeFile(file, newContent, "utf-8");
+    logger.info('Lang tag configurations written for file "{path}" (file://{file}:{line})', { path: path2, file, line: lastUpdatedLine });
     return true;
   }
   return false;
 }
+function isConfigSame(c1, c2) {
+  if (!c1 && !c2) return true;
+  if (c1 && typeof c1 === "object" && c2 && typeof c2 === "object" && JSON5.stringify(c1) === JSON5.stringify(c2)) return true;
+  return false;
+}
 const CONFIG_FILE_NAME = ".lang-tag.config.js";
 const EXPORTS_FILE_NAME = ".lang-tag.exports.json";
 const LANG_TAG_DEFAULT_CONFIG = {
@@ -974,7 +989,6 @@ async function $LT_CMD_RegenerateTags() {
     const path2 = file.substring(charactersToSkip);
     const localDirty = await checkAndRegenerateFileLangTags(config, logger, file, path2);
     if (localDirty) {
-      logger.info('Lang tag configurations written for file "{path}"', { path: path2 });
       dirty = true;
     }
   }
@@ -1375,10 +1389,7 @@ async function handleFile(config, logger, cwdRelativeFilePath, event) {
   }
   const cwd = process.cwd();
   const absoluteFilePath = path__default.join(cwd, cwdRelativeFilePath);
-  const dirty = await checkAndRegenerateFileLangTags(config, logger, absoluteFilePath, cwdRelativeFilePath);
-  if (dirty) {
-    logger.info(`Lang tag configurations written for file "{filePath}"`, { filePath: cwdRelativeFilePath });
-  }
+  await checkAndRegenerateFileLangTags(config, logger, absoluteFilePath, cwdRelativeFilePath);
   const files = await $LT_CollectCandidateFilesWithTags({ filesToScan: [cwdRelativeFilePath], config, logger });
   const namespaces = await $LT_GroupTagsToNamespaces({ logger, files, config });
   const changedNamespaces = await $LT_WriteToNamespaces({ config, namespaces, logger });
@@ -1408,7 +1419,7 @@ async function detectModuleSystem() {
 }
 async function generateDefaultConfig() {
   const moduleSystem = await detectModuleSystem();
-  const importStatement = moduleSystem === "esm" ? `import { pathBasedConfigGenerator } from '@lang-tag/cli/algorithms';` : `const { pathBasedConfigGenerator } = require('@lang-tag/cli/algorithms');`;
+  const importStatement = moduleSystem === "esm" ? `import { pathBasedConfigGenerator, configKeeper } from '@lang-tag/cli/algorithms';` : `const { pathBasedConfigGenerator, configKeeper } = require('@lang-tag/cli/algorithms');`;
   const exportStatement = moduleSystem === "esm" ? "export default config;" : "module.exports = config;";
   return `${importStatement}
 
@@ -1420,6 +1431,7 @@ const generationAlgorithm = pathBasedConfigGenerator({
     clearOnDefaultNamespace: true,
     ignoreDirectories: ['core', 'utils', 'helpers']
 });
+const keeper = configKeeper();
 
 /** @type {import('@lang-tag/cli/config').LangTagCLIConfig} */
 const config = {
@@ -1432,9 +1444,11 @@ const config = {
         // We do not modify imported configurations
         if (event.isImportedLibrary) return;
 
-        if (event.config?.manual) return;
+        if (event.config?.keep === 'both') return;
         
         await generationAlgorithm(event);
+        
+        await keeper(event);
     },
     collect: {
         defaultNamespace: 'common',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lang-tag/cli",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "type": "module",
   "publishConfig": {
     "access": "public"

package/template/base-app.mustache

@@ -13,9 +13,14 @@ import { createCallableTranslations } from 'lang-tag';
 import { ReactNode, useMemo } from 'react';
 {{/isReact}}
 
+{{#isTypeScript}}
+interface TagConfig extends LangTagTranslationsConfig {
+    keep?: 'namespace' | 'path' | 'both'
+}
+{{/isTypeScript}}
 export function {{tagName}}{{#isTypeScript}}<T extends LangTagTranslations>{{/isTypeScript}}(
     baseTranslations{{#isTypeScript}}: T{{/isTypeScript}},
-    config{{#isTypeScript}}?: LangTagTranslationsConfig{{/isTypeScript}},
+    config{{#isTypeScript}}?: TagConfig{{/isTypeScript}},
 ) {
     // Example integration with react-i18next:
     // const namespace = config?.namespace || '';

package/template/base-library.mustache

@@ -21,9 +21,14 @@ import {
 } from 'react';
 {{/isReact}}
 
+{{#isTypeScript}}
+interface TagConfig extends LangTagTranslationsConfig {
+    keep?: 'namespace' | 'path' | 'both'
+}
+{{/isTypeScript}}
 export function {{tagName}}<T extends LangTagTranslations>(
     baseTranslations: T,
-    config?: LangTagTranslationsConfig,
+    config?: TagConfig,
 ) {
     const createTranslationHelper = (normalized{{#isTypeScript}}: CallableTranslations<T> | null{{/isTypeScript}}) =>
         createCallableTranslations(baseTranslations, config, {