fix: refeactor log message interfaces

packages/pnpm-sync-lib/etc/pnpm-sync-lib.api.md

@@ -29,15 +29,37 @@ export interface ILockfileImporter {
 }
 
 // @beta (undocumented)
-export enum ILogMessageKind {
+export interface ILogMessageCallbackOptions {
     // (undocumented)
-    ERROR = "error",
-    // (undocumented)
-    INFO = "info",
+    details: {
+        messageIdentifier: LogMessageIdentifier.PREPARE_STARTING;
+        lockfilePath: string;
+        dotPnpmFolderPath: string;
+    } | {
+        messageIdentifier: LogMessageIdentifier.PREPARE_PROCESSING;
+        lockfilePath: string;
+        dotPnpmFolderPath: string;
+    } | {
+        messageIdentifier: LogMessageIdentifier.PREPARE_FINISHING;
+        lockfilePath: string;
+        dotPnpmFolderPath: string;
+        executionTimeInMs: string;
+    } | {
+        messageIdentifier: LogMessageIdentifier.COPY_STARTING;
+        pnpmSyncJsonPath: string;
+    } | {
+        messageIdentifier: LogMessageIdentifier.COPY_PROCESSING;
+        pnpmSyncJsonPath: string;
+    } | {
+        messageIdentifier: LogMessageIdentifier.COPY_FINISHING;
+        pnpmSyncJsonPath: string;
+        fileCount: number;
+        executionTimeInMs: string;
+    };
     // (undocumented)
-    VERBOSE = "verbose",
+    message: string;
     // (undocumented)
-    WARNING = "warning"
+    messageKind: LogMessageKind;
 }
 
 // @beta (undocumented)
@@ -51,10 +73,7 @@ export interface IPnpmSyncCopyOptions {
     // (undocumented)
     getPackageIncludedFiles: (packagePath: string) => Promise<string[]>;
     // (undocumented)
-    logMessageCallback: (message: string, messageKind: ILogMessageKind, details?: {
-        fileCount: number;
-        executionTimeInMs: string;
-    }) => void;
+    logMessageCallback: (options: ILogMessageCallbackOptions) => void;
     // (undocumented)
     pnpmSyncJsonPath?: string;
 }
@@ -64,11 +83,7 @@ export interface IPnpmSyncPrepareOptions {
     // (undocumented)
     lockfilePath: string;
     // (undocumented)
-    logMessageCallback: (message: string, messageKind: ILogMessageKind, details?: {
-        lockfilePath: string;
-        dotPnpmFolderPath: string;
-        executionTimeInMs: string;
-    }) => void;
+    logMessageCallback: (options: ILogMessageCallbackOptions) => void;
     // (undocumented)
     readPnpmLockfile: (lockfilePath: string, options: {
         ignoreIncompatible: boolean;
@@ -82,6 +97,34 @@ export type IVersionSpecifier = string | {
     version: string;
 };
 
+// @beta (undocumented)
+export enum LogMessageIdentifier {
+    // (undocumented)
+    COPY_FINISHING = "Finishing pnpm-sync copy",
+    // (undocumented)
+    COPY_PROCESSING = "Processing pnpm-sync copy",
+    // (undocumented)
+    COPY_STARTING = "Starting pnpm-sync copy",
+    // (undocumented)
+    PREPARE_FINISHING = "Finishing pnpm-sync prepare",
+    // (undocumented)
+    PREPARE_PROCESSING = "Processing pnpm-sync prepare",
+    // (undocumented)
+    PREPARE_STARTING = "Starting pnpm-sync prepare"
+}
+
+// @beta (undocumented)
+export enum LogMessageKind {
+    // (undocumented)
+    ERROR = "error",
+    // (undocumented)
+    INFO = "info",
+    // (undocumented)
+    VERBOSE = "verbose",
+    // (undocumented)
+    WARNING = "warning"
+}
+
 // @beta
 export function pnpmSyncCopyAsync({ pnpmSyncJsonPath, getPackageIncludedFiles, forEachAsyncWithConcurrency, ensureFolder, logMessageCallback }: IPnpmSyncCopyOptions): Promise<void>;
 

packages/pnpm-sync-lib/src/index.ts

@@ -7,5 +7,11 @@
 
 export { pnpmSyncCopyAsync, type IPnpmSyncCopyOptions } from './pnpmSyncCopy';
 export { pnpmSyncPrepareAsync, type IPnpmSyncPrepareOptions } from './pnpmSyncPrepare';
-export { ILogMessageKind } from './interfaces';
-export type { ILockfile, ILockfileImporter, IVersionSpecifier, IDependencyMeta } from './interfaces';
+export { LogMessageIdentifier, LogMessageKind } from './interfaces';
+export type {
+  ILockfile,
+  ILockfileImporter,
+  IVersionSpecifier,
+  IDependencyMeta,
+  ILogMessageCallbackOptions
+} from './interfaces';

packages/pnpm-sync-lib/src/interfaces.ts

@@ -18,13 +18,64 @@ export interface ITargetFolder {
 /**
  * @beta
  */
-export enum ILogMessageKind {
+export enum LogMessageKind {
   INFO = 'info',
   WARNING = 'warning',
   ERROR = 'error',
   VERBOSE = 'verbose'
 }
 
+/**
+ * @beta
+ */
+export enum LogMessageIdentifier {
+  PREPARE_STARTING = 'Starting pnpm-sync prepare',
+  PREPARE_PROCESSING = 'Processing pnpm-sync prepare',
+  PREPARE_FINISHING = 'Finishing pnpm-sync prepare',
+  COPY_STARTING = 'Starting pnpm-sync copy',
+  COPY_PROCESSING = 'Processing pnpm-sync copy',
+  COPY_FINISHING = 'Finishing pnpm-sync copy'
+}
+
+/**
+ * @beta
+ */
+export interface ILogMessageCallbackOptions {
+  message: string;
+  messageKind: LogMessageKind;
+  details:
+    | {
+        messageIdentifier: LogMessageIdentifier.PREPARE_STARTING;
+        lockfilePath: string;
+        dotPnpmFolderPath: string;
+      }
+    | {
+        messageIdentifier: LogMessageIdentifier.PREPARE_PROCESSING;
+        lockfilePath: string;
+        dotPnpmFolderPath: string;
+      }
+    | {
+        messageIdentifier: LogMessageIdentifier.PREPARE_FINISHING;
+        lockfilePath: string;
+        dotPnpmFolderPath: string;
+        executionTimeInMs: string;
+      }
+    | {
+        messageIdentifier: LogMessageIdentifier.COPY_STARTING;
+        pnpmSyncJsonPath: string;
+      }
+    | {
+        messageIdentifier: LogMessageIdentifier.COPY_PROCESSING;
+        pnpmSyncJsonPath: string;
+      }
+    | {
+        messageIdentifier: LogMessageIdentifier.COPY_FINISHING;
+        pnpmSyncJsonPath: string;
+        fileCount: number;
+        executionTimeInMs: string;
+      };
+}
+
 /**
  * @beta
  */

packages/pnpm-sync-lib/src/pnpmSyncCopy.ts

@@ -1,7 +1,7 @@
 import path from 'path';
 import fs from 'fs';
 import { hrtime } from 'node:process';
-import { ILogMessageKind } from './interfaces';
+import { ILogMessageCallbackOptions, LogMessageIdentifier, LogMessageKind } from './interfaces';
 
 /**
  * @beta
@@ -15,14 +15,7 @@ export interface IPnpmSyncCopyOptions {
     options: { concurrency: number }
   ) => Promise<void>;
   ensureFolder: (folderPath: string) => Promise<void>;
-  logMessageCallback: (
-    message: string,
-    messageKind: ILogMessageKind,
-    details?: {
-      fileCount: number;
-      executionTimeInMs: string;
-    }
-  ) => void;
+  logMessageCallback: (options: ILogMessageCallbackOptions) => void;
 }
 
 /**
@@ -51,14 +44,30 @@ export async function pnpmSyncCopyAsync({
     pnpmSyncJsonPath = 'node_modules/.pnpm-sync.json';
   }
 
+  logMessageCallback({
+    message: `pnpm-sync copy: Starting operation...`,
+    messageKind: LogMessageKind.VERBOSE,
+    details: {
+      messageIdentifier: LogMessageIdentifier.COPY_STARTING,
+      pnpmSyncJsonPath
+    }
+  });
+
   let pnpmSyncJsonContents: string;
   try {
     pnpmSyncJsonContents = (await fs.promises.readFile(pnpmSyncJsonPath)).toString();
   } catch (e) {
     if ((e as NodeJS.ErrnoException).code === 'ENOENT') {
-      const errorMessage: string =
-        'You are executing pnpm-sync for a package, but we can not find the .pnpm-sync.json inside node_modules folder';
-      logMessageCallback(errorMessage, ILogMessageKind.ERROR);
+      logMessageCallback({
+        message:
+          'You are executing pnpm-sync for a package, but we can not find the .pnpm-sync.json inside node_modules folder',
+        messageKind: LogMessageKind.ERROR,
+        details: {
+          messageIdentifier: LogMessageIdentifier.COPY_PROCESSING,
+          pnpmSyncJsonPath
+        }
+      });
+
       return;
     } else {
       throw e;
@@ -104,8 +113,15 @@ export async function pnpmSyncCopyAsync({
   const endTime = hrtime.bigint();
   const copyExecutionTimeInMs: string = (Number(endTime - startTime) / 1e6).toFixed(3) + 'ms';
   const infoMessage = `pnpm-sync copy: Copied ${npmPackFiles.length} files in ${copyExecutionTimeInMs} from ${sourcePath}`;
-  logMessageCallback(infoMessage, ILogMessageKind.INFO, {
-    fileCount: npmPackFiles.length,
-    executionTimeInMs: copyExecutionTimeInMs
+
+  logMessageCallback({
+    message: infoMessage,
+    messageKind: LogMessageKind.INFO,
+    details: {
+      messageIdentifier: LogMessageIdentifier.COPY_FINISHING,
+      pnpmSyncJsonPath,
+      fileCount: npmPackFiles.length,
+      executionTimeInMs: copyExecutionTimeInMs
+    }
   });
 }

packages/pnpm-sync-lib/src/pnpmSyncPrepare.ts

@@ -2,7 +2,14 @@ import path from 'path';
 import fs from 'fs';
 import { cwd, hrtime } from 'process';
 
-import { ILockfile, ILogMessageKind, IPnpmSyncJson, IVersionSpecifier } from './interfaces';
+import {
+  ILockfile,
+  ILogMessageCallbackOptions,
+  LogMessageKind,
+  LogMessageIdentifier,
+  IPnpmSyncJson,
+  IVersionSpecifier
+} from './interfaces';
 
 /**
  * @beta
@@ -14,15 +21,7 @@ export interface IPnpmSyncPrepareOptions {
     lockfilePath: string,
     options: { ignoreIncompatible: boolean }
   ) => Promise<ILockfile | undefined>;
-  logMessageCallback: (
-    message: string,
-    messageKind: ILogMessageKind,
-    details?: {
-      lockfilePath: string;
-      dotPnpmFolderPath: string;
-      executionTimeInMs: string;
-    }
-  ) => void;
+  logMessageCallback: (options: ILogMessageCallbackOptions) => void;
 }
 
 /**
@@ -45,12 +44,19 @@ export async function pnpmSyncPrepareAsync({
   // get the pnpm-lock.yaml path
   lockfilePath = path.resolve(cwd(), lockfilePath);
   storePath = path.resolve(cwd(), storePath);
-  logMessageCallback('pnpm-sync prepare: Starting operation...', ILogMessageKind.VERBOSE);
-  logMessageCallback(
-    `pnpm-sync prepare: The pnpm-lock.yaml file path => ${lockfilePath}`,
-    ILogMessageKind.VERBOSE
-  );
-  logMessageCallback(`pnpm-sync prepare: The .pnpm folder path => ${storePath}`, ILogMessageKind.VERBOSE);
+
+  logMessageCallback({
+    message:
+      `pnpm-sync prepare: Starting operation...\n` +
+      `pnpm-sync prepare: The pnpm-lock.yaml file path => ${lockfilePath}\n` +
+      `pnpm-sync prepare: The .pnpm folder path => ${storePath}`,
+    messageKind: LogMessageKind.VERBOSE,
+    details: {
+      messageIdentifier: LogMessageIdentifier.PREPARE_STARTING,
+      lockfilePath,
+      dotPnpmFolderPath: storePath
+    }
+  });
 
   if (!fs.existsSync(lockfilePath)) {
     throw Error('The input pnpm-lock.yaml path is not correct!');
@@ -133,11 +139,16 @@ export async function pnpmSyncPrepareAsync({
 
   const endTime = hrtime.bigint();
   const prepareExecutionTimeInMs: string = (Number(endTime - startTime) / 1e6).toFixed(3) + 'ms';
-  const infoMessage = `pnpm-sync prepare: Regenerated pnpm-sync.json in ${prepareExecutionTimeInMs} for ${lockfilePath}`;
-  logMessageCallback(infoMessage, ILogMessageKind.INFO, {
-    lockfilePath,
-    dotPnpmFolderPath: storePath,
-    executionTimeInMs: prepareExecutionTimeInMs
+
+  logMessageCallback({
+    message: `pnpm-sync prepare: Regenerated pnpm-sync.json in ${prepareExecutionTimeInMs} for ${lockfilePath}`,
+    messageKind: LogMessageKind.INFO,
+    details: {
+      messageIdentifier: LogMessageIdentifier.PREPARE_FINISHING,
+      lockfilePath,
+      dotPnpmFolderPath: storePath,
+      executionTimeInMs: prepareExecutionTimeInMs
+    }
   });
 }
 

packages/pnpm-sync/src/start.ts

@@ -1,5 +1,10 @@
 import { Command } from 'commander';
-import { pnpmSyncCopyAsync, pnpmSyncPrepareAsync, ILogMessageKind } from 'pnpm-sync-lib';
+import {
+  pnpmSyncCopyAsync,
+  pnpmSyncPrepareAsync,
+  LogMessageKind,
+  type ILogMessageCallbackOptions
+} from 'pnpm-sync-lib';
 import { FileSystem, Async } from '@rushstack/node-core-library';
 import { PackageExtractor } from '@rushstack/package-extractor';
 import { readWantedLockfile, Lockfile } from '@pnpm/lockfile-file';
@@ -17,12 +22,13 @@ program
         getPackageIncludedFiles: PackageExtractor.getPackageIncludedFilesAsync,
         forEachAsyncWithConcurrency: Async.forEachAsync,
         ensureFolder: FileSystem.ensureFolderAsync,
-        logMessageCallback: (message: string, messageType: ILogMessageKind) => {
-          switch (messageType) {
-            case ILogMessageKind.ERROR:
+        logMessageCallback: (options: ILogMessageCallbackOptions) => {
+          const { message, messageKind } = options;
+          switch (messageKind) {
+            case LogMessageKind.ERROR:
               console.error(message);
               break;
-            case ILogMessageKind.WARNING:
+            case LogMessageKind.WARNING:
               console.warn(message);
               break;
             default:
@@ -60,12 +66,13 @@ program
             return lockfile;
           }
         },
-        logMessageCallback: (message: string, messageType: ILogMessageKind) => {
-          switch (messageType) {
-            case ILogMessageKind.ERROR:
+        logMessageCallback: (options: ILogMessageCallbackOptions) => {
+          const { message, messageKind } = options;
+          switch (messageKind) {
+            case LogMessageKind.ERROR:
               console.error(message);
               break;
-            case ILogMessageKind.WARNING:
+            case LogMessageKind.WARNING:
               console.warn(message);
               break;
             default: