Implement DirectionValidator and PlayerOnlineValidator #295

New issue

Closed

opened 2026-03-16 01:59:22 +00:00 by freemo · 0 comments

freemo commented

2026-03-16 01:59:22 +00:00

Owner

Metadata

Key	Value
Branch	`feature/m1-direction-validator`
Commit Message	`feat: implement DirectionValidator and PlayerOnlineValidator`
Parent Epic	#291 — Input Validation Framework

Background and Context

Two common validation needs in MUD commands are validating directions (for movement and look commands) and verifying that a named player is currently online (for communication and interaction commands). These specialized validators plug into the validation pipeline's type-check and reference-resolve steps for the :direction and :player param types respectively.

Expected Behavior

DirectionValidator validates direction strings against the canonical set of valid directions: n, s, e, w, u, d, ne, nw, se, sw, in, out. It also accepts long-form aliases (north, south, east, west, up, down, northeast, northwest, southeast, southwest) and normalizes them to short-form.

PlayerOnlineValidator checks that a named player is currently logged in and connected. It performs case-insensitive matching and returns the actual Player object on success, or a descriptive error if the player is not found or not online.

DirectionValidator.validate("northeast")  # => Valid("ne")
DirectionValidator.validate("sideways")   # => Invalid("'sideways' is not a valid direction.")

PlayerOnlineValidator.validate("Freemo")  # => Valid(player_object)
PlayerOnlineValidator.validate("Ghost")   # => Invalid("No player named 'Ghost' is currently online.")

Acceptance Criteria

DirectionValidator.validate accepts all 12 short-form directions: n, s, e, w, u, d, ne, nw, se, sw, in, out.
Long-form aliases (north, south, east, west, up, down, northeast, northwest, southeast, southwest) are accepted and normalized to short-form.
Invalid direction strings produce a clear error message.
PlayerOnlineValidator.validate checks the player is currently online.
Player name matching is case-insensitive.
A valid player name returns the actual Player object.
A non-existent or offline player produces a descriptive error message.
Both validators integrate with the validation pipeline's type-check step.

Subtasks

Code

Create DirectionValidator class with .validate(input) method.
Define direction constants: short-form set and long-to-short mapping.
Implement normalization of long-form to short-form directions.
Create PlayerOnlineValidator class with .validate(name, context) method.
Implement case-insensitive player lookup against online player registry.
Register both validators in the type-check step of the validation pipeline.

Quality

Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable.
Tests (Cucumber): Add tests/unit/direction_validator.feature covering all 12 short-form directions, long-form aliases, invalid direction, case-insensitive player lookup, online player found, offline player error, non-existent player error.
Tests (Cucumber Integration): Add integration feature in tests/integration/ for DirectionValidator and PlayerOnlineValidator in the validation pipeline.
Tests (Profiling): Run bundle exec rake unit_profile and verify no performance regressions.
Quality: Verify coverage >=97% via bundle exec rake unit. If coverage is <97% then review the current unit test coverage report at build/tests/unit/coverage/ and use it to write new Cucumber based unit tests to improve coverage. Specifically, write Cucumber/Gherkin style unit tests that are descriptively named and specifically improve coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun bundle exec rake unit to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%.
Quality: Run bundle exec rake (default task: unit tests with coverage) and bundle exec rake integration, fix any errors if needed ensuring both pass across entire code base, do not ignore any failure even if it seems unrelated to this commit, fix it.

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

## Metadata | Key | Value | |-----|-------| | **Branch** | `feature/m1-direction-validator` | | **Commit Message** | `feat: implement DirectionValidator and PlayerOnlineValidator` | | **Parent Epic** | #291 — Input Validation Framework | ## Background and Context Two common validation needs in MUD commands are validating directions (for movement and look commands) and verifying that a named player is currently online (for communication and interaction commands). These specialized validators plug into the validation pipeline's type-check and reference-resolve steps for the `:direction` and `:player` param types respectively. ## Expected Behavior **DirectionValidator** validates direction strings against the canonical set of valid directions: `n`, `s`, `e`, `w`, `u`, `d`, `ne`, `nw`, `se`, `sw`, `in`, `out`. It also accepts long-form aliases (`north`, `south`, `east`, `west`, `up`, `down`, `northeast`, `northwest`, `southeast`, `southwest`) and normalizes them to short-form. **PlayerOnlineValidator** checks that a named player is currently logged in and connected. It performs case-insensitive matching and returns the actual Player object on success, or a descriptive error if the player is not found or not online. ```ruby DirectionValidator.validate("northeast") # => Valid("ne") DirectionValidator.validate("sideways") # => Invalid("'sideways' is not a valid direction.") PlayerOnlineValidator.validate("Freemo") # => Valid(player_object) PlayerOnlineValidator.validate("Ghost") # => Invalid("No player named 'Ghost' is currently online.") ``` ## Acceptance Criteria - [ ] `DirectionValidator.validate` accepts all 12 short-form directions: n, s, e, w, u, d, ne, nw, se, sw, in, out. - [ ] Long-form aliases (north, south, east, west, up, down, northeast, northwest, southeast, southwest) are accepted and normalized to short-form. - [ ] Invalid direction strings produce a clear error message. - [ ] `PlayerOnlineValidator.validate` checks the player is currently online. - [ ] Player name matching is case-insensitive. - [ ] A valid player name returns the actual Player object. - [ ] A non-existent or offline player produces a descriptive error message. - [ ] Both validators integrate with the validation pipeline's type-check step. ## Subtasks ### Code - [ ] Create `DirectionValidator` class with `.validate(input)` method. - [ ] Define direction constants: short-form set and long-to-short mapping. - [ ] Implement normalization of long-form to short-form directions. - [ ] Create `PlayerOnlineValidator` class with `.validate(name, context)` method. - [ ] Implement case-insensitive player lookup against online player registry. - [ ] Register both validators in the type-check step of the validation pipeline. ### Quality - [ ] Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable. - [ ] Tests (Cucumber): Add `tests/unit/direction_validator.feature` covering all 12 short-form directions, long-form aliases, invalid direction, case-insensitive player lookup, online player found, offline player error, non-existent player error. - [ ] Tests (Cucumber Integration): Add integration feature in `tests/integration/` for DirectionValidator and PlayerOnlineValidator in the validation pipeline. - [ ] Tests (Profiling): Run `bundle exec rake unit_profile` and verify no performance regressions. - [ ] Quality: Verify coverage >=97% via `bundle exec rake unit`. If coverage is <97% then review the current unit test coverage report at `build/tests/unit/coverage/` and use it to write new Cucumber based unit tests to improve coverage. Specifically, write Cucumber/Gherkin style unit tests that are descriptively named and specifically improve coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun `bundle exec rake unit` to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%. - [ ] Quality: Run `bundle exec rake` (default task: unit tests with coverage) and `bundle exec rake integration`, fix any errors if needed ensuring both pass across **entire** code base, do not ignore any failure even if it seems unrelated to this commit, fix it. ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.