feat: Add player age eligibility validation for leagues

[hoegertn]

Add functions to validate if a player is eligible to participate in a league by comparing their dateOfBirth against the league's minAge and maxAge restrictions:

• calculateAge: Utility to compute age from date of birth
• checkPlayerEligibility: Returns validation result with errors
• validatePlayerEligibility: Throws error if ineligible
• isPlayerEligible: Returns boolean for eligibility

Includes comprehensive tests for all edge cases including boundary conditions, missing data, and invalid formats.

Summary by CodeRabbit

• New Features

  • Added player eligibility validation capabilities including age-based checking with configurable age constraints and date handling.

• Documentation

  • Expanded and enhanced function documentation with detailed parameter descriptions, return value specifications, and usage examples for new validation features.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[amazon-inspector-frankfurt]

⏳ I'm reviewing this pull request for security vulnerabilities and code quality issues. I'll provide an update when I'm done

[coderabbitai]

Walkthrough

This PR introduces age-based player eligibility validation with four new utility functions (calculateAge, checkPlayerEligibility, validatePlayerEligibility, isPlayerEligible) in src/validation.ts, updates HTML documentation pages for these functions, adds comprehensive test coverage, and refreshes build assets with updated base64 payloads.

Changes

Cohort / File(s)	Summary
Asset Payload Updates docs/assets/navigation.js, docs/assets/search.js	Replaced base64-encoded payloads for window.navigationData and window.searchData with updated values; data content changes only, no logic modifications.
Function Documentation docs/functions/calculateAge.html, docs/functions/checkPlayerEligibility.html, docs/functions/isPlayerEligible.html, docs/functions/validatePlayerEligibility.html	Added new documentation pages and expanded existing ones with function signatures, parameter descriptions (dateOfBirth in AWSDate format YYYY-MM-DD, age constraints, referenceDate), and return type details.
Validation Implementation src/validation.ts	Added four exported functions for age-based validation: calculateAge (computes age in years from date), checkPlayerEligibility (returns ValidationCheckResult with validation errors), validatePlayerEligibility (throws on validation failure), and isPlayerEligible (returns boolean). Includes helper logic for date validation, age computation, and constraint checking.
Test Suite test/validation.test.ts	Extended with comprehensive test coverage for new validation functions, including edge cases for date handling, boundary conditions for age constraints, error scenarios, and success paths.

Sequence Diagram(s)

sequenceDiagram
    participant Caller as Client
    participant ValidateFunc as validatePlayerEligibility()
    participant CheckFunc as checkPlayerEligibility()
    participant CalcFunc as calculateAge()

    Caller->>ValidateFunc: (dateOfBirth, minAge, maxAge, referenceDate)
    ValidateFunc->>CheckFunc: (dateOfBirth, minAge, maxAge, referenceDate)
    CheckFunc->>CalcFunc: (dateOfBirth, referenceDate)
    CalcFunc-->>CheckFunc: age (number | null)
    
    alt Valid age constraints
        CheckFunc->>CheckFunc: Validate dateOfBirth format
        CheckFunc->>CheckFunc: Check age against min/max
        CheckFunc-->>ValidateFunc: ValidationCheckResult (valid)
        ValidateFunc-->>Caller: Success (void)
    else Invalid or age out of bounds
        CheckFunc-->>ValidateFunc: ValidationCheckResult (errors)
        ValidateFunc->>Caller: Throw Error
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Date handling and edge cases: Review logic in calculateAge for null/invalid dates and boundary conditions (e.g., leap years, DST).
• Validation error messages: Verify checkPlayerEligibility produces appropriate error messages for under/overage scenarios and input validation failures.
• Consistency across functions: Ensure validatePlayerEligibility and isPlayerEligible correctly wrap checkPlayerEligibility with expected behavior.
• Test coverage adequacy: Confirm test cases cover boundary conditions (age exactly at min/max, invalid date formats, null/undefined inputs).

Possibly related PRs

• taimos/radball-digital-api#34: Modifies the same docs/assets files (navigation.js and search.js) by replacing base64 payloads for window.navigationData and window.searchData.

Suggested reviewers

• hoegerma

Poem

🐰 Four functions hop into the fold,
Age calculations brave and bold!
ValidationCheckResult leads the way,
Player eligibility saves the day!
Thump, thump! ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The PR description provides a clear overview of the changes, listing the four new functions and their purposes. However, it does not follow the provided template structure with explicit sections for commit message verification, tests confirmation, documentation confirmation, change type, or breaking changes.	Consider using the repository's PR description template to include explicit checkboxes for commit message, tests, and docs, and clearly categorize the change type and breaking changes status.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding player age eligibility validation for leagues. It directly corresponds to the new functions (calculateAge, checkPlayerEligibility, validatePlayerEligibility, isPlayerEligible) and their purpose.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch claude/add-player-eligibility-check-017sye2nYis8gpndtkJ2SeZb

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[amazon-inspector-frankfurt]

✅ I finished the code review, and didn't find any security or code quality issues.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

test/validation.test.ts (1)

967-1006: Good coverage, but missing timezone edge case tests.

The test suite covers the main scenarios well. However, it doesn't expose the timezone bug in calculateAge because all tests use explicit date strings for referenceDate (which are parsed as UTC, matching the UTC parsing of dateOfBirth).

Consider adding a test that uses the current time in a specific timezone to ensure the fix handles timezone correctly:

it('should handle timezone correctly when using current time', () => {
  // Test that would expose the timezone bug if not using UTC methods
  const birthDate = '2000-01-01';
  const age = calculateAge(birthDate, new Date(2024, 0, 1, 12, 0, 0)); // January 1, 2024 noon local time
  expect(age).toBe(24);
});

This test would fail with the current implementation in timezones west of UTC.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 339d4ef and c2170a5.

📒 Files selected for processing (8)

• docs/assets/navigation.js (1 hunks)
• docs/assets/search.js (1 hunks)
• docs/functions/calculateAge.html (1 hunks)
• docs/functions/checkPlayerEligibility.html (1 hunks)
• docs/functions/isPlayerEligible.html (1 hunks)
• docs/functions/validatePlayerEligibility.html (1 hunks)
• src/validation.ts (1 hunks)
• test/validation.test.ts (2 hunks)

🔇 Additional comments (12)

docs/assets/navigation.js (1)

1-1: LGTM - Generated documentation artifact.

This is a generated navigation data payload that reflects the new API surface. No action required.

docs/assets/search.js (1)

1-1: LGTM - Generated documentation artifact.

This is a generated search index that reflects the new API surface. No action required.

docs/functions/calculateAge.html (1)

1-5: LGTM - Generated documentation page.

The documentation accurately describes the calculateAge function's parameters and return type. No action required.

docs/functions/checkPlayerEligibility.html (1)

1-7: LGTM - Generated documentation page.

The documentation accurately describes the checkPlayerEligibility function's parameters and return type. No action required.

docs/functions/validatePlayerEligibility.html (1)

1-7: LGTM - Generated documentation page.

The documentation accurately describes the validatePlayerEligibility function's throwing behavior. No action required.

docs/functions/isPlayerEligible.html (1)

1-7: LGTM - Generated documentation page.

The documentation accurately describes the isPlayerEligible function's boolean return value. No action required.

src/validation.ts (3)

523-560: LGTM - Solid validation logic.

The age eligibility validation correctly handles all edge cases:

• Returns no errors when no age restrictions are set
• Validates that dateOfBirth is provided when restrictions exist
• Delegates to calculateAge for date parsing and age computation
• Checks both minimum and maximum age constraints with clear error messages

The use of != null properly catches both null and undefined values.

Note: This function depends on calculateAge, which has a timezone issue flagged separately.

---

570-578: LGTM - Clean throwing wrapper.

The function follows the established validation pattern in the codebase by delegating to checkPlayerEligibility and throwing via result.validate().

---

588-596: LGTM - Useful boolean convenience method.

The function provides a clean boolean API by delegating to checkPlayerEligibility and converting the result to true/false based on error presence.

test/validation.test.ts (3)

1008-1138: LGTM - Comprehensive test coverage.

The test suite for checkPlayerEligibility is excellent, covering:

• No restrictions scenario
• Missing/invalid date of birth handling
• Minimum and maximum age boundaries
• Combined age range validation
• Edge cases (exact age requirements, zero minimum age)

The tests verify both the absence of errors in valid cases and the presence of specific error messages in invalid cases.

---

1140-1165: LGTM - Adequate coverage for throwing wrapper.

The tests verify the key throwing behaviors:

• No exception for eligible players
• Correct exception messages for ineligible players (too young, too old, missing DOB)
• No exception when no restrictions exist

---

1167-1197: LGTM - Complete boolean wrapper coverage.

The tests verify the boolean return values across all scenarios:

• True for eligible players
• False for all ineligibility reasons
• Partial restriction handling (minAge-only, maxAge-only)