ADR-001: 重複コード解消のためのヘルパー関数整備

[hiragram]

ADR-001: 重複コード解消のためのヘルパー関数整備

Status

Proposed

Context

コードレビューにおいて、複数のコマンドファイル（add.js, install.js, remove.js, update.js, list.js）で以下の重複パターンが特定された：

1. ファイルシステム操作の重複: ディレクトリ作成、パス結合、ファイル存在確認
2. 設定ファイル操作の重複: config/lockファイルの読み込み・保存パターン
3. リポジトリパス処理の重複: リポジトリキー解析処理
4. lock-helpers.js使用の不統一: 一部のコマンドで新しいヘルパー関数が未使用

これらの重複により、保守性の低下とコードの一貫性の欠如が発生している。

Decision

重複コードを解消するため、以下の方針で共通ヘルパー関数を整備する：

1. 新規ファイルの作成

• src/utils/command-helpers.js: コマンド共通処理のヘルパー関数群
• tests/utils/command-helpers.test.js: 対応するテストファイル

2. 既存ファイルの拡張

• src/utils/filesystem.js: ファイルシステム操作関数の追加
• src/types/index.d.ts: 型定義の追加

3. 主要なヘルパー関数

• setupCommandEnvironment(isLocal): 設定ファイル一括読み込み
• createRepositoryPaths(commandsDir, user, repo): リポジトリパス情報作成
• saveCommandEnvironment(env, isLocal): 設定ファイル一括保存
• parseRepositoryKey(repoKey): リポジトリキー解析の統一
• createCommandFilePath(targetDir, fileName): コマンドファイルパス生成

機能要件

FR1: ファイルシステム操作の統一化

• 目的: 複数のコマンドで重複するファイルシステム操作を共通化
• 制約: 既存APIの互換性を維持

FR2: 設定ファイル操作の統一化

• 目的: 設定ファイルの読み込み・保存パターンを共通化
• 制約: 既存のconfig.jsの関数との互換性を維持

FR3: リポジトリパス処理の統一化

• 目的: リポジトリキーの解析処理を統一
• 制約: 既存のparseRepositoryPath関数との互換性を維持

FR4: lock-helpers.js使用の統一化

• 目的: 全コマンドでlock-helpers.jsの関数を使用
• 対象: add.js, update.js, list.js

FR5: 包括的なテストカバレッジ

• 目的: 新しいヘルパー関数の品質保証
• 要件: ユニットテスト、エッジケーステスト、既存テスト更新

基本設計

モジュール構成

command-helpers.js
├── config.js (既存)
├── filesystem.js (拡張)
├── lock-helpers.js (既存)
└── 各コマンドファイル (add.js, install.js, etc.)

型定義

interface CommandEnvironment {
  config: CccscConfig;
  lock: CccscLock;
  commandsDir: string;
}

interface RepositoryPathInfo {
  user: string;
  repo: string;
  repoKey: string;
  targetDir: string;
}

詳細設計

技術選定

• JavaScript (ES6+): 既存コードベースとの統一
• fs-extra: 既存ファイルシステム操作との統一
• Vitest: 既存テストフレームワークとの統一

インターフェース設計

各ヘルパー関数は純粋関数として設計し、副作用を最小限に抑制。エラーハンドリングは適切な例外スローにより実現。

ユニットテスト方針

• 各ヘルパー関数に対する包括的なテスト
• エッジケース（無効な入力、ファイルシステムエラー）のテスト
• 既存テストの更新とモック対象の調整

移行計画

1. Phase 1: ヘルパー関数の実装とテスト
2. Phase 2: add.jsの移行
3. Phase 3: install.js, remove.js, update.jsの移行
4. Phase 4: list.jsの移行とlock-helpers.js統合

Consequences

正の影響

• 保守性向上: 重複コードの削減により、変更の影響範囲が明確化
• 一貫性確保: 統一されたAPIにより、コードの読みやすさが向上
• テスタビリティ向上: 共通関数の独立したテストが可能

負の影響

• 初期実装コスト: 新しいヘルパー関数の実装と既存コードの移行
• 学習コスト: 開発者が新しいAPIを習得する必要

リスク

• 移行時の回帰: 既存機能の動作変更のリスク（包括的なテストで軽減）
• 複雑性の増加: 抽象化レイヤーの追加（明確なインターフェース設計で軽減）

実装チェックリスト

• src/utils/command-helpers.jsの実装
• src/utils/filesystem.jsの拡張
• src/types/index.d.tsの型定義追加
• tests/utils/command-helpers.test.jsの実装
• tests/utils/filesystem.test.jsの更新
• add.jsの移行
• install.jsの移行
• remove.jsの移行
• update.jsの移行
• list.jsの移行とlock-helpers.js統合
• 既存テストの更新
• 統合テストの実行
• パフォーマンス確認