feat: implement watch mode

Author: mizdra

.changeset/modern-tables-dress.md

@@ -0,0 +1,5 @@
+---
+'@css-modules-kit/codegen': minor
+---
+
+feat: add `--watch` option

packages/codegen/bin/cmk.mjs

@@ -1,7 +1,15 @@
 #!/usr/bin/env node
 /* eslint-disable n/no-process-exit */
 
-import { createLogger, parseCLIArgs, printHelpText, printVersion, runCMK, shouldBePretty } from '../dist/index.js';
+import {
+  createLogger,
+  parseCLIArgs,
+  printHelpText,
+  printVersion,
+  runCMK,
+  runCMKInWatchMode,
+  shouldBePretty,
+} from '../dist/index.js';
 
 const cwd = process.cwd();
 let logger = createLogger(cwd, shouldBePretty(undefined));
@@ -18,9 +26,14 @@ try {
     process.exit(0);
   }
 
-  const success = await runCMK(args, logger);
-  if (!success) {
-    process.exit(1);
+  if (args.watch) {
+    const watcher = await runCMKInWatchMode(args, logger);
+    process.on('SIGINT', () => watcher.close());
+  } else {
+    const success = await runCMK(args, logger);
+    if (!success) {
+      process.exit(1);
+    }
   }
 } catch (e) {
   logger.logError(e);

packages/codegen/src/index.ts

@@ -1,4 +1,4 @@
-export { runCMK } from './runner.js';
+export { runCMK, runCMKInWatchMode } from './runner.js';
 export { type Logger, createLogger } from './logger/logger.js';
 export { WriteDtsFileError, ReadCSSModuleFileError } from './error.js';
 export { parseCLIArgs, printHelpText, printVersion } from './cli.js';

packages/codegen/src/runner.ts

@@ -1,4 +1,5 @@
 import { rm } from 'node:fs/promises';
+import chokidar, { type FSWatcher } from 'chokidar';
 import type { Logger } from './logger/logger.js';
 import { createProject } from './project.js';
 
@@ -7,6 +8,10 @@ interface RunnerArgs {
   clean: boolean;
 }
 
+interface Watcher {
+  close(): Promise<void>;
+}
+
 /**
  * Run css-modules-kit .d.ts generation.
  * @param project The absolute path to the project directory or the path to `tsconfig.json`.
@@ -27,3 +32,109 @@ export async function runCMK(args: RunnerArgs, logger: Logger): Promise<boolean>
   }
   return true;
 }
+
+/**
+ * Run css-modules-kit .d.ts generation in watch mode.
+ *
+ * NOTE: For implementation simplicity, config file changes are not watched.
+ * @param project The absolute path to the project directory or the path to `tsconfig.json`.
+ * @throws {TsConfigFileNotFoundError}
+ * @throws {ReadCSSModuleFileError}
+ * @throws {WriteDtsFileError}
+ */
+export async function runCMKInWatchMode(args: RunnerArgs, logger: Logger): Promise<Watcher> {
+  const fsWatchers: FSWatcher[] = [];
+  const project = createProject(args);
+  let emitAndReportDiagnosticsTimer: NodeJS.Timeout | undefined = undefined;
+
+  if (args.clean) {
+    await rm(project.config.dtsOutDir, { recursive: true, force: true });
+  }
+  await emitAndReportDiagnostics();
+
+  // Watch project files and report diagnostics on changes
+  for (const wildcardDirectory of project.config.wildcardDirectories) {
+    fsWatchers.push(
+      chokidar
+        // @ts-expect-error -- allow undefined depth
+        .watch(wildcardDirectory.fileName, {
+          ignored: (fileName, stats) => {
+            // The ignored function is called twice for the same path. The first time with stats undefined,
+            // and the second time with stats provided.
+            // In the first call, we can't determine if the path is a directory or file.
+            // So we include it in the watch target considering it might be a directory.
+            if (!stats) return false;
+
+            // In the second call, we include directories or files that match wildcards in the watch target.
+            // However, `dtsOutDir` is excluded from the watch target.
+            if (stats.isDirectory()) {
+              return fileName === project.config.dtsOutDir;
+            } else {
+              return !project.isWildcardMatchedFile(fileName);
+            }
+          },
+          ignoreInitial: true,
+          depth: wildcardDirectory.recursive ? undefined : 0,
+          awaitWriteFinish: true,
+        })
+        .on('add', (fileName) => {
+          try {
+            project.addFile(fileName);
+          } catch (e) {
+            logger.logError(e);
+            return;
+          }
+          scheduleEmitAndReportDiagnostics();
+        })
+        .on('change', (fileName) => {
+          try {
+            project.updateFile(fileName);
+          } catch (e) {
+            logger.logError(e);
+            return;
+          }
+          scheduleEmitAndReportDiagnostics();
+        })
+        .on('unlink', (fileName: string) => {
+          project.removeFile(fileName);
+          scheduleEmitAndReportDiagnostics();
+        })
+        .on('error', logger.logError.bind(logger)),
+    );
+  }
+
+  function scheduleEmitAndReportDiagnostics() {
+    // Switching between git branches results in numerous file changes occurring rapidly.
+    // Reporting diagnostics for each file change would overwhelm users.
+    // Therefore, we batch the processing.
+
+    if (emitAndReportDiagnosticsTimer !== undefined) clearTimeout(emitAndReportDiagnosticsTimer);
+
+    emitAndReportDiagnosticsTimer = setTimeout(() => {
+      emitAndReportDiagnosticsTimer = undefined;
+      emitAndReportDiagnostics().catch(logger.logError.bind(logger));
+    }, 250);
+  }
+
+  /**
+   * @throws {WriteDtsFileError}
+   */
+  async function emitAndReportDiagnostics() {
+    logger.clearScreen();
+    await project.emitDtsFiles();
+    const diagnostics = project.getDiagnostics();
+    if (diagnostics.length > 0) {
+      logger.logDiagnostics(diagnostics);
+    }
+    logger.logMessage(
+      `Found ${diagnostics.length} error${diagnostics.length === 1 ? '' : 's'}. Watching for file changes.`,
+      { time: true },
+    );
+  }
+
+  async function close() {
+    await Promise.all(fsWatchers.map(async (watcher) => watcher.close()));
+  }
+
+  return { close };
+}