|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +CSS Modules Kit is a toolkit that makes CSS Modules more convenient. It uses the TypeScript Language Service Plugin and Volar.js to provide rich editor language features for CSS Modules (Go to Definition, Rename, Find All References, etc.). |
| 6 | + |
| 7 | +The provided language features and available settings are described in [README.md](./README.md). |
| 8 | + |
| 9 | +## Architecture |
| 10 | + |
| 11 | +This project is a monorepo and consists of the following packages: |
| 12 | + |
| 13 | +- **packages/core**: Common package that provides core functionality such as parsing CSS Modules, generating type definitions, and validation |
| 14 | +- **packages/ts-plugin**: Implementation of the TypeScript Language Service Plugin (Volar.js-based) |
| 15 | + - Provides language features such as Go to Definition, Rename, Find All References |
| 16 | +- **packages/codegen**: CLI tool to generate CSS Modules type definition files (`.d.ts`) |
| 17 | +- **packages/vscode**: VS Code extension |
| 18 | + - Wrapper to run ts-plugin in VS Code |
| 19 | +- **packages/stylelint-plugin**: Stylelint plugin |
| 20 | +- **packages/eslint-plugin**: ESLint plugin |
| 21 | +- **crates/zed**: Zed editor extension (Rust implementation) |
| 22 | + - Wrapper to run ts-plugin in Zed |
| 23 | + |
| 24 | +Package dependencies: |
| 25 | + |
| 26 | +- ts-plugin, codegen, stylelint-plugin, and eslint-plugin all depend on the core package |
| 27 | +- Functionality is implemented via APIs provided by the core package (`parseCSSModule`, `generateDts`, `checkCSSModule`, etc.) |
| 28 | + |
| 29 | +## Development Commands |
| 30 | + |
| 31 | +```bash |
| 32 | +npm run build # Build all packages |
| 33 | + |
| 34 | +npm run lint # Run all linting |
| 35 | + |
| 36 | +npm run test # Run all tests except VS Code extension tests |
| 37 | +npx vitest --run --project unit # Run only unit tests |
| 38 | +npx vitest --run --project e2e # Run only E2E tests |
| 39 | +npx vitest --run packages/core/src/parser/css-module-parser.test.ts # Run a specific test file |
| 40 | +npm run vscode-test # Run VS Code extension tests |
| 41 | +``` |
| 42 | + |
| 43 | +### Updating generated files in examples |
| 44 | + |
| 45 | +The examples directory contains generated type definition files produced by codegen as examples. If the generated type definition files change, these files must also be updated. You can update them with the following command: |
| 46 | + |
| 47 | +```bash |
| 48 | +npm run update-generated-in-examples |
| 49 | +``` |
| 50 | + |
| 51 | +## Coding Conventions |
| 52 | + |
| 53 | +### Error Handling |
| 54 | + |
| 55 | +**Defining error classes**: |
| 56 | + |
| 57 | +- Use classes that extend `Error` for errors to be thrown |
| 58 | +- Place error classes in `packages/*/src/error.ts` |
| 59 | + |
| 60 | +```ts |
| 61 | +// packages/*/src/error.ts |
| 62 | +class AuthError extends Error { |
| 63 | + constructor(message: string) { |
| 64 | + super(message); |
| 65 | + this.name = 'AuthError'; |
| 66 | + } |
| 67 | +} |
| 68 | +``` |
| 69 | + |
| 70 | +**Using @throws**: |
| 71 | + |
| 72 | +- For functions that throw, describe exceptions with JSDoc `@throws` |
| 73 | +- Propagate `@throws` to calling functions (when not caught by try) |
| 74 | + |
| 75 | +```ts |
| 76 | +/** |
| 77 | + * @throws {AuthError} When the user is not authorized |
| 78 | + */ |
| 79 | +function myFunction() { |
| 80 | + if (!user.isAuthorized()) { |
| 81 | + throw new AuthError('User is not authorized'); |
| 82 | + } |
| 83 | +} |
| 84 | +``` |
| 85 | + |
| 86 | +## Glossary |
| 87 | + |
| 88 | +- **Token**: A generic term for things exported by CSS Modules, such as class names and values defined with `@value`. |
| 89 | +- **Diagnostic**: An object representing errors or warnings |
| 90 | +- **Parse phase**: The phase that parses CSS Modules files and extracts token information |
| 91 | +- **Check phase**: The phase that validates CSS Modules files |
| 92 | +- **Emit phase**: The phase that generates `.d.ts` files |
| 93 | +- **cmkOptions**: Various option settings for CSS Modules Kit |
| 94 | +- **Mapping**: An object that maintains the positional relationship between a `.d.ts` file and its corresponding .css file |
| 95 | + - Mapping enables language features such as Go to Definition, Find All References, Rename |
| 96 | + |
| 97 | +## Key Files |
| 98 | + |
| 99 | +- `packages/core/src/type.ts`: Main type definitions used by CSS Modules Kit |
| 100 | +- `packages/core/src/parser/css-module-parser.ts`: CSS Modules parsing |
| 101 | + - Responsible for extracting tokens and generating diagnostics detectable during parsing |
| 102 | +- `packages/core/src/checker.ts`: CSS Modules validation |
| 103 | + - Responsible for generating diagnostics that cannot be detected in the parse phase |
| 104 | +- `packages/core/src/dts-generator.ts`: Generates type definition files (`.d.ts`) and mappings. |
| 105 | + |
| 106 | +## Tech Stack |
| 107 | + |
| 108 | +- TypeScript |
| 109 | +- Vitest |
| 110 | +- ESLint |
| 111 | +- Prettier |
| 112 | +- npm, npm workspaces |
| 113 | +- Changesets |
| 114 | + |
| 115 | +## Other |
| 116 | + |
| 117 | +- Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) |
| 118 | + - `<type>`: use one of feat, fix, docs, refactor, test, chore, deps |
| 119 | + - `[optional scope]`: choose one of core, ts-plugin, codegen, vscode, stylelint-plugin, eslint-plugin, zed |
| 120 | + - For changes spanning multiple packages, use comma-separated scopes like `feat(core, ts-plugin): ...` |
| 121 | +- If you make changes that affect users, add a changeset file under `.changeset` |
0 commit comments