i18nsmith 0.4.3 → 0.6.0

package/src/services/transform-service.ts

@@ -0,0 +1,203 @@
+/**
+ * @fileoverview
+ * CLI Transform Service - Implements ITransformService for CLI usage
+ * 
+ * This service wraps @i18nsmith/transformer's Transformer class and provides
+ * the ITransformService interface. It lives in CLI because:
+ * - @i18nsmith/core should NOT depend on @i18nsmith/transformer
+ * - CLI depends on both packages, making this the natural location
+ * 
+ * @module @i18nsmith/cli/services/transform-service
+ */
+
+import { Transformer } from '@i18nsmith/transformer';
+import type { TransformSummary, TransformRunOptions as TransformerRunOptions } from '@i18nsmith/transformer';
+import {
+  type I18nConfig,
+  type ITransformService,
+  type TransformOptions,
+  type TransformSummaryBase,
+  type ScanCandidate,
+  type Result,
+  type CoreError,
+  success,
+  failure,
+} from '@i18nsmith/core';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Configuration for the CLI transform service.
+ */
+export interface CliTransformServiceConfig {
+  /** Workspace root directory */
+  readonly workspaceRoot: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helper Functions
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Converts a TransformSummary to TransformSummaryBase.
+ * Maps the full candidate objects to the base type and includes optional display fields.
+ */
+function toSummaryBase(summary: TransformSummary): TransformSummaryBase {
+  return {
+    filesScanned: summary.filesScanned,
+    filesChanged: summary.filesChanged,
+    candidates: summary.candidates.map(c => ({
+      filePath: c.filePath,
+      position: c.position,
+      text: c.text,
+      kind: c.kind,
+      suggestedKey: c.suggestedKey,
+      status: c.status,
+      reason: c.reason,
+    })),
+    candidateStats: summary.candidateStats,
+    write: summary.write,
+    localeStats: summary.localeStats?.map(s => ({
+      locale: s.locale,
+      added: s.added,
+      updated: s.updated,
+      removed: s.removed,
+      totalKeys: s.totalKeys,
+    })),
+    skippedFiles: summary.skippedFiles,
+    skippedReasons: summary.skippedReasons,
+  };
+}
+
+/**
+ * Creates a CoreError for transform operations.
+ */
+function createTransformError(message: string, code: string = 'TRANSFORM_ERROR'): CoreError {
+  return {
+    code,
+    message,
+    category: 'internal',
+    severity: 'error',
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Service Implementation
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * CLI implementation of ITransformService.
+ * 
+ * Wraps the @i18nsmith/transformer Transformer class with the standard
+ * Result-based error handling pattern used across the service layer.
+ */
+export class CliTransformService implements ITransformService {
+  private readonly workspaceRoot: string;
+
+  constructor(config: CliTransformServiceConfig) {
+    this.workspaceRoot = config.workspaceRoot;
+  }
+
+  /**
+   * Transforms source files to use translation functions.
+   */
+  async transform(
+    config: I18nConfig,
+    options?: TransformOptions
+  ): Promise<Result<TransformSummaryBase>> {
+    try {
+      const transformer = new Transformer(config, {
+        workspaceRoot: options?.workspaceRoot ?? this.workspaceRoot,
+        keyNamespace: options?.keyNamespace,
+      });
+
+      const runOptions: TransformerRunOptions = {
+        write: options?.write ?? false,
+        targets: options?.targets ? [...options.targets] : undefined,
+        diff: options?.diff ?? false,
+        migrateTextKeys: options?.migrateTextKeys ?? false,
+        onProgress: options?.onProgress,
+      };
+
+      const summary = await transformer.run(runOptions);
+      return success(toSummaryBase(summary));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return failure(createTransformError(`Transform failed: ${message}`));
+    }
+  }
+
+  /**
+   * Transforms specific candidates (from a previous scan).
+   * 
+   * Note: The current Transformer doesn't have a direct method for this,
+   * so we run a full transform with targets limited to the candidate files.
+   */
+  async transformCandidates(
+    config: I18nConfig,
+    candidates: readonly ScanCandidate[],
+    options?: TransformOptions
+  ): Promise<Result<TransformSummaryBase>> {
+    try {
+      // Extract unique file paths from candidates
+      const uniqueFiles = [...new Set(candidates.map(c => c.filePath))];
+
+      const transformer = new Transformer(config, {
+        workspaceRoot: options?.workspaceRoot ?? this.workspaceRoot,
+        keyNamespace: options?.keyNamespace,
+      });
+
+      const runOptions: TransformerRunOptions = {
+        write: options?.write ?? false,
+        targets: uniqueFiles,
+        diff: options?.diff ?? false,
+        migrateTextKeys: options?.migrateTextKeys ?? false,
+        onProgress: options?.onProgress,
+      };
+
+      const summary = await transformer.run(runOptions);
+      return success(toSummaryBase(summary));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return failure(createTransformError(`Transform candidates failed: ${message}`));
+    }
+  }
+
+  /**
+   * Generates a preview of transformation without applying.
+   */
+  async preview(
+    config: I18nConfig,
+    options?: Omit<TransformOptions, 'write'>
+  ): Promise<Result<TransformSummaryBase>> {
+    return this.transform(config, { ...options, write: false });
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory Function
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Creates a CLI transform service instance.
+ * 
+ * @param workspaceRoot - The workspace root directory
+ * @returns ITransformService instance
+ * 
+ * @example
+ * ```typescript
+ * import { getTransformService } from '../services/transform-service.js';
+ * 
+ * const transformService = getTransformService(projectRoot);
+ * const result = await transformService.transform(config, { write: true });
+ * 
+ * if (!result.success) {
+ *   throw new CliError(result.error.message);
+ * }
+ * ```
+ */
+export function getTransformService(workspaceRoot: string): ITransformService {
+  return new CliTransformService({ workspaceRoot });
+}

package/src/utils/bootstrap.ts

@@ -0,0 +1,221 @@
+/**
+ * @fileoverview
+ * CLI Bootstrap - Service Container Setup for CLI
+ * 
+ * This module provides a pre-configured ServiceContainer with Node.js
+ * platform adapters. CLI commands can import this to use the service layer.
+ * 
+ * Following Hexagonal Architecture:
+ * - The ServiceContainer is the "Application Layer"
+ * - This bootstrap module configures "Adapters" for CLI (Node.js) environment
+ * 
+ * @example
+ * ```typescript
+ * import { getServiceContainer } from '../utils/bootstrap.js';
+ * 
+ * async function myCommand() {
+ *   const container = getServiceContainer();
+ *   const result = await container.scanner.scan(config);
+ *   // ...
+ * }
+ * ```
+ * 
+ * @module @i18nsmith/cli/utils/bootstrap
+ */
+
+import chalk from 'chalk';
+import {
+  ServiceContainer,
+  createServiceContainer,
+  NodeFileSystem,
+  NodeLoggerFactory,
+  type ServiceContainerConfig,
+  type PlatformAdapters,
+} from '@i18nsmith/core';
+import type { ILogger, LogLevel, ILoggerFactory } from '@i18nsmith/core';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CLI Logger Adapter
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * CLI-specific logger that outputs with chalk formatting.
+ */
+class CliLogger implements ILogger {
+  private currentLevel: LogLevel;
+  private readonly scope: string;
+  private readonly levelOrder: Record<LogLevel, number> = {
+    trace: 0,
+    debug: 1,
+    info: 2,
+    warn: 3,
+    error: 4,
+  };
+
+  constructor(scope: string = 'CLI', level: LogLevel = 'info') {
+    this.scope = scope;
+    this.currentLevel = level;
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    return this.levelOrder[level] >= this.levelOrder[this.currentLevel];
+  }
+
+  trace(message: string, data?: Record<string, unknown>): void {
+    if (this.shouldLog('trace')) {
+      console.log(chalk.gray(`[${this.scope}] ${message}`), data ? data : '');
+    }
+  }
+
+  debug(message: string, data?: Record<string, unknown>): void {
+    if (this.shouldLog('debug')) {
+      console.log(chalk.gray(`[${this.scope}] ${message}`), data ? data : '');
+    }
+  }
+
+  info(message: string, data?: Record<string, unknown>): void {
+    if (this.shouldLog('info')) {
+      console.log(chalk.blue(`[${this.scope}] ${message}`), data ? data : '');
+    }
+  }
+
+  warn(message: string, data?: Record<string, unknown>): void {
+    if (this.shouldLog('warn')) {
+      console.warn(chalk.yellow(`[${this.scope}] ⚠ ${message}`), data ? data : '');
+    }
+  }
+
+  error(message: string, error?: Error, data?: Record<string, unknown>): void {
+    if (this.shouldLog('error')) {
+      console.error(chalk.red(`[${this.scope}] ✖ ${message}`));
+      if (error?.stack) {
+        console.error(chalk.gray(error.stack));
+      }
+      if (data) {
+        console.error(chalk.gray(JSON.stringify(data, null, 2)));
+      }
+    }
+  }
+
+  child(scope: string): ILogger {
+    return new CliLogger(`${this.scope}:${scope}`, this.currentLevel);
+  }
+
+  getLevel(): LogLevel {
+    return this.currentLevel;
+  }
+
+  setLevel(level: LogLevel): void {
+    this.currentLevel = level;
+  }
+}
+
+/**
+ * Factory for creating CLI loggers.
+ */
+class CliLoggerFactory implements ILoggerFactory {
+  private readonly level: LogLevel;
+  private readonly rootLogger: CliLogger;
+
+  constructor(level: LogLevel = 'info') {
+    this.level = level;
+    this.rootLogger = new CliLogger('CLI', level);
+  }
+
+  createLogger(scope: string): ILogger {
+    return new CliLogger(scope, this.level);
+  }
+
+  getRootLogger(): ILogger {
+    return this.rootLogger;
+  }
+
+  setGlobalLevel(level: LogLevel): void {
+    this.rootLogger.setLevel(level);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Service Container Management
+// ─────────────────────────────────────────────────────────────────────────────
+
+let globalContainer: ServiceContainer | null = null;
+let globalLogLevel: LogLevel = 'warn'; // CLI defaults to quiet
+
+/**
+ * Sets the global log level for CLI operations.
+ */
+export function setLogLevel(level: LogLevel): void {
+  globalLogLevel = level;
+  if (globalContainer) {
+    // Reset container to re-create with new log level
+    globalContainer = null;
+  }
+}
+
+/**
+ * Creates platform adapters for CLI environment.
+ */
+function createCliAdapters(): PlatformAdapters {
+  return {
+    fileSystem: new NodeFileSystem(),
+    loggerFactory: new CliLoggerFactory(globalLogLevel),
+  };
+}
+
+/**
+ * Gets the global service container, creating it if needed.
+ * 
+ * @param options - Optional configuration overrides
+ * @returns Configured ServiceContainer
+ */
+export function getServiceContainer(options?: {
+  workspaceRoot?: string;
+  logLevel?: LogLevel;
+}): ServiceContainer {
+  if (options?.logLevel) {
+    globalLogLevel = options.logLevel;
+  }
+
+  const workspaceRoot = options?.workspaceRoot ?? process.cwd();
+
+  // Create new container if needed or if workspaceRoot changed
+  if (!globalContainer || globalContainer.workspaceRoot !== workspaceRoot) {
+    globalContainer = createServiceContainer({
+      workspaceRoot,
+      adapters: createCliAdapters(),
+    });
+  }
+
+  return globalContainer;
+}
+
+/**
+ * Creates a fresh service container (useful for testing or scoped operations).
+ * 
+ * @param config - Container configuration
+ * @returns New ServiceContainer instance
+ */
+export function createCliServiceContainer(config?: ServiceContainerConfig): ServiceContainer {
+  return createServiceContainer({
+    workspaceRoot: config?.workspaceRoot ?? process.cwd(),
+    adapters: {
+      ...createCliAdapters(),
+      ...config?.adapters,
+    },
+  });
+}
+
+/**
+ * Resets the global container (useful for testing).
+ */
+export function resetServiceContainer(): void {
+  globalContainer = null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Utility Exports
+// ─────────────────────────────────────────────────────────────────────────────
+
+export { CliLogger, CliLoggerFactory };
+export type { LogLevel };