pgn2 1.4.0 → 2.0.0

data/ext/pgn2_native/Cargo.lock

@@ -0,0 +1,321 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "anyhow"
+version = "1.0.104"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
+
+[[package]]
+name = "arrayvec"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3fb67a6e08acf24fdeccbac2cb6ac4305825bd1f117462e0e6f2f193345ad56"
+
+[[package]]
+name = "bindgen"
+version = "0.72.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "993776b509cfb49c750f11b8f07a46fa23e0a1386ffc01fb1e7d343efc387895"
+dependencies = [
+ "bitflags",
+ "cexpr",
+ "clang-sys",
+ "itertools",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "rustc-hash",
+ "shlex",
+ "syn",
+]
+
+[[package]]
+name = "bitflags"
+version = "2.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+
+[[package]]
+name = "cexpr"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
+dependencies = [
+ "nom",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "chessie"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "69f7ee9c07973fe2b0afe17de4ae2e1158aede0912d254a3be2d3a3b26386d23"
+dependencies = [
+ "anyhow",
+ "arrayvec",
+ "chessie_types",
+]
+
+[[package]]
+name = "chessie_types"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccab5c6928f8d27e6133280700b6a76e4e5d23353e8e1864a9a99c0f91efbb31"
+dependencies = [
+ "anyhow",
+]
+
+[[package]]
+name = "clang-sys"
+version = "1.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "157a8ba7b480713b56f4c09fd13fc3e0a22a5dfab8097ba61cbc5feef950788a"
+dependencies = [
+ "glob",
+ "libc",
+ "libloading",
+]
+
+[[package]]
+name = "either"
+version = "1.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9e5e8f6c15a24b9a3ee5efec809ccd006d3b30e8b3bb63c39af737c7f87daa1d"
+
+[[package]]
+name = "glob"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
+
+[[package]]
+name = "itertools"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
+dependencies = [
+ "either",
+]
+
+[[package]]
+name = "lazy_static"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
+
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "libloading"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
+dependencies = [
+ "cfg-if",
+ "windows-link",
+]
+
+[[package]]
+name = "magnus"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b36a5b126bbe97eb0d02d07acfeb327036c6319fd816139a49824a83b7f9012"
+dependencies = [
+ "magnus-macros",
+ "rb-sys",
+ "rb-sys-env",
+ "seq-macro",
+]
+
+[[package]]
+name = "magnus-macros"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47607461fd8e1513cb4f2076c197d8092d921a1ea75bd08af97398f593751892"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "minimal-lexical"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
+
+[[package]]
+name = "nom"
+version = "7.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
+dependencies = [
+ "memchr",
+ "minimal-lexical",
+]
+
+[[package]]
+name = "pgn2-bitboard"
+version = "0.1.0"
+dependencies = [
+ "chessie",
+]
+
+[[package]]
+name = "pgn2_native"
+version = "0.1.0"
+dependencies = [
+ "magnus",
+ "pgn2-bitboard",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rb-sys"
+version = "0.9.128"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "45ca28513560e56cfb79a62b1fce363c73af170a182024ce880c77ee9429920a"
+dependencies = [
+ "rb-sys-build",
+]
+
+[[package]]
+name = "rb-sys-build"
+version = "0.9.128"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce04b2c55eff3a21aaa623fcc655d94373238e72cac6b3e1a3641ff31649f99a"
+dependencies = [
+ "bindgen",
+ "lazy_static",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "shell-words",
+ "syn",
+]
+
+[[package]]
+name = "rb-sys-env"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cca7ad6a7e21e72151d56fe2495a259b5670e204c3adac41ee7ef676ea08117a"
+
+[[package]]
+name = "regex"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
+
+[[package]]
+name = "seq-macro"
+version = "0.3.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc"
+
+[[package]]
+name = "shell-words"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc6fe69c597f9c37bfeeeeeb33da3530379845f10be461a66d16d03eca2ded77"
+
+[[package]]
+name = "shlex"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"

data/ext/pgn2_native/Cargo.toml

@@ -0,0 +1,19 @@
+[workspace]
+members = ["pgn2-bitboard", "pgn2_native"]
+resolver = "2"
+
+# The perft oracle does real work; optimize tests so `cargo test` runs
+# in release-like time instead of minutes.
+[profile.test]
+opt-level = 2
+
+[profile.dev]
+opt-level = 1
+
+# The shipped native gem is built in `release`; squeeze perft nps with LTO
+# and single codegen-unit (longer build, faster code).
+[profile.release]
+opt-level = 3
+lto = true
+codegen-units = 1
+

data/ext/pgn2_native/extconf.rb

@@ -0,0 +1,8 @@
+require 'mkmf'
+require 'rb_sys/mkmf'
+
+# The ext lives in a Cargo workspace whose root manifest is virtual, so
+# tell cargo which member to build.
+create_rust_makefile('pgn2_native/pgn2_native') do |builder|
+  builder.extra_cargo_args = ['--package', 'pgn2_native']
+end

data/ext/pgn2_native/pgn2-bitboard/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "pgn2-bitboard"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["lib"]
+
+[dependencies]
+chessie = "2.0"

data/ext/pgn2_native/pgn2-bitboard/src/board.rs

@@ -0,0 +1,32 @@
+use crate::moves::{Move, MoveList};
+
+/// A chess position backed by `chessie::Game`. Holds no chess logic of
+/// its own; every operation delegates. `Copy` because `chessie::Game`
+/// is `Copy`; `Default` because the magnus `Engine` wraps it in a
+/// `RefCell` and `#[derive(Default)]`s it.
+#[derive(Clone, Copy, PartialEq, Eq, Default)]
+pub struct Board {
+    game: chessie::Game,
+}
+
+impl Board {
+    pub fn from_fen(fen: &str) -> Result<Board, String> {
+        chessie::Game::from_fen(fen)
+            .map(|game| Board { game })
+            .map_err(|e| e.to_string())
+    }
+
+    pub fn perft(&self, depth: u32) -> u64 {
+        self.game.perft(depth as usize)
+    }
+
+    pub fn legal_moves(&self) -> MoveList {
+        let moves: Vec<Move> = self
+            .game
+            .get_legal_moves()
+            .into_iter()
+            .map(Move::from_chessie)
+            .collect();
+        MoveList(moves)
+    }
+}

data/ext/pgn2_native/pgn2-bitboard/src/lib.rs

@@ -0,0 +1,12 @@
+//! Thin adapter over the `chessie` crate exposing the small surface the
+//! `pgn2_native` magnus binding consumes. No chess logic lives here —
+//! `chessie` is the engine. Kept as a separate crate so the perft oracle
+//! stays testable in pure Rust (`cargo test -p pgn2-bitboard`) with no
+//! Ruby in the loop.
+
+pub mod board;
+pub mod moves;
+pub mod perft;
+
+pub use board::Board;
+pub use moves::{Move, MoveList};

data/ext/pgn2_native/pgn2-bitboard/src/moves.rs

@@ -0,0 +1,121 @@
+/// Adapter move carrying exactly what `to_uci` and `same_target` need:
+/// from-square, to-square, and optional promotion kind. No flag bits,
+/// so a position-free `uci_parse` can produce a comparable token — this
+/// preserves the existing `same_target` semantics (match on
+/// from + to + promo only), so `legal?("e1g1")` finds the castle and
+/// `legal?("e7e8q")` finds that exact promotion.
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub struct Move {
+    from: u8, // 0..=63, index = rank * 8 + file
+    to: u8,
+    promo: Option<Promo>,
+}
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum Promo {
+    Knight,
+    Bishop,
+    Rook,
+    Queen,
+}
+
+impl Move {
+    /// Build an adapter `Move` from a `chessie::Move` (a legal move).
+    ///
+    /// chessie encodes castling internally as "King takes Rook"
+    /// (`to` = the rook's square, Chess960 style). `into_standard_castle`
+    /// rewrites the `to` square to the king's destination (`e1g1`/`e1c1`),
+    /// matching the standard-UCI output the previous engine produced and
+    /// that `uci_parse` / `bitboard_spec.rb` expect. No-op for non-castle
+    /// moves.
+    pub(crate) fn from_chessie(m: chessie::Move) -> Self {
+        let m = m.into_standard_castle();
+        Move {
+            from: m.from().index() as u8,
+            to: m.to().index() as u8,
+            promo: m.promotion().map(|kind| match kind {
+                chessie::PieceKind::Knight => Promo::Knight,
+                chessie::PieceKind::Bishop => Promo::Bishop,
+                chessie::PieceKind::Rook => Promo::Rook,
+                chessie::PieceKind::Queen => Promo::Queen,
+                // Pawns/Kings never appear as a promotion kind.
+                _ => unreachable!("non-promotion PieceKind in Move::promotion"),
+            }),
+        }
+    }
+
+    /// UCI string: `"e2e4"`, `"e1g1"` (castle, king from→to),
+    /// `"e7e8q"` (promotion). Equal to `chessie::Move::to_uci` for
+    /// every legal move (castle and en-passant both reduce to from+to
+    /// in UCI), so the sorted-UCI output is unchanged.
+    pub fn to_uci(self) -> String {
+        let mut s = String::with_capacity(5);
+        s.push_str(&sq_name(self.from));
+        s.push_str(&sq_name(self.to));
+        if let Some(p) = self.promo {
+            s.push(match p {
+                Promo::Knight => 'n',
+                Promo::Bishop => 'b',
+                Promo::Rook => 'r',
+                Promo::Queen => 'q',
+            });
+        }
+        s
+    }
+
+    /// Match on from + to + promo (the pre-existing semantics).
+    pub fn same_target(self, other: Move) -> bool {
+        self.from == other.from && self.to == other.to && self.promo == other.promo
+    }
+}
+
+/// Thin wrapper around `Vec<Move>`; the binding calls `.iter()` on it.
+pub struct MoveList(pub Vec<Move>);
+
+impl MoveList {
+    pub fn iter(&self) -> std::slice::Iter<'_, Move> {
+        self.0.iter()
+    }
+}
+
+/// Parse a UCI string into a `Move` token **without** a position.
+/// Only `to_uci`/`same_target` consume the result, so from + to + promo
+/// is all that is needed. Returns `None` on any malformed input.
+pub fn uci_parse(s: &str) -> Option<Move> {
+    let b = s.as_bytes();
+    if b.len() < 4 {
+        return None;
+    }
+    let from = parse_sq(&b[0..2])?;
+    let to = parse_sq(&b[2..4])?;
+    let promo = if b.len() >= 5 {
+        Some(match b[4] {
+            b'n' => Promo::Knight,
+            b'b' => Promo::Bishop,
+            b'r' => Promo::Rook,
+            b'q' => Promo::Queen,
+            _ => return None,
+        })
+    } else {
+        None
+    };
+    Some(Move { from, to, promo })
+}
+
+fn parse_sq(t: &[u8]) -> Option<u8> {
+    let f = t[0].checked_sub(b'a')?;
+    let r = t[1].checked_sub(b'1')?;
+    if f > 7 || r > 7 {
+        return None;
+    }
+    Some(r * 8 + f)
+}
+
+fn sq_name(idx: u8) -> String {
+    let file = (b'a' + (idx & 7)) as char;
+    let rank = (b'1' + (idx >> 3)) as char;
+    let mut s = String::with_capacity(2);
+    s.push(file);
+    s.push(rank);
+    s
+}

data/ext/pgn2_native/pgn2-bitboard/src/perft.rs

@@ -0,0 +1,81 @@
+//! Perft oracle — the published node counts are the test. The chess
+//! logic lives in `chessie`; this file only exercises the adapter's
+//! `Board::from_fen` + `Board::perft` end-to-end in pure Rust (no Ruby).
+
+#[cfg(test)]
+mod tests {
+    use crate::board::Board;
+
+    struct Case {
+        fen: &'static str,
+        depth: u32,
+        nodes: u64,
+    }
+
+    fn run(c: Case) {
+        let b = Board::from_fen(c.fen).unwrap();
+        assert_eq!(b.perft(c.depth), c.nodes, "fen={} depth={}", c.fen, c.depth);
+    }
+
+    #[test]
+    fn perft_startpos() {
+        let f = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1";
+        run(Case { fen: f, depth: 1, nodes: 20 });
+        run(Case { fen: f, depth: 2, nodes: 400 });
+        run(Case { fen: f, depth: 3, nodes: 8902 });
+        run(Case { fen: f, depth: 4, nodes: 197281 });
+        run(Case { fen: f, depth: 5, nodes: 4865609 });
+    }
+
+    #[test]
+    fn perft_kiwipete() {
+        let f = "r3k2r/p1ppqpb1/bn2pnp1/3PN3/1p2P3/2N2Q1p/PPPBBPPP/R3K2R w KQkq - 0 1";
+        run(Case { fen: f, depth: 1, nodes: 48 });
+        run(Case { fen: f, depth: 2, nodes: 2039 });
+        run(Case { fen: f, depth: 3, nodes: 97862 });
+        run(Case { fen: f, depth: 4, nodes: 4085603 });
+    }
+
+    #[test]
+    fn perft_pos3() {
+        let f = "8/2p5/3p4/KP5r/1R3p1k/8/4P1P1/8 w - - 0 1";
+        run(Case { fen: f, depth: 1, nodes: 14 });
+        run(Case { fen: f, depth: 4, nodes: 43238 });
+        run(Case { fen: f, depth: 5, nodes: 674624 });
+    }
+
+    #[test]
+    fn perft_pos4() {
+        let f = "r3k2r/Pppp1ppp/1b3nbN/nP6/BBP1P3/q4N2/Pp1P2PP/R2Q1RK1 w kq - 0 1";
+        run(Case { fen: f, depth: 1, nodes: 6 });
+        run(Case { fen: f, depth: 3, nodes: 9467 });
+        run(Case { fen: f, depth: 4, nodes: 422333 });
+    }
+
+    #[test]
+    fn perft_pos5() {
+        let f = "rnbq1k1r/pp1Pbppp/2p5/8/2B5/8/PPP1NnPP/RNBQK2R w KQ - 1 8";
+        run(Case { fen: f, depth: 3, nodes: 62379 });
+        run(Case { fen: f, depth: 4, nodes: 2103487 });
+    }
+
+    #[test]
+    fn perft_pos6() {
+        let f = "r4rk1/1pp1qppp/p1np1n2/2b1p1B1/2B1P1b1/P1NP1N2/1PP1QPPP/R4RK1 w - - 0 10";
+        run(Case { fen: f, depth: 3, nodes: 89890 });
+        run(Case { fen: f, depth: 4, nodes: 3894594 });
+    }
+
+    #[test]
+    #[ignore] // slow; run with `cargo test -- --ignored`
+    fn perft_deep() {
+        let s = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1";
+        run(Case { fen: s, depth: 6, nodes: 119060324 });
+        let k = "r3k2r/p1ppqpb1/bn2pnp1/3PN3/1p2P3/2N2Q1p/PPPBBPPP/R3K2R w KQkq - 0 1";
+        run(Case { fen: k, depth: 5, nodes: 193690690 });
+    }
+
+    // The old `make_unmake_symmetry_via_perft` test is intentionally
+    // removed: it exercised the hand-rolled make/unmake internals, which
+    // no longer exist. chessie's own test suite covers its make/unmake.
+}

data/ext/pgn2_native/pgn2_native/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "pgn2_native"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+magnus = "0.8"
+pgn2-bitboard = { path = "../pgn2-bitboard" }

data/ext/pgn2_native/pgn2_native/src/lib.rs

@@ -0,0 +1,54 @@
+use std::cell::RefCell;
+
+use magnus::prelude::*;
+use magnus::{method, Error, Ruby};
+use pgn2_bitboard::Board;
+
+/// `PGN::Bitboard::Engine` — a magic/pext bitboard engine holding a position.
+///
+/// Constructed with a FEN string; `#perft(depth)` does a full-width perft.
+/// The wrapped board is held in a `RefCell`; `perft` borrows immutably (it
+/// clones internally for make/unmake), so no `&mut` crosses the FFI boundary.
+#[derive(Default)]
+#[magnus::wrap(class = "PGN::Bitboard::Engine", free_immediately)]
+struct Engine(RefCell<Board>);
+
+impl Engine {
+    fn initialize(ruby: &Ruby, rb_self: &Self, fen: String) -> Result<(), Error> {
+        let board = Board::from_fen(&fen)
+            .map_err(|e| Error::new(ruby.exception_arg_error(), e))?;
+        *rb_self.0.borrow_mut() = board;
+        Ok(())
+    }
+
+    fn perft(&self, depth: u32) -> u64 {
+        self.0.borrow().perft(depth)
+    }
+
+    fn legal_moves_ruby(&self) -> Vec<String> {
+        let mut v: Vec<String> = self.0.borrow().legal_moves().iter().map(|m| m.to_uci()).collect();
+        v.sort();
+        v
+    }
+
+    fn legal_p(&self, uci: String) -> bool {
+        match pgn2_bitboard::moves::uci_parse(&uci) {
+            Some(parsed) => self.0.borrow().legal_moves().iter().any(|m| m.same_target(parsed)),
+            None => false,
+        }
+    }
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let engine = ruby
+        .define_module("PGN")?
+        .define_module("Bitboard")?
+        .define_class("Engine", ruby.class_object())?;
+    engine.define_alloc_func::<Engine>();
+    engine.define_method("initialize", method!(Engine::initialize, 1))?;
+    engine.define_method("perft", method!(Engine::perft, 1))?;
+    engine.define_method("legal_moves", method!(Engine::legal_moves_ruby, 0))?;
+    engine.define_method("legal?", method!(Engine::legal_p, 1))?;;
+    Ok(())
+}

data/lib/pgn/bitboard.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Load the chessie-backed native bitboard engine if the compiled
+# extension is available. End users get the precompiled native gem (no
+# Rust toolchain needed); if the extension is absent (e.g. running from a
+# source checkout without `rake compile`), the load fails silently so
+# the rest of the gem still works. Code that calls PGN::Bitboard::Engine
+# will raise NameError naturally.
+begin
+  require 'pgn2_native/pgn2_native'
+rescue StandardError
+  LoadError
+end