validation.hpp File Reference

The validation vocabulary: the severity scale, the single finding and the report validate() fills. More...

#include <meta>
#include <algorithm>
#include <concepts>
#include <cstddef>
#include <cstdint>
#include <format>
#include <limits>
#include <string>
#include <string_view>
#include <type_traits>
#include <vector>
#include <welder/vocabulary.hpp>
#include <wowlib/core/client_version.hpp>
#include <wowlib/core/error.hpp>
#include <wowlib/formats/common/entity_reflect.hpp>

Include dependency graph for validation.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	wowlib::formats::ValidationIssue
	One validate() finding: where it is, how bad it is, and what is wrong. More...
class	wowlib::formats::ValidationReport

Namespaces
namespace	wowlib
namespace	wowlib::formats
namespace	wowlib::formats::detail

Concepts
concept	wowlib::formats::VersionedEntity
	An entity the walker can gate by client version: anything carrying the static constexpr ClientVersion version every format entity declares (chunked files, M2 offset blocks, ADT tiles and map chunks alike).
concept	wowlib::formats::detail::ValidatableSequence
	A member the walker can iterate element-wise: std::vector, std::array, Repeated<> and std::string all qualify.
concept	wowlib::formats::detail::SlotSequence
	A container of independent SLOTS rather than one logical array — a chunk that may appear several times, each occurrence complete in itself (Repeated<>, opting in with ValidationSlots).
concept	wowlib::formats::detail::HasValidateExtra
	A type carrying the imperative half of its contracts (see the validateExtra hook).

Enumerations
enum class	wowlib::formats::ValidationSeverity : std::uint8_t { wowlib::formats::Warning , wowlib::formats::Error }
	How a validation finding affects the file's fitness for the client. More...

Functions
consteval bool	wowlib::formats::detail::hasValidationAnnotation (std::meta::info member)
	Whether member carries any validation annotation.
template<typename T>
consteval bool	wowlib::formats::detail::hasValidationContent ()
	Whether validating a T can produce anything — it declares a validateExtra hook, carries an annotated member, or (recursively) holds something that does.
template<typename Values>
void	wowlib::formats::detail::validateIndexElements (const Values &values, std::size_t targetCount, std::string_view member, std::string_view target, ValidationReport &report)
	Report every element of values that is not a valid index into a targetCount-element target, capped so a corrupt file cannot flood the report.
template<std::integral T>
constexpr bool	wowlib::formats::detail::isNoIndex (T value)
	Whether value is the client's "no reference" sentinel for an index element: negative in a signed lookup, all-ones in an unsigned one (the 0xFFFF an M2 lookup table leaves in unused slots).
template<typename Values>
void	wowlib::formats::detail::validateOptionalIndexElements (const Values &values, std::size_t targetCount, std::string_view member, std::string_view target, ValidationReport &report)
	Report every non-sentinel element of values that is not a valid index into a targetCount-element target (see isNoIndex and the indexesOptional annotation); capped like validateIndexElements.
void	wowlib::formats::detail::validateCountMatches (std::size_t count, std::uint32_t scale, std::size_t targetCount, std::string_view member, std::string_view target, ValidationReport &report)
	Apply one member's countMatches contract against its resolved sibling count (see the annotation): engaged (non-empty) values only.
template<ClientVersion V, typename T>
void	wowlib::formats::detail::validateValue (const T &value, ValidationReport &report)
	Validate one value of any shape: a versioned entity (gated by its OWN version), a plain record (gated by the enclosing V), or a sequence of either (walked element-wise, paths subscripted).
template<ClientVersion V, typename T>
void	wowlib::formats::detail::validateMembers (const T &value, ValidationReport &report)
	Walk value's annotation-declared contracts, gating members by client version V and descending into everything with validation content.
template<VersionedEntity E>
void	wowlib::formats::detail::validateEntity (const E &entity, ValidationReport &report)
	Validate a whole entity — the engine behind every validate() method; see ChunkedFile::validate() for the contract.

Detailed Description

The validation vocabulary: the severity scale, the single finding and the report validate() fills.

Validation is a SEPARATE pass from write() — the serializer never runs it — asserting the logical integrity contracts a file must satisfy to load in the client (companion-chunk counts, index ranges, flag/presence coherence). Entities declare the machine-checkable contracts as annotations (see annotations.hpp); everything the annotations cannot express lives in per-entity validateExtra hooks. The walker driving both is detail::validateEntity (chunked_file.hpp).

Severity policy: an ERROR means the client would misread (or crash on) a file written in this state; a WARNING marks a state real client files ship regardless — a freshly read, unmodified client file must validate with zero errors, and the integration corpus asserts exactly that.

Definition in file validation.hpp.