Merge pull request #873 from nissa-seru/create-logging-util

Implement logging utility

Author: mrubens

.clinerules

@@ -10,6 +10,13 @@
    - Prefer fixing the underlying issue over disabling the lint rule
    - Document any approved lint rule disabling with a comment explaining the reason
 
+3. Logging Guidelines:
+   - Always instrument code changes using the logger exported from `src\utils\logging\index.ts`.
+     - This will facilitate efficient debugging without impacting production (as the logger no-ops outside of a test environment.)
+   - Logs can be found in `logs\app.log`
+     - Logfile is overwritten on each run to keep it to a manageable volume.
+
+
 # Adding a New Setting
 
-To add a new setting that persists its state, follow the steps in cline_docs/settings.md
+To add a new setting that persists its state, follow the steps in cline_docs/settings.md

.gitignore

@@ -22,4 +22,9 @@ docs/_site/
 
 # Dotenv
 .env.integration
+
+#Local lint config
 .eslintrc.local.json
+
+#Logging
+logs

src/utils/logging/CompactLogger.ts

@@ -0,0 +1,150 @@
+/**
+ * @fileoverview Implementation of the compact logging system's main logger class
+ */
+
+import { ILogger, LogMeta, CompactLogEntry, LogLevel } from "./types"
+import { CompactTransport } from "./CompactTransport"
+
+/**
+ * Main logger implementation providing compact, efficient logging capabilities
+ * @implements {ILogger}
+ */
+export class CompactLogger implements ILogger {
+	private transport: CompactTransport
+	private parentMeta: LogMeta | undefined
+
+	/**
+	 * Creates a new CompactLogger instance
+	 * @param transport - Optional custom transport instance
+	 * @param parentMeta - Optional parent metadata for hierarchical logging
+	 */
+	constructor(transport?: CompactTransport, parentMeta?: LogMeta) {
+		this.transport = transport ?? new CompactTransport()
+		this.parentMeta = parentMeta
+	}
+
+	/**
+	 * Logs a debug level message
+	 * @param message - The message to log
+	 * @param meta - Optional metadata to include
+	 */
+	debug(message: string, meta?: LogMeta): void {
+		this.log("debug", message, this.combineMeta(meta))
+	}
+
+	/**
+	 * Logs an info level message
+	 * @param message - The message to log
+	 * @param meta - Optional metadata to include
+	 */
+	info(message: string, meta?: LogMeta): void {
+		this.log("info", message, this.combineMeta(meta))
+	}
+
+	/**
+	 * Logs a warning level message
+	 * @param message - The message to log
+	 * @param meta - Optional metadata to include
+	 */
+	warn(message: string, meta?: LogMeta): void {
+		this.log("warn", message, this.combineMeta(meta))
+	}
+
+	/**
+	 * Logs an error level message
+	 * @param message - The error message or Error object
+	 * @param meta - Optional metadata to include
+	 */
+	error(message: string | Error, meta?: LogMeta): void {
+		this.handleErrorLog("error", message, meta)
+	}
+
+	/**
+	 * Logs a fatal level message
+	 * @param message - The error message or Error object
+	 * @param meta - Optional metadata to include
+	 */
+	fatal(message: string | Error, meta?: LogMeta): void {
+		this.handleErrorLog("fatal", message, meta)
+	}
+
+	/**
+	 * Creates a child logger inheriting this logger's metadata
+	 * @param meta - Additional metadata for the child logger
+	 * @returns A new logger instance with combined metadata
+	 */
+	child(meta: LogMeta): ILogger {
+		const combinedMeta = this.parentMeta ? { ...this.parentMeta, ...meta } : meta
+		return new CompactLogger(this.transport, combinedMeta)
+	}
+
+	/**
+	 * Closes the logger and its transport
+	 */
+	close(): void {
+		this.transport.close()
+	}
+
+	/**
+	 * Handles logging of error and fatal messages with special error object processing
+	 * @private
+	 * @param level - The log level (error or fatal)
+	 * @param message - The message or Error object to log
+	 * @param meta - Optional metadata to include
+	 */
+	private handleErrorLog(level: "error" | "fatal", message: string | Error, meta?: LogMeta): void {
+		if (message instanceof Error) {
+			const errorMeta: LogMeta = {
+				...meta,
+				ctx: meta?.ctx ?? level,
+				error: {
+					name: message.name,
+					message: message.message,
+					stack: message.stack,
+				},
+			}
+			this.log(level, message.message, this.combineMeta(errorMeta))
+		} else {
+			this.log(level, message, this.combineMeta(meta))
+		}
+	}
+
+	/**
+	 * Combines parent and current metadata with proper context handling
+	 * @private
+	 * @param meta - The current metadata to combine with parent metadata
+	 * @returns Combined metadata or undefined if no metadata exists
+	 */
+	private combineMeta(meta?: LogMeta): LogMeta | undefined {
+		if (!this.parentMeta) {
+			return meta
+		}
+		if (!meta) {
+			return this.parentMeta
+		}
+		return {
+			...this.parentMeta,
+			...meta,
+			ctx: meta.ctx || this.parentMeta.ctx,
+		}
+	}
+
+	/**
+	 * Core logging function that processes and writes log entries
+	 * @private
+	 * @param level - The log level
+	 * @param message - The message to log
+	 * @param meta - Optional metadata to include
+	 */
+	private log(level: LogLevel, message: string, meta?: LogMeta): void {
+		const entry: CompactLogEntry = {
+			t: Date.now(),
+			l: level,
+			m: message,
+			c: meta?.ctx,
+			d: meta ? (({ ctx, ...rest }) => (Object.keys(rest).length > 0 ? rest : undefined))(meta) : undefined,
+		}
+
+		this.transport.write(entry)
+	}
+}

src/utils/logging/CompactTransport.ts

@@ -0,0 +1,122 @@
+/**
+ * @fileoverview Implementation of the compact logging transport system with file output capabilities
+ */
+
+import { writeFileSync, mkdirSync } from "fs"
+import { dirname } from "path"
+import { CompactTransportConfig, ICompactTransport, CompactLogEntry, LogLevel, LOG_LEVELS } from "./types"
+
+/**
+ * Default configuration for the transport
+ */
+const DEFAULT_CONFIG: CompactTransportConfig = {
+	level: "debug",
+	fileOutput: {
+		enabled: true,
+		path: "./logs/app.log",
+	},
+}
+
+/**
+ * Determines if a log entry should be processed based on configured minimum level
+ * @param configLevel - The minimum log level from configuration
+ * @param entryLevel - The level of the current log entry
+ * @returns Whether the entry should be processed
+ */
+function isLevelEnabled(configLevel: LogLevel, entryLevel: string): boolean {
+	const configIdx = LOG_LEVELS.indexOf(configLevel)
+	const entryIdx = LOG_LEVELS.indexOf(entryLevel as LogLevel)
+	return entryIdx >= configIdx
+}
+
+/**
+ * Implements the compact logging transport with file output support
+ * @implements {ICompactTransport}
+ */
+export class CompactTransport implements ICompactTransport {
+	private sessionStart: number
+	private lastTimestamp: number
+	private filePath?: string
+	private initialized: boolean = false
+
+	/**
+	 * Creates a new CompactTransport instance
+	 * @param config - Optional transport configuration
+	 */
+	constructor(readonly config: CompactTransportConfig = DEFAULT_CONFIG) {
+		this.sessionStart = Date.now()
+		this.lastTimestamp = this.sessionStart
+
+		if (config.fileOutput?.enabled) {
+			this.filePath = config.fileOutput.path
+		}
+	}
+
+	/**
+	 * Ensures the log file is initialized with proper directory structure and session start marker
+	 * @private
+	 * @throws {Error} If file initialization fails
+	 */
+	private ensureInitialized(): void {
+		if (this.initialized || !this.filePath) return
+
+		try {
+			mkdirSync(dirname(this.filePath), { recursive: true })
+			writeFileSync(this.filePath, "", { flag: "w" })
+
+			const sessionStart = {
+				t: 0,
+				l: "info",
+				m: "Log session started",
+				d: { timestamp: new Date(this.sessionStart).toISOString() },
+			}
+			writeFileSync(this.filePath, JSON.stringify(sessionStart) + "\n", { flag: "w" })
+
+			this.initialized = true
+		} catch (err) {
+			throw new Error(`Failed to initialize log file: ${(err as Error).message}`)
+		}
+	}
+
+	/**
+	 * Writes a log entry to configured outputs (console and/or file)
+	 * @param entry - The log entry to write
+	 */
+	write(entry: CompactLogEntry): void {
+		const deltaT = entry.t - this.lastTimestamp
+		this.lastTimestamp = entry.t
+
+		const compact = {
+			...entry,
+			t: deltaT,
+		}
+
+		const output = JSON.stringify(compact) + "\n"
+
+		// Write to console if level is enabled
+		if (this.config.level && isLevelEnabled(this.config.level, entry.l)) {
+			process.stdout.write(output)
+		}
+
+		// Write to file if enabled
+		if (this.filePath) {
+			this.ensureInitialized()
+			writeFileSync(this.filePath, output, { flag: "a" })
+		}
+	}
+
+	/**
+	 * Closes the transport and writes session end marker
+	 */
+	close(): void {
+		if (this.filePath && this.initialized) {
+			const sessionEnd = {
+				t: Date.now() - this.lastTimestamp,
+				l: "info",
+				m: "Log session ended",
+				d: { timestamp: new Date().toISOString() },
+			}
+			writeFileSync(this.filePath, JSON.stringify(sessionEnd) + "\n", { flag: "a" })
+		}
+	}
+}