Polish FEN validation APIs

Author: Trickfest

CHANGELOG.md

@@ -90,6 +90,10 @@ release. Replace `TBD` with the release date when a release is tagged.
 - Added `PositionValidator`, `PositionValidationIssue`,
   `PositionValidationError`, and `FENSerializer.validatedPosition(from:)` for
   strict semantic validation of syntactically parsed FEN positions.
+- Added `PositionValidationResult`, `FENValidationResult`,
+  `PositionValidator.validationResult(for:)`, and
+  `FENSerializer.validationResult(for:)` so callers can inspect FEN syntax and
+  semantic position diagnostics without using throwing control flow.
 - Added PGN result/status validation so terminal checkmate and automatic-draw
   final positions reject incompatible PGN result markers during import and
   export.

Docs/ChessCoreGlossary.md

@@ -20,6 +20,11 @@ engine-analysis, and product-specific concepts belong in app-level docs.
 - **Position Validator**: `PositionValidator`, the ChessCore API that checks
   whether a syntactically parsed `Position` satisfies strict semantic position
   constraints.
+- **Position Validation Result**: `PositionValidationResult`, the non-throwing
+  result value returned when semantically validating an already parsed
+  `Position`.
+- **FEN Validation Result**: `FENValidationResult`, the non-throwing result
+  value returned when parsing and semantically validating FEN text.
 - **Dead Position Analyzer**: `DeadPositionAnalyzer`, the ChessCore API that
   proves whether a position is dead because neither side can possibly
   checkmate.
@@ -156,7 +161,8 @@ engine-analysis, and product-specific concepts belong in app-level docs.
   parses FEN syntax and then rejects impossible or inconsistent positions such
   as missing kings, invalid castling rights, invalid en-passant targets,
   en-passant targets with a nonzero halfmove clock, pawns on invalid ranks, or
-  inactive-side check.
+  inactive-side check. Use `FENSerializer.validationResult(for:)` when callers
+  need to inspect syntax and semantic validation failures without throwing.
 - **SAN**: Standard Algebraic Notation, the human-readable move notation used in
   movetext, such as `Nf3`, `exd5`, `O-O`, or `Qxf7#`.
 - **PGN**: Portable Game Notation, a text format for complete game records.

Docs/ChessCoreTestingStrategy.md

@@ -151,6 +151,10 @@ Semantic FEN validation coverage currently includes:
 
 - `FENSerializer.position(from:)` remains syntax-only
 - `FENSerializer.validatedPosition(from:)` returns valid playable positions
+- `FENSerializer.validationResult(for:)` reports syntax and semantic failures
+  without throwing
+- `PositionValidator.validationResult(for:)` reports semantic issues for an
+  already parsed `Position`
 - missing kings and multiple kings are reported
 - pawns on the first or eighth rank are reported
 - castling rights require the matching king and rook on their starting squares
@@ -211,7 +215,7 @@ classified as:
 | Pieces | Symbol parsing, equality, hashing. | Piece equality and character mapping are covered. | Covered | Low |
 | Board storage | Default/empty boards, get/set/remove pieces, color lookup, piece maps. | Board square/index/coordinate access, copy independence, and enumeration are covered. | Covered | Low |
 | FEN syntax | Valid FEN, malformed FEN, counters, en-passant fields, castling fields. | Serialization, malformed fields, generated round trips, adjacent digit rejection, and counter bounds are covered. | Covered | Low |
-| FEN semantic status | Bad castling rights, multiple kings, impossible or inconsistent positions. | `PositionValidator` and `FENSerializer.validatedPosition(from:)` cover king counts, pawn ranks, castling rights, en-passant availability, en-passant halfmove-clock consistency, inactive-side check, and multi-issue reporting. Dead-position adjudication is covered separately by `Game.status` and `DeadPositionAnalyzer`. | Covered | Low |
+| FEN semantic status | Bad castling rights, multiple kings, impossible or inconsistent positions. | `PositionValidator`, `PositionValidator.validationResult(for:)`, `FENSerializer.validatedPosition(from:)`, and `FENSerializer.validationResult(for:)` cover king counts, pawn ranks, castling rights, en-passant availability, en-passant halfmove-clock consistency, inactive-side check, syntax-vs-semantic diagnostics, and multi-issue reporting. Dead-position adjudication is covered separately by `Game.status` and `DeadPositionAnalyzer`. | Covered | Low |
 | EPD | EPD parsing, operations, best-move fields. | ChessCore does not support EPD. | Out of scope | Low |
 | Legal move generation | Legal move lists, move counts, perft-style fixtures, pseudo-legal distinctions. | Focused legal-move fixtures, 40 perft positions, a 53-position exact legal-move corpus, and 48 generated move-count/status positions created with a temporary `python-chess` oracle are covered, including castling, en-passant, promotion, underpromotion mate, checkmate, stalemate, and generated midgame positions. | Covered | Low |
 | Castling | SAN castling, selective castling, missing/invalid rights, rook/king edge cases, Chess960 castling. | Standard castling rights, missing rooks, matching rook color, attacked transit/destination, in-check rejection, b-file occupancy, rook-path attack tolerance, and application are covered. Chess960 is out of scope. | Covered | Low |

Docs/ChessCoreTutorial.md

@@ -102,6 +102,37 @@ let validated = try fenSerializer.validatedPosition(
 )
 ```
 
+Use `validationResult(for:)` when you want to show diagnostics without using
+throwing control flow:
+
+```swift
+let result = fenSerializer.validationResult(for: externalFEN)
+
+switch result {
+case .valid(let position):
+    print("Ready to play: \(position)")
+case .invalidSyntax(let error):
+    print("Malformed FEN: \(error)")
+case .invalidPosition(let validation):
+    for issue in validation.issues {
+        print("Position issue: \(issue)")
+    }
+}
+```
+
+For an already parsed `Position`, use `PositionValidator` directly:
+
+```swift
+let validation = PositionValidator().validationResult(for: position)
+
+if validation.isValid {
+    let playable = try validation.validatedPosition()
+    print(playable)
+} else {
+    print(validation.issues)
+}
+```
+
 Semantic validation rejects positions with missing or multiple kings, pawns on
 the first or eighth rank, castling rights without the matching king and rook,
 invalid en-passant targets, en-passant targets with a nonzero halfmove clock,
@@ -632,6 +663,11 @@ Common errors:
 - `GameDrawClaimError`: a draw claim was requested when it is not currently
   available.
 
+For FEN validation in forms, importers, or command-line tools,
+`FENSerializer.validationResult(for:)` returns a `FENValidationResult` instead
+of throwing. Use `validatedPosition()` on the result when you want the same
+throwing behavior as `validatedPosition(from:)`.
+
 Catch PGN parser errors:
 
 ```swift
@@ -857,6 +893,18 @@ let finalFEN = FENSerializer().fen(from: game.finalPosition)
 let position = try FENSerializer().validatedPosition(from: fen)
 ```
 
+### Inspect FEN Validation Issues
+
+```swift
+let result = FENSerializer().validationResult(for: fen)
+
+if let syntaxError = result.syntaxError {
+    print("Syntax error: \(syntaxError)")
+} else if result.isValid == false {
+    print(result.positionIssues)
+}
+```
+
 ### Replay Concrete Moves
 
 ```swift

README.md

@@ -100,6 +100,14 @@ do {
 }
 ```
 
+When accepting external FEN, use strict semantic validation or inspect a
+non-throwing validation result:
+
+```swift
+let position = try FENSerializer().validatedPosition(from: startingFEN)
+let validation = FENSerializer().validationResult(for: startingFEN)
+```
+
 ### PGN Import And Export
 
 `PGNSerializer` parses Portable Game Notation in `ChessCore`. It lexes PGN

Sources/ChessCore/FENSerializer.swift

@@ -44,6 +44,70 @@ public enum FENParsingError: Error, Equatable, CustomStringConvertible, Localize
     }
 }
 
+/// Result of parsing and semantically validating a FEN string.
+public enum FENValidationResult: Equatable, Sendable {
+
+    /// FEN syntax and semantic position validation both passed.
+    case valid(Position)
+
+    /// FEN syntax parsing failed before a `Position` could be created.
+    case invalidSyntax(FENParsingError)
+
+    /// FEN syntax parsed, but the resulting `Position` failed semantic checks.
+    case invalidPosition(PositionValidationResult)
+
+    /// `true` when the FEN string parsed and the resulting position is
+    /// semantically valid.
+    public var isValid: Bool {
+        if case .valid = self {
+            return true
+        }
+        return false
+    }
+
+    /// Parsed position, when FEN syntax was valid.
+    public var position: Position? {
+        switch self {
+        case let .valid(position):
+            return position
+        case let .invalidPosition(result):
+            return result.position
+        case .invalidSyntax:
+            return nil
+        }
+    }
+
+    /// Syntax parsing error, when FEN syntax was malformed.
+    public var syntaxError: FENParsingError? {
+        if case let .invalidSyntax(error) = self {
+            return error
+        }
+        return nil
+    }
+
+    /// Semantic position issues, when FEN syntax parsed successfully.
+    public var positionIssues: [PositionValidationIssue] {
+        if case let .invalidPosition(result) = self {
+            return result.issues
+        }
+        return []
+    }
+
+    /// Returns the parsed position, or throws the same error as strict
+    /// validation.
+    public func validatedPosition() throws -> Position {
+        switch self {
+        case let .valid(position):
+            return position
+        case let .invalidSyntax(error):
+            throw error
+        case let .invalidPosition(result):
+            return try result.validatedPosition()
+        }
+    }
+
+}
+
 /// Converts between `Position` values and Forsyth-Edwards Notation.
 public class FENSerializer {
 
@@ -83,9 +147,24 @@ public class FENSerializer {
     /// playable-position constraints such as king counts, castling rights, pawn
     /// ranks, en-passant availability, and inactive-side check.
     public func validatedPosition(from fen: String) throws -> Position {
-        let position = try self.position(from: fen)
-        try PositionValidator().validate(position)
-        return position
+        try self.validationResult(for: fen).validatedPosition()
+    }
+
+    /// Parses and semantically validates a FEN string without throwing.
+    ///
+    /// Use this method when callers need UI-friendly diagnostics or want to
+    /// distinguish malformed FEN syntax from semantic position issues without
+    /// using throwing control flow.
+    public func validationResult(for fen: String) -> FENValidationResult {
+        do {
+            let position = try self.position(from: fen)
+            let result = PositionValidator().validationResult(for: position)
+            return result.isValid ? .valid(position) : .invalidPosition(result)
+        } catch let error as FENParsingError {
+            return .invalidSyntax(error)
+        } catch {
+            preconditionFailure("Unexpected FEN parsing error: \(error)")
+        }
     }
 
     /// Formats a position as a full six-field FEN string.

Sources/ChessCore/PositionValidator.swift

@@ -56,6 +56,36 @@ public enum PositionValidationError: Error, Equatable, CustomStringConvertible,
     }
 }
 
+/// Result of semantically validating a parsed chess position.
+public struct PositionValidationResult: Equatable, Sendable {
+
+    /// The position that was checked.
+    public let position: Position
+
+    /// Semantic issues found in the position.
+    public let issues: [PositionValidationIssue]
+
+    /// Creates a validation result for a parsed position.
+    public init(position: Position, issues: [PositionValidationIssue]) {
+        self.position = position
+        self.issues = issues
+    }
+
+    /// `true` when no semantic validation issues were found.
+    public var isValid: Bool {
+        issues.isEmpty
+    }
+
+    /// Returns `position`, or throws the same error as strict validation.
+    public func validatedPosition() throws -> Position {
+        guard isValid else {
+            throw PositionValidationError.invalidPosition(issues)
+        }
+        return position
+    }
+
+}
+
 /// Performs semantic validation for parsed chess positions.
 public struct PositionValidator: Sendable {
 
@@ -101,12 +131,14 @@ public struct PositionValidator: Sendable {
         return issues
     }
 
+    /// Returns a semantic validation result for `position`.
+    public func validationResult(for position: Position) -> PositionValidationResult {
+        PositionValidationResult(position: position, issues: self.issues(in: position))
+    }
+
     /// Throws when `position` has semantic validation issues.
     public func validate(_ position: Position) throws {
-        let issues = self.issues(in: position)
-        guard issues.isEmpty else {
-            throw PositionValidationError.invalidPosition(issues)
-        }
+        _ = try self.validationResult(for: position).validatedPosition()
     }
 
     private func isValidCastlingRight(_ right: Piece, in position: Position) -> Bool {

Tests/ChessCoreTests/PositionValidatorTests.swift

@@ -26,7 +26,11 @@ import Testing
     ])
 func positionValidatorAcceptsPlayablePositions(fen: String) throws {
     let position = try FENSerializer().position(from: fen)
+    let result = PositionValidator().validationResult(for: position)
 
+    #expect(result.isValid)
+    #expect(result.issues.isEmpty)
+    #expect(try result.validatedPosition() == position)
     #expect(PositionValidator().issues(in: position).isEmpty)
     #expect(try FENSerializer().validatedPosition(from: fen) == position)
 }
@@ -175,6 +179,79 @@ func positionValidatorAcceptsPlayablePositions(fen: String) throws {
     )
 }
 
+@Test func positionValidationResultReportsSemanticIssuesWithoutThrowing() throws {
+    let position = try FENSerializer().position(from: "P3k3/8/8/8/8/8/8/8 w K d6 1 1")
+    let result = PositionValidator().validationResult(for: position)
+
+    #expect(result.position == position)
+    #expect(result.isValid == false)
+    #expect(result.issues.contains(.missingKing(.white)))
+    #expect(result.issues.contains(.pawnOnInvalidRank(Square(coordinate: "a8"))))
+    #expect(result.issues.contains(.invalidCastlingRight(Piece(kind: .king, color: .white))))
+    #expect(result.issues.contains(.invalidEnPassantTarget(Square(coordinate: "d6"))))
+
+    do {
+        _ = try result.validatedPosition()
+        Issue.record("Expected semantic validation result to throw")
+    } catch let error as PositionValidationError {
+        #expect(error == .invalidPosition(result.issues))
+    } catch {
+        Issue.record("Expected PositionValidationError, got: \(error)")
+    }
+}
+
+@Test func fenValidationResultReportsValidPositions() throws {
+    let serializer = FENSerializer()
+    let position = try serializer.position(from: PGNSerializer.standardStartingFEN)
+    let result = serializer.validationResult(for: PGNSerializer.standardStartingFEN)
+
+    #expect(result == .valid(position))
+    #expect(result.isValid)
+    #expect(result.position == position)
+    #expect(result.syntaxError == nil)
+    #expect(result.positionIssues.isEmpty)
+    #expect(try result.validatedPosition() == position)
+}
+
+@Test func fenValidationResultReportsSyntaxErrorsWithoutThrowing() {
+    let result = FENSerializer().validationResult(for: "8/8/8/8/8/8/8 w - - 0 1")
+
+    #expect(result.isValid == false)
+    #expect(result.position == nil)
+    #expect(result.syntaxError == .invalidPiecePlacement("8/8/8/8/8/8/8"))
+    #expect(result.positionIssues.isEmpty)
+
+    do {
+        _ = try result.validatedPosition()
+        Issue.record("Expected syntax-invalid FEN result to throw")
+    } catch let error as FENParsingError {
+        #expect(error == .invalidPiecePlacement("8/8/8/8/8/8/8"))
+    } catch {
+        Issue.record("Expected FENParsingError, got: \(error)")
+    }
+}
+
+@Test func fenValidationResultReportsSemanticIssuesWithoutThrowing() throws {
+    let fen = "8/8/8/8/8/8/8/8 w - - 0 1"
+    let parsedPosition = try FENSerializer().position(from: fen)
+    let result = FENSerializer().validationResult(for: fen)
+
+    #expect(result.isValid == false)
+    #expect(result.position == parsedPosition)
+    #expect(result.syntaxError == nil)
+    #expect(result.positionIssues.contains(.missingKing(.white)))
+    #expect(result.positionIssues.contains(.missingKing(.black)))
+
+    do {
+        _ = try result.validatedPosition()
+        Issue.record("Expected semantically invalid FEN result to throw")
+    } catch let error as PositionValidationError {
+        #expect(error == .invalidPosition(result.positionIssues))
+    } catch {
+        Issue.record("Expected PositionValidationError, got: \(error)")
+    }
+}
+
 @Test func fenValidatedPositionPreservesSyntaxErrorsAndThrowsSemanticErrors() throws {
     do {
         _ = try FENSerializer().validatedPosition(from: "8/8/8/8/8/8/8 w - - 0 1")