@mks2508/better-logger 1.0.0 → 1.2.0

package/src/utils/ansi-colors.ts

@@ -0,0 +1,333 @@
+/**
+ * @fileoverview ANSI color utilities for terminal environments
+ * @since 1.0.0
+ */
+
+import type { LogLevel } from '../types/index.js';
+import { supportsANSIColors } from './environment.js';
+
+/**
+ * ANSI color codes for terminal styling
+ */
+export const ANSI_CODES = {
+    // Colors
+    black: 30,
+    red: 31,
+    green: 32,
+    yellow: 33,
+    blue: 34,
+    magenta: 35,
+    cyan: 36,
+    white: 37,
+
+    // Bright colors
+    brightBlack: 90,
+    brightRed: 91,
+    brightGreen: 92,
+    brightYellow: 93,
+    brightBlue: 94,
+    brightMagenta: 95,
+    brightCyan: 96,
+    brightWhite: 97,
+
+    // Background colors
+    bgBlack: 40,
+    bgRed: 41,
+    bgGreen: 42,
+    bgYellow: 43,
+    bgBlue: 44,
+    bgMagenta: 45,
+    bgCyan: 46,
+    bgWhite: 47,
+
+    // Background bright colors
+    bgBrightBlack: 100,
+    bgBrightRed: 101,
+    bgBrightGreen: 102,
+    bgBrightYellow: 103,
+    bgBrightBlue: 104,
+    bgBrightMagenta: 105,
+    bgBrightCyan: 106,
+    bgBrightWhite: 107,
+
+    // Styles
+    reset: 0,
+    bold: 1,
+    dim: 2,
+    italic: 3,
+    underline: 4,
+    blink: 5,
+    inverse: 7,
+    hidden: 8,
+    strikethrough: 9,
+
+    // Reset specific
+    resetBold: 22,
+    resetDim: 22,
+    resetItalic: 23,
+    resetUnderline: 24,
+    resetBlink: 25,
+    resetInverse: 27,
+    resetHidden: 28,
+    resetStrikethrough: 29
+} as const;
+
+/**
+ * ANSI color presets for different log levels
+ */
+export const ANSI_LEVEL_STYLES: Record<LogLevel | 'success', {
+    color: number;
+    background?: number;
+    styles: number[];
+    emoji: string;
+}> = {
+    debug: {
+        color: ANSI_CODES.brightBlack,
+        styles: [ANSI_CODES.dim],
+        emoji: '🔍'
+    },
+    info: {
+        color: ANSI_CODES.blue,
+        styles: [ANSI_CODES.bold],
+        emoji: 'ℹ️'
+    },
+    warn: {
+        color: ANSI_CODES.yellow,
+        background: ANSI_CODES.bgYellow,
+        styles: [ANSI_CODES.bold, ANSI_CODES.black],
+        emoji: '⚠️'
+    },
+    error: {
+        color: ANSI_CODES.red,
+        background: ANSI_CODES.bgRed,
+        styles: [ANSI_CODES.bold],
+        emoji: '❌'
+    },
+    critical: {
+        color: ANSI_CODES.white,
+        background: ANSI_CODES.bgRed,
+        styles: [ANSI_CODES.bold, ANSI_CODES.blink],
+        emoji: '🚨'
+    },
+    success: {
+        color: ANSI_CODES.green,
+        background: ANSI_CODES.bgGreen,
+        styles: [ANSI_CODES.bold],
+        emoji: '✅'
+    }
+};
+
+/**
+ * Creates an ANSI escape sequence
+ */
+function ansi(code: number | number[]): string {
+    const codes = Array.isArray(code) ? code : [code];
+    return `\x1b[${codes.join(';')}m`;
+}
+
+/**
+ * Applies ANSI styling to text
+ */
+export function ansiStyle(text: string, codes: number[]): string {
+    if (!supportsANSIColors()) return text;
+    return `${ansi(codes)}${text}${ansi(ANSI_CODES.reset)}`;
+}
+
+/**
+ * Applies color to text
+ */
+export function ansiColor(text: string, color: number): string {
+    return ansiStyle(text, [color]);
+}
+
+/**
+ * Applies background color to text
+ */
+export function ansiBackground(text: string, bg: number, color?: number): string {
+    if (color) {
+        return ansiStyle(text, [color, bg]);
+    }
+    return ansiStyle(text, [bg]);
+}
+
+/**
+ * Makes text bold
+ */
+export function ansiBold(text: string): string {
+    return ansiStyle(text, [ANSI_CODES.bold]);
+}
+
+/**
+ * Makes text dim
+ */
+export function ansiDim(text: string): string {
+    return ansiStyle(text, [ANSI_CODES.dim]);
+}
+
+/**
+ * Underlines text
+ */
+export function ansiUnderline(text: string): string {
+    return ansiStyle(text, [ANSI_CODES.underline]);
+}
+
+/**
+ * Specialized formatters for different contexts
+ */
+
+/**
+ * Format timestamp for terminal
+ */
+export function formatTimestampANSI(timestamp: string): string {
+    return ansiColor(timestamp, ANSI_CODES.brightBlack);
+}
+
+/**
+ * Format log level for terminal
+ */
+export function formatLogLevelANSI(level: LogLevel, useEmojis: boolean = true): string {
+    const style = ANSI_LEVEL_STYLES[level];
+    const emoji = useEmojis ? style.emoji : '';
+    const label = level.toUpperCase().padEnd(8);
+
+    if (!supportsANSIColors()) {
+        return `${emoji} ${label}`;
+    }
+
+    let codes = [style.color, ...style.styles];
+    if (style.background) {
+        codes.push(style.background);
+    }
+
+    return ansiStyle(`${emoji} ${label}`, codes);
+}
+
+/**
+ * Format success message for terminal
+ */
+export function formatSuccessANSI(message: string, useEmojis: boolean = true): string {
+    const style = ANSI_LEVEL_STYLES.success;
+    const emoji = useEmojis ? style.emoji : '';
+
+    if (!supportsANSIColors()) {
+        return `${emoji} SUCCESS: ${message}`;
+    }
+
+    const prefix = ansiStyle(`${emoji} SUCCESS:`, [style.color, ...style.styles]);
+    return `${prefix} ${message}`;
+}
+
+/**
+ * Format prefix for terminal
+ */
+export function formatPrefixANSI(prefix: string): string {
+    if (!supportsANSIColors()) {
+        return `[${prefix}]`;
+    }
+
+    return ansiStyle(`[${prefix}]`, [ANSI_CODES.cyan, ANSI_CODES.bold]);
+}
+
+/**
+ * Format file location for terminal
+ */
+export function formatLocationANSI(location: string): string {
+    if (!supportsANSIColors()) {
+        return `(${location})`;
+    }
+
+    return ansiColor(`(${location})`, ANSI_CODES.brightBlack);
+}
+
+/**
+ * Format build-specific messages
+ */
+export const BUILD_FORMATTERS = {
+    /**
+     * Format compilation step
+     */
+    compilation: (step: string, status: 'starting' | 'completed' | 'failed' = 'starting') => {
+        const stepText = ansiBold(step);
+
+        switch (status) {
+            case 'starting':
+                return `${ansiColor('⚙️', ANSI_CODES.blue)} ${stepText}...`;
+            case 'completed':
+                return `${ansiColor('✓', ANSI_CODES.green)} ${stepText} ${ansiColor('completed', ANSI_CODES.green)}`;
+            case 'failed':
+                return `${ansiColor('✗', ANSI_CODES.red)} ${stepText} ${ansiColor('failed', ANSI_CODES.red)}`;
+            default:
+                return stepText;
+        }
+    },
+
+    /**
+     * Format warning message
+     */
+    warning: (message: string) => {
+        return `${ansiColor('⚠', ANSI_CODES.yellow)} ${ansiStyle('Warning:', [ANSI_CODES.yellow, ANSI_CODES.bold])} ${message}`;
+    },
+
+    /**
+     * Format error message
+     */
+    error: (message: string) => {
+        return `${ansiColor('✗', ANSI_CODES.red)} ${ansiStyle('Error:', [ANSI_CODES.red, ANSI_CODES.bold])} ${message}`;
+    },
+
+    /**
+     * Format success message
+     */
+    success: (message: string) => {
+        return `${ansiColor('✓', ANSI_CODES.green)} ${ansiColor(message, ANSI_CODES.green)}`;
+    },
+
+    /**
+     * Format info message
+     */
+    info: (message: string) => {
+        return `${ansiColor('ℹ', ANSI_CODES.blue)} ${message}`;
+    }
+};
+
+/**
+ * Terminal-friendly emoji alternatives for environments that don't support them
+ */
+export const EMOJI_ALTERNATIVES = {
+    '🔍': '[DEBUG]',
+    'ℹ️': '[INFO]',
+    '⚠️': '[WARN]',
+    '❌': '[ERROR]',
+    '🚨': '[CRITICAL]',
+    '✅': '[OK]',
+    '✓': '[OK]',
+    '✗': '[FAIL]',
+    '⚙️': '[BUILD]',
+    '📦': '[PKG]'
+};
+
+/**
+ * Replace emojis with text alternatives for non-emoji terminals
+ */
+export function sanitizeEmojis(text: string): string {
+    // Check if we're in a terminal that likely supports emojis
+    const isModernTerminal = process.env.TERM &&
+        (process.env.TERM.includes('xterm') ||
+         process.env.TERM.includes('screen') ||
+         process.env.TERM.includes('tmux'));
+
+    const isCI = process.env.CI || process.env.GITHUB_ACTIONS || process.env.JENKINS_URL;
+
+    // Use emojis if we have a modern terminal and not in CI
+    if (isModernTerminal && !isCI) {
+        return text;
+    }
+
+    // Replace emojis with text alternatives
+    let result = text;
+    Object.entries(EMOJI_ALTERNATIVES).forEach(([emoji, alt]) => {
+        result = result.replace(new RegExp(emoji, 'g'), alt);
+    });
+
+    return result;
+}

package/src/utils/environment-detector.ts

@@ -0,0 +1,148 @@
+/**
+ * Environment Detector - Robust environment detection for logger
+ * Detects browser, terminal, server, and other runtime environments
+ */
+
+export type Environment = 'browser' | 'terminal' | 'server' | 'webworker' | 'deno' | 'unknown';
+
+/**
+ * Main environment detection function
+ */
+export function getEnvironment(): Environment {
+    // Check for Deno first
+    if (typeof globalThis !== 'undefined' && (globalThis as any).Deno) {
+        return 'deno';
+    }
+
+    // Check for WebWorker
+    if (typeof window === 'undefined' && typeof self !== 'undefined' && typeof (self as any).importScripts === 'function') {
+        return 'webworker';
+    }
+
+    // Check for Node.js (server environment)
+    if (typeof process !== 'undefined' && process.versions && process.versions.node) {
+        // Determine if it's running in a terminal or as a server
+        if (isRunningInTerminal()) {
+            return 'terminal';
+        }
+        return 'server';
+    }
+
+    // Check for browser
+    if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+        return 'browser';
+    }
+
+    return 'unknown';
+}
+
+/**
+ * Check if running in an interactive terminal
+ */
+export function isRunningInTerminal(): boolean {
+    // Check for common terminal indicators
+    if (typeof process === 'undefined') return false;
+
+    const isTTY = process.stdout && process.stdout.isTTY;
+    const hasTerminalEnv = process.env && (
+        process.env.TERM ||
+        process.env.TERM_PROGRAM ||
+        process.env.SSH_TTY ||
+        process.env.TERM_SESSION_ID
+    );
+
+    // Check if we're running in common terminal programs
+    const terminalPrograms = [
+        'vscode',
+        'hyper',
+        'iterm',
+        'terminal',
+        'alacritty',
+        'kitty',
+        'gnome-terminal',
+        'konsole',
+        'xterm',
+        'tmux',
+        'screen'
+    ];
+
+    const isTerminalProgram = hasTerminalEnv && terminalPrograms.some(program =>
+        process.env.TERM_PROGRAM?.toLowerCase().includes(program) ||
+        process.env.TERM?.toLowerCase().includes(program)
+    );
+
+    return Boolean(isTTY || hasTerminalEnv || isTerminalProgram);
+}
+
+/**
+ * Check if environment supports ANSI colors
+ */
+export function supportsANSI(): boolean {
+    const env = getEnvironment();
+
+    if (env === 'browser') return false;
+    if (env === 'terminal') return true;
+    if (env === 'server') return checkServerANSISupport();
+
+    return false;
+}
+
+/**
+ * Check if server environment supports ANSI colors
+ */
+function checkServerANSISupport(): boolean {
+    if (typeof process === 'undefined') return false;
+
+    // Check common environment variables that indicate ANSI support
+    const supportsANSI = process.env && (
+        process.env.COLORTERM ||
+        process.env.FORCE_COLOR ||
+        (process.env.TERM && process.env.TERM !== 'dumb') ||
+        process.env.TERM_PROGRAM
+    );
+
+    return Boolean(supportsANSI);
+}
+
+/**
+ * Get environment-specific color capability
+ */
+export function getColorCapability(): 'full' | 'basic' | 'none' {
+    const env = getEnvironment();
+
+    if (env === 'browser') {
+        return 'full'; // CSS colors
+    }
+
+    if (!supportsANSI()) {
+        return 'none';
+    }
+
+    // Check for 256-color or truecolor support
+    if (typeof process !== 'undefined' && process.env) {
+        const hasTrueColor = process.env.COLORTERM === 'truecolor' || process.env.COLORTERM === '24bit';
+        const has256Colors = process.env.TERM && process.env.TERM.includes('256');
+
+        if (hasTrueColor || has256Colors) {
+            return 'full';
+        }
+    }
+
+    return 'basic'; // Basic 16 colors
+}
+
+/**
+ * Environment information for debugging
+ */
+export function getEnvironmentInfo() {
+    return {
+        environment: getEnvironment(),
+        supportsANSI: supportsANSI(),
+        colorCapability: getColorCapability(),
+        isTTY: typeof process !== 'undefined' ? Boolean(process.stdout?.isTTY) : false,
+        platform: typeof process !== 'undefined' ? process.platform : 'unknown',
+        nodeVersion: typeof process !== 'undefined' ? process.versions?.node : null,
+        term: typeof process !== 'undefined' ? process.env?.TERM : null,
+        colorTerm: typeof process !== 'undefined' ? process.env?.COLORTERM : null
+    };
+}

package/src/utils/formatting.ts

@@ -2,8 +2,45 @@
  * @fileoverview Formatting utilities for Universal Logger
  */
 
-import type { LogLevel, StackInfo } from '../types/index.js';
+import type { LogLevel, StackInfo, OutputFormat } from '../types/index.js';
 import { formatTimestamp } from './timestamps.js';
+import { isNode, supportsANSIColors } from './environment.js';
+import {
+    formatLogLevelANSI,
+    formatTimestampANSI,
+    formatPrefixANSI,
+    formatLocationANSI,
+    sanitizeEmojis,
+    BUILD_FORMATTERS
+} from './ansi-colors.js';
+
+// Re-export the type for convenience
+export type { OutputFormat } from '../types/index.js';
+
+/**
+ * Creates output based on environment and format preference
+ */
+export function createOutput(
+    level: LogLevel,
+    message: string,
+    prefix?: string,
+    stackInfo?: StackInfo | null,
+    format: OutputFormat = 'auto'
+): string {
+    const detectedFormat = format === 'auto' ? detectOptimalFormat() : format;
+
+    switch (detectedFormat) {
+        case 'ansi':
+            return createANSIOutput(level, message, prefix, stackInfo);
+        case 'build':
+            return createBuildOutput(level, message, prefix, stackInfo);
+        case 'ci':
+            return createCIOutput(level, message, prefix, stackInfo);
+        case 'plain':
+        default:
+            return createPlainOutput(level, message, prefix, stackInfo);
+    }
+}
 
 /**
  * Creates plain text output for any environment
@@ -17,22 +54,175 @@ export function createPlainOutput(
 ): string {
     const timestamp = formatTimestamp();
     const timeStr = timestamp.slice(11, 23); // HH:MM:SS.mmm
-    
+
     let output = `[${timeStr}] [${level.toUpperCase()}]`;
-    
+
     if (prefix) {
         output += ` [${prefix}]`;
     }
-    
+
     output += ` ${message}`;
-    
+
     if (stackInfo) {
         output += ` (${stackInfo.file}:${stackInfo.line}:${stackInfo.column})`;
     }
-    
+
     return output;
 }
 
+/**
+ * Creates ANSI-colored output for terminals
+ */
+export function createANSIOutput(
+    level: LogLevel,
+    message: string,
+    prefix?: string,
+    stackInfo?: StackInfo | null
+): string {
+    const timestamp = formatTimestamp();
+    const timeStr = timestamp.slice(11, 23);
+
+    let output = '';
+
+    // Timestamp
+    output += formatTimestampANSI(`[${timeStr}]`) + ' ';
+
+    // Log level with colors
+    output += formatLogLevelANSI(level) + ' ';
+
+    // Prefix if provided
+    if (prefix) {
+        output += formatPrefixANSI(prefix) + ' ';
+    }
+
+    // Message
+    output += message;
+
+    // Stack info if provided
+    if (stackInfo) {
+        output += ' ' + formatLocationANSI(`(${stackInfo.file}:${stackInfo.line}:${stackInfo.column})`);
+    }
+
+    return sanitizeEmojis(output);
+}
+
+/**
+ * Creates build-friendly output (optimized for Next.js builds, webpack, etc.)
+ */
+export function createBuildOutput(
+    level: LogLevel,
+    message: string,
+    prefix?: string,
+    stackInfo?: StackInfo | null
+): string {
+    const timestamp = formatTimestamp();
+    const timeStr = timestamp.slice(11, 23);
+
+    let output = '';
+
+    // Use ANSI colors if supported
+    if (supportsANSIColors()) {
+        output += formatTimestampANSI(`[${timeStr}]`) + ' ';
+
+        // Use build-specific formatters
+        switch (level) {
+            case 'info':
+                output += BUILD_FORMATTERS.info(message);
+                break;
+            case 'warn':
+                output += BUILD_FORMATTERS.warning(message);
+                break;
+            case 'error':
+            case 'critical':
+                output += BUILD_FORMATTERS.error(message);
+                break;
+            default:
+                output += `${formatLogLevelANSI(level)} ${message}`;
+        }
+    } else {
+        // Fallback to plain text
+        output = `[${timeStr}] [${level.toUpperCase()}]`;
+
+        if (prefix) {
+            output += ` [${prefix}]`;
+        }
+
+        output += ` ${message}`;
+    }
+
+    if (stackInfo) {
+        output += ` (${stackInfo.file}:${stackInfo.line}:${stackInfo.column})`;
+    }
+
+    return sanitizeEmojis(output);
+}
+
+/**
+ * Creates CI-friendly output (no emojis, simple formatting)
+ */
+export function createCIOutput(
+    level: LogLevel,
+    message: string,
+    prefix?: string,
+    stackInfo?: StackInfo | null
+): string {
+    const timestamp = formatTimestamp();
+    const timeStr = timestamp.slice(11, 23);
+
+    let output = `[${timeStr}] [${level.toUpperCase()}]`;
+
+    if (prefix) {
+        output += ` [${prefix}]`;
+    }
+
+    output += ` ${message}`;
+
+    if (stackInfo) {
+        output += ` (${stackInfo.file}:${stackInfo.line}:${stackInfo.column})`;
+    }
+
+    // Always remove emojis for CI
+    return sanitizeEmojis(output);
+}
+
+/**
+ * Detects the optimal output format based on environment
+ */
+export function detectOptimalFormat(): OutputFormat {
+    // Check for specific environment variables
+    const isCI = process.env.CI ||
+                 process.env.GITHUB_ACTIONS ||
+                 process.env.JENKINS_URL ||
+                 process.env.GITLAB_CI ||
+                 process.env.TRAVIS ||
+                 process.env.CIRCLECI;
+
+    const isBuild = process.env.NODE_ENV === 'production' ||
+                   process.env.BUILD_MODE === 'production' ||
+                   process.argv.some(arg => arg.includes('build') || arg.includes('webpack'));
+
+    const isNextJS = process.env.NEXT_RUNTIME ||
+                     process.argv.some(arg => arg.includes('next'));
+
+    // CI environment - always use plain text
+    if (isCI) {
+        return 'ci';
+    }
+
+    // Next.js build environment
+    if (isNextJS || isBuild) {
+        return 'build';
+    }
+
+    // Node.js with ANSI support
+    if (isNode && supportsANSIColors()) {
+        return 'ansi';
+    }
+
+    // Default to plain text
+    return 'plain';
+}
+
 /**
  * Gets the appropriate log method for the level
  * Uses different console methods for better semantics