# Validate Piles Notation

> jigsawRのピースフュージョングループを指定するためのPILES（Puzzle Input Line Entry System）記法を解析・検証する。構文検証、グループリストへの解析、 平易な説明、パズル結果に対する隣接検証、ラウンドトリップシリアライズを カバー。generate_puzzle()に渡す前のユーザー提供PILES文字列の検証、 フュージョングループの問題デバッグ、ユーザーへの記法説明、 ラウンドトリップ解析/シリアライズの忠実性テストに使用する。

- Skill: `pjt222/validate-piles-notation-3` (Agent Skill)
- Install (CLI): `npx get-skill add pjt222/validate-piles-notation-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pjt222/validate-piles-notation-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: pjt222 (https://skillmd.com/u/pjt222)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/pjt222/validate-piles-notation-3

---


# PILES記法の検証

パズルピースフュージョングループのためのPILES記法文字列を解析・検証する。

## 使用タイミング

- `generate_puzzle()`に渡す前のユーザー提供PILES文字列の検証
- フュージョングループの問題デバッグ（間違ったピースの結合、予期しない結果）
- ユーザーへのPILES記法の平易な説明
- ラウンドトリップの忠実性テスト: 解析 -> グループ -> シリアライズ -> 解析

## 入力

- **必須**: PILES記法文字列（例: `"1-2-3,4-5"`）
- **任意**: パズル結果オブジェクト（隣接検証とキーワード解決用）
- **任意**: パズルタイプ（`"center"`、`"ring1"`、`"R1"`などのキーワードサポート用）

## 手順

### ステップ1: 構文検証

```r
library(jigsawR)
result <- validate_piles_syntax("1-2-3,4-5")
# Returns TRUE if valid, error message if invalid
```

一般的な構文エラーを確認する:
- 対応しない括弧: `"1-2(-3)-4"` で`()`が不一致
- 無効な文字: 数字、`-`、`,`、`:`、`(`、`)`とキーワードのみ許可
- 空のグループ: `"1-2,,3-4"`（二重カンマ）

**期待結果:** 有効な構文の場合は`TRUE`、無効な場合は説明的なエラー。

**失敗時:** 正確なPILES文字列と検証エラーメッセージを出力する。

### ステップ2: グループへの解析

```r
groups <- parse_piles("1-2-3,4-5")
# Returns: list(c(1, 2, 3), c(4, 5))
```

範囲を含む文字列の場合:
```r
groups <- parse_piles("1:6,7-8")
# Returns: list(c(1, 2, 3, 4, 5, 6), c(7, 8))
```

**期待結果:** 整数ベクトルのリスト（フュージョングループごとに1つ）。正しいピースIDとグループ境界を持つ。

**失敗時:** PILES文字列がステップ1で構文検証を通過しているか最初に確認する。解析が予期しないグループを返す場合、`-`がグループ内のピースを区切り、`,`がグループを区切ること、および範囲記法（`:`）が両端を含む形で展開されることを確認する。

### ステップ3: 平易な言葉での説明

各グループをユーザーに説明する:

- `"1-2-3,4-5"` -> 「グループ1: ピース1、2、3を融合。グループ2: ピース4と5を融合。」
- `"1:6"` -> 「グループ1: ピース1から6を融合（6ピース）。」
- `"center,ring1"` -> 「グループ1: 中心ピース。グループ2: リング1のすべてのピース。」

**期待結果:** 各フュージョングループがピース数と識別子とともに平易な言葉で説明され、非技術的なユーザーにも記法が理解可能になる。

**失敗時:** キーワードが説明できない場合（例: `"ring1"`が明確な意味を持たない）、記法にはコンテキストとしてパズル結果オブジェクトが必要な場合がある。ユーザーにパズルタイプを提供するか、代わりに数値ピースIDを使用するようアドバイスする。

### ステップ4: パズル結果に対する検証（任意）

パズル結果オブジェクトが利用可能な場合、以下を確認する:

```r
# Generate the puzzle first
puzzle <- generate_puzzle(type = "hexagonal", grid = c(3), size = c(200))

# Parse with puzzle context (resolves keywords)
groups <- parse_fusion("center,ring1", puzzle)
```

確認事項:
- すべてのピースIDがパズルに存在する
- キーワードが有効なピースセットに解決される
- 融合されるピースが実際に隣接している（隣接していない場合は警告）

**期待結果:** すべてのピースIDが有効。隣接するピースがクリーンに融合される。

**失敗時:** 無効なピースIDまたは非隣接ペアをリストする。

### ステップ5: ラウンドトリップシリアライズ

解析/シリアライズの忠実性を検証する:

```r
original <- "1-2-3,4-5"
groups <- parse_piles(original)
roundtrip <- to_piles(groups)
# roundtrip should equal original (or canonical equivalent)

groups2 <- parse_piles(roundtrip)
identical(groups, groups2)  # Must be TRUE
```

**期待結果:** ラウンドトリップが同一のグループリストを生成し、`parse_piles()`と`to_piles()`が逆関数であることを確認する。

**失敗時:** ラウンドトリップが異なる場合、シリアライザが記法を正規化しているか確認する（例: ピースIDのソートや範囲を明示的リストへの変換）。`identical(groups, groups2)`が`TRUE`を返す限り、正規化の違いは許容される。

## PILESクイックリファレンス

```text
# 基本構文
"1-2"           # ピース1と2を融合
"1-2-3,4-5"     # 2つのグループ: (1,2,3)と(4,5)
"1:6"           # 範囲: ピース1から6

# キーワード（puzzle_resultが必要）
"center"        # 中心ピース（hex/concentric）
"ring1"         # リング1のすべてのピース
"R1"            # 行1（rectangular）
"boundary"      # すべての境界ピース

# 関数
parse_piles("1-2-3,4-5")                    # PILES文字列を解析
parse_fusion("1-2-3", puzzle)               # フォーマットを自動検出
to_piles(list(c(1,2), c(3,4)))              # PILESに変換
validate_piles_syntax("1-2(-3)-4")          # 構文を検証
```

## バリデーション

- [ ] `validate_piles_syntax()`が有効な文字列に対してTRUEを返す
- [ ] `parse_piles()`が正しいグループリストを返す
- [ ] ラウンドトリップシリアライズがグループを保持する
- [ ] キーワードがパズルコンテキストで正しく解決される
- [ ] 無効な構文が明確なエラーメッセージを生成する

## よくある落とし穴

- **パズルコンテキストなしのキーワード**: `"center"`のようなキーワードにはパズル結果オブジェクトが必要。`parse_piles()`ではなく`parse_fusion()`に渡すこと。
- **1始まりのピース**: ピースIDは0ではなく1から始まる。
- **隣接 vs 非隣接フュージョン**: 非隣接ピースの融合は動作するが、予期しない視覚結果を生じる場合がある。可能な場合は隣接を検証する。
- **範囲記法**: `"1:6"`は両端を含む（1, 2, 3, 4, 5, 6）。

## 関連スキル

- `generate-puzzle` — フュージョングループを使用してパズルを生成する
- `add-puzzle-type` — 新しいタイプにはPILES/フュージョンサポートが必要
- `run-puzzle-tests` — フルスイートでPILES解析をテストする

