From 398ef953846cfe98c947a072573e20195c24af5c Mon Sep 17 00:00:00 2001 From: Florian Hammerschmidt Date: Mon, 12 Oct 2026 10:13:29 +0200 Subject: [PATCH 1/2] 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 9f9ad342906c9298c589e1f58aced04be12765fd Mon Sep 17 00:00:00 2001 From: Florian Hammerschmidt Date: Mon, 12 Oct 2026 10:43:35 +0200 Subject: [PATCH 2/2] 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