Say when declarations that differ read the same

Why:
    With the annotations printed, two declarations can still read the same
    and not match, when a type they mention differs between the two sides,
    e.g. a base class that the interface leaves abstract. The error then
    showed the same text twice, which reads as a bug in the compiler. The
    reasons now start with a note saying so, which replaces the lead-in of a
    difference in runtime representation.

Diagnostic modified (declarations that print the same):
Example:
    // Classes.res
    @instanceof("Animal") type animal
    @instanceof("Dog") type dog = private animal
    // Classes.resi
    type animal
    @instanceof("Dog") type dog = private animal
Before (diagnostic):
    Actual declaration (Classes.res:2:20-44):
      @instanceof("Dog") type dog = private animal

    Expected declaration (Classes.resi:2:20-44):
      @instanceof("Dog") type dog = private animal

    Their runtime representations differ:
      Actual declaration: instances of Dog, a subclass of Animal
      Expected declaration: instances of Dog
After (diagnostic):
    Actual declaration (Classes.res:2:20-44):
      @instanceof("Dog") type dog = private animal

    Expected declaration (Classes.resi:2:20-44):
      @instanceof("Dog") type dog = private animal

    The declarations read the same, but a type they mention differs:
      Actual declaration: instances of Dog, a subclass of Animal
      Expected declaration: instances of Dog

Review: Why compare the printed text? It is what the reader sees, and the case to catch is exactly two declarations that look the same.

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/includecore.ml

@@ -201,7 +201,9 @@ let label side decl =
   in
   String.capitalize_ascii (side ^ " " ^ decl)
 
-let report_type_mismatch0 first second decl ppf err =
+(* [lead_in] introduces the two lines of a difference in runtime
+   representation; without it they stand under a lead-in printed before *)
+let report_type_mismatch0 ?(lead_in = true) first second decl ppf err =
   let pr fmt = Format.fprintf ppf fmt in
   match err with
   | Arity -> pr "They have different arities"
@@ -243,24 +245,41 @@ let report_type_mismatch0 first second decl ppf err =
   | Variant_representation s ->
     pr "The internal representations for case %s are not equal" (Ident.name s)
   | Not_undefined ->
-    pr
-      "@[<v 2>Their runtime representations differ:@,\
-       %s: can hold undefined@,\
-       %s: @notUndefined@]"
-      (label first decl) (label second decl)
+    if lead_in then pr "@[<v 2>Their runtime representations differ:@,";
+    pr "%s: can hold undefined@,%s: @notUndefined" (label first decl)
+      (label second decl);
+    if lead_in then pr "@]"
   | Runtime_annotation (declared1, declared2) ->
-    pr "@[<v 2>Their runtime representations differ:@,%s: %s@,%s: %s@]"
-      (label first decl) declared1 (label second decl) declared2
+    if lead_in then pr "@[<v 2>Their runtime representations differ:@,";
+    pr "%s: %s@,%s: %s" (label first decl) declared1 (label second decl)
+      declared2;
+    if lead_in then pr "@]"
 
-let report_type_mismatch first second decl ppf =
-  List.iter (fun err ->
-      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)
+(* Each reason on a line after a break. [read_the_same] puts them under a note
+   that the declarations print the same, which then replaces the lead-in of a
+   difference in runtime representation. *)
+let report_type_mismatch ?(read_the_same = false) first second decl ppf errs =
+  let report ppf =
+    List.iter (fun err ->
+        match err with
+        | Manifest -> ()
+        (* Its lines are labels, not sentences *)
+        | Runtime_annotation _ | Not_undefined ->
+          Format.fprintf ppf "@ %a"
+            (report_type_mismatch0 ~lead_in:(not read_the_same) first second
+               decl)
+            err
+        | _ ->
+          Format.fprintf ppf "@ %a."
+            (report_type_mismatch0 first second decl)
+            err)
+  in
+  if read_the_same then
+    Format.fprintf ppf
+      "@ @[<v 2>The declarations read the same, but a type they mention \
+       differs:%a@]"
+      report errs
+  else report ppf errs
 
 let rec compare_constructor_arguments env cstr params1 params2 arg1 arg2 =
   match (arg1, arg2) with

compiler/ml/includecore.mli

@@ -67,4 +67,10 @@ val extension_constructors :
   Env.t -> Ident.t -> extension_constructor -> extension_constructor -> bool
 
 val report_type_mismatch :
-  string -> string -> string -> Format.formatter -> type_mismatch list -> unit
+  ?read_the_same:bool ->
+  string ->
+  string ->
+  string ->
+  Format.formatter ->
+  type_mismatch list ->
+  unit

compiler/ml/includemod.ml

@@ -583,8 +583,16 @@ let include_symptom ~swapped env ppf = function
         if swapped then ("the expected", "the actual")
         else ("the actual", "the expected")
       in
+      (* Declarations can print the same and still differ, when a type they
+         mention differs between the two sides, e.g. a class the interface
+         leaves abstract. The reasons then say that first. *)
+      let read_the_same =
+        Format.asprintf "%a" (type_declaration id) d1
+        = Format.asprintf "%a" (type_declaration id) d2
+      in
       fprintf ppf "@,%a"
-        (Includecore.report_type_mismatch first second "declaration")
+        (Includecore.report_type_mismatch ~read_the_same first second
+           "declaration")
         errs
   | Extension_constructors (id, x1, x2) ->
     show_declarations ~swapped (extension_constructor id) ppf

tests/build_tests/super_errors_multi/expected/Cross_runtime_annotation_hidden_base.expected

@@ -16,6 +16,6 @@
   Expected declaration (/.../fixtures/Cross_runtime_annotation_hidden_base/Classes.resi:2:20-44):
     @instanceOf("Dog") type dog = private animal
 
-  Their runtime representations differ:
+  The declarations read the same, but a type they mention differs:
     Actual declaration: instances of Dog, a subclass of Animal
     Expected declaration: instances of Dog