What a worm is

A worm is a larvae extension. You name it in larvae.toml, larvae worm install puts it on disk from a GitHub release or crates.io, and it loads before any work starts. A path worm is read from its directory instead. Installing is its own step: a command that finds a named worm missing reports it once and moves on, rather than downloading mid run.

If you only read one sentence: a worm is a worm.toml beside one artifact, the artifact is Luau source, a wasm32 module, or a native executable, and every form answers the same four capabilities.

Three forms

The manifest states the form, and the form is a trade the project makes.

The first two forms are sandboxed, and that is a property of the runtime rather than a promise in a document. A native worm is an ordinary program running as you, so it is never the default: a project chooses it for code it trusts, because that is the only honest way to offer native speed.

A worm author never depends on larvae itself. larvae is the host. The guest side for Rust authors is the larvae-worm crate: frontend! and rules! for the wasm ABI, and a native module with a Handler trait and serve() for the pipe protocol. The wire types are the same on every transport, so a worm returns the same values whichever form ships.

Four capabilities

Every form answers every capability. The manifest declares what the worm does, and larvae refuses a promise the artifact cannot answer.

The division of labor does not move with the form. A worm never decides a severity, never renders, and never writes a file. The host stamps lint levels, applies allow comments, and owns exit codes, so [lint.rules.<worm>] and a -- larvae: allow(...) comment work on a worm's findings exactly as they work on builtin ones. Format and lint cross once per file on every transport.

Beside the four sit two optional editor answers, code actions and Luau type definitions. The manifest does not promise them, so a form with nothing to say answers with nothing rather than an error. The user's side is on using worms; the exports are on the writing pages.

Ranges do not need exact ends

A format reply that names byte ranges does not have to place the range ends exactly. A worm draws the ranges from its own parse, and a worm that ends a range at the last token of a statement leaves the ; that terminates the statement outside it.

larvae takes a ; that sits just after a range into that range, and leaves a ; that opens a range outside it. Both edges matter for the same reason: larvae formats each range as a chunk of its own and cannot see the text around it, so a ; at an edge reads as a stray statement. The first edge would give a file where semicolons worked on some statements and not others. The second would give the ambiguous call syntax that Luau rejects. Neither edge needs the worm to change, because a contract that needs exact ends from every worm gives output in two styles as soon as one end is wrong.

What a worm inherits

The short forms give a worm most of larvae for the cost of naming where the Luau is.

• Formatting. A format reply that names the Luau ranges and nothing else gets each range formatted in the project style, and every other byte kept as the author wrote it. See formatting.
• Linting. inherit_lints = true runs the 51 builtin lints on claimed files, against the Luau shadow the worm returns, or against its transform output when there is no shadow. The project narrows this with [worms.<name>.inherit]. See linting.
• Settings. At init a worm receives the resolved [fmt] table and the lint levels, so it lays its own constructs out in the project style and the user states each setting one time.

What worms cost you

Per file, the cost is measured rather than estimated, and it is small enough that the boundary matters more than the parse. See what a worm costs.

Related

• using worms, the [worms] table, install channels, and inheritance
• writing a worm in Luau, no toolchain, a file in your own repo
• writing a worm in Rust, the wasm macros and the native pipe
• worm.toml, the manifest beside the artifact