feat: enhance game statistics and add perft support in README and codebase

Author: moritzmyrz

README.md

@@ -39,14 +39,30 @@ This project is **not** a top-tier competitive chess engine and does not current
   - full game replay to final position
 - **Per-game summaries and aggregate statistics**
   - player/result/plies summary fields
-  - wins/draws/unresolved totals and average plies
+  - opening move frequencies (White and Black first moves)
+  - castling distribution (kingside, queenside, no castling)
+  - total/average captures, checks, and promotions
+  - average game length by result type
+- **Perft support**
+  - reusable perft API for legal move generation validation
+  - CLI command for quick node-count checks
 - **JSON export**
   - structured JSON for aggregate stats and per-game summaries
 - **CLI workflows**
   - validate PGN files
   - summarize reconstructed games
   - print aggregate stats (text or JSON)
   - inspect FEN positions and legal moves
+  - run perft against startpos or custom FEN
+
+## Correctness and validation
+
+`ply` treats correctness as a core requirement and validates behavior at multiple layers:
+
+- **Move legality validation**: legal move generation is covered by integration tests for baseline positions and special rules like en passant.
+- **Replay validation**: PGN reconstruction resolves SAN against generated legal moves and is exercised with fixture-based tests.
+- **Perft regression checks**: known perft node counts (including start position and tricky reference positions) are tested to catch move-generation regressions.
+- **CLI-level checks**: command integration tests verify that key workflows (`validate`, `stats --json`, `perft`) execute and emit expected output.
 
 ### Current implementation boundaries
 
@@ -68,6 +84,9 @@ ply stats games.pgn --json
 
 # Parse a FEN and list legal moves in coordinate notation
 ply fen "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1" --legal-moves
+
+# Run perft on start position (or pass --fen "<fen>")
+ply perft --depth 3
 ```
 
 You can also run the binary through Cargo during development:
@@ -90,13 +109,34 @@ JSON stats (`ply stats tests/fixtures/sample_games.pgn --json`):
 ```json
 {
   "stats": {
-    "games": 2,
-    "white_wins": 1,
+    "average_captures": 0.5,
+    "average_checks": 0.5,
+    "average_plies": 7.5,
+    "average_plies_black_wins": null,
+    "average_plies_draws": 8.0,
+    "average_plies_unresolved": null,
+    "average_plies_white_wins": 7.0,
+    "average_promotions": 0.0,
+    "black_first_moves": {
+      "d5": 1,
+      "e5": 1
+    },
     "black_wins": 0,
     "draws": 1,
-    "unresolved": 0,
+    "games": 2,
+    "games_with_kingside_castle": 0,
+    "games_with_no_castling": 2,
+    "games_with_queenside_castle": 0,
+    "total_captures": 1,
+    "total_checks": 1,
     "total_plies": 15,
-    "average_plies": 7.5
+    "total_promotions": 0,
+    "unresolved": 0,
+    "white_first_moves": {
+      "d4": 1,
+      "e4": 1
+    },
+    "white_wins": 1
   },
   "games": [
     {
@@ -119,6 +159,15 @@ JSON stats (`ply stats tests/fixtures/sample_games.pgn --json`):
 }
 ```
 
+Perft (`ply perft --depth 3`):
+
+```text
+depth: 3
+nodes: 8902
+elapsed_ms: 24
+nps: 357520
+```
+
 ## Architecture
 
 The repository is organized as a library-first core with a small command-line frontend.
@@ -161,6 +210,7 @@ cargo run -- validate tests/fixtures/sample_games.pgn
 cargo run -- summarize tests/fixtures/sample_games.pgn
 cargo run -- stats tests/fixtures/sample_games.pgn --json
 cargo run -- fen "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1" --legal-moves
+cargo run -- perft --depth 3
 ```
 
 ### Run tests
@@ -192,7 +242,6 @@ cargo bench
 ## Roadmap
 
 - Improve opening metadata extraction and ECO classification support.
-- Add perft tooling for move-generation validation and regression checks.
 - Introduce Zobrist hashing for efficient position keys and caching.
 - Add evaluation/search scaffolding (non-competitive baseline engine components).
 - Provide bindings/WASM targets for browser and polyglot tooling integration.

src/export.rs

@@ -1,3 +1,5 @@
+use std::collections::BTreeMap;
+
 use serde::Serialize;
 
 use crate::board::Color;
@@ -22,6 +24,21 @@ pub struct JsonAggregateStats {
     pub unresolved: usize,
     pub total_plies: usize,
     pub average_plies: f64,
+    pub average_plies_white_wins: Option<f64>,
+    pub average_plies_black_wins: Option<f64>,
+    pub average_plies_draws: Option<f64>,
+    pub average_plies_unresolved: Option<f64>,
+    pub white_first_moves: BTreeMap<String, usize>,
+    pub black_first_moves: BTreeMap<String, usize>,
+    pub games_with_kingside_castle: usize,
+    pub games_with_queenside_castle: usize,
+    pub games_with_no_castling: usize,
+    pub total_captures: usize,
+    pub average_captures: f64,
+    pub total_checks: usize,
+    pub average_checks: f64,
+    pub total_promotions: usize,
+    pub average_promotions: f64,
 }
 
 pub fn to_json_summary(summary: &GameSummary) -> JsonGameSummary {
@@ -44,6 +61,21 @@ pub fn to_json_aggregate(stats: &AggregateStats) -> JsonAggregateStats {
         unresolved: stats.unresolved,
         total_plies: stats.total_plies,
         average_plies: stats.average_plies,
+        average_plies_white_wins: stats.average_plies_white_wins,
+        average_plies_black_wins: stats.average_plies_black_wins,
+        average_plies_draws: stats.average_plies_draws,
+        average_plies_unresolved: stats.average_plies_unresolved,
+        white_first_moves: stats.white_first_moves.clone(),
+        black_first_moves: stats.black_first_moves.clone(),
+        games_with_kingside_castle: stats.games_with_kingside_castle,
+        games_with_queenside_castle: stats.games_with_queenside_castle,
+        games_with_no_castling: stats.games_with_no_castling,
+        total_captures: stats.total_captures,
+        average_captures: stats.average_captures,
+        total_checks: stats.total_checks,
+        average_checks: stats.average_checks,
+        total_promotions: stats.total_promotions,
+        average_promotions: stats.average_promotions,
     }
 }
 

src/lib.rs

@@ -2,5 +2,6 @@ pub mod board;
 pub mod export;
 pub mod fen;
 pub mod movegen;
+pub mod perft;
 pub mod pgn;
 pub mod stats;

src/main.rs

@@ -1,12 +1,14 @@
 use std::fs;
 use std::path::PathBuf;
+use std::time::Instant;
 
 use clap::{Parser, Subcommand};
 use ply::export::{to_json_aggregate, to_json_summary};
-use ply::fen::{parse_fen, to_fen};
+use ply::fen::{parse_fen, to_fen, STARTPOS_FEN};
 use ply::movegen::generate_legal_moves;
+use ply::perft::perft;
 use ply::pgn::{parse_pgn, reconstruct_game};
-use ply::stats::{aggregate_stats, summarize_game, summarize_games};
+use ply::stats::{aggregate_record_stats, summarize_game, summarize_games};
 
 #[derive(Parser, Debug)]
 #[command(name = "ply")]
@@ -34,6 +36,12 @@ enum Commands {
         #[arg(long)]
         legal_moves: bool,
     },
+    Perft {
+        #[arg(long)]
+        fen: Option<String>,
+        #[arg(long)]
+        depth: u8,
+    },
 }
 
 fn main() {
@@ -43,6 +51,7 @@ fn main() {
         Commands::Summarize { file } => cmd_summarize(&file),
         Commands::Stats { file, json } => cmd_stats(&file, json),
         Commands::Fen { fen, legal_moves } => cmd_fen(&fen, legal_moves),
+        Commands::Perft { fen, depth } => cmd_perft(fen.as_deref(), depth),
     };
     if let Err(err) = result {
         eprintln!("error: {err}");
@@ -96,7 +105,7 @@ fn cmd_stats(file: &PathBuf, json: bool) -> Result<(), String> {
     let games = parse_pgn(&content).map_err(|e| format!("{e:?}"))?;
     let records = games.iter().filter_map(|g| reconstruct_game(g).ok()).collect::<Vec<_>>();
     let summaries = summarize_games(&records);
-    let stats = aggregate_stats(&summaries);
+    let stats = aggregate_record_stats(&records);
     if json {
         let payload = serde_json::json!({
             "stats": to_json_aggregate(&stats),
@@ -108,12 +117,41 @@ fn cmd_stats(file: &PathBuf, json: bool) -> Result<(), String> {
         );
     } else {
         println!("games: {}", stats.games);
-        println!("white_wins: {}", stats.white_wins);
-        println!("black_wins: {}", stats.black_wins);
-        println!("draws: {}", stats.draws);
-        println!("unresolved: {}", stats.unresolved);
-        println!("total_plies: {}", stats.total_plies);
-        println!("average_plies: {:.2}", stats.average_plies);
+        println!("results:");
+        println!("  white_wins: {}", stats.white_wins);
+        println!("  black_wins: {}", stats.black_wins);
+        println!("  draws: {}", stats.draws);
+        println!("  unresolved: {}", stats.unresolved);
+
+        println!("length:");
+        println!("  total_plies: {}", stats.total_plies);
+        println!("  average_plies: {:.2}", stats.average_plies);
+        println!("  average_plies_white_wins: {}", format_optional(stats.average_plies_white_wins));
+        println!("  average_plies_black_wins: {}", format_optional(stats.average_plies_black_wins));
+        println!("  average_plies_draws: {}", format_optional(stats.average_plies_draws));
+        println!("  average_plies_unresolved: {}", format_optional(stats.average_plies_unresolved));
+
+        println!("first_moves_white:");
+        for (mv, count) in &stats.white_first_moves {
+            println!("  {mv}: {count}");
+        }
+        println!("first_moves_black:");
+        for (mv, count) in &stats.black_first_moves {
+            println!("  {mv}: {count}");
+        }
+
+        println!("castling:");
+        println!("  games_with_kingside_castle: {}", stats.games_with_kingside_castle);
+        println!("  games_with_queenside_castle: {}", stats.games_with_queenside_castle);
+        println!("  games_with_no_castling: {}", stats.games_with_no_castling);
+
+        println!("move_events:");
+        println!("  total_captures: {}", stats.total_captures);
+        println!("  average_captures: {:.2}", stats.average_captures);
+        println!("  total_checks: {}", stats.total_checks);
+        println!("  average_checks: {:.2}", stats.average_checks);
+        println!("  total_promotions: {}", stats.total_promotions);
+        println!("  average_promotions: {:.2}", stats.average_promotions);
     }
     Ok(())
 }
@@ -131,3 +169,24 @@ fn cmd_fen(fen: &str, legal_moves: bool) -> Result<(), String> {
     }
     Ok(())
 }
+
+fn cmd_perft(fen: Option<&str>, depth: u8) -> Result<(), String> {
+    let fen = fen.unwrap_or(STARTPOS_FEN);
+    let position = parse_fen(fen).map_err(|e| format!("{e:?}"))?;
+
+    let started = Instant::now();
+    let nodes = perft(&position, depth);
+    let elapsed = started.elapsed();
+    let secs = elapsed.as_secs_f64();
+    let nps = if secs > 0.0 { (nodes as f64 / secs) as u64 } else { 0 };
+
+    println!("depth: {depth}");
+    println!("nodes: {nodes}");
+    println!("elapsed_ms: {}", elapsed.as_millis());
+    println!("nps: {nps}");
+    Ok(())
+}
+
+fn format_optional(value: Option<f64>) -> String {
+    value.map(|v| format!("{v:.2}")).unwrap_or_else(|| "-".to_string())
+}

src/perft.rs

@@ -0,0 +1,21 @@
+use crate::board::Position;
+use crate::movegen::{apply_move, generate_legal_moves};
+
+pub fn perft(position: &Position, depth: u8) -> u64 {
+    if depth == 0 {
+        return 1;
+    }
+
+    let legal_moves = generate_legal_moves(position);
+    if depth == 1 {
+        return legal_moves.len() as u64;
+    }
+
+    let mut nodes = 0u64;
+    for mv in legal_moves {
+        let mut next = position.clone();
+        apply_move(&mut next, mv);
+        nodes += perft(&next, depth - 1);
+    }
+    nodes
+}