JA Architecture Technology Stack - aku11i/phantom GitHub Wiki

テクノロジースタック

English | 日本語

このドキュメントでは、Phantomで使用されている言語、フレームワーク、ツール、テクノロジーについて詳しく説明します。

コアテクノロジー

言語とランタイム

TypeScript

ソース: package.json#L48

バージョン: 5.8.0-dev（ネイティブプレビュー機能を使用）
ターゲット: ES2023
モジュールシステム: ESモジュール（ESM）
型チェック: Strictモード有効

使用している主なTypeScript機能：

厳密なnullチェック
型推論
Resultパターン用のユニオン型
テスト用のモジュール拡張

Node.js

ソース: package.json#L36

最小バージョン: v22.0.0
使用機能:
- ネイティブESモジュール
- 組み込みテストランナー
- ネイティブモジュールモッキング
- 子プロセス管理

ランタイム依存関係ゼロ

ソース: package.json#L50

Phantomにはランタイム依存関係がありません。これにより以下が実現されます：

より高速なインストール
より小さなパッケージサイズ
より良いセキュリティ態勢
簡素化されたデプロイメント

ビルドツール

esbuild

ソース: build.ts

目的: 高速JavaScript/TypeScriptバンドラー
バージョン: 0.24.2
用途: CLI実行可能ファイルのビルド

ビルド設定：

{
  bundle: true,
  minify: false,  // デバッグ用に読みやすく保つ
  platform: "node",
  target: "node22",
  format: "esm",
  sourcemap: true
}

TypeScript Native Preview

ソース: package.json#L46

パッケージ: @typescript/native-preview
目的: 実験的なTypeScript機能へのアクセス
利点: 最新の言語機能とパフォーマンス改善

コード品質ツール

Biome

ソース: biome.json

バージョン: 1.9.4
目的: 高速フォーマッターとリンター
置き換え: ESLint + Prettier

設定のハイライト：

{
  "formatter": {
    "indentStyle": "tab",
    "lineWidth": 100,
    "quoteStyle": "double"
  },
  "linter": {
    "rules": {
      "recommended": true,
      "noPrototypeBuiltins": "off",
      "noUselessElse": "off"
    }
  }
}

従来のツールに対する利点：

ESLintより10-20倍高速
フォーマットとリンティングの単一ツール
パフォーマンスのためRustで記述
優れたTypeScriptサポート

パッケージ管理

pnpm

ソース: package.json#L37

バージョン: 10.8.1以上
目的: 高速でディスクスペース効率的なパッケージマネージャー

利点：

効率的な依存関係ストレージ
厳密な依存関係解決
より高速なインストール
より良いモノレポサポート

開発依存関係

型定義

ソース: package.json#L45

@types/node: v22.10.2
- Node.js API型定義
- TypeScript IntelliSenseを有効化

テストツール

組み込みNode.jsテストランナー：

外部テストフレームワークなし
ネイティブモジュールモッキング
組み込みアサーション
並列テスト実行

バージョン管理とコラボレーション

Git

バージョン: 2.5.0+（worktreeサポート用）
用途: コア機能はGit CLIに依存
使用機能:
- Worktree管理
- ブランチ操作
- リポジトリ情報

GitHub

課題追跡: GitHub Issues
コードレビュー: GitHub Pull Requests
CI/CD: GitHub Actions
パッケージレジストリ: GitHub経由のnpm

CI/CDパイプライン

GitHub Actions

ソース: .github/workflows/

ワークフロー設定：

Node.jsバージョン: v22、v24
オペレーティングシステム: Linux、macOS、Windows
品質チェック:
- リンティング（Biome）
- 型チェック（TypeScript）
- ユニットテスト（Node.jsテストランナー）

アーキテクチャパターン

関数型プログラミング

エラーハンドリング用のResult型
可能な限り純粋関数
不変データ構造
関数合成

オブジェクト指向設計

SOLID原則
モジュールごとの単一責任
依存性注入パターン
インターフェース分離

使用されているデザインパターン

Resultパターン: 明示的なエラーハンドリング
Builderパターン: コマンド構築
Strategyパターン: コマンドハンドラー
Facadeパターン: Git操作ラッパー

ファイルシステム構造

モジュール編成

src/
├── bin/              # エントリーポイント（ESM）
├── cli/              # CLIレイヤー
│   ├── handlers/     # コマンド実装
│   └── output.ts     # 出力フォーマット
└── core/             # ビジネスロジック
    ├── worktree/     # Worktree操作
    ├── git/          # Git抽象化
    ├── process/      # プロセス管理
    └── types/        # 型定義

ビルド出力

dist/
├── phantom.js        # メイン実行可能ファイル
└── phantom.js.map    # ソースマップ

パフォーマンス特性

起動パフォーマンス

コールドスタート: ~50ms
要因:
- 依存関係ゼロ
- バンドルされた実行可能ファイル
- 最小限の初期化

メモリ使用量

基本メモリ: ~30MB
スケーラビリティ: worktree数に対して線形
バックグラウンドプロセスなし: アイドル時メモリゼロ

ビルドパフォーマンス

フルビルド: <1秒（esbuild）
型チェック: ~2秒
テストスイート: ~1秒

セキュリティに関する考慮事項

入力検証

コマンド引数のサニタイズ
パストラバーサル防止
シェルインジェクション保護

プロセス分離

制御された環境変数
明示的なシェル呼び出し
evalや動的実行なし

依存関係のセキュリティ

ランタイム依存関係ゼロ = 最小限の攻撃面
開発依存関係は定期的に更新
CIパイプラインでnpm audit

プラットフォームサポート

オペレーティングシステム

macOS: フルサポート
Linux: フルサポート
Windows: フルサポート（Git Bash使用）

シェルサポート

bash: プライマリサポート
zsh: 完全互換性
fish: 完全互換性
PowerShell: 基本的な互換性

将来のテクノロジーに関する考慮事項

潜在的な追加機能

設定管理
- 設定ファイル用のTOML/YAML
- 環境変数サポート
プラグインシステム
- 動的モジュールローディング
- 拡張用API
パフォーマンス監視
- OpenTelemetry統合
- メトリクス収集
追加言語サポート
- パフォーマンスクリティカルな部分にRust
- プラグイン用WebAssembly

テクノロジー原則

依存関係を最小限に: すべての依存関係は負債
パフォーマンス優先: 高速なツールを選択
開発者体験: 優れたツーリング
型安全性: TypeScriptを最大限活用
モダン標準: 最新の安定機能を使用

代替案との比較

vs. Git Worktree直接使用

機能	Git Worktree	Phantom
学習曲線	急	緩やか
コマンド	複雑	シンプル
命名	パス	名前
統合	手動	自動化

vs. Git Clone

側面	Git Clone	Phantom
ディスク使用量	高	低
セットアップ時間	遅い	高速
共有履歴	なし	あり
コンテキスト切り替え	手動	即座

まとめ

Phantomのテクノロジースタックは以下を提供するよう慎重に選択されています：

パフォーマンス: 高速実行と最小限のオーバーヘッド
信頼性: 型安全性と包括的なテスト
シンプルさ: ランタイム依存関係ゼロ
開発者体験: モダンなツーリングとプラクティス
保守性: クリーンなアーキテクチャとコード品質

TypeScript、Node.js、モダンなビルドツールの組み合わせにより、Gitワークフローの生産性を向上させる堅牢で高性能なCLIツールが作成されます。