@aramassa/ai-rules 0.1.1-npmjs.20250910072942 → 0.1.5

package/artifact/instructions/rules/test/environment-independent-paths.md

@@ -0,0 +1,206 @@
+---
+type: test
+category: best-practices
+focus: environment-independence
+---
+
+# 環境非依存テスト実行のためのパス指定ルール
+
+## 概要
+
+テスト実行は、ローカル環境でもCI環境でもどちらでもパスするように気をつける必要があります。パス指定などは絶対パス指定にせず、環境に依存しない書き方をすることが重要です。
+
+## 背景・理由
+
+コーディングするのはAIだけではありません。手動で修正した内容が問題ないかの確認を実施する際に、ローカル環境でテストがこけてしまうと困ります。CI環境とローカル環境の差異によるテスト失敗を防ぐため、環境に依存しないテストコードの作成が必要です。
+
+## 基本原則
+
+### 1. 絶対パスの使用を避ける
+
+- **禁止**: `/home/user/project/test-data/sample.txt` のような絶対パス指定
+- **推奨**: 相対パス や Node.js の `path` モジュールを使った動的パス生成
+
+### 2. 一時ディレクトリの適切な使用
+
+- **推奨**: `os.tmpdir()` と `mkdtemp()` の組み合わせを使用
+- **理由**: OS固有の一時ディレクトリ場所を自動で取得し、ユニークなディレクトリを作成
+
+### 3. プラットフォーム依存機能の適切な処理
+
+- **推奨**: テスト前後で環境変数やプラットフォーム情報を保存・復元
+- **推奨**: プラットフォーム固有の機能は条件分岐で対応
+
+## 実装パターン
+
+### パターン 1: 一時ディレクトリの使用
+
+```typescript
+import { mkdtemp, rm } from "fs/promises";
+import path from "path";
+import os from "os";
+
+describe("Example Test", () => {
+  let testTempDir: string;
+
+  beforeEach(async () => {
+    // 環境に依存しない一時ディレクトリの作成
+    testTempDir = await mkdtemp(path.join(os.tmpdir(), "test-prefix-"));
+  });
+
+  afterEach(async () => {
+    // テスト後のクリーンアップ
+    try {
+      await rm(testTempDir, { recursive: true, force: true });
+    } catch {
+      // エラーは無視（クリーンアップエラーは致命的ではない）
+    }
+  });
+
+  it("should work with temporary files", async () => {
+    const testFile = path.join(testTempDir, "test.txt");
+    // テスト実装...
+  });
+});
+```
+
+### パターン 2: 環境変数の保存・復元
+
+```typescript
+describe("Environment Test", () => {
+  let originalEnv: NodeJS.ProcessEnv;
+  let originalPlatform: string;
+
+  beforeEach(() => {
+    // 元の環境を保存
+    originalEnv = { ...process.env };
+    originalPlatform = process.platform;
+  });
+
+  afterEach(() => {
+    // 環境を復元
+    process.env = originalEnv;
+    Object.defineProperty(process, 'platform', {
+      value: originalPlatform
+    });
+  });
+
+  it("should handle platform differences", () => {
+    // プラットフォーム固有のテスト...
+  });
+});
+```
+
+### パターン 3: 相対パスの適切な解決
+
+```typescript
+import path from "path";
+
+describe("Path Resolution Test", () => {
+  it("should resolve paths correctly", () => {
+    // ❌ 絶対パス（環境依存）
+    // const filePath = "/home/user/project/src/cli.ts";
+    
+    // ✅ 相対パス（環境非依存）
+    const filePath = path.resolve("src/cli.ts");
+    
+    // ✅ パッケージルートからの相対パス
+    const packageRoot = findPackageRoot();
+    const configPath = path.join(packageRoot, "config/settings.json");
+  });
+});
+```
+
+### パターン 4: CLI実行時のパス指定
+
+```typescript
+import { execSync } from "child_process";
+import path from "path";
+
+describe("CLI Test", () => {
+  it("should execute CLI with proper paths", () => {
+    const testSrcDir = path.join(testTempDir, "test-src");
+    
+    // ❌ 絶対パスでCLIファイル指定
+    // execSync(`/home/user/project/dist/cli.js extract --src ${testSrcDir}`);
+    
+    // ✅ 相対パスでCLIファイル指定
+    execSync(`npx tsx src/cli.ts extract --src ${testSrcDir}`, {
+      cwd: process.cwd(), // 現在の作業ディレクトリを明示
+      stdio: "pipe"
+    });
+  });
+});
+```
+
+## 避けるべきパターン
+
+### ❌ 絶対パスの直接指定
+
+```typescript
+// 悪い例: ユーザーディレクトリやシステムパスの直接指定
+const testFile = "/home/runner/project/test/data.txt";
+const configPath = "C:\\Users\\user\\project\\config.json";
+```
+
+### ❌ プラットフォーム固有パスの固定
+
+```typescript
+// 悪い例: パス区切り文字の直接使用
+const filePath = "src/utils/helper.js"; // Windowsでは問題になる可能性
+// 良い例: path.join() の使用
+const filePath = path.join("src", "utils", "helper.js");
+```
+
+### ❌ 環境変数の復元なし
+
+```typescript
+// 悪い例: テスト後に環境を復元しない
+it("should test with modified env", () => {
+  process.env.TEST_VAR = "test-value";
+  // テスト後も環境変数が残り、他のテストに影響する
+});
+```
+
+## クリーンアップのベストプラクティス
+
+### 確実なリソース解放
+
+```typescript
+afterEach(async () => {
+  // ファイルシステムリソースの解放
+  try {
+    await rm(testTempDir, { recursive: true, force: true });
+  } catch {
+    // クリーンアップエラーは無視（テストの失敗より重要ではない）
+  }
+});
+```
+
+### プロセス状態の復元
+
+```typescript
+afterEach(() => {
+  // プロセス状態を確実に復元
+  process.env = originalEnv;
+  process.chdir(originalCwd);
+});
+```
+
+## CI/ローカル共通の注意点
+
+1. **タイムアウト設定**: CI環境では処理が遅い場合があるため、適切なタイムアウト値を設定
+2. **並列実行対応**: 複数のテストが同時実行されても競合しないよう、ユニークな識別子を使用
+3. **権限問題の回避**: 読み取り専用ファイルや権限制限のあるディレクトリを避ける
+4. **パスの長さ制限**: Windows環境での長いパス名制限を考慮
+
+## 検証方法
+
+テストが環境非依存であることを確認する方法：
+
+1. **ローカルでの実行**: `npm test`
+2. **異なるワーキングディレクトリからの実行**: 別のディレクトリからテストを実行
+3. **CI環境での実行**: GitHub Actions や他のCI環境での動作確認
+4. **異なるOS環境**: 可能であれば Windows/Linux/macOS での動作確認
+
+このルールに従うことで、テストはどの環境でも一貫して動作し、開発者の生産性向上とCI/CDパイプラインの安定性を実現できます。

package/artifact/prompts/todo_plans.prompt.md

@@ -0,0 +1,47 @@
+---
+type: prompt
+category: todo-planning
+focus: workflow-management
+---
+
+# TODO Plans 作成ルール
+
+## 基本ルール
+
+- 今後の計画を立てる際は、必ず `todo_plans/` に記載する
+- ファイル名規則は、`YYYYMMDD_[タイトル].md`
+- 計画が不要になった場合は削除する。Git の履歴で過去の計画は追跡できるため、アーカイブせずにリポジトリをすっきり保つ
+
+## ワークフロー管理
+
+### todo_plans の役割
+
+#### todo_plans段階
+
+- **目的**: 将来の計画とアイデアの整理
+- **期間**: プロジェクトのアイデア段階
+- **成果物**: 計画の概要と方向性
+- **品質基準**: 実現したいことが明確に記述されている
+
+## 実践ガイドライン
+
+- 将来実装したい機能やアイデアは、必ず todo_plans/ に記載する
+- 計画の内容は、実現したいことと大まかな方向性を記述する
+- 詳細な実装方法は不要。コンセプトレベルで十分
+- 計画が変更されたり不要になった場合は、ファイルを削除してリポジトリを整理する
+
+## ファイル名規則の例
+
+```
+todo_plans/
+├── 20250911_API機能拡張構想.md
+├── 20250911_パフォーマンス改善アイデア.md
+└── 20250911_新機能企画書.md
+```
+
+## 注意事項
+
+- todo_plans は「将来やりたいこと」「検討したいアイデア」の整理段階
+- 具体的な実装計画ではなく、方向性やコンセプトを記録する
+- 実装に着手する際は、別途 change_plans でより詳細な計画を立てる
+- 長期的なビジョンや中期的な目標の管理に活用する

package/dist/cli.d.ts

@@ -1,3 +1,6 @@
 #!/usr/bin/env node
-export {};
+/**
+ * Recursively scans a directory for YAML files and returns their relative paths
+ */
+export declare function findYamlFilesRecursively(dir: string, baseDir?: string): Promise<string[]>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

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