Add rewatch as an alternative build system to eventually replace bsb

[cknitt]

• Add rewatch to compiler repo + CI + the rescript npm package (as an experimental alternative to bsb)
• Use rewatch to build the standard libraries (OCaml stdlib, Caml_*, Belt, Js)
• (Move Core into the compiler, move other stdlibs out of the compiler, ...)
• Remove bsb, do not ship any compiled stdlib artifacts with the ReScript npm package anymore (see Split rescript npm package into multiple subpackages #6183)
• Remove bsb support from reanalyze https://github.com/rescript-lang/rescript/pull/8149/files#diff-f762e3324f935368317a5ac639e27f6b323a29eef74b2aa6340db6d82c370195R137

[nojaf]

Is it the plan to make rewatch available from the node_modules/.bin folder?
It is not yet the case with 12.0.0-alpha.1.

[cknitt]

Yes, that would be the plan. Seems this was lost in a refactoring where the path to the rewatch wrapper script in package.json was not updated.

[nojaf]

This works for me in 12.0.0-alpha.2, thanks!

[cknitt]

rewatch is now included in v12, bsb will be removed in a future version. Core is now included in the compiler repo as the new stdlib.

Other items still in progress.

[nojaf]

BSB to Rewatch Migration Plan

Guess, who chatted a bit with Claude 😉

This outlines the plan to remove the legacy bsb build system and use rewatch as the single build system in the next major version of ReScript.

Executive Summary

• 27 build tests currently use the legacy build system (execBuildLegacy)
• 7 build tests already use the modern rewatch system (execBuild)
• Runtime/stdlib already builds with rewatch
• Several configuration features need team decisions on removal vs implementation

---

Questions for Team Discussion

Configuration Features to Remove or Keep

The following features are NOT implemented in rewatch (verified against rewatch/src/config.rs).

Rewatch explicitly lists these as unsupported in UNSUPPORTED_TOP_LEVEL_FIELDS:

• ignored-dirs
• generators
• cut-generators
• pp-flags
• entries
• use-stdlib
• external-stdlib
• bs-external-includes
• reanalyze

The team needs to decide whether to:

• Remove: Drop support entirely in the major version
• Implement: Add support to rewatch before migration

Feature	Current Status	Recommendation	Notes
generators	Explicitly unsupported	Remove	No tests exist, appears unused
cut-generators	Explicitly unsupported	Remove	Related to generators
ignored-dirs	Explicitly unsupported	Discuss	Only used in deprecated-config test
pp-flags	Explicitly unsupported	Discuss	Preprocessor (different from PPX), rarely used
use-stdlib	Removed	N/A	Already removed in v11 (see CHANGELOG)
external-stdlib	Removed	N/A	Removed - team confirmed not needed
bs-external-includes	Explicitly unsupported	Discuss	External include paths
reanalyze	Explicitly unsupported	Discuss	Config in rescript.json; but rewatch generates .sourcedirs.json for reanalyze
entries	Explicitly unsupported	Remove	Marked as "likely to be removed" in spec
package-specs as string[]	Not implemented	Discuss	e.g., ["es6", "commonjs"] shorthand (only object form supported)
Source files filtering	Not implemented	Discuss	Include/exclude specific files
Source public	Not implemented	Discuss	Control module visibility
Source resources	Not implemented	Discuss	Copy non-ReScript files
Source group	Not implemented	Remove	Spec says not implemented in ReScript
Source internal-depends	Not implemented	Discuss	Internal dependency hints
gentypeconfig.path	Pass-through only	Verify	Parsed as JSON value, passed to bsc; path not validated by rewatch

Specific Questions

1. Generators: Are there any known external users relying on generators or cut-generators? Can we safely remove?

2. ignored-dirs: Is this feature used in production projects? Should rewatch implement it?

3. pp-flags: Is the non-PPX preprocessor (pp-flags) still needed? Different from ppx-flags.

4. use-stdlib / external-stdlib: Removed - team confirmed these are not needed.

5. bs-external-includes: Are external include paths needed for any use cases?

6. Source public: Is module visibility control ("public": ["ModuleA", "ModuleB"]) used?

7. Source resources: Is resource file copying needed, or should users handle this separately?

8. reanalyze config: Rewatch already generates .sourcedirs.json for reanalyze. Should reanalyze configuration remain in rescript.json or be handled separately?

---

Features Already Implemented in Rewatch

Based on rewatch/src/config.rs and CHANGELOG, these are confirmed working:

Feature	Status	Notes
name	✅ Implemented
namespace (boolean)	✅ Implemented
namespace (string)	✅ Implemented	Custom namespace name
sources (all forms)	✅ Implemented	string, array, Source object
sources.type: "dev"	✅ Implemented	Dev sources compiled by default for local packages (v12)
sources.subdirs	✅ Implemented	boolean, array of string, array of Source
dependencies	✅ Implemented
dev-dependencies	✅ Implemented
jsx	✅ Implemented	version, module, mode, v3-dependencies
gentypeconfig	✅ Implemented	Pass-through to bsc
compiler-flags	✅ Implemented
warnings	✅ Implemented	number, error (boolean/string)
ppx-flags	✅ Implemented
js-post-build	✅ Implemented	Added in v12.1.0; ${file} is absolute path
package-specs (object)	✅ Implemented	module, in-source, suffix
suffix	✅ Implemented
experimental-features	✅ Implemented	e.g., LetUnwrap
editor	✅ Implemented	Pass-through for VS Code extension

Rewatch-Only Features (not in bsb)

Feature	Description
namespace-entry	Config field for monorepo support
allowed-dependents	Config field for dependency control
-f / --filter	CLI flag to filter source files by regex
-a / --after-build	CLI flag to run command after build
--no-timing	CLI flag to disable output timing

CLI Flag Comparison (bsb vs rewatch)

bsb flag	rewatch equivalent	Status
-w	watch subcommand	Different syntax (flag vs subcommand)
-ws [host]:port	-	Not in rewatch (WebSocket notifications)
-verbose	-v / --verbose	Available (different syntax)
-with-deps	N/A	Deprecated in both (now default)
-install	(automatic)	Built-in: rewatch copies to lib/ocaml automatically
-regen	-	Not needed: rewatch handles regeneration internally
-no-deps	-	Not needed: different watcher architecture
-runtime-path	RESCRIPT_RUNTIME env	Via environment variable instead of CLI flag
-warn-error	--warn-error	Same functionality
-	-f / --filter	New in rewatch
-	-a / --after-build	New in rewatch
-	--no-timing	New in rewatch

Notes:

• The -install functionality is automatic in rewatch - it copies .cmi, .cmj, .cmt, .cmti files to lib/ocaml as part of every build.
• The -runtime-path is handled via the RESCRIPT_RUNTIME environment variable. If not set, rewatch resolves @rescript/runtime from node_modules.
• The -ws WebSocket notifications feature has no equivalent in rewatch - this may need discussion if users rely on it.

Deprecated but Supported

Old Field	New Field	Notes
bs-dependencies	dependencies	Mutual exclusion enforced
bs-dev-dependencies	dev-dependencies	Mutual exclusion enforced
bsc-flags	compiler-flags	Mutual exclusion enforced
es6 module format	esmodule	Deprecation warning emitted
es6-global module format	-	Deprecation warning emitted

---

Legacy Code to Remove

Once all tests are migrated, the following can be removed:

JavaScript/Node Files

• lib_dev/process.js: Remove rescriptLegacy, execBuildLegacy, execCleanLegacy exports
• cli/rescript-legacy.js: Remove entire file
• cli/common/bsb.js: Remove entire file (legacy CLI support)

OCaml/Compiler Code

• compiler/bsb/: Remove entire directory (legacy build system)
• compiler/bsb_helper/: Remove entire directory (dependency file generator for bsb)
• compiler/bsb_exe/: Remove entire directory (bsb executables)
• compiler/bsb_helper_exe/: Remove entire directory (bsb_helper executable)

Binaries

• rescript_legacy_exe: Remove from build and distribution
• bsb_helper_exe: Remove from build and distribution

Build Configuration

• Update Makefile to remove legacy build targets
• Update dune files to remove bsb-related builds
• Update packages/@rescript/<platform>/bin to not include legacy binaries

---

Legacy Build Tests Migration

The following 27 tests use execBuildLegacy/execCleanLegacy and need migration to execBuild/execClean:

Test Details

#	Test Name	Features Tested	Config Fields	Priority
1	unboxed_bool_with_const	Compiler error for unboxed variants	package-specs (in-source, suffix)	High
2	weird_names	Special characters in filenames ([slug], 404.res)	sources.subdirs	High
3	case3	Case sensitivity in file naming	sources, warnings	Medium
4	cycle	Circular dependency detection	warnings.error	High
5	cycle1	Circular deps with namespace	namespace	High
6	devonly	Dev-only sources (type: "dev")	sources.type	High
7	unicode	Unicode in directory names (emoji 📕)	sources	Medium
8	rerror	Reason syntax error reporting	sources, dependencies	Medium
9	install	-install flag for OCaml artifacts	CLI flags	Low
10	not_undefined_attribute	@notUndefined attribute validation	sources	Medium
11	in_source	Multiple output formats (CJS + ES6)	package-specs (array)	High
12	weird_deps	Missing dependency error	dependencies	High
13	weird_devdeps	Dev-dependencies handling	dev-dependencies	High
14	gpr_978	Duplicate module export detection	sources	High
15	warn_legacy_config	bsconfig.json deprecation warning	Legacy config	Low
16	hyphen2	Hyphenated package names	namespace, sources	Medium
17	weird_names_not_found_bug	Module not found errors	sources, package-specs	Medium
18	xpkg	Reserved package name validation	sources	Medium
19	scoped_ppx	PPX with scoped npm packages	ppx-flags	High
20	duplicated_symlinked_packages	Symlinked package deduplication	dependencies	Medium
21	ns	Namespace with CommonJS	namespace, package-specs	High
22	react_ppx	JSX v4 with React PPX	jsx, namespace, dependencies	High
23	x-y	Hyphenated source directories	sources	Low
24	exports	Basic module exports	sources	Low
25	zerocycle	Build with no dependencies	dependencies: []	Low
26	nested	Nested directory module naming	sources.subdirs	High
27	nnest	Nested dirs with namespace	namespace, sources.subdirs	High
28	custom_namespace	Custom namespace string	namespace: "string", compiler-flags	High
29	transitive_dependency	Transitive dep handling	Multi-package dependencies	High
30	uncurried-always	Uncurried function mode	uncurried	Medium
31	jsx_settings_inheritance	JSX config inheritance	jsx, dependencies	High

Migration Priority

High Priority (core features, likely to expose gaps):

• cycle, cycle1 - Dependency cycle detection
• devonly - Dev source handling
• in_source - Multiple output formats
• weird_deps, weird_devdeps - Dependency validation
• ns, nnest, custom_namespace - Namespace features
• nested - Nested directory handling
• scoped_ppx - PPX support
• react_ppx, jsx_settings_inheritance - JSX configuration
• transitive_dependency - Transitive dependency handling
• gpr_978 - Duplicate module detection

Medium Priority (important but less likely to have gaps):

• weird_names, weird_names_not_found_bug - Special filename handling
• unicode - Unicode support
• case3 - Case sensitivity
• rerror - Error reporting
• not_undefined_attribute - Attribute validation
• hyphen2 - Hyphenated names
• xpkg - Package name validation
• duplicated_symlinked_packages - Symlink handling
• uncurried-always - Uncurried mode
• unboxed_bool_with_const - Compiler validation

Low Priority (simple tests or legacy features):

• x-y, exports, zerocycle - Basic build tests
• install - Legacy OCaml install feature
• warn_legacy_config - bsconfig.json warning (may remove)

---

Tests Already Using Rewatch

These 7 tests already use execBuild/execClean:

Test Name	Features Tested
post-build	js-post-build hook
case	Basic build
case2	Basic build
build_warn_as_error	Warning as error
deprecated-package-specs	Deprecation warnings
cli_help	CLI help output
cli_compile_status	Compilation status
super_errors	Error formatting

---

Migration Process

For each legacy test:

Step 1: Verify Rewatch Support

cd tests/build_tests/<test_name>
# Try building with rewatch
node ../../../cli/rescript.js build

Step 2: Update Test File

Change input.js from:

import { setup } from "#dev/process";
const { execBuildLegacy, execCleanLegacy } = setup(import.meta.dirname);
// ... uses execBuildLegacy(), execCleanLegacy()

To:

import { setup } from "#dev/process";
const { execBuild, execClean } = setup(import.meta.dirname);
// ... uses execBuild(), execClean()

Step 3: Verify Test Passes

cd tests/build_tests/<test_name> && node input.js

Or run all build tests:

node scripts/test.js -bsb

Step 4: Document Any Gaps

If rewatch doesn't support a feature, document it and decide whether to:

• Implement in rewatch
• Remove the test (if feature is deprecated)
• Keep test on legacy temporarily

---

bsb_helper Binary

What It Does

bsb_helper is a dependency file generator for the legacy Ninja-based build system:

1. Reads .mlast/.mliast files (AST files from bsc)
2. Extracts dependency information
3. Generates .d (depfile) files for Ninja incremental builds

Rewatch Replacement

Rewatch has its own dependency analysis in Rust (rewatch/src/build/deps.rs). It does not use bsb_helper.

Removal

bsb_helper can be safely removed along with bsb. Files to remove:

• compiler/bsb_helper/bsb_helper_depfile_gen.ml
• compiler/bsb_helper_exe/bsb_helper_main.ml

---

Timeline Checklist

Phase 1: Team Decisions

• Decide on each "Discuss" item in the configuration features table
• Confirm generators, cut-generators, entries, group can be removed
• Document breaking changes for release notes

Phase 2: Test Migration (one by one)

• Migrate high-priority tests first
• Document any rewatch gaps found during migration
• Implement missing rewatch features (if decided to keep)
• All 27 legacy tests migrated to rewatch

Phase 3: Code Removal

• Remove legacy exports from lib_dev/process.js
• Remove cli/rescript-legacy.js
• Remove compiler/bsb/ directory
• Remove compiler/bsb_helper/ directory
• Remove compiler/bsb_exe/ directory
• Remove compiler/bsb_helper_exe/ directory
• Update Makefile
• Update dune files

Phase 4: Cleanup

• Update CompilerConfigurationSpec.md (remove deprecated fields, add rewatch-only features)
• Update docs/docson/build-schema.json
• Update documentation website
• Add migration guide for users

---

Appendix: Current Build System Usage

Component	Current Build System	After Migration
Runtime/stdlib	rewatch	rewatch
Compiler tests (mocha)	rewatch	rewatch
Build tests	mixed (27 legacy / 7 modern)	rewatch
Rewatch integration tests	rewatch	rewatch
Analysis tests	rewatch	rewatch

---

References

• Rewatch config source: rewatch/src/config.rs
• CompilerConfigurationSpec: rewatch/CompilerConfigurationSpec.md
• CHANGELOG entries for rewatch features: Search "rewatch" in CHANGELOG.md
• Rewatch monorepo support: rewatch/MonorepoSupport.md