Skip to content

Commit

Permalink
chore(compiler): add debug statements for file watching
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
rwaskiewicz committed Apr 4, 2023
1 parent 32a9770 commit 87c2230
Show file tree
Hide file tree
Showing 3 changed files with 40 additions and 4 deletions.
2 changes: 1 addition & 1 deletion src/cli/logs.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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}`);
}
Expand Down
31 changes: 30 additions & 1 deletion src/compiler/build/watch-build.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand All @@ -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);
Expand Down Expand Up @@ -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();
}
};
Expand Down
11 changes: 9 additions & 2 deletions src/sys/node/node-sys.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -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)[] = [];

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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) => {
Expand Down

0 comments on commit 87c2230

Please sign in to comment.