happy-css-modules 0.2.0

package/src/loader/index.test.ts

@@ -0,0 +1,306 @@
+import fs, { readFile, writeFile } from 'fs/promises';
+import { jest } from '@jest/globals';
+import dedent from 'dedent';
+import { createFixtures, FIXTURE_DIR_PATH, getFixturePath } from '../test/util.js';
+import { sleepSync } from '../util.js';
+
+const readFileSpy = jest.spyOn(fs, 'readFile');
+// In ESM, for some reason, we need to explicitly mock module
+jest.unstable_mockModule('fs/promises', () => ({
+  ...fs, // Inherit native functions (e.g., fs.stat)
+  readFile: readFileSpy,
+}));
+
+// After the mock of fs/promises is complete, . /index.js after the mock of fs/promises is complete.
+// ref: https://www.coolcomputerclub.com/posts/jest-hoist-await/
+const { Loader } = await import('./index.js');
+// NOTE: ../test/util.js depends on . /index.js, so it must also be imported dynamically...
+
+const loader = new Loader();
+
+afterEach(() => {
+  readFileSpy.mockClear();
+});
+
+test('basic', async () => {
+  createFixtures({
+    '/test/1.css': dedent`
+    .a {}
+    .b {}
+    `,
+  });
+  const result = await loader.load(getFixturePath('/test/1.css'));
+  expect(result).toMatchInlineSnapshot(`
+    {
+      dependencies: [],
+      tokens: [
+        {
+          name: "a",
+          originalLocations: [
+            { filePath: "<fixtures>/test/1.css", start: { line: 1, column: 1 }, end: { line: 1, column: 2 } },
+          ],
+        },
+        {
+          name: "b",
+          originalLocations: [
+            { filePath: "<fixtures>/test/1.css", start: { line: 2, column: 1 }, end: { line: 2, column: 2 } },
+          ],
+        },
+      ],
+    }
+  `);
+});
+
+test('tracks other files when `@import` is present', async () => {
+  createFixtures({
+    '/test/1.css': dedent`
+    @import './2.css';
+    @import '3.css';
+    @import '${getFixturePath('/test/4.css')}';
+    `,
+    '/test/2.css': dedent`
+    .a {}
+    `,
+    '/test/3.css': dedent`
+    .b {}
+    `,
+    '/test/4.css': dedent`
+    .c {}
+    `,
+  });
+  const result = await loader.load(getFixturePath('/test/1.css'));
+  expect(result).toMatchInlineSnapshot(`
+    {
+      dependencies: ["<fixtures>/test/2.css", "<fixtures>/test/3.css", "<fixtures>/test/4.css"],
+      tokens: [
+        {
+          name: "a",
+          originalLocations: [
+            { filePath: "<fixtures>/test/2.css", start: { line: 1, column: 1 }, end: { line: 1, column: 2 } },
+          ],
+        },
+        {
+          name: "b",
+          originalLocations: [
+            { filePath: "<fixtures>/test/3.css", start: { line: 1, column: 1 }, end: { line: 1, column: 2 } },
+          ],
+        },
+        {
+          name: "c",
+          originalLocations: [
+            { filePath: "<fixtures>/test/4.css", start: { line: 1, column: 1 }, end: { line: 1, column: 2 } },
+          ],
+        },
+      ],
+    }
+  `);
+});
+
+test('tracks other files when `composes` is present', async () => {
+  createFixtures({
+    '/test/1.css': dedent`
+    .a {
+      composes: b from './2.css';
+      composes: c d from './3.css';
+      composes: e from '${getFixturePath('/test/4.css')}';
+    }
+    `,
+    '/test/2.css': dedent`
+    .b {}
+    `,
+    '/test/3.css': dedent`
+    .c {}
+    .d {}
+    `,
+    '/test/4.css': dedent`
+    .e {}
+    `,
+  });
+  const result = await loader.load(getFixturePath('/test/1.css'));
+  expect(result).toMatchInlineSnapshot(`
+    {
+      dependencies: ["<fixtures>/test/2.css", "<fixtures>/test/3.css", "<fixtures>/test/4.css"],
+      tokens: [
+        {
+          name: "a",
+          originalLocations: [
+            { filePath: "<fixtures>/test/1.css", start: { line: 1, column: 1 }, end: { line: 1, column: 2 } },
+          ],
+        },
+        {
+          name: "b",
+          originalLocations: [
+            { filePath: "<fixtures>/test/2.css", start: { line: 1, column: 1 }, end: { line: 1, column: 2 } },
+          ],
+        },
+        {
+          name: "c",
+          originalLocations: [
+            { filePath: "<fixtures>/test/3.css", start: { line: 1, column: 1 }, end: { line: 1, column: 2 } },
+          ],
+        },
+        {
+          name: "d",
+          originalLocations: [
+            { filePath: "<fixtures>/test/3.css", start: { line: 2, column: 1 }, end: { line: 2, column: 2 } },
+          ],
+        },
+        {
+          name: "e",
+          originalLocations: [
+            { filePath: "<fixtures>/test/4.css", start: { line: 1, column: 1 }, end: { line: 1, column: 2 } },
+          ],
+        },
+      ],
+    }
+  `);
+});
+
+test('normalizes tokens', async () => {
+  createFixtures({
+    '/test/1.css': dedent`
+    /* duplicate import */
+    @import './2.css';
+    @import '2.css';
+    .a {
+      /* duplicate composes */
+      composes: c from './3.css';
+      composes: c from '3.css';
+      composes: c c from './3.css';
+      /* duplicate import and composes */
+      composes: b from './2.css';
+    }
+    .a {} /* duplicate class selector */
+    `,
+    '/test/2.css': dedent`
+    .a {} /* class selector that duplicates the import source */
+    .b {}
+    `,
+    '/test/3.css': dedent`
+    .c {}
+    `,
+  });
+  const result = await loader.load(getFixturePath('/test/1.css'));
+  expect(result).toMatchInlineSnapshot(`
+    {
+      dependencies: ["<fixtures>/test/2.css", "<fixtures>/test/3.css"],
+      tokens: [
+        {
+          name: "a",
+          originalLocations: [
+            { filePath: "<fixtures>/test/2.css", start: { line: 1, column: 1 }, end: { line: 1, column: 2 } },
+            { filePath: "<fixtures>/test/1.css", start: { line: 4, column: 1 }, end: { line: 4, column: 2 } },
+            { filePath: "<fixtures>/test/1.css", start: { line: 12, column: 1 }, end: { line: 12, column: 2 } },
+          ],
+        },
+        {
+          name: "b",
+          originalLocations: [
+            { filePath: "<fixtures>/test/2.css", start: { line: 2, column: 1 }, end: { line: 2, column: 2 } },
+          ],
+        },
+        {
+          name: "c",
+          originalLocations: [
+            { filePath: "<fixtures>/test/3.css", start: { line: 1, column: 1 }, end: { line: 1, column: 2 } },
+          ],
+        },
+      ],
+    }
+  `);
+});
+
+test.failing('returns the result from the cache when the file has not been modified', async () => {
+  createFixtures({
+    '/test/1.css': dedent`
+    @import './2.css';
+    @import './2.css';
+    .a {
+      composes: b from './2.css';
+      composes: c from './3.css';
+      composes: d from './3.css';
+    }
+    `,
+    '/test/2.css': dedent`
+    .b {}
+    `,
+    '/test/3.css': dedent`
+    .c {}
+    .d {}
+    `,
+  });
+  await loader.load(getFixturePath('/test/1.css'));
+  expect(readFileSpy).toHaveBeenCalledTimes(3);
+  expect(readFileSpy).toHaveBeenNthCalledWith(1, '/test/1.css', 'utf-8');
+  expect(readFileSpy).toHaveBeenNthCalledWith(2, '/test/2.css', 'utf-8');
+  expect(readFileSpy).toHaveBeenNthCalledWith(3, '/test/3.css', 'utf-8');
+  readFileSpy.mockClear();
+
+  // update `/test/2.css`
+  sleepSync(1); // wait for the file system to update the mtime
+  await writeFile(getFixturePath('/test/2.css'), await readFile(getFixturePath('/test/2.css'), 'utf-8'));
+
+  // `3.css` is not updated, so the cache is used. Therefore, `readFile` is not called.
+  await loader.load(getFixturePath('/test/3.css'));
+  expect(readFileSpy).toHaveBeenCalledTimes(0);
+
+  // `1.css` is not updated, but dependencies are updated, so the cache is used. Therefore, `readFile` is called.
+  await loader.load(getFixturePath('/test/1.css'));
+  expect(readFileSpy).toHaveBeenCalledTimes(2);
+  expect(readFileSpy).toHaveBeenNthCalledWith(1, '/test/1.css', 'utf-8');
+  expect(readFileSpy).toHaveBeenNthCalledWith(2, '/test/2.css', 'utf-8');
+
+  // ``2.css` is updated, but the cache is already available because it was updated in the previous step. Therefore, `readFile` is not called.
+  await loader.load(getFixturePath('/test/2.css'));
+  expect(readFileSpy).toHaveBeenCalledTimes(2);
+});
+
+test('ignores the composition of non-existent tokens', async () => {
+  // In css-loader and postcss-modules, compositions of non-existent tokens are simply ignored.
+  // Therefore, happy-css-modules follows suit.
+  // It may be preferable to warn rather than ignore, but for now, we will focus on compatibility.
+  // ref: https://github.com/css-modules/css-modules/issues/356
+  createFixtures({
+    '/test/1.css': dedent`
+    .a {
+      composes: b c from './2.css';
+    }
+    `,
+    '/test/2.css': dedent`
+    .b {}
+    `,
+  });
+  const result = await loader.load(getFixturePath('/test/1.css'));
+  expect(result.tokens.map((t) => t.name)).toStrictEqual(['a', 'b']);
+});
+
+test('throws error the composition of non-existent file', async () => {
+  // In postcss-modules, compositions of non-existent file are causes an error.
+  // Therefore, happy-css-modules follows suit.
+  createFixtures({
+    '/test/1.css': dedent`
+    .a {
+      composes: a from './2.css';
+    }
+    `,
+  });
+  await expect(async () => {
+    await loader.load(getFixturePath('/test/1.css')).catch((e) => {
+      e.message = e.message.replace(FIXTURE_DIR_PATH, '<fixtures>');
+      throw e;
+    });
+  }).rejects.toThrowError(`Could not resolve './2.css' in '<fixtures>/test/1.css'`);
+});
+
+test.todo('supports sourcemap file and inline sourcemap');
+
+test('ignores http(s) protocol file', async () => {
+  createFixtures({
+    '/test/1.css': dedent`
+    @import 'http://example.com/path/1.css';
+    @import 'https://example.com/path/1.css';
+    `,
+  });
+  const result = await loader.load(getFixturePath('/test/1.css'));
+  expect(result.dependencies).toStrictEqual([]);
+});

package/src/loader/index.ts

@@ -0,0 +1,199 @@
+import { readFile, stat } from 'fs/promises';
+import postcss from 'postcss';
+import type { Resolver } from '../resolver/index.js';
+import { createDefaultResolver } from '../resolver/index.js';
+import { createDefaultTransformer, type Transformer } from '../transformer/index.js';
+import { unique, uniqueBy } from '../util.js';
+import {
+  getOriginalLocation,
+  generateLocalTokenNames,
+  parseAtImport,
+  type Location,
+  parseComposesDeclarationWithFromUrl,
+  collectNodes,
+} from './postcss.js';
+
+export { collectNodes, type Location } from './postcss.js';
+
+/**
+ * Whether the specifier should be ignored.
+ * For example, specifiers starting with `http://` or `https://` should be ignored.
+ */
+function isIgnoredSpecifier(specifier: string): boolean {
+  return specifier.startsWith('http://') || specifier.startsWith('https://');
+}
+
+/** The exported token. */
+export type Token = {
+  /** The token name. */
+  name: string;
+  /** The original locations of the token in the source file. */
+  originalLocations: Location[];
+};
+
+type CacheEntry = {
+  mtime: number; // TODO: `--cache-strategy` option will allow you to switch between `content` and `metadata` modes.
+  result: LoadResult;
+};
+
+/** The result of `Loader#load`. */
+export type LoadResult = {
+  /** The path of the file imported from the source file with `@import` or `composes`. */
+  dependencies: string[];
+  /** The tokens exported by the source file. */
+  tokens: Token[];
+};
+
+function normalizeTokens(tokens: Token[]): Token[] {
+  const tokenNameToOriginalLocations = new Map<string, Location[]>();
+  for (const token of tokens) {
+    tokenNameToOriginalLocations.set(
+      token.name,
+      uniqueBy([...(tokenNameToOriginalLocations.get(token.name) ?? []), ...token.originalLocations], (location) =>
+        JSON.stringify(location),
+      ),
+    );
+  }
+  return Array.from(tokenNameToOriginalLocations.entries()).map(([name, originalLocations]) => ({
+    name,
+    originalLocations,
+  }));
+}
+
+export type LoaderOptions = {
+  /** The function to transform source code. */
+  transformer?: Transformer | undefined;
+  /** The function to resolve the path of the imported file. */
+  resolver?: Resolver | undefined;
+};
+
+/** The resolver that throws an exception if resolving fails. */
+export type StrictlyResolver = (...args: Parameters<Resolver>) => Promise<string>;
+
+/** This class collects information on tokens exported from CSS Modules files. */
+export class Loader {
+  private readonly cache: Map<string, CacheEntry> = new Map();
+  private readonly transformer: Transformer | undefined;
+  private readonly resolver: StrictlyResolver;
+
+  constructor(options?: LoaderOptions) {
+    this.transformer = options?.transformer ?? createDefaultTransformer();
+    this.resolver = async (specifier, resolverOptions) => {
+      const resolver = options?.resolver ?? createDefaultResolver();
+      const resolved = await resolver(specifier, resolverOptions);
+      if (resolved === false) throw new Error(`Could not resolve '${specifier}' in '${resolverOptions.request}'.`);
+      return resolved;
+    };
+  }
+
+  /** Returns `true` if the cache is outdated. */
+  private async isCacheOutdated(filePath: string): Promise<boolean> {
+    const entry = this.cache.get(filePath);
+    if (!entry) return true;
+    const mtime = (await stat(filePath)).mtime.getTime();
+    if (entry.mtime !== mtime) return true;
+
+    const { dependencies } = entry.result;
+    for (const dependency of dependencies) {
+      const entry = this.cache.get(dependency);
+      if (!entry) return true;
+      const mtime = (await stat(dependency)).mtime.getTime();
+      if (entry.mtime !== mtime) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Reads the source file and returns the code.
+   * If transformer is specified, the code is transformed before returning.
+   */
+  private async readCSS(
+    filePath: string,
+  ): Promise<
+    | { css: string; map: undefined; dependencies: string[] }
+    | { css: string; map: string | object | undefined; dependencies: string[] }
+  > {
+    const css = await readFile(filePath, 'utf-8');
+    if (!this.transformer) return { css, map: undefined, dependencies: [] };
+    const result = await this.transformer(css, { from: filePath, resolver: this.resolver });
+    if (result === false) return { css, map: undefined, dependencies: [] };
+    return {
+      css: result.css,
+      map: result.map,
+      dependencies: result.dependencies.map((dep) => {
+        if (typeof dep === 'string') return dep;
+        if (dep.protocol !== 'file:') throw new Error('Unsupported protocol: ' + dep.protocol);
+        return dep.pathname;
+      }),
+    };
+  }
+
+  /** Returns information about the tokens exported from the CSS Modules file. */
+  async load(filePath: string): Promise<LoadResult> {
+    // NOTE: Loader does not support concurrent calls.
+    // TODO: Throw an error if called concurrently.
+    if (!(await this.isCacheOutdated(filePath))) {
+      const cacheEntry = this.cache.get(filePath)!;
+      return cacheEntry.result;
+    }
+
+    const mtime = (await stat(filePath)).mtime.getTime();
+
+    const { css, map, dependencies } = await this.readCSS(filePath);
+
+    const ast = postcss.parse(css, { from: filePath, map: map ? { inline: false, prev: map } : { inline: false } });
+
+    // Get the local tokens exported by the source file.
+    // The tokens are fetched using `postcss-modules` plugin.
+    const localTokenNames = await generateLocalTokenNames(ast);
+
+    const tokens: Token[] = [];
+
+    const { atImports, classSelectors, composesDeclarations } = collectNodes(ast);
+
+    // Load imported sheets recursively.
+    for (const atImport of atImports) {
+      const importedSheetPath = parseAtImport(atImport);
+      if (!importedSheetPath) continue;
+      if (isIgnoredSpecifier(importedSheetPath)) continue;
+      const from = await this.resolver(importedSheetPath, { request: filePath });
+      const result = await this.load(from);
+      const externalTokens = result.tokens;
+      dependencies.push(from);
+      tokens.push(...externalTokens);
+    }
+
+    // Traverse the source file to find a class selector that matches the local token.
+    for (const { rule, classSelector } of classSelectors) {
+      // Consider a class selector to be the origin of a token if it matches a token fetched by postcss-modules.
+      // NOTE: This method has false positives. However, it works as expected in many cases.
+      if (!localTokenNames.includes(classSelector.value)) continue;
+
+      const originalLocation = getOriginalLocation(rule, classSelector);
+
+      tokens.push({
+        name: classSelector.value,
+        originalLocations: [originalLocation],
+      });
+    }
+
+    // Load imported tokens by the names recursively.
+    for (const composesDeclaration of composesDeclarations) {
+      const declarationDetail = parseComposesDeclarationWithFromUrl(composesDeclaration);
+      if (!declarationDetail) continue;
+      if (isIgnoredSpecifier(declarationDetail.from)) continue;
+      const from = await this.resolver(declarationDetail.from, { request: filePath });
+      const result = await this.load(from);
+      const externalTokens = result.tokens.filter((token) => declarationDetail.tokenNames.includes(token.name));
+      dependencies.push(from);
+      tokens.push(...externalTokens);
+    }
+
+    const result: LoadResult = {
+      dependencies: unique(dependencies).filter((dep) => dep !== filePath),
+      tokens: normalizeTokens(tokens),
+    };
+    this.cache.set(filePath, { mtime, result });
+    return result;
+  }
+}