@lang-tag/cli 0.14.0 → 0.16.0

package/algorithms/case-utils.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Available case transformation types supported by the case library.
+ */
+export type CaseType = 'no' | 'camel' | 'capital' | 'constant' | 'dot' | 'header' | 'kebab' | 'lower' | 'param' | 'pascal' | 'path' | 'sentence' | 'snake' | 'swap' | 'title' | 'upper';
+/**
+ * Applies case transformation to a string using the case library.
+ *
+ * @param str - The string to transform
+ * @param caseType - The case transformation type
+ * @returns The transformed string
+ */
+export declare function applyCaseTransform(str: string, caseType: CaseType): string;

package/algorithms/collector/dictionary-collector.d.ts

@@ -0,0 +1,17 @@
+import { TranslationsCollector } from './type.ts';
+import { LangTagCLIProcessedTag } from '../../config.ts';
+interface Options {
+    appendNamespaceToPath: boolean;
+}
+export declare class DictionaryCollector extends TranslationsCollector {
+    private readonly options;
+    private clean;
+    constructor(options?: Options);
+    aggregateCollection(namespace: string): string;
+    transformTag(tag: LangTagCLIProcessedTag): LangTagCLIProcessedTag;
+    preWrite(clean: boolean): Promise<void>;
+    resolveCollectionFilePath(baseLanguageCode: string): Promise<any>;
+    onMissingCollection(baseLanguageCode: string): Promise<void>;
+    postWrite(changedCollections: string[]): Promise<void>;
+}
+export {};

package/algorithms/collector/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Translation collectors for organizing translation tags into output files.
+ *
+ * These collectors define how translation tags are grouped and written to files
+ * during the collection process. Each collector implements a different strategy
+ * for organizing translations (e.g., single dictionary vs. namespace-based files).
+ */
+export { DictionaryCollector } from './dictionary-collector.ts';
+export { NamespaceCollector } from './namespace-collector.ts';
+export { type TranslationsCollector } from './type.ts';

package/algorithms/collector/namespace-collector.d.ts

@@ -0,0 +1,12 @@
+import { TranslationsCollector } from './type.ts';
+import { LangTagCLIProcessedTag } from '../../config.ts';
+export declare class NamespaceCollector extends TranslationsCollector {
+    private clean;
+    private languageDirectory;
+    aggregateCollection(namespace: string): string;
+    transformTag(tag: LangTagCLIProcessedTag): LangTagCLIProcessedTag;
+    preWrite(clean: boolean): Promise<void>;
+    resolveCollectionFilePath(collectionName: string): Promise<any>;
+    onMissingCollection(collectionName: string): Promise<void>;
+    postWrite(changedCollections: string[]): Promise<void>;
+}

package/algorithms/collector/type.d.ts

@@ -0,0 +1,12 @@
+import { LangTagCLIConfig, LangTagCLIProcessedTag } from '../../config.ts';
+import { LangTagCLILogger } from '../../logger.ts';
+export declare abstract class TranslationsCollector {
+    config: LangTagCLIConfig;
+    logger: LangTagCLILogger;
+    abstract aggregateCollection(namespace: string): string;
+    abstract transformTag(tag: LangTagCLIProcessedTag): LangTagCLIProcessedTag;
+    abstract preWrite(clean?: boolean): Promise<void>;
+    abstract resolveCollectionFilePath(collectionName: string): Promise<string>;
+    abstract onMissingCollection(collectionName: string): Promise<void>;
+    abstract postWrite(changedCollections: string[]): Promise<void>;
+}

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

@@ -6,3 +6,4 @@
  */
 export { pathBasedConfigGenerator, type PathBasedConfigGeneratorOptions } from './path-based-config-generator.ts';
 export { configKeeper, type ConfigKeeperOptions, type ConfigKeeperMode } from './config-keeper.ts';
+export { prependNamespaceToPath, type PrependNamespaceToPathOptions } from './prepend-namespace-to-path.ts';

package/algorithms/config-generation/path-based-config-generator.d.ts

@@ -1,4 +1,5 @@
 import { LangTagCLIConfigGenerationEvent } from '../../config.ts';
+import { CaseType } from '../case-utils';
 export interface PathBasedConfigGeneratorOptions {
     /**
      * Whether to include the filename (without extension) as part of the path segments.
@@ -120,14 +121,14 @@ export interface PathBasedConfigGeneratorOptions {
      * 'lower', 'no', 'param', 'pascal', 'path', 'sentence', 'snake', 'swap', 'title', 'upper'
      * @default undefined (no transformation)
      */
-    namespaceCase?: 'camel' | 'capital' | 'constant' | 'dot' | 'header' | 'kebab' | 'lower' | 'no' | 'param' | 'pascal' | 'path' | 'sentence' | 'snake' | 'swap' | 'title' | 'upper';
+    namespaceCase?: CaseType;
     /**
      * Case transformation to apply to the path segments.
      * Available options: 'camel', 'capital', 'constant', 'dot', 'header', 'kebab',
      * 'lower', 'no', 'param', 'pascal', 'path', 'sentence', 'snake', 'swap', 'title', 'upper'
      * @default undefined (no transformation)
      */
-    pathCase?: 'camel' | 'capital' | 'constant' | 'dot' | 'header' | 'kebab' | 'lower' | 'no' | 'param' | 'pascal' | 'path' | 'sentence' | 'snake' | 'swap' | 'title' | 'upper';
+    pathCase?: CaseType;
     /**
      * Fallback namespace to use when no segments remain after filtering.
      * Defaults to the defaultNamespace from langTagConfig.collect.defaultNamespace if not provided.

package/algorithms/config-generation/prepend-namespace-to-path.d.ts

@@ -0,0 +1,28 @@
+import { LangTagCLIConfigGenerationEvent } from '../../config.ts';
+/**
+ * Options for the prependNamespaceToPath algorithm.
+ */
+export interface PrependNamespaceToPathOptions {
+}
+/**
+ * Algorithm that prepends the namespace to the path in translation tag configurations.
+ *
+ * This is useful when you want to flatten the namespace structure by moving the namespace
+ * into the path, effectively removing the namespace separation.
+ *
+ * @example
+ * ```typescript
+ * // Before: { namespace: 'common', path: 'hello.world' }
+ * // After:  { path: 'common.hello.world' }
+ *
+ * // Before: { namespace: 'common' }
+ * // After:  { path: 'common' }
+ *
+ * // Before: {}
+ * // After:  { path: 'common' }
+ * ```
+ *
+ * @param options Configuration options for the algorithm
+ * @returns A function compatible with LangTagCLIConfigGenerationEvent
+ */
+export declare function prependNamespaceToPath(options?: PrependNamespaceToPathOptions): (event: LangTagCLIConfigGenerationEvent) => Promise<void>;

package/algorithms/import/flexible-import-algorithm.d.ts

@@ -0,0 +1,232 @@
+import { LangTagCLIImportEvent } from '../../config.ts';
+import { CaseType } from '../case-utils';
+/**
+ * Available case transformation options for variable names.
+ * Only includes transformations that produce valid JavaScript identifiers.
+ */
+export type VariableNameCaseType = 'no' | 'camel' | 'capital' | 'constant' | 'lower' | 'pascal' | 'snake' | 'swap' | 'upper';
+/**
+ * Case transformation configuration for file paths.
+ * Can be a string for uniform case transformation, or an object with separate
+ * case transformations for directories and files.
+ */
+export type FilePathCaseType = CaseType | {
+    directories?: CaseType;
+    files?: CaseType;
+};
+export interface VariableNameOptions {
+    /**
+     * Whether to prefix variable names with package name to avoid conflicts.
+     * @default false
+     */
+    prefixWithPackageName?: boolean;
+    /**
+     * How to handle scoped package names (e.g., '@scope/package').
+     * - 'remove-scope': Remove @scope/ part, keep only package name
+     * - 'replace': Remove @ and replace / with underscores
+     * @default 'replace'
+     */
+    scopedPackageHandling?: 'remove-scope' | 'replace';
+    /**
+     * Case transformation to apply to variable names.
+     * Available options: 'camel', 'capital', 'constant', 'lower', 'no', 'pascal', 'snake', 'swap', 'upper'
+     * @default 'no'
+     */
+    case?: VariableNameCaseType;
+    /**
+     * Whether to sanitize variable names by replacing invalid characters with $.
+     * This ensures the final variable name is a valid JavaScript identifier.
+     * @default true
+     */
+    sanitizeVariableName?: boolean;
+    /**
+     * How to handle tags without variableName.
+     * - 'skip': Skip tags without variableName
+     * - 'auto-generate': Generate names like 'translations1', 'translations2', etc. (default)
+     * - Function: Custom function to generate variable names
+     * @default 'auto-generate'
+     */
+    handleMissingVariableName?: 'skip' | 'auto-generate' | ((tag: any, packageName: string, fileName: string, index: number) => string);
+    /**
+     * Custom function to generate variable names, completely overriding original names from export.
+     * When provided, this function will be used instead of the original variableName from the export.
+     *
+     * Note: The returned custom name will still be processed by all other transformations
+     * (case transformation, sanitization, prefixWithPackageName, etc.).
+     *
+     * @param context - Context information about the import
+     * @returns The custom variable name, or null to fall back to original naming logic
+     *
+     * @example
+     * ```typescript
+     * customVariableName: (context) => {
+     *   // Generate names based on package and file structure
+     *   const packagePrefix = context.packageName.replace('@company/', '').replace('-', '');
+     *   const fileBase = context.fileName.split('/').pop()?.replace('.ts', '') || 'unknown';
+     *   return `${packagePrefix}_${fileBase}_${context.tagIndex + 1}`;
+     *   // This will still be processed by case transformation, sanitization, etc.
+     * }
+     * ```
+     */
+    customVariableName?: (context: {
+        packageName: string;
+        fileName: string;
+        originalVariableName: string | undefined;
+        tagIndex: number;
+        tag: any;
+    }) => string | null;
+}
+export interface FilePathOptions {
+    /**
+     * Whether to group all translations from each package into a single file.
+     * If false, preserves the original file structure from the library.
+     * @default false
+     */
+    groupByPackage?: boolean;
+    /**
+     * Whether to include package name in the file path.
+     * @default false
+     */
+    includePackageInPath?: boolean;
+    /**
+     * How to handle scoped package names in file paths (e.g., '@scope/package').
+     * - 'remove-scope': Remove @scope/ part, keep only package name
+     * - 'replace': Remove @ and replace / with dashes
+     * @default 'replace'
+     */
+    scopedPackageHandling?: 'remove-scope' | 'replace';
+    /**
+     * Case transformation to apply to file names and path segments.
+     * Can be a string for uniform case transformation, or an object with separate
+     * case transformations for directories and files.
+     * Available options: 'camel', 'capital', 'constant', 'dot', 'header', 'kebab',
+     * 'lower', 'no', 'param', 'pascal', 'path', 'sentence', 'snake', 'swap', 'title', 'upper'
+     * @default 'no'
+     */
+    case?: FilePathCaseType;
+}
+export interface FlexibleImportAlgorithmOptions {
+    /**
+     * Options for controlling variable name generation.
+     */
+    variableName?: VariableNameOptions;
+    /**
+     * Options for controlling file path generation.
+     */
+    filePath?: FilePathOptions;
+    /**
+     * Inclusion rules for filtering imports.
+     * If undefined, all packages and namespaces are processed.
+     * If defined, only matching packages and namespaces are processed.
+     */
+    include?: {
+        /**
+         * List of package name patterns to include from import.
+         * Supports wildcards with * (e.g., '@company/*', 'ui-*')
+         * @default undefined (include all)
+         */
+        packages?: string[];
+        /**
+         * List of namespace patterns to include from import.
+         * Supports wildcards with * (e.g., 'ui.*', '*.common')
+         * @default undefined (include all)
+         */
+        namespaces?: string[];
+    };
+    /**
+     * Exclusion rules for filtering imports.
+     * Applied after inclusion rules.
+     */
+    exclude?: {
+        /**
+         * List of package name patterns to exclude from import.
+         * Supports wildcards with * (e.g., '@company/*', 'ui-*')
+         * @default []
+         */
+        packages?: string[];
+        /**
+         * List of namespace patterns to exclude from import.
+         * Supports wildcards with * (e.g., 'admin.*', '*.internal')
+         * @default []
+         */
+        namespaces?: string[];
+    };
+    /**
+     * Function to remap/override configs before saving imported tags.
+     * Allows modification of namespace, path, and other config properties
+     * based on package name, file path, or other context.
+     *
+     * @param originalConfig - The original config from the imported tag
+     * @param context - Context information about the import
+     * @returns The modified config object, or null to remove the config from the tag
+     *
+     * @example
+     * ```typescript
+     * configRemap: (config, context) => {
+     *   // Override namespace based on package name
+     *   if (context.packageName === 'ui-components') {
+     *     return { ...config, namespace: 'ui' };
+     *   }
+     *
+     *   // Remove config for certain packages (tag will be imported without config)
+     *   if (context.packageName === 'no-config-package') {
+     *     return null;
+     *   }
+     *
+     *   // Add prefix to all paths
+     *   if (config.path) {
+     *     return { ...config, path: `lib.${config.path}` };
+     *   }
+     *
+     *   return config;
+     * }
+     * ```
+     */
+    configRemap?: (originalConfig: any, context: {
+        packageName: string;
+        fileName: string;
+        variableName: string;
+        tagIndex: number;
+    }) => any | null;
+}
+/**
+ * Default import algorithm that imports translations from libraries.
+ *
+ * This algorithm provides flexible options for organizing imported translations
+ * while preserving the ability to customize the import process.
+ *
+ * @param options - Configuration options for the import algorithm
+ * @returns A function compatible with LangTagCLIConfig.import.onImport
+ *
+ * @example
+ * ```typescript
+ * import { flexibleImportAlgorithm } from '@lang-tag/cli/algorithms';
+ *
+ * export default {
+ *   import: {
+ *     onImport: flexibleImportAlgorithm({
+ *       variableName: {
+ *         prefixWithPackageName: true,
+ *         scopedPackageHandling: 'replace', // '@scope/package' -> 'scope_package'
+ *         case: 'camel', // 'scope_package_myVar' -> 'scopePackageMyVar'
+ *         handleMissingVariableName: 'auto-generate' // Generate 'translations1', 'translations2', etc.
+ *       },
+ *       filePath: {
+ *         groupByPackage: true,
+ *         scopedPackageHandling: 'remove-scope', // '@scope/package' -> 'package'
+ *         case: 'kebab' // 'package.ts' -> 'package.ts' (no change), 'my-file.ts' -> 'my-file.ts'
+ *       },
+ *       include: {
+ *         packages: ['@company/*', 'ui-*'],
+ *         namespaces: ['ui.*', '*.common']
+ *       },
+ *       exclude: {
+ *         packages: ['@company/internal-*'],
+ *         namespaces: ['admin.*', '*.internal']
+ *       }
+ *     })
+ *   }
+ * };
+ * ```
+ */
+export declare function flexibleImportAlgorithm(options?: FlexibleImportAlgorithmOptions): (event: LangTagCLIImportEvent) => void;

package/algorithms/import/index.d.ts

@@ -4,4 +4,5 @@
  * These algorithms customize how library translations are imported
  * and organized in your project.
  */
-export {};
+export { flexibleImportAlgorithm, type FlexibleImportAlgorithmOptions, type FilePathCaseType, type VariableNameCaseType } from './flexible-import-algorithm.ts';
+export { simpleMappingImportAlgorithm, type SimpleMappingImportAlgorithmOptions, type PackageMapping, type FileMapping } from './simple-mapping-import-algorithm.ts';

package/algorithms/import/simple-mapping-import-algorithm.d.ts

@@ -0,0 +1,120 @@
+import { LangTagCLIImportEvent } from '../../config.ts';
+/**
+ * Mapping for a specific file within a package.
+ * Defines which variables to import and optionally rename them.
+ */
+export interface FileMapping {
+    /**
+     * Source file path within the package
+     * @example 'components/button.ts'
+     */
+    sourceFile: string;
+    /**
+     * Target file path where variables should be imported
+     * @example 'ui/buttons.ts'
+     */
+    targetFile: string;
+    /**
+     * Map of variable names to import and their optional new names.
+     * If no new name is provided, the original name is used.
+     * @example { 'primaryButton': 'button', 'secondaryButton': 'secondary' }
+     */
+    variables: Record<string, string | undefined>;
+}
+/**
+ * Mapping for a specific package.
+ * Defines which files to import and how to map their variables.
+ */
+export interface PackageMapping {
+    /**
+     * Package name to match
+     * @example '@company/ui-components'
+     */
+    packageName: string;
+    /**
+     * Array of file mappings for this package
+     */
+    files: FileMapping[];
+}
+/**
+ * Options for the simple mapping import algorithm.
+ */
+export interface SimpleMappingImportAlgorithmOptions {
+    /**
+     * Array of package mappings defining how to import from each package
+     */
+    mappings: PackageMapping[];
+    /**
+     * Global config remapping function applied to all imported tags
+     */
+    configRemap?: (originalConfig: any, context: {
+        packageName: string;
+        sourceFile: string;
+        targetFile: string;
+        variableName: string;
+        originalVariableName: string;
+    }) => any | null;
+}
+/**
+ * Simple mapping import algorithm that provides straightforward control over
+ * how library translations are imported based on explicit package->file->variable mappings.
+ *
+ * This algorithm allows you to:
+ * - Specify exactly which packages to import from
+ * - Map specific files from packages to target files
+ * - Select which variables to import and optionally rename them
+ * - Skip packages/files/variables not explicitly mapped
+ *
+ * @param options - Configuration options for the simple mapping algorithm
+ * @returns A function compatible with LangTagCLIConfig.import.onImport
+ *
+ * @example
+ * ```typescript
+ * import { simpleMappingImportAlgorithm } from '@lang-tag/cli/algorithms';
+ *
+ * export default {
+ *   import: {
+ *     onImport: simpleMappingImportAlgorithm({
+ *       mappings: [
+ *         {
+ *           packageName: '@company/ui-components',
+ *           files: [
+ *             {
+ *               sourceFile: 'components/button.ts',
+ *               targetFile: 'ui/buttons.ts',
+ *               variables: {
+ *                 'primaryButton': 'button',
+ *                 'secondaryButton': 'secondary',
+ *                 'tertiaryButton': undefined // keep original name
+ *               }
+ *             },
+ *             {
+ *               sourceFile: 'components/input.ts',
+ *               targetFile: 'ui/inputs.ts',
+ *               variables: {
+ *                 'textInput': 'input',
+ *                 'passwordInput': 'password'
+ *               }
+ *             }
+ *           ]
+ *         },
+ *         {
+ *           packageName: '@company/utils',
+ *           files: [
+ *             {
+ *               sourceFile: 'helpers.ts',
+ *               targetFile: 'utils/helpers.ts',
+ *               variables: {
+ *                 'formatDate': undefined,
+ *                 'formatCurrency': 'currency'
+ *               }
+ *             }
+ *           ]
+ *         }
+ *       ]
+ *     })
+ *   }
+ * };
+ * ```
+ */
+export declare function simpleMappingImportAlgorithm(options: SimpleMappingImportAlgorithmOptions): (event: LangTagCLIImportEvent) => void;