[garak]

• Add Fen::parse() and Fen::serialize(). They replace Chess::load() and the body of Chess::fen().
• Fen delegates validation to Validation, which stays public.
• parse() places only the first king per color, matching the old put() behaviour.
• Drop Chess::load() and Chess::clear(). The constructor builds its Position via Fen::parse().
• Test Fen directly: round trip over the FenTest provider, fields, extra kings, board reuse, errors.

This is part 5 of #91

Summary by CodeRabbit

• New Features
  • Added support for parsing FEN strings into chess positions and serializing positions back into FEN. Invalid FEN input raises an exception.
• Documentation
  • Added guidance on FEN parsing and serialization, including validation details and an example. A link is available from the chess documentation index.

[coderabbitai]

No actionable comments were generated in the recent review.

Walkthrough

The PR adds Fen::parse() and Fen::serialize() for converting between FEN strings and Position objects. Chess now uses these methods for constructor input and FEN output. The PR also adds tests and documentation for the conversion methods.

Changes: FEN Parsing and Serialization

Layer / File(s)	Summary
Parse FEN into a Position src/Fen.php, tests/FenTest.php	Fen::parse() validates input and populates a Position, with optional reuse of a supplied Board. Tests cover parsed fields, board reuse, and invalid input.
Integrate FEN conversion with Chess src/Fen.php, src/Chess.php, tests/FenTest.php, docs/fen.md, docs/index.md	Fen::serialize() formats a Position as FEN. Chess uses Fen for constructor parsing and FEN output; its clear() and load() methods were removed. Tests cover round trips and positions with extra kings. The documentation describes the conversion methods and links to the new page.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Refactor

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant Chess
  participant Fen
  participant Validation
  participant Position
  Caller->>Chess: construct with FEN
  Chess->>Fen: parse FEN
  Fen->>Validation: validate FEN
  Validation-->>Fen: return validation result
  Fen->>Position: populate position fields and board
  Fen-->>Chess: return Position
  Chess->>Chess: assign board and refresh hash
  Caller->>Chess: request FEN
  Chess->>Fen: serialize position
  Fen-->>Chess: return FEN string

Loading

Possibly related issues

• Continue the decomposition of the Chess class #91 — The issue proposes extracting FEN parsing and serialization from Chess; this PR adds Fen::parse() and Fen::serialize() and removes the corresponding Chess methods.

Possibly related PRs

• p-chess/chess#96 — This PR uses the Position fields introduced by that PR for FEN parsing, serialization, and Chess construction.

Merge Risk: Minimal · up to 1317b

No merge-blocking issue is established; the FEN conversion is mergeable after normal checks.

Security architecture risk: Low · up to 1317b

The extraction preserves input validation and normal Chess initialization. The main integration risks are destructive reuse of mutable boards and removal of protected lifecycle methods used by potential subclasses. No introduced security bypass was established.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The inspected parser's mutable scope is the newly allocated or caller-supplied in-process Board and the returned Position. It does not itself acquire credentials or perform filesystem, network, deployment, or persistent-store operations. Effects on other owners depend on the caller supplying a shared Board.

Trust Boundaries and Controls

• observed — Caller-controlled FEN text passes through the same validator used by the former Chess loader before any board mutation. Chess consumes the parsed Position without an alternate unvalidated construction path in the inspected changes.

Resilience and Maintainability Implications

• observed — Normal Chess construction uses a fresh parsed board and keeps Position and Chess board identity aligned. Its move-generation and SAN caches begin empty, and its hash and history are initialized after parsing. The retained-Position aliasing case requires explicit Board reuse outside that normal constructor path.

Hardening Proposals

• proposed — Clarify that supplied-board reuse requires exclusive lifecycle ownership: callers should not reuse a Board still backing a live Chess instance or a Position whose metadata they expect to remain coherent. This would strengthen the documented ownership contract, not remediate a verified security finding.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documenta…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly identifies the main change: extracting FEN parsing and serialization into the Fen class. It is concise and related to the changeset.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 4 functions across 3 files. (2 skipped: 2 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches

Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Tip

🎯 Customize your risk assessments

Guide how CodeRabbit assesses merge risk and security architecture risk. Highlight sensitive changes and explain your security boundaries using Merge Risk Instructions and Security Risk Instructions in your review settings. Security architecture risk assessments require the Advanced plan or above.

✅ Automatic approvals, with your rules

Let CodeRabbit approve pull requests once required threads are resolved, pre-merge checks pass, and your risk limits are met. Enable Automatic approvals in review settings, with overrides for teams or file paths.

Recent review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 46657e69-d4cc-4468-bd50-f6b90ba1f522

Commits

Reviewing files that changed from the base of the PR and between 77aa315 and 1317b1c.

Files selected for processing: 5

• docs/fen.md
• docs/index.md
• src/Chess.php
• src/Fen.php
• tests/FenTest.php

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.