Label the two sides when runtime representations differ

Why:
    "The actual declaration states values whose typeof is "object"" reads
    clumsily: a declaration doesn't state values. The two lines now use the
    labels of the declaration blocks above them, followed by what each side
    states.

Diagnostic modified (runtime representation reason):
Before (diagnostic):
    Their runtime representations differ:
      The actual declaration states values whose typeof is "object".
      The expected declaration states values whose typeof is "string".
After (diagnostic):
    Their runtime representations differ:
      Actual declaration: typeof "object"
      Expected declaration: typeof "string"

Diagnostic modified (@notundefined reason):
Before (diagnostic):
    Their runtime representations differ:
      The expected declaration is @notundefined,
      but the actual declaration can hold undefined.
After (diagnostic):
    Their runtime representations differ:
      Actual declaration: can hold undefined
      Expected declaration: @notundefined

Mapping modified (what a declaration states, Ast_untagged_variants.describe_declared_values):
Before (representation):
    @instanceof("Dog") ↦ instances of Dog
    @instanceof("Dog") of a subclass ↦ instances of Dog, a subclass of Animal
    arrays ↦ arrays
    @typeof("string") ↦ values whose typeof is "string"
    nothing ↦ no runtime class or typeof
After (representation):
    @instanceof("Dog") ↦ instances of Dog
    @instanceof("Dog") of a subclass ↦ instances of Dog, a subclass of Animal
    arrays ↦ arrays
    @typeof("string") ↦ typeof "string"
    nothing ↦ no stated class or typeof

Review: Where do the labels come from? From the side names the caller passes, without their article: "the actual" and "declaration" make "Actual declaration"; the type definition errors of Typedecl get "Original definition" and "This definition".
Review: Why no period? The lines are labels with a value, like the declaration labels, not sentences.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Kbf3gLpf7RN1MiRcubPgRn
Signed-off-by: Christoph Knittel <ck@cca.io>

Author: cknitt

compiler/ml/ast_untagged_variants.ml

@@ -322,16 +322,16 @@ let runtime_annotation_to_string = function
   | Type_of block_type ->
     Printf.sprintf "@%s(\"%s\")" type_of (typeof_name block_type)
 
-(* What a declaration's annotations state, for error messages *)
-let describe_declared_block_type = function
+(* What a declaration's annotations state about its values, for error
+   messages *)
+let describe_declared_values = function
   | Some (InstanceType (Class {name; ancestors = []})) -> "instances of " ^ name
   | Some (InstanceType (Class {name; ancestors})) ->
     "instances of " ^ name ^ ", a subclass of "
     ^ String.concat " and " ancestors
   | Some (InstanceType Array) -> "arrays"
-  | Some block_type ->
-    "values whose typeof is \"" ^ typeof_name block_type ^ "\""
-  | None -> "no runtime class or typeof"
+  | Some block_type -> "typeof \"" ^ typeof_name block_type ^ "\""
+  | None -> "no stated class or typeof"
 
 (* The [@notUndefined], [@instanceOf] or [@typeOf] annotation in [attrs],
    validated. Only [Typedecl] passes [~loc]; later readers see attributes it

compiler/ml/includecore.ml

@@ -191,6 +191,16 @@ type type_mismatch =
   | Runtime_annotation of string * string
   | Not_undefined
 
+(* A side of a comparison as a label: "the actual" and "declaration" make
+   "Actual declaration" *)
+let label side decl =
+  let side =
+    match String.split_on_char ' ' side with
+    | "the" :: rest -> String.concat " " rest
+    | _ -> side
+  in
+  String.capitalize_ascii (side ^ " " ^ decl)
+
 let report_type_mismatch0 first second decl ppf err =
   let pr fmt = Format.fprintf ppf fmt in
   match err with
@@ -235,24 +245,21 @@ let report_type_mismatch0 first second decl ppf err =
   | Not_undefined ->
     pr
       "@[<v 2>Their runtime representations differ:@,\
-       %s %s is @notUndefined,@,\
-       but %s %s can hold undefined@]"
-      (String.capitalize_ascii second)
-      decl first decl
+       %s: can hold undefined@,\
+       %s: @notUndefined@]"
+      (label first decl) (label second decl)
   | Runtime_annotation (declared1, declared2) ->
-    pr
-      "@[<v 2>Their runtime representations differ:@,\
-       %s %s states %s.@,\
-       %s %s states %s@]"
-      (String.capitalize_ascii first)
-      decl declared1
-      (String.capitalize_ascii second)
-      decl declared2
+    pr "@[<v 2>Their runtime representations differ:@,%s: %s@,%s: %s@]"
+      (label first decl) declared1 (label second decl) declared2
 
 let report_type_mismatch first second decl ppf =
   List.iter (fun err ->
-      if err = Manifest then ()
-      else
+      match err with
+      | Manifest -> ()
+      (* Its lines are labels, not sentences *)
+      | Runtime_annotation _ | Not_undefined ->
+        Format.fprintf ppf "@ %a" (report_type_mismatch0 first second decl) err
+      | _ ->
         Format.fprintf ppf "@ %a." (report_type_mismatch0 first second decl) err)
 
 let rec compare_constructor_arguments env cstr params1 params2 arg1 arg2 =
@@ -397,8 +404,8 @@ let compare_runtime_annotations env id decl1 decl2 =
     else
       [
         Runtime_annotation
-          ( Ast_untagged_variants.describe_declared_block_type declared1,
-            Ast_untagged_variants.describe_declared_block_type declared2 );
+          ( Ast_untagged_variants.describe_declared_values declared1,
+            Ast_untagged_variants.describe_declared_values declared2 );
       ]
 
 let type_declarations ?(equality = false) ~loc env name decl1 id decl2 =

tests/build_tests/super_errors/expected/not_undefined_functor_argument.res.expected

@@ -18,5 +18,5 @@
     type t
 
   Their runtime representations differ:
-    The expected declaration is @notUndefined,
-    but the actual declaration can hold undefined.
+    Actual declaration: can hold undefined
+    Expected declaration: @notUndefined

tests/build_tests/super_errors/expected/not_undefined_functor_parameter.res.expected

@@ -19,5 +19,5 @@
     type t
 
   Their runtime representations differ:
-    The expected declaration is @notUndefined,
-    but the actual declaration can hold undefined.
+    Actual declaration: can hold undefined
+    Expected declaration: @notUndefined

tests/build_tests/super_errors/expected/runtime_annotation_interface_over_record.res.expected

@@ -18,5 +18,5 @@
     type t
 
   Their runtime representations differ:
-    The actual declaration states values whose typeof is "object".
-    The expected declaration states values whose typeof is "string".
+    Actual declaration: typeof "object"
+    Expected declaration: typeof "string"

tests/build_tests/super_errors_multi/expected/Cross_not_undefined_option_implementation.expected

@@ -17,5 +17,5 @@
     type t
 
   Their runtime representations differ:
-    The expected declaration is @notUndefined,
-    but the actual declaration can hold undefined.
+    Actual declaration: can hold undefined
+    Expected declaration: @notUndefined

tests/build_tests/super_errors_multi/expected/Cross_runtime_annotation_claimed_by_interface.expected

@@ -16,5 +16,5 @@
     type t
 
   Their runtime representations differ:
-    The actual declaration states no runtime class or typeof.
-    The expected declaration states values whose typeof is "string".
+    Actual declaration: no stated class or typeof
+    Expected declaration: typeof "string"

tests/build_tests/super_errors_multi/expected/Cross_runtime_annotation_functor_argument.expected

@@ -17,5 +17,5 @@
     type dog
 
   Their runtime representations differ:
-    The actual declaration states instances of Dog, a subclass of Animal.
-    The expected declaration states instances of Dog.
+    Actual declaration: instances of Dog, a subclass of Animal
+    Expected declaration: instances of Dog

tests/build_tests/super_errors_multi/expected/Cross_runtime_annotation_hidden_base.expected

@@ -17,5 +17,5 @@
     type dog = private animal
 
   Their runtime representations differ:
-    The actual declaration states instances of Dog, a subclass of Animal.
-    The expected declaration states instances of Dog.
+    Actual declaration: instances of Dog, a subclass of Animal
+    Expected declaration: instances of Dog

tests/build_tests/super_errors_multi/expected/Cross_runtime_annotation_hidden_superclass.expected

@@ -17,5 +17,5 @@
     type dog
 
   Their runtime representations differ:
-    The actual declaration states instances of Dog, a subclass of Animal.
-    The expected declaration states instances of Dog.
+    Actual declaration: instances of Dog, a subclass of Animal
+    Expected declaration: instances of Dog