Handoff — 2026-09-01 — turbo-core extracted from turbo-go

State

The library exists, is complete, and is green. Sixteen packages, whole suite passing and passing under -race, quality gate PASS at 0/0/0 with complexity 1584. Documentation is 12 pages × EN + FR, plus a README.md per package and a diagram generated from go list.

Two editors are built on it and both work: turbo-go (migrated onto the library, full existing suite green) and turbo-rust (new, with a hand-written Rust scanner verified against a real rust-analyzer). Both are in repositories beside this one.

Everything is uncommitted, on main.

In flight

Nothing.

Next steps

Review and commit, in this order: turbo-core first, then turbo-go, then turbo-rust. The two editors do not build without the library beside them.
Tag v0.1.0 and push. Until then the editors carry a replace directive pointing at ../turbo-core, which is committed on purpose — see docs/en/how-to/release-the-library.md.
Drop the replace directives in both editors once the tag exists, one editor at a time, running each suite before moving on.
Ticket 0001 in turbo-editors/.tickets is the user's to close.

Open questions / blockers

None. Every decision the work needed was put to the user and answered before implementation started.

Watch out for

The tests here drive a fictional editor, Turbo Test, and that is deliberate. A test that expects the Go menu, .turbo-go, or gopls is testing an editor's choices from inside the library those choices are made outside of. If you find yourself wanting Turbo Go's answer in a test here, the test belongs in turbo-go.
syntax.Register is package-level state, and the examples in syntax's own test binary use it. TestRegisteredListsWhatThisPackageColours was originally written to assert an exact count and passed or failed depending on whether the examples had run yet. It asserts presence and sortedness now. Do not "tighten" it back to a count.
Emit drops empty spans, so a scanner must pass a span's start in as a parameter rather than patch it onto the last span afterwards — the last one may not be the one it thinks. This has bitten twice in this codebase, in two different scanners.
A theme test that passes the moment you write it has not been tested. Every rule in editor/view_test.go was falsified before being trusted, and the two Catppuccin themes were falsified again when they were added.
The environment variable names are load-bearing. TURBO_GO_THEME_DIR and friends are derived from the profile's slug precisely so the released names are preserved. Changing how envPrefix works breaks somebody's configuration silently.
profile.Templates' formatting contract is not enforced. Settings takes two %q, Snippets two %s, Tools none. Getting it wrong shows up as %!s(MISSING) in a user's project. Each editor tests its own templates; the library cannot.
make race before committing anything touching a goroutine. There are three — the LSP read loop, the pty reader, and a running tool's output — and every one has had a race in it at some point.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


# Handoff — 2026-09-01 — turbo-core extracted from turbo-go

## State

The library exists, is complete, and is green. Sixteen packages, whole suite passing and passing under `-race`, quality gate PASS at 0/0/0 with complexity 1584. Documentation is 12 pages × EN + FR, plus a `README.md` per package and a diagram generated from `go list`.

Two editors are built on it and both work: **turbo-go** (migrated onto the library, full existing suite green) and **turbo-rust** (new, with a hand-written Rust scanner verified against a real rust-analyzer). Both are in repositories beside this one.

Everything is **uncommitted**, on `main`.

## In flight

Nothing.

## Next steps

1. **Review and commit**, in this order: turbo-core first, then turbo-go, then turbo-rust. The two editors do not build without the library beside them.
2. **Tag `v0.1.0`** and push. Until then the editors carry a `replace` directive pointing at `../turbo-core`, which is committed on purpose — see `docs/en/how-to/release-the-library.md`.
3. **Drop the `replace` directives** in both editors once the tag exists, one editor at a time, running each suite before moving on.
4. Ticket 0001 in `turbo-editors/.tickets` is the user's to close.

## Open questions / blockers

None. Every decision the work needed was put to the user and answered before implementation started.

## Watch out for

- **The tests here drive a fictional editor, Turbo Test, and that is deliberate.** A test that expects the Go menu, `.turbo-go`, or gopls is testing an editor's choices from inside the library those choices are made outside of. If you find yourself wanting Turbo Go's answer in a test here, the test belongs in turbo-go.
- **`syntax.Register` is package-level state, and the examples in `syntax`'s own test binary use it.** `TestRegisteredListsWhatThisPackageColours` was originally written to assert an exact count and passed or failed depending on whether the examples had run yet. It asserts presence and sortedness now. Do not "tighten" it back to a count.
- **`Emit` drops empty spans, so a scanner must pass a span's start in as a parameter** rather than patch it onto the last span afterwards — the last one may not be the one it thinks. This has bitten twice in this codebase, in two different scanners.
- **A theme test that passes the moment you write it has not been tested.** Every rule in `editor/view_test.go` was falsified before being trusted, and the two Catppuccin themes were falsified again when they were added.
- **The environment variable names are load-bearing.** `TURBO_GO_THEME_DIR` and friends are derived from the profile's slug precisely so the released names are preserved. Changing how `envPrefix` works breaks somebody's configuration silently.
- **`profile.Templates`' formatting contract is not enforced.** `Settings` takes two `%q`, `Snippets` two `%s`, `Tools` none. Getting it wrong shows up as `%!s(MISSING)` in a user's project. Each editor tests its own templates; the library cannot.
- **`make race` before committing anything touching a goroutine.** There are three — the LSP read loop, the pty reader, and a running tool's output — and every one has had a race in it at some point.