pipeworks_mud_mapper.services.validation_service

Validation service for map integrity checks.

This module provides validation functions that check map files for common issues. Validations are non-destructive - they return warnings but don’t modify the map.

Validation Categories

Connectivity

Unreachable rooms (no path from spawn)
Dead-end rooms (no exits)
Broken exit references

Exit Consistency

Asymmetric exits (A→B exists but B→A doesn’t)
Direction conflicts (exit says “north” but coords say “south”)

Language-Direction

Room names with vertical words (“Upper”, “Basement”) that don’t match their navigational reality
This catches the “Upper Landing” problem from goblin_cartography.md

Warning Severity

Warnings have severity levels:

ERROR: Must be fixed before export (broken references)
WARNING: Should be reviewed but may be intentional (dead ends)
INFO: Informational only (asymmetric exits may be intended)

Usage

Run all validations:

from pipeworks_mud_mapper.services import validation_service

warnings = validation_service.validate_all(map_file)
for warning in warnings:
    print(f"[{warning.severity}] {warning.room_id}: {warning.message}")

Run specific validations:

conn_warnings = validation_service.validate_connectivity(map_file)
exit_warnings = validation_service.validate_exit_consistency(map_file)

Classes

`Severity`	Severity level for validation warnings.
`ValidationWarning`	A validation warning or error.

Functions

`validate_all`(map_file)	Run all validation checks on a map file.
`validate_connectivity`(map_file)	Check for connectivity issues.
`validate_exit_consistency`(map_file)	Check for exit consistency issues.
`validate_language_direction`(map_file)	Check for language-direction conflicts in room names.
`has_errors`(warnings)	Check if any warnings are errors.
`filter_by_severity`(warnings, severity)	Filter warnings by severity level.
`filter_by_category`(warnings, category)	Filter warnings by category.
`create_validation_report`(map_file_name, warnings)	Create a validation report dictionary.
`write_validation_report`(map_file_name, warnings[, ...])	Write a validation report to a JSON file.

Module Contents

class pipeworks_mud_mapper.services.validation_service.Severity[source]

Bases: enum.StrEnum

Severity level for validation warnings.

class pipeworks_mud_mapper.services.validation_service.ValidationWarning[source]

A validation warning or error.

severity

How serious this issue is.

Type:: Severity

category

Category of the warning (connectivity, consistency, language).

Type:: str

room_id

Room ID related to the warning, if applicable.

Type:: str or None

message

Human-readable description of the issue.

Type:: str

details

Additional structured data about the issue.

Type:: dict

pipeworks_mud_mapper.services.validation_service.validate_all(map_file)[source]

Run all validation checks on a map file.

Parameters:: map_file (MapFile) – The map file to validate.
Returns:: All warnings from all validation checks, sorted by severity.
Return type:: list[ValidationWarning]

Examples

>>> warnings = validate_all(map_file)
>>> errors = [w for w in warnings if w.severity == Severity.ERROR]
>>> if errors:
...     print("Cannot export: fix errors first")

pipeworks_mud_mapper.services.validation_service.validate_connectivity(map_file)[source]

Check for connectivity issues.

Checks for: - Unreachable rooms (no path from spawn) - Dead-end rooms (no exits) - Broken exit references (exit to nonexistent room)

Parameters:: map_file (MapFile) – The map file to validate.
Returns:: Connectivity warnings.
Return type:: list[ValidationWarning]

Examples

>>> warnings = validate_connectivity(map_file)
>>> for w in warnings:
...     if "unreachable" in w.message:
...         print(f"Orphan room: {w.room_id}")

pipeworks_mud_mapper.services.validation_service.validate_exit_consistency(map_file)[source]

Check for exit consistency issues.

Checks for: - Asymmetric exits (A→north→B but B has no south→A) - Direction/coordinate mismatches (exit says “north” but room is south)

Parameters:: map_file (MapFile) – The map file to validate.
Returns:: Exit consistency warnings.
Return type:: list[ValidationWarning]

Notes

Asymmetric exits are flagged as INFO, not errors, because some asymmetry is intentional (one-way doors, hidden passages, trapdoors).

pipeworks_mud_mapper.services.validation_service.validate_language_direction(map_file)[source]

Check for language-direction conflicts in room names.

Flags rooms whose names contain vertical words (like “Upper”, “Basement”) but are not reached via the corresponding vertical direction (up/down).

This catches the “Upper Landing” problem from goblin_cartography.md: a room named “Upper Landing” reached via “north” creates cognitive dissonance for players trying to build a mental map.

Parameters:: map_file (MapFile) – The map file to validate.
Returns:: Language-direction conflict warnings.
Return type:: list[ValidationWarning]

Notes

These are flagged as INFO because the author may have intentional reasons for the naming, or may be using the word in a non-directional sense.

pipeworks_mud_mapper.services.validation_service.has_errors(warnings)[source]

Check if any warnings are errors.

Parameters:: warnings (list[ValidationWarning]) – List of validation warnings.
Returns:: True if any warning has ERROR severity.
Return type:: bool

Examples

>>> warnings = validate_all(map_file)
>>> if has_errors(warnings):
...     print("Fix errors before exporting")

pipeworks_mud_mapper.services.validation_service.filter_by_severity(warnings, severity)[source]

Filter warnings by severity level.

Parameters:

warnings (list[ValidationWarning]) – List of validation warnings.
severity (Severity) – Severity level to filter for.

Returns:

Warnings matching the specified severity.

Return type:

list[ValidationWarning]

Examples

>>> errors = filter_by_severity(warnings, Severity.ERROR)

pipeworks_mud_mapper.services.validation_service.filter_by_category(warnings, category)[source]

Filter warnings by category.

Parameters:

warnings (list[ValidationWarning]) – List of validation warnings.
category (str) – Category to filter for (connectivity, consistency, language).

Returns:

Warnings matching the specified category.

Return type:

list[ValidationWarning]

Examples

>>> conn_issues = filter_by_category(warnings, "connectivity")

pipeworks_mud_mapper.services.validation_service.create_validation_report(map_file_name, warnings)[source]

Create a validation report dictionary.

Creates a structured report suitable for JSON serialization and display in the UI. The report includes a summary with counts by severity and a pass/fail status based on whether any errors exist.

Parameters:

map_file_name (str) – Name of the map file that was validated.
warnings (list[ValidationWarning]) – List of validation warnings from validate_all().

Returns:

Validation report with the following structure:

{
    "timestamp": "2026-02-02T17:00:00Z",
    "map_file": "ledgerfall_alley.map.json",
    "summary": {
        "errors": 0,
        "warnings": 2,
        "info": 3,
        "total": 5,
        "passed": true
    },
    "warnings": [
        {
            "severity": "warning",
            "category": "connectivity",
            "room_id": "room_1",
            "message": "Room is unreachable from spawn"
        }
    ]
}

Return type:

dict

Examples

>>> warnings = validate_all(map_file)
>>> report = create_validation_report("my_zone.map.json", warnings)
>>> if report["summary"]["passed"]:
...     print("Validation passed!")

pipeworks_mud_mapper.services.validation_service.write_validation_report(map_file_name, warnings, output_dir=None)[source]

Write a validation report to a JSON file.

Creates a validation report and writes it to the data/validation/ directory. The file is named after the map file with a .validation.json extension.

Parameters:

map_file_name (str) – Name of the map file that was validated (e.g., “my_zone.map.json”).
warnings (list[ValidationWarning]) – List of validation warnings from validate_all().
output_dir (str, optional) – Directory to write the report to. Defaults to “data/validation/”.

Returns:

Absolute path to the written validation report file.

Return type:

str

Raises:

OSError – If the output directory cannot be created or the file cannot be written.

Examples

>>> warnings = validate_all(map_file)
>>> report_path = write_validation_report("my_zone.map.json", warnings)
>>> print(f"Report written to: {report_path}")

Notes

The validation directory is created if it doesn’t exist. Previous validation reports for the same map file are overwritten.

The report file uses the naming convention: {zone_id}.validation.json where zone_id is extracted from the map file name (e.g., “my_zone.map.json” -> “my_zone.validation.json”).