@css-modules-kit/codegen 0.6.0 → 0.8.0

package/src/logger/logger.ts

@@ -1,12 +1,14 @@
+import { inspect } from 'node:util';
 import type { DiagnosticSourceFile } from '@css-modules-kit/core';
-import { convertDiagnostic, convertSystemError, type Diagnostic, type SystemError } from '@css-modules-kit/core';
+import { convertDiagnostic, convertSystemError, type Diagnostic, SystemError } from '@css-modules-kit/core';
 import ts from 'typescript';
-import { formatDiagnostics } from './formatter.js';
+import { formatDiagnostics, formatTime } from './formatter.js';
 
 export interface Logger {
   logDiagnostics(diagnostics: Diagnostic[]): void;
-  logSystemError(error: SystemError): void;
-  logMessage(message: string): void;
+  logError(error: unknown): void;
+  logMessage(message: string, options?: { time?: boolean }): void;
+  clearScreen(): void;
 }
 
 export function createLogger(cwd: string, pretty: boolean): Logger {
@@ -29,12 +31,24 @@ export function createLogger(cwd: string, pretty: boolean): Logger {
       );
       process.stderr.write(result);
     },
-    logSystemError(error: SystemError): void {
-      const result = formatDiagnostics([convertSystemError(error)], host, pretty);
-      process.stderr.write(result);
+    logError(error: unknown): void {
+      // NOTE: SystemErrors are errors expected by the css-modules-kit specification and may occur within normal usage.
+      // These errors are formatted clearly and concisely. No stack trace is output.
+      //
+      // All other errors are unexpected errors. To assist in debugging when these errors occur, a stack trace is output.
+      if (error instanceof SystemError) {
+        const result = formatDiagnostics([convertSystemError(error)], host, pretty);
+        process.stderr.write(result);
+      } else {
+        process.stderr.write(`${inspect(error, { colors: pretty })}\n`);
+      }
+    },
+    logMessage(message: string, options?: { time?: boolean }): void {
+      const header = options?.time ? `${formatTime(new Date(), pretty)} ` : '';
+      process.stdout.write(`${header}${message}\n`);
     },
-    logMessage(message: string): void {
-      process.stdout.write(`${message}\n`);
+    clearScreen(): void {
+      process.stdout.write('\x1B[2J\x1B[3J\x1B[H');
     },
   };
 }

package/src/project.ts

@@ -0,0 +1,242 @@
+import { readFileSync } from 'node:fs';
+import type { CSSModule, Diagnostic } from '@css-modules-kit/core';
+import {
+  checkCSSModule,
+  type CMKConfig,
+  createExportBuilder,
+  createMatchesPattern,
+  createResolver,
+  generateDts,
+  getFileNamesByPattern,
+  parseCSSModule,
+  readConfigFile,
+  relative,
+} from '@css-modules-kit/core';
+import ts from 'typescript';
+import { writeDtsFile } from './dts-writer.js';
+import { ReadCSSModuleFileError } from './error.js';
+
+interface ProjectArgs {
+  project: string;
+}
+
+export interface Project {
+  config: CMKConfig;
+  /** Whether the file matches the wildcard patterns in `include` / `exclude` options */
+  isWildcardMatchedFile(fileName: string): boolean;
+  /**
+   * Add a file to the project.
+   * @throws {ReadCSSModuleFileError}
+   */
+  addFile(fileName: string): void;
+  /**
+   * Update a file in the project.
+   * @throws {ReadCSSModuleFileError}
+   */
+  updateFile(fileName: string): void;
+  /** Remove a file from the project. */
+  removeFile(fileName: string): void;
+  /**
+   * Get all diagnostics.
+   * Including three types of diagnostics: project diagnostics, syntactic diagnostics, and semantic diagnostics.
+   * - Project diagnostics: For example, it includes configuration errors in tsconfig.json or warnings when there are no target files.
+   * - Syntactic diagnostics: Syntax errors in CSS Module files.
+   * - Semantic diagnostics: Errors related to the use of imports and exports in CSS module files.
+   * If there are any project diagnostics or syntactic diagnostics, semantic diagnostics will be skipped.
+   */
+  getDiagnostics(): Diagnostic[];
+  /**
+   * Emit .d.ts files for all project files.
+   * @throws {WriteDtsFileError}
+   */
+  emitDtsFiles(): Promise<void>;
+}
+
+/**
+ * Create a Project instance.
+ * Project is like a facade that calls core operations such as loading settings, parsing CSS Module files, and performing checks.
+ * The parsing and checking results are cached, and methods are also provided to clear the cache when files change.
+ * @throws {TsConfigFileNotFoundError}
+ * @throws {ReadCSSModuleFileError}
+ */
+export function createProject(args: ProjectArgs): Project {
+  const config = readConfigFile(args.project);
+
+  const getCanonicalFileName = (fileName: string) =>
+    ts.sys.useCaseSensitiveFileNames ? fileName : fileName.toLowerCase();
+  const moduleResolutionCache = ts.createModuleResolutionCache(
+    config.basePath,
+    getCanonicalFileName,
+    config.compilerOptions,
+  );
+  const resolver = createResolver(config.compilerOptions, moduleResolutionCache);
+  const matchesPattern = createMatchesPattern(config);
+
+  const cssModuleMap = new Map<string, CSSModule>();
+  const semanticDiagnosticsMap = new Map<string, Diagnostic[]>();
+  // Tracks whether .d.ts has been emitted after the last change
+  const emittedSet = new Set<string>();
+  const getCSSModule = (path: string) => cssModuleMap.get(path);
+  const exportBuilder = createExportBuilder({ getCSSModule, matchesPattern, resolver });
+
+  for (const fileName of getFileNamesByPattern(config)) {
+    // NOTE: Files may be deleted between executing `getFileNamesByPattern` and `tryParseCSSModule`.
+    // Therefore, `tryParseCSSModule` may return `undefined`.
+    const cssModule = tryParseCSSModule(fileName);
+    if (cssModule) cssModuleMap.set(fileName, cssModule);
+  }
+
+  /**
+   * @throws {ReadCSSModuleFileError}
+   */
+  function addFile(fileName: string) {
+    if (cssModuleMap.has(fileName)) return;
+
+    const cssModule = tryParseCSSModule(fileName);
+    if (!cssModule) return;
+    cssModuleMap.set(fileName, cssModule);
+
+    // TODO: Delete only the minimum amount of check stage cache
+    moduleResolutionCache.clear();
+    exportBuilder.clearCache();
+    semanticDiagnosticsMap.clear();
+  }
+
+  /**
+   * @throws {ReadCSSModuleFileError}
+   */
+  function updateFile(fileName: string) {
+    if (!cssModuleMap.has(fileName)) return;
+
+    const cssModule = tryParseCSSModule(fileName);
+    if (!cssModule) return;
+    cssModuleMap.set(fileName, cssModule);
+
+    // TODO: Delete only the minimum amount of check stage cache
+    exportBuilder.clearCache();
+    semanticDiagnosticsMap.clear();
+
+    emittedSet.delete(fileName);
+  }
+
+  function removeFile(fileName: string) {
+    if (!cssModuleMap.has(fileName)) return;
+
+    cssModuleMap.delete(fileName);
+
+    // TODO: Delete only the minimum amount of check stage cache
+    moduleResolutionCache.clear();
+    exportBuilder.clearCache();
+    semanticDiagnosticsMap.clear();
+
+    emittedSet.delete(fileName);
+  }
+
+  /**
+   * @throws {ReadCSSModuleFileError}
+   */
+  function tryParseCSSModule(fileName: string): CSSModule | undefined {
+    let text: string;
+    try {
+      // NOTE: We are not using asynchronous APIs for the following reasons:
+      //
+      // - Asynchronous APIs are slow in Node.js.
+      //   - https://github.com/nodejs/performance/issues/151
+      // - Handling race conditions is cumbersome.
+      //   - Using an asynchronous API makes `addFile` asynchronous too.
+      //   - If `deleteFile` runs while `addFile` is executing, a race condition occurs.
+      //   - Avoiding this requires something like a mutex. However, implementing that is cumbersome.
+      text = readFileSync(fileName, 'utf-8');
+    } catch (error) {
+      if (isNodeJSSystemError(error) && error.code === 'ENOENT') {
+        return undefined;
+      }
+      throw new ReadCSSModuleFileError(fileName, error);
+    }
+    return parseCSSModule(text, { fileName, includeSyntaxError: true, keyframes: config.keyframes });
+  }
+
+  function getDiagnostics(): Diagnostic[] {
+    const diagnostics: Diagnostic[] = [...getProjectDiagnostics(), ...getSyntacticDiagnostics()];
+    // If there are project or syntactic diagnostics, skip semantic diagnostics
+    if (diagnostics.length > 0) return diagnostics;
+    diagnostics.push(...getSemanticDiagnostics());
+    return diagnostics;
+  }
+
+  function getProjectDiagnostics() {
+    const diagnostics: Diagnostic[] = [];
+    diagnostics.push(...config.diagnostics);
+    if (config.enabled === undefined) {
+      diagnostics.push({
+        category: 'warning',
+        text: `"cmkOptions.enabled" will be required in a future version of css-modules-kit. Add \`"cmkOptions": { "enabled": true }\` to ${relative(config.basePath, config.configFileName)}. See https://github.com/mizdra/css-modules-kit/issues/289 for details.`,
+      });
+    }
+    if (cssModuleMap.size === 0) {
+      diagnostics.push({
+        category: 'error',
+        text: `The file specified in tsconfig.json not found.`,
+      });
+    }
+    return diagnostics;
+  }
+
+  function getSyntacticDiagnostics() {
+    return Array.from(cssModuleMap.values()).flatMap(({ diagnostics }) => diagnostics);
+  }
+
+  function getSemanticDiagnostics() {
+    const allDiagnostics: Diagnostic[] = [];
+    for (const cssModule of cssModuleMap.values()) {
+      let diagnostics = semanticDiagnosticsMap.get(cssModule.fileName);
+      if (!diagnostics) {
+        diagnostics = checkCSSModule(cssModule, {
+          config,
+          getExportRecord: (m) => exportBuilder.build(m),
+          matchesPattern,
+          resolver,
+          getCSSModule,
+        });
+        semanticDiagnosticsMap.set(cssModule.fileName, diagnostics);
+      }
+      allDiagnostics.push(...diagnostics);
+    }
+    return allDiagnostics;
+  }
+
+  /**
+   * @throws {WriteDtsFileError}
+   */
+  async function emitDtsFiles(): Promise<void> {
+    const promises: Promise<void>[] = [];
+    for (const cssModule of cssModuleMap.values()) {
+      if (emittedSet.has(cssModule.fileName)) continue;
+      const dts = generateDts(cssModule, { ...config, forTsPlugin: false });
+      promises.push(
+        writeDtsFile(dts.text, cssModule.fileName, {
+          outDir: config.dtsOutDir,
+          basePath: config.basePath,
+          arbitraryExtensions: config.arbitraryExtensions,
+        }).then(() => {
+          emittedSet.add(cssModule.fileName);
+        }),
+      );
+    }
+    await Promise.all(promises);
+  }
+
+  return {
+    config,
+    isWildcardMatchedFile: (fileName) => matchesPattern(fileName),
+    addFile,
+    updateFile,
+    removeFile,
+    getDiagnostics,
+    emitDtsFiles,
+  };
+}
+
+function isNodeJSSystemError(error: unknown): error is NodeJS.ErrnoException {
+  return typeof error === 'object' && error !== null && 'code' in error && typeof error.code === 'string';
+}

package/src/runner.ts

@@ -1,132 +1,182 @@
-import { readFile, rm } from 'node:fs/promises';
-import type {
-  CMKConfig,
-  CSSModule,
-  Diagnostic,
-  DiagnosticWithLocation,
-  MatchesPattern,
-  ParseCSSModuleResult,
-  Resolver,
-} from '@css-modules-kit/core';
-import {
-  checkCSSModule,
-  createDts,
-  createExportBuilder,
-  createMatchesPattern,
-  createResolver,
-  getFileNamesByPattern,
-  parseCSSModule,
-  readConfigFile,
-} from '@css-modules-kit/core';
-import ts from 'typescript';
-import type { ParsedArgs } from './cli.js';
-import { writeDtsFile } from './dts-writer.js';
-import { ReadCSSModuleFileError } from './error.js';
+import type { Stats } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import chokidar, { type FSWatcher } from 'chokidar';
+import { CMKDisabledError } from './error.js';
 import type { Logger } from './logger/logger.js';
+import { createProject, type Project } from './project.js';
 
-/**
- * @throws {ReadCSSModuleFileError} When failed to read CSS Module file.
- */
-async function parseCSSModuleByFileName(fileName: string, config: CMKConfig): Promise<ParseCSSModuleResult> {
-  let text: string;
-  try {
-    text = await readFile(fileName, 'utf-8');
-  } catch (error) {
-    throw new ReadCSSModuleFileError(fileName, error);
-  }
-  return parseCSSModule(text, { fileName, safe: false, keyframes: config.keyframes });
+interface RunnerArgs {
+  project: string;
+  clean: boolean;
+  preserveWatchOutput: boolean;
+}
+
+export interface Watcher {
+  /** Exported for testing purposes */
+  project: Project;
+  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`.
+ * @throws {CMKDisabledError} When css-modules-kit is disabled.
+ * @throws {ReadCSSModuleFileError} When failed to read CSS Module file.
  * @throws {WriteDtsFileError}
+ * @returns Whether the process succeeded without errors.
  */
-async function writeDtsByCSSModule(
-  cssModule: CSSModule,
-  { dtsOutDir, basePath, arbitraryExtensions, namedExports, prioritizeNamedImports }: CMKConfig,
-  resolver: Resolver,
-  matchesPattern: MatchesPattern,
-): Promise<void> {
-  const dts = createDts(
-    cssModule,
-    { resolver, matchesPattern },
-    { namedExports, prioritizeNamedImports, forTsPlugin: false },
-  );
-  await writeDtsFile(dts.text, cssModule.fileName, {
-    outDir: dtsOutDir,
-    basePath,
-    arbitraryExtensions,
-  });
+export async function runCMK(args: RunnerArgs, logger: Logger): Promise<boolean> {
+  const project = createProject(args);
+  if (project.config.enabled === false) {
+    throw new CMKDisabledError(project.config);
+  }
+  if (args.clean) {
+    await rm(project.config.dtsOutDir, { recursive: true, force: true });
+  }
+  await project.emitDtsFiles();
+  const diagnostics = project.getDiagnostics();
+  if (diagnostics.length > 0) {
+    logger.logDiagnostics(diagnostics);
+    const hasErrors = diagnostics.some((d) => d.category === 'error');
+    return !hasErrors;
+  }
+  return true;
 }
 
 /**
- * Run css-modules-kit .d.ts generation.
+ * Run css-modules-kit .d.ts generation in watch mode.
+ *
+ * The promise resolves when the initial diagnostics report, emit, and watcher initialization are complete.
+ * Errors are reported through the logger.
+ *
+ * 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 {ReadCSSModuleFileError} When failed to read CSS Module file.
+ * @throws {CMKDisabledError} When css-modules-kit is disabled.
+ * @throws {TsConfigFileNotFoundError}
+ * @throws {ReadCSSModuleFileError}
  * @throws {WriteDtsFileError}
  */
-export async function runCMK(args: ParsedArgs, logger: Logger): Promise<void> {
-  const config = readConfigFile(args.project);
-  if (config.diagnostics.length > 0) {
-    logger.logDiagnostics(config.diagnostics);
-    // eslint-disable-next-line n/no-process-exit
-    process.exit(1);
+export async function runCMKInWatchMode(args: RunnerArgs, logger: Logger): Promise<Watcher> {
+  const fsWatchers: FSWatcher[] = [];
+  const project = createProject(args);
+  if (project.config.enabled === false) {
+    throw new CMKDisabledError(project.config);
   }
+  let emitAndReportDiagnosticsTimer: NodeJS.Timeout | undefined = undefined;
 
-  const getCanonicalFileName = (fileName: string) =>
-    ts.sys.useCaseSensitiveFileNames ? fileName : fileName.toLowerCase();
-  const moduleResolutionCache = ts.createModuleResolutionCache(
-    config.basePath,
-    getCanonicalFileName,
-    config.compilerOptions,
-  );
-  const resolver = createResolver(config.compilerOptions, moduleResolutionCache);
-  const matchesPattern = createMatchesPattern(config);
+  if (args.clean) {
+    await rm(project.config.dtsOutDir, { recursive: true, force: true });
+  }
+  await emitAndReportDiagnostics();
 
-  const cssModuleMap = new Map<string, CSSModule>();
-  const syntacticDiagnostics: DiagnosticWithLocation[] = [];
+  // Watch project files and report diagnostics on changes
+  const readyPromises: Promise<void>[] = [];
+  for (const wildcardDirectory of project.config.wildcardDirectories) {
+    const { promise, resolve } = promiseWithResolvers<void>();
+    readyPromises.push(promise);
+    fsWatchers.push(
+      chokidar
+        .watch(wildcardDirectory.fileName, {
+          ignored: (fileName: string, stats?: 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;
 
-  const fileNames = getFileNamesByPattern(config);
-  if (fileNames.length === 0) {
-    logger.logDiagnostics([
-      {
-        category: 'warning',
-        text: `The file specified in tsconfig.json not found.`,
-      },
-    ]);
-    return;
-  }
-  const parseResults = await Promise.all(fileNames.map(async (fileName) => parseCSSModuleByFileName(fileName, config)));
-  for (const parseResult of parseResults) {
-    cssModuleMap.set(parseResult.cssModule.fileName, parseResult.cssModule);
-    syntacticDiagnostics.push(...parseResult.diagnostics);
+            // 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,
+          ...(wildcardDirectory.recursive ? {} : { depth: 0 }),
+        })
+        .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', (e) => logger.logError(e))
+        .on('ready', () => resolve()),
+    );
   }
+  await Promise.all(readyPromises);
 
-  if (syntacticDiagnostics.length > 0) {
-    logger.logDiagnostics(syntacticDiagnostics);
-    // eslint-disable-next-line n/no-process-exit
-    process.exit(1);
-  }
+  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.
 
-  const getCSSModule = (path: string) => cssModuleMap.get(path);
-  const exportBuilder = createExportBuilder({ getCSSModule, matchesPattern, resolver });
-  const semanticDiagnostics: Diagnostic[] = [];
-  for (const { cssModule } of parseResults) {
-    const diagnostics = checkCSSModule(cssModule, config, exportBuilder, matchesPattern, resolver, getCSSModule);
-    semanticDiagnostics.push(...diagnostics);
+    if (emitAndReportDiagnosticsTimer !== undefined) clearTimeout(emitAndReportDiagnosticsTimer);
+
+    emitAndReportDiagnosticsTimer = setTimeout(() => {
+      emitAndReportDiagnosticsTimer = undefined;
+      emitAndReportDiagnostics().catch(logger.logError.bind(logger));
+    }, 250);
   }
 
-  if (semanticDiagnostics.length > 0) {
-    logger.logDiagnostics(semanticDiagnostics);
-    // eslint-disable-next-line n/no-process-exit
-    process.exit(1);
+  /**
+   * @throws {WriteDtsFileError}
+   */
+  async function emitAndReportDiagnostics() {
+    if (!args.preserveWatchOutput) {
+      logger.clearScreen();
+    }
+    await project.emitDtsFiles();
+    const diagnostics = project.getDiagnostics();
+    if (diagnostics.length > 0) {
+      logger.logDiagnostics(diagnostics);
+    }
+    const errorCount = diagnostics.filter((d) => d.category === 'error').length;
+    const warningCount = diagnostics.filter((d) => d.category === 'warning').length;
+    const warningPart = warningCount > 0 ? ` and ${warningCount} warning${warningCount === 1 ? '' : 's'}` : '';
+    logger.logMessage(
+      `Found ${errorCount} error${errorCount === 1 ? '' : 's'}${warningPart}. Watching for file changes.`,
+      { time: true },
+    );
+    if (args.preserveWatchOutput) {
+      logger.logMessage('');
+    }
   }
 
-  if (args.clean) {
-    await rm(config.dtsOutDir, { recursive: true, force: true });
+  async function close() {
+    await Promise.all(fsWatchers.map(async (watcher) => watcher.close()));
   }
-  await Promise.all(
-    parseResults.map(async (parseResult) =>
-      writeDtsByCSSModule(parseResult.cssModule, config, resolver, matchesPattern),
-    ),
-  );
+
+  return { project, close };
+}
+
+function promiseWithResolvers<T>() {
+  let resolve;
+  let reject;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return {
+    promise,
+    resolve: resolve as unknown as (value: T) => void,
+    reject: reject as unknown as (reason?: unknown) => void,
+  };
 }

package/bin/cmk.mjs

@@ -1,29 +0,0 @@
-#!/usr/bin/env node
-/* eslint-disable n/no-process-exit */
-
-import { SystemError } from '@css-modules-kit/core';
-import { createLogger, parseCLIArgs, printHelpText, printVersion, runCMK, shouldBePretty } from '../dist/index.js';
-
-const cwd = process.cwd();
-let logger = createLogger(cwd, shouldBePretty(undefined));
-
-try {
-  const args = parseCLIArgs(process.argv.slice(2), cwd);
-  logger = createLogger(cwd, shouldBePretty(args.pretty));
-
-  if (args.help) {
-    printHelpText();
-    process.exit(0);
-  } else if (args.version) {
-    printVersion();
-    process.exit(0);
-  }
-
-  await runCMK(args, logger);
-} catch (e) {
-  if (e instanceof SystemError) {
-    logger.logSystemError(e);
-    process.exit(1);
-  }
-  throw e;
-}