@aramassa/ai-rules 0.4.0 → 0.4.3

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

@@ -0,0 +1,358 @@
+---
+type: package-management
+category: workspace
+language: nodejs
+applyTo: "**/package.json"
+human-instruction: |-
+  ## npm Workspaces の特性
+
+  npm workspaces は npm 7.0+ で利用可能な、単一リポジトリ内で複数のパッケージを管理する仕組みです。
+
+  特に注意すべき点：
+  - npm 7.0 以降が必須
+  - ワークスペース間の依存関係は自動的にシンボリックリンクされる
+  - `--workspace` フラグで特定のパッケージに対してコマンドを実行可能
+---
+
+# Node.js (npm) Workspace Management Rules
+
+## 目次
+
+- [Overview](#overview)
+- [Workspace Configuration](#workspace-configuration)
+- [Package Structure Rules](#package-structure-rules)
+- [Package Management Commands](#package-management-commands)
+- [Build and Development Workflow](#build-and-development-workflow)
+- [Local CLI Execution](#local-cli-execution)
+- [Package Distribution Check（必須）](#package-distribution-check必須)
+- [Common Issues](#common-issues)
+- [Best Practices](#best-practices)
+- [Example Project Structure](#example-project-structure)
+
+## Overview
+
+このルールでは **npm のみ** を使用します（yarn/pnpm は使用禁止）。
+
+npm workspaces（npm 7.0+）で単一リポジトリ内の複数パッケージを管理します。
+
+## Workspace Configuration
+
+ルートの `package.json`:
+
+```json
+{
+  "name": "my-monorepo",
+  "private": true,
+  "workspaces": ["packages/*"]
+}
+```
+
+## Package Structure Rules
+
+### 必須パッケージ
+
+| パッケージ名 | 説明 | 依存関係ルール |
+|:-----------|:-----|:-------------|
+| `core` | プロジェクトの主機能 | `common` に依存可能 |
+| `common` | 共有機能 | 他パッケージに依存不可 |
+
+### オプションパッケージ
+
+- `cli` - CLI（`core` に依存）
+- `types` - 型定義（依存なし）
+- `utils` - ユーティリティ（`common` に依存可能）
+
+### 依存関係のルール
+
+```
+common (依存なし)
+  ↑
+core (common に依存可能)
+  ↑
+cli, その他 (core, common に依存可能)
+```
+
+**禁止**: `core` が `cli` などに依存、`common` が他の内部パッケージに依存
+
+### テストのルール
+
+**重要**: 各パッケージのテストは、そのパッケージ内で完結する必要があります。
+
+- ✅ **許可される**: 自パッケージ内のコードのみをテスト
+- ✅ **許可される**: 依存しているパッケージ（`common`、`core`）の公開APIを使用
+- ❌ **禁止**: 他パッケージの内部実装に依存したテスト
+- ❌ **禁止**: テストのために他パッケージのテストヘルパーをインポート
+
+```bash
+# 各パッケージで独立してテスト実行可能
+cd packages/common && npm test  # common のテストのみ
+cd packages/core && npm test    # core のテストのみ
+cd packages/cli && npm test     # cli のテストのみ
+
+# 全体テストも実行可能
+npm test --workspaces
+```
+
+**ベストプラクティス**:
+- テストヘルパーやモックが必要な場合は、各パッケージ内に配置
+- 共通のテストユーティリティが必要な場合は、`common` または専用の `test-utils` パッケージを作成
+
+## Package Management Commands
+
+```bash
+# インストール
+npm install
+
+# パッケージ追加
+npm install <package> --workspace=packages/core
+npm install <package> --workspaces  # 全ワークスペース
+
+# ワークスペース間依存
+cd packages/core
+npm install @scope/common
+# → node_modules/@scope/common は packages/common へのシンボリックリンク
+```
+
+## Build and Development Workflow
+
+```bash
+# ビルド（依存順に手動実行推奨）
+cd packages/common && npm run build
+cd ../core && npm run build
+cd ../cli && npm run build
+
+# または全体ビルド
+npm run build --workspaces
+
+# 開発時 watch
+npm run dev --workspaces
+npm run dev --workspace=packages/core
+
+# テスト
+npm test --workspaces
+npm test --workspace=packages/core
+npm test --workspaces --if-present  # スクリプトがない場合スキップ
+```
+
+## Local CLI Execution
+
+```bash
+# 1. ビルド実行（必須）
+npm run build --workspaces
+
+# 2. CLI 実行
+node packages/cli/dist/index.js
+npx @scope/cli  # bin フィールドがある場合
+
+# 開発時リンク
+npm link --workspace=packages/cli
+my-cli --version
+npm unlink --workspace=packages/cli -g  # 解除
+
+# TypeScript 直接実行（開発時）
+npx tsx packages/cli/src/index.ts
+```
+
+## Package Distribution Check（必須）
+
+### コミット前・リリース前の確認
+
+```bash
+cd packages/core
+npm pack --dry-run
+
+# 出力例：
+# npm notice 📦  @scope/core@1.0.0
+# npm notice === Tarball Contents ===
+# npm notice 1.2kB  dist/index.js
+# npm notice 256B   package.json
+```
+
+### 除外設定
+
+`package.json` の `files` フィールド（推奨）:
+
+```json
+{
+  "files": ["dist", "README.md", "LICENSE"]
+}
+```
+
+または `.npmignore`:
+
+```
+src/
+*.test.ts
+*.spec.ts
+tsconfig.json
+```
+
+### 確認タイミング
+
+- ✅ 新機能追加時
+- ✅ リファクタリング後
+- ✅ コミット前（必須）
+- ✅ リリース前（必須）
+
+## Common Issues
+
+### 型定義が認識されない
+
+```json
+// packages/core/tsconfig.json
+{
+  "references": [{ "path": "../common" }]
+}
+```
+
+```bash
+npx tsc --build
+```
+
+### ローカル変更が反映されない
+
+```bash
+npm run build --workspaces
+# または watch モード
+npm run dev --workspaces
+```
+
+### 循環依存エラー
+
+```
+ERROR: Circular dependency detected:
+  @scope/core -> @scope/cli -> @scope/core
+```
+
+解決策:
+1. 依存関係ルールを確認
+2. 共通機能を `common` に移動
+
+### npm install が遅い
+
+```bash
+rm -rf node_modules packages/*/node_modules
+npm install
+# または CI 環境で
+npm ci
+```
+
+## Best Practices
+
+1. **ビルド前提**: CLI/スクリプト実行前に必ずビルド
+2. **依存管理**: `core` → `common` の一方向を守る
+3. **配布物確認**: `npm pack --dry-run` を徹底
+4. **private 設定**: ルートの package.json に `"private": true"`
+5. **TypeScript**: プロジェクト参照で型定義を共有
+
+## Example Project Structure
+
+```
+my-monorepo/
+├── package.json              # workspaces 定義、private: true
+├── package-lock.json
+├── node_modules/
+├── packages/
+│   ├── common/
+│   │   ├── package.json      # @scope/common
+│   │   ├── src/
+│   │   └── dist/
+│   ├── core/
+│   │   ├── package.json      # @scope/core
+│   │   ├── src/
+│   │   └── dist/
+│   └── cli/
+│       ├── package.json      # @scope/cli
+│       ├── src/
+│       └── dist/
+└── tsconfig.json
+```
+
+### 除外確認のタイミング
+
+- ✅ 新機能追加時
+- ✅ リファクタリング後
+- ✅ コミット前（必須）
+- ✅ リリース前（必須）
+
+## Common Issues and Solutions
+
+### Issue: ワークスペース間の型定義が認識されない
+
+```bash
+# 解決方法: TypeScript のプロジェクト参照を設定
+# packages/core/tsconfig.json
+{
+  "references": [
+    { "path": "../common" }
+  ]
+}
+
+# ビルド時に --build フラグを使用
+npx tsc --build
+```
+
+### Issue: ローカルパッケージの変更が反映されない
+
+```bash
+# 解決方法: ビルドを再実行
+npm run build --workspaces
+
+# または watch モードで開発
+npm run dev --workspaces
+```
+
+### Issue: パッケージの循環依存
+
+```
+ERROR: Circular dependency detected:
+  @scope/core -> @scope/cli -> @scope/core
+```
+
+解決方法:
+1. 依存関係ルールを確認（`core` は `cli` に依存してはいけない）
+2. 共通機能を `common` に移動
+3. アーキテクチャを見直し
+
+### Issue: npm install が遅い
+
+```bash
+# node_modules をクリーンアップ
+rm -rf node_modules packages/*/node_modules
+npm install
+
+# または npm ci を使用（CI環境推奨）
+npm ci
+```
+
+## Best Practices
+
+1. **ビルド前提の実行**: CLI やスクリプトを実行する前に必ずビルドを実行
+2. **厳格な依存関係管理**: `core` → `common` の一方向依存を守る
+3. **型定義の共有**: TypeScript プロジェクト参照を活用
+4. **配布物の確認**: `npm pack --dry-run` でリリース前確認を徹底
+5. **private フラグ**: ルートの package.json には `"private": true` を設定
+6. **バージョン管理**: 各パッケージのバージョンを適切に管理
+
+## Example Project Structure
+
+```
+my-monorepo/
+├── package.json              # ルート設定（workspaces 定義、private: true）
+├── package-lock.json         # ロックファイル
+├── node_modules/             # すべてのパッケージの依存関係
+├── packages/
+│   ├── common/
+│   │   ├── package.json      # @scope/common
+│   │   ├── src/
+│   │   └── dist/             # ビルド成果物
+│   ├── core/
+│   │   ├── package.json      # @scope/core（common に依存）
+│   │   ├── src/
+│   │   └── dist/
+│   └── cli/
+│       ├── package.json      # @scope/cli（core, common に依存）
+│       ├── src/
+│       └── dist/
+└── tsconfig.json             # ルート TypeScript 設定
+```

package/artifact/instructions/{python/workspace-management.md → rules/workspace-management/python.md}

@@ -184,7 +184,7 @@ if ! command -v uv &> /dev/null; then
     echo "📦 Installing uv..."
     curl -LsSf https://astral.sh/uv/install.sh | sh
     source $HOME/.cargo/env
-    
+
     # Verify installation
     if ! command -v uv &> /dev/null; then
         echo "❌ Failed to install uv. Please install manually."
@@ -547,21 +547,21 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    
+
     - name: Install uv
       uses: astral-sh/setup-uv@v1
       with:
         version: "latest"
-    
+
     - name: Set up Python ${{ matrix.python-version }}
       run: uv python install ${{ matrix.python-version }}
-    
+
     - name: Install dependencies
       run: uv sync --dev
-    
+
     - name: Run quality checks
       run: ./scripts/check-quality.sh
-    
+
     - name: Upload coverage reports
       uses: codecov/codecov-action@v3
       if: matrix.python-version == '3.11'
@@ -575,16 +575,16 @@ jobs:
    ```bash
    # 1. 開発環境更新
    uv sync --dev
-   
+
    # 2. 品質チェック
    ./scripts/check-quality.sh
-   
+
    # 3. 実装
    # ... コード変更 ...
-   
+
    # 4. テスト実行
    uv run pytest packages/target-package/tests/
-   
+
    # 5. 最終品質チェック
    ./scripts/check-quality.sh
    ```
@@ -649,7 +649,7 @@ uv run mypy packages/target-package/ --show-error-codes
    ```bash
    # poetry.lock から requirements.txt 生成
    poetry export --output requirements.txt
-   
+
    # UV での依存関係インストール
    uv add $(cat requirements.txt | cut -d'=' -f1)
    ```
@@ -670,4 +670,4 @@ uv run mypy packages/target-package/ --show-error-codes
 - [ ] 品質チェックがパス
 - [ ] CI/CD パイプラインが動作
 
-このガイドラインに従うことで、保守性が高く、開発効率の良い Python プロジェクトを UV workspace で管理できます。
+このガイドラインに従うことで、保守性が高く、開発効率の良い Python プロジェクトを UV workspace で管理できます。