@aramassa/ai-rules 0.4.0 → 0.4.3

package/artifact/instructions/rules/workspace-management/typescript.md

@@ -0,0 +1,337 @@
+---
+type: package-management
+category: workspace
+language: typescript
+applyTo: "**/tsconfig.json"
+human-instruction: |-
+  ## TypeScript Project References の特性
+
+  TypeScript のプロジェクト参照（Project References）は、複数のパッケージ間での型情報共有とビルド最適化を実現する仕組みです。
+
+  特に注意すべき点：
+  - `references` フィールドでパッケージ間の依存関係を明示する
+  - `composite: true` を設定することで、プロジェクト参照が有効になる
+  - `tsc --build` コマンドで依存関係を考慮した段階的ビルドが可能
+---
+
+# TypeScript Workspace Management Rules
+
+## 目次
+
+- [Overview](#overview)
+- [TypeScript Configuration](#typescript-configuration)
+- [Project References](#project-references)
+- [Build Strategy](#build-strategy)
+- [Type Definition Management](#type-definition-management)
+- [Common Issues](#common-issues)
+- [Best Practices](#best-practices)
+
+## Overview
+
+このドキュメントは **TypeScript Project References** に特化したルールです。
+
+基本的なワークスペース管理については [nodejs.md](./nodejs.md) を参照してください。
+
+## TypeScript Configuration
+
+### Root tsconfig.json
+
+ルートの `tsconfig.json` は共通設定を定義します：
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "composite": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+### Package-level tsconfig.json
+
+各パッケージの `tsconfig.json`:
+
+```json
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "references": [
+    { "path": "../common" }
+  ],
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}
+```
+
+## Project References
+
+### 依存関係の定義
+
+パッケージ間の依存関係は `references` フィールドで明示します：
+
+```json
+// packages/core/tsconfig.json
+{
+  "references": [
+    { "path": "../common" }
+  ]
+}
+```
+
+```json
+// packages/cli/tsconfig.json
+{
+  "references": [
+    { "path": "../common" },
+    { "path": "../core" }
+  ]
+}
+```
+
+### composite フラグ（必須）
+
+プロジェクト参照を有効にするため、各パッケージで `composite: true` を設定：
+
+```json
+{
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true
+  }
+}
+```
+
+**composite: true の効果**:
+- `.d.ts` ファイル（型定義）の生成を強制
+- `tsconfig.tsbuildinfo` ファイルによる段階的ビルドの有効化
+- プロジェクト参照による高速な型チェック
+
+## Build Strategy
+
+### 推奨ビルドコマンド
+
+```bash
+# TypeScript の段階的ビルド（推奨）
+npx tsc --build
+
+# watch モード（開発時）
+npx tsc --build --watch
+
+# クリーンビルド
+npx tsc --build --clean
+npx tsc --build
+```
+
+### package.json の scripts
+
+```json
+{
+  "scripts": {
+    "build": "tsc --build",
+    "build:clean": "tsc --build --clean",
+    "build:watch": "tsc --build --watch"
+  }
+}
+```
+
+## Type Definition Management
+
+### 型定義の export
+
+各パッケージで型定義を適切に export します：
+
+```typescript
+// packages/common/src/index.ts
+export type { CommonConfig } from './types';
+export { createCommon } from './common';
+```
+
+```json
+// packages/common/package.json
+{
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"]
+}
+```
+
+### 型定義の import
+
+```typescript
+// packages/core/src/index.ts
+import type { CommonConfig } from '@scope/common';
+import { createCommon } from '@scope/common';
+
+export function createCore(config: CommonConfig) {
+  const common = createCommon(config);
+  // ...
+}
+```
+
+### 共有型定義パッケージ
+
+プロジェクト全体で使用する型定義は `types` パッケージに集約：
+
+```typescript
+// packages/types/src/index.ts
+export type ProjectConfig = {
+  name: string;
+  version: string;
+};
+
+export type Result<T, E = Error> =
+  | { success: true; data: T }
+  | { success: false; error: E };
+```
+
+## Common Issues
+
+### 型定義が認識されない
+
+**原因**: プロジェクト参照の設定漏れ
+
+```json
+// packages/core/tsconfig.json
+{
+  "references": [{ "path": "../common" }],
+  "compilerOptions": {
+    "composite": true
+  }
+}
+```
+
+```bash
+npx tsc --build
+```
+
+### ビルドエラー: "Project references may not form a circular chain"
+
+**原因**: 循環参照（`core` → `cli` → `core`）
+
+解決策: 依存関係を見直し、共通機能を `common` に移動
+
+### import の型解決ができない
+
+**原因**: `declaration: true` の設定漏れ
+
+```json
+{
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true
+  }
+}
+```
+
+## Best Practices
+
+1. **composite フラグの徹底**: 全パッケージで `composite: true` を設定
+2. **型定義の明示的 export**: 公開する型は必ず `export type` で export
+3. **段階的ビルドの活用**: `tsc --build` でビルド時間を短縮
+4. **declarationMap の活用**: デバッグ時にソースコードにジャンプ可能
+5. **tsconfig の継承**: 共通設定はルートで定義して `extends` で継承
+
+### tsconfig.json テンプレート
+
+```json
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "references": [
+    // 依存するパッケージのパスを記載
+  ],
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}
+```
+
+### Example Project Structure
+
+```
+my-monorepo/
+├── tsconfig.json             # ルート設定
+├── packages/
+│   ├── types/
+│   │   ├── tsconfig.json     # composite: true
+│   │   └── src/index.ts
+│   ├── common/
+│   │   ├── tsconfig.json     # references: [types]
+│   │   └── src/index.ts
+│   ├── core/
+│   │   ├── tsconfig.json     # references: [types, common]
+│   │   └── src/index.ts
+│   └── cli/
+│       ├── tsconfig.json     # references: [types, common, core]
+│       └── src/index.ts
+└── tsconfig.tsbuildinfo      # ビルドキャッシュ（.gitignore）
+```
+
+## Related Documentation
+
+- [Node.js Workspace Management](./nodejs.md) - npm workspaces の基本ルール
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "references": [
+    // 依存するパッケージを記載
+  ],
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}
+```
+
+### Example Project Structure
+
+```
+my-monorepo/
+├── tsconfig.json             # ルート設定
+├── package.json
+├── packages/
+│   ├── types/
+│   │   ├── tsconfig.json     # composite: true
+│   │   ├── package.json
+│   │   └── src/
+│   │       └── index.ts
+│   ├── common/
+│   │   ├── tsconfig.json     # references: [types]
+│   │   ├── package.json
+│   │   └── src/
+│   │       └── index.ts
+│   ├── core/
+│   │   ├── tsconfig.json     # references: [types, common]
+│   │   ├── package.json
+│   │   └── src/
+│   │       └── index.ts
+│   └── cli/
+│       ├── tsconfig.json     # references: [types, common, core]
+│       ├── package.json
+│       └── src/
+│           └── index.ts
+└── tsconfig.tsbuildinfo      # ビルドキャッシュ（gitignore）
+```

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAujBA;;GAEG;AACH,wBAAsB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,MAAY,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAyBpG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA+qBA;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,MAAY,GACpB,OAAO,CAAC,MAAM,EAAE,CAAC,CA4BnB"}