@css-modules-kit/core 0.0.1

package/src/parser/css-module-parser.ts

@@ -0,0 +1,193 @@
+import type { AtRule, Node, Root, Rule } from 'postcss';
+import { CssSyntaxError, parse } from 'postcss';
+import safeParser from 'postcss-safe-parser';
+import type { SyntacticDiagnostic } from '../diagnostic.js';
+import { parseAtImport } from './at-import-parser.js';
+import { parseAtValue } from './at-value-parser.js';
+import { type Location } from './location.js';
+import { parseRule } from './rule-parser.js';
+
+type AtImport = AtRule & { name: 'import' };
+type AtValue = AtRule & { name: 'value' };
+
+function isAtRuleNode(node: Node): node is AtRule {
+  return node.type === 'atrule';
+}
+
+function isAtImportNode(node: Node): node is AtImport {
+  return isAtRuleNode(node) && node.name === 'import';
+}
+
+function isAtValueNode(node: Node): node is AtValue {
+  return isAtRuleNode(node) && node.name === 'value';
+}
+
+function isRuleNode(node: Node): node is Rule {
+  return node.type === 'rule';
+}
+
+/**
+ * Collect tokens from the AST.
+ */
+function collectTokens(ast: Root) {
+  const allDiagnostics: SyntacticDiagnostic[] = [];
+  const localTokens: Token[] = [];
+  const tokenImporters: TokenImporter[] = [];
+  ast.walk((node) => {
+    if (isAtImportNode(node)) {
+      const parsed = parseAtImport(node);
+      if (parsed !== undefined) {
+        tokenImporters.push({ type: 'import', ...parsed });
+      }
+    } else if (isAtValueNode(node)) {
+      const { atValue, diagnostics } = parseAtValue(node);
+      allDiagnostics.push(...diagnostics);
+      if (atValue === undefined) return;
+      if (atValue.type === 'valueDeclaration') {
+        localTokens.push({ name: atValue.name, loc: atValue.loc });
+      } else if (atValue.type === 'valueImportDeclaration') {
+        tokenImporters.push({ ...atValue, type: 'value' });
+      }
+    } else if (isRuleNode(node)) {
+      const { classSelectors, diagnostics } = parseRule(node);
+      allDiagnostics.push(...diagnostics);
+      for (const classSelector of classSelectors) {
+        localTokens.push(classSelector);
+      }
+    }
+  });
+  return { localTokens, tokenImporters, diagnostics: allDiagnostics };
+}
+
+/** The item being exported from a CSS module file (a.k.a. token). */
+export interface Token {
+  /** The token name. */
+  name: string;
+  /** The location of the token in the source file. */
+  loc: Location;
+}
+
+/**
+ * A token importer using `@import '...'`.
+ * `@import` imports all tokens from the file. Therefore, it does not have
+ * the name of the imported token unlike {@link AtValueTokenImporter}.
+ */
+export interface AtImportTokenImporter {
+  type: 'import';
+  /**
+   * The specifier of the file from which the token is imported.
+   * This is a string before being resolved and unquoted.
+   * @example `@import './a.module.css'` would have `from` as `'./a.module.css'`.
+   */
+  from: string;
+  /** The location of the `from` in *.module.css file. */
+  fromLoc: Location;
+}
+
+/** A token importer using `@value ... from '...'`. */
+export interface AtValueTokenImporter {
+  type: 'value';
+  /** The values imported from the file. */
+  values: AtValueTokenImporterValue[];
+  /**
+   * The specifier of the file from which the token is imported.
+   * This is a string before being resolved and unquoted.
+   * @example `@value a from './a.module.css'` would have `from` as `'./a.module.css'`.
+   */
+  from: string;
+  /** The location of the `from` in *.module.css file. */
+  fromLoc: Location;
+}
+
+/** A value imported from a CSS module file using `@value ... from '...'`. */
+export interface AtValueTokenImporterValue {
+  /**
+   * The name of the token in the file from which it is imported.
+   * @example `@value a from './a.module.css'` would have `name` as `'a'`.
+   * @example `@value a as b from './a.module.css'` would have `name` as `'a'`.
+   */
+  name: string;
+  /** The location of the `name` in *.module.css file. */
+  loc: Location;
+  /**
+   * The name of the token in the current file.
+   * @example `@value a from './a.module.css'` would not have `localName`.
+   * @example `@value a as b from './a.module.css'` would have `localName` as `'b'`.
+   */
+  localName?: string;
+  /**
+   * The location of the `localName` in *.module.css file.
+   * This is `undefined` when `localName` is `undefined`.
+   */
+  localLoc?: Location;
+}
+
+export type TokenImporter = AtImportTokenImporter | AtValueTokenImporter;
+
+export interface CSSModule {
+  /** Absolute path of the file */
+  fileName: string;
+  /**
+   * List of token names defined in the file.
+   * @example
+   * Consider the following file:
+   * ```css
+   * .foo { color: red }
+   * .bar, .baz { color: red }
+   * ```
+   * The `localTokens` for this file would be `['foo', 'bar', 'baz']`.
+   */
+  localTokens: Token[];
+  /**
+   * List of token importers in the file.
+   * Token importer is a statement that imports tokens from another file.
+   */
+  tokenImporters: TokenImporter[];
+}
+
+export interface ParseCSSModuleOptions {
+  fileName: string;
+  dashedIdents: boolean;
+  safe: boolean;
+}
+
+export interface ParseCSSModuleResult {
+  cssModule: CSSModule;
+  diagnostics: SyntacticDiagnostic[];
+}
+
+export function parseCSSModule(text: string, { fileName, safe }: ParseCSSModuleOptions): ParseCSSModuleResult {
+  let ast: Root;
+  try {
+    const parser = safe ? safeParser : parse;
+    ast = parser(text, { from: fileName });
+  } catch (e) {
+    if (e instanceof CssSyntaxError) {
+      const start = { line: e.line ?? 1, column: e.column ?? 1 };
+      return {
+        cssModule: { fileName, localTokens: [], tokenImporters: [] },
+        diagnostics: [
+          {
+            type: 'syntactic',
+            fileName,
+            start,
+            ...(e.endLine !== undefined &&
+              e.endColumn !== undefined && {
+                end: { line: e.endLine, column: e.endColumn },
+              }),
+            text: e.reason,
+            category: 'error',
+          },
+        ],
+      };
+    }
+    throw e;
+  }
+  const { localTokens, tokenImporters, diagnostics } = collectTokens(ast);
+  const cssModule = {
+    fileName,
+    localTokens,
+    tokenImporters,
+  };
+  return { cssModule, diagnostics };
+}

package/src/parser/location.ts

@@ -0,0 +1,43 @@
+import type { Rule } from 'postcss';
+import type selectorParser from 'postcss-selector-parser';
+import type { DiagnosticPosition } from '../diagnostic.js';
+
+export interface Position {
+  /**
+   * The line number in the source file. It is 1-based.
+   * This is compatible with postcss and tsserver.
+   */
+  // TODO: Maybe it should be deleted since it is not used
+  line: number;
+  /**
+   * The column number in the source file. It is 1-based.
+   * This is compatible with postcss and tsserver.
+   */
+  // TODO: Maybe it should be deleted since it is not used
+  column: number;
+  /** The offset in the source file. It is 0-based. */
+  offset: number;
+}
+
+export interface Location {
+  /**
+   * The starting position of the node. It is inclusive.
+   * This is compatible with postcss and tsserver.
+   */
+  start: Position;
+  /**
+   * The ending position of the node. It is exclusive.
+   * This is compatible with tsserver, but not postcss.
+   */
+  // TODO: Maybe it should be deleted since it is not used
+  end: Position;
+}
+
+export function calcDiagnosticsLocationForSelectorParserNode(
+  rule: Rule,
+  node: selectorParser.Node,
+): { start: DiagnosticPosition; end: DiagnosticPosition } {
+  const start = rule.positionBy({ index: node.sourceIndex });
+  const end = rule.positionBy({ index: node.sourceIndex + node.toString().length });
+  return { start, end };
+}

package/src/parser/rule-parser.ts

@@ -0,0 +1,140 @@
+import type { Rule } from 'postcss';
+import selectorParser from 'postcss-selector-parser';
+import type { SyntacticDiagnostic } from '../diagnostic.js';
+import { calcDiagnosticsLocationForSelectorParserNode, type Location } from './location.js';
+
+interface CollectResult {
+  classNames: selectorParser.ClassName[];
+  diagnostics: SyntacticDiagnostic[];
+}
+
+function flatCollectResults(results: CollectResult[]): CollectResult {
+  const classNames: selectorParser.ClassName[] = [];
+  const diagnostics: SyntacticDiagnostic[] = [];
+  for (const result of results) {
+    classNames.push(...result.classNames);
+    diagnostics.push(...result.diagnostics);
+  }
+  return { classNames, diagnostics };
+}
+
+const JS_IDENTIFIER_PATTERN = /^[$_\p{ID_Start}][$\u200c\u200d\p{ID_Continue}]*$/u;
+
+function convertClassNameToCollectResult(rule: Rule, node: selectorParser.ClassName): CollectResult {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- `raws` property is defined if `node` has escaped characters.
+  const name = (node as any).raws?.value ?? node.value;
+
+  if (!JS_IDENTIFIER_PATTERN.test(name)) {
+    const diagnostic: SyntacticDiagnostic = {
+      type: 'syntactic',
+      fileName: rule.source!.input.file!,
+      ...calcDiagnosticsLocationForSelectorParserNode(rule, node),
+      text: `\`${name}\` is not allowed because it is not a valid JavaScript identifier.`,
+      category: 'error',
+    };
+    return { classNames: [], diagnostics: [diagnostic] };
+  }
+  return { classNames: [node], diagnostics: [] };
+}
+
+/**
+ * Collect local class names from the AST.
+ * This function is based on the behavior of postcss-modules-local-by-default.
+ *
+ * @see https://github.com/css-modules/postcss-modules-local-by-default/blob/38119276608ef14821797cfc0242b3c7dead69af/src/index.js
+ * @see https://github.com/css-modules/postcss-modules-local-by-default/blob/38119276608ef14821797cfc0242b3c7dead69af/test/index.test.js
+ * @example `.local1 :global(.global1) .local2 :local(.local3)` => `[".local1", ".local2", ".local3"]`
+ */
+function collectLocalClassNames(rule: Rule, root: selectorParser.Root): CollectResult {
+  return visitNode(root, undefined);
+
+  function visitNode(node: selectorParser.Node, wrappedBy: ':local(...)' | ':global(...)' | undefined): CollectResult {
+    if (selectorParser.isClassName(node)) {
+      switch (wrappedBy) {
+        // If the class name is wrapped by `:local(...)` or `:global(...)`,
+        // the scope is determined by the wrapper.
+        case ':local(...)':
+          return convertClassNameToCollectResult(rule, node);
+        case ':global(...)':
+          return { classNames: [], diagnostics: [] };
+        // If the class name is not wrapped by `:local(...)` or `:global(...)`,
+        // the scope is determined by the mode.
+        default:
+          // Mode is customizable in css-loader, but we don't support it for simplicity. We fix the mode to 'local'.
+          return convertClassNameToCollectResult(rule, node);
+      }
+    } else if (selectorParser.isPseudo(node) && (node.value === ':local' || node.value === ':global')) {
+      if (node.nodes.length === 0) {
+        // `node` is `:local` or `:global` (without any arguments)
+        // We don't support `:local` and `:global` (without any arguments) because they are complex.
+        const diagnostic: SyntacticDiagnostic = {
+          type: 'syntactic',
+          fileName: rule.source!.input.file!,
+          ...calcDiagnosticsLocationForSelectorParserNode(rule, node),
+          text: `\`${node.value}\` is not supported. Use \`${node.value}(...)\` instead.`,
+          category: 'error',
+        };
+        return { classNames: [], diagnostics: [diagnostic] };
+      } else {
+        // `node` is `:local(...)` or `:global(...)` (with arguments)
+        if (wrappedBy !== undefined) {
+          const diagnostic: SyntacticDiagnostic = {
+            type: 'syntactic',
+            fileName: rule.source!.input.file!,
+            ...calcDiagnosticsLocationForSelectorParserNode(rule, node),
+            text: `A \`${node.value}(...)\` is not allowed inside of \`${wrappedBy}\`.`,
+            category: 'error',
+          };
+          return { classNames: [], diagnostics: [diagnostic] };
+        }
+        return flatCollectResults(
+          node.nodes.map((child) => visitNode(child, node.value === ':local' ? ':local(...)' : ':global(...)')),
+        );
+      }
+    } else if (selectorParser.isContainer(node)) {
+      return flatCollectResults(node.nodes.map((child) => visitNode(child, wrappedBy)));
+    }
+    return { classNames: [], diagnostics: [] };
+  }
+}
+
+interface ClassSelector {
+  /** The class name. It does not include the leading dot. */
+  name: string;
+  /** The location of the class selector. */
+  loc: Location;
+}
+
+interface ParseRuleResult {
+  classSelectors: ClassSelector[];
+  diagnostics: SyntacticDiagnostic[];
+}
+
+/**
+ * Parse a rule and collect local class selectors.
+ */
+export function parseRule(rule: Rule): ParseRuleResult {
+  const root = selectorParser().astSync(rule);
+  const result = collectLocalClassNames(rule, root);
+  const classSelectors = result.classNames.map((className) => {
+    // If `rule` is `.a, .b { color: red; }` and `className` is `.b`,
+    // `rule.source` is `{ start: { line: 1, column: 1 }, end: { line: 1, column: 22 } }`
+    // And `className.source` is `{ start: { line: 1, column: 5 }, end: { line: 1, column: 6 } }`.
+    const start = {
+      line: rule.source!.start!.line + className.source!.start!.line - 1,
+      column: rule.source!.start!.column + className.source!.start!.column,
+      offset: rule.source!.start!.offset + className.sourceIndex + 1,
+    };
+    const end = {
+      // The end line is always the same as the start line, as a class selector cannot break in the middle.
+      line: start.line,
+      column: start.column + className.value.length,
+      offset: start.offset + className.value.length,
+    };
+    return {
+      name: className.value,
+      loc: { start, end },
+    };
+  });
+  return { classSelectors, diagnostics: result.diagnostics };
+}

package/src/path.ts

@@ -0,0 +1,40 @@
+// eslint-disable-next-line no-restricted-imports
+import type { ParsedPath } from 'node:path';
+// eslint-disable-next-line no-restricted-imports
+import nodePath from 'node:path';
+import ts from 'typescript';
+
+export function slash(path: string): string {
+  return ts.server.toNormalizedPath(path);
+}
+
+export function join(...paths: string[]): string {
+  return slash(nodePath.join(...paths));
+}
+
+export function resolve(...paths: string[]): string {
+  return slash(nodePath.resolve(...paths));
+}
+
+export function relative(from: string, to: string): string {
+  return slash(nodePath.relative(from, to));
+}
+
+export function dirname(path: string): string {
+  return slash(nodePath.dirname(path));
+}
+
+export function basename(path: string): string {
+  return slash(nodePath.basename(path));
+}
+
+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 n/no-unsupported-features/node-builtins, @typescript-eslint/unbound-method
+export const matchesGlob = nodePath.matchesGlob;
+
+// eslint-disable-next-line @typescript-eslint/unbound-method
+export const isAbsolute = nodePath.isAbsolute;

package/src/resolver.ts

@@ -0,0 +1,57 @@
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import ts from 'typescript';
+import { isAbsolute, resolve } from './path.js';
+
+export interface ResolverOptions {
+  /** The file that imports the specifier. It is a absolute path. */
+  request: string;
+}
+
+/**
+ * A resolver function that resolves import specifiers.
+ * @param specifier The import specifier.
+ * @param options The options.
+ * @returns The resolved import specifier. It is a absolute path. If the import specifier cannot be resolved, return `undefined`.
+ */
+export type Resolver = (specifier: string, options: ResolverOptions) => string | undefined;
+
+export function createResolver(paths: Record<string, string[]>): Resolver {
+  return (_specifier: string, options: ResolverOptions) => {
+    let specifier = _specifier;
+
+    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'));
+        }
+        return ts.sys.fileExists(fileName);
+      },
+    };
+    const { resolvedModule } = ts.resolveModuleName(specifier, options.request, { paths }, host);
+    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;
+    }
+  };
+}
+
+/**
+ * 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/typing/typescript.d.ts

@@ -0,0 +1,19 @@
+export {};
+
+declare module 'typescript' {
+  interface FileSystemEntries {
+    readonly files: readonly string[];
+    readonly directories: readonly string[];
+  }
+  export function matchFiles(
+    path: string,
+    extensions: readonly string[] | undefined,
+    excludes: readonly string[] | undefined,
+    includes: readonly string[] | undefined,
+    useCaseSensitiveFileNames: boolean,
+    currentDirectory: string,
+    depth: number | undefined,
+    getFileSystemEntries: (path: string) => FileSystemEntries,
+    realpath: (path: string) => string,
+  ): string[];
+}

package/src/util.ts

@@ -0,0 +1,3 @@
+export function isPosixRelativePath(path: string): boolean {
+  return path.startsWith(`./`) || path.startsWith(`../`);
+}