From aa47e87128f79ca50019111f08909bbd72d42faf Mon Sep 17 00:00:00 2001 From: Florian Hammerschmidt Date: Mon, 12 Oct 2026 00:41:54 +0200 Subject: [PATCH 1/5] ci: check ReScript formatting and committed output Check ReScript formatting across all workspaces alongside Oxfmt. Clean and rebuild before comparing tracked JavaScript output, refresh guide routes output, and share the root format commands with the docs workspace. Refs #1416 and #1421. --- .github/workflows/pull-request.yml | 4 +++- README.md | 14 ++++++++++++++ apps/docs/package.json | 4 ++-- apps/guide/app/routes.jsx | 4 +++- package.json | 5 +++-- 5 files changed, 25 insertions(+), 6 deletions(-) diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index 941da3094..41ac49dd1 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -17,7 +17,7 @@ jobs: cache: yarn - name: Install dependencies run: yarn - - name: Format check + - name: Check formatting (Oxfmt and ReScript) run: yarn ci:format Site_Checks: runs-on: ubuntu-latest @@ -35,6 +35,8 @@ jobs: cache: yarn - name: Install dependencies run: yarn + - name: Check committed ReScript output + run: yarn ci:generated - name: Test examples and hrefs run: yarn test # Confirms that Wrangler can start the Docs Pages and Guide local dev servers. diff --git a/README.md b/README.md index 2630705a2..5d0774ef0 100644 --- a/README.md +++ b/README.md @@ -102,6 +102,20 @@ Tailwind is configured in [`styles/main.css`](styles/main.css). There is no `tai ## Testing +### Formatting and Generated Output + +`yarn ci:format` checks Oxfmt formatting and ReScript formatting across all four +workspaces. Run `yarn format` to apply both formatters. + +`yarn ci:generated` cleans and rebuilds ReScript, then fails if any tracked `.jsx` +or `.mjs` file differs from the committed version. Most compiler output is ignored +by Git; the guide's `app/root.jsx` and `app/routes.jsx` are currently tracked. +After changing their ReScript sources or updating the compiler, run +`yarn build:res` and commit the regenerated output alongside the sources. + +Both checks run on pull requests. The generated-output check uses a clean build +so a local compiler cache cannot hide stale output. + ### Vitest Browser Tests We use [Vitest](https://vitest.dev/) in browser mode with Playwright for component-level tests. Test files live in `__tests__/` and are written in ReScript. diff --git a/apps/docs/package.json b/apps/docs/package.json index e7350a978..52e01f787 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -15,7 +15,7 @@ "build:vite": "react-router build", "check:algolia-public-env": "node _scripts/LogAlgoliaEnvStatus.mjs", "build": "yarn build:res && yarn build:scripts && yarn check:algolia-public-env && yarn build:update-index && yarn build:vite && yarn build:generate-sitemap", - "ci:format": "cd ../.. && oxfmt --check", + "ci:format": "cd ../.. && yarn ci:format", "ci:homepage-performance": "node --test scripts/__tests__/homepage-compiler.test.mjs && node scripts/homepage-performance.mjs", "ci:test": "vitest --run --browser.headless", "ci:test:e2e": "cypress run --config-file cypress.homepage.config.mjs --browser chrome", @@ -28,7 +28,7 @@ "dev:vite": "react-router dev --host", "dev:wrangler": "yarn build:vite && yarn wrangler pages dev build/client", "dev": "yarn prepare && yarn dev:res & yarn dev:vite & yarn dev:wrangler", - "format": "cd ../.. && oxfmt && cd apps/docs && rescript format", + "format": "cd ../.. && yarn format", "prepare": "yarn build:res && yarn build:scripts && yarn check:algolia-public-env && yarn build:update-index", "preview": "yarn build && static-server build/client", "serve:build": "static-server --host 127.0.0.1 --port 4173 build/client", diff --git a/apps/guide/app/routes.jsx b/apps/guide/app/routes.jsx index c22c7185b..e793a07bf 100644 --- a/apps/guide/app/routes.jsx +++ b/apps/guide/app/routes.jsx @@ -4,5 +4,7 @@ import * as Routes from "@react-router/dev/routes"; let $$default = [Routes.index("./GuideHomeRoute.jsx")]; -export { $$default as default }; +export { + $$default as default, +} /* default Not a pure module */ diff --git a/package.json b/package.json index b54140105..4eff69ce9 100644 --- a/package.json +++ b/package.json @@ -18,7 +18,8 @@ "build:update-index": "yarn workspace @rescript-lang/docs build:update-index", "build:vite": "yarn workspace @rescript-lang/docs build:vite", "build": "yarn workspace @rescript-lang/docs build", - "ci:format": "oxfmt --check", + "ci:format": "oxfmt --check && rescript format --check", + "ci:generated": "yarn clean:res && yarn build:res && git diff --exit-code -- '*.jsx' '*.mjs'", "ci:homepage-performance": "yarn workspace @rescript-lang/docs ci:homepage-performance", "ci:test": "yarn workspace @rescript-lang/docs ci:test && yarn workspace @rescript-lang/guide ci:test", "ci:test:e2e": "yarn workspace @rescript-lang/docs ci:test:e2e", @@ -30,7 +31,7 @@ "dev:vite": "yarn workspace @rescript-lang/docs dev:vite", "dev:wrangler": "yarn workspace @rescript-lang/docs dev:wrangler", "dev": "yarn workspace @rescript-lang/docs dev", - "format": "yarn workspace @rescript-lang/docs format", + "format": "oxfmt && rescript format", "prepare": "yarn workspace @rescript-lang/docs prepare", "preview": "yarn workspace @rescript-lang/docs preview", "reanalyze": "yarn workspace @rescript-lang/docs reanalyze", From 48b19884b699090926ec2ebb79e4152740be732d Mon Sep 17 00:00:00 2001 From: Florian Hammerschmidt Date: Mon, 12 Oct 2026 00:51:13 +0200 Subject: [PATCH 2/5] fix: reject orphaned tracked compiler output Remove compiler-generated tracked files identified by their committed header before rebuilding. Preserve handwritten JavaScript and detect output whose source was deleted or whose workspace was excluded from the build. --- .../scripts/clean-tracked-rescript-output.sh | 13 +++++++++++++ README.md | 17 +++++++++-------- package.json | 2 +- 3 files changed, 23 insertions(+), 9 deletions(-) create mode 100644 .github/scripts/clean-tracked-rescript-output.sh diff --git a/.github/scripts/clean-tracked-rescript-output.sh b/.github/scripts/clean-tracked-rescript-output.sh new file mode 100644 index 000000000..fe3ba5edf --- /dev/null +++ b/.github/scripts/clean-tracked-rescript-output.sh @@ -0,0 +1,13 @@ +#!/usr/bin/env bash +set -euo pipefail + +# rescript clean only knows sources that still belong to the build. Identify +# tracked compiler output from the index so deleted/excluded sources are covered, +# while handwritten JavaScript and configuration remain untouched. +git ls-files -z -- '*.jsx' '*.mjs' | + while IFS= read -r -d '' output; do + committed=$(git show ":$output") + if [[ "$committed" == "// Generated by ReScript,"* ]]; then + rm -f -- "$output" + fi + done diff --git a/README.md b/README.md index 5d0774ef0..ce49a0964 100644 --- a/README.md +++ b/README.md @@ -107,14 +107,15 @@ Tailwind is configured in [`styles/main.css`](styles/main.css). There is no `tai `yarn ci:format` checks Oxfmt formatting and ReScript formatting across all four workspaces. Run `yarn format` to apply both formatters. -`yarn ci:generated` cleans and rebuilds ReScript, then fails if any tracked `.jsx` -or `.mjs` file differs from the committed version. Most compiler output is ignored -by Git; the guide's `app/root.jsx` and `app/routes.jsx` are currently tracked. -After changing their ReScript sources or updating the compiler, run -`yarn build:res` and commit the regenerated output alongside the sources. - -Both checks run on pull requests. The generated-output check uses a clean build -so a local compiler cache cannot hide stale output. +`yarn ci:generated` cleans ReScript artifacts, removes tracked compiler output, +and rebuilds, then fails if any tracked `.jsx` or `.mjs` file differs from the +committed version. Most compiler output is ignored by Git; the guide's +`app/root.jsx` and `app/routes.jsx` are currently tracked. After changing their +ReScript sources or updating the compiler, run `yarn build:res` and commit the +regenerated output alongside the sources. + +Both checks run on pull requests. Removing tracked output before rebuilding also +catches orphaned output whose source was deleted or excluded from the build. ### Vitest Browser Tests diff --git a/package.json b/package.json index 4eff69ce9..75eaf654b 100644 --- a/package.json +++ b/package.json @@ -19,7 +19,7 @@ "build:vite": "yarn workspace @rescript-lang/docs build:vite", "build": "yarn workspace @rescript-lang/docs build", "ci:format": "oxfmt --check && rescript format --check", - "ci:generated": "yarn clean:res && yarn build:res && git diff --exit-code -- '*.jsx' '*.mjs'", + "ci:generated": "yarn clean:res && bash .github/scripts/clean-tracked-rescript-output.sh && yarn build:res && git diff --exit-code -- '*.jsx' '*.mjs'", "ci:homepage-performance": "yarn workspace @rescript-lang/docs ci:homepage-performance", "ci:test": "yarn workspace @rescript-lang/docs ci:test && yarn workspace @rescript-lang/guide ci:test", "ci:test:e2e": "yarn workspace @rescript-lang/docs ci:test:e2e", From 398ef953846cfe98c947a072573e20195c24af5c Mon Sep 17 00:00:00 2001 From: Florian Hammerschmidt Date: Mon, 12 Oct 2026 10:13:29 +0200 Subject: [PATCH 3/5] chore: prune redundant package script aliases Keep focused docs helpers in their workspace and retain contributor commands with an explicit purpose. Document manual tools and Yarn preparation behavior, and remove duplicate docs formatting and cleaning entries. --- apps/docs/package.json | 2 -- apps/docs/scripts/README.md | 38 ++++++++++++++++++++++++++++++++++++- package.json | 6 ------ 3 files changed, 37 insertions(+), 9 deletions(-) diff --git a/apps/docs/package.json b/apps/docs/package.json index e7350a978..6938ac279 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -15,14 +15,12 @@ "build:vite": "react-router build", "check:algolia-public-env": "node _scripts/LogAlgoliaEnvStatus.mjs", "build": "yarn build:res && yarn build:scripts && yarn check:algolia-public-env && yarn build:update-index && yarn build:vite && yarn build:generate-sitemap", - "ci:format": "cd ../.. && oxfmt --check", "ci:homepage-performance": "node --test scripts/__tests__/homepage-compiler.test.mjs && node scripts/homepage-performance.mjs", "ci:test": "vitest --run --browser.headless", "ci:test:e2e": "cypress run --config-file cypress.homepage.config.mjs --browser chrome", "ci:test:scripts": "yarn build:scripts && vitest run --config vitest.scripts.config.mjs && node --test scripts/__tests__/generate-llms.test.mjs scripts/__tests__/test-examples.test.mjs scripts/__tests__/test-hrefs.test.mjs scripts/__tests__/test-runner.test.mjs", "ci:test:visual": "VISUAL_TESTS=1 vitest --run --browser.headless", "ci:test:visual:update": "VISUAL_TESTS=1 VISUAL_BASELINE_UPDATE=1 vitest --run --browser.headless --update", - "clean:res": "rescript clean", "convert-images": "auto-convert-images", "dev:res": "rescript watch", "dev:vite": "react-router dev --host", diff --git a/apps/docs/scripts/README.md b/apps/docs/scripts/README.md index b188c7648..97a8bff17 100644 --- a/apps/docs/scripts/README.md +++ b/apps/docs/scripts/README.md @@ -1,4 +1,40 @@ -# Homepage Performance Checks +# Docs Workspace Commands + +Run the common development, build, test, and formatting commands from the +repository root. Focused docs helpers live in the docs workspace; invoke them +with `yarn workspace @rescript-lang/docs `: + +| Command | Purpose | +| ------------------------- | -------------------------------------------------------------------------------------------------------- | +| `prepare` | Compile ReScript and build scripts, check public search config, and generate LLM files and the blog feed | +| `build:generate-llms` | Regenerate LLM files after compiling and bundling the scripts | +| `dev:vite` | Run only the React Router/Vite development server | +| `dev:wrangler` | Build the docs client and serve it through Wrangler Pages | +| `ci:homepage-performance` | Test the homepage asset reporter and report production-build asset sizes | +| `ci:test:e2e` | Run homepage Cypress specs against an already-running production server | + +`yarn dev` explicitly calls the workspace's `prepare` before starting its +watcher. Yarn 4 does not run `prepare` automatically during installation; see +[Yarn's supported lifecycle scripts](https://yarnpkg.com/advanced/lifecycle-scripts). +The `lefthook` dependency has its own `postinstall` for Git hook installation. +Use root `yarn clean:res` to clean compiler output and `yarn ci:format` to check +formatting. + +These contributor tools intentionally run manually. Compile browser test specs +with `yarn build:res` before running the watch commands: + +- `yarn vitest:guide` watches the guide's browser tests. +- `yarn vitest:visual` watches the docs visual tests. Screenshot updates use the + repository's screenshot workflow. +- `yarn convert-images` runs the docs image converter using + [`image-converter.config.mjs`](../image-converter.config.mjs). It converts + PNG/JPG/JPEG files under `apps/docs/public/` to AVIF and removes the converted + originals. Review the resulting asset and reference changes before committing. +- The `cy:open`, `cy:run`, `cy:e2e`, and `test:e2e` root commands support local + Cypress testing. `test:e2e` builds the docs and manages its homepage test server; + the `cy:*` commands require a running full-site server. + +## Homepage Performance Checks `homepage-performance.mjs` measures local JavaScript and CSS explicitly referenced by the built homepage HTML, deduplicating script, module preload, and stylesheet diff --git a/package.json b/package.json index b54140105..133fdfe85 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,6 @@ ], "scripts": { "build:scripts": "yarn workspace @rescript-lang/docs build:scripts", - "build:generate-llms": "yarn workspace @rescript-lang/docs build:generate-llms", "build:guide": "yarn workspace @rescript-lang/guide build", "build:res": "rescript build --warn-error +3+8+11+12+26+27+31+32+33+34+35+39+44+45+110", "build:sync-bundles": "yarn workspace @rescript-lang/docs build:sync-bundles", @@ -19,19 +18,14 @@ "build:vite": "yarn workspace @rescript-lang/docs build:vite", "build": "yarn workspace @rescript-lang/docs build", "ci:format": "oxfmt --check", - "ci:homepage-performance": "yarn workspace @rescript-lang/docs ci:homepage-performance", "ci:test": "yarn workspace @rescript-lang/docs ci:test && yarn workspace @rescript-lang/guide ci:test", - "ci:test:e2e": "yarn workspace @rescript-lang/docs ci:test:e2e", "ci:test:visual": "yarn workspace @rescript-lang/docs ci:test:visual", "clean:res": "rescript clean", "convert-images": "yarn workspace @rescript-lang/docs convert-images", "dev:res": "rescript watch", "dev:guide": "yarn workspace @rescript-lang/guide dev:vite", - "dev:vite": "yarn workspace @rescript-lang/docs dev:vite", - "dev:wrangler": "yarn workspace @rescript-lang/docs dev:wrangler", "dev": "yarn workspace @rescript-lang/docs dev", "format": "yarn workspace @rescript-lang/docs format", - "prepare": "yarn workspace @rescript-lang/docs prepare", "preview": "yarn workspace @rescript-lang/docs preview", "reanalyze": "yarn workspace @rescript-lang/docs reanalyze", "test": "yarn workspace @rescript-lang/docs test", From c5339ac7b3040e19c33c5310a8c71996ab9b159b Mon Sep 17 00:00:00 2001 From: Florian Hammerschmidt Date: Mon, 12 Oct 2026 10:15:13 +0200 Subject: [PATCH 4/5] chore: align script aliases with the package audit Remove the unused root performance and preparation aliases and the redundant docs formatting entry also removed by #1419. Keep the workspace helpers and root formatter checks so the CI and script-audit PRs merge cleanly. --- apps/docs/package.json | 1 - package.json | 2 -- 2 files changed, 3 deletions(-) diff --git a/apps/docs/package.json b/apps/docs/package.json index 52e01f787..ef7a1f18a 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -15,7 +15,6 @@ "build:vite": "react-router build", "check:algolia-public-env": "node _scripts/LogAlgoliaEnvStatus.mjs", "build": "yarn build:res && yarn build:scripts && yarn check:algolia-public-env && yarn build:update-index && yarn build:vite && yarn build:generate-sitemap", - "ci:format": "cd ../.. && yarn ci:format", "ci:homepage-performance": "node --test scripts/__tests__/homepage-compiler.test.mjs && node scripts/homepage-performance.mjs", "ci:test": "vitest --run --browser.headless", "ci:test:e2e": "cypress run --config-file cypress.homepage.config.mjs --browser chrome", diff --git a/package.json b/package.json index 75eaf654b..1e373cc5a 100644 --- a/package.json +++ b/package.json @@ -20,7 +20,6 @@ "build": "yarn workspace @rescript-lang/docs build", "ci:format": "oxfmt --check && rescript format --check", "ci:generated": "yarn clean:res && bash .github/scripts/clean-tracked-rescript-output.sh && yarn build:res && git diff --exit-code -- '*.jsx' '*.mjs'", - "ci:homepage-performance": "yarn workspace @rescript-lang/docs ci:homepage-performance", "ci:test": "yarn workspace @rescript-lang/docs ci:test && yarn workspace @rescript-lang/guide ci:test", "ci:test:e2e": "yarn workspace @rescript-lang/docs ci:test:e2e", "ci:test:visual": "yarn workspace @rescript-lang/docs ci:test:visual", @@ -32,7 +31,6 @@ "dev:wrangler": "yarn workspace @rescript-lang/docs dev:wrangler", "dev": "yarn workspace @rescript-lang/docs dev", "format": "oxfmt && rescript format", - "prepare": "yarn workspace @rescript-lang/docs prepare", "preview": "yarn workspace @rescript-lang/docs preview", "reanalyze": "yarn workspace @rescript-lang/docs reanalyze", "test": "yarn workspace @rescript-lang/docs test", From ad6fda1ec416996c90fe3ee39fbb8bf8817001c7 Mon Sep 17 00:00:00 2001 From: Florian Hammerschmidt Date: Mon, 12 Oct 2026 10:43:35 +0200 Subject: [PATCH 5/5] docs: remove redundant package command guide Keep the package-script audit focused on the eight redundant entries. Explain retained manual commands in the PR description without duplicating package scripts and contributor documentation. --- apps/docs/scripts/README.md | 38 +------------------------------------ 1 file changed, 1 insertion(+), 37 deletions(-) diff --git a/apps/docs/scripts/README.md b/apps/docs/scripts/README.md index 97a8bff17..b188c7648 100644 --- a/apps/docs/scripts/README.md +++ b/apps/docs/scripts/README.md @@ -1,40 +1,4 @@ -# Docs Workspace Commands - -Run the common development, build, test, and formatting commands from the -repository root. Focused docs helpers live in the docs workspace; invoke them -with `yarn workspace @rescript-lang/docs `: - -| Command | Purpose | -| ------------------------- | -------------------------------------------------------------------------------------------------------- | -| `prepare` | Compile ReScript and build scripts, check public search config, and generate LLM files and the blog feed | -| `build:generate-llms` | Regenerate LLM files after compiling and bundling the scripts | -| `dev:vite` | Run only the React Router/Vite development server | -| `dev:wrangler` | Build the docs client and serve it through Wrangler Pages | -| `ci:homepage-performance` | Test the homepage asset reporter and report production-build asset sizes | -| `ci:test:e2e` | Run homepage Cypress specs against an already-running production server | - -`yarn dev` explicitly calls the workspace's `prepare` before starting its -watcher. Yarn 4 does not run `prepare` automatically during installation; see -[Yarn's supported lifecycle scripts](https://yarnpkg.com/advanced/lifecycle-scripts). -The `lefthook` dependency has its own `postinstall` for Git hook installation. -Use root `yarn clean:res` to clean compiler output and `yarn ci:format` to check -formatting. - -These contributor tools intentionally run manually. Compile browser test specs -with `yarn build:res` before running the watch commands: - -- `yarn vitest:guide` watches the guide's browser tests. -- `yarn vitest:visual` watches the docs visual tests. Screenshot updates use the - repository's screenshot workflow. -- `yarn convert-images` runs the docs image converter using - [`image-converter.config.mjs`](../image-converter.config.mjs). It converts - PNG/JPG/JPEG files under `apps/docs/public/` to AVIF and removes the converted - originals. Review the resulting asset and reference changes before committing. -- The `cy:open`, `cy:run`, `cy:e2e`, and `test:e2e` root commands support local - Cypress testing. `test:e2e` builds the docs and manages its homepage test server; - the `cy:*` commands require a running full-site server. - -## Homepage Performance Checks +# Homepage Performance Checks `homepage-performance.mjs` measures local JavaScript and CSS explicitly referenced by the built homepage HTML, deduplicating script, module preload, and stylesheet