happy-css-modules 0.2.0

package/src/__snapshots__/runner.test.ts.snap

@@ -0,0 +1,34 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`generates .d.ts and .d.ts.map 1`] = `
+"declare const styles:
+  & Readonly<{ "a": string }>
+;
+export default styles;
+//# sourceMappingURL=./1.css.d.ts.map
+"
+`;
+
+exports[`generates .d.ts and .d.ts.map 2`] = `"{"version":3,"sources":["./1.css"],"names":["a"],"mappings":"AAAA;AAAA,E,aAAAA,G,WAAA;AAAA;AAAA","file":"1.css.d.ts","sourceRoot":""}"`;
+
+exports[`generates .d.ts and .d.ts.map 3`] = `
+"declare const styles:
+  & Readonly<{ "b": string }>
+;
+export default styles;
+//# sourceMappingURL=./2.css.d.ts.map
+"
+`;
+
+exports[`generates .d.ts and .d.ts.map 4`] = `"{"version":3,"sources":["./2.css"],"names":["b"],"mappings":"AAAA;AAAA,E,aAAAA,G,WAAA;AAAA;AAAA","file":"2.css.d.ts","sourceRoot":""}"`;
+
+exports[`supports transformer 1`] = `
+"declare const styles:
+  & Readonly<{ "a": string }>
+;
+export default styles;
+//# sourceMappingURL=./1.scss.d.ts.map
+"
+`;
+
+exports[`supports transformer 2`] = `"{"version":3,"sources":["./1.scss"],"names":["a"],"mappings":"AAAA;AAAA,E,aAAAA,G,WAAA;AAAA;AAAA","file":"1.scss.d.ts","sourceRoot":""}"`;

package/src/cli.test.ts

@@ -0,0 +1,38 @@
+import { parseArgv } from './cli.js';
+
+const baseArgs = ['node', 'hcm'];
+
+describe('parseArgv', () => {
+  test('pattern', () => {
+    expect(parseArgv([...baseArgs, 'foo']).pattern).toStrictEqual('foo');
+    expect(parseArgv([...baseArgs, '1']).pattern).toStrictEqual('1');
+
+    // TODO: Support multiple patterns
+    // parseArgv([...baseArgs, 'foo', 'bar']);
+  });
+  test('--outDir', () => {
+    expect(parseArgv([...baseArgs, '1.css', '--outDir', 'foo']).outDir).toStrictEqual('foo');
+    expect(parseArgv([...baseArgs, '1.css', '--outDir', '1']).outDir).toStrictEqual('1');
+  });
+  test('--watch', () => {
+    expect(parseArgv([...baseArgs, '1.css', '--watch']).watch).toBe(true);
+    expect(parseArgv([...baseArgs, '1.css', '--no-watch']).watch).toBe(false);
+  });
+  test('--localsConvention', () => {
+    expect(parseArgv([...baseArgs, '1.css']).localsConvention).toBe(undefined);
+    expect(parseArgv([...baseArgs, '1.css', '--localsConvention', 'camelCaseOnly']).localsConvention).toBe(
+      'camelCaseOnly',
+    );
+    expect(parseArgv([...baseArgs, '1.css', '--localsConvention', 'camelCase']).localsConvention).toBe('camelCase');
+    expect(parseArgv([...baseArgs, '1.css', '--localsConvention', 'dashesOnly']).localsConvention).toBe('dashesOnly');
+    expect(parseArgv([...baseArgs, '1.css', '--localsConvention', 'dashes']).localsConvention).toBe('dashes');
+  });
+  test('--declarationMap', () => {
+    expect(parseArgv([...baseArgs, '1.css', '--declarationMap']).declarationMap).toBe(true);
+    expect(parseArgv([...baseArgs, '1.css', '--no-declarationMap']).declarationMap).toBe(false);
+  });
+  test('--silent', () => {
+    expect(parseArgv([...baseArgs, '1.css', '--silent']).silent).toBe(true);
+    expect(parseArgv([...baseArgs, '1.css', '--no-silent']).silent).toBe(false);
+  });
+});

package/src/cli.ts

@@ -0,0 +1,70 @@
+import { readFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { type RunnerOptions } from './runner.js';
+
+const pkgJson = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '../package.json'), 'utf-8'));
+
+/**
+ * Parse command line arguments.
+ * @returns Runner options.
+ */
+export function parseArgv(argv: string[]): RunnerOptions {
+  const parsedArgv = yargs(hideBin(argv))
+    .parserConfiguration({
+      // workaround for https://github.com/yargs/yargs/issues/1318
+      'duplicate-arguments-array': false,
+    })
+    .scriptName('hcm')
+    .usage('Create .d.ts and .d.ts.map from CSS modules *.css files.\n\n$0 [options] <glob>')
+    .example("$0 'src/**/*.module.css'", 'Generate .d.ts and .d.ts.map.')
+    .example("$0 'src/**/*.module.{css,scss,less}'", 'Also generate files for sass and less.')
+    .example("$0 'src/**/*.module.css' --watch", 'Watch for changes and generate .d.ts and .d.ts.map.')
+    .example("$0 'src/**/*.module.css' --declarationMap=false", 'Generate .d.ts only.')
+    .detectLocale(false)
+    .option('outDir', {
+      type: 'string',
+      describe: 'Output directory',
+    })
+    .option('watch', {
+      type: 'boolean',
+      alias: 'w',
+      default: false,
+      describe: "Watch input directory's css files or pattern",
+    })
+    .option('localsConvention', {
+      choices: ['camelCase', 'camelCaseOnly', 'dashes', 'dashesOnly'] as const,
+      describe: 'Style of exported class names.',
+    })
+    .option('declarationMap', {
+      type: 'boolean',
+      default: true,
+      describe: 'Create sourcemaps for d.ts files',
+    })
+    .option('silent', {
+      type: 'boolean',
+      default: false,
+      describe: 'Silent output. Do not show "files written" messages',
+    })
+    .alias('h', 'help')
+    .alias('v', 'version')
+    .version(pkgJson.version)
+    .check((argv) => {
+      const patterns = argv._;
+      // TODO: support multiple patterns
+      if (patterns.length !== 1) throw new Error('Only one pattern is allowed.');
+      return true;
+    })
+    .parseSync();
+  const patterns: string[] = parsedArgv._.map((pattern) => pattern.toString());
+  return {
+    pattern: patterns[0]!,
+    outDir: parsedArgv.outDir,
+    watch: parsedArgv.watch,
+    localsConvention: parsedArgv.localsConvention,
+    declarationMap: parsedArgv.declarationMap,
+    silent: parsedArgv.silent,
+  };
+}

package/src/emitter/dts.test.ts

@@ -0,0 +1,266 @@
+import dedent from 'dedent';
+import { SourceMapConsumer } from 'source-map';
+import { Loader } from '../loader/index.js';
+import { getFixturePath, createFixtures } from '../test/util.js';
+import { generateDtsContentWithSourceMap, getDtsFilePath } from './dts.js';
+import { type DtsFormatOptions } from './index.js';
+
+const loader = new Loader();
+const isExternalFile = () => false;
+
+test('getDtsFilePath', () => {
+  expect(getDtsFilePath('/app/src/dir/1.css', undefined)).toBe('/app/src/dir/1.css.d.ts');
+  expect(getDtsFilePath('/app/src/dir/1.css', { rootDir: '/app', outDir: '/app/dist' })).toBe(
+    '/app/dist/src/dir/1.css.d.ts',
+  );
+  expect(() => getDtsFilePath('/tmp/src/dir/1.css', { rootDir: '/app', outDir: '/app/dist' })).toThrow();
+  expect(() => getDtsFilePath('/app/src/dir/1.css', { rootDir: '/app', outDir: '/tmp/dist' })).toThrow();
+});
+
+describe('generateDtsContentWithSourceMap', () => {
+  const filePath = getFixturePath('/test/1.css');
+  const dtsFilePath = getFixturePath('/test/1.css.d.ts');
+  const sourceMapFilePath = getFixturePath('/test/1.css.map');
+  const dtsFormatOptions: DtsFormatOptions = {
+    localsConvention: undefined,
+  };
+  test('generate dts content with source map', async () => {
+    createFixtures({
+      '/test/1.css': dedent`
+      @import './2.css';
+      .a {}
+      .b {}
+      .b {}
+      `,
+      '/test/2.css': dedent`
+      @import './3.css';
+      .c {}
+      `,
+      '/test/3.css': dedent`
+      .d {}
+      `,
+    });
+    const result = await loader.load(filePath);
+    const { dtsContent, sourceMap } = generateDtsContentWithSourceMap(
+      filePath,
+      dtsFilePath,
+      sourceMapFilePath,
+      result.tokens,
+      dtsFormatOptions,
+      isExternalFile,
+    );
+    expect(dtsContent).toMatchInlineSnapshot(`
+      "declare const styles:
+        & Readonly<Pick<(typeof import("./3.css"))["default"], "d">>
+        & Readonly<Pick<(typeof import("./2.css"))["default"], "c">>
+        & Readonly<{ "a": string }>
+        & Readonly<{ "b": string }>
+        & Readonly<{ "b": string }>
+      ;
+      export default styles;
+      "
+    `);
+    const smc = await new SourceMapConsumer(sourceMap.toJSON());
+    expect(smc.originalPositionFor({ line: 4, column: 15 })).toMatchInlineSnapshot(`
+      {
+        "column": 0,
+        "line": 2,
+        "name": "a",
+        "source": "1.css",
+      }
+    `);
+    expect(smc.originalPositionFor({ line: 5, column: 15 })).toMatchInlineSnapshot(`
+      {
+        "column": 0,
+        "line": 3,
+        "name": "b",
+        "source": "1.css",
+      }
+    `);
+    expect(smc.originalPositionFor({ line: 6, column: 15 })).toMatchInlineSnapshot(`
+      {
+        "column": 0,
+        "line": 4,
+        "name": "b",
+        "source": "1.css",
+      }
+    `);
+  });
+  describe('format case', () => {
+    async function getResult(filePath: string) {
+      createFixtures({
+        '/test/1.css': dedent`
+        .foo-bar {}
+        .foo_bar {}
+        `,
+      });
+      return await loader.load(filePath);
+    }
+    test('undefined', async () => {
+      const result = await getResult(filePath);
+      const { dtsContent } = generateDtsContentWithSourceMap(
+        filePath,
+        dtsFilePath,
+        sourceMapFilePath,
+        result.tokens,
+        {
+          ...dtsFormatOptions,
+          localsConvention: undefined,
+        },
+        isExternalFile,
+      );
+      expect(dtsContent).toMatchInlineSnapshot(`
+        "declare const styles:
+          & Readonly<{ "foo-bar": string }>
+          & Readonly<{ "foo_bar": string }>
+        ;
+        export default styles;
+        "
+      `);
+    });
+    test('camelCaseOnly', async () => {
+      const result = await getResult(filePath);
+      const { dtsContent } = generateDtsContentWithSourceMap(
+        filePath,
+        dtsFilePath,
+        sourceMapFilePath,
+        result.tokens,
+        {
+          ...dtsFormatOptions,
+          localsConvention: 'camelCaseOnly',
+        },
+        isExternalFile,
+      );
+      expect(dtsContent).toMatchInlineSnapshot(`
+        "declare const styles:
+          & Readonly<{ "fooBar": string }>
+          & Readonly<{ "fooBar": string }>
+        ;
+        export default styles;
+        "
+      `);
+    });
+    test('camelCase', async () => {
+      const result = await getResult(filePath);
+      const { dtsContent } = generateDtsContentWithSourceMap(
+        filePath,
+        dtsFilePath,
+        sourceMapFilePath,
+        result.tokens,
+        {
+          ...dtsFormatOptions,
+          localsConvention: 'camelCase',
+        },
+        isExternalFile,
+      );
+      expect(dtsContent).toMatchInlineSnapshot(`
+        "declare const styles:
+          & Readonly<{ "foo-bar": string }>
+          & Readonly<{ "fooBar": string }>
+          & Readonly<{ "foo_bar": string }>
+          & Readonly<{ "fooBar": string }>
+        ;
+        export default styles;
+        "
+      `);
+    });
+    test('dashesOnly', async () => {
+      const result = await getResult(filePath);
+      const { dtsContent } = generateDtsContentWithSourceMap(
+        filePath,
+        dtsFilePath,
+        sourceMapFilePath,
+        result.tokens,
+        {
+          ...dtsFormatOptions,
+          localsConvention: 'dashesOnly',
+        },
+        isExternalFile,
+      );
+      expect(dtsContent).toMatchInlineSnapshot(`
+        "declare const styles:
+          & Readonly<{ "fooBar": string }>
+          & Readonly<{ "foo_bar": string }>
+        ;
+        export default styles;
+        "
+      `);
+    });
+    test('dashes', async () => {
+      const result = await getResult(filePath);
+      const { dtsContent } = generateDtsContentWithSourceMap(
+        filePath,
+        dtsFilePath,
+        sourceMapFilePath,
+        result.tokens,
+        {
+          ...dtsFormatOptions,
+          localsConvention: 'dashes',
+        },
+        isExternalFile,
+      );
+      expect(dtsContent).toMatchInlineSnapshot(`
+        "declare const styles:
+          & Readonly<{ "foo-bar": string }>
+          & Readonly<{ "fooBar": string }>
+          & Readonly<{ "foo_bar": string }>
+          & Readonly<{ "foo_bar": string }>
+        ;
+        export default styles;
+        "
+      `);
+    });
+  });
+  test('emit other directory', async () => {
+    createFixtures({
+      '/test/1.css': `.a {}`,
+    });
+    const result = await loader.load(filePath);
+    const { dtsContent, sourceMap } = generateDtsContentWithSourceMap(
+      getFixturePath('/test/src/1.css'),
+      getFixturePath('/test/dist/1.css.d.ts'),
+      getFixturePath('/test/dist/1.css.d.ts.map'),
+      result.tokens,
+      dtsFormatOptions,
+      isExternalFile,
+    );
+    expect(dtsContent).toMatchInlineSnapshot(`
+      "declare const styles:
+        & Readonly<Pick<(typeof import("../1.css"))["default"], "a">>
+      ;
+      export default styles;
+      "
+    `);
+    expect(sourceMap.toJSON().sources).toStrictEqual(['../src/1.css']);
+    expect(sourceMap.toJSON().file).toStrictEqual('1.css.d.ts');
+  });
+  test('treats imported tokens from external files the same as local tokens', async () => {
+    createFixtures({
+      '/test/1.css': dedent`
+      @import './2.css';
+      @import './3.css';
+      .a {}
+      `,
+      '/test/2.css': `.b {}`,
+      '/test/3.css': `.c {}`,
+    });
+    const result = await loader.load(filePath);
+    const { dtsContent } = generateDtsContentWithSourceMap(
+      filePath,
+      dtsFilePath,
+      sourceMapFilePath,
+      result.tokens,
+      dtsFormatOptions,
+      (filePath) => filePath.endsWith('3.css'),
+    );
+    expect(dtsContent).toMatchInlineSnapshot(`
+      "declare const styles:
+        & Readonly<Pick<(typeof import("./2.css"))["default"], "b">>
+        & Readonly<{ "c": string }>
+        & Readonly<{ "a": string }>
+      ;
+      export default styles;
+      "
+    `);
+  });
+});

package/src/emitter/dts.ts

@@ -0,0 +1,134 @@
+import { EOL } from 'os';
+import { join, relative, basename } from 'path';
+import camelcase from 'camelcase';
+import { SourceNode, type CodeWithSourceMap } from '../library/source-map/index.js';
+import { type Token } from '../loader/index.js';
+import { type LocalsConvention } from '../runner.js';
+import { type DistOptions, getRelativePath, isSubDirectoryFile, type DtsFormatOptions } from './index.js';
+
+/**
+ * Get .d.ts file path.
+ * @param filePath The path to the source file (i.e. `/dir/foo.css`). It is absolute.
+ * @param distOptions The distribution option.
+ * @returns The path to the .d.ts file. It is absolute.
+ */
+export function getDtsFilePath(filePath: string, distOptions: DistOptions | undefined): string {
+  if (distOptions) {
+    if (!isSubDirectoryFile(distOptions.rootDir, filePath))
+      throw new Error(`The filePath(${filePath}) is not a subdirectory of rootDir(${distOptions.rootDir}).`);
+    if (!isSubDirectoryFile(distOptions.rootDir, distOptions.outDir))
+      throw new Error(`The outDir(${distOptions.outDir}) is not a subdirectory of rootDir(${distOptions.rootDir}).`);
+    return join(distOptions.outDir, relative(distOptions.rootDir, filePath) + '.d.ts');
+  } else {
+    return filePath + '.d.ts';
+  }
+}
+
+function dashesCamelCase(str: string): string {
+  return str.replace(/-+(\w)/g, function (match, firstLetter) {
+    return firstLetter.toUpperCase();
+  });
+}
+
+function formatTokens(tokens: Token[], localsConvention: LocalsConvention): Token[] {
+  const result: Token[] = [];
+  for (const token of tokens) {
+    if (localsConvention === 'camelCaseOnly') {
+      result.push({ ...token, name: camelcase(token.name) });
+    } else if (localsConvention === 'camelCase') {
+      result.push(token);
+      result.push({ ...token, name: camelcase(token.name) });
+    } else if (localsConvention === 'dashesOnly') {
+      result.push({ ...token, name: dashesCamelCase(token.name) });
+    } else if (localsConvention === 'dashes') {
+      result.push(token);
+      result.push({ ...token, name: dashesCamelCase(token.name) });
+    } else {
+      result.push(token); // asIs
+    }
+  }
+  return result;
+}
+
+function generateTokenDeclarations(
+  filePath: string,
+  sourceMapFilePath: string,
+  tokens: Token[],
+  dtsFormatOptions: DtsFormatOptions | undefined,
+  isExternalFile: (filePath: string) => boolean,
+): typeof SourceNode[] {
+  const formattedTokens = formatTokens(tokens, dtsFormatOptions?.localsConvention);
+  const result: typeof SourceNode[] = [];
+
+  for (const token of formattedTokens) {
+    // Only one original position can be associated with one generated position.
+    // This is due to the sourcemap specification. Therefore, we output multiple type definitions
+    // with the same name and assign a separate original position to each.
+
+    for (const originalLocation of token.originalLocations) {
+      result.push(
+        originalLocation.filePath === filePath || isExternalFile(originalLocation.filePath)
+          ? new SourceNode(null, null, null, [
+              '& Readonly<{ ',
+              new SourceNode(
+                originalLocation.start.line ?? null,
+                // The SourceNode's column is 0-based, but the originalLocation's column is 1-based.
+                originalLocation.start.column - 1 ?? null,
+                getRelativePath(sourceMapFilePath, originalLocation.filePath),
+                `"${token.name}"`,
+                token.name,
+              ),
+              ': string }>',
+            ])
+          : // Imported tokens in non-external files are typed by dynamic import.
+            // See https://github.com/mizdra/happy-css-modules/issues/106.
+            new SourceNode(null, null, null, [
+              '& Readonly<Pick<(typeof import(',
+              `"${getRelativePath(filePath, originalLocation.filePath)}"`,
+              '))["default"], ',
+              `"${token.name}"`,
+              '>>',
+            ]),
+      );
+    }
+  }
+  return result;
+}
+
+export function generateDtsContentWithSourceMap(
+  filePath: string,
+  dtsFilePath: string,
+  sourceMapFilePath: string,
+  tokens: Token[],
+  dtsFormatOptions: DtsFormatOptions | undefined,
+  isExternalFile: (filePath: string) => boolean,
+): { dtsContent: CodeWithSourceMap['code']; sourceMap: CodeWithSourceMap['map'] } {
+  const tokenDeclarations = generateTokenDeclarations(
+    filePath,
+    sourceMapFilePath,
+    tokens,
+    dtsFormatOptions,
+    isExternalFile,
+  );
+
+  let sourceNode: typeof SourceNode;
+  if (!tokenDeclarations || !tokenDeclarations.length) {
+    sourceNode = new SourceNode(null, null, null, '');
+  } else {
+    sourceNode = new SourceNode(1, 0, getRelativePath(sourceMapFilePath, filePath), [
+      'declare const styles:' + EOL,
+      ...tokenDeclarations.map((tokenDeclaration) => ['  ', tokenDeclaration, EOL]),
+      ';' + EOL,
+      'export default styles;' + EOL,
+    ]);
+  }
+  const codeWithSourceMap = sourceNode.toStringWithSourceMap({
+    // Since sourcemap and type definitions are in the same directory, they can be referenced by relative paths.
+    file: basename(dtsFilePath),
+    sourceRoot: '',
+  });
+  return {
+    dtsContent: codeWithSourceMap.code,
+    sourceMap: codeWithSourceMap.map,
+  };
+}

package/src/emitter/file-system.test.ts

@@ -0,0 +1,36 @@
+import { readFile, rm, stat } from 'fs/promises';
+import { createFixtures, getFixturePath } from '../test/util.js';
+import { writeFileIfChanged } from './file-system.js';
+
+const TEST_FILE_PATH = getFixturePath('/test.txt');
+const TEST_NESTED_FILE_PATH = getFixturePath('/dir/test.txt');
+const OLD_CONTENT = 'old';
+const NEW_CONTENT = 'new';
+
+beforeEach(async () => {
+  createFixtures({});
+  await writeFileIfChanged(TEST_FILE_PATH, OLD_CONTENT);
+});
+
+describe('writeFileIfChanged', () => {
+  test('should write file if changed', async () => {
+    await writeFileIfChanged(TEST_FILE_PATH, NEW_CONTENT);
+    expect(await readFile(TEST_FILE_PATH, 'utf8')).toBe(NEW_CONTENT);
+  });
+  test('should not write file if not changed', async () => {
+    const oldStat = await stat(TEST_FILE_PATH);
+    await writeFileIfChanged(TEST_FILE_PATH, OLD_CONTENT);
+    const newStat = await stat(TEST_FILE_PATH);
+    expect(oldStat.mtimeMs).toBe(newStat.mtimeMs);
+  });
+  test("should create new file if it doesn't exist", async () => {
+    await rm(TEST_FILE_PATH);
+    await writeFileIfChanged(TEST_FILE_PATH, NEW_CONTENT);
+    expect(await readFile(TEST_FILE_PATH, 'utf8')).toBe(NEW_CONTENT);
+  });
+  test('should write file in nested directories', async () => {
+    await writeFileIfChanged(TEST_NESTED_FILE_PATH, NEW_CONTENT);
+    expect(await readFile(TEST_NESTED_FILE_PATH, 'utf8')).toBe(NEW_CONTENT);
+    await writeFileIfChanged(TEST_NESTED_FILE_PATH, NEW_CONTENT);
+  });
+});

package/src/emitter/file-system.ts

@@ -0,0 +1,24 @@
+import { mkdir, readFile, writeFile } from 'fs/promises';
+import { dirname } from 'path';
+import { isSystemError } from '../util.js';
+
+/**
+ * Write a file if it doesn't exist or is changed.
+ * @param filePath The file path.
+ * @param newContent The new content of the file.
+ */
+export async function writeFileIfChanged(filePath: string, newContent: string): Promise<void> {
+  try {
+    const content = await readFile(filePath, 'utf8');
+    if (content !== newContent) {
+      await writeFile(filePath, newContent, 'utf8');
+    }
+  } catch (e) {
+    if (isSystemError(e) && e.code === 'ENOENT') {
+      await mkdir(dirname(filePath), { recursive: true }); // if directory doesn't exist, create it
+      await writeFile(filePath, newContent, 'utf8');
+    } else {
+      throw e;
+    }
+  }
+}