Fix 1429

.github/workflows/build.yml

@@ -12,8 +12,7 @@ jobs:
         os:
           - ubuntu-latest
         ocaml-compiler:
-          - "4.08"
-          - "4.10"
+          - "4.11"
           - "4.12"
           - "4.14"
           - "5.0"
@@ -28,7 +27,7 @@ jobs:
             run-mdx: true
             test-sherlodoc: true
           - os: macos-latest
-            ocaml-compiler: "5.3"
+            ocaml-compiler: "5.4"
           # - os: windows-latest
           #   ocaml-compiler: "5.2"
 

.github/workflows/oxcaml.yml

@@ -38,7 +38,6 @@ jobs:
 
       - name: Install dependencies
         run: |
-          sed -i '/bisect_ppx/d' odoc.opam
           opam install --deps-only --with-test ./odoc.opam ./odoc-parser.opam \
             ${{ matrix.test-sherlodoc && './sherlodoc.opam' }}
 

CHANGES.md

@@ -1,8 +1,10 @@
 # Unreleased
 
 ### Fixed
-- Fix #1426, which broke docs in packages include `base` in OCaml 5.5.0
+- Fix #1426, which broke docs in packages including `base` in OCaml 5.5.0
   (@jonludlam, #1427)
+- Fix #1429, which broke docs in packages including `merlin-lib` (@jonludlam,
+  #1430)
 
 # 3.2.0
 

src/xref2/subst.ml

@@ -453,7 +453,12 @@ let rec resolved_signature_fragment :
       let p =
         match resolved_module_type_path t p with
         | Not_replaced p -> p
-        | Replaced _ -> assert false
+        | Replaced _ ->
+            (* The resolved root module type of the fragment is being
+               substituted away. The resolved form is no longer valid —
+               unresolve and re-resolve against the post-substitution context
+            *)
+            raise Invalidated
       in
       `Root (`ModuleType p)
   | `Root (`Module p) -> `Root (`Module (resolved_module_path t p))

test/xref2/apply_inner_substs_module_type.t/a_include.mli

@@ -0,0 +1,9 @@
+(** A destructively-substituted module type referenced from a [with]-clause
+    in a later [include]. *)
+module type Inner = sig
+  module type X := sig type t end
+
+  include X with type t := int
+end
+
+include Inner

test/xref2/apply_inner_substs_module_type.t/b_modtype_def.mli

@@ -0,0 +1,9 @@
+(** A destructively-substituted module type referenced from a [with]-clause
+    in a later module type definition. *)
+module type Inner = sig
+  module type X := sig type t end
+
+  module type S = X with type t := int
+end
+
+include Inner

test/xref2/apply_inner_substs_module_type.t/c_module_decl.mli

@@ -0,0 +1,9 @@
+(** A destructively-substituted module type referenced from a [with]-clause
+    in a later module declaration. *)
+module type Inner = sig
+  module type X := sig type t end
+
+  module M : X with type t := int
+end
+
+include Inner

test/xref2/apply_inner_substs_module_type.t/d_functor_param.mli

@@ -0,0 +1,9 @@
+(** A destructively-substituted module type referenced from a [with]-clause
+    in a functor parameter constraint. *)
+module type Inner = sig
+  module type X := sig type t end
+
+  module F : functor (M : X with type t := int) -> sig end
+end
+
+include Inner

test/xref2/apply_inner_substs_module_type.t/e_nested.mli

@@ -0,0 +1,11 @@
+(** A destructively-substituted module type referenced from a [with]-clause
+    nested inside a sub-module type. *)
+module type Inner = sig
+  module type X := sig type t end
+
+  module type S = sig
+    module N : X with type t := int
+  end
+end
+
+include Inner

test/xref2/apply_inner_substs_module_type.t/f_with_modtype_subst.mli

@@ -0,0 +1,11 @@
+(** A destructively-substituted module type appearing not as a top-level
+    [module type X := ...] item but as the substitution clause of a regular
+    [with module type X := ...] expression. The replacement enters
+    [module_type_replacement] via [fragmap]'s [sub_of_removed], not via
+    [apply_inner_substs]. *)
+module type T = sig
+  module type X = sig type t end
+  module type Y = X with type t := int
+end
+
+module M : T with module type X := sig type t end

test/xref2/apply_inner_substs_module_type.t/run.t

@@ -0,0 +1,28 @@
+Minimal repros of #1429. We shouldn't see any errors from odoc for any of these
+examples.
+
+  $ for f in *.mli; do ocamlc -bin-annot -c "$f"; done
+
+Position A — destructive subst at signature level, fragment in a later [include]:
+
+  $ odoc compile a_include.cmti
+
+Position B — destructive subst at signature level, fragment in a later module type definition:
+
+  $ odoc compile b_modtype_def.cmti
+
+Position C — destructive subst at signature level, fragment in a later module declaration:
+
+  $ odoc compile c_module_decl.cmti
+
+Position D — destructive subst at signature level, fragment in a functor parameter:
+
+  $ odoc compile d_functor_param.cmti
+
+Position E — destructive subst at signature level, fragment nested inside a sub-module type:
+
+  $ odoc compile e_nested.cmti
+
+Position F — destructive subst inside a [with]-clause, fragment in another [with]-clause of the substituted signature:
+
+  $ odoc compile f_with_modtype_subst.cmti

test/xref2/dune

@@ -57,7 +57,7 @@
 ; 4.13.0 and above
 
 (cram
- (applies_to github_issue_793)
+ (applies_to github_issue_793 apply_inner_substs_module_type)
  (enabled_if
   (>= %{ocaml_version} 4.13.0)))