happy-css-modules 2.0.0 → 2.1.1

package/src/runner.ts

@@ -7,6 +7,7 @@ import AwaitLock from 'await-lock';
 import chalk from 'chalk';
 import * as chokidar from 'chokidar';
 import _glob from 'glob';
+import { DEFAULT_ARBITRARY_EXTENSIONS } from './config.js';
 import { isGeneratedFilesExist, emitGeneratedFiles } from './emitter/index.js';
 import { Locator } from './locator/index.js';
 import { Logger } from './logger.js';
@@ -26,6 +27,10 @@ export type LocalsConvention = 'camelCase' | 'camelCaseOnly' | 'dashes' | 'dashe
 export interface RunnerOptions {
   pattern: string;
   watch?: boolean | undefined;
+  /**
+   * Style of exported class names.
+   * @default undefined
+   */
   localsConvention?: LocalsConvention | undefined;
   declarationMap?: boolean | undefined;
   transformer?: Transformer | undefined;
@@ -55,6 +60,11 @@ export interface RunnerOptions {
    * @example '/home/user/repository/src'
    */
   postcssConfig?: string | undefined;
+  /**
+   * Generate `.d.css.ts` instead of `.css.d.ts`.
+   * @default false
+   */
+  arbitraryExtensions?: boolean | undefined;
   /**
    * Only generate .d.ts and .d.ts.map for changed files.
    * @default true
@@ -126,7 +136,11 @@ export async function run(options: RunnerOptions): Promise<Watcher | void> {
     await lock.acquireAsync();
 
     try {
-      const _isGeneratedFilesExist = await isGeneratedFilesExist(filePath, options.declarationMap);
+      const _isGeneratedFilesExist = await isGeneratedFilesExist(
+        filePath,
+        options.declarationMap,
+        options.arbitraryExtensions ?? DEFAULT_ARBITRARY_EXTENSIONS,
+      );
       const _isChangedFile = await isChangedFile(filePath);
       // Generate .d.ts and .d.ts.map only when the file has been updated.
       // However, if .d.ts or .d.ts.map has not yet been generated, always generate.
@@ -142,6 +156,7 @@ export async function run(options: RunnerOptions): Promise<Watcher | void> {
         emitDeclarationMap: options.declarationMap,
         dtsFormatOptions: {
           localsConvention: options.localsConvention,
+          arbitraryExtensions: options.arbitraryExtensions,
         },
         isExternalFile,
       });

package/src/test-util/tsserver.ts

@@ -7,9 +7,8 @@ import serverHarness from '@typescript/server-harness';
 import _glob from 'glob';
 import { resolve } from 'import-meta-resolve';
 import lineColumn from 'line-column';
-import type { UpdateOpenRequest, DefinitionResponse, DefinitionRequest } from 'typescript/lib/protocol.js';
+import type { server } from 'typescript/lib/tsserverlibrary.js';
 import { getFixturePath } from './util.js';
-
 const glob = promisify(_glob);
 
 async function writeFile(path: string, content: string): Promise<void> {
@@ -68,7 +67,7 @@ export async function createTSServer() {
       const results: { identifier: string; definitions: Definition[] }[] = [];
 
       for (let i = 0; i < identifiers.length; i++) {
-        const response: DefinitionResponse = await server.message({
+        const response: server.protocol.DefinitionResponse = await server.message({
           seq: 0,
           type: 'request',
           command: 'definition',
@@ -77,7 +76,7 @@ export async function createTSServer() {
             line: i + 2, // line, 1-based
             offset: 8, // column, 1-based
           },
-        } as DefinitionRequest);
+        } as server.protocol.DefinitionRequest);
         const definitions: Definition[] = response.body!.map((definition) => {
           const { file, start, end } = definition;
           const fileContent = readFileSync(file, 'utf-8');
@@ -100,7 +99,7 @@ export async function createTSServer() {
 
       await this.refreshCache();
 
-      const response: DefinitionResponse = await server.message({
+      const response: server.protocol.DefinitionResponse = await server.message({
         seq: 0,
         type: 'request',
         command: 'definition',
@@ -109,7 +108,7 @@ export async function createTSServer() {
           line: 1, // line, 1-based
           offset: 20, // column, 1-based
         },
-      } as DefinitionRequest);
+      } as server.protocol.DefinitionRequest);
       const definitions: Definition[] = response.body!.map((definition) => {
         const { file, start, end } = definition;
         const fileContent = readFileSync(file, 'utf-8');
@@ -127,12 +126,14 @@ export async function createTSServer() {
 
       const fixtureFilePaths = await glob(getFixturePath('/**/*.ts'), { dot: true });
       // latest contents
-      const openFiles: UpdateOpenRequest['arguments']['openFiles'] = fixtureFilePaths.map((filePath) => ({
-        file: filePath,
-        fileContent: readFileSync(filePath, 'utf-8'),
-        projectRootPath: getFixturePath('/server-harness'),
-        scriptKindName: 'TS', // It's easy to get this wrong when copy-pasting
-      }));
+      const openFiles: server.protocol.UpdateOpenRequest['arguments']['openFiles'] = fixtureFilePaths.map(
+        (filePath) => ({
+          file: filePath,
+          fileContent: readFileSync(filePath, 'utf-8'),
+          projectRootPath: getFixturePath('/server-harness'),
+          scriptKindName: 'TS', // It's easy to get this wrong when copy-pasting
+        }),
+      );
 
       // override the cache
       await server.message({
@@ -144,7 +145,7 @@ export async function createTSServer() {
           closedFiles: [],
           openFiles,
         },
-      } as UpdateOpenRequest);
+      } as server.protocol.UpdateOpenRequest);
     },
     exit: async () => {
       await server.message({ command: 'exit' });

package/src/transformer/postcss-transformer.ts

@@ -1,6 +1,6 @@
 import { createRequire } from 'node:module';
 import { resolve } from 'node:path';
-import { default as postcss, type Message } from 'postcss';
+import postcss, { type Message } from 'postcss';
 import type { Result } from 'postcss-load-config';
 import type { Transformer } from '../index.js';
 
@@ -44,7 +44,7 @@ export const createPostcssTransformer: (postcssTransformerOptions?: PostcssTrans
     });
     if (postcssConfig === undefined) return false;
 
-    const result = await postcss(postcssConfig.plugins).process(source, {
+    const result = await postcss.default(postcssConfig.plugins).process(source, {
       ...postcssConfig.options,
       from: options.from,
       map: { inline: false, absolute: true },

package/src/util.test.ts

@@ -1,7 +1,6 @@
 import { join } from 'path';
-import { hasProp, isObject, isSystemError, unique, uniqueBy } from '../src/util.js';
 import { createFixtures, getFixturePath } from './test-util/util.js';
-import { isMatchByGlob, exists } from './util.js';
+import { hasProp, isObject, isSystemError, unique, uniqueBy, isMatchByGlob, exists } from './util.js';
 
 function fakeSystemError({ code }: { code: string }) {
   const error = new Error();

package/LICENSE.txt

@@ -1,23 +0,0 @@
-The MIT License (MIT)
-
-Copyright (c) 2022 mizdra
-Copyright (c) [2016] [Yosuke Kurami]
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-

package/README.md

@@ -1,277 +0,0 @@
-<p align="center">
-  <img alt="Cover image" src="./docs/cover.svg" />
-</p>
-
-<h2 align="center">Happy CSS Modules</h2>
-
-<p align="center">
-  <em>Typed, definition jumpable CSS Modules.</em>
-  <br />
-  <em>Moreover, easy!</em>
-</p>
-
-https://user-images.githubusercontent.com/9639995/189538880-872ad38d-2c9d-4c19-b257-521018963eec.mov
-
-## Features
-
-- :white_check_mark: Strict type checking
-  - Generate `.d.ts` of CSS Modules for type checking
-- :mag: Definition jumps
-  - Clicking on a property on `.jsx`/`.tsx` will jump to the source of the definition on `.module.css`.
-  - This is accomplished by generating `.d.ts.map` (a.k.a. [Declaration Map](https://www.typescriptlang.org/tsconfig#declarationMap)).
-- :handshake: High compatibility with the ecosystem
-  - Support for Postcss/Sass/Less
-  - Implement webpack-compatible resolving algorithms
-  - Also supports [`resolve.alias`](https://webpack.js.org/configuration/resolve/#resolvealias)
-- :beginner: Easy to use
-  - No configuration file, some simple CLI options
-
-## Installation
-
-```console
-$ npm i -D happy-css-modules
-```
-
-## Usage
-
-In the simple case, everything goes well with the following!
-
-```console
-$ hcm 'src/**/*.module.{css,scss,less}'
-```
-
-If you want to customize the behavior, see `--help`.
-
-```console
-$ hcm --help
-Generate .d.ts and .d.ts.map for CSS modules.
-
-hcm [options] <glob>
-
-Options:
-  -w, --watch                Watch input directory's css files or pattern                                         [boolean] [default: false]
-      --localsConvention     Style of exported class names.                  [choices: "camelCase", "camelCaseOnly", "dashes", "dashesOnly"]
-      --declarationMap       Create sourcemaps for d.ts files                                                      [boolean] [default: true]
-      --sassLoadPaths        The option compatible with sass's `--load-path`.                                                        [array]
-      --lessIncludePaths     The option compatible with less's `--include-path`.                                                     [array]
-      --webpackResolveAlias  The option compatible with webpack's `resolve.alias`.                                                  [string]
-      --postcssConfig        The option compatible with postcss's `--config`.                                                       [string]
-      --cache                Only generate .d.ts and .d.ts.map for changed files.                                  [boolean] [default: true]
-      --cacheStrategy        Strategy for the cache to use for detecting changed files.[choices: "content", "metadata"] [default: "content"]
-      --logLevel             What level of logs to report.                            [choices: "debug", "info", "silent"] [default: "info"]
-  -h, --help                 Show help                                                                                             [boolean]
-  -v, --version              Show version number                                                                                   [boolean]
-
-Examples:
-  hcm 'src/**/*.module.css'                                       Generate .d.ts and .d.ts.map.
-  hcm 'src/**/*.module.{css,scss,less}'                           Also generate files for sass and less.
-  hcm 'src/**/*.module.css' --watch                               Watch for changes and generate .d.ts and .d.ts.map.
-  hcm 'src/**/*.module.css' --declarationMap=false                Generate .d.ts only.
-  hcm 'src/**/*.module.css' --sassLoadPaths=src/style             Run with sass's `--load-path`.
-  hcm 'src/**/*.module.css' --lessIncludePaths=src/style          Run with less's `--include-path`.
-  hcm 'src/**/*.module.css' --webpackResolveAlias='{"@": "src"}'  Run with webpack's `resolve.alias`.
-  hcm 'src/**/*.module.css' --cache=false                         Disable cache.
-```
-
-## How docs definition jumps work?
-
-In addition to `.module.css.d.ts`, happy-css-modules also generates a `.module.css.d.ts.map` file (a.k.a. [Declaration Map](https://www.typescriptlang.org/tsconfig#declarationMap)). This file is a Source Map that contains code mapping information from generated (`.module.css.d.ts`) to source (`.module.css`).
-
-When tsserver (TypeScript Language Server for VSCode) tries to jump to the code on `.module.css.d.ts`, it restores the original location from this Source Map and redirects to the code on` .module.css`. happy-css-modules uses this mechanism to realize definition jump.
-
-![Illustration of how definition jump works](docs/how-does-definition-jumps-work/basic/flow.drawio.svg)
-
-The case of multiple definitions is a bit more complicated. This is because the Source Map specification does not allow for a 1:N mapping of the generated:original locations. Therefore, happy-css-modules define multiple definitions of the same property type and map each property to a different location in `.module.css`.
-
-![Illustration of a case with multiple definitions](docs/how-does-definition-jumps-work/multiple-definitions/flow.drawio.svg)
-
-## Node.js API (Experimental)
-
-> **Warning**
-> This feature is experimental and may change significantly. The API is not stable and may have breaking changes even in minor or patch version updates.
-
-`happy-css-modules` provides Node.js API for programmatically generating .d.ts and .d.ts.map.
-
-See [src/index.ts](https://github.com/mizdra/happy-css-modules/blob/main/src/index.ts) for available API.
-
-### Example: Custom `hcm` commands
-
-You can create your own customized `hcm` commands. We also provide a `parseArgv` utility that parses `process.argv` and extracts options.
-
-```javascript
-#!/usr/bin/env ts-node
-// scripts/hcm.ts
-
-import { run, parseArgv } from 'happy-css-modules';
-
-// Write your code here...
-
-run({
-  // Inherit default CLI options (e.g. --watch).
-  ...parseArgv(process.argv),
-  // Add custom CLI options.
-  cwd: __dirname,
-}).catch((e) => {
-  console.error(e);
-  process.exit(1);
-});
-```
-
-### Example: Custom transformer
-
-With the `transformer` option, you can use AltCSS, which is not supported by `happy-css-modules`.
-
-```typescript
-#!/usr/bin/env ts-node
-
-import { run, parseArgv, createDefaultTransformer, type Transformer } from 'happy-css-modules';
-import sass from 'sass';
-import { promisify } from 'util';
-
-const defaultTransformer = createDefaultTransformer();
-const render = promisify(sass.render);
-
-// The custom transformer supporting sass indented syntax
-const transformer: Transformer = async (source, options) => {
-  if (from.endsWith('.sass')) {
-    const result = await render({
-      // Use indented syntax.
-      // ref: https://sass-lang.com/documentation/syntax#the-indented-syntax
-      indentedSyntax: true,
-      data: source,
-      file: options.from,
-      outFile: 'DUMMY',
-      // Output sourceMap.
-      sourceMap: true,
-      // Resolve import specifier using resolver.
-      importer: (url, prev, done) => {
-        options
-          .resolver(url, { request: prev })
-          .then((resolved) => done({ file: resolved }))
-          .catch((e) => done(e));
-      },
-    });
-    return { css: result.css, map: result.sourceMap!, dependencies: result.loadedUrls };
-  }
-  // Fallback to default transformer.
-  return await defaultTransformer(source, from);
-};
-
-run({ ...parseArgv(process.argv), transformer }).catch((e) => {
-  console.error(e);
-  process.exit(1);
-});
-```
-
-### Example: Custom resolver
-
-With the `resolver` option, you can customize the resolution algorithm for import specifier (such as `@import "specifier"`).
-
-```typescript
-#!/usr/bin/env ts-node
-
-import { run, parseArgv, createDefaultResolver, type Resolver } from 'happy-css-modules';
-import { exists } from 'fs/promises';
-import { resolve, join } from 'path';
-
-const cwd = process.cwd();
-const runnerOptions = parseArgv(process.argv);
-const { sassLoadPaths, lessIncludePaths, webpackResolveAlias } = runnerOptions;
-// Some runner options must be passed to the default resolver.
-const defaultResolver = createDefaultResolver({ cwd, sassLoadPaths, lessIncludePaths, webpackResolveAlias });
-const stylesDir = resolve(__dirname, 'src/styles');
-
-const resolver: Resolver = async (specifier, options) => {
-  // If the default resolver cannot resolve, fallback to a customized resolve algorithm.
-  const resolvedByDefaultResolver = await defaultResolver(specifier, options);
-  if (resolvedByDefaultResolver === false) {
-    // Search for files in `src/styles` directory.
-    const path = join(stylesDir, specifier);
-    if (await exists(path)) return path;
-  }
-  // Returns `false` if specifier cannot be resolved.
-  return false;
-};
-
-run({ ...runnerOptions, resolver, cwd }).catch((e) => {
-  console.error(e);
-  process.exit(1);
-});
-```
-
-### Example: Get locations for selectors exported by CSS Modules
-
-`Locator` can be used to get location for selectors exported by CSS Modules.
-
-```typescript
-import { Locator } from 'happy-css-modules';
-import { resolve } from 'path';
-import assert from 'assert';
-
-const locator = new Locator({
-  // You can customize the transformer and resolver used by the locator.
-  // transformer: createDefaultTransformer(),
-  // resolver: createDefaultResolver(),
-});
-
-// Process https://github.com/mizdra/happy-css-modules/blob/main/example/02-import/2.css
-const filePath = resolve('example/02-import/2.css'); // Convert to absolute path
-const result = await locator.load(filePath);
-
-assert.deepEqual(result, {
-  dependencies: ['/Users/mizdra/src/github.com/mizdra/happy-css-modules/example/02-import/3.css'],
-  tokens: [
-    {
-      name: 'b',
-      originalLocations: [
-        {
-          filePath: '/Users/mizdra/src/github.com/mizdra/happy-css-modules/example/02-import/3.css',
-          start: { line: 1, column: 1 },
-          end: { line: 1, column: 2 },
-        },
-      ],
-    },
-    {
-      name: 'a',
-      originalLocations: [
-        {
-          filePath: '/Users/mizdra/src/github.com/mizdra/happy-css-modules/example/02-import/2.css',
-          start: { line: 3, column: 1 },
-          end: { line: 3, column: 2 },
-        },
-      ],
-    },
-  ],
-});
-```
-
-## About the origins of this project
-
-This project was born as a PoC for [Quramy/typed-css-modules#177](https://github.com/Quramy/typed-css-modules/issues/177). That is why this project forks [`Quramy/typed-css-modules`](https://github.com/Quramy/typed-css-modules). Due to refactoring, only a small amount of code now comes from `Quramy/typed-css-modules`, but its contributions can still be found in the credits of the license.
-
-Thank you [@Quramy](https://github.com/Quramy)!
-
-## Prior art
-
-There is a lot of excellent prior art.
-
-- ✅ Supported
-- 🔶 Partially supported
-- 🛑 Not supported
-- ❓ Unknown
-
-| Repository                                                                                        | Strict type checking | Definition jumps | Sass | Less | `resolve.alias` |              How implemented              |
-| :------------------------------------------------------------------------------------------------ | :------------------: | :--------------: | :--: | :--: | :-------------: | :---------------------------------------: |
-| [Quramy/typed-css-modules](https://github.com/Quramy/typed-css-modules)                           |          ✅          |        🛑        |  🛑  |  🛑  |       🛑        |                 CLI Tool                  |
-| [skovy/typed-scss-modules](https://github.com/skovy/typed-scss-modules)                           |          ✅          |        🛑        |  ✅  |  🛑  |       🛑        |                 CLI Tool                  |
-| [qiniu/typed-less-modules](https://github.com/qiniu/typed-less-modules)                           |          ✅          |        🛑        |  🛑  |  ✅  |       🛑        |                 CLI Tool                  |
-| [mrmckeb/typescript-plugin-css-modules](https://github.com/mrmckeb/typescript-plugin-css-modules) |   🔶<sup>\*1</sup>   | 🔶<sup>\*2</sup> |  ✅  |  ✅  |       🛑        | TypeScript Language Service<sup>\*3</sup> |
-| [clinyong/vscode-css-modules](https://github.com/clinyong/vscode-css-modules)                     |          🛑          |        ✅        |  ✅  |  ✅  |       🛑        |             VSCode Extension              |
-| [Viijay-Kr/react-ts-css](https://github.com/Viijay-Kr/react-ts-css)                               |   🔶<sup>\*1</sup>   |        ✅        |  ✅  |  ✅  |       ❓        |             VSCode Extension              |
-| [mizdra/happy-css-modules](https://github.com/mizdra/happy-css-modules)                           |          ✅          |        ✅        |  ✅  |  ✅  |       ✅        |        CLI Tool + Declaration Map         |
-
-- \*1: Warnings are displayed in the editor, but not at compile time.
-- \*2: Not supported for `.less` definition jumps.
-- \*3: The TypeScript language service can display warnings in the editor, but not at compile time. It is also complicated to set up.
-
-Another known tool for generating `.css.d.ts` is [wix/stylable](https://github.com/wix/stylable) , which does not use CSS Modules.