feature: mdx 0.4 stanza with support for mld files out of the box

CHANGES.md

@@ -128,6 +128,9 @@ Unreleased
 - Fix bug where RPC clients built with dune-rpc-lwt would crash when closing
   their connection to the server (#7581, @gridbugs)
 
+- Introduce mdx stanza 0.4 requiring mdx >= 2.3.0 which updates the default
+  list of files to include `*.mld` files (#7582, @Leonidas-from-XIV)
+
 3.7.1 (2023-04-04)
 ------------------
 

doc/stanzas/mdx.rst

@@ -18,9 +18,10 @@ Note that this feature is still experimental and needs to be enabled in your
 
 .. code:: dune
 
-  (using mdx 0.3)
+  (using mdx 0.4)
 
-.. note:: Version ``0.2`` of the stanza requires mdx ``1.9.0``.
+.. note:: Version ``0.2`` of the stanza requires mdx ``1.9.0``. Version ``0.4``
+   of the stanza requires mdx ``2.3.0``.
 
 
 The syntax is as follows:
@@ -33,7 +34,8 @@ Where ``<optional-fields>`` are:
 
 - ``(files <globs>)`` are the files that you want MDX to check, described as a
   list of globs (see the :ref:`Glob language specification <glob>` ). It
-  defaults to ``*.md``.
+  defaults to ``*.md *.mld`` as of version ``0.4`` of the stanza and ``*.md``
+  before.
 
 - ``(deps <deps-conf list>)`` to specify the dependencies of your documentation
   code blocks. See :doc:`concepts/dependency-spec` for more details.

src/dune_rules/mdx.ml

@@ -187,19 +187,27 @@ let syntax =
     [ ((0, 1), `Since (2, 4))
     ; ((0, 2), `Since (3, 0))
     ; ((0, 3), `Since (3, 2))
+    ; ((0, 4), `Since (3, 8))
     ]
 
-let default_files =
-  let has_extension ext s = String.equal ext (Filename.extension s) in
-  Predicate_lang.Glob.of_pred (has_extension ".md")
+let glob_predicate repr =
+  repr |> Dune_lang.Glob.of_string_exn Loc.none |> Predicate_lang.Glob.of_glob
+
+let default_files_of_version version =
+  let md_files = glob_predicate "*.md" in
+  let mld_files = glob_predicate "*.mld" in
+  let mld_support_since = (0, 4) in
+  match Syntax.Version.Infix.(version >= mld_support_since) with
+  | true -> Predicate_lang.union [ md_files; mld_files ]
+  | false -> md_files
 
 let decode =
   let open Dune_lang.Decoder in
   fields
     (let+ loc = loc
      and+ version = Dune_lang.Syntax.get_exn syntax
      and+ files =
-       field "files" Predicate_lang.Glob.decode ~default:default_files
+       field "files" Predicate_lang.Glob.decode ~default:Predicate_lang.Standard
      and+ enabled_if =
        Enabled_if.decode ~allowed_vars:Any ~since:(Some (2, 9)) ()
      and+ package =
@@ -249,7 +257,8 @@ let files_to_mdx t ~sctx ~dir =
   in
   let must_mdx src_path =
     let file = Path.Source.basename src_path in
-    Predicate_lang.Glob.exec t.files ~standard:default_files file
+    let standard = default_files_of_version t.version in
+    Predicate_lang.Glob.exec t.files ~standard file
   in
   let build_path src_path =
     Path.Build.append_source (Super_context.context sctx).build_dir src_path

test/blackbox-tests/test-cases/mdx-stanza/mld-files.t

@@ -3,7 +3,6 @@ that that file is not being picked up:
 
   $ cat > dune-project <<EOF
   > (lang dune 3.7)
-  > 
   > (using mdx 0.3)
   > EOF
   $ cat > dune <<EOF
@@ -63,3 +62,76 @@ the test should succeed this time.
   $ dune promote
   Promoting _build/default/.mdx/needs-fixes.mld.corrected to needs-fixes.mld.
   $ dune runtest
+
+The 0.4 version of the stanza adds support for `.mld` files by default, so bump
+the stanza version.
+
+  $ cat > dune-project <<EOF
+  > (lang dune 3.7)
+  > (using mdx 0.4)
+  > EOF
+  $ cat > dune <<EOF
+  > (mdx)
+  > EOF
+  $ cat > needs-fixes.mld <<EOF
+  > This is a sample mld file. It has some code that is invalid.
+  >  
+  > {[
+  >   # List.map (fun x -> x * x) [(1 + 9); 2; 3; 4];;
+  >   - : int list = [1; 2; 3; 8]
+  > ]}
+  > 
+  > A run of MDX should output a fixed version.
+  > EOF
+
+0.4 is only supported since dune-lang 3.8, so attempting to use it should fail:
+
+  $ dune runtest
+  File "dune-project", line 2, characters 11-14:
+  2 | (using mdx 0.4)
+                 ^^^
+  Error: Version 0.4 of mdx extension to verify code blocks in .md files is not
+  supported until version 3.8 of the dune language.
+  Supported versions of this extension in version 3.7 of the dune language:
+  - 0.1 to 0.3
+  [1]
+
+Updating the dune-lang should make the test run.
+
+  $ cat > dune-project <<EOF
+  > (lang dune 3.8)
+  > (using mdx 0.4)
+  > EOF
+  $ dune runtest
+  File "needs-fixes.mld", line 1, characters 0-0:
+  Error: Files _build/default/needs-fixes.mld and
+  _build/default/.mdx/needs-fixes.mld.corrected differ.
+  [1]
+  $ dune promote
+  Promoting _build/default/.mdx/needs-fixes.mld.corrected to needs-fixes.mld.
+  $ dune runtest
+
+We also make sure that `:standard` resolves properly:
+
+  $ cat > dune <<EOF
+  > (mdx
+  >   (files :standard))
+  > EOF
+  $ cat > needs-fixes.mld <<EOF
+  > This is a sample mld file. It has some code that is invalid.
+  >  
+  > {[
+  >   # List.map (fun x -> x * x) [(1 + 9); 2; 3; 4];;
+  >   - : int list = [1; 2; 3; 8]
+  > ]}
+  > 
+  > A run of MDX should output a fixed version.
+  > EOF
+  $ dune runtest
+  File "needs-fixes.mld", line 1, characters 0-0:
+  Error: Files _build/default/needs-fixes.mld and
+  _build/default/.mdx/needs-fixes.mld.corrected differ.
+  [1]
+  $ dune promote
+  Promoting _build/default/.mdx/needs-fixes.mld.corrected to needs-fixes.mld.
+  $ dune runtest