Match fields and constructors by name in signature mismatch errors

Why:
    The inclusion check compared the fields of two records and the
    constructors of two variants by position and reported only the first
    difference. A field missing in the middle, two swapped fields or a
    constructor added at the front all read as "Fields number N have
    different names", and the other differences stayed hidden. Upstream
    OCaml 4.13 lines the declarations up with an edit distance (#9130);
    names are unique within a declaration, so lining them up by name is
    enough here.

Includecore.align lines the two lists up by name. Declarations with the same
names in the same order, as nearly all are, are paired directly. Otherwise a
name in only one declaration is missing or extra, one name lacking on each
side after the same common entry is a renaming (paired in order when that gap
holds as many on each side), and common names in another order are reported
once, in the expected order. Each entry in both is compared on its own, at its
own position in each variant layout, so every difference is reported. The
differences of an inline record are grouped under its constructor.

The declarations are printed as before; the blocks below show the reasons
under them.

Diagnostic modified (field missing in the middle):
Example:
    module M: {
      type t = {name: string, age: int, email: string}
    } = {
      type t = {name: string, email: string}
    }
Before (diagnostic):
    Fields number 2 have different names, email and age.
After (diagnostic):
    The field age is only present in the expected declaration.

Diagnostic modified (fields in another order):
Example:
    module M: {
      type t = {a: int, b: int, c: int, d: int}
    } = {
      type t = {c: int, a: int, b: int, e: int}
    }
Before (diagnostic):
    Fields number 1 have different names, c and a.
After (diagnostic):
    The field d is only present in the expected declaration.
    The field e is only present in the actual declaration.
    The fields are in another order in the expected declaration:
    a, b, c.

Diagnostic modified (several differing fields):
Example:
    module M: {
      type t = {id: int, mutable name: string, age: int, @as("e-mail") email?: string}
    } = {
      type t = {id: string, name: string, age: float, email: string}
    }
Before (diagnostic):
    The mutability of field name is different.
After (diagnostic):
    The types for field id are not equal.
    The mutability of field name is different.
    The types for field age are not equal.
    The optional attribute of field email is different.
    The field email has the runtime name "email" in the actual declaration,
    but "e-mail" in the expected declaration.

Diagnostic modified (constructor added and renamed):
Example:
    module M: {
      type t = Red | Green | Blue | Gray
    } = {
      type t = Black | Red | Green | Blue | Grey
    }
Before (diagnostic):
    Constructors number 1 have different names, Black and Red.
After (diagnostic):
    The constructor Grey is named Gray in the expected declaration.
    The constructor Black is only present in the actual declaration.

Diagnostic modified (inline record of a constructor):
Example:
    module M: {
      type t = Person({name: string, age: int}) | Anonymous
    } = {
      type t = Person({age: int, name: string, nick: string}) | Anonymous
    }
Before (diagnostic):
    Fields number 0 have different names, age and name.
After (diagnostic):
    The records of constructor Person differ:
      The field nick is only present in the actual declaration.
      The fields are in another order in the expected declaration:
      name, age.

Review: Does the check accept anything it rejected before, or the other way round? No. A declaration passes only when every name is in both, in the same order, with no difference per entry, which is what the positional walk required; only the messages change.
Review: Why is the type of an optional field not reported when only its optional attribute differs? The type of an optional field is an option of the declared type, so it differs whenever the attribute does; the attribute message already says so.

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

changes/inclusion-diff-by-name.polish.md

@@ -0,0 +1 @@
+- Report every difference between the record fields or variant constructors of an implementation and its interface, matched by name: missing, extra, renamed and reordered entries, and say which side is the actual and which the expected declaration.

compiler/ml/includecore.ml

@@ -31,12 +31,16 @@ type type_mismatch =
   | Field_mutable of Ident.t
   | Field_optional of Ident.t
   | Field_arity of Ident.t
-  | Field_names of int * string * string
+  | Field_renamed of string * string
+  | Field_runtime_name of Ident.t * string * string
   | Field_missing of bool * Ident.t
+  | Field_order of string list
   | Constructor_type of Ident.t
   | Constructor_arity of Ident.t
-  | Constructor_names of int * string * string
+  | Constructor_renamed of string * string
   | Constructor_missing of bool * Ident.t
+  | Constructor_order of string list
+  | Constructor_record of Ident.t * type_mismatch list
   | Record_representation of record_representation * record_representation
   | Unboxed_representation of bool
   | Immediate

compiler/ml/includecore.mli

@@ -17,4 +17,5 @@
   Expected declaration (/.../fixtures/OptionalInlineImplIntf.res:2:3-23):
     type t = A({x?: int})
 
-  The optional attribute of field x is different.
+  The records of constructor A differ:
+    The optional attribute of field x is different.

tests/build_tests/super_errors/expected/OptionalInlineImplIntf.res.expected

@@ -0,0 +1,21 @@
+
+  We've found a bug for you!
+  /.../fixtures/inclusion_constructor_extra.res:5:5-7:1
+
+  3 │ module M: {
+  4 │   type t = Red | Green | Blue | Gray
+  5 │ } = {
+  6 │   type t = Black | Red | Green | Blue | Grey
+  7 │ }
+  8 │ 
+
+  Signature mismatch:
+  
+  Actual declaration (/.../fixtures/inclusion_constructor_extra.res:6:3-44):
+    type t = Black | Red | Green | Blue | Grey
+  
+  Expected declaration (/.../fixtures/inclusion_constructor_extra.res:4:3-36):
+    type t = Red | Green | Blue | Gray
+  
+  The constructor Grey is named Gray in the expected declaration.
+  The constructor Black is only present in the actual declaration.

tests/build_tests/super_errors/expected/inclusion_constructor_extra.res.expected

@@ -0,0 +1,22 @@
+
+  We've found a bug for you!
+  /.../fixtures/inclusion_constructor_order.res:5:5-7:1
+
+  3 │ module M: {
+  4 │   type t = A(int) | B(string) | C
+  5 │ } = {
+  6 │   type t = B(int) | A(int) | C
+  7 │ }
+  8 │ 
+
+  Signature mismatch:
+  
+  Actual declaration (/.../fixtures/inclusion_constructor_order.res:6:3-30):
+    type t = B(int) | A(int) | C
+  
+  Expected declaration (/.../fixtures/inclusion_constructor_order.res:4:3-33):
+    type t = A(int) | B(string) | C
+  
+  The types for constructor B are not equal.
+  The constructors are in another order in the expected declaration:
+  A, B, C.

tests/build_tests/super_errors/expected/inclusion_constructor_order.res.expected

@@ -0,0 +1,20 @@
+
+  We've found a bug for you!
+  /.../fixtures/inclusion_field_missing.res:5:5-7:1
+
+  3 │ module M: {
+  4 │   type t = {name: string, age: int, email: string}
+  5 │ } = {
+  6 │   type t = {name: string, email: string}
+  7 │ }
+  8 │ 
+
+  Signature mismatch:
+  
+  Actual declaration (/.../fixtures/inclusion_field_missing.res:6:3-40):
+    type t = {name: string, email: string}
+  
+  Expected declaration (/.../fixtures/inclusion_field_missing.res:4:3-50):
+    type t = {name: string, age: int, email: string}
+  
+  The field age is only present in the expected declaration.

tests/build_tests/super_errors/expected/inclusion_field_missing.res.expected

@@ -0,0 +1,23 @@
+
+  We've found a bug for you!
+  /.../fixtures/inclusion_field_order.res:5:5-7:1
+
+  3 │ module M: {
+  4 │   type t = {a: int, b: int, c: int, d: int}
+  5 │ } = {
+  6 │   type t = {c: int, a: int, b: int, e: int}
+  7 │ }
+  8 │ 
+
+  Signature mismatch:
+  
+  Actual declaration (/.../fixtures/inclusion_field_order.res:6:3-43):
+    type t = {c: int, a: int, b: int, e: int}
+  
+  Expected declaration (/.../fixtures/inclusion_field_order.res:4:3-43):
+    type t = {a: int, b: int, c: int, d: int}
+  
+  The field d is only present in the expected declaration.
+  The field e is only present in the actual declaration.
+  The fields are in another order in the expected declaration:
+  a, b, c.

tests/build_tests/super_errors/expected/inclusion_field_order.res.expected

@@ -0,0 +1,20 @@
+
+  We've found a bug for you!
+  /.../fixtures/inclusion_field_renamed.res:4:5-6:1
+
+  2 │ module M: {
+  3 │   type t = {name: string, email: string, age: int}
+  4 │ } = {
+  5 │   type t = {name: string, mail: string, age: int}
+  6 │ }
+  7 │ 
+
+  Signature mismatch:
+  
+  Actual declaration (/.../fixtures/inclusion_field_renamed.res:5:3-49):
+    type t = {name: string, mail: string, age: int}
+  
+  Expected declaration (/.../fixtures/inclusion_field_renamed.res:3:3-50):
+    type t = {name: string, email: string, age: int}
+  
+  The field mail is named email in the expected declaration.

tests/build_tests/super_errors/expected/inclusion_field_renamed.res.expected

@@ -0,0 +1,26 @@
+
+  We've found a bug for you!
+  /.../fixtures/inclusion_field_several.res:4:5-6:1
+
+  2 │ module M: {
+  3 │   type t = {id: int, mutable name: string, age: int, @as("e-mail") email
+    │ ?: string}
+  4 │ } = {
+  5 │   type t = {id: string, name: string, age: float, email: string}
+  6 │ }
+  7 │ 
+
+  Signature mismatch:
+  
+  Actual declaration (/.../fixtures/inclusion_field_several.res:5:3-64):
+    type t = {id: string, name: string, age: float, email: string}
+  
+  Expected declaration (/.../fixtures/inclusion_field_several.res:3:3-82):
+    type t = {id: int, mutable name: string, age: int, @as("e-mail") email?: string}
+  
+  The types for field id are not equal.
+  The mutability of field name is different.
+  The types for field age are not equal.
+  The optional attribute of field email is different.
+  The field email has the runtime name "email" in the actual declaration,
+  but "e-mail" in the expected declaration.