happy-css-modules 0.2.0

package/src/transformer/index.ts

@@ -0,0 +1,44 @@
+import type { StrictlyResolver } from '../loader/index.js';
+import { createLessTransformer } from './less-transformer.js';
+import { createScssTransformer } from './scss-transformer.js';
+
+/**
+ * The value returned from the transformer.
+ * `false` means to skip transpiling on that file.
+ * */
+export type TransformResult =
+  | {
+      /** The transformed code. */
+      css: string;
+      /** The source map from the transformed code to the original code. */
+      map: string | object;
+      dependencies: (string | URL)[];
+    }
+  | false;
+
+export type TransformerOptions = {
+  /** The path of the file to transform. */
+  from: string;
+  /** The function to resolve the path of the imported file. */
+  resolver: StrictlyResolver;
+};
+
+/** The function to transform source code. */
+export type Transformer = (source: string, options: TransformerOptions) => TransformResult | Promise<TransformResult>;
+
+export const handleImportError = (packageName: string) => (e: unknown) => {
+  console.error(`${packageName} import failed. Did you forget to \`npm install -D ${packageName}\`?`);
+  throw e;
+};
+
+export const createDefaultTransformer: () => Transformer = () => async (source, options) => {
+  const scssTransformer = createScssTransformer();
+  const lessTransformer = createLessTransformer();
+  if (options.from.endsWith('.scss')) {
+    return scssTransformer(source, options);
+  } else if (options.from.endsWith('.less')) {
+    return lessTransformer(source, options);
+  }
+  // TODO: support postcss
+  return false;
+};

package/src/transformer/less-transformer.test.ts

@@ -0,0 +1,135 @@
+import { jest } from '@jest/globals';
+import dedent from 'dedent';
+import { Loader } from '../loader/index.js';
+import { createFixtures, getFixturePath } from '../test/util.js';
+import { createLessTransformer } from './less-transformer.js';
+
+const loader = new Loader({ transformer: createLessTransformer() });
+const loadSpy = jest.spyOn(loader, 'load');
+
+afterEach(() => {
+  loadSpy.mockClear();
+});
+
+test('handles less features', async () => {
+  createFixtures({
+    '/test/1.less': dedent`
+      @import './2.less'; // less feature test (@use)
+      .a_1 { dummy: ''; }
+      .a_2 {
+        dummy: '';
+        // less feature test (nesting)
+        .a_2_1 { dummy: ''; }
+        &_2 { dummy: ''; }
+        .b_1();
+        .b_2();
+        composes: a_1; // css module feature test (composes)
+        composes: c from './3.less'; // css module feature test (composes from other file)
+      }
+      `,
+    '/test/2.less': dedent`
+      .b_1 { dummy: ''; }
+      .b_2() { dummy: ''; }
+      `,
+    '/test/3.less': dedent`
+      .c { dummy: ''; }
+      `,
+  });
+  const result = await loader.load(getFixturePath('/test/1.less'));
+
+  // FIXME: The end position of 'a_2_2' is incorrect.
+  expect(result).toMatchInlineSnapshot(`
+    {
+      dependencies: ["<fixtures>/test/2.less", "<fixtures>/test/3.less"],
+      tokens: [
+        {
+          name: "b_1",
+          originalLocations: [
+            { filePath: "<fixtures>/test/2.less", start: { line: 1, column: 1 }, end: { line: 1, column: 3 } },
+          ],
+        },
+        {
+          name: "a_1",
+          originalLocations: [
+            { filePath: "<fixtures>/test/1.less", start: { line: 2, column: 1 }, end: { line: 2, column: 3 } },
+          ],
+        },
+        {
+          name: "a_2",
+          originalLocations: [
+            { filePath: "<fixtures>/test/1.less", start: { line: 3, column: 1 }, end: { line: 3, column: 3 } },
+          ],
+        },
+        {
+          name: "a_2_1",
+          originalLocations: [
+            { filePath: "<fixtures>/test/1.less", start: { line: 6, column: 3 }, end: { line: 6, column: 7 } },
+          ],
+        },
+        {
+          name: "a_2_2",
+          originalLocations: [
+            { filePath: "<fixtures>/test/1.less", start: { line: 7, column: 3 }, end: { line: 7, column: 7 } },
+          ],
+        },
+        {
+          name: "c",
+          originalLocations: [
+            { filePath: "<fixtures>/test/3.less", start: { line: 1, column: 1 }, end: { line: 1, column: 1 } },
+          ],
+        },
+      ],
+    }
+  `);
+});
+
+test('tracks dependencies that have been pre-bundled by less compiler', async () => {
+  createFixtures({
+    '/test/1.less': dedent`
+    @import './2.less';
+    @import './3.less';
+    `,
+    '/test/2.less': dedent`
+    `,
+    '/test/3.less': dedent`
+    @import './4.less';
+    `,
+    '/test/4.less': dedent`
+    `,
+  });
+  const result = await loader.load(getFixturePath('/test/1.less'));
+
+  // The files imported using @import are pre-bundled by the compiler.
+  // Therefore, `Loader#load` is not called to process other files.
+  expect(loadSpy).toBeCalledTimes(1);
+  expect(loadSpy).toHaveBeenNthCalledWith(1, getFixturePath('/test/1.less'));
+
+  // The files pre-bundled by the compiler are also included in `result.dependencies`
+  // eslint-disable-next-line @typescript-eslint/require-array-sort-compare
+  expect(result.dependencies.sort()).toStrictEqual(
+    // eslint-disable-next-line @typescript-eslint/require-array-sort-compare
+    ['/test/2.less', '/test/3.less', '/test/4.less'].map(getFixturePath).sort(),
+  );
+});
+
+test('resolves specifier using resolver', async () => {
+  createFixtures({
+    '/test/1.less': dedent`
+    @import 'package-1';
+    @import 'package-2';
+    // NOTE: less does not resolve files that are http(s) protocol.
+    // Therefore, the resolver will not be called for those files,
+    // and they will not be included in result.dependencies.
+    @import 'http://example.com/path/1.css';
+    @import 'https://example.com/path/1.css';
+    `,
+    '/node_modules/package-1/index.css': `.a {}`,
+    '/node_modules/package-2/index.less': `.a {}`,
+  });
+  const result = await loader.load(getFixturePath('/test/1.less'));
+  // eslint-disable-next-line @typescript-eslint/require-array-sort-compare
+  expect(result.dependencies.sort()).toStrictEqual(
+    // eslint-disable-next-line @typescript-eslint/require-array-sort-compare
+    ['/node_modules/package-1/index.css', '/node_modules/package-2/index.less'].map(getFixturePath).sort(),
+  );
+});

package/src/transformer/less-transformer.ts

@@ -0,0 +1,55 @@
+import type { Transformer } from '../index.js';
+import type { TransformerOptions } from './index.js';
+import { handleImportError } from './index.js';
+
+// eslint-disable-next-line @typescript-eslint/naming-convention, @typescript-eslint/consistent-type-imports
+function createLessPluginResolver(Less: typeof import('less'), options: TransformerOptions): Less.Plugin {
+  class ResolverFileManager extends Less.FileManager {
+    options: TransformerOptions;
+    constructor(options: TransformerOptions) {
+      super();
+      this.options = options;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    public override supports(filename: string): boolean {
+      return true;
+    }
+    public override async loadFile(
+      filename: string,
+      currentDirectory: string,
+      options: Less.LoadFileOptions,
+      environment: Less.Environment,
+    ): Promise<Less.FileLoadResult> {
+      const resolved = await this.options.resolver(filename, { request: currentDirectory });
+      return super.loadFile(resolved, currentDirectory, options, environment);
+    }
+  }
+
+  class LessPluginResolver implements Less.Plugin {
+    options: TransformerOptions;
+    constructor(options: TransformerOptions) {
+      this.options = options;
+    }
+    public install(less: LessStatic, pluginManager: Less.PluginManager): void {
+      pluginManager.addFileManager(new ResolverFileManager(this.options));
+    }
+    public minVersion: [number, number, number] = [2, 1, 1];
+  }
+
+  return new LessPluginResolver(options);
+}
+
+export const createLessTransformer: () => Transformer = () => {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-imports
+  let less: typeof import('less');
+  return async (source, options) => {
+    less ??= (await import('less').catch(handleImportError('less'))).default;
+    const result = await less.render(source, {
+      filename: options.from,
+      sourceMap: {},
+      plugins: [createLessPluginResolver(less, options)],
+      syncImport: false, // Don't use `Less.FileManager#loadFileSync`.
+    });
+    return { css: result.css, map: result.map, dependencies: result.imports };
+  };
+};

package/src/transformer/scss-transformer.test.ts

@@ -0,0 +1,142 @@
+import { jest } from '@jest/globals';
+import dedent from 'dedent';
+import { Loader } from '../loader/index.js';
+import { createFixtures, getFixturePath } from '../test/util.js';
+import { createScssTransformer } from './scss-transformer.js';
+
+const loader = new Loader({ transformer: createScssTransformer() });
+const loadSpy = jest.spyOn(loader, 'load');
+
+afterEach(() => {
+  loadSpy.mockClear();
+});
+
+test('handles sass features', async () => {
+  createFixtures({
+    '/test/1.scss': dedent`
+      @use './2.scss' as two; // sass feature test (@use)
+      @import './3.scss'; // css feature test (@import)
+      .a_1 { dummy: ''; }
+      .a_2 {
+        dummy: '';
+        // sass feature test (nesting)
+        .a_2_1 { dummy: ''; }
+        &_2 { dummy: ''; }
+        composes: a_1; // css module feature test (composes)
+        composes: d from './4.scss'; // css module feature test (composes from other file)
+      }
+      `,
+    '/test/2.scss': dedent`
+      .b_1 { dummy: ''; }
+      @mixin b_2 { dummy: ''; }
+      `,
+    '/test/3.scss': dedent`
+      .c { dummy: ''; }
+      `,
+    '/test/4.scss': dedent`
+      .d { dummy: ''; }
+      `,
+  });
+  const result = await loader.load(getFixturePath('/test/1.scss'));
+
+  // NOTE: There should be only one originalLocations for 'a_2', but there are multiple.
+  // This is probably due to an incorrect sourcemap output by the sass compiler.
+  // FIXME: The sass compiler or Loader implementation needs to be fixed.
+
+  // FIXME: The end position of 'a_2_2' is incorrect.
+  expect(result).toMatchInlineSnapshot(`
+    {
+      dependencies: ["<fixtures>/test/2.scss", "<fixtures>/test/3.scss", "<fixtures>/test/4.scss"],
+      tokens: [
+        {
+          name: "b_1",
+          originalLocations: [
+            { filePath: "<fixtures>/test/2.scss", start: { line: 1, column: 1 }, end: { line: 1, column: 3 } },
+          ],
+        },
+        {
+          name: "c",
+          originalLocations: [
+            { filePath: "<fixtures>/test/3.scss", start: { line: 1, column: 1 }, end: { line: 1, column: 1 } },
+          ],
+        },
+        {
+          name: "a_1",
+          originalLocations: [
+            { filePath: "<fixtures>/test/1.scss", start: { line: 3, column: 1 }, end: { line: 3, column: 3 } },
+          ],
+        },
+        {
+          name: "a_2",
+          originalLocations: [
+            { filePath: "<fixtures>/test/1.scss", start: { line: 4, column: 1 }, end: { line: 4, column: 3 } },
+            { filePath: "<fixtures>/test/1.scss", start: { line: 7, column: 3 }, end: { line: 7, column: 5 } },
+          ],
+        },
+        {
+          name: "a_2_1",
+          originalLocations: [
+            { filePath: "<fixtures>/test/1.scss", start: { line: 7, column: 3 }, end: { line: 7, column: 7 } },
+          ],
+        },
+        {
+          name: "a_2_2",
+          originalLocations: [
+            { filePath: "<fixtures>/test/1.scss", start: { line: 8, column: 3 }, end: { line: 8, column: 7 } },
+          ],
+        },
+        {
+          name: "d",
+          originalLocations: [
+            { filePath: "<fixtures>/test/4.scss", start: { line: 1, column: 1 }, end: { line: 1, column: 1 } },
+          ],
+        },
+      ],
+    }
+  `);
+});
+
+test('tracks dependencies that have been pre-bundled by sass compiler', async () => {
+  createFixtures({
+    '/test/1.scss': dedent`
+    @import './2.scss';
+    @import './3.scss';
+    `,
+    '/test/2.scss': dedent`
+    `,
+    '/test/3.scss': dedent`
+    @import './4.scss';
+    `,
+    '/test/4.scss': dedent`
+    `,
+  });
+  const result = await loader.load(getFixturePath('/test/1.scss'));
+
+  // The files imported using @import are pre-bundled by the compiler.
+  // Therefore, `Loader#load` is not called to process other files.
+  expect(loadSpy).toBeCalledTimes(1);
+  expect(loadSpy).toHaveBeenNthCalledWith(1, getFixturePath('/test/1.scss'));
+
+  // The files pre-bundled by the compiler are also included in `result.dependencies`
+  expect(result.dependencies).toStrictEqual(['/test/2.scss', '/test/3.scss', '/test/4.scss'].map(getFixturePath));
+});
+
+test('resolves specifier using resolver', async () => {
+  createFixtures({
+    '/test/1.scss': dedent`
+    @import 'package-1';
+    @import 'package-2';
+    // NOTE: sass does not resolve files that are http(s) protocol.
+    // Therefore, the resolver will not be called for those files,
+    // and they will not be included in result.dependencies.
+    @import 'http://example.com/path/1.css';
+    @import 'https://example.com/path/1.css';
+    `,
+    '/node_modules/package-1/index.css': `.a {}`,
+    '/node_modules/package-2/index.scss': `.a {}`,
+  });
+  const result = await loader.load(getFixturePath('/test/1.scss'));
+  expect(result.dependencies).toStrictEqual(
+    ['/node_modules/package-1/index.css', '/node_modules/package-2/index.scss'].map(getFixturePath),
+  );
+});

package/src/transformer/scss-transformer.ts

@@ -0,0 +1,94 @@
+// NOTE: The workaround for using sass's modern API. happy-css-modules used to use this API.
+// However, due to the implementation of custom resolvers, we have switched to the legacy API.
+// Therefore, the workaround is now disabled. See
+// https://github.com/mizdra/happy-css-modules/issues/65#issuecomment-1229471950 for more information.
+
+import type { LegacyResult } from 'sass';
+import type { Transformer, TransformerOptions } from './index.js';
+import { handleImportError } from './index.js';
+
+// const IS_JEST_ENVIRONMENT = process.env.JEST_WORKER_ID !== undefined;
+
+// function verifyJestEnvironment() {
+//   if (
+//     !(
+//       'window' in global &&
+//       'location' in global &&
+//       // eslint-disable-next-line @typescript-eslint/no-explicit-any
+//       'href' in (global as any).location &&
+//       // eslint-disable-next-line @typescript-eslint/no-explicit-any
+//       typeof (global as any).location.href === 'string' &&
+//       // eslint-disable-next-line @typescript-eslint/no-explicit-any
+//       (global as any).location.href.startsWith('http://')
+//     )
+//   ) {
+//     throw new Error(
+//       'To use dart-sass with jest, dummy `global.window` and `global.location.href` must be set. See https://github.com/sass/dart-sass/issues/1692#issuecomment-1229219993 .',
+//     );
+//   }
+// }
+
+// const createImporterForJest: (from: string) => Importer<'async'> = (from) => ({
+//   canonicalize(url) {
+//     // NOTE: The format of `url` changes depending on the import source.
+//     //
+//     // - When `from === '/test/1.scss'` and `@import './2.scss'` in `/test/1.scss` is resolved, `url === '2.scss'`.
+//     // - When `from === '/test/1.scss'` and `@import './3.scss'` in `/test/2.scss` is resolved, `url === 'file:///test/3.scss'`.
+//     //
+//     // That is, the paths of @import statements written to the `from` file is passed through unresolved,
+//     // but paths written to other files is passed through resolved to absolute paths.
+//     return new URL(url, pathToFileURL(from));
+//   },
+//   async load(canonicalUrl) {
+//     return {
+//       contents: await readFile(fileURLToPath(canonicalUrl.href), 'utf8'),
+//       syntax: 'scss',
+//       sourceMapUrl: canonicalUrl,
+//     };
+//   },
+// });
+
+// eslint-disable-next-line @typescript-eslint/consistent-type-imports
+async function renderSass(sass: typeof import('sass'), source: string, options: TransformerOptions) {
+  return new Promise<LegacyResult>((resolve, reject) => {
+    sass.render(
+      {
+        data: source,
+        file: options.from,
+        outFile: 'DUMMY', // Required for sourcemap output.
+        sourceMap: true,
+        importer: (url, prev, done) => {
+          options
+            .resolver(url, { request: prev })
+            .then((resolved) => done({ file: resolved }))
+            .catch((e) => done(e));
+        },
+      },
+      (exception, result) => {
+        if (exception) {
+          reject(exception);
+        } else {
+          resolve(result!);
+        }
+      },
+    );
+  });
+}
+
+export const createScssTransformer: () => Transformer = () => {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-imports
+  let sass: typeof import('sass');
+  return async (source, options) => {
+    sass ??= (await import('sass').catch(handleImportError('sass'))).default;
+    const result = await renderSass(sass, source, options);
+    return { css: result.css.toString(), map: result.map!.toString(), dependencies: result.stats.includedFiles };
+
+    // if (IS_JEST_ENVIRONMENT) verifyJestEnvironment();
+    // const result = await sass.default.compileStringAsync(source, {
+    //   url: pathToFileURL(from),
+    //   sourceMap: true,
+    //   importers: IS_JEST_ENVIRONMENT ? [createImporterForJest(from)] : [],
+    // });
+    // return { css: result.css, map: result.sourceMap!, dependencies: result.loadedUrls };
+  };
+};

package/src/util.test.ts

@@ -0,0 +1,89 @@
+import { join } from 'path';
+import { hasProp, isObject, isSystemError, unique, uniqueBy } from '../src/util.js';
+import { createFixtures, getFixturePath } from './test/util.js';
+import { isMatchByGlob, exists } from './util.js';
+
+function fakeSystemError({ code }: { code: string }) {
+  const error = new Error();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (error as any).code = code;
+  return error;
+}
+
+test('isSystemError', () => {
+  expect(isSystemError(fakeSystemError({ code: 'ENOENT' }))).toBe(true);
+  expect(isSystemError(fakeSystemError({ code: 'EACCES' }))).toBe(true);
+  expect(isSystemError(new Error('ENOENT'))).toBe(false);
+  expect(isSystemError({ code: 'ENOENT' })).toBe(false);
+});
+
+test('isObject', () => {
+  expect(isObject({})).toBe(true);
+  expect(isObject({ a: '1' })).toBe(true);
+  expect(isObject([])).toBe(true);
+  expect(
+    isObject(() => {
+      /* noop */
+    }),
+  ).toBe(true);
+  expect(isObject(null)).toBe(false);
+  expect(isObject(undefined)).toBe(false);
+  expect(isObject(1)).toBe(false);
+  expect(isObject('1')).toBe(false);
+  expect(isObject(true)).toBe(false);
+});
+
+test('hasProp', () => {
+  expect(hasProp({ a: '1' }, 'a')).toBe(true);
+  expect(hasProp({ a: '1' }, 'b')).toBe(false);
+  // it can check prototype
+  expect(hasProp({}, 'toString')).toBe(true);
+  expect(hasProp([], 'length')).toBe(true);
+});
+
+test('unique', () => {
+  expect(unique([0, 1, 1, 2, 1])).toStrictEqual([0, 1, 2]);
+});
+
+test('uniqueBy', () => {
+  expect(uniqueBy([], () => 0)).toStrictEqual([]);
+  expect(
+    uniqueBy(
+      [
+        { key: 'a', value: 0 },
+        { key: 'a', value: 1 },
+        { key: 'b', value: 2 },
+        { key: 'b', value: 3 },
+        { key: 'c', value: 4 },
+        { key: 'c', value: 5 },
+      ],
+      (el) => el.key,
+    ),
+  ).toStrictEqual([
+    { key: 'a', value: 0 },
+    { key: 'b', value: 2 },
+    { key: 'c', value: 4 },
+  ]);
+});
+
+test('exists', async () => {
+  createFixtures({
+    '/test/1.css': `.a {}`,
+  });
+  expect(await exists(getFixturePath('/test/1.css'))).toBe(true);
+  expect(await exists(getFixturePath('/test/2.css'))).toBe(false);
+});
+
+test('isMatchByGlob', () => {
+  const cwd = process.cwd();
+  expect(isMatchByGlob(join(cwd, '1.css'), '*.css', { cwd })).toBe(true);
+  expect(isMatchByGlob(join(cwd, '1.scss'), '*.css', { cwd })).toBe(false);
+  expect(isMatchByGlob(join(cwd, 'dir/1.css'), '**/*.css', { cwd })).toBe(true);
+  expect(isMatchByGlob(join(cwd, 'dir/dir/1.css'), '**/*.css', { cwd })).toBe(true);
+  expect(isMatchByGlob(join(cwd, '1.css'), '*.{css,scss}', { cwd })).toBe(true);
+  expect(isMatchByGlob(join(cwd, '1.scss'), '*.{css,scss}', { cwd })).toBe(true);
+  expect(isMatchByGlob(join(cwd, '1.less'), '*.{css,scss}', { cwd })).toBe(false);
+  expect(isMatchByGlob(join(cwd, '1.css'), '!(*.css)', { cwd })).toBe(false);
+  expect(isMatchByGlob(join(cwd, '1.scss'), '!(*.css)', { cwd })).toBe(true);
+  expect(isMatchByGlob(join(cwd, '1.less'), '!(*.css)', { cwd })).toBe(true);
+});

package/src/util.ts

@@ -0,0 +1,67 @@
+import { constants } from 'fs';
+import { access } from 'fs/promises';
+import { join } from 'path';
+import minimatch from 'minimatch';
+/**
+ * The SystemError type of Node.js.
+ * @see https://nodejs.org/api/errors.html#class-systemerror
+ */
+export interface SystemError {
+  code: string;
+}
+
+export function isSystemError(value: unknown): value is SystemError {
+  return (
+    isObject(value) &&
+    hasProp(value, 'constructor') &&
+    isObject(value.constructor) &&
+    hasProp(value.constructor, 'name') &&
+    value.constructor.name === 'Error' &&
+    hasProp(value, 'code') &&
+    typeof value.code === 'string'
+  );
+}
+
+export function isObject(value: unknown): value is object {
+  return (typeof value === 'object' || typeof value === 'function') && value !== null;
+}
+
+export function hasProp<T extends string>(obj: object, prop: T): obj is { [key in T]: unknown } {
+  return prop in obj;
+}
+
+export function unique<T>(array: T[]): T[] {
+  return [...new Set(array)];
+}
+
+export function uniqueBy<T, U>(arr: T[], fn: (el: T) => U): T[] {
+  const result: T[] = [];
+  const keys = new Set<U>();
+  for (const el of arr) {
+    const key = fn(el);
+    if (!keys.has(key)) {
+      keys.add(key);
+      result.push(el);
+    }
+  }
+  return result;
+}
+
+export function sleepSync(ms: number) {
+  const start = Date.now();
+  // eslint-disable-next-line no-empty
+  while (Date.now() - start < ms) {}
+}
+
+export async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+export function isMatchByGlob(filePath: string, pattern: string, options: { cwd: string }): boolean {
+  return minimatch(filePath, join(options.cwd, pattern));
+}