magus v0.4.3 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
1 min read

MGS3021: preflight outside the closure

--preflight reorders work the invoked target already does: it runs part of that target's ctx.needs closure first, everywhere, so a cheap failure stops the run before the expensive part starts. A name outside that closure would add work instead, so magus refuses the invocation before anything runs, and exits 2, the misuse status.

[MGS3021] --preflight unrelated is not in what ci runs in any selected project, so running it first would add work rather than reorder it (see `magus describe target ci`)
  app:ci chain: lint -> build -> test
  see: https://eli.gladman.cc/magus/reference/codes/sandbox/MGS3021/

Each listed line is a selected project, the invoked target, and its chain: the same first hop magus describe target <target> prints. The closure is that chain followed transitively, so a target lint needs counts for ci when ci needs lint.

Naming the invoked target itself is refused the same way: it is not a step before itself.

A project whose invoked target does not reach the name runs no preflight for it; the refusal fires only when no selected project reaches it. A preflight names a target alone, with no charm: it runs under the invocation's charms, so it is keyed the way the main run would key it.

Resolution

  • Name a target the invoked target composes. magus describe target <target> shows its chain.
  • If the check should gate the invoked target, add it to that target's ctx.needs, then name it in --preflight.

See also

  • MGS3020: a preflight target that ran and failed.
  • Targets: using --preflight before a CI fan-out.
MGS3021preflightctx.needschainclosuredescribe targetexit 2
Last updated (f41fc67b)
Glossary

Project

A directory magus recognizes as a unit of work (it has a magusfile); the unit of caching, scheduling, and dependency tracking. See workspace.

Target

A named operation (build, test, ...) you invoke with magus run <target>; it may compose a spell's tool-native operations and depend on other targets. See targets.

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). See operations.

Charm

An execution modifier attached with : (lint:rw) that changes how a target runs, not which one; the built-in rw flips a check-only target to mutate in place, and ci always strips it. See charms.

Sandbox

The restricted filesystem and environment a target runs in, so builds stay reproducible and side-effect-free. See sandbox.

CI

An ordinary magusfile-defined target you compose yourself with magus\needs - magus does not hardcode its stages. Magus.RunCI treats it specially only in that it strips the rw charm, it is the anchor magus affected ci keys off, and a selected scope with no project declaring it is a load error rather than a silent no-op. See targets.

Invocation

One magus process's recorded facts - the targets it finished, their outcomes, the lease it acted as, and the session it ran in when a host delivered one - kept in a repo-scoped store every worktree shares. magus session lists them; the store prunes itself by last-fact age.

Run

One target executing under one magus invocation, such as magus run test web or magus affected ci. A run keeps its captured output behind an output reference. Every magus run is a run whether or not any job asked for it; see Job for how the two relate.

Conventions

Placeholders

Angle brackets mark a value you replace with your own - never type the brackets:

magus run <target>
magus completion <shell>    # e.g. bash, zsh, fish

<target>, <path>, <shell>, <name> and the like are stand-ins, not literal text.