CLAUDE.md

1# GitHub Actions Workflow Maintenance Guide
2 
3This document provides guidance for maintaining the GitHub Actions workflows in this repository.
4 
5## format.yml Workflow
6 
7### Overview
8 
9The `format.yml` workflow runs code formatters (Prettier, clang-format, and `cargo fmt`) on pull requests and pushes to main. It's optimized for speed by running all formatters in parallel. It also regenerates the checked-in `*.generated.rs` string maps (`bun run codegen:string-maps`) before the formatters start: everything the step leaves modified, formatting or codegen, is what the autofix.ci action at the end of the job pushes back to the PR (failing the run when it had anything to push), so nothing that produces fixes may run after it, and nothing that only verifies should run before it.
10 
11### Key Components
12 
13#### 1. Clang-format Script (`scripts/run-clang-format.sh`)
14 
15- **Purpose**: Formats C++ source and header files
16- **What it does**:
17  - Globs C++ files via `bun scripts/glob-sources.ts cxx`
18  - Finds all header files in `src/` and `packages/`
19  - Excludes third-party directories (libuv, napi, deps, vendor, sqlite, etc.)
20  - Requires specific clang-format version (no fallbacks)
21 
22**Important exclusions**:
23 
24- `src/runtime/napi/` - Node API headers (third-party)
25- `src/jsc/bindings/libuv/` - libuv headers (third-party)
26- `src/jsc/bindings/sqlite/` - SQLite headers (third-party)
27- `src/runtime/ffi/ffi-*.h` - FFI headers (generated/third-party)
28- `src/deps/` - Dependencies (third-party)
29- Files in `vendor/`, `third_party/`, `generated/` directories
30 
31#### 2. Parallel Execution
32 
33The workflow runs all three formatters simultaneously:
34 
35- Each formatter outputs with a prefix (`[prettier]`, `[clang-format]`, `[rustfmt]`)
36- Output is streamed in real-time without blocking
37- Uses GitHub Actions groups (`::group::`) for collapsible sections
38 
39#### 3. Tool Installation
40 
41##### Clang-format-21
42 
43- Installs ONLY `clang-format-21` package (not the entire LLVM toolchain)
44- Uses `--no-install-recommends --no-install-suggests` to skip unnecessary packages
45- Quiet installation with `-qq` and `-o=Dpkg::Use-Pty=0`
46 
47##### Rustfmt
48 
49- The pinned nightly is set via `RUSTUP_TOOLCHAIN` in the step `env:` (kept in sync with `channel` in `rust-toolchain.toml`); `cargo fmt --all` runs against the workspace at the repo root.
50- `RUSTUP_TOOLCHAIN` makes rustup ignore `rust-toolchain.toml` entirely, so the workflow installs only the host toolchain + `rustfmt` (`rustup toolchain install --profile minimal --component rustfmt`) rather than the file's full cross-target list.
51 
52### Updating the Workflow
53 
54#### To update the Rust toolchain:
55 
561. Bump `channel` in `rust-toolchain.toml` (and `Dockerfile`/`bootstrap.sh` to match).
572. Bump `RUSTUP_TOOLCHAIN` in the `Format Code` step's `env:` block in `format.yml` to the same value.
583. Bump `RUSTUP_TOOLCHAIN` in the workflow-level `env:` block in `rust-lints.yml` to the same value.
594. `cargo fmt` formatting can change between nightlies; run `cargo fmt --all` locally on the new toolchain and include the resulting diff in the same PR.
60 
61#### To update clang-format version:
62 
631. Update `LLVM_VERSION_MAJOR` environment variable at the top of format.yml
642. Update the version check in `scripts/run-clang-format.sh`
65 
66#### To add/remove file exclusions:
67 
681. Edit the exclusion patterns in `scripts/run-clang-format.sh` (lines 34-39)
692. Test locally to ensure the right files are being formatted
70 
71### Performance Optimizations
72 
731. **Parallel execution**: All formatters run simultaneously
742. **Minimal installations**: Only required packages, no extras
753. **Streaming output**: Real-time feedback without buffering
764. **Early start**: Formatting begins immediately after each tool is ready
77 
78### Troubleshooting
79 
80**If formatters appear to run sequentially:**
81 
82- Check if output is being buffered (should use `sed` for line prefixing)
83- Ensure background processes use `&` and proper wait commands
84 
85**If third-party files are being formatted:**
86 
87- Review exclusion patterns in `scripts/run-clang-format.sh`
88- Check if new third-party directories were added that need exclusion
89 
90**If clang-format installation is slow:**
91 
92- Ensure using minimal package installation flags
93- Check if apt cache needs updating
94- Consider caching the clang-format binary between runs
95 
96### Testing Changes Locally
97 
98```bash
99# Test the clang-format script
100export LLVM_VERSION_MAJOR=19
101./scripts/run-clang-format.sh format
102 
103# Test with check mode (no modifications)
104./scripts/run-clang-format.sh check
105 
106# Test specific file exclusions
107./scripts/run-clang-format.sh format 2>&1 | grep -E "(libuv|napi|deps)"
108# Should return nothing if exclusions work correctly
109```
110 
111### Important Notes
112 
113- The script defaults to **format** mode (modifies files)
114- Always test locally before pushing workflow changes
115- Keep the exclusion list updated as new third-party code is added
116 
117## rust-lints.yml Workflow
118 
119Four independent jobs that each run one cargo command over the Rust workspace. They share `.github/actions/rust-lint-setup`, a composite action that installs LLVM from apt.llvm.org (configure resolves a clang even though nothing here compiles C++), Bun, optionally a pinned Rust toolchain plus components, runs `bun install`, then `bun scripts/build.ts --configure-only` and the ninja targets a job asks for: `clone-lolhtml` (cargo cannot resolve the workspace until the vendored `lol_html` path dependency exists) and, for jobs that check `bun_runtime`/`bun_jsc`/`bun_core`, `codegen` (their `include!()`d sources under `build/debug/codegen`).
120 
121| Job       | Check name            | Runs                                         | Blocking                       |
122| --------- | --------------------- | -------------------------------------------- | ------------------------------ |
123| `clippy`  | `cargo clippy`        | `bun run rust:clippy`                        | yes                            |
124| `miri`    | `cargo miri test`     | `bun run rust:miri` (`scripts/rust-miri.ts`) | yes                            |
125| `lolhtml` | `lol-html cargo test` | `cargo test` in `vendor/lolhtml`             | yes                            |
126| `mordant` | `mordant`             | `cargo dylint --all --workspace`             | advisory (`continue-on-error`) |
127 
128- `clippy`, `miri` and `lolhtml` pin `RUSTUP_TOOLCHAIN` at the workflow level (kept in sync with `channel` in `rust-toolchain.toml`) so rustup does not install that file's cross-target list; the action installs the toolchain with `--profile minimal` plus the components the job names (`clippy`, `miri rust-src`, none).
129- `lolhtml` exists because the vendored lol-html is a fork (oven-sh/lol-html, `bun` branch) whose own test suite is the only thing guarding the fork's invariants. It used to trigger only on `scripts/build/deps/lolhtml.ts`; it now shares the workflow's wider path filter.
130- `mordant` runs the [mordant](https://github.com/scarletindustries/mordant) dylint pack. It sets `RUSTUP_TOOLCHAIN: stable` instead: mordant is built with, and lints us using, the nightly named in its own rust-toolchain file, which dylint fetches on demand, so the outer cargo only needs to exist. Because that nightly is older than ours, the job passes `-A unknown_lints` through `DYLINT_RUSTFLAGS`. Two caches cover the slow parts: `~/.cargo/bin/{cargo-dylint,dylint-link}` keyed on `DYLINT_VERSION`, and `~/.dylint_drivers` + `target/dylint/libraries` keyed on `DYLINT_VERSION` plus the pinned mordant rev read out of `Cargo.toml`. It is skipped on `merge_group`.
131 
132### mordant: pin, baseline, disabled lints
133 
134- The pack is pinned by commit in `Cargo.toml` under `[workspace.metadata.dylint]`. A bump can also fail if this workspace stops compiling on mordant's nightly.
135- `dylint.toml`'s `[mordant]` table points `baseline` at `mordant-baseline.toml` (per-(lint, file) counts of the findings that predate the job) and lists the lints this repo has switched off under `disabled`, each with its reason.
136- In baseline mode mordant prints findings over the baseline as warnings and writes them to `target/mordant/over-baseline.txt` (relative to the workspace root). The job deletes that file, runs dylint, and fails if the file is non-empty; absent or empty means clean. Fixing baselined findings needs no baseline update.
137- Locally, `bun run rust:mordant` is the same dylint invocation and `bun run rust:mordant:baseline` regenerates the baseline (`MORDANT_BASELINE_WRITE=1`). Both need `cargo install cargo-dylint dylint-link` once, and expect `build/debug/codegen` and `vendor/lolhtml` to exist, which any normal `bun bd` leaves behind.
138 
139To bump mordant: change the `rev` in `Cargo.toml`, run `bun run rust:mordant`, fix what the new revision reports or regenerate `mordant-baseline.toml` with `bun run rust:mordant:baseline`, and put the triage in the PR description.
140