@revealui/core 0.0.1-pre.0

package/dist/core/naming/UnifiedNaming.ts

@@ -0,0 +1,424 @@
+/**
+ * Unified Naming Convention System
+ *
+ * Standardizes all naming conventions across the codebase.
+ * Replaces inconsistent naming patterns across 100+ files.
+ */
+
+// ======
+// NAMING CONVENTIONS
+// ======
+
+export const NAMING_CONVENTIONS = {
+  // File naming
+  FILES: {
+    COMPONENTS: 'PascalCase', // UserProfile.tsx
+    SERVICES: 'PascalCase', // UserService.ts
+    UTILITIES: 'camelCase', // userUtils.ts
+    CONSTANTS: 'UPPER_SNAKE_CASE', // USER_ROLES.ts
+    TYPES: 'PascalCase', // UserTypes.ts
+    INTERFACES: 'PascalCase', // IUserService.ts
+    ENUMS: 'PascalCase', // UserRole.ts
+    CONFIGS: 'camelCase', // userConfig.ts
+    TESTS: 'camelCase', // userService.test.ts
+    STORIES: 'camelCase', // userProfile.stories.tsx
+  },
+
+  // Variable naming
+  VARIABLES: {
+    CAMEL_CASE: 'camelCase', // userName, userEmail
+    SNAKE_CASE: 'snake_case', // user_name, user_email
+    PASCAL_CASE: 'PascalCase', // UserName, UserEmail
+    UPPER_SNAKE_CASE: 'UPPER_SNAKE_CASE', // USER_NAME, USER_EMAIL
+  },
+
+  // Function naming
+  FUNCTIONS: {
+    CAMEL_CASE: 'camelCase', // getUserName, setUserEmail
+    PASCAL_CASE: 'PascalCase', // GetUserName, SetUserEmail
+    SNAKE_CASE: 'snake_case', // get_user_name, set_user_email
+  },
+
+  // Class naming
+  CLASSES: {
+    PASCAL_CASE: 'PascalCase', // UserService, UserRepository
+    SUFFIXES: {
+      SERVICE: 'Service', // UserService, PostService
+      REPOSITORY: 'Repository', // UserRepository, PostRepository
+      CONTROLLER: 'Controller', // UserController, PostController
+      MIDDLEWARE: 'Middleware', // AuthMiddleware, LoggingMiddleware
+      ADAPTER: 'Adapter', // UserAdapter, PostAdapter
+      VALIDATOR: 'Validator', // UserValidator, PostValidator
+      UTILITY: 'Utils', // UserUtils, PostUtils
+      HELPER: 'Helper', // UserHelper, PostHelper
+    },
+  },
+
+  // Interface naming
+  INTERFACES: {
+    PREFIX: 'I', // IUserService, IPostRepository
+    PASCAL_CASE: 'PascalCase', // IUserService, IPostRepository
+  },
+
+  // Enum naming
+  ENUMS: {
+    PASCAL_CASE: 'PascalCase', // UserRole, PostStatus
+    VALUES: 'UPPER_SNAKE_CASE', // ADMIN, PUBLISHED
+  },
+
+  // Constant naming
+  CONSTANTS: {
+    UPPER_SNAKE_CASE: 'UPPER_SNAKE_CASE', // MAX_RETRY_ATTEMPTS
+    PREFIXES: {
+      MAX: 'MAX_', // MAX_RETRY_ATTEMPTS
+      MIN: 'MIN_', // MIN_PASSWORD_LENGTH
+      DEFAULT: 'DEFAULT_', // DEFAULT_PAGE_SIZE
+    },
+  },
+
+  // Event naming
+  EVENTS: {
+    PAST_TENSE: 'past_tense', // userCreated, postPublished
+    CAMEL_CASE: 'camelCase', // userCreated, postPublished
+  },
+
+  // Hook naming
+  HOOKS: {
+    PREFIX: 'use', // useUser, usePosts
+    CAMEL_CASE: 'camelCase', // useUser, usePosts
+  },
+
+  // Component naming
+  COMPONENTS: {
+    PASCAL_CASE: 'PascalCase', // UserProfile, PostCard
+    SUFFIXES: {
+      COMPONENT: 'Component', // UserProfileComponent
+      CONTAINER: 'Container', // UserProfileContainer
+      PRESENTATION: 'Presentation', // UserProfilePresentation
+    },
+  },
+
+  // Route naming
+  ROUTES: {
+    KEBAB_CASE: 'kebab-case', // user-profile, post-details
+    SLASH_SEPARATED: '/', // /user-profile, /post-details
+  },
+
+  // Database naming
+  DATABASE: {
+    TABLES: 'snake_case', // users, posts, user_posts
+    COLUMNS: 'snake_case', // user_id, created_at, updated_at
+    INDEXES: 'idx_', // idx_users_email, idx_posts_status
+    FOREIGN_KEYS: 'fk_', // fk_posts_user_id
+  },
+
+  // API naming
+  API: {
+    ENDPOINTS: 'kebab-case', // /user-profile, /post-details
+    QUERY_PARAMS: 'camelCase', // pageSize, sortBy
+    HEADERS: 'kebab-case', // x-api-key, x-user-id
+  },
+
+  // CSS naming
+  CSS: {
+    BEM: 'block__element--modifier', // user-profile__avatar--large
+    KEBAB_CASE: 'kebab-case', // user-profile, post-card
+  },
+
+  // Environment naming
+  ENVIRONMENT: {
+    UPPER_SNAKE_CASE: 'UPPER_SNAKE_CASE', // DATABASE_URL, API_KEY
+    PREFIXES: {
+      DATABASE: 'DATABASE_', // DATABASE_URL, DATABASE_HOST
+      API: 'API_', // API_KEY, API_SECRET
+      REDIS: 'REDIS_', // REDIS_URL, REDIS_HOST
+    },
+  },
+} as const;
+
+// ======
+// NAMING UTILITIES
+// ======
+
+// ======
+// CASE CONVERSION
+// ======
+
+export function toCamelCase(str: string): string {
+  return str
+    .replace(/(?:^\w|[A-Z]|\b\w)/g, (word, index) => {
+      return index === 0 ? word.toLowerCase() : word.toUpperCase();
+    })
+    .replace(/\s+/g, '');
+}
+
+export function toPascalCase(str: string): string {
+  return str.replace(/(?:^\w|[A-Z]|\b\w)/g, word => word.toUpperCase()).replace(/\s+/g, '');
+}
+
+export function toSnakeCase(str: string): string {
+  return str
+    .replace(/([A-Z])/g, '_$1')
+    .toLowerCase()
+    .replace(/^_/, '');
+}
+
+export function toKebabCase(str: string): string {
+  return str
+    .replace(/([A-Z])/g, '-$1')
+    .toLowerCase()
+    .replace(/^-/, '');
+}
+
+export function toUpperSnakeCase(str: string): string {
+  return toSnakeCase(str).toUpperCase();
+}
+
+// ======
+// VALIDATION
+// ======
+
+export function isValidCamelCase(str: string): boolean {
+  return /^[a-z][a-zA-Z0-9]*$/.test(str);
+}
+
+export function isValidPascalCase(str: string): boolean {
+  return /^[A-Z][a-zA-Z0-9]*$/.test(str);
+}
+
+export function isValidSnakeCase(str: string): boolean {
+  return /^[a-z][a-z0-9_]*[a-z0-9]$/.test(str);
+}
+
+export function isValidKebabCase(str: string): boolean {
+  return /^[a-z][a-z0-9-]*[a-z0-9]$/.test(str);
+}
+
+export function isValidUpperSnakeCase(str: string): boolean {
+  return /^[A-Z][A-Z0-9_]*[A-Z0-9]$/.test(str);
+}
+
+// ======
+// NORMALIZATION
+// ======
+
+export function normalize(str: string): string {
+  return str
+    .trim()
+    .replace(/\s+/g, ' ')
+    .replace(/[^\w\s-]/g, '');
+}
+
+export function sanitize(str: string): string {
+  return str.replace(/[^a-zA-Z0-9\s-_]/g, '').trim();
+}
+
+// ======
+// PREFIXES AND SUFFIXES
+// ======
+
+export function addPrefix(str: string, prefix: string): string {
+  return `${prefix}${toPascalCase(str)}`;
+}
+
+export function addSuffix(str: string, suffix: string): string {
+  return `${toPascalCase(str)}${suffix}`;
+}
+
+export function removePrefix(str: string, prefix: string): string {
+  return str.startsWith(prefix) ? str.slice(prefix.length) : str;
+}
+
+export function removeSuffix(str: string, suffix: string): string {
+  return str.endsWith(suffix) ? str.slice(0, -suffix.length) : str;
+}
+
+// ======
+// PLURALIZATION
+// ======
+
+export function pluralize(str: string): string {
+  if (str.endsWith('y')) {
+    return `${str.slice(0, -1)}ies`;
+  }
+  if (
+    str.endsWith('s') ||
+    str.endsWith('sh') ||
+    str.endsWith('ch') ||
+    str.endsWith('x') ||
+    str.endsWith('z')
+  ) {
+    return `${str}es`;
+  }
+  return `${str}s`;
+}
+
+export function singularize(str: string): string {
+  if (str.endsWith('ies')) {
+    return `${str.slice(0, -3)}y`;
+  }
+  if (str.endsWith('es') && str.length > 3) {
+    return str.slice(0, -2);
+  }
+  if (str.endsWith('s') && str.length > 1) {
+    return str.slice(0, -1);
+  }
+  return str;
+}
+
+// ======
+// SPECIFIC NAMING PATTERNS
+// ======
+
+export function toFileName(str: string, type: keyof typeof NAMING_CONVENTIONS.FILES): string {
+  const normalized = normalize(str);
+
+  switch (type) {
+    case 'COMPONENTS':
+    case 'SERVICES':
+    case 'TYPES':
+    case 'INTERFACES':
+    case 'ENUMS':
+      return toPascalCase(normalized);
+    case 'UTILITIES':
+    case 'CONFIGS':
+    case 'TESTS':
+    case 'STORIES':
+      return toCamelCase(normalized);
+    case 'CONSTANTS':
+      return toUpperSnakeCase(normalized);
+    default:
+      return normalized;
+  }
+}
+
+export function toVariableName(
+  str: string,
+  type: keyof typeof NAMING_CONVENTIONS.VARIABLES
+): string {
+  const normalized = normalize(str);
+
+  switch (type) {
+    case 'CAMEL_CASE':
+      return toCamelCase(normalized);
+    case 'SNAKE_CASE':
+      return toSnakeCase(normalized);
+    case 'PASCAL_CASE':
+      return toPascalCase(normalized);
+    case 'UPPER_SNAKE_CASE':
+      return toUpperSnakeCase(normalized);
+    default:
+      return normalized;
+  }
+}
+
+export function toFunctionName(
+  str: string,
+  type: keyof typeof NAMING_CONVENTIONS.FUNCTIONS
+): string {
+  const normalized = normalize(str);
+
+  switch (type) {
+    case 'CAMEL_CASE':
+      return toCamelCase(normalized);
+    case 'PASCAL_CASE':
+      return toPascalCase(normalized);
+    case 'SNAKE_CASE':
+      return toSnakeCase(normalized);
+    default:
+      return normalized;
+  }
+}
+
+export function toClassName(str: string, suffix?: string): string {
+  const normalized = normalize(str);
+  const pascalCase = toPascalCase(normalized);
+  return suffix ? addSuffix(pascalCase, suffix) : pascalCase;
+}
+
+export function toInterfaceName(str: string): string {
+  const normalized = normalize(str);
+  return addPrefix(toPascalCase(normalized), 'I');
+}
+
+export function toEnumName(str: string): string {
+  const normalized = normalize(str);
+  return toPascalCase(normalized);
+}
+
+export function toEnumValue(str: string): string {
+  const normalized = normalize(str);
+  return toUpperSnakeCase(normalized);
+}
+
+export function toConstantName(str: string, prefix?: string): string {
+  const normalized = normalize(str);
+  const upperSnakeCase = toUpperSnakeCase(normalized);
+  return prefix ? addPrefix(upperSnakeCase, prefix) : upperSnakeCase;
+}
+
+export function toEventName(str: string): string {
+  const normalized = normalize(str);
+  return toCamelCase(normalized);
+}
+
+export function toHookName(str: string): string {
+  const normalized = normalize(str);
+  return addPrefix(toCamelCase(normalized), 'use');
+}
+
+export function toComponentName(str: string, suffix?: string): string {
+  const normalized = normalize(str);
+  const pascalCase = toPascalCase(normalized);
+  return suffix ? addSuffix(pascalCase, suffix) : pascalCase;
+}
+
+export function toRouteName(str: string): string {
+  const normalized = normalize(str);
+  return toKebabCase(normalized);
+}
+
+export function toDatabaseName(str: string): string {
+  const normalized = normalize(str);
+  return toSnakeCase(normalized);
+}
+
+export function toApiEndpoint(str: string): string {
+  const normalized = normalize(str);
+  return toKebabCase(normalized);
+}
+
+export function toCssClass(
+  str: string,
+  block?: string,
+  element?: string,
+  modifier?: string
+): string {
+  const normalized = normalize(str);
+  const kebabCase = toKebabCase(normalized);
+
+  if (block && element && modifier) {
+    return `${block}__${element}--${modifier}`;
+  }
+  if (block && element) {
+    return `${block}__${element}`;
+  }
+  if (block) {
+    return block;
+  }
+
+  return kebabCase;
+}
+
+export function toEnvironmentVariable(str: string, prefix?: string): string {
+  const normalized = normalize(str);
+  const upperSnakeCase = toUpperSnakeCase(normalized);
+  return prefix ? addPrefix(upperSnakeCase, prefix) : upperSnakeCase;
+}
+
+// ======
+// EXPORTS
+// ======
+
+// All functions and constants are exported directly above - no re-export needed
+

package/dist/core/observability/logger.ts

@@ -0,0 +1,195 @@
+/**
+ * Structured Logging System
+ * Provides JSON-formatted logging with log levels, request ID tracking, and correlation IDs
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error"
+
+export interface LogContext {
+  requestId?: string
+  correlationId?: string
+  userId?: string
+  tenantId?: string
+  [key: string]: unknown
+}
+
+export interface LogEntry {
+  timestamp: string
+  level: LogLevel
+  message: string
+  context?: LogContext
+  error?: {
+    name: string
+    message: string
+    stack?: string
+  }
+}
+
+class StructuredLogger {
+  private minLevel: LogLevel = "info"
+  private requestId?: string
+  private correlationId?: string
+
+  /**
+   * Set the minimum log level
+   */
+  setMinLevel(level: LogLevel): void {
+    this.minLevel = level
+  }
+
+  /**
+   * Set request ID for request tracking
+   */
+  setRequestId(requestId: string): void {
+    this.requestId = requestId
+  }
+
+  /**
+   * Set correlation ID for distributed tracing
+   */
+  setCorrelationId(correlationId: string): void {
+    this.correlationId = correlationId
+  }
+
+  /**
+   * Create a log entry
+   */
+  private createLogEntry(
+    level: LogLevel,
+    message: string,
+    context?: LogContext,
+    error?: Error
+  ): LogEntry {
+    const entry: LogEntry = {
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+    }
+
+    if (context || this.requestId || this.correlationId) {
+      entry.context = {
+        ...context,
+        ...(this.requestId && { requestId: this.requestId }),
+        ...(this.correlationId && { correlationId: this.correlationId }),
+      }
+    }
+
+    if (error) {
+      entry.error = {
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      }
+    }
+
+    return entry
+  }
+
+  /**
+   * Output log entry to console (JSON format in production, formatted in development)
+   */
+  private output(entry: LogEntry): void {
+    if (process.env.NODE_ENV === "production") {
+      // Production: JSON format for log aggregation
+      console.log(JSON.stringify(entry))
+    } else {
+      // Development: Formatted output for readability
+      const prefix = `[${entry.timestamp}] [${entry.level.toUpperCase()}]`
+      console.log(prefix, entry.message)
+      if (entry.context) {
+        console.log("  Context:", entry.context)
+      }
+      if (entry.error) {
+        console.error("  Error:", entry.error)
+      }
+    }
+  }
+
+  /**
+   * Check if log level should be output
+   */
+  private shouldLog(level: LogLevel): boolean {
+    const levels: LogLevel[] = ["debug", "info", "warn", "error"]
+    return levels.indexOf(level) >= levels.indexOf(this.minLevel)
+  }
+
+  /**
+   * Log debug message
+   */
+  debug(message: string, context?: LogContext): void {
+    if (this.shouldLog("debug")) {
+      this.output(this.createLogEntry("debug", message, context))
+    }
+  }
+
+  /**
+   * Log info message
+   */
+  info(message: string, context?: LogContext): void {
+    if (this.shouldLog("info")) {
+      this.output(this.createLogEntry("info", message, context))
+    }
+  }
+
+  /**
+   * Log warning message
+   */
+  warn(message: string, context?: LogContext): void {
+    if (this.shouldLog("warn")) {
+      this.output(this.createLogEntry("warn", message, context))
+    }
+  }
+
+  /**
+   * Log error message
+   */
+  error(message: string, error?: Error, context?: LogContext): void {
+    if (this.shouldLog("error")) {
+      this.output(this.createLogEntry("error", message, context, error))
+    }
+  }
+
+  /**
+   * Create a child logger with additional context
+   */
+  child(context: LogContext): StructuredLogger {
+    const childLogger = new StructuredLogger()
+    childLogger.setMinLevel(this.minLevel)
+    const requestId = this.requestId || context.requestId
+    const correlationId = this.correlationId || context.correlationId
+    if (requestId) {
+      childLogger.setRequestId(requestId)
+    }
+    if (correlationId) {
+      childLogger.setCorrelationId(correlationId)
+    }
+    return childLogger
+  }
+}
+
+// Export singleton instance
+export const logger = new StructuredLogger()
+
+// Set log level from environment
+if (process.env.LOG_LEVEL) {
+  logger.setMinLevel(process.env.LOG_LEVEL as LogLevel)
+} else if (process.env.NODE_ENV === "production") {
+  logger.setMinLevel("info")
+} else {
+  logger.setMinLevel("debug")
+}
+
+/**
+ * Generate a unique request ID
+ */
+export function generateRequestId(): string {
+  return `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`
+}
+
+/**
+ * Generate a unique correlation ID
+ */
+export function generateCorrelationId(): string {
+  return `corr-${Date.now()}-${Math.random().toString(36).substring(2, 15)}`
+}
+