@css-modules-kit/core 0.7.0 → 0.8.1

package/src/checker.ts

@@ -4,23 +4,24 @@ import type {
   AtValueTokenImporterValue,
   CSSModule,
   Diagnostic,
-  ExportBuilder,
+  ExportRecord,
   Location,
   MatchesPattern,
   Resolver,
   TokenImporter,
 } from './type.js';
-import { isValidAsJSIdentifier } from './util.js';
+import { isURLSpecifier, isValidAsJSIdentifier } from './util.js';
 
-// eslint-disable-next-line max-params, complexity
-export function checkCSSModule(
-  cssModule: CSSModule,
-  config: CMKConfig,
-  exportBuilder: ExportBuilder,
-  matchesPattern: MatchesPattern,
-  resolver: Resolver,
-  getCSSModule: (path: string) => CSSModule | undefined,
-): Diagnostic[] {
+export interface CheckerArgs {
+  config: CMKConfig;
+  getExportRecord: (cssModule: CSSModule) => ExportRecord;
+  matchesPattern: MatchesPattern;
+  resolver: Resolver;
+  getCSSModule: (path: string) => CSSModule | undefined;
+}
+
+export function checkCSSModule(cssModule: CSSModule, args: CheckerArgs): Diagnostic[] {
+  const { config } = args;
   const diagnostics: Diagnostic[] = [];
 
   for (const token of cssModule.localTokens) {
@@ -37,16 +38,18 @@ export function checkCSSModule(
   }
 
   for (const tokenImporter of cssModule.tokenImporters) {
-    const from = resolver(tokenImporter.from, { request: cssModule.fileName });
-    if (!from || !matchesPattern(from)) continue;
-    const imported = getCSSModule(from);
-    if (!imported) {
+    if (isURLSpecifier(tokenImporter.from)) continue;
+    const from = args.resolver(tokenImporter.from, { request: cssModule.fileName });
+    if (!from) {
       diagnostics.push(createCannotImportModuleDiagnostic(cssModule, tokenImporter));
       continue;
     }
+    if (!args.matchesPattern(from)) continue;
+    const imported = args.getCSSModule(from);
+    if (!imported) throw new Error('unreachable: `imported` is undefined');
 
     if (tokenImporter.type === 'value') {
-      const exportRecord = exportBuilder.build(imported);
+      const exportRecord = args.getExportRecord(imported);
       for (const value of tokenImporter.values) {
         if (!exportRecord.allTokens.includes(value.name)) {
           diagnostics.push(createModuleHasNoExportedTokenDiagnostic(cssModule, tokenImporter, value));

package/src/config.ts

@@ -13,6 +13,7 @@ const DEFAULT_INCLUDE_SPEC = '**/*';
 export interface CMKConfig {
   includes: string[];
   excludes: string[];
+  enabled: boolean | undefined;
   dtsOutDir: string;
   arbitraryExtensions: boolean;
   namedExports: boolean;
@@ -71,6 +72,7 @@ export interface CMKConfig {
 interface UnnormalizedRawConfig {
   includes?: string[];
   excludes?: string[];
+  enabled?: boolean;
   dtsOutDir?: string;
   arbitraryExtensions?: boolean;
   namedExports?: boolean;
@@ -124,6 +126,16 @@ function parseRawData(raw: unknown, tsConfigSourceFile: ts.TsConfigSourceFile):
     // MEMO: The errors for this option are reported by `tsc` or `tsserver`, so we don't need to report.
   }
   if ('cmkOptions' in raw && typeof raw.cmkOptions === 'object' && raw.cmkOptions !== null) {
+    if ('enabled' in raw.cmkOptions) {
+      if (typeof raw.cmkOptions.enabled === 'boolean') {
+        result.config.enabled = raw.cmkOptions.enabled;
+      } else {
+        result.diagnostics.push({
+          category: 'error',
+          text: `\`enabled\` in ${tsConfigSourceFile.fileName} must be a boolean.`,
+        });
+      }
+    }
     if ('dtsOutDir' in raw.cmkOptions) {
       if (typeof raw.cmkOptions.dtsOutDir === 'string') {
         result.config.dtsOutDir = raw.cmkOptions.dtsOutDir;
@@ -255,6 +267,7 @@ export function readConfigFile(project: string): CMKConfig {
     namedExports: parsedTsConfig.config.namedExports ?? false,
     prioritizeNamedImports: parsedTsConfig.config.prioritizeNamedImports ?? false,
     keyframes: parsedTsConfig.config.keyframes ?? true,
+    enabled: parsedTsConfig.config.enabled,
     basePath,
     configFileName,
     compilerOptions: parsedTsConfig.compilerOptions,

package/src/diagnostic.ts

@@ -11,6 +11,8 @@ function convertErrorCategory(category: DiagnosticCategory): ts.DiagnosticCatego
   switch (category) {
     case 'error':
       return ts.DiagnosticCategory.Error;
+    case 'warning':
+      return ts.DiagnosticCategory.Warning;
     default:
       throw new Error(`Unknown category: ${String(category)}`);
   }

package/src/dts-generator.ts

@@ -1,13 +1,8 @@
-import type { CSSModule, MatchesPattern, Resolver, Token, TokenImporter } from './type.js';
-import { isValidAsJSIdentifier } from './util.js';
+import type { CSSModule, Token, TokenImporter } from './type.js';
+import { isURLSpecifier, isValidAsJSIdentifier } from './util.js';
 
 export const STYLES_EXPORT_NAME = 'styles';
 
-export interface GenerateDtsHost {
-  resolver: Resolver;
-  matchesPattern: MatchesPattern;
-}
-
 export interface GenerateDtsOptions {
   namedExports: boolean;
   prioritizeNamedImports: boolean;
@@ -46,11 +41,7 @@ interface GenerateDtsResult {
 /**
  * Generate .d.ts from `CSSModule`.
  */
-export function generateDts(
-  cssModule: CSSModule,
-  host: GenerateDtsHost,
-  options: GenerateDtsOptions,
-): GenerateDtsResult {
+export function generateDts(cssModule: CSSModule, options: GenerateDtsOptions): GenerateDtsResult {
   // Exclude invalid tokens
   const localTokens = cssModule.localTokens.filter((token) => isValidName(token.name, options));
   const tokenImporters = cssModule.tokenImporters
@@ -69,10 +60,43 @@ export function generateDts(
         return tokenImporter;
       }
     })
-    // Exclude token importers for external files
     .filter((tokenImporter) => {
-      const resolved = host.resolver(tokenImporter.from, { request: cssModule.fileName });
-      return resolved !== undefined && host.matchesPattern(resolved);
+      /**
+       * In principle, token importers with specifiers that cannot be resolved are still included in the type
+       * definitions. For example, consider the following:
+       *
+       * ```css
+       * // src/a.module.css
+       * @import './unresolved.module.css';
+       * @import './unmatched.css';
+       * .a_1 { color: red; }
+       * ```
+       *
+       * In this case, CSS Modules Kit generates the following type definitions:
+       *
+       * ```ts
+       * // generated/src/a.module.css.d.ts
+       * // @ts-nocheck
+       * declare const styles = {
+       *   a_1: '' as readonly string,
+       *   ...(await import('./unresolved.module.css')).default,
+       *   ...(await import('./unmatched.css')).default,
+       * };
+       * ```
+       *
+       * Even if `./unresolved.module.css` or `./unmatched.css` does not exist, the same type definitions are
+       * generated. It is important that the generated type definitions do not change depending on whether the
+       * files exist. This provides the following benefits:
+       *
+       * - Simplifies the watch mode implementation
+       *   - Only the type definitions for changed files need to be regenerated
+       * - Makes it easier to parallelize code generation
+       *   - Type definitions can be generated independently per file
+       *
+       * However, as an exception, URL specifiers are not included in the type definitions, because URL
+       * specifiers are typically resolved at runtime.
+       */
+      return !isURLSpecifier(tokenImporter.from);
     });
 
   if (options.namedExports) {
@@ -82,28 +106,7 @@ export function generateDts(
   }
 }
 
-/**
- * Generate a d.ts file with named exports.
- * @example
- * If the CSS module file is:
- * ```css
- * @import './a.module.css';
- * @value local1: string;
- * @value imported1, imported2 as aliasedImported2 from './b.module.css';
- * .local2 { color: red }
- * ```
- * The d.ts file would be:
- * ```ts
- * // @ts-nocheck
- * export var local1: string;
- * export var local2: string;
- * export * from './a.module.css';
- * export {
- *   imported1,
- *   imported2 as aliasedImported2,
- * } from './b.module.css';
- * ```
- */
+/** Generate a d.ts file with named exports. */
 function generateNamedExportsDts(
   localTokens: Token[],
   tokenImporters: TokenImporter[],
@@ -125,6 +128,25 @@ function generateNamedExportsDts(
   let text = `// @ts-nocheck\n`;
 
   for (const token of localTokens) {
+    /**
+     * The mapping is created as follows:
+     * a.module.css:
+     * 1 | .a_1 { color: red; }
+     *   |  ^ mapping.sourceOffsets[0]
+     *   |
+     * 2 | .a_2 { color: blue; }
+     *   |  ^ mapping.sourceOffsets[1]
+     *   |
+     *
+     * a.module.css.d.ts:
+     * 1 | // @ts-nocheck
+     * 2 | export var a_1: string;
+     *   |            ^ mapping.generatedOffsets[0]
+     *   |
+     * 3 | export var a_2: string;
+     *   |            ^ mapping.generatedOffsets[1]
+     */
+
     text += `export var `;
     mapping.sourceOffsets.push(token.loc.start.offset);
     mapping.generatedOffsets.push(text.length);
@@ -133,12 +155,71 @@ function generateNamedExportsDts(
   }
   for (const tokenImporter of tokenImporters) {
     if (tokenImporter.type === 'import') {
+      /**
+       * The mapping is created as follows:
+       * a.module.css:
+       * 1 | @import './b.module.css';
+       *   |         ^ mapping.sourceOffsets[0]
+       *   |
+       * 2 | @import './c.module.css';
+       *   |         ^ mapping.sourceOffsets[1]
+       *   |
+       *
+       * a.module.css.d.ts:
+       * 1 | // @ts-nocheck
+       * 2 | export * from './b.module.css';
+       *   |               ^ mapping.generatedOffsets[0]
+       *   |
+       * 3 | export * from './c.module.css';
+       *   |               ^ mapping.generatedOffsets[1]
+       *
+       * NOTE: Not only the specifier but also the surrounding quotes are included in the mapping.
+       */
+
       text += `export * from `;
       mapping.sourceOffsets.push(tokenImporter.fromLoc.start.offset - 1);
       mapping.lengths.push(tokenImporter.from.length + 2);
       mapping.generatedOffsets.push(text.length);
       text += `'${tokenImporter.from}';\n`;
     } else {
+      /**
+       * The mapping is created as follows:
+       * a.module.css:
+       * 1 | @value b_1, b_2 from './b.module.css';
+       *   |        ^    ^        ^ mapping.sourceOffsets[2]
+       *   |        ^    ^ mapping.sourceOffsets[1]
+       *   |        ^ mapping.sourceOffsets[0]
+       *   |
+       * 2 | @value c_1 as aliased_c_1 from './c.module.css';
+       *   |        ^      ^                ^ mapping.sourceOffsets[5]
+       *   |        ^      ^ mapping.sourceOffsets[4]
+       *   |        ^ mapping.sourceOffsets[3]
+       *   |
+       *
+       * a.module.css.d.ts:
+       * 1 | // @ts-nocheck
+       * 2 | export {
+       * 3 |   b_1,
+       *   |   ^ mapping.generatedOffsets[0]
+       *   |
+       * 4 |   b_2,
+       *   |   ^ mapping.generatedOffsets[1]
+       *   |
+       * 5 | } from './b.module.css';
+       *   |        ^ mapping.generatedOffsets[2]
+       *   |
+       * 6 | export {
+       * 7 |   c_1 as aliased_c_1,
+       *   |   ^      ^ mapping.generatedOffsets[4], linkedCodeMapping.sourceOffsets[0]
+       *   |   ^ mapping.generatedOffsets[3], linkedCodeMapping.generatedOffsets[0]
+       *   |
+       * 8 | } from './c.module.css';
+       *   |        ^ mapping.generatedOffsets[5]
+       *
+       * NOTE: Not only the specifier but also the surrounding quotes are included in the mapping.
+       * NOTE: linkedCodeMapping is only generated for tokens that have a `localName` (i.e., aliased tokens).
+       */
+
       text += `export {\n`;
       // eslint-disable-next-line no-loop-func
       tokenImporter.values.forEach((value) => {
@@ -179,29 +260,7 @@ function generateNamedExportsDts(
   return { text, mapping, linkedCodeMapping };
 }
 
-/**
- * Generate a d.ts file with a default export.
- * @example
- * If the CSS module file is:
- * ```css
- * @import './a.module.css';
- * @value local1: string;
- * @value imported1, imported2 as aliasedImported2 from './b.module.css';
- * .local2 { color: red }
- * ```
- * The d.ts file would be:
- * ```ts
- * // @ts-nocheck
- * const styles = {
- *   local1: '' as readonly string,
- *   local2: '' as readonly string,
- *   ...(await import('./a.module.css')).default,
- *   imported1: (await import('./b.module.css')).default.imported1,
- *   aliasedImported2: (await import('./b.module.css')).default.imported2,
- * };
- * export default styles;
- * ```
- */
+/** Generate a d.ts file with a default export. */
 function generateDefaultExportDts(
   localTokens: Token[],
   tokenImporters: TokenImporter[],
@@ -219,9 +278,40 @@ function generateDefaultExportDts(
   //
   // If `--skipLibCheck` is false, those errors will be reported by `tsc`. However, these are negligible errors.
   // Therefore, `@ts-nocheck` is added to the generated type definition file.
-  let text = `// @ts-nocheck\ndeclare const ${STYLES_EXPORT_NAME} = {\n`;
+  let text = `// @ts-nocheck\n`;
 
+  // This is a workaround to avoid the issue described as a "Drawbacks" in https://github.com/mizdra/css-modules-kit/pull/302.
+  // It uses the technique from https://stackoverflow.com/a/55541672 to fall back from `any` to `{}`.
+  // However, the import type for an unresolvable specifier becomes a special `any` type called `errorType`.
+  // The technique from https://stackoverflow.com/a/55541672 does not work with `errorType`.
+  // Therefore, this combines it with the approach from https://github.com/microsoft/TypeScript/issues/62972.
+  if (tokenImporters.some((importer) => importer.type === 'import')) {
+    text += `function blockErrorType<T>(val: T): [0] extends [(1 & T)] ? {} : T;\n`;
+  }
+
+  text += `declare const ${STYLES_EXPORT_NAME} = {\n`;
   for (const token of localTokens) {
+    /**
+     * The mapping is created as follows:
+     * a.module.css:
+     * 1 | .a_1 { color: red; }
+     *   |  ^ mapping.sourceOffsets[0]
+     *   |
+     * 2 | .a_2 { color: blue; }
+     *   |  ^ mapping.sourceOffsets[1]
+     *   |
+     *
+     * a.module.css.d.ts:
+     * 1 | declare const styles = {
+     * 2 |   a_1: '' as readonly string,
+     *   |   ^ mapping.generatedOffsets[0]
+     *   |
+     * 3 |   a_2: '' as readonly string,
+     *   |   ^ mapping.generatedOffsets[1]
+     *   |
+     * 4 | };
+     */
+
     text += `  `;
     mapping.sourceOffsets.push(token.loc.start.offset);
     mapping.generatedOffsets.push(text.length);
@@ -230,12 +320,70 @@ function generateDefaultExportDts(
   }
   for (const tokenImporter of tokenImporters) {
     if (tokenImporter.type === 'import') {
-      text += `  ...(await import(`;
+      /**
+       * The mapping is created as follows:
+       * a.module.css:
+       * 1 | @import './b.module.css';
+       *   |         ^ mapping.sourceOffsets[0]
+       *   |
+       * 2 | @import './c.module.css';
+       *   |         ^ mapping.sourceOffsets[1]
+       *   |
+       *
+       * a.module.css.d.ts:
+       * 1 | declare const styles = {
+       * 2 |   ...blockErrorType((await import('./b.module.css')).default),
+       *   |                                   ^ mapping.generatedOffsets[0]
+       *   |
+       * 3 |   ...blockErrorType((await import('./c.module.css')).default),
+       *   |                                   ^ mapping.generatedOffsets[1]
+       *   |
+       * 4 | };
+       *
+       * NOTE: Not only the specifier but also the surrounding quotes are included in the mapping.
+       */
+
+      text += `  ...blockErrorType((await import(`;
       mapping.sourceOffsets.push(tokenImporter.fromLoc.start.offset - 1);
       mapping.lengths.push(tokenImporter.from.length + 2);
       mapping.generatedOffsets.push(text.length);
-      text += `'${tokenImporter.from}')).default,\n`;
+      text += `'${tokenImporter.from}')).default),\n`;
     } else {
+      /**
+       * The mapping is created as follows:
+       * a.module.css:
+       * 1 | @value b_1, b_2 from './b.module.css';
+       *   |        ^    ^        ^ mapping.sourceOffsets[0]
+       *   |        ^    ^ mapping.sourceOffsets[2]
+       *   |        ^ mapping.sourceOffsets[1]
+       *   |
+       * 2 | @value c_1 as aliased_c_1 from './c.module.css';
+       *   |        ^      ^                ^ mapping.sourceOffsets[4]
+       *   |        ^      ^ mapping.sourceOffsets[3]
+       *   |        ^ mapping.sourceOffsets[5]
+       *   |
+       *
+       * a.module.css.d.ts:
+       * 1 | declare const styles = {
+       * 2 |   b_1: (await import('./b.module.css')).default.b_1,
+       *   |   ^                  ^                          ^ linkedCodeMapping.generatedOffsets[0]
+       *   |   ^                  ^ mapping.generatedOffsets[1]
+       *   |   ^ mapping.generatedOffsets[0], linkedCodeMapping.sourceOffsets[0]
+       *   |
+       * 3 |   b_2: (await import('./b.module.css')).default.b_2,
+       *   |   ^                                             ^ linkedCodeMapping.generatedOffsets[1]
+       *   |   ^ mapping.generatedOffsets[2], linkedCodeMapping.sourceOffsets[1]
+       *   |
+       * 4 |   aliased_c_1: (await import('./c.module.css')).default.c_1,
+       *   |   ^                          ^                          ^ mapping.generatedOffsets[5], linkedCodeMapping.generatedOffsets[2]
+       *   |   ^                          ^ mapping.generatedOffsets[4]
+       *   |   ^ mapping.generatedOffsets[3], linkedCodeMapping.sourceOffsets[2]
+       *   |
+       * 5 | };
+       *
+       * NOTE: Not only the specifier but also the surrounding quotes are included in the mapping.
+       */
+
       // eslint-disable-next-line no-loop-func
       tokenImporter.values.forEach((value, i) => {
         const localName = value.localName ?? value.name;
@@ -254,9 +402,11 @@ function generateDefaultExportDts(
           mapping.generatedOffsets.push(text.length);
         }
         text += `'${tokenImporter.from}')).default.`;
-        mapping.sourceOffsets.push(value.loc.start.offset);
-        mapping.lengths.push(value.name.length);
-        mapping.generatedOffsets.push(text.length);
+        if ('localName' in value) {
+          mapping.sourceOffsets.push(value.loc.start.offset);
+          mapping.lengths.push(value.name.length);
+          mapping.generatedOffsets.push(text.length);
+        }
         linkedCodeMapping.generatedOffsets.push(text.length);
         linkedCodeMapping.generatedLengths.push(value.name.length);
         text += `${value.name},\n`;

package/src/index.ts

@@ -15,6 +15,7 @@ export {
   type Resolver,
   type MatchesPattern,
   type ExportBuilder,
+  type ExportRecord,
   type DiagnosticSourceFile,
   type Diagnostic,
   type DiagnosticWithLocation,
@@ -33,8 +34,8 @@ export {
   createMatchesPattern,
   getFileNamesByPattern,
 } from './file.js';
-export { checkCSSModule } from './checker.js';
+export { checkCSSModule, type CheckerArgs } from './checker.js';
 export { createExportBuilder } from './export-builder.js';
-export { join, resolve, relative, dirname, basename, parse, isAbsolute } from './path.js';
+export { join, resolve, relative, dirname, basename, parse } from './path.js';
 export { findUsedTokenNames } from './util.js';
 export { convertDiagnostic, convertDiagnosticWithLocation, convertSystemError } from './diagnostic.js';

package/src/path.ts

@@ -32,6 +32,3 @@ export function parse(path: string): ParsedPath {
   const { root, dir, base, name, ext } = nodePath.parse(path);
   return { root: slash(root), dir: slash(dir), base, name, ext };
 }
-
-// eslint-disable-next-line @typescript-eslint/unbound-method
-export const isAbsolute = nodePath.isAbsolute;

package/src/resolver.ts

@@ -1,21 +1,19 @@
-import { fileURLToPath, pathToFileURL } from 'node:url';
 import type { CompilerOptions } from 'typescript';
 import ts from 'typescript';
-import { isAbsolute, resolve } from './path.js';
 import type { Resolver, ResolverOptions } from './type.js';
+import { isURLSpecifier } from './util.js';
 
 export function createResolver(
   compilerOptions: CompilerOptions,
   moduleResolutionCache: ts.ModuleResolutionCache | undefined,
 ): Resolver {
-  return (_specifier: string, options: ResolverOptions) => {
-    let specifier = _specifier;
-
+  return (specifier: string, options: ResolverOptions) => {
+    if (isURLSpecifier(specifier)) return undefined;
     const host: ts.ModuleResolutionHost = {
       ...ts.sys,
       fileExists: (fileName) => {
-        if (fileName.endsWith('.module.d.css.ts')) {
-          return ts.sys.fileExists(fileName.replace(/\.module\.d\.css\.ts$/u, '.module.css'));
+        if (fileName.endsWith('.d.css.ts')) {
+          return ts.sys.fileExists(fileName.replace(/\.d\.css\.ts$/u, '.css'));
         }
         return ts.sys.fileExists(fileName);
       },
@@ -28,28 +26,8 @@ export function createResolver(
       moduleResolutionCache,
     );
     if (resolvedModule) {
-      // TODO: Logging that the paths is used.
-      specifier = resolvedModule.resolvedFileName.replace(/\.module\.d\.css\.ts$/u, '.module.css');
-    }
-    if (isAbsolute(specifier)) {
-      return resolve(specifier);
-    } else if (isRelativeSpecifier(specifier)) {
-      // Convert the specifier to an absolute path
-      // NOTE: Node.js resolves relative specifier with standard relative URL resolution semantics. So we will follow that here as well.
-      // ref: https://nodejs.org/docs/latest-v23.x/api/esm.html#terminology
-      return resolve(fileURLToPath(new URL(specifier, pathToFileURL(options.request)).href));
-    } else {
-      // Do not support URL or bare specifiers
-      // TODO: Logging that the specifier could not resolve.
-      return undefined;
+      return resolvedModule.resolvedFileName.replace(/\.d\.css\.ts$/u, '.css');
     }
+    return undefined;
   };
 }
-
-/**
- * Check if the specifier is a relative specifier.
- * @see https://nodejs.org/docs/latest-v23.x/api/esm.html#terminology
- */
-function isRelativeSpecifier(specifier: string): boolean {
-  return specifier.startsWith('./') || specifier.startsWith('../');
-}

package/src/type.ts

@@ -151,7 +151,7 @@ export interface ExportBuilder {
   clearCache(): void;
 }
 
-export type DiagnosticCategory = 'error';
+export type DiagnosticCategory = 'error' | 'warning';
 
 export interface DiagnosticSourceFile {
   fileName: string;

package/src/typing/typescript.d.ts

@@ -5,7 +5,7 @@ declare module 'typescript' {
     readonly files: readonly string[];
     readonly directories: readonly string[];
   }
-  // eslint-disable-next-line max-params
+
   export function matchFiles(
     path: string,
     extensions: readonly string[] | undefined,

package/src/util.ts

@@ -25,3 +25,7 @@ export function findUsedTokenNames(componentText: string): Set<string> {
   }
   return usedClassNames;
 }
+
+export function isURLSpecifier(specifier: string): boolean {
+  return URL.canParse(specifier);
+}