feat(core, ts-plugin): support composes property with from specifier (#409)

Class names referenced via `composes: foo from './other.module.css';`
are now parsed as external token references, enabling Go to Definition,
Find All References, and Rename across files. The check phase reports
unresolvable specifiers and tokens not exported by the referenced file.

`TokenReference` is now a discriminated union of local and external
references so that each phase can handle them separately.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: mizdra

.changeset/composes-external-references.md

@@ -0,0 +1,13 @@
+---
+'@css-modules-kit/core': minor
+'@css-modules-kit/ts-plugin': minor
+---
+
+feat(core, ts-plugin): support `composes: <name> from '<specifier>'`
+
+Class names referenced via `composes: foo from './other.module.css';` are now linked to the `.foo {...}` declaration in the referenced file. Go to Definition jumps from the reference to the declaration, Find All References lists reference sites across files, and Rename updates the declaration and every reference together.
+
+Two diagnostics are also emitted in the check phase:
+
+- `Cannot import module '<specifier>'` when the specifier cannot be resolved.
+- `Module '<specifier>' has no exported token '<name>'.` when the referenced file does not export the token.

AGENTS.md

@@ -87,7 +87,9 @@ function myFunction() {
 ## Glossary
 
 - **Token**: A generic term for things exported by CSS Modules, such as class names, `@value` definitions, and `@keyframes` names.
-- **Token reference**: A usage of a token elsewhere in the CSS. Currently produced for `animation-name: <name>`. The referenced token may be defined in the same file (e.g. `@keyframes`) or imported via `@import` / `@value ... from`.
+- **Token reference**: A usage of a token elsewhere in the CSS. Currently produced for `animation-name: <name>` and `composes: <name>`. There are two kinds:
+  - **Local token reference**: References a token available in the current file. The token may be defined in the same file (e.g. `@keyframes`) or imported via `@import` / `@value ... from`.
+  - **External token reference**: References tokens exported by another file, like `composes: <name> ... from '<specifier>'`. One reference corresponds to one `from` clause and holds an entry per referenced token.
 - **Diagnostic**: An object representing errors or warnings
 - **Parse phase**: The phase that parses CSS Modules files and extracts token information
 - **Check phase**: The phase that validates CSS Modules files

docs/ts-plugin-internals.ja.md

@@ -302,9 +302,9 @@ CSS Modules Kit ではこの問題を、
 
 参考: [mizdra/volar-single-quote-span-problem](https://github.com/mizdra/volar-single-quote-span-problem)
 
-### Token References (`animation-name`) のサポート
+### Local Token References (`animation-name`, `composes`) のサポート
 
-CSS では `@keyframes foo {...}` で定義したアニメーション名を `animation-name: foo;` で参照できます。CSS Modules Kit はこの参照を Volar.js の mapping を介して定義側と結びつけ、Go to Definition / Find All References / Rename を一貫して動作させます。
+CSS では `@keyframes foo {...}` で定義したアニメーション名を `animation-name: foo;` で参照できます。また CSS Modules では `composes: foo;` で同一ファイル内の別のクラス名を参照できます。CSS Modules Kit はこうした現在のファイルで利用可能なトークンへの参照 (local token reference) を Volar.js の mapping を介して定義側と結びつけ、Go to Definition / Find All References / Rename を一貫して動作させます。
 
 仕組みとしては、生成する `.d.ts` の末尾に「参照の式」を埋め込みます。default export の場合は `styles['<name>'];` という bracket access の式文として、named export の場合は自モジュールへの self-import (`declare const __self: typeof import('./<self-basename>');`) を 1 度生成した上で `__self['<name>'];` という bracket access として吐きます。各参照式のクオート内側部分には CSS 側の参照位置の mapping を張ります。
 
@@ -340,3 +340,35 @@ export { _token_1 as 'a_2' };
 declare const __self: typeof import('./a.module.css');
 __self['a_1'];
 ```
+
+### External Token References (`composes: ... from '<specifier>'`) のサポート
+
+CSS Modules では `composes: b_1 b_2 from './b.module.css';` のように、`from` 句で指定した別ファイルのトークンを参照できます。CSS Modules Kit はこうした別ファイルがエクスポートするトークンへの参照 (external token reference) も、local token reference と同じく参照式と mapping によって定義側と結びつけます。
+
+例えば、次のような CSS モジュールがあるとします:
+
+`src/a.module.css`:
+
+```css
+.a_1 { composes: b_1 b_2 from './b.module.css'; }
+```
+
+default export の場合、次のような型定義が生成されます:
+
+```ts
+declare const styles = {
+  'a_1': '' as string,
+} as const;
+(await import('./b.module.css')).default['b_1'];
+(await import('./b.module.css')).default['b_2'];
+export default styles;
+```
+
+named export の場合、次のような型定義が生成されます:
+
+```ts
+var _token_0: string;
+export { _token_0 as 'a_1' };
+(await import('./b.module.css'))['b_1'];
+(await import('./b.module.css'))['b_2'];
+```

docs/ts-plugin-internals.md

@@ -305,9 +305,9 @@ With this, `getDefinitionAtPosition`'s `{ start: 27, length: 5 }` also matches t
 
 Reference: [mizdra/volar-single-quote-span-problem](https://github.com/mizdra/volar-single-quote-span-problem)
 
-### Token References (`animation-name`) Support
+### Local Token References (`animation-name`, `composes`) Support
 
-In CSS, an animation name defined with `@keyframes foo {...}` can be referenced by `animation-name: foo;`. CSS Modules Kit links such references to their definitions via Volar.js mappings, making Go to Definition / Find All References / Rename work consistently.
+In CSS, an animation name defined with `@keyframes foo {...}` can be referenced by `animation-name: foo;`. In CSS Modules, `composes: foo;` can also reference another class name in the same file. CSS Modules Kit links such references to tokens available in the current file (local token references) to their definitions via Volar.js mappings, making Go to Definition / Find All References / Rename work consistently.
 
 The mechanism is to embed "reference expressions" at the end of the generated `.d.ts`. For default export, it is emitted as a bracket access expression statement like `styles['<name>'];`. For named export, after emitting a self-import (`declare const __self: typeof import('./<self-basename>');`) once, it is emitted as a bracket access like `__self['<name>'];`. A mapping is attached to the inside-of-quotes part of each reference expression, pointing to the reference position in the CSS.
 
@@ -343,3 +343,35 @@ export { _token_1 as 'a_2' };
 declare const __self: typeof import('./a.module.css');
 __self['a_1'];
 ```
+
+### External Token References (`composes: ... from '<specifier>'`) Support
+
+In CSS Modules, tokens of another file can be referenced with a `from` clause, like `composes: b_1 b_2 from './b.module.css';`. CSS Modules Kit links such references to tokens exported by another file (external token references) to their definitions via reference expressions and mappings, just like local token references.
+
+For example, suppose we have the following CSS module:
+
+`src/a.module.css`:
+
+```css
+.a_1 { composes: b_1 b_2 from './b.module.css'; }
+```
+
+For default export, the following type definition is generated:
+
+```ts
+declare const styles = {
+  'a_1': '' as string,
+} as const;
+(await import('./b.module.css')).default['b_1'];
+(await import('./b.module.css')).default['b_2'];
+export default styles;
+```
+
+For named export, the following type definition is generated:
+
+```ts
+var _token_0: string;
+export { _token_0 as 'a_1' };
+(await import('./b.module.css'))['b_1'];
+(await import('./b.module.css'))['b_2'];
+```

examples/1-basic/src/a.module.css

@@ -7,7 +7,7 @@
   100% { transform: translateY(-100%); }
 }
 .a_5 {
-  composes: a_1;
+  composes: a_1, b_1 from './b.module.css';
   animation-name: a_4;
 }
 

packages/core/src/checker.test.ts

@@ -300,4 +300,59 @@ describe('checkCSSModule', () => {
     const diagnostics = check(readAndParseCSSModule(iff.paths['a.module.css'])!);
     expect(diagnostics).toEqual([]);
   });
+  test('report diagnostics for external references with unresolvable modules', async () => {
+    // The diagnostic is reported once per `from` clause, even if it has multiple entries.
+    const iff = await createIFF({
+      'a.module.css': `.a_1 { composes: b_1 b_2 from './b.module.css'; }`,
+    });
+    const check = prepareChecker();
+    const diagnostics = check(readAndParseCSSModule(iff.paths['a.module.css'])!);
+    expect(formatDiagnostics(diagnostics, iff.rootDir)).toMatchInlineSnapshot(`
+      [
+        {
+          "category": "error",
+          "fileName": "<rootDir>/a.module.css",
+          "length": 14,
+          "start": {
+            "column": 32,
+            "line": 1,
+          },
+          "text": "Cannot import module './b.module.css'",
+        },
+      ]
+    `);
+  });
+  test('report diagnostics for external references to non-exported tokens', async () => {
+    const iff = await createIFF({
+      'a.module.css': `.a_1 { composes: b_1 b_2 from './b.module.css'; }`,
+      'b.module.css': `.b_1 { color: red; }`,
+    });
+    const check = prepareChecker();
+    const diagnostics = check(readAndParseCSSModule(iff.paths['a.module.css'])!);
+    expect(formatDiagnostics(diagnostics, iff.rootDir)).toMatchInlineSnapshot(`
+      [
+        {
+          "category": "error",
+          "fileName": "<rootDir>/a.module.css",
+          "length": 3,
+          "start": {
+            "column": 22,
+            "line": 1,
+          },
+          "text": "Module './b.module.css' has no exported token 'b_2'.",
+        },
+      ]
+    `);
+  });
+  test('do not report diagnostics for external references for unmatched modules', async () => {
+    const iff = await createIFF({
+      'a.module.css': `.a_1 { composes: unmatched_1 from './unmatched.module.css'; }`,
+      'unmatched.module.css': '.unmatched_1 { color: red; }',
+    });
+    const check = prepareChecker({
+      matchesPattern: (path) => path.endsWith('.module.css') && !path.endsWith('unmatched.module.css'),
+    });
+    const diagnostics = check(readAndParseCSSModule(iff.paths['a.module.css'])!);
+    expect(diagnostics).toEqual([]);
+  });
 });

packages/core/src/checker.ts

@@ -4,12 +4,9 @@ import type {
   Diagnostic,
   ExportRecord,
   Location,
+  LocalTokenReference,
   MatchesPattern,
-  NamedTokenImporter,
-  NamedTokenImporterEntry,
   Resolver,
-  TokenImporter,
-  TokenReference,
 } from './type.js';
 import { isURLSpecifier, type TokenNameViolation, validateTokenName } from './util.js';
 
@@ -37,7 +34,7 @@ export function checkCSSModule(cssModule: CSSModule, args: CheckerArgs): Diagnos
     if (isURLSpecifier(tokenImporter.from)) continue;
     const from = args.resolver(tokenImporter.from, { request: cssModule.fileName });
     if (!from) {
-      diagnostics.push(createCannotImportModuleDiagnostic(cssModule, tokenImporter));
+      diagnostics.push(createCannotImportModuleDiagnostic(cssModule, tokenImporter.from, tokenImporter.fromLoc));
       continue;
     }
     if (!args.matchesPattern(from)) continue;
@@ -48,7 +45,9 @@ export function checkCSSModule(cssModule: CSSModule, args: CheckerArgs): Diagnos
       const exportRecord = args.getExportRecord(imported);
       for (const entry of tokenImporter.entries) {
         if (!exportRecord.allTokens.includes(entry.name)) {
-          diagnostics.push(createModuleHasNoExportedTokenDiagnostic(cssModule, tokenImporter, entry));
+          diagnostics.push(
+            createModuleHasNoExportedTokenDiagnostic(cssModule, tokenImporter.from, entry.name, entry.loc),
+          );
         }
         const nameViolation = validateTokenName(entry.name, { namedExports: config.namedExports });
         if (nameViolation) {
@@ -66,8 +65,26 @@ export function checkCSSModule(cssModule: CSSModule, args: CheckerArgs): Diagnos
 
   const exportRecord = args.getExportRecord(cssModule);
   for (const reference of cssModule.tokenReferences) {
-    if (!exportRecord.allTokens.includes(reference.name)) {
-      diagnostics.push(createTokenNotFoundDiagnostic(cssModule, reference));
+    if (reference.type === 'local') {
+      if (!exportRecord.allTokens.includes(reference.name)) {
+        diagnostics.push(createTokenNotFoundDiagnostic(cssModule, reference));
+      }
+      continue;
+    }
+    // Unlike `@import`, URL specifiers are not skipped because css-loader fails to resolve them in `composes`.
+    const from = args.resolver(reference.from, { request: cssModule.fileName });
+    if (!from) {
+      diagnostics.push(createCannotImportModuleDiagnostic(cssModule, reference.from, reference.fromLoc));
+      continue;
+    }
+    if (!args.matchesPattern(from)) continue;
+    const imported = args.getCSSModule(from);
+    if (!imported) throw new Error('unreachable: `imported` is undefined');
+    const importedExportRecord = args.getExportRecord(imported);
+    for (const entry of reference.entries) {
+      if (!importedExportRecord.allTokens.includes(entry.name)) {
+        diagnostics.push(createModuleHasNoExportedTokenDiagnostic(cssModule, reference.from, entry.name, entry.loc));
+      }
     }
   }
   return diagnostics;
@@ -97,31 +114,32 @@ function createTokenNameDiagnostic(cssModule: CSSModule, loc: Location, violatio
   };
 }
 
-function createCannotImportModuleDiagnostic(cssModule: CSSModule, tokenImporter: TokenImporter): Diagnostic {
+function createCannotImportModuleDiagnostic(cssModule: CSSModule, from: string, fromLoc: Location): Diagnostic {
   return {
-    text: `Cannot import module '${tokenImporter.from}'`,
+    text: `Cannot import module '${from}'`,
     category: 'error',
     file: { fileName: cssModule.fileName, text: cssModule.text },
-    start: { line: tokenImporter.fromLoc.start.line, column: tokenImporter.fromLoc.start.column },
-    length: tokenImporter.fromLoc.end.offset - tokenImporter.fromLoc.start.offset,
+    start: { line: fromLoc.start.line, column: fromLoc.start.column },
+    length: fromLoc.end.offset - fromLoc.start.offset,
   };
 }
 
 function createModuleHasNoExportedTokenDiagnostic(
   cssModule: CSSModule,
-  tokenImporter: NamedTokenImporter,
-  entry: NamedTokenImporterEntry,
+  from: string,
+  name: string,
+  loc: Location,
 ): Diagnostic {
   return {
-    text: `Module '${tokenImporter.from}' has no exported token '${entry.name}'.`,
+    text: `Module '${from}' has no exported token '${name}'.`,
     category: 'error',
     file: { fileName: cssModule.fileName, text: cssModule.text },
-    start: { line: entry.loc.start.line, column: entry.loc.start.column },
-    length: entry.loc.end.offset - entry.loc.start.offset,
+    start: { line: loc.start.line, column: loc.start.column },
+    length: loc.end.offset - loc.start.offset,
   };
 }
 
-function createTokenNotFoundDiagnostic(cssModule: CSSModule, reference: TokenReference): Diagnostic {
+function createTokenNotFoundDiagnostic(cssModule: CSSModule, reference: LocalTokenReference): Diagnostic {
   return {
     text: `Cannot find token '${reference.name}'.`,
     category: 'error',

packages/core/src/dts-generator.test.ts

@@ -370,6 +370,90 @@ describe('emits token reference statements when forTsPlugin is true', () => {
   });
 });
 
+describe('emits external token reference statements when forTsPlugin is true', () => {
+  // `b_1` and `b_2` share one `from` clause. The `from` clause of `b_3` has the same specifier
+  // as the first one, but is a separate clause.
+  const source = `.a_1 { composes: b_1 b_2 from './b.module.css', b_3 from './b.module.css'; }`;
+  test('default export', async () => {
+    expect(await run(source, { ...defaultExportOptions, forTsPlugin: true })).toMatchInlineSnapshot(`
+      "=== source ===
+      .a_1 { composes: b_1 b_2 from './b.module.css', b_3 from './b.module.css'; }
+                                                               ^^^^^^^^^^^^^^^^ mapping[4]
+                                                      ^^^ mapping[5]
+                                    ^^^^^^^^^^^^^^^^ mapping[1]
+                           ^^^ mapping[3]
+                       ^^^ mapping[2]
+       ^^^ mapping[0]
+
+      === generated ===
+      // @ts-nocheck
+      declare const styles = {
+        'a_1': '' as string,
+         ^^^ mapping[0]
+      } as const;
+      (await import('./b.module.css')).default['b_1'];
+                                                ^^^ mapping[2]
+                    ^^^^^^^^^^^^^^^^ mapping[1]
+      (await import('./b.module.css')).default['b_2'];
+                                                ^^^ mapping[3]
+      (await import('./b.module.css')).default['b_3'];
+                                                ^^^ mapping[5]
+                    ^^^^^^^^^^^^^^^^ mapping[4]
+      export default styles;
+      "
+    `);
+  });
+  test('named export', async () => {
+    expect(await run(source, { ...namedExportOptions, forTsPlugin: true })).toMatchInlineSnapshot(`
+      "=== source ===
+      .a_1 { composes: b_1 b_2 from './b.module.css', b_3 from './b.module.css'; }
+                                                               ^^^^^^^^^^^^^^^^ mapping[4]
+                                                      ^^^ mapping[5]
+                                    ^^^^^^^^^^^^^^^^ mapping[1]
+                           ^^^ mapping[3]
+                       ^^^ mapping[2]
+       ^^^ mapping[0]
+
+      === generated ===
+      // @ts-nocheck
+      var _token_0: string;
+          ^^^^^^^^ mapping[0]
+      export { _token_0 as 'a_1' };
+                           ^^^^^ linkedCodeMapping[0]
+               ^^^^^^^^ linkedCodeMapping[0]
+      (await import('./b.module.css'))['b_1'];
+                                        ^^^ mapping[2]
+                    ^^^^^^^^^^^^^^^^ mapping[1]
+      (await import('./b.module.css'))['b_2'];
+                                        ^^^ mapping[3]
+      (await import('./b.module.css'))['b_3'];
+                                        ^^^ mapping[5]
+                    ^^^^^^^^^^^^^^^^ mapping[4]
+      declare const styles: {};
+      export default styles;
+      "
+    `);
+  });
+});
+
+test('omits external token reference statements whose specifier is a URL', async () => {
+  const source = `.a_1 { composes: b_1 from 'https://example.com/b.module.css'; }`;
+  expect(await run(source, { ...defaultExportOptions, forTsPlugin: true })).toMatchInlineSnapshot(`
+    "=== source ===
+    .a_1 { composes: b_1 from 'https://example.com/b.module.css'; }
+     ^^^ mapping[0]
+
+    === generated ===
+    // @ts-nocheck
+    declare const styles = {
+      'a_1': '' as string,
+       ^^^ mapping[0]
+    } as const;
+    export default styles;
+    "
+  `);
+});
+
 describe('omits importers whose specifier is a URL', () => {
   const source = dedent`
     @import 'https://example.com/b.module.css';