ocaml-html5rw / lib / html5_checker / error_code.ml

(** Typed error codes for HTML5 validation messages.

    This module defines a comprehensive variant type for all validation errors,
    ensuring exact message matching with the Nu HTML Validator test suite. *)

(** Severity level of a validation message *)
type severity = Error | Warning | Info

(** Typed error codes with associated data *)
type t =
  (* ===== Attribute Errors ===== *)
  | Attr_not_allowed_on_element of { attr: string; element: string }
      (** Attribute "X" not allowed on element "Y" at this point. *)
  | Attr_not_allowed_here of { attr: string }
      (** Attribute "X" not allowed here. *)
  | Attr_not_allowed_when of { attr: string; element: string; condition: string }
      (** Attribute "X" is only allowed when ... *)
  | Missing_required_attr of { element: string; attr: string }
      (** Element "X" is missing required attribute "Y". *)
  | Missing_required_attr_one_of of { element: string; attrs: string list }
      (** Element "X" is missing one or more of the following attributes: [A, B]. *)
  | Bad_attr_value of { element: string; attr: string; value: string; reason: string }
      (** Bad value "X" for attribute "Y" on element "Z". *)
  | Bad_attr_value_generic of { message: string }
      (** Generic bad attribute value message *)
  | Duplicate_id of { id: string }
      (** Duplicate ID "X". *)
  | Data_attr_invalid_name of { reason: string }
      (** "data-*" attribute names must be XML 1.0 4th ed. plus Namespaces NCNames. *)
  | Data_attr_uppercase
      (** "data-*" attributes must not have characters from the range "A"…"Z" in the name. *)

  (* ===== Element Errors ===== *)
  | Obsolete_element of { element: string; suggestion: string }
      (** The "X" element is obsolete. Y *)
  | Obsolete_attr of { element: string; attr: string; suggestion: string option }
      (** The "X" attribute on the "Y" element is obsolete. *)
  | Obsolete_global_attr of { attr: string; suggestion: string }
      (** The "X" attribute is obsolete. Y *)
  | Element_not_allowed_as_child of { child: string; parent: string }
      (** Element "X" not allowed as child of element "Y" in this context. *)
  | Unknown_element of { name: string }
      (** Unknown element "X". *)
  | Element_must_not_be_descendant of { element: string; attr: string option; ancestor: string }
      (** The element "X" [with attribute "A"] must not appear as a descendant of the "Y" element. *)
  | Missing_required_child of { parent: string; child: string }
      (** Element "X" is missing required child element "Y". *)
  | Missing_required_child_one_of of { parent: string; children: string list }
      (** Element "X" is missing one or more of the following child elements: [A, B]. *)
  | Missing_required_child_generic of { parent: string }
      (** Element "X" is missing a required child element. *)
  | Element_must_not_be_empty of { element: string }
      (** Element "X" must not be empty. *)
  | Stray_start_tag of { tag: string }
      (** Stray start tag "X". *)
  | Stray_end_tag of { tag: string }
      (** Stray end tag "X". *)
  | End_tag_for_void_element of { tag: string }
      (** End tag "X". (for void elements like br) *)
  | Self_closing_non_void
      (** Self-closing syntax used on a non-void HTML element. *)
  | Text_not_allowed of { parent: string }
      (** Text not allowed in element "X" in this context. *)

  (* ===== Child Restrictions ===== *)
  | Div_child_of_dl_bad_role
      (** A "div" child of a "dl" element must not have any "role" value other than "presentation" or "none". *)
  | Li_bad_role_in_menu
      (** An "li" element descendant of role=menu/menubar must have specific roles. *)
  | Li_bad_role_in_tablist
      (** An "li" element descendant of role=tablist must have role=tab. *)
  | Li_bad_role_in_list
      (** An "li" element descendant of ul/ol/menu or role=list must have role=listitem. *)

  (* ===== ARIA Errors ===== *)
  | Unnecessary_role of { role: string; element: string; reason: string }
      (** The "X" role is unnecessary for Y. *)
  | Bad_role of { element: string; role: string }
      (** Bad value "X" for attribute "role" on element "Y". *)
  | Aria_must_not_be_specified of { attr: string; element: string; condition: string }
      (** The "X" attribute must not be specified on any "Y" element unless... *)
  | Aria_must_not_be_used of { attr: string; element: string; condition: string }
      (** The "X" attribute must not be used on an "Y" element which has... *)
  | Aria_should_not_be_used of { attr: string; role: string }
      (** The "X" attribute should not be used on any element which has "role=Y". *)
  | Aria_hidden_on_body
      (** "aria-hidden=true" must not be used on the "body" element. *)
  | Img_empty_alt_with_role
      (** An "img" element with empty alt must not have a role attribute. *)
  | Checkbox_button_needs_aria_pressed
      (** An "input" type="checkbox" with role="button" must have aria-pressed. *)
  | Tab_without_tabpanel
      (** Every active "role=tab" element must have a corresponding "role=tabpanel" element. *)
  | Multiple_main_visible
      (** A document should not include more than one visible element with "role=main". *)
  | Discarding_unrecognized_role of { token: string }
      (** Discarding unrecognized token "X" from value of attribute "role". *)

  (* ===== Required Attribute/Element Conditions ===== *)
  | Img_missing_alt
      (** An "img" element must have an "alt" attribute. *)
  | Img_missing_src_or_srcset
      (** Element "img" is missing one or more of the following attributes: [src, srcset]. *)
  | Option_empty_without_label
      (** Element "option" without attribute "label" must not be empty. *)
  | Bdo_missing_dir
      (** Element "bdo" must have attribute "dir". *)
  | Bdo_dir_auto
      (** The value of "dir" attribute for the "bdo" element must not be "auto". *)
  | Base_missing_href_or_target
      (** Element "base" is missing one or more of the following attributes: [href, target]. *)
  | Base_after_link_script
      (** The "base" element must come before any "link" or "script" elements. *)
  | Link_missing_href
      (** A "link" element must have an "href" or "imagesrcset" attribute. *)
  | Link_as_requires_preload
      (** A "link" element with an "as" attribute must have rel="preload" or "modulepreload". *)
  | Link_imagesrcset_requires_as_image
      (** A "link" element with "imagesrcset" must have as="image". *)
  | Img_ismap_needs_a_href
      (** The "img" element with "ismap" must have an "a" ancestor with "href". *)
  | Sizes_without_srcset
      (** The "sizes" attribute must only be specified if "srcset" is also specified. *)
  | Imagesizes_without_imagesrcset
      (** The "imagesizes" attribute must only be specified if "imagesrcset" is also specified. *)
  | Srcset_w_without_sizes
      (** When the "srcset" attribute has width descriptors, "sizes" must also be specified. *)
  | Source_missing_srcset
      (** Element "source" is missing required attribute "srcset". *)
  | Source_needs_media_or_type
      (** A "source" element with following source/img[srcset] must have media/type. *)
  | Picture_missing_img
      (** Element "picture" is missing required child element "img". *)
  | Map_id_name_mismatch
      (** The "id" attribute on a "map" element must have the same value as the "name" attribute. *)
  | List_attr_requires_datalist
      (** The "list" attribute of "input" must refer to a "datalist" element. *)
  | Input_list_not_allowed
      (** Attribute "list" is only allowed on certain input types. *)
  | Label_too_many_labelable
      (** The "label" element may contain at most one labelable descendant. *)
  | Label_for_id_mismatch
      (** Any "input" descendant of a "label" with "for" must have matching ID. *)
  | Role_on_label_ancestor
      (** The "role" attribute must not be on label ancestor of labelable element. *)
  | Role_on_label_for
      (** The "role" attribute must not be on label associated via for. *)
  | Aria_label_on_label_for
      (** The "aria-label" attribute must not be on label associated via for. *)
  | Input_value_constraint of { constraint_type: string }
      (** The value of the "value" attribute must be... *)
  | Summary_missing_role
      (** Element "summary" is missing required attribute "role". *)
  | Summary_missing_attrs
      (** Element "summary" is missing one or more of [aria-checked, aria-level, role]. *)
  | Summary_role_not_allowed
      (** The "role" attribute must not be used on any "summary" for its parent "details". *)
  | Autocomplete_webauthn_on_select
      (** The value of "autocomplete" for "select" must not contain "webauthn". *)
  | Commandfor_invalid_target
      (** The value of "commandfor" must be the ID of an element in the same tree. *)

  (* ===== Parse Errors ===== *)
  | Forbidden_codepoint of { codepoint: int }
      (** Forbidden code point U+XXXX. *)
  | Char_ref_control of { codepoint: int }
      (** Character reference expands to a control character (U+XXXX). *)
  | Char_ref_non_char of { codepoint: int; astral: bool }
      (** Character reference expands to a [astral] non-character (U+XXXX). *)
  | Char_ref_unassigned
      (** Character reference expands to a permanently unassigned code point. *)
  | Char_ref_zero
      (** Character reference expands to zero. *)
  | Char_ref_out_of_range
      (** Character reference outside the permissible Unicode range. *)
  | Numeric_char_ref_carriage_return
      (** A numeric character reference expanded to carriage return. *)
  | End_of_file_with_open_elements
      (** End of file seen and there were open elements. *)
  | No_element_in_scope of { tag: string }
      (** No "X" element in scope but a "X" end tag seen. *)
  | End_tag_implied_open_elements of { tag: string }
      (** End tag "X" implied, but there were open elements. *)
  | Start_tag_in_table of { tag: string }
      (** Start tag "X" seen in "table". *)
  | Bad_start_tag_in of { tag: string; context: string }
      (** Bad start tag in "X" in "noscript" in "head". *)

  (* ===== Table Errors ===== *)
  | Table_row_no_cells of { row: int }
      (** Row N of an implicit row group has no cells beginning on it. *)
  | Table_cell_overlap
      (** Table cell is overlapped by later table cell. *)
  | Table_cell_spans_rowgroup
      (** Table cell spans past the end of its row group. *)
  | Table_column_no_cells of { column: int; element: string }
      (** Table column N established by element "X" has no cells beginning in it. *)

  (* ===== Language/Internationalization ===== *)
  | Missing_lang_attr
      (** Consider adding a "lang" attribute to the "html" start tag. *)
  | Wrong_lang of { detected: string; declared: string; suggested: string }
      (** This document appears to be written in X but has lang="Y". Consider using "Z". *)
  | Missing_dir_rtl of { language: string }
      (** This document appears to be written in X. Consider adding dir="rtl". *)
  | Wrong_dir of { language: string; declared: string }
      (** This document appears to be written in X but has dir="Y". Consider dir="rtl". *)
  | Xml_lang_without_lang
      (** When xml:lang is specified, lang must also be present with the same value. *)
  | Xml_lang_lang_mismatch
      (** xml:lang and lang must have the same value. *)

  (* ===== Unicode Normalization ===== *)
  | Not_nfc of { replacement: string }
      (** Text run is not in Unicode Normalization Form C. *)

  (* ===== Multiple h1 ===== *)
  | Multiple_h1
      (** Consider using only one "h1" element per document. *)
  | Multiple_autofocus
      (** There must not be two elements with autofocus in the same scoping root. *)

  (* ===== Import Maps ===== *)
  | Importmap_invalid_json
      (** A "script" type="importmap" must have valid JSON content. *)
  | Importmap_invalid_root
      (** A "script" type="importmap" must contain a JSON object with only imports/scopes/integrity. *)
  | Importmap_imports_not_object
      (** The value of "imports" property must be a JSON object. *)
  | Importmap_empty_key
      (** Specifier map must only contain non-empty keys. *)
  | Importmap_non_string_value
      (** Specifier map must only contain string values. *)
  | Importmap_key_trailing_slash
      (** Specifier map values must end with "/" when key ends with "/". *)
  | Importmap_scopes_not_object
      (** The value of "scopes" property must be a JSON object with valid URL keys. *)
  | Importmap_scopes_values_not_object
      (** The value of "scopes" property values must also be JSON objects. *)
  | Importmap_scopes_invalid_url
      (** The "scopes" property keys must be valid URL strings. *)
  | Importmap_scopes_value_invalid_url
      (** The specifier map within "scopes" must only contain valid URL values. *)

  (* ===== Style Element ===== *)
  | Style_type_invalid
      (** The only allowed value for "type" on "style" is "text/css". *)

  (* ===== Headingoffset ===== *)
  | Headingoffset_invalid
      (** The value of "headingoffset" must be a number between "0" and "8". *)

  (* ===== Media Attribute ===== *)
  | Media_empty
      (** Value of "media" attribute here must not be empty. *)
  | Media_all
      (** Value of "media" attribute here must not be "all". *)

  (* ===== SVG/MathML specific ===== *)
  | Svg_deprecated_attr of { attr: string; element: string }
      (** SVG deprecated attribute *)
  | Missing_required_svg_attr of { element: string; attr: string }
      (** Element "X" is missing required attribute "Y". (SVG) *)

  (* ===== Generic/Fallback ===== *)
  | Generic of { message: string }
      (** For messages that don't fit any specific pattern *)

(** Get the severity level for an error code *)
let severity = function
  | Missing_lang_attr -> Info
  | Multiple_h1 -> Info
  | Wrong_lang _ -> Warning
  | Missing_dir_rtl _ -> Warning
  | Wrong_dir _ -> Warning
  | Unnecessary_role _ -> Warning
  | Aria_should_not_be_used _ -> Warning
  | Unknown_element _ -> Warning
  | Not_nfc _ -> Warning
  | _ -> Error

(** Get a short code string for categorization *)
let code_string = function
  | Attr_not_allowed_on_element _ -> "disallowed-attribute"
  | Attr_not_allowed_here _ -> "disallowed-attribute"
  | Attr_not_allowed_when _ -> "disallowed-attribute"
  | Missing_required_attr _ -> "missing-required-attribute"
  | Missing_required_attr_one_of _ -> "missing-required-attribute"
  | Bad_attr_value _ -> "bad-attribute-value"
  | Bad_attr_value_generic _ -> "bad-attribute-value"
  | Duplicate_id _ -> "duplicate-id"
  | Data_attr_invalid_name _ -> "bad-attribute-name"
  | Data_attr_uppercase -> "bad-attribute-name"
  | Obsolete_element _ -> "obsolete-element"
  | Obsolete_attr _ -> "obsolete-attribute"
  | Obsolete_global_attr _ -> "obsolete-attribute"
  | Element_not_allowed_as_child _ -> "disallowed-child"
  | Unknown_element _ -> "unknown-element"
  | Element_must_not_be_descendant _ -> "prohibited-ancestor"
  | Missing_required_child _ -> "missing-required-child"
  | Missing_required_child_one_of _ -> "missing-required-child"
  | Missing_required_child_generic _ -> "missing-required-child"
  | Element_must_not_be_empty _ -> "empty-element"
  | Stray_start_tag _ -> "stray-tag"
  | Stray_end_tag _ -> "stray-tag"
  | End_tag_for_void_element _ -> "end-tag-void"
  | Self_closing_non_void -> "self-closing-non-void"
  | Text_not_allowed _ -> "text-not-allowed"
  | Div_child_of_dl_bad_role -> "invalid-role"
  | Li_bad_role_in_menu -> "invalid-role"
  | Li_bad_role_in_tablist -> "invalid-role"
  | Li_bad_role_in_list -> "invalid-role"
  | Unnecessary_role _ -> "unnecessary-role"
  | Bad_role _ -> "bad-role"
  | Aria_must_not_be_specified _ -> "aria-not-allowed"
  | Aria_must_not_be_used _ -> "aria-not-allowed"
  | Aria_should_not_be_used _ -> "aria-not-allowed"
  | Aria_hidden_on_body -> "aria-not-allowed"
  | Img_empty_alt_with_role -> "img-alt-role"
  | Checkbox_button_needs_aria_pressed -> "missing-aria-pressed"
  | Tab_without_tabpanel -> "tab-without-tabpanel"
  | Multiple_main_visible -> "multiple-main"
  | Discarding_unrecognized_role _ -> "unrecognized-role"
  | Img_missing_alt -> "missing-alt"
  | Img_missing_src_or_srcset -> "missing-src"
  | Option_empty_without_label -> "empty-option"
  | Bdo_missing_dir -> "missing-dir"
  | Bdo_dir_auto -> "bdo-dir-auto"
  | Base_missing_href_or_target -> "missing-required-attribute"
  | Base_after_link_script -> "base-position"
  | Link_missing_href -> "missing-href"
  | Link_as_requires_preload -> "link-as-preload"
  | Link_imagesrcset_requires_as_image -> "link-imagesrcset"
  | Img_ismap_needs_a_href -> "ismap-needs-href"
  | Sizes_without_srcset -> "sizes-without-srcset"
  | Imagesizes_without_imagesrcset -> "imagesizes-without-srcset"
  | Srcset_w_without_sizes -> "srcset-needs-sizes"
  | Source_missing_srcset -> "missing-srcset"
  | Source_needs_media_or_type -> "source-needs-media"
  | Picture_missing_img -> "picture-missing-img"
  | Map_id_name_mismatch -> "map-id-name"
  | List_attr_requires_datalist -> "list-datalist"
  | Input_list_not_allowed -> "list-not-allowed"
  | Label_too_many_labelable -> "label-multiple"
  | Label_for_id_mismatch -> "label-for-mismatch"
  | Role_on_label_ancestor -> "role-on-label"
  | Role_on_label_for -> "role-on-label"
  | Aria_label_on_label_for -> "aria-label-on-label"
  | Input_value_constraint _ -> "input-value"
  | Summary_missing_role -> "summary-role"
  | Summary_missing_attrs -> "summary-attrs"
  | Summary_role_not_allowed -> "summary-role"
  | Autocomplete_webauthn_on_select -> "autocomplete"
  | Commandfor_invalid_target -> "commandfor"
  | Forbidden_codepoint _ -> "forbidden-codepoint"
  | Char_ref_control _ -> "char-ref-control"
  | Char_ref_non_char _ -> "char-ref-non-char"
  | Char_ref_unassigned -> "char-ref-unassigned"
  | Char_ref_zero -> "char-ref-zero"
  | Char_ref_out_of_range -> "char-ref-range"
  | Numeric_char_ref_carriage_return -> "numeric-char-ref"
  | End_of_file_with_open_elements -> "eof-open-elements"
  | No_element_in_scope _ -> "no-element-in-scope"
  | End_tag_implied_open_elements _ -> "end-tag-implied"
  | Start_tag_in_table _ -> "start-tag-in-table"
  | Bad_start_tag_in _ -> "bad-start-tag"
  | Table_row_no_cells _ -> "table-row"
  | Table_cell_overlap -> "table-overlap"
  | Table_cell_spans_rowgroup -> "table-span"
  | Table_column_no_cells _ -> "table-column"
  | Missing_lang_attr -> "missing-lang"
  | Wrong_lang _ -> "wrong-lang"
  | Missing_dir_rtl _ -> "missing-dir"
  | Wrong_dir _ -> "wrong-dir"
  | Xml_lang_without_lang -> "xml-lang"
  | Xml_lang_lang_mismatch -> "xml-lang-mismatch"
  | Not_nfc _ -> "unicode-normalization"
  | Multiple_h1 -> "multiple-h1"
  | Multiple_autofocus -> "multiple-autofocus"
  | Importmap_invalid_json -> "importmap"
  | Importmap_invalid_root -> "importmap"
  | Importmap_imports_not_object -> "importmap"
  | Importmap_empty_key -> "importmap"
  | Importmap_non_string_value -> "importmap"
  | Importmap_key_trailing_slash -> "importmap"
  | Importmap_scopes_not_object -> "importmap"
  | Importmap_scopes_values_not_object -> "importmap"
  | Importmap_scopes_invalid_url -> "importmap"
  | Importmap_scopes_value_invalid_url -> "importmap"
  | Style_type_invalid -> "style-type"
  | Headingoffset_invalid -> "headingoffset"
  | Media_empty -> "media-empty"
  | Media_all -> "media-all"
  | Svg_deprecated_attr _ -> "svg-deprecated"
  | Missing_required_svg_attr _ -> "missing-required-attribute"
  | Generic _ -> "generic"

(** Format using curly quotes (Unicode) *)
let q s = "\xe2\x80\x9c" ^ s ^ "\xe2\x80\x9d"

(** Convert error code to exact Nu validator message string *)
let to_message = function
  | Attr_not_allowed_on_element { attr; element } ->
      Printf.sprintf "Attribute %s not allowed on element %s at this point."
        (q attr) (q element)
  | Attr_not_allowed_here { attr } ->
      Printf.sprintf "Attribute %s not allowed here." (q attr)
  | Attr_not_allowed_when { attr; element = _; condition } ->
      Printf.sprintf "The %s attribute must not be used on any element which has %s." (q attr) condition
  | Missing_required_attr { element; attr } ->
      Printf.sprintf "Element %s is missing required attribute %s."
        (q element) (q attr)
  | Missing_required_attr_one_of { element; attrs } ->
      let attrs_str = String.concat ", " attrs in
      Printf.sprintf "Element %s is missing one or more of the following attributes: [%s]."
        (q element) attrs_str
  | Bad_attr_value { element; attr; value; reason } ->
      Printf.sprintf "Bad value %s for attribute %s on element %s: %s"
        (q value) (q attr) (q element) reason
  | Bad_attr_value_generic { message } -> message
  | Duplicate_id { id } ->
      Printf.sprintf "Duplicate ID %s." (q id)
  | Data_attr_invalid_name { reason } ->
      Printf.sprintf "%s attribute names %s." (q "data-*") reason
  | Data_attr_uppercase ->
      Printf.sprintf "%s attributes must not have characters from the range %s\xe2\x80\xa6%s in the name."
        (q "data-*") (q "A") (q "Z")

  | Obsolete_element { element; suggestion } ->
      if suggestion = "" then
        Printf.sprintf "The %s element is obsolete." (q element)
      else
        Printf.sprintf "The %s element is obsolete. %s" (q element) suggestion
  | Obsolete_attr { element; attr; suggestion } ->
      let base = Printf.sprintf "The %s attribute on the %s element is obsolete."
        (q attr) (q element) in
      (match suggestion with Some s -> base ^ " " ^ s | None -> base)
  | Obsolete_global_attr { attr; suggestion } ->
      Printf.sprintf "The %s attribute is obsolete. %s" (q attr) suggestion
  | Element_not_allowed_as_child { child; parent } ->
      Printf.sprintf "Element %s not allowed as child of element %s in this context. (Suppressing further errors from this subtree.)"
        (q child) (q parent)
  | Unknown_element { name } ->
      Printf.sprintf "Unknown element %s." (q name)
  | Element_must_not_be_descendant { element; attr; ancestor } ->
      (match attr with
       | Some a ->
           Printf.sprintf "The element %s with the attribute %s must not appear as a descendant of the %s element."
             (q element) (q a) (q ancestor)
       | None ->
           Printf.sprintf "The element %s must not appear as a descendant of the %s element."
             (q element) (q ancestor))
  | Missing_required_child { parent; child } ->
      Printf.sprintf "Element %s is missing required child element %s."
        (q parent) (q child)
  | Missing_required_child_one_of { parent; children } ->
      let children_str = String.concat ", " children in
      Printf.sprintf "Element %s is missing one or more of the following child elements: [%s]."
        (q parent) children_str
  | Missing_required_child_generic { parent } ->
      Printf.sprintf "Element %s is missing a required child element." (q parent)
  | Element_must_not_be_empty { element } ->
      Printf.sprintf "Element %s must not be empty." (q element)
  | Stray_start_tag { tag } ->
      Printf.sprintf "Stray start tag %s." (q tag)
  | Stray_end_tag { tag } ->
      Printf.sprintf "Stray end tag %s." (q tag)
  | End_tag_for_void_element { tag } ->
      Printf.sprintf "End tag %s." (q tag)
  | Self_closing_non_void ->
      Printf.sprintf "Self-closing syntax (%s) used on a non-void HTML element. Ignoring the slash and treating as a start tag."
        (q "/>")
  | Text_not_allowed { parent } ->
      Printf.sprintf "Text not allowed in element %s in this context." (q parent)

  | Div_child_of_dl_bad_role ->
      Printf.sprintf "A %s child of a %s element must not have any %s value other than %s or %s."
        (q "div") (q "dl") (q "role") (q "presentation") (q "none")
  | Li_bad_role_in_menu ->
      Printf.sprintf "An %s element that is a descendant of a %s element or %s element must not have any %s value other than %s, %s, %s, %s, or %s."
        (q "li") (q "role=menu") (q "role=menubar") (q "role")
        (q "group") (q "menuitem") (q "menuitemcheckbox") (q "menuitemradio") (q "separator")
  | Li_bad_role_in_tablist ->
      Printf.sprintf "An %s element that is a descendant of a %s element must not have any %s value other than %s."
        (q "li") (q "role=tablist") (q "role") (q "tab")
  | Li_bad_role_in_list ->
      Printf.sprintf "An %s element that is a descendant of a %s, %s, or %s element with no explicit %s value, or a descendant of a %s element, must not have any %s value other than %s."
        (q "li") (q "ul") (q "ol") (q "menu") (q "role") (q "role=list") (q "role") (q "listitem")

  | Unnecessary_role { role; element = _; reason } ->
      Printf.sprintf "The %s role is unnecessary %s."
        (q role) reason
  | Bad_role { element; role } ->
      Printf.sprintf "Bad value %s for attribute %s on element %s."
        (q role) (q "role") (q element)
  | Aria_must_not_be_specified { attr; element; condition } ->
      Printf.sprintf "The %s attribute must not be specified on any %s element unless %s."
        (q attr) (q element) condition
  | Aria_must_not_be_used { attr; element; condition } ->
      Printf.sprintf "The %s attribute must not be used on an %s element which has %s."
        (q attr) (q element) condition
  | Aria_should_not_be_used { attr; role } ->
      Printf.sprintf "The %s attribute should not be used on any element which has %s."
        (q attr) (q ("role=" ^ role))
  | Aria_hidden_on_body ->
      Printf.sprintf "%s must not be used on the %s element."
        (q "aria-hidden=true") (q "body")
  | Img_empty_alt_with_role ->
      Printf.sprintf "An %s element which has an %s attribute whose value is the empty string must not have a %s attribute."
        (q "img") (q "alt") (q "role")
  | Checkbox_button_needs_aria_pressed ->
      Printf.sprintf "An %s element with a %s attribute whose value is %s and with a %s attribute whose value is %s must have an %s attribute."
        (q "input") (q "type") (q "checkbox") (q "role") (q "button") (q "aria-pressed")
  | Tab_without_tabpanel ->
      Printf.sprintf "Every active %s element must have a corresponding %s element."
        (q "role=tab") (q "role=tabpanel")
  | Multiple_main_visible ->
      Printf.sprintf "A document should not include more than one visible element with %s."
        (q "role=main")
  | Discarding_unrecognized_role { token } ->
      Printf.sprintf "Discarding unrecognized token %s from value of attribute %s. Browsers ignore any token that is not a defined ARIA non-abstract role."
        (q token) (q "role")

  | Img_missing_alt ->
      Printf.sprintf "An %s element must have an %s attribute, except under certain conditions. For details, consult guidance on providing text alternatives for images."
        (q "img") (q "alt")
  | Img_missing_src_or_srcset ->
      Printf.sprintf "Element %s is missing one or more of the following attributes: [src, srcset]."
        (q "img")
  | Option_empty_without_label ->
      Printf.sprintf "Element %s without attribute %s must not be empty."
        (q "option") (q "label")
  | Bdo_missing_dir ->
      Printf.sprintf "Element %s must have attribute %s." (q "bdo") (q "dir")
  | Bdo_dir_auto ->
      Printf.sprintf "The value of %s attribute for the %s element must not be %s."
        (q "dir") (q "bdo") (q "auto")
  | Base_missing_href_or_target ->
      Printf.sprintf "Element %s is missing one or more of the following attributes: [href, target]."
        (q "base")
  | Base_after_link_script ->
      Printf.sprintf "The %s element must come before any %s or %s elements in the document."
        (q "base") (q "link") (q "script")
  | Link_missing_href ->
      Printf.sprintf "A %s element must have an %s or %s attribute, or both."
        (q "link") (q "href") (q "imagesrcset")
  | Link_as_requires_preload ->
      Printf.sprintf "A %s element with an %s attribute must have a %s attribute that contains the value %s or the value %s."
        (q "link") (q "as") (q "rel") (q "preload") (q "modulepreload")
  | Link_imagesrcset_requires_as_image ->
      Printf.sprintf "A %s element with an %s attribute must have an %s attribute with value %s."
        (q "link") (q "imagesrcset") (q "as") (q "image")
  | Img_ismap_needs_a_href ->
      Printf.sprintf "The %s element with the %s attribute set must have an %s ancestor with the %s attribute."
        (q "img") (q "ismap") (q "a") (q "href")
  | Sizes_without_srcset ->
      Printf.sprintf "The %s attribute must only be specified if the %s attribute is also specified."
        (q "sizes") (q "srcset")
  | Imagesizes_without_imagesrcset ->
      Printf.sprintf "The %s attribute must only be specified if the %s attribute is also specified."
        (q "imagesizes") (q "imagesrcset")
  | Srcset_w_without_sizes ->
      Printf.sprintf "When the %s attribute has any image candidate string with a width descriptor, the %s attribute must also be specified."
        (q "srcset") (q "sizes")
  | Source_missing_srcset ->
      Printf.sprintf "Element %s is missing required attribute %s."
        (q "source") (q "srcset")
  | Source_needs_media_or_type ->
      Printf.sprintf "A %s element that has a following sibling %s element or %s element with a %s attribute must have a %s attribute and/or %s attribute."
        (q "source") (q "source") (q "img") (q "srcset") (q "media") (q "type")
  | Picture_missing_img ->
      Printf.sprintf "Element %s is missing required child element %s."
        (q "picture") (q "img")
  | Map_id_name_mismatch ->
      Printf.sprintf "The %s attribute on a %s element must have an the same value as the %s attribute."
        (q "id") (q "map") (q "name")
  | List_attr_requires_datalist ->
      Printf.sprintf "The %s attribute of the %s element must refer to a %s element."
        (q "list") (q "input") (q "datalist")
  | Input_list_not_allowed ->
      Printf.sprintf "Attribute %s is only allowed when the input type is %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, or %s."
        (q "list") (q "color") (q "date") (q "datetime-local") (q "email") (q "month")
        (q "number") (q "range") (q "search") (q "tel") (q "text") (q "time") (q "url") (q "week")
  | Label_too_many_labelable ->
      Printf.sprintf "The %s element may contain at most one %s, %s, %s, %s, %s, %s, or %s descendant."
        (q "label") (q "button") (q "input") (q "meter") (q "output") (q "progress") (q "select") (q "textarea")
  | Label_for_id_mismatch ->
      Printf.sprintf "Any %s descendant of a %s element with a %s attribute must have an ID value that matches that %s attribute."
        (q "input") (q "label") (q "for") (q "for")
  | Role_on_label_ancestor ->
      Printf.sprintf "The %s attribute must not be used on any %s element that is an ancestor of a labelable element."
        (q "role") (q "label")
  | Role_on_label_for ->
      Printf.sprintf "The %s attribute must not be used on any %s element that is associated with a labelable element."
        (q "role") (q "label")
  | Aria_label_on_label_for ->
      Printf.sprintf "The %s attribute must not be used on any %s element that is associated with a labelable element."
        (q "aria-label") (q "label")
  | Input_value_constraint { constraint_type } -> constraint_type
  | Summary_missing_role ->
      Printf.sprintf "Element %s is missing required attribute %s."
        (q "summary") (q "role")
  | Summary_missing_attrs ->
      Printf.sprintf "Element %s is missing one or more of the following attributes: [aria-checked, aria-level, role]."
        (q "summary")
  | Summary_role_not_allowed ->
      Printf.sprintf "The %s attribute must not be used on any %s element that is a summary for its parent %s element."
        (q "role") (q "summary") (q "details")
  | Autocomplete_webauthn_on_select ->
      Printf.sprintf "The value of the %s attribute for the %s element must not contain %s."
        (q "autocomplete") (q "select") (q "webauthn")
  | Commandfor_invalid_target ->
      Printf.sprintf "The value of the %s attribute of the %s element must be the ID of an element in the same tree as the %s with the %s attribute."
        (q "commandfor") (q "button") (q "button") (q "commandfor")

  | Forbidden_codepoint { codepoint } ->
      Printf.sprintf "Forbidden code point U+%04x." codepoint
  | Char_ref_control { codepoint } ->
      Printf.sprintf "Character reference expands to a control character (U+%04x)." codepoint
  | Char_ref_non_char { codepoint; astral } ->
      if astral then
        Printf.sprintf "Character reference expands to an astral non-character (U+%05x)." codepoint
      else
        Printf.sprintf "Character reference expands to a non-character (U+%04x)." codepoint
  | Char_ref_unassigned ->
      "Character reference expands to a permanently unassigned code point."
  | Char_ref_zero ->
      "Character reference expands to zero."
  | Char_ref_out_of_range ->
      "Character reference outside the permissible Unicode range."
  | Numeric_char_ref_carriage_return ->
      "A numeric character reference expanded to carriage return."
  | End_of_file_with_open_elements ->
      "End of file seen and there were open elements."
  | No_element_in_scope { tag } ->
      Printf.sprintf "No %s element in scope but a %s end tag seen."
        (q tag) (q tag)
  | End_tag_implied_open_elements { tag } ->
      Printf.sprintf "End tag %s implied, but there were open elements."
        (q tag)
  | Start_tag_in_table { tag } ->
      Printf.sprintf "Start tag %s seen in %s." (q tag) (q "table")
  | Bad_start_tag_in { tag; context = _ } ->
      Printf.sprintf "Bad start tag in %s in %s in %s."
        (q tag) (q "noscript") (q "head")

  | Table_row_no_cells { row } ->
      Printf.sprintf "Row %d of an implicit row group has no cells beginning on it." row
  | Table_cell_overlap ->
      "Table cell is overlapped by later table cell."
  | Table_cell_spans_rowgroup ->
      Printf.sprintf "Table cell spans past the end of its row group established by a %s element; clipped to the end of the row group."
        (q "tbody")
  | Table_column_no_cells { column; element } ->
      Printf.sprintf "Table column %d established by element %s has no cells beginning in it."
        column (q element)

  | Missing_lang_attr ->
      Printf.sprintf "Consider adding a %s attribute to the %s start tag to declare the language of this document."
        (q "lang") (q "html")
  | Wrong_lang { detected; declared; suggested } ->
      Printf.sprintf "This document appears to be written in %s but the %s start tag has %s. Consider using %s (or variant) instead."
        detected (q "html") (q ("lang=\"" ^ declared ^ "\"")) (q ("lang=\"" ^ suggested ^ "\""))
  | Missing_dir_rtl { language } ->
      Printf.sprintf "This document appears to be written in %s. Consider adding %s to the %s start tag."
        language (q "dir=\"rtl\"") (q "html")
  | Wrong_dir { language; declared } ->
      Printf.sprintf "This document appears to be written in %s but the %s start tag has %s. Consider using %s instead."
        language (q "html") (q ("dir=\"" ^ declared ^ "\"")) (q "dir=\"rtl\"")
  | Xml_lang_without_lang ->
      Printf.sprintf "When the attribute %s in no namespace is specified, the element must also have the attribute %s present with the same value."
        (q "xml:lang") (q "lang")
  | Xml_lang_lang_mismatch ->
      Printf.sprintf "The %s and %s attributes must have the same value."
        (q "xml:lang") (q "lang")

  | Not_nfc { replacement } ->
      Printf.sprintf "Text run is not in Unicode Normalization Form C. Should instead be %s. (Copy and paste that into your source document to replace the un-normalized text.)"
        (q replacement)

  | Multiple_h1 ->
      Printf.sprintf "Consider using only one %s element per document (or, if using %s elements multiple times is required, consider using the %s attribute to indicate that these %s elements are not all top-level headings)."
        (q "h1") (q "h1") (q "headingoffset") (q "h1")
  | Multiple_autofocus ->
      Printf.sprintf "There must not be two elements with the same %s that both have the %s attribute specified."
        (q "nearest ancestor autofocus scoping root element") (q "autofocus")

  | Importmap_invalid_json ->
      Printf.sprintf "A script %s with a %s attribute whose value is %s must have valid JSON content."
        (q "script") (q "type") (q "importmap")
  | Importmap_invalid_root ->
      Printf.sprintf "A %s element with a %s attribute whose value is %s must contain a JSON object with no properties other than %s, %s, and %s."
        (q "script") (q "type") (q "importmap") (q "imports") (q "scopes") (q "integrity")
  | Importmap_imports_not_object ->
      Printf.sprintf "The value of the %s property within the content of a %s element with a %s attribute whose value is %s must be a JSON object."
        (q "imports") (q "script") (q "type") (q "importmap")
  | Importmap_empty_key ->
      Printf.sprintf "A specifier map defined in a %s property within the content of a %s element with a %s attribute whose value is %s must only contain non-empty keys."
        (q "imports") (q "script") (q "type") (q "importmap")
  | Importmap_non_string_value ->
      Printf.sprintf "A specifier map defined in a %s property within the content of a %s element with a %s attribute whose value is %s must only contain string values."
        (q "imports") (q "script") (q "type") (q "importmap")
  | Importmap_key_trailing_slash ->
      Printf.sprintf "A specifier map defined in a %s property within the content of a %s element with a %s attribute whose value is %s must have values that end with %s when its corresponding key ends with %s."
        (q "imports") (q "script") (q "type") (q "importmap") (q "/") (q "/")
  | Importmap_scopes_not_object ->
      Printf.sprintf "The value of the %s property within the content of a %s element with a %s attribute whose value is %s must be a JSON object whose keys are valid URL strings."
        (q "scopes") (q "script") (q "type") (q "importmap")
  | Importmap_scopes_values_not_object ->
      Printf.sprintf "The value of the %s property within the content of a %s element with a %s attribute whose value is %s must be a JSON object whose values are also JSON objects."
        (q "scopes") (q "script") (q "type") (q "importmap")
  | Importmap_scopes_invalid_url ->
      Printf.sprintf "The value of the %s property within the content of a %s element with a %s attribute whose value is %s must be a JSON object whose keys are valid URL strings."
        (q "scopes") (q "script") (q "type") (q "importmap")
  | Importmap_scopes_value_invalid_url ->
      Printf.sprintf "A specifier map defined in a %s property within the content of a %s element with a %s attribute whose value is %s must only contain valid URL values."
        (q "scopes") (q "script") (q "type") (q "importmap")

  | Style_type_invalid ->
      Printf.sprintf "The only allowed value for the %s attribute for the %s element is %s (with no parameters). (But the attribute is not needed and should be omitted altogether.)"
        (q "type") (q "style") (q "text/css")

  | Headingoffset_invalid ->
      Printf.sprintf "The value of the %s attribute must be a number between %s and %s."
        (q "headingoffset") (q "0") (q "8")

  | Media_empty ->
      Printf.sprintf "Value of %s attribute here must not be empty." (q "media")
  | Media_all ->
      Printf.sprintf "Value of %s attribute here must not be %s." (q "media") (q "all")

  | Svg_deprecated_attr { attr; element } ->
      Printf.sprintf "Attribute %s not allowed on element %s at this point."
        (q attr) (q element)
  | Missing_required_svg_attr { element; attr } ->
      Printf.sprintf "Element %s is missing required attribute %s."
        (q element) (q attr)

  | Generic { message } -> message