# アーキテクチャ設計書

## 概要

本ドキュメントは、Nushell（Nu）プロジェクトのアーキテクチャ設計を記述したものである。NushellはRustで実装された新しいタイプのシェルであり、従来のテキストベースのシェルとは異なり、構造化データ（テーブル、レコード、リスト等）をネイティブにサポートするパイプライン指向の設計を採用している。

## システム全体構成

### アーキテクチャ概要図

[アーキテクチャ構成図.md](./アーキテクチャ構成図.md) を参照

### システム境界と外部連携

| 外部システム | 連携方式 | 用途 |
| --- | --- | --- |
| プラグイン（外部バイナリ） | JSON-RPC over stdin/stdout（MessagePack/JSON） | シェル機能の拡張、カスタムコマンドの追加 |
| 外部コマンド（OS標準コマンド） | プロセス間通信（stdin/stdout/stderr） | システムコマンドの実行 |
| Language Server Protocol (LSP) | JSON-RPC over stdio | IDEとの統合（補完、定義ジャンプ等） |
| Model Context Protocol (MCP) | HTTP/stdio | AIモデルとの連携 |
| ファイルシステム | OS API | ファイル操作、設定ファイル読み込み |
| ネットワーク | HTTP/HTTPS（ureq/rustls） | Web APIアクセス、ファイルダウンロード |
| SQLite | rusqlite | 履歴管理、キーバリューストア |

## レイヤー構成

### アーキテクチャスタイル

Nushellはモジュラーモノリスアーキテクチャを採用しており、複数のRust crateに機能が分割されている。各crateは明確な責務を持ち、依存関係は一方向に制御されている。設計思想としてはパイプライン指向アーキテクチャを基盤とし、関数型プログラミングの原則（イミュータブルデータ、パイプラインによる変換）を取り入れている。

### レイヤー定義

| レイヤー | 責務 | 主なコンポーネント |
| --- | --- | --- |
| Presentation（CLI層） | ユーザーインターフェース、REPL、コマンドライン引数解析 | `src/main.rs`, `nu-cli`, `nu-explore` |
| Application（エンジン層） | コマンド実行、式評価、環境管理 | `nu-engine`, `nu-cmd-lang`, `nu-cmd-base` |
| Domain（プロトコル層） | AST、型システム、値、シグネチャ、パイプライン | `nu-protocol`, `nu-parser` |
| Infrastructure（コマンド実装層） | 具体的なコマンド実装、外部システム連携 | `nu-command`, `nu-cmd-extra`, `nu-std` |
| Plugin（拡張層） | プラグインプロトコル、プラグインランタイム | `nu-plugin`, `nu-plugin-engine`, `nu-plugin-protocol` |

### レイヤー間の依存関係ルール

```
Presentation (nu-cli, src/main.rs)
      |
      v
Application (nu-engine)
      |
      v
Domain (nu-protocol, nu-parser)
      ^
      |
Infrastructure (nu-command, nu-std)
      |
      v
Plugin (nu-plugin, nu-plugin-engine)
```

**依存ルール：**
- 上位レイヤーは下位レイヤーに依存可能
- 下位レイヤーは上位レイヤーに依存しない
- `nu-protocol`は最も基底のcrateであり、他のすべてのcrateが依存する
- コマンド実装層（`nu-command`）はプロトコル層のトレイトを実装するが、エンジン層には直接依存しない

## モジュール構成

### ドメイン分割

| ドメイン | 責務 | 関連モジュール |
| --- | --- | --- |
| コア言語 | パイプライン、式、型、値の定義 | `nu-protocol`, `nu-parser` |
| コマンド実行 | 式評価、ブロック実行、環境変数 | `nu-engine` |
| 組み込みコマンド | フィルター、変換、I/O、システム操作 | `nu-command`, `nu-cmd-extra` |
| 言語コマンド | 制御構文、変数、関数定義 | `nu-cmd-lang` |
| CLI | REPL、補完、シンタックスハイライト | `nu-cli` |
| 標準ライブラリ | Nushellスクリプトによる標準機能 | `nu-std` |
| プラグイン | 外部プラグイン連携プロトコル | `nu-plugin`, `nu-plugin-engine`, `nu-plugin-protocol` |
| ユーティリティ | パス操作、JSON、テーブル表示 | `nu-utils`, `nu-path`, `nu-json`, `nu-table` |
| 開発支援 | LSP、テストサポート | `nu-lsp`, `nu-test-support` |

### パッケージ構造

```
nushell/
├── src/                          # メインバイナリ（nu）
│   ├── main.rs                   # エントリーポイント
│   ├── command.rs                # CLI引数解析
│   ├── config_files.rs           # 設定ファイル処理
│   ├── run.rs                    # 実行モード分岐
│   └── ...
├── crates/                       # Rustワークスペースcrates
│   ├── nu-protocol/              # コアプロトコル（AST、型、値）
│   │   └── src/
│   │       ├── ast/              # 抽象構文木
│   │       ├── config/           # 設定構造体
│   │       ├── engine/           # エンジン状態、スタック
│   │       ├── errors/           # エラー型定義
│   │       ├── pipeline/         # パイプラインデータ
│   │       ├── value/            # Value型定義
│   │       └── ...
│   ├── nu-parser/                # パーサー
│   │   └── src/
│   │       ├── lex.rs            # レキサー
│   │       ├── parser.rs         # パーサー本体
│   │       ├── parse_keywords.rs # キーワード解析
│   │       └── ...
│   ├── nu-engine/                # 実行エンジン
│   │   └── src/
│   │       ├── eval.rs           # 式評価
│   │       ├── eval_ir.rs        # IR評価
│   │       ├── compile.rs        # IRコンパイル
│   │       └── ...
│   ├── nu-cli/                   # CLIインターフェース
│   │   └── src/
│   │       ├── repl.rs           # REPLループ
│   │       ├── completions/      # 補完機能
│   │       └── ...
│   ├── nu-command/               # 組み込みコマンド
│   │   └── src/
│   │       ├── filters/          # フィルターコマンド（where, select等）
│   │       ├── filesystem/       # ファイル操作コマンド
│   │       ├── strings/          # 文字列操作コマンド
│   │       ├── network/          # ネットワークコマンド
│   │       └── ...
│   ├── nu-plugin/                # プラグインSDK
│   ├── nu-plugin-engine/         # プラグインランタイム
│   ├── nu-plugin-protocol/       # プラグインプロトコル定義
│   ├── nu-std/                   # 標準ライブラリ（Nushellスクリプト）
│   │   └── std/
│   │       ├── mod.nu
│   │       ├── assert/
│   │       ├── log/
│   │       └── ...
│   ├── nu-lsp/                   # Language Server Protocol実装
│   └── nu_plugin_*/              # 公式プラグイン群
└── tests/                        # 統合テスト
```

### コンポーネント依存関係

**主要コンポーネント間の依存関係：**

1. **nu-protocol** - 基底crate、すべてのcrateが依存
2. **nu-parser** - `nu-protocol`に依存、ASTを生成
3. **nu-engine** - `nu-protocol`, `nu-parser`に依存、式を評価
4. **nu-command** - `nu-protocol`, `nu-engine`に依存、コマンドを実装
5. **nu-cli** - 上記すべてに依存、REPLを提供
6. **nu-plugin** - `nu-protocol`に依存、プラグインSDKを提供
7. **nu-plugin-engine** - `nu-plugin`, `nu-plugin-protocol`に依存、プラグインを実行

## ミドルウェア構成

### データベース

| 種類 | ミドルウェア | バージョン | 用途 |
| --- | --- | --- | --- |
| RDB | SQLite（rusqlite） | 0.37 | コマンド履歴保存、`stor`コマンドによるキーバリューストア、インメモリDB |

### キャッシュ

| ミドルウェア | バージョン | 用途 | TTL |
| --- | --- | --- | --- |
| LRU Cache（lru crate） | 0.16 | 正規表現キャッシュ | - |
| In-memory | - | パース結果、LSP状態デルタ | セッション中 |

### メッセージキュー

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| 該当なし | - | Nushellは同期処理が主、バックグラウンドジョブはスレッド間チャネルで管理 |

### 検索エンジン

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| 該当なし | - | テキスト検索はfancy-regex、ファジーマッチはnucleo-matcherを使用 |

### その他ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| reedline | 0.46.0 | 行編集エンジン（プロンプト、履歴、補完） |
| crossterm | 0.29.0 | ターミナル制御 |
| miette | 7.6 | エラーレポーティング |
| serde | 1.0 | シリアライゼーション |
| chrono | 0.4.43 | 日時処理 |
| ureq | 3.0.12 | HTTPクライアント |
| rustls | 0.23.28 | TLS暗号化 |

## データフロー

### リクエスト処理の流れ

1. **入力受付**: ユーザーがREPLに入力、またはスクリプトファイルを指定
2. **レキシング**: `nu-parser`のレキサーがトークンに分解
3. **パース**: パーサーがAST（`Block`）を生成
4. **IRコンパイル**: `nu-engine`がASTを中間表現（IR）にコンパイル
5. **評価**: `eval_ir_block`がIRを実行し、`PipelineData`を生成
6. **パイプライン処理**: 各コマンドがパイプライン入力を変換
7. **出力**: 最終結果を`table`コマンド等でフォーマットし表示

```
User Input
    |
    v
Lexer (Token Stream)
    |
    v
Parser (AST/Block)
    |
    v
IR Compiler (IrBlock)
    |
    v
Evaluator (PipelineData)
    |
    v
Command Pipeline (Value transformations)
    |
    v
Output (formatted result)
```

### 非同期処理の流れ

1. **バックグラウンドジョブ**: ユーザーが`&`でコマンドを実行
2. **ジョブ登録**: `Jobs`構造体にジョブを登録
3. **スレッド実行**: 別スレッドでコマンドを実行
4. **完了通知**: `Mailbox`経由でメインスレッドに通知
5. **結果取得**: ユーザーが`fg`コマンドで結果を取得

### データ永続化の流れ

1. **履歴保存**: reedlineが自動的にSQLiteに保存（`history_session_id`で識別）
2. **設定保存**: ユーザーが明示的に`config.nu`を編集
3. **プラグイン登録**: `plugin add`コマンドで`plugin.nu`に記録
4. **storコマンド**: SQLiteにキーバリューデータを保存

## 横断的関心事

### 認証・認可

| 方式 | 実装箇所 | 対象 |
| --- | --- | --- |
| OS権限 | ファイルシステムコマンド | ファイルアクセス権限はOSに委譲 |
| TLS証明書 | `nu-command/network` | HTTPSリクエストの証明書検証 |
| プラグイン署名 | 未実装 | プラグインの信頼性検証（将来検討） |

### ロギング・監査

| 種類 | 実装方式 | 保存先 |
| --- | --- | --- |
| アプリケーションログ | `log`クレート + `simplelog` | stderr、ファイル |
| コマンド履歴 | SQLite | `~/.config/nushell/history.sqlite3` |
| パフォーマンス計測 | `nu-utils::perf!`マクロ | stderr（デバッグ時） |

### エラーハンドリング

| エラー種別 | ハンドリング方式 | レスポンス |
| --- | --- | --- |
| パースエラー | `miette`によるスパン付きエラー | エラー箇所をハイライト表示 |
| 実行時エラー | `ShellError`列挙型 | エラーメッセージ + ヘルプテキスト |
| プラグインエラー | `LabeledError`でシリアライズ | プラグインからのエラーをラップ |
| I/Oエラー | `IoError`ラッパー | ファイルパス + 元エラーを表示 |

### トランザクション管理

| 範囲 | 管理方式 | 分離レベル |
| --- | --- | --- |
| SQLite操作 | rusqliteのトランザクション | デフォルト（DEFERRED） |
| 設定変更 | StateWorkingSet + Delta | スナップショット分離 |

## 設計原則・コーディング規約

### 適用している設計原則

| 原則 | 適用箇所 | 実装例 |
| --- | --- | --- |
| 関数型パイプライン | パイプライン全体 | コマンドは入力を変換して出力、副作用を最小化 |
| 構造化データ | Value型 | すべてのデータは型付き構造（Record, List, Table） |
| Command Pattern | コマンド実装 | `Command`トレイトによる統一インターフェース |
| Plugin Architecture | プラグインシステム | 外部プロセスとのRPC通信による拡張 |
| Single Responsibility | crate分割 | 各crateは単一の責務を持つ |
| Dependency Inversion | `nu-protocol` | 抽象（トレイト）に依存し、具象に依存しない |

### コーディング規約

- **Rust Edition**: 2024
- **最小Rustバージョン**: 1.91.1
- **Clippy設定**: `unchecked_duration_subtraction`, `used_underscore_binding`を警告
- **ドキュメント**: 各crateにREADME.mdを配置
- **テスト**: `rstest`を使用したパラメタライズドテスト
- **フォーマット**: `rustfmt`による自動フォーマット
- **型安全性**: `Value`型は非公開コンストラクタ、コンストラクタメソッド経由でのみ生成

## 備考

### 特徴的な設計判断

1. **イミュータブル中心の設計**: `Value`型はCloneを多用し、変更時は新しい値を生成
2. **Span追跡**: すべての値にソースコード位置情報を保持（エラー表示用）
3. **プラグインの分離**: プラグインは別プロセスで実行、安全性と拡張性を両立
4. **標準ライブラリのNushell実装**: `nu-std`はNushellスクリプトで記述、言語の表現力を示す
5. **IR導入**: ASTの直接評価からIRベースの評価に移行（パフォーマンス向上）

### バージョン情報

- プロジェクトバージョン: 0.111.1
- ライセンス: MIT
