@css-modules-kit/core 0.0.1

package/src/dts-creator.ts

@@ -0,0 +1,128 @@
+import type { MatchesPattern } from './file.js';
+import type { CSSModule } from './parser/css-module-parser.js';
+import type { Resolver } from './resolver.js';
+
+export const STYLES_EXPORT_NAME = 'styles';
+
+export interface CreateDtsOptions {
+  resolver: Resolver;
+  matchesPattern: MatchesPattern;
+}
+
+interface CodeMapping {
+  /** The source offsets of the tokens in the *.module.css file. */
+  sourceOffsets: number[];
+  /** The lengths of the tokens in the *.module.css file. */
+  lengths: number[];
+  /** The generated offsets of the tokens in the *.d.ts file. */
+  generatedOffsets: number[];
+}
+
+/** The map linking the two codes in *.d.ts */
+// NOTE: `sourceOffsets` and `generatedOffsets` are interchangeable. Exchanging code assignments does not change the behavior.
+interface LinkedCodeMapping extends CodeMapping {
+  /** The offset of the first code to be linked. */
+  sourceOffsets: number[];
+  /** The length of the first code to be linked. */
+  lengths: number[];
+  /** The offset of the second code to be linked. */
+  generatedOffsets: number[];
+  /** The length of the second code to be linked. */
+  generatedLengths: number[];
+}
+
+/**
+ * Create a d.ts file from a CSS module file.
+ * @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
+ * 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;
+ * ```
+ */
+export function createDts(
+  { fileName, localTokens, tokenImporters: _tokenImporters }: CSSModule,
+  options: CreateDtsOptions,
+): { text: string; mapping: CodeMapping; linkedCodeMapping: LinkedCodeMapping } {
+  const mapping: CodeMapping = { sourceOffsets: [], lengths: [], generatedOffsets: [] };
+  const linkedCodeMapping: LinkedCodeMapping = {
+    sourceOffsets: [],
+    lengths: [],
+    generatedOffsets: [],
+    generatedLengths: [],
+  };
+
+  // Filter external files
+  const tokenImporters = _tokenImporters.filter((tokenImporter) => {
+    const resolved = options.resolver(tokenImporter.from, { request: fileName });
+    return resolved !== undefined && options.matchesPattern(resolved);
+  });
+
+  // If the CSS module file has no tokens, return an .d.ts file with an empty object.
+  if (localTokens.length === 0 && tokenImporters.length === 0) {
+    return {
+      text: `declare const ${STYLES_EXPORT_NAME} = {};\nexport default ${STYLES_EXPORT_NAME};\n`,
+      mapping,
+      linkedCodeMapping,
+    };
+  }
+
+  let text = `declare const ${STYLES_EXPORT_NAME} = {\n`;
+  for (const token of localTokens) {
+    text += `  `;
+    mapping.sourceOffsets.push(token.loc.start.offset);
+    mapping.generatedOffsets.push(text.length);
+    mapping.lengths.push(token.name.length);
+    text += `${token.name}: '' as readonly string,\n`;
+  }
+  for (const tokenImporter of tokenImporters) {
+    if (tokenImporter.type === 'import') {
+      text += `  ...(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`;
+    } else {
+      // eslint-disable-next-line no-loop-func
+      tokenImporter.values.forEach((value, i) => {
+        const localName = value.localName ?? value.name;
+        const localLoc = value.localLoc ?? value.loc;
+
+        text += `  `;
+        mapping.sourceOffsets.push(localLoc.start.offset);
+        mapping.lengths.push(localName.length);
+        mapping.generatedOffsets.push(text.length);
+        linkedCodeMapping.sourceOffsets.push(text.length);
+        linkedCodeMapping.lengths.push(localName.length);
+        text += `${localName}: (await import(`;
+        if (i === 0) {
+          mapping.sourceOffsets.push(tokenImporter.fromLoc.start.offset - 1);
+          mapping.lengths.push(tokenImporter.from.length + 2);
+          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);
+        linkedCodeMapping.generatedOffsets.push(text.length);
+        linkedCodeMapping.generatedLengths.push(value.name.length);
+        text += `${value.name},\n`;
+      });
+    }
+  }
+  text += `};\nexport default ${STYLES_EXPORT_NAME};\n`;
+  return { text, mapping, linkedCodeMapping };
+}

package/src/error.ts

@@ -0,0 +1,13 @@
+export class SystemError extends Error {
+  code: string;
+  constructor(code: string, message: string, cause?: unknown) {
+    super(message, { cause });
+    this.code = code;
+  }
+}
+
+export class TsConfigFileNotFoundError extends SystemError {
+  constructor() {
+    super('TS_CONFIG_NOT_FOUND', 'No tsconfig.json found.');
+  }
+}

package/src/export-builder.ts

@@ -0,0 +1,51 @@
+import type { MatchesPattern } from './file.js';
+import type { CSSModule } from './parser/css-module-parser.js';
+import type { Resolver } from './resolver.js';
+
+export interface ExportBuilderHost {
+  matchesPattern: MatchesPattern;
+  getCSSModule: (path: string) => CSSModule | undefined;
+  resolver: Resolver;
+}
+
+/**
+ * The export token record of a CSS module.
+ */
+export interface ExportRecord {
+  /** The all exported tokens of the CSS module. */
+  allTokens: string[];
+}
+
+export interface ExportBuilder {
+  build(cssModule: CSSModule): ExportRecord;
+}
+
+/**
+ * A builder for exported token records of CSS modules.
+ */
+// TODO: Add cache
+// TODO: Add support for circular dependencies
+// TODO: Handle same token name from different modules
+export function createExportBuilder(host: ExportBuilderHost): ExportBuilder {
+  function build(cssModule: CSSModule): ExportRecord {
+    const result: ExportRecord = { allTokens: [...cssModule.localTokens.map((t) => t.name)] };
+
+    for (const tokenImporter of cssModule.tokenImporters) {
+      const from = host.resolver(tokenImporter.from, { request: cssModule.fileName });
+      if (!from || !host.matchesPattern(from)) continue;
+      const imported = host.getCSSModule(from);
+      if (!imported) continue;
+
+      const importedResult = build(imported);
+      if (tokenImporter.type === 'import') {
+        result.allTokens.push(...importedResult.allTokens);
+      } else {
+        for (const value of tokenImporter.values) {
+          result.allTokens.push(value.name);
+        }
+      }
+    }
+    return result;
+  }
+  return { build };
+}

package/src/file.ts

@@ -0,0 +1,83 @@
+import ts from 'typescript';
+import { join, parse } from './path.js';
+
+export const CSS_MODULE_EXTENSION = '.module.css';
+const COMPONENT_EXTENSIONS = ['.tsx', '.jsx'];
+
+export function isCSSModuleFile(fileName: string): boolean {
+  return fileName.endsWith(CSS_MODULE_EXTENSION);
+}
+
+export function getCssModuleFileName(tsFileName: string): string {
+  const { dir, name } = parse(tsFileName);
+  return join(dir, `${name}${CSS_MODULE_EXTENSION}`);
+}
+
+export function isComponentFileName(fileName: string): boolean {
+  // NOTE: Do not check whether it is an upper camel case or not, since lower camel case (e.g. `page.tsx`) is used in Next.js.
+  return COMPONENT_EXTENSIONS.some((ext) => fileName.endsWith(ext));
+}
+
+export async function findComponentFile(
+  cssModuleFileName: string,
+  readFile: (path: string) => Promise<string>,
+): Promise<{ fileName: string; text: string } | undefined> {
+  const pathWithoutExtension = cssModuleFileName.slice(0, -CSS_MODULE_EXTENSION.length);
+  for (const path of COMPONENT_EXTENSIONS.map((ext) => pathWithoutExtension + ext)) {
+    try {
+      // TODO: Cache the result of readFile
+      // eslint-disable-next-line no-await-in-loop
+      const text = await readFile(path);
+      return { fileName: path, text };
+    } catch {
+      continue;
+    }
+  }
+  return undefined;
+}
+
+export type MatchesPattern = (fileName: string) => boolean;
+
+/**
+ * Create a function that checks whether the given file name matches the pattern.
+ * This does not access the file system.
+ * @param options
+ * @returns
+ */
+export function createMatchesPattern(options: { includes: string[]; excludes: string[] }): MatchesPattern {
+  // Setup utilities to check for pattern matches without accessing the file system
+  const realpath = (path: string) => path;
+  const getFileSystemEntries = (path: string): ts.FileSystemEntries => {
+    return {
+      files: [path],
+      directories: [],
+    };
+  };
+
+  return (fileName: string) => {
+    const matchedFileNames = ts.matchFiles(
+      fileName,
+      [CSS_MODULE_EXTENSION],
+      options.excludes,
+      options.includes,
+      ts.sys.useCaseSensitiveFileNames,
+      '', // `fileName`, `includes`, and `excludes` are absolute paths, so `currentDirectory` is not needed.
+      undefined,
+      getFileSystemEntries,
+      realpath,
+    );
+    return matchedFileNames.length > 0;
+  };
+}
+
+/**
+ * Get files matched by the pattern.
+ */
+export function getFileNamesByPattern(options: { basePath: string; includes: string[]; excludes: string[] }): string[] {
+  // ref: https://github.com/microsoft/TypeScript/blob/caf1aee269d1660b4d2a8b555c2d602c97cb28d7/src/compiler/commandLineParser.ts#L3929
+
+  // MEMO: `ts.sys.readDirectory` catch errors internally. So we don't need to wrap with try-catch.
+  // https://github.com/microsoft/TypeScript/blob/caf1aee269d1660b4d2a8b555c2d602c97cb28d7/src/compiler/sys.ts#L1877-L1879
+
+  return ts.sys.readDirectory(options.basePath, [CSS_MODULE_EXTENSION], options.excludes, options.includes);
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+export type { CMKConfig } from './config.js';
+export { readConfigFile } from './config.js';
+export { TsConfigFileNotFoundError, SystemError } from './error.js';
+export {
+  parseCSSModule,
+  type ParseCSSModuleOptions,
+  type CSSModule,
+  type Token,
+  type AtImportTokenImporter,
+  type TokenImporter,
+  type AtValueTokenImporter,
+  type AtValueTokenImporterValue,
+  type ParseCSSModuleResult,
+} from './parser/css-module-parser.js';
+export { type Location, type Position } from './parser/location.js';
+export { parseRule } from './parser/rule-parser.js';
+export {
+  type Diagnostic,
+  type SemanticDiagnostic,
+  type SyntacticDiagnostic,
+  type DiagnosticCategory,
+  type DiagnosticPosition,
+} from './diagnostic.js';
+export { type CreateDtsOptions, createDts, STYLES_EXPORT_NAME } from './dts-creator.js';
+export { createResolver, type Resolver } from './resolver.js';
+export {
+  CSS_MODULE_EXTENSION,
+  getCssModuleFileName,
+  isComponentFileName,
+  isCSSModuleFile,
+  findComponentFile,
+  type MatchesPattern,
+  createMatchesPattern,
+  getFileNamesByPattern,
+} from './file.js';
+export { checkCSSModule } from './checker.js';
+export { type ExportBuilder, createExportBuilder } from './export-builder.js';
+export { join, resolve, relative, dirname, basename, parse, matchesGlob, isAbsolute } from './path.js';

package/src/parser/at-import-parser.ts

@@ -0,0 +1,47 @@
+import type { AtRule } from 'postcss';
+import postcssValueParser from 'postcss-value-parser';
+import type { Location } from './location.js';
+
+interface ParsedAtImport {
+  from: string;
+  fromLoc: Location;
+}
+
+/**
+ * Parse the `@import` rule.
+ * @param atImport The `@import` rule to parse.
+ * @returns The specifier of the imported file.
+ */
+export function parseAtImport(atImport: AtRule): ParsedAtImport | undefined {
+  const firstNode = postcssValueParser(atImport.params).nodes[0];
+  if (firstNode === undefined) return undefined;
+  if (firstNode.type === 'string') return convertParsedAtImport(atImport, firstNode);
+  if (firstNode.type === 'function' && firstNode.value === 'url') {
+    if (firstNode.nodes[0] === undefined) return undefined;
+    if (firstNode.nodes[0].type === 'string') return convertParsedAtImport(atImport, firstNode.nodes[0]);
+    if (firstNode.nodes[0].type === 'word') return convertParsedAtImport(atImport, firstNode.nodes[0]);
+  }
+  return undefined;
+}
+
+function convertParsedAtImport(
+  atImport: AtRule,
+  node: postcssValueParser.StringNode | postcssValueParser.WordNode,
+): ParsedAtImport {
+  // The length of the `@import  ` part in `@import  '...'`
+  const baseLength = 7 + (atImport.raws.afterName?.length ?? 0);
+  const start = {
+    line: atImport.source!.start!.line,
+    column: atImport.source!.start!.column + baseLength + node.sourceIndex + (node.type === 'string' ? 1 : 0),
+    offset: atImport.source!.start!.offset + baseLength + node.sourceIndex + (node.type === 'string' ? 1 : 0),
+  };
+  const end = {
+    line: start.line,
+    column: start.column + node.value.length,
+    offset: start.offset + node.value.length,
+  };
+  return {
+    from: node.value,
+    fromLoc: { start, end },
+  };
+}

package/src/parser/at-value-parser.ts

@@ -0,0 +1,177 @@
+import type { AtRule } from 'postcss';
+import type { DiagnosticPosition, SyntacticDiagnostic } from '../diagnostic.js';
+import type { Location } from './location.js';
+
+interface ValueDeclaration {
+  type: 'valueDeclaration';
+  name: string;
+  // value: string; // unused
+  loc: Location;
+}
+
+interface ValueImportDeclaration {
+  type: 'valueImportDeclaration';
+  values: {
+    name: string;
+    loc: Location;
+    localName?: string;
+    localLoc?: Location;
+  }[];
+  from: string;
+  fromLoc: Location;
+}
+
+type ParsedAtValue = ValueDeclaration | ValueImportDeclaration;
+
+interface ParseAtValueResult {
+  atValue?: ParsedAtValue;
+  diagnostics: SyntacticDiagnostic[];
+}
+
+const VALUE_IMPORT_PATTERN = /^(.+?)\s+from\s+("[^"]*"|'[^']*')$/du;
+const VALUE_DEFINITION_PATTERN = /(?:\s+|^)([\w-]+):?(.*?)$/du;
+const IMPORTED_ITEM_PATTERN = /^([\w-]+)(?:\s+as\s+([\w-]+))?/du;
+
+/**
+ * Parse the `@value` rule.
+ * Forked from https://github.com/css-modules/postcss-modules-values/blob/v4.0.0/src/index.js.
+ *
+ * @license
+ * ISC License (ISC)
+ * Copyright (c) 2015, Glen Maddern
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted,
+ * provided that the above copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING
+ * ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+ * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+ * WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH
+ * THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+// MEMO: css-modules-kit does not support `@value` with parentheses (e.g., `@value (a, b) from '...';`) to simplify the implementation.
+// MEMO: css-modules-kit does not support `@value` with variable module name (e.g., `@value a from moduleName;`) to simplify the implementation.
+export function parseAtValue(atValue: AtRule): ParseAtValueResult {
+  const matchesForValueImport = atValue.params.match(VALUE_IMPORT_PATTERN);
+  const diagnostics: SyntacticDiagnostic[] = [];
+  if (matchesForValueImport) {
+    const [, importedItems, from] = matchesForValueImport as [string, string, string];
+    // The length of the `@value  ` part in `@value  import1 from '...'`
+    const baseLength = 6 + (atValue.raws.afterName?.length ?? 0);
+
+    let lastItemIndex = 0;
+    const values: ValueImportDeclaration['values'] = [];
+    for (const alias of importedItems.split(/\s*,\s*/u)) {
+      const currentItemIndex = importedItems.indexOf(alias, lastItemIndex);
+      lastItemIndex = currentItemIndex;
+      const matchesForImportedItem = alias.match(IMPORTED_ITEM_PATTERN);
+
+      if (matchesForImportedItem) {
+        const [, name, localName] = matchesForImportedItem as [string, string, string | undefined];
+        const nameIndex = matchesForImportedItem.indices![1]![0];
+        const start = {
+          line: atValue.source!.start!.line,
+          column: atValue.source!.start!.column + baseLength + currentItemIndex + nameIndex,
+          offset: atValue.source!.start!.offset + baseLength + currentItemIndex + nameIndex,
+        };
+        const end = {
+          line: start.line,
+          column: start.column + name.length,
+          offset: start.offset + name.length,
+        };
+        const result = { name, loc: { start, end } };
+        if (localName === undefined) {
+          values.push(result);
+        } else {
+          const localNameIndex = matchesForImportedItem.indices![2]![0];
+          const start = {
+            line: atValue.source!.start!.line,
+            column: atValue.source!.start!.column + baseLength + currentItemIndex + localNameIndex,
+            offset: atValue.source!.start!.offset + baseLength + currentItemIndex + localNameIndex,
+          };
+          const end = {
+            line: start.line,
+            column: start.column + localName.length,
+            offset: start.offset + localName.length,
+          };
+          values.push({ ...result, localName, localLoc: { start, end } });
+        }
+      } else {
+        const start: DiagnosticPosition = {
+          line: atValue.source!.start!.line,
+          column: atValue.source!.start!.column + baseLength + currentItemIndex,
+        };
+        const end: DiagnosticPosition = {
+          line: start.line,
+          column: start.column + alias.length,
+        };
+        diagnostics.push({
+          type: 'syntactic',
+          fileName: atValue.source!.input.file!,
+          start,
+          end,
+          text: `\`${alias}\` is invalid syntax.`,
+          category: 'error',
+        });
+      }
+    }
+
+    // `from` is surrounded by quotes (e.g., `"./test.module.css"`). So, remove the quotes.
+    const normalizedFrom = from.slice(1, -1);
+
+    const fromIndex = matchesForValueImport.indices![2]![0] + 1;
+    const start = {
+      line: atValue.source!.start!.line,
+      column: atValue.source!.start!.column + baseLength + fromIndex,
+      offset: atValue.source!.start!.offset + baseLength + fromIndex,
+    };
+    const end = {
+      line: start.line,
+      column: start.column + normalizedFrom.length,
+      offset: start.offset + normalizedFrom.length,
+    };
+
+    const parsedAtValue: ValueImportDeclaration = {
+      type: 'valueImportDeclaration',
+      values,
+      from: normalizedFrom,
+      fromLoc: { start, end },
+    };
+    return { atValue: parsedAtValue, diagnostics };
+  }
+
+  const matchesForValueDefinition = `${atValue.params}${atValue.raws.between!}`.match(VALUE_DEFINITION_PATTERN);
+  if (matchesForValueDefinition) {
+    const [, name, _value] = matchesForValueDefinition;
+    if (name === undefined) throw new Error(`unreachable`);
+    /** The index of the `<name>` in `@value <name>: <value>;`. */
+    const nameIndex = 6 + (atValue.raws.afterName?.length ?? 0) + matchesForValueDefinition.indices![1]![0];
+    const start = {
+      line: atValue.source!.start!.line,
+      column: atValue.source!.start!.column + nameIndex,
+      offset: atValue.source!.start!.offset + nameIndex,
+    };
+    const end = {
+      line: start.line,
+      column: start.column + name.length,
+      offset: start.offset + name.length,
+    };
+    const parsedAtValue = { type: 'valueDeclaration', name, loc: { start, end } } as const;
+    return { atValue: parsedAtValue, diagnostics };
+  }
+  diagnostics.push({
+    type: 'syntactic',
+    fileName: atValue.source!.input.file!,
+    start: {
+      line: atValue.source!.start!.line,
+      column: atValue.source!.start!.column,
+    },
+    end: {
+      line: atValue.source!.end!.line,
+      column: atValue.source!.end!.column + 1,
+    },
+    text: `\`${atValue.toString()}\` is a invalid syntax.`,
+    category: 'error',
+  });
+  return { diagnostics };
+}