Local setup

Run commands from the repository root. The build pipeline installs the pinned compiler and fixture dependencies.

Prerequisites

Install the .NET SDK selected by global.json, Node.js 24 (see .node-version), npm, and Git.

git clone https://github.com/shayanhabibi/Xantham.git
cd Xantham
npm ci
dotnet build Xantham.slnx

The root package.json pins the TypeScript compiler used by the generator and live compiler tests. The pipeline installs the committed npm lockfile with npm ci.

Run the test pipeline

dotnet fsi build.fsx -- test

For Fable runtime checks as well:

dotnet fsi build.fsx -- test --run-gate

The compile-gate projects are ordinary projects: a solution build compiles their goldens. The run gate validates selected JavaScript behavior.

--quick reuses existing dependencies and build setup. --no-format skips local formatting while retaining setup; CI checks formatting. Use --explain to inspect the resolved stages without running them.

CI, packages and golden provenance

The Test workflow runs the complete suite and runtime gates. Each successful run uploads the committed corpus as golden/<fixture>/... in an artifact alongside provenance.json: the checked-out source commit and SHA-256 of every golden file. Golden contents retain their exact bytes. The artifact contains the checked, committed corpus; it does not regenerate or rewrite goldens. The known Linux Solid golden differences remain reported by the suite.

After a successful master push, the Tag goldens workflow creates an annotated goldens/<full-commit-hash> Git tag pointing to the tested source commit. Its annotation records the run and artifact digest. Reruns preserve an existing tag. Artifacts are retained for 90 days; tags remain in Git. Pull-request runs upload provenance artifacts but do not create tags.

The Publish workflow runs pack --ci --run-gate, transfers the verified packages to a separate job, then runs publish artifacts --ci. The NuGet key is exposed only to that final upload step. Local publish still runs the complete pipeline. The artifact command checks package filenames against selected project versions and rejects missing or unexpected packages before uploading.

Run the local CLI

dotnet run --project src/Xantham.Cli -- generate ./node_modules/your-package -o ./scratch/out

Replace the input with an installed package directory containing package.json.

Preview the website

dotnet fsi build.fsx -- docs --watch

Open http://localhost:8080/Xantham/.

For a static build:

dotnet fsi build.fsx -- docs

Pages are written to output/. The docs pipeline builds all six published library assemblies in Release before generating their API references. Missing assemblies fail the site build. The CLI is covered by the guide.

Working in a worktree

The build pipeline can borrow the main checkout's compiler installation. Fixture dependencies are installed separately in the worktree:

dotnet fsi tools/xantham-fixtures.fsx -- init

Use the pipeline for tests so compiler discovery and fixture setup follow the repository's conventions.