Source map

Where things live in src/, how a luau-run test run passes through them, and the words the code uses. It is for maintainers and agents. Getting started covers using Luau Run.

A run, in order

1. cli.ts builds the Windows host record and the three lanes, then hands the arguments to cli/run-cli.ts.
2. commands/test.ts reads luau-run.toml (project-configuration/) and selects files (selection/): which files are tests, which runner and runtime each gets, which are refused.
3. test-run/execution/preparation.ts asks each lane to prepare the files it takes, then plans them (test-run/planning/, test-run/invocation/).
4. test-run/scheduling/execute-bounded-schedule.ts runs the invocations within the worker and class limits. Each lane starts its processes through the supervisor (supervisor/).
5. test-run/receipt-writer.ts writes the one receipt, and reporters/ turns it into the report.

Folders

Folder	What it holds
cli/, cli.ts	Argument dispatch, the composition root, receipt rendering
build-identity.ts, runtime-version.ts	Which Luau Run this is (version and stamped commit) and the Bun it needs
commands/	test, init, setup, pin (a Lute’s hashes into luau-run.toml) and the project’s own commands
project-configuration/	Loading and checking luau-run.toml
global-configuration/	The user’s own config.toml: [test] defaults, [paths], [spinner] and [output]
selection/	The [test] settings, discovery, selection, runner and runtime rules
test-run/	Running a selection: planning, scheduling, invocations, receipts
providers/	The lanes and the layers they share, in Lanes
supervisor/	The Windows supervisor protocol, its client and its output readers
manifest/	The one list of every piece Luau Run admits, per platform, and the rules that name its releases
store/	Where each installed file lives, computed from its pin, and the records under roots of which build needs what. Read only, so test may use it
archive/	Luau Run’s own zip reader and entry-name rules. Read only
acquisition/	The only code that writes the store, downloads or composes: sources, the downloader, the piece writer, records, the lock, the Bun and Windows ports. Only cli.ts reaches it, through one import() of effects.ts
setup/	luau-run setup on init’s pattern: decisions, items, words, screens, flow, and its real effects
prompt/	What init and setup share: the terminal, question layout, the ask-and-retry loop, the refusal block
contracts/	Types a lane implements and another layer takes, such as the runner probe
managed-tools/	Tool paths and admission (hash-checked executables), reading the manifest’s pins
tool-choice/	Which Lute, supervisor, Studio, Rojo and Jest-Portable version a run uses, chosen from every layer that names them (the variable, a per-project override, luau-run.toml or the project’s Rokit pin, config.toml, then Luau Run’s own), a Lute’s bytes read once a run, and doctor’s view of them
execution/	Processes, workspaces, bounded stream reads
host/	Host identity, file identity and state, paths, the platform and its path rules, the per-user home (LUAU_RUN_HOME)
serialization/	Canonical and strict JSON, plain data, sha256Hex
installed-studio/	Which Roblox Studio is installed: its version, the candidates every install records, and the choice. Read only, so doctor may use it
roblox-place/	Building a place with Rojo
rokit/	A project’s pinned tools, found as Rokit finds them in its, Aftman’s and Foreman’s manifests, without starting Rokit
preflight/	The Luau require scanner and graph
reporters/	Compact and live output
terminal/	The spinner, colours, column widths and the live status line
init/	luau-run init
request/	doctor, plan and run given --request, the old request commands, kept apart to be retired. Plain doctor is commands/settings-report.ts
compatibility/, conformance/	The Lute canary campaign and gate configuration, used by scripts only
testing/	Support shared by specs: a fake host, native test builds, live-test switches

Any folder may have its own testing/ folder for its specs’ support.

Lanes

A lane runs the files one runner and runtime take. Each wires itself in its lane.ts, which is the only file of a lane that code outside providers/ may import.

Lane	Runs
providers/entry-runner/	Script files and the project’s own runners, one Lute process each
providers/jest-portable/lute/	Jest specs on Lute, on the runner setup composed in the store
providers/jest-portable/roblox-studio/	Jest specs in Roblox Studio, with the framework read in memory from the archive inside luau-run.exe (framework-source.ts)

The layers lanes share are providers/lute/ (the Lute wrapper provider), providers/roblox-studio/ (the Studio session) and the files directly in providers/jest-portable/ (the Jest result format and surface). scripts/check-architecture.ts enforces these boundaries:

• generic code reaches no provider
• no lane reaches another
• the supervisor rests only on execution/, serialization/, host/ and two test-run/ contracts
• only the CLI reaches request/

From a code to where it is thrown

A code in a receipt or a report is a string literal where it is thrown. Search for it in quotes, for example "studio.capture-dynamic-require". Its prefix names the owner:

Prefix	Owner
test., command., init.	Selection and discovery, luau-run.toml, init
runtime.	Runtime headers and choice, in selection/
update., install., self-install., uninstall.	Luau Run’s own install and updates, in commands/ and acquisition/
global-configuration., luau-run-home.	The user’s config.toml in global-configuration/, LUAU_RUN_HOME in host/
jest-toolchain.	Managed tool admission in managed-tools/, for every lane despite the name
pin.	luau-run pin lute in commands/pin.ts. Its downloads’ refusals keep their download. codes
tool-choice.	The resolver in tool-choice/: a layer that names a tool that is not there, a Lute it cannot run, a Jest-Portable version this Luau Run does not carry
jest-topology., jest-precompiled., jest-distribution., jest-provider., jest-suite.	The Jest on Lute lane
entry-provider., entry-runtime.	The script-file lane
studio., place.	The Studio lane and the place build. studio.rojo- refusals come from Rojo’s choice in tool-choice/rojo.ts
supervisor., source-workspace., result-artifact.	The supervisor client and its helpers
spec-clock.	A spec’s own time limit
setup.	luau-run setup in setup/, and a file it needs but cannot get in acquisition/sources/
download., integrity., store.	The downloader, archive and file checks, and the store’s writes in acquisition/ and archive/
launch.	A launch Windows blocked, named from the supervisor’s Windows error in supervisor/launch-block.ts
test-provider-settlement., test-run-member-receipt.	Checks on what a lane reports back
suite.	Jest-Portable’s runner, in the fork, not in this repository

Words

• Lane: the providers that run files of one runner and runtime.
• Selection: the files chosen for a run, each with its runner, runtime and any refusal.
• Job: one selected file in the plan, ready or refused.
• Invocation: one provider run over one or more files, its members.
• Attempt: one try of an invocation, with its own nonce. Its identity ties results to it.
• Admission: the scheduler starting an invocation. A file not admitted keeps a receipt saying why. Also a tool’s executable passing its pinned hash check, in managed-tools/.
• Settlement: what a provider reports when an invocation ends: lifecycle, output, evidence.
• Ownership: whether everything an invocation started is known to have ended (released) or not (unresolved). Unresolved ownership holds its capacity, so the run cannot overrun its limits.
• Quarantine: a class of work stopped after one of its invocations ended in doubt. Its other files are not admitted.
• Projection: the short public result, an exit code and a reason code. Also a Terminal turned into receipt evidence.
• Conservation: the scheduler’s accounting, checked at the end: every admission settled, every file one receipt.
• Terminal: the supervisor’s final message for a process, which the receipt keeps the end of.