chore(compiler): add debug statements for file watching

this commit is a follow up to #4146.
when debugging the file watcher, it's valuable to know what files have
been perceived as added/updated/etc. for #4146, we created dev-builds
with additional logging statements to help diagnose the issue. in this
commit, we add more refined debugging statements that attempt to balance
providing useful information while not spamming the output with logging
statements.

when starting a dev server, the version of stencil has been added to the
`[LOCAL DEV]`. starting with #4098,
stencil has useful information in both dev and prod builds of the
project that can is used here. this was also added to avoid a call to
stencil's info task - most of the information from the info task is
already provided in the output of starting of the dev server. by adding
only the version here, we avoid redundant logging statements.

the watch build task has been updated to log the files changed (added,
updated, deleted, written). these statements can get slightly verbose,
with at least one line per category per rebuild. however, this
information was immensely helpful in #4146, and was deemed worth the
extra output. the output is only provided when the logging level of the
stencil logger is set to "debug", and won't be enabled for normal runs
of the compiler.

similar to the watch build task, additional debug-only logging was
added to the node-sys watch file-related functions. debug statements in
this file are not guarded with a conditional statement, as we do not
have any guarantees/information around the logging level that has been
set when a node-sys instance is created. in order to log correctly, an
optional logger (optional as to not break the contract of this public
api) has been added to the creation of node-sys. should one not be
provided, debug logging will not apply.

Author: rwaskiewicz

src/cli/logs.ts

@@ -40,7 +40,7 @@ export const startupLogVersion = (logger: Logger, task: TaskCommand, coreCompile
   let startupMsg: string;
 
   if (isDevBuild) {
-    startupMsg = logger.yellow('[LOCAL DEV]');
+    startupMsg = logger.yellow(`[LOCAL DEV] v${coreCompiler.version}`);
   } else {
     startupMsg = logger.cyan(`v${coreCompiler.version}`);
   }

src/compiler/build/watch-build.ts

@@ -53,6 +53,19 @@ export const createWatchBuild = async (
     buildCtx.hasHtmlChanges = hasHtmlChanges(config, buildCtx);
     buildCtx.hasServiceWorkerChanges = hasServiceWorkerChanges(config, buildCtx);
 
+    if (config.flags.debug) {
+      config.logger.debug(`WATCH_BUILD::watchBuild::onBuild filesAdded: ${formatFilesForDebug(buildCtx.filesAdded)}`);
+      config.logger.debug(
+        `WATCH_BUILD::watchBuild::onBuild filesDeleted: ${formatFilesForDebug(buildCtx.filesDeleted)}`
+      );
+      config.logger.debug(
+        `WATCH_BUILD::watchBuild::onBuild filesUpdated: ${formatFilesForDebug(buildCtx.filesUpdated)}`
+      );
+      config.logger.debug(
+        `WATCH_BUILD::watchBuild::onBuild filesWritten: ${formatFilesForDebug(buildCtx.filesWritten)}`
+      );
+    }
+
     dirsAdded.clear();
     dirsDeleted.clear();
     filesAdded.clear();
@@ -70,6 +83,22 @@ export const createWatchBuild = async (
     }
   };
 
+  /**
+   * Utility method for formatting a debug message that must either list a number of files, or the word 'none' if the
+   * provided list is empty
+   * @param files a list of files, the list may be empty
+   * @returns the provided list if it is not empty. otherwise, return the word 'none'
+   */
+  const formatFilesForDebug = (files: ReadonlyArray<string>): string => {
+    /**
+     * In the created message, it's important that there's no whitespace prior to the file name.
+     * Stencil's logger will split messages by whitespace according to the width of the terminal window.
+     * Since file names can be fully qualified paths (and therefore quite long), putting whitespace between a '-' and
+     * the path can lead to formatted messages where the '-' is on its own line
+     */
+    return files.length > 0 ? files.map((filename: string) => `-${filename}`).join('\n') : 'none';
+  };
+
   const start = async () => {
     const srcRead = watchSrcDirectory(config, compilerCtx);
     const otherRead = watchRootFiles(config, compilerCtx);
@@ -104,7 +133,7 @@ export const createWatchBuild = async (
           break;
       }
 
-      config.logger.debug(`onFsChange ${eventKind}: ${p}`);
+      config.logger.debug(`WATCH_BUILD::fs_event_change - type=${eventKind}, path=${p}, time=${new Date().getTime()}`);
       tsWatchProgram.rebuild();
     }
   };

src/sys/node/node-sys.ts

@@ -17,6 +17,7 @@ import type {
   CompilerSystemRealpathResults,
   CompilerSystemRemoveFileResults,
   CompilerSystemWriteFileResults,
+  Logger,
 } from '../../declarations';
 import { asyncGlob, nodeCopyTasks } from './node-copy-tasks';
 import { NodeLazyRequire } from './node-lazy-require';
@@ -30,11 +31,12 @@ import { NodeWorkerController } from './node-worker-controller';
  *
  * This takes an optional param supplying a `process` object to be used.
  *
- * @param c an optional object wrapping a `process` object
+ * @param c an optional object wrapping `process` and `logger` objects
  * @returns a node.js `CompilerSystem` object
  */
-export function createNodeSys(c: { process?: any } = {}): CompilerSystem {
+export function createNodeSys(c: { process?: any; logger?: Logger } = {}): CompilerSystem {
   const prcs: NodeJS.Process = c?.process ?? global.process;
+  const logger: Logger = c?.logger;
   const destroys = new Set<() => Promise<void> | void>();
   const onInterruptsCallbacks: (() => void)[] = [];
 
@@ -457,9 +459,12 @@ export function createNodeSys(c: { process?: any } = {}): CompilerSystem {
       sys.events = buildEvents();
 
       sys.watchDirectory = (p, callback, recursive) => {
+        logger?.debug(`NODE_SYS_DEBUG::watchDir ${p}`);
+
         const tsFileWatcher = tsSysWatchDirectory(
           p,
           (fileName) => {
+            logger?.debug(`NODE_SYS_DEBUG::watchDir:callback dir=${p} changedPath=${fileName}`);
             callback(normalizePath(fileName), 'fileUpdate');
           },
           recursive
@@ -496,6 +501,8 @@ export function createNodeSys(c: { process?: any } = {}): CompilerSystem {
        * @returns an object with a method for unhooking the file watcher from the system
        */
       sys.watchFile = (path: string, callback: CompilerFileWatcherCallback): CompilerFileWatcher => {
+        logger?.debug(`NODE_SYS_DEBUG::watchFile ${path}`);
+
         const tsFileWatcher = tsSysWatchFile(
           path,
           (fileName: string, tsEventKind: TypeScript.FileWatcherEventKind) => {