# 機能設計書 96-Incプラグイン

## 概要

本ドキュメントはNushellのIncプラグイン（nu_plugin_inc）について記述する。数値やバージョン文字列をインクリメントするプラグインの設計を定義する。

### 本機能の処理概要

Incプラグインは、数値または意味論的バージョン（Semantic Version）文字列をインクリメントする機能を提供する。整数値の場合は単純に1を加算し、セマンティックバージョン文字列の場合はメジャー・マイナー・パッチのいずれかを指定してインクリメントできる。

**業務上の目的・背景**：ソフトウェア開発において、バージョン番号の更新は頻繁に行われる作業である。特にリリース作業やCI/CDパイプラインにおいて、セマンティックバージョニングに従ったバージョン番号の自動更新が必要となる。Incプラグインはこのような作業を自動化し、一貫性のあるバージョン管理を支援する。

**機能の利用シーン**：
- リリース時のバージョン番号更新
- CI/CDパイプラインでの自動バージョニング
- Cargo.tomlやpackage.jsonのバージョンフィールド更新
- 連番カウンターのインクリメント
- テーブルデータ内の特定カラムの値インクリメント

**主要な処理内容**：
1. 入力値の型判定（整数または文字列）
2. セマンティックバージョンパース（文字列の場合）
3. 指定されたアクション（Major/Minor/Patch）に基づくインクリメント
4. cell_path指定時のネストされた値の更新

**関連システム・外部連携**：semverクレート（セマンティックバージョニング処理）

**権限による制御**：特になし。入力データの変換処理のみ。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はCLIコマンドとして提供され、特定の画面とは関連しない |

## 機能種別

データ変換 / 数値操作 / バージョン管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| cell_path | CellPath | No | 更新対象のセルパス | 有効なセルパス |
| --major, -M | Switch | No | メジャーバージョンをインクリメント | - |
| --minor, -m | Switch | No | マイナーバージョンをインクリメント | - |
| --patch, -p | Switch | No | パッチバージョンをインクリメント | - |

### 入力データソース

- パイプライン入力: 整数値、数値文字列、またはセマンティックバージョン文字列
- テーブル/レコードとcell_pathの組み合わせ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | Int/String | インクリメント後の値。整数入力は整数、文字列入力は文字列で返却 |

### 出力先

- パイプライン出力

## 処理フロー

### 処理シーケンス

```
inc:
1. オプション解析
   ├─ cell_path取得（オプション）
   ├─ --major フラグ確認
   ├─ --minor フラグ確認
   └─ --patch フラグ確認
2. アクション決定
   └─ フラグに応じてSemVerAction設定
3. 値のインクリメント
   ├─ cell_path指定あり → ネスト値を取得・更新
   └─ cell_path指定なし → 直接値を処理
4. 型別処理
   ├─ Int → val + 1
   ├─ String（セマンティックバージョン） → バージョンインクリメント
   └─ String（数値文字列） → パースして +1
5. 結果返却
```

### フローチャート

```mermaid
flowchart TD
    A[inc] --> B[オプション解析]
    B --> C{cell_path指定?}
    C -->|Yes| D[cell_pathで値取得]
    C -->|No| E[入力値をそのまま使用]
    D --> F{値の型判定}
    E --> F
    F -->|Int| G[val + 1]
    F -->|String| H{SemVerアクション?}
    H -->|Yes| I[semver::Version::parse]
    H -->|No| J[数値としてパース]
    I --> K{パース成功?}
    K -->|Yes| L[バージョンインクリメント]
    K -->|No| M[元の文字列を返却]
    L --> N[Major/Minor/Patchに応じた処理]
    J --> O{数値パース成功?}
    O -->|Yes| P[val + 1]
    O -->|No| M
    G --> Q[結果返却]
    N --> Q
    P --> Q
    M --> Q
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-96-01 | 単一アクション | Major/Minor/Patchのいずれか1つのみ指定可能 | 複数フラグ指定時はエラー |
| BR-96-02 | メジャーインクリメント | major +1、minor=0、patch=0、pre/build=空 | --majorフラグ |
| BR-96-03 | マイナーインクリメント | minor +1、patch=0、pre/build=空 | --minorフラグ |
| BR-96-04 | パッチインクリメント | patch +1、pre/build=空 | --patchフラグ |
| BR-96-05 | デフォルト動作 | フラグなしの場合は数値として+1 | フラグ未指定 |

### 計算ロジック

**セマンティックバージョンのインクリメントルール**:

```
Major: 1.2.3 → 2.0.0
  - major += 1
  - minor = 0
  - patch = 0
  - pre = EMPTY
  - build = EMPTY

Minor: 1.2.3 → 1.3.0
  - minor += 1
  - patch = 0
  - pre = EMPTY
  - build = EMPTY

Patch: 1.2.3 → 1.2.4
  - patch += 1
  - pre = EMPTY
  - build = EMPTY
```

**プレリリース・ビルドメタデータの扱い**:
- インクリメント時にプレリリース識別子（-alpha, -beta等）はクリア
- インクリメント時にビルドメタデータ（+build.123等）もクリア
- 例: `1.2.3-beta+build.456 --patch` → `1.2.4`

## データベース操作仕様

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| can only apply one | 内部エラー | 複数のSemVerアクションを指定 | 1つのアクションのみ指定 |
| Unable to extract string | LabeledError | 文字列に変換できない型 | 整数または文字列を入力 |
| Incorrect value | LabeledError | 不正な値 | 有効な数値またはバージョン文字列を入力 |

### リトライ仕様

特になし。

## トランザクション仕様

該当なし（読み取り/変換処理のみ）。

## パフォーマンス要件

- 即座に処理実行
- semverパースは軽量な処理

## セキュリティ考慮事項

- 入力値のバリデーションによる不正入力防止
- 外部リソースへのアクセスなし

## 備考

- semverクレートはRustの標準的なセマンティックバージョニングライブラリ
- SemVer 2.0.0仕様に準拠
- パース失敗時は元の文字列をそのまま返却（エラーにはならない）

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

Inc構造体とアクションの定義を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | inc.rs | `crates/nu_plugin_inc/src/inc.rs` | Action/SemVerAction列挙型（4-15行目） |
| 1-2 | inc.rs | `crates/nu_plugin_inc/src/inc.rs` | Inc構造体の定義（17-22行目） |

**読解のコツ**: Actionは`SemVerAction(SemVerAction)`と`Default`の2種類。SemVerActionはMajor/Minor/Patchの3種類。Inc構造体はerror、cell_path、actionの3フィールドを持つ。

#### Step 2: プラグインコマンドを理解する

プラグインの登録とコマンド定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | nu/mod.rs | `crates/nu_plugin_inc/src/nu/mod.rs` | IncPluginの定義（5-15行目） |
| 2-2 | nu/mod.rs | `crates/nu_plugin_inc/src/nu/mod.rs` | signatureでのパラメータ定義（28-46行目） |
| 2-3 | nu/mod.rs | `crates/nu_plugin_inc/src/nu/mod.rs` | runメソッドの実装（48-72行目） |

**主要処理フロー（nu/mod.rs）**:
1. **57行目**: cell_pathオプションの取得
2. **61-69行目**: フラグに応じてSemVerActionを設定
3. **71行目**: inc.inc()を呼び出して処理実行

#### Step 3: インクリメント処理を理解する

実際のインクリメントロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | inc.rs | `crates/nu_plugin_inc/src/inc.rs` | incメソッド（92-104行目） |
| 3-2 | inc.rs | `crates/nu_plugin_inc/src/inc.rs` | inc_valueメソッド（106-121行目） |
| 3-3 | inc.rs | `crates/nu_plugin_inc/src/inc.rs` | applyメソッド（29-53行目） |

**主要処理フロー（inc.rs）**:
1. **92-104行目**: cell_path指定時はネスト値を取得して更新
2. **106-121行目**: 型に応じた処理分岐（Int, String）
3. **29-53行目**: 文字列の場合のセマンティックバージョン処理

#### Step 4: バージョンインクリメント関数を理解する

各バージョンコンポーネントのインクリメント実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | inc.rs | `crates/nu_plugin_inc/src/inc.rs` | increment_patch（55-59行目） |
| 4-2 | inc.rs | `crates/nu_plugin_inc/src/inc.rs` | increment_minor（61-66行目） |
| 4-3 | inc.rs | `crates/nu_plugin_inc/src/inc.rs` | increment_major（68-74行目） |

### プログラム呼び出し階層図

```
IncPlugin::run()
    │
    └─ Inc::inc()
           │
           ├─ cell_path処理（指定時）
           │      ├─ value.follow_cell_path()
           │      │      └─ ネスト値の取得
           │      └─ value.update_data_at_cell_path()
           │             └─ 更新後の値を設定
           │
           └─ Inc::inc_value()
                  │
                  ├─ Int型
                  │      └─ val + 1
                  │
                  └─ String型
                         └─ Inc::apply()
                                │
                                ├─ SemVerAction指定時
                                │      ├─ semver::Version::parse()
                                │      └─ increment_major/minor/patch()
                                │
                                └─ Default
                                       └─ 数値パースして +1
```

### データフロー図

```
[入力]                    [処理]                         [出力]

Int値      ─────────▶   val + 1           ─────────▶   Int (val + 1)

String値   ─────────▶   apply()           ─────────▶   String
("1.2.3")               │
                        ├─ --major
                        │      └─ increment_major()
                        │             └─ "2.0.0"
                        ├─ --minor
                        │      └─ increment_minor()
                        │             └─ "1.3.0"
                        └─ --patch
                               └─ increment_patch()
                                      └─ "1.2.4"

Record     ─────────▶   follow_cell_path  ─────────▶   更新済みRecord
+ cell_path             └─ inc_value()
                        └─ update_data_at_cell_path()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| lib.rs | `crates/nu_plugin_inc/src/lib.rs` | ソース | モジュールエクスポート |
| inc.rs | `crates/nu_plugin_inc/src/inc.rs` | ソース | Inc構造体とインクリメントロジック |
| nu/mod.rs | `crates/nu_plugin_inc/src/nu/mod.rs` | ソース | プラグインコマンド定義 |
| main.rs | `crates/nu_plugin_inc/src/main.rs` | ソース | プラグインエントリーポイント |
