(** Structured expected messages from Nu validator.

    This module parses Nu validator message strings into structured form,
    enabling semantic comparison rather than string matching. *)

(** Structured expected message *)
type t = {
  message: string;                              (** Full message text *)
  error_code: Html5_checker.Error_code.t option; (** Parsed typed code *)
  line: int option;                             (** Expected line number *)
  column: int option;                           (** Expected column number *)
  element: string option;                       (** Element context *)
  attribute: string option;                     (** Attribute context *)
  severity: [`Error | `Warning | `Info] option; (** Expected severity *)
}

(** Match quality - how well an actual message matches expected *)
type match_quality =
  | Exact_match
      (** Perfect: message, code, and location all match *)
  | Code_match
      (** Error code matches but message text differs slightly *)
  | Message_match
      (** Full message matches but no typed code comparison *)
  | Substring_match
      (** Expected is substring of actual (legacy behavior) *)
  | Severity_mismatch
      (** Right message but wrong severity (error vs warning) *)
  | No_match
      (** Does not match *)

(** Strictness configuration for matching *)
type strictness = {
  require_exact_message: bool;    (** No substring matching *)
  require_error_code: bool;       (** Typed code must match if available *)
  require_location: bool;         (** Line/column must match *)
  require_severity: bool;         (** Severity must match *)
}

(** Lenient matching (current behavior) *)
val lenient : strictness

(** Exact message matching (no substring matching, but doesn't require typed codes) *)
val exact_message : strictness

(** Full strict matching (requires typed error code migration) *)
val strict : strictness

(** Parse a message string into structured form.
    Attempts to recognize Nu validator message patterns and extract
    element, attribute, and error code information. *)
val parse : string -> t

(** Parse a JSON-like structure. For internal use by the message loader. *)
val parse_json_value :
  get_string: (string -> string option) ->
  get_int: (string -> int option) ->
  message_field: string option ->
  t

(** Check if actual message matches expected.
    Returns the quality of match achieved. *)
val matches : strictness:strictness -> expected:t -> actual:Html5_checker.Message.t -> match_quality

(** Check if match quality is acceptable given strictness *)
val is_acceptable : strictness:strictness -> match_quality -> bool

(** Convert match quality to string for reporting *)
val match_quality_to_string : match_quality -> string