happy-css-modules 3.0.1 → 3.1.1

package/src/locator/index.ts

@@ -4,7 +4,15 @@ 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, collectNodes } from './postcss.js';
+import {
+  getOriginalLocationOfClassSelector,
+  getOriginalLocationOfAtValue,
+  generateLocalTokenNames,
+  parseAtImport,
+  type Location,
+  collectNodes,
+  parseAtValue,
+} from './postcss.js';
 
 export { collectNodes, type Location } from './postcss.js';
 
@@ -20,8 +28,10 @@ function isIgnoredSpecifier(specifier: string): boolean {
 export type Token = {
   /** The token name. */
   name: string;
-  /** The original locations of the token in the source file. */
-  originalLocations: Location[];
+  /** The name of the imported token. */
+  importedName?: string;
+  /** The original location of the token in the source file. */
+  originalLocation: Location;
 };
 
 type CacheEntry = {
@@ -37,22 +47,6 @@ export type LoadResult = {
   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 LocatorOptions = {
   /** The function to transform source code. */
   transformer?: Transformer | undefined;
@@ -158,7 +152,7 @@ export class Locator {
 
     const tokens: Token[] = [];
 
-    const { atImports, classSelectors } = collectNodes(ast);
+    const { atImports, atValues, classSelectors } = collectNodes(ast);
 
     // Load imported sheets recursively.
     for (const atImport of atImports) {
@@ -180,17 +174,51 @@ export class Locator {
       // 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);
+      const originalLocation = getOriginalLocationOfClassSelector(rule, classSelector);
 
       tokens.push({
         name: classSelector.value,
-        originalLocations: [originalLocation],
+        originalLocation,
       });
     }
 
+    for (const atValue of atValues) {
+      const parsedAtValue = parseAtValue(atValue);
+
+      if (parsedAtValue.type === 'valueDeclaration') {
+        tokens.push({
+          name: parsedAtValue.tokenName,
+          originalLocation: getOriginalLocationOfAtValue(atValue, parsedAtValue),
+        });
+      } else if (parsedAtValue.type === 'valueImportDeclaration') {
+        if (isIgnoredSpecifier(parsedAtValue.from)) continue;
+        // eslint-disable-next-line no-await-in-loop
+        const from = await this.resolver(parsedAtValue.from, { request: filePath });
+        // eslint-disable-next-line no-await-in-loop
+        const result = await this._load(from);
+        dependencies.push(from, ...result.dependencies);
+        for (const token of result.tokens) {
+          const matchedImport = parsedAtValue.imports.find((i) => i.importedTokenName === token.name);
+          if (!matchedImport) continue;
+          if (matchedImport.localTokenName === matchedImport.importedTokenName) {
+            tokens.push({
+              name: matchedImport.localTokenName,
+              originalLocation: token.originalLocation,
+            });
+          } else {
+            tokens.push({
+              name: matchedImport.localTokenName,
+              importedName: matchedImport.importedTokenName,
+              originalLocation: token.originalLocation,
+            });
+          }
+        }
+      }
+    }
+
     const result: LoadResult = {
       dependencies: unique(dependencies).filter((dep) => dep !== filePath),
-      tokens: normalizeTokens(tokens),
+      tokens: uniqueBy(tokens, (token) => JSON.stringify(token)),
     };
     this.cache.set(filePath, { mtime, result });
     return result;

package/src/locator/postcss.test.ts

@@ -1,6 +1,20 @@
 import dedent from 'dedent';
-import { createRoot, createClassSelectors, createAtImports, createFixtures } from '../test-util/util.js';
-import { generateLocalTokenNames, getOriginalLocation, parseAtImport, collectNodes } from './postcss.js';
+import type { AtRule } from 'postcss';
+import {
+  createRoot,
+  createClassSelectors,
+  createAtImports,
+  createFixtures,
+  createAtValues,
+} from '../test-util/util.js';
+import {
+  generateLocalTokenNames,
+  getOriginalLocationOfClassSelector,
+  parseAtImport,
+  parseAtValue,
+  collectNodes,
+  getOriginalLocationOfAtValue,
+} from './postcss.js';
 
 describe('generateLocalTokenNames', () => {
   test('basic', async () => {
@@ -27,9 +41,11 @@ describe('generateLocalTokenNames', () => {
           .local_class_name_3 {}
         }
         :local(.local_class_name_4) {}
+        @value value: #BF4040;
         `),
       ),
     ).toStrictEqual([
+      'value',
       'basic',
       'cascading',
       'pseudo_class_1',
@@ -63,14 +79,18 @@ describe('generateLocalTokenNames', () => {
     ).toStrictEqual([]);
   });
   test('does not track styles imported by @value in other file because it is not a local token', async () => {
-    createFixtures({});
+    createFixtures({
+      '/test/1.css': dedent`
+      .a {}
+      `,
+    });
     expect(
       await generateLocalTokenNames(
         createRoot(`
-        @value something from "/test/1.css";
+        @value a from "/test/1.css";
         `),
       ),
-    ).toStrictEqual([]);
+    ).toStrictEqual(['a']);
   });
   test('does not track styles imported by composes in other file because it is not a local token', async () => {
     createFixtures({
@@ -90,14 +110,14 @@ describe('generateLocalTokenNames', () => {
   });
 });
 
-describe('getOriginalLocation', () => {
+describe('getOriginalLocationOfClassSelector', () => {
   test('basic', () => {
     const [basic] = createClassSelectors(
       createRoot(dedent`
       .basic {}
       `),
     );
-    expect(getOriginalLocation(basic!.rule, basic!.classSelector)).toMatchInlineSnapshot(
+    expect(getOriginalLocationOfClassSelector(basic!.rule, basic!.classSelector)).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 1, column: 1 }, end: { line: 1, column: 6 } }`,
     );
   });
@@ -109,10 +129,10 @@ describe('getOriginalLocation', () => {
       .cascading {}
       `),
     );
-    expect(getOriginalLocation(cascading_1!.rule, cascading_1!.classSelector)).toMatchInlineSnapshot(
+    expect(getOriginalLocationOfClassSelector(cascading_1!.rule, cascading_1!.classSelector)).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 1, column: 1 }, end: { line: 1, column: 10 } }`,
     );
-    expect(getOriginalLocation(cascading_2!.rule, cascading_2!.classSelector)).toMatchInlineSnapshot(
+    expect(getOriginalLocationOfClassSelector(cascading_2!.rule, cascading_2!.classSelector)).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 2, column: 1 }, end: { line: 2, column: 10 } }`,
     );
   });
@@ -125,13 +145,19 @@ describe('getOriginalLocation', () => {
       :not(.pseudo_class_3) {}
       `),
     );
-    expect(getOriginalLocation(pseudo_class_1!.rule, pseudo_class_1!.classSelector)).toMatchInlineSnapshot(
+    expect(
+      getOriginalLocationOfClassSelector(pseudo_class_1!.rule, pseudo_class_1!.classSelector),
+    ).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 1, column: 1 }, end: { line: 1, column: 15 } }`,
     );
-    expect(getOriginalLocation(pseudo_class_2!.rule, pseudo_class_2!.classSelector)).toMatchInlineSnapshot(
+    expect(
+      getOriginalLocationOfClassSelector(pseudo_class_2!.rule, pseudo_class_2!.classSelector),
+    ).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 2, column: 1 }, end: { line: 2, column: 15 } }`,
     );
-    expect(getOriginalLocation(pseudo_class_3!.rule, pseudo_class_3!.classSelector)).toMatchInlineSnapshot(
+    expect(
+      getOriginalLocationOfClassSelector(pseudo_class_3!.rule, pseudo_class_3!.classSelector),
+    ).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 3, column: 6 }, end: { line: 3, column: 20 } }`,
     );
   });
@@ -142,10 +168,14 @@ describe('getOriginalLocation', () => {
       .multiple_selector_1.multiple_selector_2 {}
       `),
     );
-    expect(getOriginalLocation(multiple_selector_1!.rule, multiple_selector_1!.classSelector)).toMatchInlineSnapshot(
+    expect(
+      getOriginalLocationOfClassSelector(multiple_selector_1!.rule, multiple_selector_1!.classSelector),
+    ).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 1, column: 1 }, end: { line: 1, column: 20 } }`,
     );
-    expect(getOriginalLocation(multiple_selector_2!.rule, multiple_selector_2!.classSelector)).toMatchInlineSnapshot(
+    expect(
+      getOriginalLocationOfClassSelector(multiple_selector_2!.rule, multiple_selector_2!.classSelector),
+    ).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 1, column: 21 }, end: { line: 1, column: 40 } }`,
     );
   });
@@ -157,10 +187,10 @@ describe('getOriginalLocation', () => {
       .combinator_1 + .combinator_2 {}
       `),
     );
-    expect(getOriginalLocation(combinator_1!.rule, combinator_1!.classSelector)).toMatchInlineSnapshot(
+    expect(getOriginalLocationOfClassSelector(combinator_1!.rule, combinator_1!.classSelector)).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 1, column: 1 }, end: { line: 1, column: 13 } }`,
     );
-    expect(getOriginalLocation(combinator_2!.rule, combinator_2!.classSelector)).toMatchInlineSnapshot(
+    expect(getOriginalLocationOfClassSelector(combinator_2!.rule, combinator_2!.classSelector)).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 1, column: 17 }, end: { line: 1, column: 29 } }`,
     );
   });
@@ -175,7 +205,7 @@ describe('getOriginalLocation', () => {
       }
       `),
     );
-    expect(getOriginalLocation(at_rule!.rule, at_rule!.classSelector)).toMatchInlineSnapshot(
+    expect(getOriginalLocationOfClassSelector(at_rule!.rule, at_rule!.classSelector)).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 3, column: 5 }, end: { line: 3, column: 12 } }`,
     );
   });
@@ -186,10 +216,14 @@ describe('getOriginalLocation', () => {
       .selector_list_1, .selector_list_2 {}
       `),
     );
-    expect(getOriginalLocation(selector_list_1!.rule, selector_list_1!.classSelector)).toMatchInlineSnapshot(
+    expect(
+      getOriginalLocationOfClassSelector(selector_list_1!.rule, selector_list_1!.classSelector),
+    ).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 1, column: 1 }, end: { line: 1, column: 16 } }`,
     );
-    expect(getOriginalLocation(selector_list_2!.rule, selector_list_2!.classSelector)).toMatchInlineSnapshot(
+    expect(
+      getOriginalLocationOfClassSelector(selector_list_2!.rule, selector_list_2!.classSelector),
+    ).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 1, column: 19 }, end: { line: 1, column: 34 } }`,
     );
   });
@@ -205,16 +239,24 @@ describe('getOriginalLocation', () => {
       :local(.local_class_name_4) {}
       `),
     );
-    expect(getOriginalLocation(local_class_name_1!.rule, local_class_name_1!.classSelector)).toMatchInlineSnapshot(
+    expect(
+      getOriginalLocationOfClassSelector(local_class_name_1!.rule, local_class_name_1!.classSelector),
+    ).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 1, column: 8 }, end: { line: 1, column: 26 } }`,
     );
-    expect(getOriginalLocation(local_class_name_2!.rule, local_class_name_2!.classSelector)).toMatchInlineSnapshot(
+    expect(
+      getOriginalLocationOfClassSelector(local_class_name_2!.rule, local_class_name_2!.classSelector),
+    ).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 3, column: 3 }, end: { line: 3, column: 21 } }`,
     );
-    expect(getOriginalLocation(local_class_name_3!.rule, local_class_name_3!.classSelector)).toMatchInlineSnapshot(
+    expect(
+      getOriginalLocationOfClassSelector(local_class_name_3!.rule, local_class_name_3!.classSelector),
+    ).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 4, column: 3 }, end: { line: 4, column: 21 } }`,
     );
-    expect(getOriginalLocation(local_class_name_4!.rule, local_class_name_4!.classSelector)).toMatchInlineSnapshot(
+    expect(
+      getOriginalLocationOfClassSelector(local_class_name_4!.rule, local_class_name_4!.classSelector),
+    ).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 6, column: 8 }, end: { line: 6, column: 26 } }`,
     );
   });
@@ -227,19 +269,44 @@ describe('getOriginalLocation', () => {
         + .with_newline_3, {}
       `),
     );
-    expect(getOriginalLocation(with_newline_1!.rule, with_newline_1!.classSelector)).toMatchInlineSnapshot(
+    expect(
+      getOriginalLocationOfClassSelector(with_newline_1!.rule, with_newline_1!.classSelector),
+    ).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 1, column: 1 }, end: { line: 1, column: 15 } }`,
     );
-    expect(getOriginalLocation(with_newline_2!.rule, with_newline_2!.classSelector)).toMatchInlineSnapshot(
+    expect(
+      getOriginalLocationOfClassSelector(with_newline_2!.rule, with_newline_2!.classSelector),
+    ).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 2, column: 1 }, end: { line: 2, column: 15 } }`,
     );
 
-    expect(getOriginalLocation(with_newline_3!.rule, with_newline_3!.classSelector)).toMatchInlineSnapshot(
+    expect(
+      getOriginalLocationOfClassSelector(with_newline_3!.rule, with_newline_3!.classSelector),
+    ).toMatchInlineSnapshot(
       `{ filePath: "/test/test.css", start: { line: 3, column: 5 }, end: { line: 3, column: 19 } }`,
     );
   });
 });
 
+test('getOriginalLocationOfAtValue', () => {
+  function tryGetOriginalLocationOfAtValue(atValue: AtRule) {
+    const parsed = parseAtValue(atValue);
+    if (parsed.type === 'valueDeclaration') {
+      return getOriginalLocationOfAtValue(atValue, parsed);
+    } else {
+      throw new Error('Unexpected type');
+    }
+  }
+  const [basic] = createAtValues(
+    createRoot(dedent`
+    @value basic: #000;
+    `),
+  );
+  expect(tryGetOriginalLocationOfAtValue(basic!)).toMatchInlineSnapshot(
+    `{ filePath: "/test/test.css", start: { line: 1, column: 8 }, end: { line: 1, column: 13 } }`,
+  );
+});
+
 test('collectNodes', () => {
   const ast = createRoot(dedent`
     @import;
@@ -277,3 +344,45 @@ test('parseAtImport', () => {
   expect(parseAtImport(atImports[3]!)).toBe('test.css');
   expect(parseAtImport(atImports[4]!)).toBe('test.css');
 });
+
+test('parseAtValue', () => {
+  const atValues = createAtValues(
+    createRoot(dedent`
+    @value basic: #000;
+    @value withoutColon #000;
+    @value empty:;
+    @value comment:/* comment */;
+    @value complex: (max-width: 599px);
+    @value import from "test.css";
+    @value import1, import2 from "test.css";
+    @value import as alias from "test.css";
+    /*
+     * NOTE: happy-css-modules intentionally does not support module specifier as variable.
+     * e.g. \`@value d, e from moduleName;\`
+     */
+    `),
+  );
+  expect(parseAtValue(atValues[0]!)).toStrictEqual({ type: 'valueDeclaration', tokenName: 'basic' });
+  expect(parseAtValue(atValues[1]!)).toStrictEqual({ type: 'valueDeclaration', tokenName: 'withoutColon' });
+  expect(parseAtValue(atValues[2]!)).toStrictEqual({ type: 'valueDeclaration', tokenName: 'empty' });
+  expect(parseAtValue(atValues[3]!)).toStrictEqual({ type: 'valueDeclaration', tokenName: 'comment' });
+  expect(parseAtValue(atValues[4]!)).toStrictEqual({ type: 'valueDeclaration', tokenName: 'complex' });
+  expect(parseAtValue(atValues[5]!)).toStrictEqual({
+    type: 'valueImportDeclaration',
+    imports: [{ importedTokenName: 'import', localTokenName: 'import' }],
+    from: 'test.css',
+  });
+  expect(parseAtValue(atValues[6]!)).toStrictEqual({
+    type: 'valueImportDeclaration',
+    imports: [
+      { importedTokenName: 'import1', localTokenName: 'import1' },
+      { importedTokenName: 'import2', localTokenName: 'import2' },
+    ],
+    from: 'test.css',
+  });
+  expect(parseAtValue(atValues[7]!)).toStrictEqual({
+    type: 'valueImportDeclaration',
+    imports: [{ importedTokenName: 'import', localTokenName: 'alias' }],
+    from: 'test.css',
+  });
+});

package/src/locator/postcss.ts

@@ -1,4 +1,4 @@
-import postcss, { type Rule, type AtRule, type Root, type Node, type Declaration, type Plugin } from 'postcss';
+import postcss, { type Rule, type AtRule, type Root, type Node } from 'postcss';
 import modules from 'postcss-modules';
 import selectorParser, { type ClassName } from 'postcss-selector-parser';
 import valueParser from 'postcss-value-parser';
@@ -26,40 +26,27 @@ export type Location =
       end: undefined;
     };
 
-function removeDependenciesPlugin(): Plugin {
-  return {
-    postcssPlugin: 'remove-dependencies',
-    // eslint-disable-next-line @typescript-eslint/naming-convention
-    AtRule(atRule) {
-      if (isAtImportNode(atRule) || isAtValueNode(atRule)) {
-        atRule.remove();
-      }
-    },
-    // eslint-disable-next-line @typescript-eslint/naming-convention
-    Declaration(declaration) {
-      if (isComposesDeclaration(declaration)) {
-        declaration.remove();
-      }
-    },
-  };
-}
-
 /**
  * Traverses a local token from the AST and returns its name.
  * @param ast The AST to traverse.
  * @returns The name of the local token.
  */
 export async function generateLocalTokenNames(ast: Root): Promise<string[]> {
+  class EmptyLoader {
+    async fetch(_file: string, _relativeTo: string, _depTrace: string): Promise<{ [key: string]: string }> {
+      // Return an empty object because we do not want to load external tokens in `generateLocalTokenNames`.
+      return Promise.resolve({});
+    }
+  }
   return new Promise((resolve, reject) => {
     postcss
       .default()
-      // postcss-modules collects tokens (i.e., includes external tokens) by following
-      // the dependencies specified in the @import.
-      // However, we do not want `generateLocalTokenNames` to return external tokens.
-      // So we remove the @import beforehand.
-      .use(removeDependenciesPlugin())
       .use(
         modules({
+          // `@import`, `@value`, and `composes` can read tokens from external files.
+          // However, we want to collect only local tokens. So we will fake that
+          // an empty token is exported from the external file.
+          Loader: EmptyLoader,
           getJSON: (_cssFileName, json) => {
             resolve(Object.keys(json));
           },
@@ -72,12 +59,12 @@ export async function generateLocalTokenNames(ast: Root): Promise<string[]> {
 }
 
 /**
- * Get the token's location on the source file.
+ * Get the original location of the class selector.
  * @param rule The rule node that contains the token.
  * @param classSelector The class selector node that contains the token.
- * @returns The token's location on the source file.
+ * @returns The original location of the class selector.
  */
-export function getOriginalLocation(rule: Rule, classSelector: ClassName): Location {
+export function getOriginalLocationOfClassSelector(rule: Rule, classSelector: ClassName): Location {
   // The node derived from `postcss.parse` always has `source` property. Therefore, this line is unreachable.
   if (rule.source === undefined || classSelector.source === undefined) throw new Error('Node#source is undefined');
   // The node derived from `postcss.parse` always has `start` and `end` property. Therefore, this line is unreachable.
@@ -127,6 +114,32 @@ export function getOriginalLocation(rule: Rule, classSelector: ClassName): Locat
   };
 }
 
+/**
+ * Get the original location of `@value`.
+ * @param atValue The `@value` rule.
+ * @returns The location of the `@value` rule.
+ */
+export function getOriginalLocationOfAtValue(atValue: AtRule, valueDeclaration: ValueDeclaration): Location {
+  // The node derived from `postcss.parse` always has `source` property. Therefore, this line is unreachable.
+  if (atValue.source === undefined) throw new Error('Node#source is undefined');
+  // The node derived from `postcss.parse` always has `start` and `end` property. Therefore, this line is unreachable.
+  if (atValue.source.start === undefined) throw new Error('Node#start is undefined');
+  if (atValue.source.end === undefined) throw new Error('Node#end is undefined');
+  if (atValue.source.input.file === undefined) throw new Error('Node#input.file is undefined');
+
+  return {
+    filePath: atValue.source.input.file,
+    start: {
+      line: atValue.source.start.line,
+      column: atValue.source.start.column + 7, // Add for `@value `
+    },
+    end: {
+      line: atValue.source.start.line,
+      column: atValue.source.start.column + 7 + valueDeclaration.tokenName.length, // Add for `@value ` and token name
+    },
+  };
+}
+
 function isAtRuleNode(node: Node): node is AtRule {
   return node.type === 'atrule';
 }
@@ -143,16 +156,9 @@ function isRuleNode(node: Node): node is Rule {
   return node.type === 'rule';
 }
 
-function isDeclaration(node: Node): node is Declaration {
-  return node.type === 'decl';
-}
-
-function isComposesDeclaration(node: Node): node is Declaration {
-  return isDeclaration(node) && node.prop === 'composes';
-}
-
 type CollectNodesResult = {
   atImports: AtRule[];
+  atValues: AtRule[];
   classSelectors: { rule: Rule; classSelector: ClassName }[];
 };
 
@@ -162,10 +168,13 @@ type CollectNodesResult = {
  */
 export function collectNodes(ast: Root): CollectNodesResult {
   const atImports: AtRule[] = [];
+  const atValues: AtRule[] = [];
   const classSelectors: { rule: Rule; classSelector: ClassName }[] = [];
   ast.walk((node) => {
     if (isAtImportNode(node)) {
       atImports.push(node);
+    } else if (isAtValueNode(node)) {
+      atValues.push(node);
     } else if (isRuleNode(node)) {
       // In `rule.selector` comes the following string:
       // 1. ".foo"
@@ -183,7 +192,7 @@ export function collectNodes(ast: Root): CollectNodesResult {
       }).processSync(node);
     }
   });
-  return { atImports, classSelectors };
+  return { atImports, atValues, classSelectors };
 }
 
 /**
@@ -202,3 +211,78 @@ export function parseAtImport(atImport: AtRule): string | undefined {
   }
   return undefined;
 }
+
+type ValueDeclaration = {
+  type: 'valueDeclaration';
+  tokenName: string;
+  // value: string; // unneeded
+};
+type ValueImportDeclaration = {
+  type: 'valueImportDeclaration';
+  imports: { importedTokenName: string; localTokenName: string }[];
+  from: string;
+};
+
+type ParsedAtValue = ValueDeclaration | ValueImportDeclaration;
+
+const matchImports = /^(.+?|\([\s\S]+?\))\s+from\s+("[^"]*"|'[^']*'|[\w-]+)$/u;
+const matchValueDefinition = /(?:\s+|^)([\w-]+):?(.*?)$/u;
+const matchImport = /^([\w-]+)(?:\s+as\s+([\w-]+))?/u;
+
+/**
+ * Parse the `@value` rule.
+ * Forked from https://github.com/css-modules/postcss-modules-values/blob/v4.0.0/src/index.js.
+ *
+ * @license
+ * ISC License (ISC)
+ * Copyright (c) 2015, Glen Maddern
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted,
+ * provided that the above copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING
+ * ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+ * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+ * WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH
+ * THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+export function parseAtValue(atValue: AtRule): ParsedAtValue {
+  const matchesForImports = atValue.params.match(matchImports);
+  if (matchesForImports) {
+    const [, aliases, path] = matchesForImports;
+
+    // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+    if (aliases === undefined || path === undefined) throw new Error(`unreachable`);
+
+    const imports = aliases
+      .replace(/^\(\s*([\s\S]+)\s*\)$/u, '$1')
+      .split(/\s*,\s*/u)
+      .map((alias) => {
+        const tokens = matchImport.exec(alias);
+
+        if (tokens) {
+          const [, theirName, myName] = tokens;
+          if (theirName === undefined) throw new Error(`unreachable`);
+          return { importedTokenName: theirName, localTokenName: myName ?? theirName };
+        } else {
+          throw new Error(`@import statement "${alias}" is invalid!`);
+        }
+      });
+
+    // Remove quotes from the path.
+    // NOTE: This is a restriction unique to "happy-css-modules" and not a specification of CSS Modules.
+    const normalizedPath = path.replace(/^['"]|['"]$/gu, '');
+
+    return { type: 'valueImportDeclaration', imports, from: normalizedPath };
+  }
+
+  const matchesForValueDefinitions = `${atValue.params}${atValue.raws.between!}`.match(matchValueDefinition);
+  if (matchesForValueDefinitions) {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const [, key, value] = matchesForValueDefinitions;
+    if (key === undefined) throw new Error(`unreachable`);
+    return { type: 'valueDeclaration', tokenName: key };
+  }
+  // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+  throw new Error(`@value statement "${atValue.source!}" is invalid!`);
+}

package/src/test-util/util.ts

@@ -21,31 +21,36 @@ export function createAtImports(root: Root): AtRule[] {
   return collectNodes(root).atImports;
 }
 
+export function createAtValues(root: Root): AtRule[] {
+  return collectNodes(root).atValues;
+}
+
 export function createClassSelectors(root: Root): { rule: Rule; classSelector: ClassName }[] {
   return collectNodes(root).classSelectors;
 }
 
 export function fakeToken(args: {
   name: Token['name'];
-  originalLocations: { filePath?: Location['filePath']; start?: Location['start'] }[];
+  originalLocation: { filePath?: Location['filePath']; start?: Location['start'] };
 }): Token {
-  return {
-    name: args.name,
-    originalLocations: args.originalLocations.map((location) => {
-      if (location.filePath === undefined || location.start === undefined) {
-        return { filePath: undefined, start: undefined, end: undefined };
-      } else {
-        return {
-          filePath: location.filePath ?? getFixturePath('/test/1.css'),
-          start: location.start,
-          end: {
-            line: location.start.line,
-            column: location.start.column + args.name.length - 1,
-          },
-        };
-      }
-    }),
-  };
+  if (args.originalLocation.filePath === undefined || args.originalLocation.start === undefined) {
+    return {
+      name: args.name,
+      originalLocation: { filePath: undefined, start: undefined, end: undefined },
+    };
+  } else {
+    return {
+      name: args.name,
+      originalLocation: {
+        filePath: args.originalLocation.filePath ?? getFixturePath('/test/1.css'),
+        start: args.originalLocation.start,
+        end: {
+          line: args.originalLocation.start.line,
+          column: args.originalLocation.start.column + args.name.length - 1,
+        },
+      },
+    };
+  }
 }
 
 export async function waitForAsyncTask(ms?: number): Promise<void> {