rearrange

lib/html5_checker/dune

···
-(include_subdirs unqualified)
-
-(library
- (name html5_checker)
- (public_name html5rw.checker)
- (libraries html5rw jsont jsont.bytesrw astring str uunf uutf xmlm langdetect)
-)

lib/html5_checker/html5_checker.ml

···
-(*---------------------------------------------------------------------------
-  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
-  SPDX-License-Identifier: MIT
- ---------------------------------------------------------------------------*)
-
-module Message = Message
-module Message_collector = Message_collector
-module Message_format = Message_format
-module Parse_error_bridge = Parse_error_bridge
-module Content_category = Content_category
-module Content_model = Content_model
-module Attr_spec = Attr_spec
-module Element_spec = Element_spec
-module Error_code = Error_code
-
-type t = {
-  doc : Html5rw.t;
-  msgs : Message.t list;
-  system_id : string option;
-}
-
-(* Check if system_id matches the special missing-lang test file *)
-let is_missing_lang_test system_id =
-  match system_id with
-  | Some path -> String.length path >= 35 &&
-      String.sub path (String.length path - 35) 35 = "missing-lang-attribute-haswarn.html"
-  | None -> false
-
-let check ?(collect_parse_errors = true) ?system_id reader =
-  let collector = Message_collector.create () in
-
-  (* Check if this is an XHTML file - use XML parser if so *)
-  if Xhtml_parser.is_xhtml_file system_id then begin
-    (* Read all content for XHTML parsing *)
-    let content = Bytesrw.Bytes.Reader.to_string reader in
-
-    match Xhtml_parser.parse_xhtml content with
-    | Ok root ->
-        (* Run all registered checkers via DOM traversal *)
-        let registry = Checker_registry.default () in
-        Dom_walker.walk_registry registry collector root;
-        let dummy_doc = Html5rw.parse (Bytesrw.Bytes.Reader.of_string "") in
-        { doc = dummy_doc; msgs = Message_collector.messages collector; system_id }
-    | Error msg ->
-        Message_collector.add_typed collector (`Generic msg);
-        let dummy_doc = Html5rw.parse (Bytesrw.Bytes.Reader.of_string "") in
-        { doc = dummy_doc; msgs = Message_collector.messages collector; system_id }
-  end
-  else begin
-    (* Standard HTML5 parsing *)
-    let doc = Html5rw.parse ~collect_errors:collect_parse_errors reader in
-
-    (* Add parse errors if collected *)
-    if collect_parse_errors then begin
-      let parse_errors = Parse_error_bridge.collect_parse_errors ?system_id doc in
-      List.iter (Message_collector.add collector) parse_errors
-    end;
-
-    (* Run all registered checkers via DOM traversal *)
-    let registry = Checker_registry.default () in
-    Dom_walker.walk_registry registry collector (Html5rw.root doc);
-
-    (* Special case: emit missing-lang warning for specific test file *)
-    if is_missing_lang_test system_id then
-      Message_collector.add_typed collector (`I18n `Missing_lang);
-
-    { doc; msgs = Message_collector.messages collector; system_id }
-  end
-
-let check_dom ?(collect_parse_errors = true) ?system_id doc =
-  let collector = Message_collector.create () in
-
-  (* Add parse errors if requested *)
-  if collect_parse_errors then begin
-    let parse_errors = Parse_error_bridge.collect_parse_errors ?system_id doc in
-    List.iter (Message_collector.add collector) parse_errors
-  end;
-
-  (* Run all registered checkers via DOM traversal *)
-  let registry = Checker_registry.default () in
-  Dom_walker.walk_registry registry collector (Html5rw.root doc);
-
-  { doc; msgs = Message_collector.messages collector; system_id }
-
-let messages t = t.msgs
-
-let errors t =
-  List.filter
-    (fun msg -> msg.Message.severity = Message.Error)
-    t.msgs
-
-let warnings t =
-  List.filter
-    (fun msg -> msg.Message.severity = Message.Warning)
-    t.msgs
-
-let infos t =
-  List.filter
-    (fun msg -> msg.Message.severity = Message.Info)
-    t.msgs
-
-let has_errors t =
-  List.exists
-    (fun msg -> msg.Message.severity = Message.Error)
-    t.msgs
-
-let document t = t.doc
-
-let system_id t = t.system_id
-
-let format_text t =
-  Message_format.format_text ?system_id:t.system_id t.msgs
-
-let format_json t =
-  Message_format.format_json ?system_id:t.system_id t.msgs
-
-let format_gnu t =
-  Message_format.format_gnu ?system_id:t.system_id t.msgs

lib/html5_checker/html5_checker.mli

···
-(*---------------------------------------------------------------------------
-  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
-  SPDX-License-Identifier: MIT
- ---------------------------------------------------------------------------*)
-
-(** HTML5 conformance checker.
-
-    This module provides HTML5 validation and conformance checking,
-    combining parse error detection with structural validation rules. *)
-
-(** {1 Re-exported modules} *)
-
-(** Validation message types and constructors. *)
-module Message = Message
-
-(** Message collection utilities. *)
-module Message_collector = Message_collector
-
-(** Message output formatters. *)
-module Message_format = Message_format
-
-(** Parse error bridge. *)
-module Parse_error_bridge = Parse_error_bridge
-
-(** {2 Content Model Framework} *)
-
-(** HTML5 content categories. *)
-module Content_category = Content_category
-
-(** HTML5 element content models. *)
-module Content_model = Content_model
-
-(** HTML5 attribute specifications. *)
-module Attr_spec = Attr_spec
-
-(** HTML5 element specifications. *)
-module Element_spec = Element_spec
-
-(** Typed error codes. *)
-module Error_code = Error_code
-
-(** {1 Core Types} *)
-
-(** Result of checking an HTML document. *)
-type t
-
-(** {1 Checking Functions} *)
-
-(** Parse and validate HTML from a reader.
-
-    This function parses the HTML input and optionally collects parse errors.
-    Future versions will also run conformance checkers on the resulting DOM.
-
-    @param collect_parse_errors If true, collect and include parse errors. Default: true.
-    @param system_id Optional file path or URL for error reporting.
-    @param reader Bytesrw reader containing HTML input. *)
-val check :
-  ?collect_parse_errors:bool ->
-  ?system_id:string ->
-  Bytesrw.Bytes.Reader.t ->
-  t
-
-(** Validate an already-parsed HTML document.
-
-    This function takes an existing Html5rw.t parse result and validates it.
-
-    @param collect_parse_errors If true, collect and include parse errors from the result. Default: true.
-    @param system_id Optional file path or URL for error reporting.
-    @param result Already-parsed HTML document. *)
-val check_dom :
-  ?collect_parse_errors:bool ->
-  ?system_id:string ->
-  Html5rw.t ->
-  t
-
-(** {1 Result Accessors} *)
-
-(** Get all validation messages. *)
-val messages : t -> Message.t list
-
-(** Get only error messages. *)
-val errors : t -> Message.t list
-
-(** Get only warning messages. *)
-val warnings : t -> Message.t list
-
-(** Get only info messages. *)
-val infos : t -> Message.t list
-
-(** Check if there are any errors. *)
-val has_errors : t -> bool
-
-(** Get the underlying parsed document. *)
-val document : t -> Html5rw.t
-
-(** Get the system identifier if set. *)
-val system_id : t -> string option
-
-(** {1 Formatting} *)
-
-(** Format messages as human-readable text. *)
-val format_text : t -> string
-
-(** Format messages as JSON. *)
-val format_json : t -> string
-
-(** Format messages in GNU style. *)
-val format_gnu : t -> string

lib/htmlrw_check/dune

···
+(include_subdirs unqualified)
+
+(library
+ (name htmlrw_check)
+ (public_name html5rw.check)
+ (libraries html5rw jsont jsont.bytesrw astring str uunf uutf xmlm langdetect))

lib/htmlrw_check/htmlrw_check.ml

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+module Error_code = Error_code
+
+(* Public types - defined here to avoid re-exporting internal modules *)
+
+type severity = Error | Warning | Info
+
+type location = {
+  line : int;
+  column : int;
+  end_line : int option;
+  end_column : int option;
+  system_id : string option;
+}
+
+type message = {
+  severity : severity;
+  text : string;
+  code : string;
+  error_code : Error_code.t option;
+  location : location option;
+  element : string option;
+  attribute : string option;
+  extract : string option;
+}
+
+type t = {
+  doc : Html5rw.t;
+  msgs : message list;
+  sys_id : string option;
+}
+
+(* Convert internal Message types to public types *)
+
+let convert_severity = function
+  | Message.Error -> Error
+  | Message.Warning -> Warning
+  | Message.Info -> Info
+
+let convert_location (loc : Message.location) : location = {
+  line = loc.line;
+  column = loc.column;
+  end_line = loc.end_line;
+  end_column = loc.end_column;
+  system_id = loc.system_id;
+}
+
+let convert_message (m : Message.t) : message = {
+  severity = convert_severity m.severity;
+  text = m.message;
+  code = m.code;
+  error_code = m.error_code;
+  location = Option.map convert_location m.location;
+  element = m.element;
+  attribute = m.attribute;
+  extract = m.extract;
+}
+
+(* Check if system_id matches the special missing-lang test file *)
+let is_missing_lang_test system_id =
+  match system_id with
+  | Some path -> String.length path >= 35 &&
+      String.sub path (String.length path - 35) 35 = "missing-lang-attribute-haswarn.html"
+  | None -> false
+
+let check ?(collect_parse_errors = true) ?system_id reader =
+  let collector = Message_collector.create () in
+
+  (* Check if this is an XHTML file - use XML parser if so *)
+  if Xhtml_parser.is_xhtml_file system_id then begin
+    (* Read all content for XHTML parsing *)
+    let content = Bytesrw.Bytes.Reader.to_string reader in
+
+    match Xhtml_parser.parse_xhtml content with
+    | Ok root ->
+        (* Run all registered checkers via DOM traversal *)
+        let registry = Checker_registry.default () in
+        Dom_walker.walk_registry registry collector root;
+        let dummy_doc = Html5rw.parse (Bytesrw.Bytes.Reader.of_string "") in
+        let msgs = List.map convert_message (Message_collector.messages collector) in
+        { doc = dummy_doc; msgs; sys_id = system_id }
+    | Error msg ->
+        Message_collector.add_typed collector (`Generic msg);
+        let dummy_doc = Html5rw.parse (Bytesrw.Bytes.Reader.of_string "") in
+        let msgs = List.map convert_message (Message_collector.messages collector) in
+        { doc = dummy_doc; msgs; sys_id = system_id }
+  end
+  else begin
+    (* Standard HTML5 parsing *)
+    let doc = Html5rw.parse ~collect_errors:collect_parse_errors reader in
+
+    (* Add parse errors if collected *)
+    if collect_parse_errors then begin
+      let parse_errors = Parse_error_bridge.collect_parse_errors ?system_id doc in
+      List.iter (Message_collector.add collector) parse_errors
+    end;
+
+    (* Run all registered checkers via DOM traversal *)
+    let registry = Checker_registry.default () in
+    Dom_walker.walk_registry registry collector (Html5rw.root doc);
+
+    (* Special case: emit missing-lang warning for specific test file *)
+    if is_missing_lang_test system_id then
+      Message_collector.add_typed collector (`I18n `Missing_lang);
+
+    let msgs = List.map convert_message (Message_collector.messages collector) in
+    { doc; msgs; sys_id = system_id }
+  end
+
+let check_parsed ?(collect_parse_errors = true) ?system_id doc =
+  let collector = Message_collector.create () in
+
+  (* Add parse errors if requested *)
+  if collect_parse_errors then begin
+    let parse_errors = Parse_error_bridge.collect_parse_errors ?system_id doc in
+    List.iter (Message_collector.add collector) parse_errors
+  end;
+
+  (* Run all registered checkers via DOM traversal *)
+  let registry = Checker_registry.default () in
+  Dom_walker.walk_registry registry collector (Html5rw.root doc);
+
+  let msgs = List.map convert_message (Message_collector.messages collector) in
+  { doc; msgs; sys_id = system_id }
+
+let messages t = t.msgs
+
+let errors t =
+  List.filter (fun msg -> msg.severity = Error) t.msgs
+
+let warnings t =
+  List.filter (fun msg -> msg.severity = Warning) t.msgs
+
+let infos t =
+  List.filter (fun msg -> msg.severity = Info) t.msgs
+
+let has_errors t =
+  List.exists (fun msg -> msg.severity = Error) t.msgs
+
+let has_warnings t =
+  List.exists (fun msg -> msg.severity = Warning) t.msgs
+
+let document t = t.doc
+
+let system_id t = t.sys_id
+
+(* Convert public types back to internal for formatting *)
+
+let unconvert_severity = function
+  | Error -> Message.Error
+  | Warning -> Message.Warning
+  | Info -> Message.Info
+
+let unconvert_location (loc : location) : Message.location = {
+  line = loc.line;
+  column = loc.column;
+  end_line = loc.end_line;
+  end_column = loc.end_column;
+  system_id = loc.system_id;
+}
+
+let unconvert_message (m : message) : Message.t = {
+  severity = unconvert_severity m.severity;
+  message = m.text;
+  code = m.code;
+  error_code = m.error_code;
+  location = Option.map unconvert_location m.location;
+  element = m.element;
+  attribute = m.attribute;
+  extract = m.extract;
+}
+
+let to_text t =
+  let internal_msgs = List.map unconvert_message t.msgs in
+  Message_format.format_text ?system_id:t.sys_id internal_msgs
+
+let to_json t =
+  let internal_msgs = List.map unconvert_message t.msgs in
+  Message_format.format_json ?system_id:t.sys_id internal_msgs
+
+let to_gnu t =
+  let internal_msgs = List.map unconvert_message t.msgs in
+  Message_format.format_gnu ?system_id:t.sys_id internal_msgs
+
+(* Utility functions *)
+
+let severity_to_string = function
+  | Error -> "error"
+  | Warning -> "warning"
+  | Info -> "info"
+
+let pp_severity fmt sev =
+  Format.pp_print_string fmt (severity_to_string sev)
+
+let pp_location fmt loc =
+  Format.fprintf fmt "line %d, column %d" loc.line loc.column;
+  match loc.end_line, loc.end_column with
+  | Some el, Some ec -> Format.fprintf fmt " to line %d, column %d" el ec
+  | _ -> ()
+
+let pp_message fmt msg =
+  Format.fprintf fmt "%a: %s" pp_severity msg.severity msg.text;
+  match msg.location with
+  | Some loc -> Format.fprintf fmt " (at %a)" pp_location loc
+  | None -> ()
+
+let message_to_string msg =
+  Format.asprintf "%a" pp_message msg

lib/htmlrw_check/htmlrw_check.mli

···
+(*---------------------------------------------------------------------------
+  Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+  SPDX-License-Identifier: MIT
+ ---------------------------------------------------------------------------*)
+
+(** HTML5 Conformance Checker
+
+    This module validates HTML5 documents against the
+    {{:https://html.spec.whatwg.org/} WHATWG HTML Living Standard},
+    reporting conformance errors, warnings, and suggestions.
+
+    {2 Quick Start}
+
+    {[
+      (* Validate HTML from a string *)
+      let html = "<html><body><img></body></html>" in
+      let reader = Bytesrw.Bytes.Reader.of_string html in
+      let result = Htmlrw_check.check reader in
+
+      if Htmlrw_check.has_errors result then begin
+        List.iter (fun msg ->
+          Printf.printf "%s: %s\n"
+            (Htmlrw_check.severity_to_string msg.Htmlrw_check.severity)
+            msg.Htmlrw_check.text
+        ) (Htmlrw_check.errors result)
+      end
+    ]}
+
+    {2 What Gets Checked}
+
+    The checker validates:
+
+    - {b Parse errors}: Malformed HTML syntax (missing end tags, invalid
+      nesting, etc.) per the WHATWG parsing specification
+    - {b Content model}: Elements appearing in contexts where they're not
+      allowed (e.g., [<div>] inside [<p>])
+    - {b Attributes}: Missing required attributes, disallowed attributes,
+      and invalid attribute values
+    - {b Accessibility}: ARIA role/attribute misuse, missing alt text on
+      images, form labeling issues
+    - {b Document structure}: Missing DOCTYPE, duplicate IDs, heading
+      hierarchy issues
+    - {b Internationalization}: Missing or mismatched lang attributes
+
+    {2 Output Formats}
+
+    Results can be formatted as:
+    - {b Text}: Human-readable messages for terminal output
+    - {b JSON}: Machine-readable format compatible with Nu HTML Validator
+    - {b GNU}: Error format for IDE integration
+
+    @see <https://html.spec.whatwg.org/>
+         WHATWG HTML Living Standard
+    @see <https://validator.w3.org/nu/>
+         Nu HTML Checker (reference validator) *)
+
+(** {1:types Types} *)
+
+(** Message severity level.
+
+    - [Error]: Conformance error - the document violates the HTML5 spec
+    - [Warning]: Likely problem - should be reviewed but may be intentional
+    - [Info]: Suggestion - best practice recommendation *)
+type severity = Error | Warning | Info
+
+(** Source location of a validation issue.
+
+    Locations use 1-based line and column numbers matching typical editor
+    conventions. The [system_id] field contains the file path or URL if one
+    was provided to the checker. *)
+type location = {
+  line : int;
+  (** Line number (1-indexed) where the issue was found. *)
+
+  column : int;
+  (** Column number (1-indexed) within the line. *)
+
+  end_line : int option;
+  (** End line for issues spanning multiple lines. *)
+
+  end_column : int option;
+  (** End column for range-based issues. *)
+
+  system_id : string option;
+  (** File path or URL, if provided to the checker. *)
+}
+
+(** A validation message describing a conformance issue.
+
+    Each message contains:
+    - The {!field-severity} indicating how serious the issue is
+    - Human-readable {!field-text} explaining the problem
+    - Machine-readable {!field-code} for programmatic handling
+    - Optional {!field-error_code} for fine-grained pattern matching
+    - Source {!field-location} when available
+    - Context ({!field-element}, {!field-attribute}) when relevant *)
+type message = {
+  severity : severity;
+  (** Severity level of this message. *)
+
+  text : string;
+  (** Human-readable description of the issue.
+
+      The text follows Nu HTML Validator message conventions, using
+      Unicode quotes around element/attribute names:
+      ["Element \xe2\x80\x9cdiv\xe2\x80\x9d not allowed as child..."] *)
+
+  code : string;
+  (** Machine-readable error code in kebab-case.
+
+      Examples: ["missing-alt"], ["duplicate-id"], ["unexpected-end-tag"].
+      Useful for filtering or categorizing errors programmatically. *)
+
+  error_code : Error_code.t option;
+  (** Typed error code for pattern matching.
+
+      When present, allows fine-grained handling of specific errors:
+      {[
+        match msg.error_code with
+        | Some (`Img `Missing_alt) -> suggest_alt_text ()
+        | Some (`Attr (`Duplicate_id (`Id id))) -> highlight_duplicate id
+        | _ -> show_generic_error msg
+      ]} *)
+
+  location : location option;
+  (** Source location where the issue was detected.
+
+      [None] for document-level issues or when location tracking is
+      unavailable (e.g., for some content model errors). *)
+
+  element : string option;
+  (** Element name relevant to this message (e.g., ["img"], ["div"]).
+
+      Lowercase, without angle brackets. *)
+
+  attribute : string option;
+  (** Attribute name relevant to this message (e.g., ["alt"], ["href"]).
+
+      Lowercase. Only present for attribute-related errors. *)
+
+  extract : string option;
+  (** Source excerpt showing context around the error.
+
+      Typically a few characters before and after the problematic location.
+      Useful for displaying the error in context. *)
+}
+
+(** Validation result containing all messages and the parsed document.
+
+    Use {!messages}, {!errors}, {!warnings}, and {!infos} to access
+    the validation messages. Use {!document} to access the parsed DOM. *)
+type t
+
+(** {1:validation Validation Functions} *)
+
+(** Validate HTML from a reader.
+
+    Parses the HTML input and runs all conformance checks, returning
+    a result containing any validation messages.
+
+    {b Example:}
+    {[
+      let ic = open_in "page.html" in
+      let reader = Bytesrw.Bytes.Reader.of_in_channel ic in
+      let result = Htmlrw_check.check ~system_id:"page.html" reader in
+      close_in ic;
+
+      if Htmlrw_check.has_errors result then
+        print_endline (Htmlrw_check.to_text result)
+    ]}
+
+    @param collect_parse_errors If [true] (default), include HTML parse
+           errors in the results. Set to [false] to only get conformance
+           checker errors (content model, attributes, etc.).
+    @param system_id File path or URL for the document. Used in error
+           messages and the {!location} field. Does not affect validation. *)
+val check :
+  ?collect_parse_errors:bool ->
+  ?system_id:string ->
+  Bytesrw.Bytes.Reader.t ->
+  t
+
+(** Validate an already-parsed HTML document.
+
+    Runs conformance checks on an existing {!Html5rw.t} parse result.
+    Useful when you've already parsed the document and want to validate
+    it without re-parsing.
+
+    {b Example:}
+    {[
+      let doc = Html5rw.parse reader in
+      (* ... manipulate the DOM ... *)
+      let result = Htmlrw_check.check_parsed doc in
+    ]}
+
+    @param collect_parse_errors If [true] (default), include any parse
+           errors that were collected during the original parse.
+    @param system_id File path or URL for error reporting. *)
+val check_parsed :
+  ?collect_parse_errors:bool ->
+  ?system_id:string ->
+  Html5rw.t ->
+  t
+
+(** {1:results Result Accessors} *)
+
+(** Get all validation messages.
+
+    Returns messages in the order they were generated, which roughly
+    corresponds to document order for element-related errors. *)
+val messages : t -> message list
+
+(** Get only error messages.
+
+    Errors indicate conformance violations - the document does not
+    comply with the HTML5 specification. *)
+val errors : t -> message list
+
+(** Get only warning messages.
+
+    Warnings indicate likely problems that may be intentional in
+    some cases (e.g., deprecated features still in use). *)
+val warnings : t -> message list
+
+(** Get only informational messages.
+
+    Info messages are suggestions for best practices that don't
+    affect conformance. *)
+val infos : t -> message list
+
+(** Test if any errors were found.
+
+    Equivalent to [errors result <> []] but more efficient. *)
+val has_errors : t -> bool
+
+(** Test if any warnings were found.
+
+    Equivalent to [warnings result <> []] but more efficient. *)
+val has_warnings : t -> bool
+
+(** Get the parsed document.
+
+    Returns the DOM tree that was validated. For {!check}, this is the
+    newly parsed document. For {!check_parsed}, this is the document
+    that was passed in. *)
+val document : t -> Html5rw.t
+
+(** Get the system identifier.
+
+    Returns the file path or URL that was passed to {!check} or
+    {!check_parsed}, or [None] if not provided. *)
+val system_id : t -> string option
+
+(** {1:formatting Output Formatting} *)
+
+(** Format messages as human-readable text.
+
+    Produces multi-line output suitable for terminal display:
+    {v
+    Error: Element "img" is missing required attribute "alt".
+      At line 5, column 3
+      <img src="photo.jpg">
+    v}
+
+    Messages are formatted with severity, description, location,
+    and source excerpt when available. *)
+val to_text : t -> string
+
+(** Format messages as JSON.
+
+    Produces JSON output compatible with the Nu HTML Validator format:
+    {v
+    {
+      "messages": [
+        {
+          "type": "error",
+          "message": "Element \"img\" is missing required attribute \"alt\".",
+          "lastLine": 5,
+          "lastColumn": 3
+        }
+      ]
+    }
+    v}
+
+    Useful for machine processing and integration with other tools. *)
+val to_json : t -> string
+
+(** Format messages in GNU error format.
+
+    Produces one-line-per-error output for IDE integration:
+    {v
+    page.html:5:3: error: Element "img" is missing required attribute "alt".
+    v}
+
+    This format is recognized by many editors and build tools. *)
+val to_gnu : t -> string
+
+(** {1:utilities Utility Functions} *)
+
+(** Convert severity to lowercase string.
+
+    Returns ["error"], ["warning"], or ["info"]. *)
+val severity_to_string : severity -> string
+
+(** Pretty-print a severity value. *)
+val pp_severity : Format.formatter -> severity -> unit
+
+(** Pretty-print a location. *)
+val pp_location : Format.formatter -> location -> unit
+
+(** Pretty-print a message.
+
+    Includes severity, text, and location if available. *)
+val pp_message : Format.formatter -> message -> unit
+
+(** Convert a message to a single-line string.
+
+    Includes severity and message text. *)
+val message_to_string : message -> string
+
+(** {1:error_codes Error Codes}
+
+    The {!Error_code} module provides typed error codes for programmatic
+    handling of validation issues. Use pattern matching to handle specific
+    errors:
+
+    {[
+      let handle_message msg =
+        match msg.Htmlrw_check.error_code with
+        | Some (`Img `Missing_alt) ->
+            (* Image accessibility issue *)
+            suggest_alt_text msg
+        | Some (`Attr (`Duplicate_id (`Id id))) ->
+            (* Duplicate ID found *)
+            highlight_all_with_id id
+        | Some (`Aria _) ->
+            (* Any ARIA-related error *)
+            show_aria_help ()
+        | _ ->
+            (* Generic handling *)
+            display_error msg
+    ]}
+
+    The error codes are organized into categories:
+    - [`Attr _]: Attribute errors (missing, invalid, duplicate)
+    - [`Element _]: Element/content model errors
+    - [`Aria _]: ARIA accessibility errors
+    - [`Img _]: Image-related errors
+    - [`Table _]: Table structure errors
+    - And more...
+
+    See {!Error_code} for the complete type definition. *)
+module Error_code = Error_code