Merge master into fix/versioned-api-docs

Bring the API documentation routing PR up to date with master and its fix for matching the Semantic Diff workflow to the renderer. Preserve the CI branch filters applied through the GitHub web UI.

Signed-off-by: Florian Hammerschmidt <florianh89@gmail.com>

Author: fhammerschmidt

.claude/skills/records/SKILL.md

@@ -49,16 +49,31 @@ Breaking: <what existing code or tooling stops working, and the migration>
 Signed-off-by: Name <email>
 ```
 
-- The subject and `Signed-off-by` are required. The message ends with its
-  trailers, git's `Key: value` lines (`Co-Authored-By:`, `Fixes:` or any
-  other one-word key), `Signed-off-by` last; the page lists the
-  `Co-Authored-By` names and draws no other trailer. Every section is
-  optional.
-- A section starts at a line `Why:`, `Review:`, `Breaking:`, an object
-  block's heading, an `Example:` alone on its line, or a `Before (<form>):`
-  or `After (<form>):` heading, and holds the text after its colon and the
-  block indented by 4 spaces or more under it; a blank line ends a section
-  that holds only text. `Review:` repeats, one question each. Every other
+A commit without object blocks, such as a script change, is its subject
+and a line or two of prose:
+
+```
+Draw handles starting with a digit as code in the comment
+
+GitHub usernames may start with a digit, so `@0x` in a commit message
+would have mentioned a user; the comment now draws it as code as well.
+
+Signed-off-by: Name <email>
+```
+
+- The subject, a description and `Signed-off-by` are required: the
+  description says why the commit is made, as a line or two of prose or
+  a `Why:` section, and object blocks then show what it changes. Every
+  other section is optional. The message ends with its trailers, git's
+  `Key: value` lines (`Co-Authored-By:`, `Fixes:` or any other one-word
+  key), `Signed-off-by` last; the page lists the `Co-Authored-By` names
+  and draws no other trailer.
+- A section starts at a line `Why:`, `Review:` or `Breaking:` that no
+  paragraph of prose runs onto (a blank line or another section above it),
+  an object block's heading, an `Example:` alone on its line, or a
+  `Before (<form>):` or `After (<form>):` heading, and holds the text after
+  its colon and the block indented by 4 spaces or more under it; a blank
+  line ends a section that holds only text. `Review:` repeats, one question each. Every other
   line is prose, and a block indented by 4 spaces outside a section is
   ReScript code. Tabs count as 4 columns.
 - An **object block** is a heading `<Kind> added|modified|removed (<object>):`,
@@ -159,11 +174,13 @@ The table lists the common kinds.
   `-dce` and `-termination` select the other analyses.
 - A form of another name is drawn as text.
 
-## When to add a block
+## What a commit holds
 
-A commit gets one object block for each object it changes, with the
+Every commit says why it is made. A commit that changes what the compiler
+or a tool does gets one object block for each object it changes, with the
 smallest example that shows the change. A refactor, a test, a script or a
-review fix is a subject and a line or two of prose.
+review fix needs no block, only its subject and a line or two of prose; a
+review fix names the finding it answers.
 
 ## Rendering
 
@@ -175,14 +192,16 @@ node scripts/commitRecords.js --out page.html [--pr <number>] [--title <text>] \
 
 - `--pr` and `--title` head the page with the pull request.
   `.github/workflows/semantic_diff.yml` renders each pull request's range
-  and comments the page's link.
+  and comments the records as Markdown (`--markdown <file> --url <page>`,
+  scripts/recordMarkdown.js) with the page's link: after a push that keeps
+  the previous head, only the commits it added (`--since <previous head>`).
 - In prose, `#1234` and full pull request and issue URLs link as `#1234`,
   and the 9-character short sha of a commit on the page links to its card.
 
 ## What the page shows
 
 The page is the heading, then a card per commit. A card shows the commit's
-short sha, author and date, the pull request a `(#1234)` at the end of the
-subject names, and the message drawn: the subject, the prose, each object
-block with its example and forms, the `Breaking:` sections as banners, the
-`Review:` sections as a list, and the co-authors.
+short sha, author and co-authors, date, the pull request a `(#1234)` at
+the end of the subject names, and the message drawn: the subject, the
+prose, each object block with its example and forms, the `Breaking:`
+sections as banners, and the `Review:` sections as a list.

.github/workflows/ci.yml

@@ -51,6 +51,7 @@ jobs:
             build_playground: true
             generate_api_docs: true
             benchmarks: true
+            test_commit_records: true
             node-target: linux-arm64
             rust-target: aarch64-unknown-linux-musl
             dune-profile: static
@@ -194,6 +195,10 @@ jobs:
       - name: Test release plan
         run: yarn test-release-plan
 
+      - name: Test commit records
+        if: matrix.test_commit_records
+        run: yarn test-commit-records
+
       - name: Run tests
         run: node scripts/test.js -all
 

.github/workflows/semantic_diff.yml

@@ -1,19 +1,28 @@
 name: Semantic Diff
 
 # Renders the commit records of each pull request (scripts/commitRecords.js)
-# as a review page on the CDN and links it from the pull request.
+# as a review page on the CDN, and comments them on the pull request as
+# Markdown (scripts/recordMarkdown.js) with the page's link. The page holds
+# every commit; the comment holds the commits a push added, or every commit
+# when the pull request is opened or reopened or its branch is force-pushed.
 #
 # A pull request from a branch of this repository runs on pull_request, with
-# its own workflow and renderer. A pull request from a fork runs on
-# pull_request_target, which GitHub takes from the default branch and runs
-# with the repository's secrets: it executes only the default branch's code,
-# and the fork's commits are fetched as git data and never checked out.
+# the workflow and renderer of its merge into the base branch: GitHub takes
+# the workflow from that merge, so the renderer comes from it too, and a
+# branch made before the workflow changed still gets matching scripts. A
+# pull request from a fork runs on pull_request_target, which GitHub takes
+# from the default branch and runs with the repository's secrets: it
+# executes only the default branch's code, and the fork's commits are
+# fetched as git data and never checked out.
+#
+# Pages are never deleted, so the links in the comments stay valid after a
+# pull request is merged or closed.
 
 on:
   pull_request:
-    types: [opened, synchronize, reopened, closed]
+    types: [opened, synchronize, reopened]
   pull_request_target:
-    types: [opened, synchronize, reopened, closed]
+    types: [opened, synchronize, reopened]
 
 concurrency:
   group: semantic-diff-${{ github.event_name }}-${{ github.event.pull_request.number }}
@@ -22,7 +31,6 @@ concurrency:
 jobs:
   render:
     if: >-
-      github.event.action != 'closed' &&
       github.actor != 'dependabot[bot]' &&
       (github.event_name == 'pull_request') ==
       (github.event.pull_request.head.repo.full_name == github.repository)
@@ -34,11 +42,14 @@ jobs:
       PR_NUMBER: ${{ github.event.pull_request.number }}
       PR_TITLE: ${{ github.event.pull_request.title }}
       BASE_SHA: ${{ github.event.pull_request.base.sha }}
+      # The head before a push; empty when the pull request is opened or
+      # reopened.
+      BEFORE_SHA: ${{ github.event.action == 'synchronize' && github.event.before || '' }}
     steps:
       - name: Checkout renderer
         uses: actions/checkout@v7
         with:
-          ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.event.pull_request.base.sha }}
+          ref: ${{ github.event_name == 'pull_request' && github.sha || github.event.pull_request.base.sha }}
           fetch-depth: 0
           filter: blob:none
           persist-credentials: false
@@ -48,9 +59,21 @@ jobs:
         run: |
           git fetch --no-tags --filter=blob:none origin "refs/pull/${PR_NUMBER}/head:refs/heads/pr-${PR_NUMBER}"
           base=$(git merge-base "$BASE_SHA" "pr-${PR_NUMBER}")
+          head=$(git rev-parse --short=9 "pr-${PR_NUMBER}")
+          # The query string names the rendered commit, so each push gets a
+          # URL that no cache has seen.
+          url="https://cdn.rescript-lang.org/semantic-diff/pr-${PR_NUMBER}/index.html?v=${head}"
+          # A push that keeps the previous head adds commits on top of it:
+          # the comment holds those. After a force push the previous head is
+          # no ancestor (nor, from a fork, fetched), and the comment holds
+          # every commit.
+          since=()
+          if [ -n "$BEFORE_SHA" ] && git merge-base --is-ancestor "$BEFORE_SHA" "pr-${PR_NUMBER}" 2>/dev/null; then
+            since=(--since "$BEFORE_SHA")
+          fi
           mkdir -p semantic-diff
-          node scripts/commitRecords.js --out semantic-diff/index.html --pr "$PR_NUMBER" --title "$PR_TITLE" "${base}..pr-${PR_NUMBER}"
-          echo "head=$(git rev-parse --short=9 "pr-${PR_NUMBER}")" >> "$GITHUB_OUTPUT"
+          node scripts/commitRecords.js --out semantic-diff/index.html --markdown semantic-diff/comment.md "${since[@]}" --url "$url" --pr "$PR_NUMBER" --title "$PR_TITLE" "${base}..pr-${PR_NUMBER}"
+          echo "head=${head}" >> "$GITHUB_OUTPUT"
 
       - name: Setup Rclone
         uses: cometkim/rclone-actions/setup-rclone@8d9c6b95341f7698609deee65c3d62af42893288 # main, 2025-06-18
@@ -68,41 +91,14 @@ jobs:
       - name: Upload semantic diff
         run: rclone copyto --s3-no-check-bucket semantic-diff/index.html "rescript:cdn-assets/semantic-diff/pr-${PR_NUMBER}/index.html"
 
-      # The query string names the rendered commit, so each push gets a URL
-      # that no cache has seen.
-      - name: Comment semantic diff URL
+      # A push that adds only merge commits writes no comment.
+      - name: Comment semantic diff
+        if: hashFiles('semantic-diff/comment.md') != ''
         uses: thollander/actions-comment-pull-request@v3
         with:
           pr-number: ${{ github.event.pull_request.number }}
-          comment-tag: semantic-diff
-          # Each push replaces the comment, so the newest link is the last
-          # comment on the pull request.
-          mode: recreate
-          message: |
-            Semantic diff: https://cdn.rescript-lang.org/semantic-diff/pr-${{ github.event.pull_request.number }}/index.html?v=${{ steps.render.outputs.head }}
-
-  cleanup:
-    if: >-
-      github.event.action == 'closed' &&
-      github.actor != 'dependabot[bot]' &&
-      (github.event_name == 'pull_request') ==
-      (github.event.pull_request.head.repo.full_name == github.repository)
-    runs-on: ubuntu-26.04
-    permissions: {}
-    steps:
-      - name: Setup Rclone
-        uses: cometkim/rclone-actions/setup-rclone@8d9c6b95341f7698609deee65c3d62af42893288 # main, 2025-06-18
-
-      - name: Configure Rclone remote
-        uses: cometkim/rclone-actions/configure-remote/s3-provider@8d9c6b95341f7698609deee65c3d62af42893288 # main, 2025-06-18
-        with:
-          name: rescript
-          provider: Cloudflare
-          endpoint: https://${{ vars.CLOUDFLARE_ACCOUNT_ID }}.r2.cloudflarestorage.com
-          access-key-id: ${{ secrets.CLOUDFLARE_R2_ACCESS_KEY_ID }}
-          secret-access-key: ${{ secrets.CLOUDFLARE_R2_SECRET_ACCESS_KEY }}
-          acl: private
-
-      - name: Delete semantic diff
-        continue-on-error: true
-        run: rclone purge --s3-no-check-bucket "rescript:cdn-assets/semantic-diff/pr-${{ github.event.pull_request.number }}"
+          # Each push gets its own comment, so the comments of earlier pushes
+          # stay; a re-run of the same head updates its comment.
+          comment-tag: semantic-diff-${{ steps.render.outputs.head }}
+          mode: upsert
+          file-path: semantic-diff/comment.md

AGENTS.md

@@ -105,7 +105,8 @@ on `master`. CI runs on every PR in the stack.
 For compiler or standard-library changes, run `make test`. For syntax changes,
 also run `make test-syntax`; use `make test-syntax-roundtrip` when parsing or
 printing changes. Other focused suites are `make test-gentype`,
-`make test-analysis`, `make test-tools`, and `make test-rewatch`.
+`make test-analysis`, `make test-tools`, `make test-rewatch` (OCaml build
+system), and `make test-rewatch-rust` (Rust build system).
 
 ### Testing Requirements
 

Makefile

@@ -188,6 +188,9 @@ test-gentype: lib
 test-rewatch: lib
 	./rewatch/tests/suite.sh $(RESCRIPT_EXE)
 
+test-rewatch-rust: lib rewatch
+	./rewatch/tests/suite.sh $(RESCRIPT_RUST_EXE)
+
 test-all: test test-gentype test-analysis test-tools test-rewatch
 
 # Playground
@@ -382,4 +385,4 @@ clean: clean-lib clean-compiler clean-rewatch clean-coverage
 
 .DEFAULT_GOAL := build
 
-.PHONY: yarn-install build rewatch compiler lib artifacts bench test test-analysis test-reanalyze benchmark-reanalyze test-tools test-syntax test-syntax-roundtrip test-gentype test-rewatch test-all playground playground-compiler playground-test playground-cmijs playground-release format checkformat semantic-diff clean-rewatch clean-compiler clean-lib clean-gentype clean-tests clean
+.PHONY: yarn-install build rewatch compiler lib artifacts bench test test-analysis test-reanalyze benchmark-reanalyze test-tools test-syntax test-syntax-roundtrip test-gentype test-rewatch test-rewatch-rust test-all playground playground-compiler playground-test playground-cmijs playground-release format checkformat semantic-diff clean-rewatch clean-compiler clean-lib clean-gentype clean-tests clean

analysis/src/process_attributes.ml

@@ -4,7 +4,7 @@ open Shared_types
 let rec find_doc_attribute attributes =
   match attributes with
   | [] -> None
-  | ({Asttypes.txt = "ocaml.doc" | "ns.doc" | "res.doc"}, payload) :: rest -> (
+  | ({Asttypes.txt = "res.doc"}, payload) :: rest -> (
     match Ast_payload.semantic_string_of_payload payload with
     | Some doc -> Some doc
     | None -> find_doc_attribute rest)

analysis/src/type_utils.ml

@@ -476,7 +476,8 @@ let rec extract_type ?(print_opening_debug = true)
           {
             name = label;
             display_name =
-              Utils.print_maybe_exotic_ident ~allow_uident:true label;
+              Res_printer.print_poly_var_ident label
+              |> Res_doc.to_string ~width:80;
             args =
               (* Multiple arguments are represented as a Ttuple, while a single argument is just the type expression itself. *)
               (match field with

analysis/src/utils.ml

@@ -242,29 +242,6 @@ let rec flatten_any_namespace_in_path path =
       (parts |> List.rev) @ flatten_any_namespace_in_path tail
     else head :: flatten_any_namespace_in_path tail
 
-let print_maybe_exotic_ident ?(allow_uident = false) txt =
-  let len = String.length txt in
-
-  let rec loop i =
-    if i == len then txt
-    else if i == 0 then
-      match String.unsafe_get txt i with
-      | 'A' .. 'Z' when allow_uident -> loop (i + 1)
-      | 'a' .. 'z' | '$' -> loop (i + 1)
-      (* Same as Res_printer.classify_ident_content: a lone [_] or one
-         followed by another character is not scanned as an identifier. *)
-      | '_' when len > 1 -> (
-        match String.unsafe_get txt 1 with
-        | 'A' .. 'Z' | 'a' .. 'z' | '0' .. '9' | '_' | '$' -> loop (i + 1)
-        | _ -> "\"" ^ txt ^ "\"")
-      | _ -> "\"" ^ txt ^ "\""
-    else
-      match String.unsafe_get txt i with
-      | 'A' .. 'Z' | 'a' .. 'z' | '0' .. '9' | '\'' | '_' | '$' -> loop (i + 1)
-      | _ -> "\"" ^ txt ^ "\""
-  in
-  if Res_token.is_keyword_txt txt then "\"" ^ txt ^ "\"" else loop 0
-
 let find_package_json root =
   let path = Uri.to_path root in
 

changes/as-literals-by-value.fix.md

@@ -0,0 +1 @@
+- Reject `@as` literals of one variant that are the same JavaScript value, such as `@as(1)` and `@as(1.0)`, and accept `@as(1)` beside `@as(1n)`.

changes/as-payload-error-lists-float-bigint.polish.md

@@ -0,0 +1 @@
+- List floats and bigints in the error for an invalid `@as` payload, since `@as` accepts them.