@enactprotocol/shared 1.2.13 → 2.0.0

package/src/utils/logger.ts

@@ -1,83 +1,294 @@
-// src/utils/logger.ts
-import pc from "picocolors";
-
-export enum LogLevel {
-	DEBUG = 0,
-	INFO = 1,
-	SUCCESS = 2,
-	WARN = 3,
-	ERROR = 4,
-}
-
-// Default log level
-let currentLogLevel = LogLevel.INFO;
-
 /**
- * Sets the current log level
+ * @enactprotocol/shared - Logger utility
+ *
+ * Provides structured logging with level filtering and
+ * configurable output formats (console with colors or JSON).
  */
-export function setLogLevel(level: LogLevel): void {
-	currentLogLevel = level;
+
+export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+
+export interface LogEntry {
+  timestamp: string;
+  level: LogLevel;
+  message: string;
+  context?: Record<string, unknown> | undefined;
 }
 
-/**
- * Debug log - only shown when log level is DEBUG
- */
-export function debug(message: string): void {
-	if (currentLogLevel <= LogLevel.DEBUG) {
-		console.error(pc.dim(`🔍 ${message}`));
-	}
+export interface LoggerOptions {
+  /** Minimum level to output */
+  level?: LogLevel;
+  /** Output format: 'console' for colored output, 'json' for structured */
+  format?: "console" | "json";
+  /** Enable colors in console output */
+  colors?: boolean;
+  /** Custom output function (defaults to console) */
+  output?: (text: string) => void;
+  /** Custom error output function (defaults to console.error) */
+  errorOutput?: (text: string) => void;
+  /** Prefix for log messages */
+  prefix?: string;
 }
 
+/** Level priorities (higher = more severe) */
+const LEVEL_PRIORITY: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  silent: 4,
+};
+
+/** ANSI color codes */
+const COLORS = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  bold: "\x1b[1m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m",
+  gray: "\x1b[90m",
+};
+
+/** Level display colors */
+const LEVEL_COLORS: Record<Exclude<LogLevel, "silent">, string> = {
+  debug: COLORS.gray,
+  info: COLORS.blue,
+  warn: COLORS.yellow,
+  error: COLORS.red,
+};
+
+/** Level labels for output */
+const LEVEL_LABELS: Record<Exclude<LogLevel, "silent">, string> = {
+  debug: "DEBUG",
+  info: "INFO",
+  warn: "WARN",
+  error: "ERROR",
+};
+
 /**
- * Info log - general information
+ * Logger class with level filtering and structured output
  */
-export function info(message: string): void {
-	if (currentLogLevel <= LogLevel.INFO) {
-		console.error(pc.blue(`ℹ️ ${message}`));
-	}
+export class Logger {
+  private level: LogLevel;
+  private format: "console" | "json";
+  private colors: boolean;
+  private output: (text: string) => void;
+  private errorOutput: (text: string) => void;
+  private prefix: string;
+
+  constructor(options: LoggerOptions = {}) {
+    this.level = options.level ?? "info";
+    this.format = options.format ?? "console";
+    this.colors = options.colors ?? true;
+    this.output = options.output ?? console.log;
+    this.errorOutput = options.errorOutput ?? console.error;
+    this.prefix = options.prefix ?? "";
+  }
+
+  /**
+   * Check if a level should be logged
+   */
+  shouldLog(level: LogLevel): boolean {
+    return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[this.level];
+  }
+
+  /**
+   * Set the minimum log level
+   */
+  setLevel(level: LogLevel): void {
+    this.level = level;
+  }
+
+  /**
+   * Get the current log level
+   */
+  getLevel(): LogLevel {
+    return this.level;
+  }
+
+  /**
+   * Set the output format
+   */
+  setFormat(format: "console" | "json"): void {
+    this.format = format;
+  }
+
+  /**
+   * Enable or disable colors
+   */
+  setColors(enabled: boolean): void {
+    this.colors = enabled;
+  }
+
+  /**
+   * Set the prefix for log messages
+   */
+  setPrefix(prefix: string): void {
+    this.prefix = prefix;
+  }
+
+  /**
+   * Create a child logger with a prefix
+   */
+  child(prefix: string): Logger {
+    const childPrefix = this.prefix ? `${this.prefix}:${prefix}` : prefix;
+    return new Logger({
+      level: this.level,
+      format: this.format,
+      colors: this.colors,
+      output: this.output,
+      errorOutput: this.errorOutput,
+      prefix: childPrefix,
+    });
+  }
+
+  /**
+   * Log a debug message
+   */
+  debug(message: string, context?: Record<string, unknown>): void {
+    this.log("debug", message, context);
+  }
+
+  /**
+   * Log an info message
+   */
+  info(message: string, context?: Record<string, unknown>): void {
+    this.log("info", message, context);
+  }
+
+  /**
+   * Log a warning message
+   */
+  warn(message: string, context?: Record<string, unknown>): void {
+    this.log("warn", message, context);
+  }
+
+  /**
+   * Log an error message
+   */
+  error(message: string, context?: Record<string, unknown>): void {
+    this.log("error", message, context);
+  }
+
+  /**
+   * Core logging method
+   */
+  private log(
+    level: Exclude<LogLevel, "silent">,
+    message: string,
+    context?: Record<string, unknown>
+  ): void {
+    if (!this.shouldLog(level)) {
+      return;
+    }
+
+    const entry: LogEntry = {
+      timestamp: new Date().toISOString(),
+      level,
+      message: this.prefix ? `[${this.prefix}] ${message}` : message,
+      context,
+    };
+
+    const formatted = this.format === "json" ? this.formatJson(entry) : this.formatConsole(entry);
+
+    // Use error output for warn/error levels
+    if (level === "warn" || level === "error") {
+      this.errorOutput(formatted);
+    } else {
+      this.output(formatted);
+    }
+  }
+
+  /**
+   * Format entry as JSON
+   */
+  private formatJson(entry: LogEntry): string {
+    const obj: Record<string, unknown> = {
+      timestamp: entry.timestamp,
+      level: entry.level,
+      message: entry.message,
+    };
+
+    if (entry.context && Object.keys(entry.context).length > 0) {
+      obj.context = entry.context;
+    }
+
+    return JSON.stringify(obj);
+  }
+
+  /**
+   * Format entry for console with colors
+   */
+  private formatConsole(entry: LogEntry): string {
+    const parts: string[] = [];
+
+    // Timestamp (dim)
+    if (this.colors) {
+      parts.push(`${COLORS.dim}${entry.timestamp}${COLORS.reset}`);
+    } else {
+      parts.push(entry.timestamp);
+    }
+
+    // Level label with color (only active levels, not silent)
+    const level = entry.level as Exclude<LogLevel, "silent">;
+    const label = LEVEL_LABELS[level];
+    if (this.colors) {
+      const color = LEVEL_COLORS[level];
+      parts.push(`${color}${label.padEnd(5)}${COLORS.reset}`);
+    } else {
+      parts.push(label.padEnd(5));
+    }
+
+    // Message
+    parts.push(entry.message);
+
+    // Context (if any)
+    if (entry.context && Object.keys(entry.context).length > 0) {
+      const contextStr = JSON.stringify(entry.context);
+      if (this.colors) {
+        parts.push(`${COLORS.dim}${contextStr}${COLORS.reset}`);
+      } else {
+        parts.push(contextStr);
+      }
+    }
+
+    return parts.join(" ");
+  }
 }
 
 /**
- * Success log - operation completed successfully
+ * Default logger instance
  */
-export function success(message: string): void {
-	if (currentLogLevel <= LogLevel.SUCCESS) {
-		console.error(pc.green(`✓ ${message}`));
-	}
-}
+let defaultLogger = new Logger();
 
 /**
- * Warning log - non-critical issues
+ * Get the default logger instance
  */
-export function warn(message: string): void {
-	if (currentLogLevel <= LogLevel.WARN) {
-		console.error(pc.yellow(`⚠️ ${message}`));
-	}
+export function getLogger(): Logger {
+  return defaultLogger;
 }
 
 /**
- * Error log - critical issues
+ * Configure the default logger
  */
-export function error(message: string, details?: any): void {
-	if (currentLogLevel <= LogLevel.ERROR) {
-		console.error(pc.red(`✗ Error: ${message}`));
-
-		if (details && currentLogLevel === LogLevel.DEBUG) {
-			console.error(pc.dim("Details:"));
-			console.error(details);
-		}
-	}
+export function configureLogger(options: LoggerOptions): void {
+  defaultLogger = new Logger(options);
 }
 
 /**
- * Table log - display tabular data
+ * Create a new logger with the given options
  */
-export function table(data: any[], columns?: string[]): void {
-	if (currentLogLevel <= LogLevel.INFO) {
-		if (columns) {
-			console.table(data, columns);
-		} else {
-			console.table(data);
-		}
-	}
+export function createLogger(options?: LoggerOptions): Logger {
+  return new Logger(options);
 }
+
+// Convenience exports for quick logging
+export const debug = (message: string, context?: Record<string, unknown>) =>
+  defaultLogger.debug(message, context);
+export const info = (message: string, context?: Record<string, unknown>) =>
+  defaultLogger.info(message, context);
+export const warn = (message: string, context?: Record<string, unknown>) =>
+  defaultLogger.warn(message, context);
+export const error = (message: string, context?: Record<string, unknown>) =>
+  defaultLogger.error(message, context);

package/src/utils/version.ts

@@ -1,37 +1,305 @@
-// src/utils/version.ts
-import pc from "picocolors";
-import { readFileSync } from "fs";
-import { join, dirname } from "path";
-import { fileURLToPath } from "url";
-
-/**
- * Displays the CLI version with nice formatting
- */
-export function showVersion(): void {
-	let version = "0.0.1-dev";
-	
-	try {
-		// Try to get version from environment first (for npm scripts)
-		if (process.env.npm_package_version) {
-			version = process.env.npm_package_version;
-		} else {
-			// When running as installed binary, read from package.json
-			// Go up from shared/dist/utils/version.js to find package.json
-			const currentFile = typeof __filename !== 'undefined' ? __filename : fileURLToPath(import.meta.url);
-			const sharedDir = dirname(dirname(dirname(currentFile)));
-			const packageJsonPath = join(sharedDir, 'package.json');
-			const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
-			version = packageJson.version;
-		}
-	} catch (error) {
-		// Fall back to default version if anything fails
-		version = "1.0.14";
-	}
-	
-	const versionText = `v${version}`;
-
-	console.error(`
-${pc.bold("Enact CLI")} ${pc.cyan(versionText)}
-${pc.dim("A tool to create and publish enact documents.")}
-`);
+/**
+ * @enactprotocol/shared - Version utilities
+ *
+ * Provides semver parsing, comparison, and range checking.
+ */
+
+export interface ParsedVersion {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease?: string | undefined;
+  build?: string | undefined;
+  raw: string;
+}
+
+export interface VersionRange {
+  operator: "=" | ">" | ">=" | "<" | "<=" | "^" | "~";
+  version: ParsedVersion;
+  raw: string;
+}
+
+/**
+ * Parse a semver version string
+ * Supports: 1.0.0, 1.0, 1, 1.0.0-alpha, 1.0.0+build, 1.0.0-alpha+build
+ */
+export function parseVersion(version: string): ParsedVersion | null {
+  const trimmed = version.trim();
+
+  // Remove leading 'v' if present (common in tags)
+  const normalized = trimmed.startsWith("v") ? trimmed.slice(1) : trimmed;
+
+  // Full semver regex with prerelease and build metadata
+  const semverRegex =
+    /^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([a-zA-Z0-9.-]+))?(?:\+([a-zA-Z0-9.-]+))?$/;
+  const match = normalized.match(semverRegex);
+
+  if (!match) {
+    return null;
+  }
+
+  const major = Number.parseInt(match[1] ?? "0", 10);
+  const minor = Number.parseInt(match[2] ?? "0", 10);
+  const patch = Number.parseInt(match[3] ?? "0", 10);
+
+  return {
+    major,
+    minor,
+    patch,
+    prerelease: match[4],
+    build: match[5],
+    raw: trimmed,
+  };
+}
+
+/**
+ * Check if a string is a valid semver version
+ */
+export function isValidVersion(version: string): boolean {
+  return parseVersion(version) !== null;
+}
+
+/**
+ * Compare two version strings
+ * @returns -1 if a < b, 0 if a === b, 1 if a > b
+ */
+export function compareVersions(a: string, b: string): -1 | 0 | 1 {
+  const parsedA = parseVersion(a);
+  const parsedB = parseVersion(b);
+
+  // Invalid versions sort last
+  if (!parsedA && !parsedB) return 0;
+  if (!parsedA) return 1;
+  if (!parsedB) return -1;
+
+  // Compare major.minor.patch
+  if (parsedA.major !== parsedB.major) {
+    return parsedA.major < parsedB.major ? -1 : 1;
+  }
+  if (parsedA.minor !== parsedB.minor) {
+    return parsedA.minor < parsedB.minor ? -1 : 1;
+  }
+  if (parsedA.patch !== parsedB.patch) {
+    return parsedA.patch < parsedB.patch ? -1 : 1;
+  }
+
+  // Prerelease comparison
+  // A version without prerelease is greater than one with
+  if (!parsedA.prerelease && parsedB.prerelease) return 1;
+  if (parsedA.prerelease && !parsedB.prerelease) return -1;
+
+  // Both have prereleases - compare lexically
+  if (parsedA.prerelease && parsedB.prerelease) {
+    const prereleaseCompare = comparePrerelease(parsedA.prerelease, parsedB.prerelease);
+    if (prereleaseCompare !== 0) return prereleaseCompare;
+  }
+
+  return 0;
+}
+
+/**
+ * Compare prerelease strings according to semver rules
+ */
+function comparePrerelease(a: string, b: string): -1 | 0 | 1 {
+  const partsA = a.split(".");
+  const partsB = b.split(".");
+
+  for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
+    const partA = partsA[i];
+    const partB = partsB[i];
+
+    // Shorter prerelease is less than longer
+    if (partA === undefined) return -1;
+    if (partB === undefined) return 1;
+
+    const numA = Number.parseInt(partA, 10);
+    const numB = Number.parseInt(partB, 10);
+
+    const isNumA = !Number.isNaN(numA) && String(numA) === partA;
+    const isNumB = !Number.isNaN(numB) && String(numB) === partB;
+
+    // Numeric identifiers are less than alphanumeric
+    if (isNumA && !isNumB) return -1;
+    if (!isNumA && isNumB) return 1;
+
+    // Both numeric - compare as numbers
+    if (isNumA && isNumB) {
+      if (numA < numB) return -1;
+      if (numA > numB) return 1;
+      continue;
+    }
+
+    // Both alphanumeric - compare lexically
+    if (partA < partB) return -1;
+    if (partA > partB) return 1;
+  }
+
+  return 0;
+}
+
+/**
+ * Parse a version range string
+ * Supports: =1.0.0, >1.0.0, >=1.0.0, <1.0.0, <=1.0.0, ^1.0.0, ~1.0.0
+ */
+export function parseRange(range: string): VersionRange | null {
+  const trimmed = range.trim();
+
+  // Match operator at start
+  const rangeRegex = /^([=><^~]+)?\s*(.+)$/;
+  const match = trimmed.match(rangeRegex);
+
+  if (!match || !match[2]) {
+    return null;
+  }
+
+  const operator = (match[1] ?? "=") as VersionRange["operator"];
+  const versionStr = match[2];
+
+  // Validate operator
+  if (!["=", ">", ">=", "<", "<=", "^", "~"].includes(operator)) {
+    return null;
+  }
+
+  const version = parseVersion(versionStr);
+  if (!version) {
+    return null;
+  }
+
+  return {
+    operator,
+    version,
+    raw: trimmed,
+  };
+}
+
+/**
+ * Check if a version satisfies a range
+ */
+export function satisfiesRange(version: string, range: string): boolean {
+  const parsedVersion = parseVersion(version);
+  const parsedRange = parseRange(range);
+
+  if (!parsedVersion || !parsedRange) {
+    return false;
+  }
+
+  const comparison = compareVersions(version, parsedRange.version.raw);
+
+  switch (parsedRange.operator) {
+    case "=":
+      return comparison === 0;
+    case ">":
+      return comparison === 1;
+    case ">=":
+      return comparison >= 0;
+    case "<":
+      return comparison === -1;
+    case "<=":
+      return comparison <= 0;
+    case "^":
+      // Caret range: compatible changes (same major, >= version)
+      // ^1.2.3 := >=1.2.3 <2.0.0
+      // ^0.2.3 := >=0.2.3 <0.3.0
+      // ^0.0.3 := >=0.0.3 <0.0.4
+      if (comparison === -1) return false;
+      if (parsedRange.version.major === 0) {
+        if (parsedRange.version.minor === 0) {
+          // ^0.0.x - must be exact patch
+          return parsedVersion.patch === parsedRange.version.patch;
+        }
+        // ^0.x - must be same minor
+        return parsedVersion.minor === parsedRange.version.minor;
+      }
+      // ^x - must be same major
+      return parsedVersion.major === parsedRange.version.major;
+    case "~":
+      // Tilde range: patch-level changes (same major.minor, >= version)
+      // ~1.2.3 := >=1.2.3 <1.3.0
+      if (comparison === -1) return false;
+      return (
+        parsedVersion.major === parsedRange.version.major &&
+        parsedVersion.minor === parsedRange.version.minor
+      );
+    default:
+      return false;
+  }
+}
+
+/**
+ * Sort versions in ascending order
+ */
+export function sortVersions(versions: string[]): string[] {
+  return [...versions].sort(compareVersions);
+}
+
+/**
+ * Get the highest version from a list
+ */
+export function getHighestVersion(versions: string[]): string | null {
+  const valid = versions.filter(isValidVersion);
+  if (valid.length === 0) return null;
+
+  const sorted = sortVersions(valid);
+  const last = sorted[sorted.length - 1];
+  return last ?? null;
+}
+
+/**
+ * Increment a version by bump type
+ */
+export function incrementVersion(
+  version: string,
+  bump: "major" | "minor" | "patch"
+): string | null {
+  const parsed = parseVersion(version);
+  if (!parsed) return null;
+
+  switch (bump) {
+    case "major":
+      return `${parsed.major + 1}.0.0`;
+    case "minor":
+      return `${parsed.major}.${parsed.minor + 1}.0`;
+    case "patch":
+      return `${parsed.major}.${parsed.minor}.${parsed.patch + 1}`;
+  }
+}
+
+/**
+ * Coerce a string to a valid semver, filling in missing parts
+ */
+export function coerceVersion(version: string): string | null {
+  const trimmed = version.trim();
+  const normalized = trimmed.startsWith("v") ? trimmed.slice(1) : trimmed;
+
+  // Try parsing as-is first
+  const parsed = parseVersion(normalized);
+  if (parsed) {
+    return `${parsed.major}.${parsed.minor}.${parsed.patch}`;
+  }
+
+  // Try extracting numbers
+  const numbers = normalized.match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  if (!numbers) {
+    return null;
+  }
+
+  const major = Number.parseInt(numbers[1] ?? "0", 10);
+  const minor = Number.parseInt(numbers[2] ?? "0", 10);
+  const patch = Number.parseInt(numbers[3] ?? "0", 10);
+
+  return `${major}.${minor}.${patch}`;
+}
+
+/**
+ * Format a parsed version back to string
+ */
+export function formatVersion(version: ParsedVersion): string {
+  let result = `${version.major}.${version.minor}.${version.patch}`;
+  if (version.prerelease) {
+    result += `-${version.prerelease}`;
+  }
+  if (version.build) {
+    result += `+${version.build}`;
+  }
+  return result;
 }