chore: sync fork with upstream (conflicts resolved)

.gitattributes

@@ -3,13 +3,13 @@
 
 # the linguist-vendored/linguist-generated attribute suppresses changes being
 # displayed by default in pull requests.
-/analysis/dist/*.cjs -diff linguist-generated
+/analysis/dist/*.mjs -diff linguist-generated
 /analysis/dist/*.txt -diff linguist-generated
-/dist/**/*.cjs -diff linguist-generated
+/dist/**/*.mjs -diff linguist-generated
 /dist/**/*.txt -diff linguist-generated
-/lint-doc/dist/*.cjs -diff linguist-generated
+/lint-doc/dist/*.mjs -diff linguist-generated
 /lint-doc/dist/*.txt -diff linguist-generated
-/lint-fmt/dist/*.cjs -diff linguist-generated
+/lint-fmt/dist/*.mjs -diff linguist-generated
 /lint-fmt/dist/*.txt -diff linguist-generated
-/lint-opam/dist/*.cjs -diff linguist-generated
+/lint-opam/dist/*.mjs -diff linguist-generated
 /lint-opam/dist/*.txt -diff linguist-generated

.github/workflows/workflow.yml

@@ -4,7 +4,6 @@ on:
   pull_request:
   push:
   schedule:
-    # Prime the caches every Monday
     - cron: 0 1 * * MON
 
 permissions: read-all
@@ -15,64 +14,91 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout tree
-        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - name: Set-up Mise
-        uses: jdx/mise-action@146a28175021df8ca24f8ee1828cc2a60f980bd5 # v3.5.1
+        uses: jdx/mise-action@dba19683ed58901619b14f395a24841710cb4925 # v4.1.0
+        with:
+          cache: false
       - run: yarn install --immutable
       - if: always()
         run: yarn lint
       - if: always()
         run: yarn typecheck
-      - name: Ensure dist directory is up-to-date
-        if: always()
+      - if: always()
+        name: Ensure dist directory is up-to-date
         run: yarn build && git diff --exit-code --ignore-cr-at-eol
 
-  test:
-    name: Test
+  ubuntu:
+    name: Ubuntu
     needs: hygiene
+    runs-on: ubuntu-latest
     strategy:
-      fail-fast: false
       matrix:
-        os:
-          - ubuntu-slim
-          - ubuntu-latest
-          - macos-latest
-          - windows-latest
-        ocaml-compiler:
-          - "5.3"
         allow-prerelease-opam:
+          - true
           - false
-        include:
-          - os: ubuntu-latest
-            ocaml-compiler: ocaml-variants.5.3.0+options,ocaml-option-flambda
-            allow-prerelease-opam: false
-          - os: ubuntu-latest
-            ocaml-compiler: "5.3"
-            allow-prerelease-opam: true
-    runs-on: ${{ matrix.os }}
+      fail-fast: false
     steps:
       - name: Checkout tree
-        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
-      - name: Set-up OCaml ${{ matrix.ocaml-compiler }}
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - name: Set-up OCaml 5.4
         uses: ./
         with:
-          ocaml-compiler: ${{ matrix.ocaml-compiler }}
+          ocaml-compiler: "5.4"
           allow-prerelease-opam: ${{ matrix.allow-prerelease-opam }}
       - run: opam install ssl
 
-  test-container:
-    name: Test on a container in a GitHub runner
+  macos:
+    name: macOS
+    needs: hygiene
+    runs-on: macos-latest
+    steps:
+      - name: Checkout tree
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - name: Set-up OCaml 5.4
+        uses: ./
+        with:
+          ocaml-compiler: "5.4"
+      - run: opam install ssl
+
+  windows:
+    name: Windows
+    needs: hygiene
+    runs-on: windows-latest
+    strategy:
+      matrix:
+        windows-compiler:
+          - mingw
+          - msvc
+        windows-environment:
+          - cygwin
+          - msys2
+      fail-fast: false
+    steps:
+      - name: Checkout tree
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - name: Set-up OCaml 5.4
+        uses: ./
+        with:
+          ocaml-compiler: "5.4"
+          windows-compiler: ${{ matrix.windows-compiler }}
+          windows-environment: ${{ matrix.windows-environment }}
+      - run: opam install ssl
+        continue-on-error: ${{ matrix.windows-compiler == 'msvc' }}
+
+  container:
+    name: Container
     needs: hygiene
     runs-on: ubuntu-latest
     container:
       image: archlinux:latest
     steps:
       - name: Checkout tree
-        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - name: Install dependencies
         run: pacman -Sy --noconfirm bash bubblewrap ca-certificates coreutils curl diffutils gcc git make nano ncurses patch rsync sudo tar unzip xz
       - name: Set-up OCaml
         uses: ./
         with:
-          ocaml-compiler: "5.3"
+          ocaml-compiler: "5.4"
       - run: opam install ssl

.gitignore

@@ -1,4 +1,2 @@
-/.turbo/
-/.vscode/
 /.yarn/
 /node_modules/

.yarnrc.yml

@@ -1,5 +1,7 @@
 defaultSemverRangePrefix: ""
 
+nmHoistingLimits: workspaces
+
 npmMinimalAgeGate: 7d
 
 nodeLinker: node-modules

EXAMPLES.md

@@ -20,17 +20,17 @@ jobs:
   deploy-odoc:
     name: Deploy odoc to GitHub Pages
 
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-
     permissions:
       contents: read
       id-token: write
       pages: write
 
     runs-on: ubuntu-latest
 
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
     steps:
       - name: Checkout tree
         uses: actions/checkout@v6
@@ -54,8 +54,8 @@ jobs:
         with:
           path: _build/default/_doc/_html
 
-      - name: Deploy odoc to GitHub Pages
-        id: deployment
+      - id: deployment
+        name: Deploy odoc to GitHub Pages
         uses: actions/deploy-pages@v4
 ```
 
@@ -77,19 +77,89 @@ steps:
         !exclude.opam
 ```
 
+## Using MSVC on Windows
+
+```yml
+runs-on: windows-latest
+
+steps:
+  - name: Checkout tree
+    uses: actions/checkout@v6
+
+  - name: Set-up OCaml with MSVC
+    uses: ocaml/setup-ocaml@v3
+    with:
+      ocaml-compiler: "5.4"
+      windows-compiler: msvc
+```
+
+## Using MSYS2 on Windows
+
+```yml
+runs-on: windows-latest
+
+steps:
+  - name: Checkout tree
+    uses: actions/checkout@v6
+
+  - name: Set-up OCaml with MSYS2
+    uses: ocaml/setup-ocaml@v3
+    with:
+      ocaml-compiler: "5.4"
+      windows-environment: msys2
+```
+
+## Using a custom OCaml compiler
+
+To use a custom or unreleased OCaml compiler, create a custom [opam repository](https://opam.ocaml.org/doc/Manual.html#Repositories) containing the compiler package and add it via the `opam-repositories` input. When specifying a compiler from a custom repository, you must use the full opam package name rather than a semver version range, because semver resolution only queries the official [opam-repository](https://github.com/ocaml/opam-repository).
+
+```yml
+steps:
+  - name: Checkout tree
+    uses: actions/checkout@v6
+
+  - name: Set-up OCaml
+    uses: ocaml/setup-ocaml@v3
+    with:
+      ocaml-compiler: ocaml-base-compiler.5.4.0~dev
+      opam-repositories: |
+        custom: git+https://github.com/<username>/<custom-opam-repository>.git
+        default: git+https://github.com/ocaml/opam-repository.git
+```
+
+## Using opam lock files
+
+To use dependencies specified by [opam lock files](https://opam.ocaml.org/doc/Manual.html#opam-lock), set the `OPAMLOCKED` environment variable to `locked` in the setup-ocaml step. This ensures that `opam pin` uses the `.opam.locked` files, so subsequent `opam install . --deps-only --locked` correctly installs the locked dependencies.
+
+```yml
+steps:
+  - name: Checkout tree
+    uses: actions/checkout@v6
+
+  - name: Set-up OCaml
+    uses: ocaml/setup-ocaml@v3
+    with:
+      ocaml-compiler: "5.4"
+    env:
+      OPAMLOCKED: locked
+
+  - name: Install dependencies
+    run: opam install . --deps-only --locked
+```
+
 ## Using with [Containers](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idcontainer)
 
 ```yml
+runs-on: ubuntu-latest
+
+container: ${{ matrix.container }}
+
 strategy:
-  fail-fast: false
   matrix:
     container:
       - debian:latest
       - ubuntu:latest
-
-container: ${{ matrix.container }}
-
-runs-on: ubuntu-latest
+  fail-fast: false
 
 steps:
   - name: Checkout tree