Flaky CI: `hilite.markdown not found` on ubuntu — replace git pin with a released hilite

[cuihtlauac]

Symptom

Intermittent failures of the ubuntu Build project step with:

File "tool/data-packer/lib/dune", line 17, characters 2-17:
Error: Library "hilite.markdown" not found.
make: *** [Makefile:9: all] Error 1

macOS is unaffected. It clears on a plain re-run. Seen at least twice:

• main push CI on the docs: note Git LFS workaround for pushing to contributor forks #3758 merge commit (run 33375102857) — failed, green on re-run.
• Earlier on PR Add the announce for opam 2.5.2 #3712's CI (ubuntu).

The identical tree passes on a PR check and then fails on the follow-up main push, which points to an environmental/cache flake rather than a code problem.

Root cause

ocamlorg.opam depends on hilite via an unreleased git pin:

"hilite" {>= "0.6.0"}
...
pin-depends: [
  [ "hilite.0.6.0" "git+https://github.com/patricoferris/hilite#f5368558f765ff6c884fda68acf4d4e9256970b4" ]
]

But there is no hilite 0.6.0. The latest release in ocaml/opam-repository is 0.5.0, and upstream has no 0.6.0/v0.6.0 tag. The pinned commit f5368558 is v0.5.0 + 17 commits and adds the MDX mode to hilite's markdown backend (src/markdown/*) — i.e. the hilite.markdown sublibrary that tool/data-packer/lib/dune consumes. The pin was introduced in #3593 ("Use Hilite's new ocaml-mdx support").

Building a git-pinned package in CI is cache-fragile: the git source is re-fetched/re-resolved rather than restored from an immutable, content-addressed tarball, so hilite.markdown occasionally isn't present at dune build time.

Proposed fix

1. Cut a proper hilite 0.6.0 release to ocaml/opam-repository, containing the MDX markdown backend (v0.5.0..f5368558). This is an upstream action by the hilite maintainer (patricoferris).
2. Once released, drop the git pin here: remove the pin-depends entry for hilite.0.6.0 and keep hilite {>= "0.6.0"} resolving from opam-repository.

That makes the build reproducible and removes the flake.

Workaround until then

Re-run the failed ubuntu job (gh run rerun <id> --failed).

[sahilnyk]

went through the dune and opam docs before starting on this.

hilite.markdown is an (optional) dune library so it is built only when cmarkit and re are present. in hilite both of those are depopts not depends so installing hilite does not bring them in by itself.

releasing 0.6.0 and dropping the pin removes the git source fragility. but hilite.markdown would still be optional and still gated on cmarkit and re being available when hilite builds. so i am not sure if that on its own is a full fix or if it mainly removes one trigger.

would it make sense to have cmarkit and re as real depends of hilite or to split hilite.markdown into its own package. what is your view.

i am going to set this up locally and check the actual build behavior then report back here.

[sahilnyk]

set it up locally and the one nothing guards is fmt. the markdown lib needs fmt cmarkit re and since cmarkit and re are depopts of hilite opam still builds them before it, but fmt is not a depend or a depopt anywhere so if hilite builds first the markdown lib gets skipped and that is where Library "hilite.markdown" not found comes from.

i could only trigger it by installing the pinned hilite with fmt removed and then the markdown/ dir goes missing and comes back once fmt is there and hilite is rebuilt. a normal build worked fine for me so i did not hit the flake itself but it shows where it comes from.

so along with the 0.6.0 change it would help to move fmt cmarkit re into hilite's real depends and drop (optional).