.clinerules

# プロジェクト構成

## プロジェクトの概要

- このプロジェクトは CSS Modules に関するツールセットです
- このプロジェクトは、以下のパッケージから構成されています
  - `core`: 他のパッケージから使われる共通のコードを含むパッケージ
  - `codegen`: コード生成ツール。`*.module.css` ファイルから TypeScript の型定義ファイルを生成します
  - `stylelint-plugin`: CSS Modules 用の stylelint プラグイン
  - `ts-plugin`: CSS Modules 用の TypeScript Language Service Plugin
  - `vscode`: `ts-plugin` を組み込んだ VS Code 拡張機能

# ディレクトリ構造

## サンプルディレクトリ

- `example` ディレクトリには、`codegen`, `stylelint-plugin`, `vscode` を試すためのサンプルが含まれています

## ファイル名とディレクトリ名にはケバブケースを使う

- ファイル名とディレクトリ名にはケバブケースを使ってください
- 例: `my-file.ts`, `my-file.test.ts`, `my-directory`

## barrel file は作らない

- 他のファイルのアイテムを import して、そのまま export するだけの barrel file は作らないでください

```ts
// Bad
// src/index.ts
export * from './my-file-1.js';
export { myFunction } from './my-file-2.js';
```

## テストファイルは、テスト対象のファイルと同じディレクトリに配置する

- テストファイルは、テスト対象のファイルと同じディレクトリに配置してください
- テストファイルの名前は、テスト対象のファイルの名前に `.test.ts` を付けたものにしてください
- 例: `src/my-file.ts` のテストファイルは `src/my-file.test.ts`

## E2E テストファイルは `e2e` ディレクトリに配置する

- テストファイルの中でも、E2E テストのファイルは `e2e` ディレクトリに配置してください
- 例: `e2e/my-e2e.test.ts`

## テストでのみ利用する utility 関数は、`src/test` ディレクトリに配置する

- テストでのみ利用する utility 関数は、`src/test` ディレクトリに配置してください
- 例: `src/test/ast.ts`

## 3rd-party ライブラリの型を拡張するための型定義ファイルは `typing` ディレクトリに配置する

- 3rd-party ライブラリの型を拡張するための型定義ファイルは `typing` ディレクトリに配置してください
- 例: `typing/my-library.d.ts`

# ビルドと実行

## npm-scripts

- `npm run build`: コードをビルドします
- `npm run lint`: formatter や linter、型チェッカーを実行します
- `npm t`: ユニットテストを実行します
- `npm run e2e`: コードをビルドした上で E2E テストを実行します

## VS Code Launch Configuration

- `codegen: debug`: `example` ディレクトリに対して、`codegen` package をデバッグモードで実行します
- `stylelint-plugin: debug`: `example` ディレクトリに対して、`stylelint-plugin` package をデバッグモードで実行します
- `vscode: debug`: `example` ディレクトリに対して、`vscode` package をデバッグモードで実行します

# コーディングスタイル

## クラスは原則使用しない

- `class` は原則使用しないでください
  - 使って良いのはエラークラスのみです
- 状態を持つオブジェクトを作る場合は、`createXxx` という関数を使ってください
- 関数の返り値の型は、`interface` で定義してください

```ts
// Bad
class User {
  private name: string;
  constructor(name: string) {
    this.name = name;
  }
  getName() {
    return this.name;
  }
}

// Good
interface User {
  name: string;
  getName(): string;
}
function createUser(name: string): User {
  return {
    name,
    getName() {
      return name;
    },
  };
}
```

## throw するエラーは Error クラスを継承したクラスを使う

- エラーを throw する場合は、`Error` クラスを継承したクラスを使ってください
- エラークラスは、`src/error.ts` に配置してください

```ts
// src/error.ts
class AuthError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'AuthError';
  }
}
```

## エラーを throw する時は `@throws` を使う

- 例外を throw する場合は、throw する 関数の JSDoc に `@throws` で例外の説明を記述してください
- `@throws` には、例外の型と、その例外がどういう時に throw されるかを記述してください

```ts
/**
 * @throws {AuthError} When the user is not authorized
 */
function myFunction() {
  if (!user.isAuthorized()) {
    throw new AuthError('User is not authorized');
  }
}
```

## エラーが throw される可能性のある関数を呼び出す場合は、呼び出し元の関数にも `@throws` を記述する

- エラーが throw される可能性のある関数を呼び出す場合は、呼び出し元の関数の JSDoc にも `@throws` を記述してください
- `@throws` には、呼び出される関数が throw する可能性のある例外の型と、その例外がどういう時に throw されるかを記述してください
- ただし、呼び出し元の関数で、呼び出される関数が throw する例外を catch して処理する場合は、`@throws` は不要です

```ts
/**
 * @throws {AuthError} When the user is not authorized
 */
function myFunction1() {
  anotherFunction();
}

function myFunction2() {
  try {
    anotherFunction();
  } catch (e) {
    // エラー処理
  }
}

/**
 * @throws {AuthError} When the user is not authorized
 */
function anotherFunction() {
  if (!user.isAuthorized()) {
    throw new AuthError('User is not authorized');
  }
}
```

## テストからのみ import する関数は、そのまま export せずに `xxxForTest` という名前で export する

- テストからのみ import する関数は、そのまま export せずに `xxxForTest` という名前で export してください

```ts
// src/my-file.ts
function myFunction() {
  // ...
}

export { myFunction as myFunctionForTest };
```