Centralize log file and refactor desktop logging

- Migrate to `electron-log` v5.X.X, centralizing log files to adhere to
  best-practices.
- Add critical event logging in the log file.
- Replace `ElectronLog` type with `LogFunctions` for better abstraction.
- Unify log handling in `desktop-runtime-error` by removing
  `renderer.log` due to `electron-log` v5 changes.
- Update and extend logger interfaces, removing 'I' prefix and adding
  common log levels to abstract `electron-log` completely.
- Move logger interfaces to the application layer as it's cross-cutting
  concern, meanwhile keeping the implementations in the infrastructure
  layer.
- Introduce `useLogger` hook for easier logging in Vue components.
- Simplify `WindowVariables` by removing nullable properties.
- Improve documentation to clearly differentiate between desktop and web
  versions, outlining specific features of each.

tests/checks/desktop-runtime-errors/check-desktop-runtime-errors/app/app-logs.ts

@@ -5,33 +5,28 @@ import { exists } from '../utils/io';
 import { SupportedPlatform, CURRENT_PLATFORM } from '../utils/platform';
 import { getAppName } from '../utils/npm';
 
-const LOG_FILE_NAMES = ['main', 'renderer'];
-
 export async function clearAppLogFiles(
   projectDir: string,
 ): Promise<void> {
   if (!projectDir) { throw new Error('missing project directory'); }
-  await Promise.all(LOG_FILE_NAMES.map(async (logFileName) => {
-    const logPath = await determineLogPath(projectDir, logFileName);
-    if (!logPath || !await exists(logPath)) {
-      log(`Skipping clearing logs, log file does not exist: ${logPath}.`);
-      return;
-    }
-    try {
-      await unlink(logPath);
-      log(`Successfully cleared the log file at: ${logPath}.`);
-    } catch (error) {
-      die(`Failed to clear the log file at: ${logPath}. Reason: ${error}`);
-    }
-  }));
+  const logPath = await determineLogPath(projectDir);
+  if (!logPath || !await exists(logPath)) {
+    log(`Skipping clearing logs, log file does not exist: ${logPath}.`);
+    return;
+  }
+  try {
+    await unlink(logPath);
+    log(`Successfully cleared the log file at: ${logPath}.`);
+  } catch (error) {
+    die(`Failed to clear the log file at: ${logPath}. Reason: ${error}`);
+  }
 }
 
 export async function readAppLogFile(
   projectDir: string,
-  logFileName: string,
 ): Promise<AppLogFileResult> {
   if (!projectDir) { throw new Error('missing project directory'); }
-  const logPath = await determineLogPath(projectDir, logFileName);
+  const logPath = await determineLogPath(projectDir);
   if (!logPath || !await exists(logPath)) {
     log(`No log file at: ${logPath}`, LogLevel.Warn);
     return {
@@ -52,10 +47,9 @@ interface AppLogFileResult {
 
 async function determineLogPath(
   projectDir: string,
-  logFileName: string,
 ): Promise<string> {
   if (!projectDir) { throw new Error('missing project directory'); }
-  if (!LOG_FILE_NAMES.includes(logFileName)) { throw new Error(`unknown log file name: ${logFileName}`); }
+  const logFileName = 'main.log';
   const appName = await getAppName(projectDir);
   if (!appName) {
     return die('App name not found.');
@@ -67,19 +61,19 @@ async function determineLogPath(
       if (!process.env.HOME) {
         throw new Error('HOME environment variable is not defined');
       }
-      return join(process.env.HOME, 'Library', 'Logs', appName, `${logFileName}.log`);
+      return join(process.env.HOME, 'Library', 'Logs', appName, logFileName);
     },
     [SupportedPlatform.Linux]: () => {
       if (!process.env.HOME) {
         throw new Error('HOME environment variable is not defined');
       }
-      return join(process.env.HOME, '.config', appName, 'logs', `${logFileName}.log`);
+      return join(process.env.HOME, '.config', appName, 'logs', logFileName);
     },
     [SupportedPlatform.Windows]: () => {
       if (!process.env.USERPROFILE) {
         throw new Error('USERPROFILE environment variable is not defined');
       }
-      return join(process.env.USERPROFILE, 'AppData', 'Roaming', appName, 'logs', `${logFileName}.log`);
+      return join(process.env.USERPROFILE, 'AppData', 'Roaming', appName, 'logs', logFileName);
     },
   };
   const logFilePath = logFilePaths[CURRENT_PLATFORM]?.();

tests/checks/desktop-runtime-errors/check-desktop-runtime-errors/app/check-for-errors.ts

@@ -1,4 +1,4 @@
-import { splitTextIntoLines, indentText, filterEmpty } from '../utils/text';
+import { splitTextIntoLines, indentText } from '../utils/text';
 import { log, die } from '../utils/log';
 import { readAppLogFile } from './app-logs';
 import { STDERR_IGNORE_PATTERNS } from './error-ignore-patterns';
@@ -11,8 +11,6 @@ const EXPECTED_LOG_MARKERS = [
   '[APP_INIT]',
 ];
 
-type ProcessType = 'main' | 'renderer';
-
 export async function checkForErrors(
   stderr: string,
   windowTitles: readonly string[],
@@ -31,13 +29,11 @@ async function gatherErrors(
   projectDir: string,
 ): Promise<ExecutionError[]> {
   if (!projectDir) { throw new Error('missing project directory'); }
-  const { logFileContent: mainLogs, logFilePath: mainLogFile } = await readAppLogFile(projectDir, 'main');
-  const { logFileContent: rendererLogs, logFilePath: rendererLogFile } = await readAppLogFile(projectDir, 'renderer');
-  const allLogs = filterEmpty([mainLogs, rendererLogs, stderr]).join('\n');
+  const { logFileContent: mainLogs, logFilePath: mainLogFile } = await readAppLogFile(projectDir);
+  const allLogs = [mainLogs, stderr].filter(Boolean).join('\n');
   return [
     verifyStdErr(stderr),
-    verifyApplicationLogsExist('main', mainLogs, mainLogFile),
-    verifyApplicationLogsExist('renderer', rendererLogs, rendererLogFile),
+    verifyApplicationLogsExist(mainLogs, mainLogFile),
     ...EXPECTED_LOG_MARKERS.map(
       (marker) => verifyLogMarkerExistsInLogs(allLogs, marker),
     ),
@@ -72,13 +68,12 @@ function formatError(error: ExecutionError): string {
 }
 
 function verifyApplicationLogsExist(
-  processType: ProcessType,
   logContent: string | undefined,
   logFilePath: string,
 ): ExecutionError | undefined {
   if (!logContent?.length) {
     return describeError(
-      `Missing application (${processType}) logs`,
+      'Missing application logs',
       'Application logs are empty not were not found.'
         + `\nLog path: ${logFilePath}`,
     );

tests/unit/infrastructure/Log/ConsoleLogger.spec.ts

@@ -32,21 +32,6 @@ describe('ConsoleLogger', () => {
       expect(consoleMock.callHistory[0].args).to.deep.equal(expectedParams);
     });
   });
-  describe('throws if log function is missing', () => {
-    itEachLoggingMethod((functionName, testParameters) => {
-      // arrange
-      const expectedError = `missing "${functionName}" function`;
-      const consoleMock = {} as Partial<Console>;
-      consoleMock[functionName] = undefined;
-      const logger = new ConsoleLogger(consoleMock);
-
-      // act
-      const act = () => logger[functionName](...testParameters);
-
-      // assert
-      expect(act).to.throw(expectedError);
-    });
-  });
 });
 
 class MockConsole
@@ -58,4 +43,25 @@ class MockConsole
       args,
     });
   }
+
+  public warn(...args: unknown[]) {
+    this.registerMethodCall({
+      methodName: 'warn',
+      args,
+    });
+  }
+
+  public debug(...args: unknown[]) {
+    this.registerMethodCall({
+      methodName: 'debug',
+      args,
+    });
+  }
+
+  public error(...args: unknown[]) {
+    this.registerMethodCall({
+      methodName: 'error',
+      args,
+    });
+  }
 }

tests/unit/infrastructure/Log/ElectronLogger.spec.ts

@@ -1,42 +1,15 @@
 import { describe, expect } from 'vitest';
-import { ElectronLog } from 'electron-log';
 import { StubWithObservableMethodCalls } from '@tests/unit/shared/Stubs/StubWithObservableMethodCalls';
 import { createElectronLogger } from '@/infrastructure/Log/ElectronLogger';
-import { itEachAbsentObjectValue } from '@tests/unit/shared/TestCases/AbsentTests';
 import { itEachLoggingMethod } from './LoggerTestRunner';
+import type { LogFunctions } from 'electron-log';
 
 describe('ElectronLogger', () => {
-  describe('throws if logger is missing', () => {
-    itEachAbsentObjectValue((absentValue) => {
-      // arrange
-      const expectedError = 'missing logger';
-      const electronLog = absentValue as never;
-      // act
-      const act = () => createElectronLogger(electronLog);
-      // assert
-      expect(act).to.throw(expectedError);
-    }, { excludeUndefined: true });
-  });
-  describe('throws if log function is missing', () => {
-    itEachLoggingMethod((functionName, testParameters) => {
-      // arrange
-      const expectedError = `missing "${functionName}" function`;
-      const electronLogMock = {} as Partial<ElectronLog>;
-      electronLogMock[functionName] = undefined;
-      const logger = createElectronLogger(electronLogMock);
-
-      // act
-      const act = () => logger[functionName](...testParameters);
-
-      // assert
-      expect(act).to.throw(expectedError);
-    });
-  });
   describe('methods log the provided params', () => {
     itEachLoggingMethod((functionName, testParameters) => {
       // arrange
       const expectedParams = testParameters;
-      const electronLogMock = new MockElectronLog();
+      const electronLogMock = new ElectronLogStub();
       const logger = createElectronLogger(electronLogMock);
 
       // act
@@ -50,9 +23,51 @@ describe('ElectronLogger', () => {
   });
 });
 
-class MockElectronLog
-  extends StubWithObservableMethodCalls<ElectronLog>
-  implements Partial<ElectronLog> {
+class ElectronLogStub
+  extends StubWithObservableMethodCalls<LogFunctions>
+  implements LogFunctions {
+  public error(...args: unknown[]) {
+    this.registerMethodCall({
+      methodName: 'error',
+      args,
+    });
+  }
+
+  public warn(...args: unknown[]) {
+    this.registerMethodCall({
+      methodName: 'warn',
+      args,
+    });
+  }
+
+  public verbose(...args: unknown[]): void {
+    this.registerMethodCall({
+      methodName: 'verbose',
+      args,
+    });
+  }
+
+  public debug(...args: unknown[]) {
+    this.registerMethodCall({
+      methodName: 'debug',
+      args,
+    });
+  }
+
+  public silly(...args: unknown[]) {
+    this.registerMethodCall({
+      methodName: 'silly',
+      args,
+    });
+  }
+
+  public log(...args: unknown[]) {
+    this.registerMethodCall({
+      methodName: 'log',
+      args,
+    });
+  }
+
   public info(...args: unknown[]) {
     this.registerMethodCall({
       methodName: 'info',

tests/unit/infrastructure/Log/LoggerTestRunner.ts

@@ -1,23 +1,25 @@
 import { it } from 'vitest';
-import { FunctionKeys } from '@/TypeHelpers';
-import { ILogger } from '@/infrastructure/Log/ILogger';
-
-type TestParameters = [string, number, { some: string }];
+import { Logger } from '@/application/Common/Log/Logger';
 
 export function itEachLoggingMethod(
   handler: (
-    functionName: keyof ILogger,
-    testParameters: TestParameters,
+    functionName: keyof Logger,
+    testParameters: readonly unknown[]
   ) => void,
 ) {
-  const testParameters: TestParameters = ['test', 123, { some: 'object' }];
-  const loggerMethods: Array<FunctionKeys<ILogger>> = [
-    'info',
-  ];
-  loggerMethods
-    .forEach((functionKey) => {
+  const testScenarios: {
+    readonly [FunctionName in keyof Logger]: Parameters<Logger[FunctionName]>;
+  } = {
+    info: ['single-string'],
+    warn: ['with number', 123],
+    debug: ['with simple object', { some: 'object' }],
+    error: ['with error object', new Error('error')],
+  };
+
+  Object.entries(testScenarios)
+    .forEach(([functionKey, testParameters]) => {
       it(functionKey, () => {
-        handler(functionKey, testParameters);
+        handler(functionKey as keyof Logger, testParameters);
       });
     });
 }

tests/unit/infrastructure/Log/NoopLogger.spec.ts

@@ -1,6 +1,6 @@
 import { describe, expect } from 'vitest';
 import { NoopLogger } from '@/infrastructure/Log/NoopLogger';
-import { ILogger } from '@/infrastructure/Log/ILogger';
+import { Logger } from '@/application/Common/Log/Logger';
 import { itEachLoggingMethod } from './LoggerTestRunner';
 
 describe('NoopLogger', () => {
@@ -8,7 +8,7 @@ describe('NoopLogger', () => {
     itEachLoggingMethod((functionName, testParameters) => {
       // arrange
       const randomParams = testParameters;
-      const logger: ILogger = new NoopLogger();
+      const logger: Logger = new NoopLogger();
 
       // act
       const act = () => logger[functionName](...randomParams);

tests/unit/infrastructure/RuntimeEnvironment/WindowVariablesValidator.spec.ts

@@ -177,10 +177,11 @@ function expectObjectOnDesktop<T>(key: keyof WindowVariables) {
   describe('does not object type when not on desktop', () => {
     itEachInvalidObjectValue((invalidObjectValue) => {
       // arrange
+      const isOnDesktop = false;
       const invalidObject = invalidObjectValue as T;
       const input: WindowVariables = {
         ...new WindowVariablesStub(),
-        isDesktop: undefined,
+        isDesktop: isOnDesktop,
         [key]: invalidObject,
       };
       // act

tests/unit/presentation/bootstrapping/ClientLoggerFactory.spec.ts

@@ -3,7 +3,7 @@ import {
 } from 'vitest';
 import { IRuntimeEnvironment } from '@/infrastructure/RuntimeEnvironment/IRuntimeEnvironment';
 import { ClientLoggerFactory } from '@/presentation/bootstrapping/ClientLoggerFactory';
-import { ILogger } from '@/infrastructure/Log/ILogger';
+import { Logger } from '@/application/Common/Log/Logger';
 import { WindowInjectedLogger } from '@/infrastructure/Log/WindowInjectedLogger';
 import { ConsoleLogger } from '@/infrastructure/Log/ConsoleLogger';
 import { NoopLogger } from '@/infrastructure/Log/NoopLogger';
@@ -29,7 +29,7 @@ describe('ClientLoggerFactory', () => {
     });
     const testCases: Array<{
       readonly description: string,
-      readonly expectedType: Constructible<ILogger>,
+      readonly expectedType: Constructible<Logger>,
       readonly environment: IRuntimeEnvironment,
     }> = [
       {

tests/unit/presentation/bootstrapping/DependencyProvider.spec.ts

@@ -17,6 +17,7 @@ describe('DependencyProvider', () => {
       useClipboard: createTransientTests(),
       useCurrentCode: createTransientTests(),
       useUserSelectionState: createTransientTests(),
+      useLogger: createTransientTests(),
     };
     Object.entries(testCases).forEach(([key, runTests]) => {
       const registeredKey = InjectionKeys[key].key;

tests/unit/presentation/components/Shared/Hooks/UseLogger.spec.ts

@@ -0,0 +1,17 @@
+import { describe, it, expect } from 'vitest';
+import { useLogger } from '@/presentation/components/Shared/Hooks/UseLogger';
+import { LoggerStub } from '@tests/unit/shared/Stubs/LoggerStub';
+import { LoggerFactoryStub } from '@tests/unit/shared/Stubs/LoggerFactoryStub';
+
+describe('UseLogger', () => {
+  it('returns expected logger from factory', () => {
+    // arrange
+    const expectedLogger = new LoggerStub();
+    const factory = new LoggerFactoryStub()
+      .withLogger(expectedLogger);
+    // act
+    const { log: actualLogger } = useLogger(factory);
+    // assert
+    expect(actualLogger).to.equal(expectedLogger);
+  });
+});

tests/unit/presentation/electron/preload/WindowVariablesProvider.spec.ts

@@ -3,7 +3,7 @@ import { provideWindowVariables } from '@/presentation/electron/preload/WindowVa
 import { SystemOperationsStub } from '@tests/unit/shared/Stubs/SystemOperationsStub';
 import { OperatingSystem } from '@/domain/OperatingSystem';
 import { ISystemOperations } from '@/infrastructure/SystemOperations/ISystemOperations';
-import { ILogger } from '@/infrastructure/Log/ILogger';
+import { Logger } from '@/application/Common/Log/Logger';
 import { LoggerStub } from '@tests/unit/shared/Stubs/LoggerStub';
 
 describe('WindowVariablesProvider', () => {
@@ -55,7 +55,7 @@ class TestContext {
 
   private os: OperatingSystem = OperatingSystem.Android;
 
-  private log: ILogger = new LoggerStub();
+  private log: Logger = new LoggerStub();
 
   public withSystem(system: ISystemOperations): this {
     this.system = system;
@@ -67,7 +67,7 @@ class TestContext {
     return this;
   }
 
-  public withLogger(log: ILogger): this {
+  public withLogger(log: Logger): this {
     this.log = log;
     return this;
   }

tests/unit/shared/Stubs/LoggerFactoryStub.ts

@@ -0,0 +1,12 @@
+import { Logger } from '@/application/Common/Log/Logger';
+import { LoggerFactory } from '@/application/Common/Log/LoggerFactory';
+import { LoggerStub } from './LoggerStub';
+
+export class LoggerFactoryStub implements LoggerFactory {
+  public logger: Logger = new LoggerStub();
+
+  public withLogger(logger: Logger): this {
+    this.logger = logger;
+    return this;
+  }
+}

tests/unit/shared/Stubs/LoggerStub.ts

@@ -1,12 +1,32 @@
-import { ILogger } from '@/infrastructure/Log/ILogger';
+import { Logger } from '@/application/Common/Log/Logger';
 import { StubWithObservableMethodCalls } from './StubWithObservableMethodCalls';
 
-export class LoggerStub extends StubWithObservableMethodCalls<ILogger> implements ILogger {
+export class LoggerStub extends StubWithObservableMethodCalls<Logger> implements Logger {
+  public warn(...params: unknown[]): void {
+    this.registerMethodCall({
+      methodName: 'warn',
+      args: params,
+    });
+  }
+
+  public error(...params: unknown[]): void {
+    this.registerMethodCall({
+      methodName: 'error',
+      args: params,
+    });
+  }
+
+  public debug(...params: unknown[]): void {
+    this.registerMethodCall({
+      methodName: 'debug',
+      args: params,
+    });
+  }
+
   public info(...params: unknown[]): void {
     this.registerMethodCall({
       methodName: 'info',
       args: params,
     });
-    console.log(...params);
   }
 }

tests/unit/shared/Stubs/WindowVariablesStub.ts

@@ -1,5 +1,5 @@
 import { OperatingSystem } from '@/domain/OperatingSystem';
-import { ILogger } from '@/infrastructure/Log/ILogger';
+import { Logger } from '@/application/Common/Log/Logger';
 import { ISystemOperations } from '@/infrastructure/SystemOperations/ISystemOperations';
 import { WindowVariables } from '@/infrastructure/WindowVariables/WindowVariables';
 import { SystemOperationsStub } from './SystemOperationsStub';
@@ -8,18 +8,18 @@ import { LoggerStub } from './LoggerStub';
 export class WindowVariablesStub implements WindowVariables {
   public system?: ISystemOperations = new SystemOperationsStub();
 
-  public isDesktop? = false;
+  public isDesktop = false;
 
   public os?: OperatingSystem = OperatingSystem.BlackBerryOS;
 
-  public log?: ILogger = new LoggerStub();
+  public log: Logger = new LoggerStub();
 
-  public withLog(log?: ILogger): this {
+  public withLog(log: Logger): this {
     this.log = log;
     return this;
   }
 
-  public withIsDesktop(value?: boolean): this {
+  public withIsDesktop(value: boolean): this {
     this.isDesktop = value;
     return this;
   }