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

scripted-rewrite

An advisory by default: it explains, and blocks nothing, on a scripted substitute-and-write, which cannot tell your symbol from a dependency's.

What it catches

A scripted substitute-and-write, which cannot tell your symbol from a dependency's.

Why

A regex cannot tell YOUR symbol from a dependency's symbol of the same name. A \.Sum\b rewrite aimed at one proto field also hits the OTel SDK's metricdata.Sum and a histogram's dp.Sum, and the damage is written before any diff is read. The graph knows which is which and a pattern never can: magus refs <symbol> --occurrences returns verified sites, per file, with columns. Run magus graph build first if refs reports a project not-indexed, because that verdict means unknown rather than absent, and taking it for "no matches" is how a rename misses half its sites. Rewriting raw TEXT (prose, a config value, a string literal) has no graph equivalent; say so and use an editor tool. A script file is judged by its program: python3 p.py, and a write of p.py, get the verdict the same program would get inline. A program whose every named path lies outside the workspace is untouched. An APPEND passes, since it adds to the end and cannot mangle a line already there: a heredoc appended with cat >> f <<EOF or tee -a, whatever program its text documents, and a program whose every file write opens in append mode (open(p, 'a'), perl's '>>') or goes to its own stdout.

Default and override

By default this rule takes the decision advise. A workspace sets it by name, in its root magusfile, to deny, advise or off:

magus\guard.builtins({"scripted-rewrite": "deny"})

A loosening takes effect once it is committed; a tightening applies at once.

Seeing it

A verdict names its rule in brackets, which is how you got here:

advise [scripted-rewrite]: ...

magus describe rule scripted-rewrite prints the same entry at a terminal, and magus describe rules lists every rule this workspace enforces.

See also

ReferencePages in this section. chained-run: magus runs sequenced with `&&` or `;`, which a pipe of the same stages runs ordered and fail-fastAn advisory by default: it explains, and blocks nothing, on magus runs sequenced with `&&` or `;`, which a pipe of the same stages runs ordered and fail-fast. throwaway-copy: a run inside a temp or scratchpad copy, which leaves the real tree unverifiedAn advisory by default: it explains, and blocks nothing, on a run inside a temp or scratchpad copy, which leaves the real tree unverified. magus\guard.commandRegister one Buzz function the agent guard calls on every agent shell command, to add a deny or an advisory from your repository's own rules. magus ships the seam and no rules.
guardrulesscripted-rewriteadvise
Last updated (1a76274f)
Earlier changes on this page (3)

Full history ↗ · Blame source ↗

Glossary

Workspace

The magus root directory that owns a set of projects and shared config; the unit magus operates over. See workspace.

Project

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

Magusfile

The magusfile.buzz that declares a project's targets (as export funs) and binds its spells. 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.

Buzz

The language magusfiles are written in (the .buzz engine). See engines.

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.

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.

Advisor

One read-only check from the advice suite: it reads the changeset through magus and writes one titled section of findings. The same advisors run as a pull request comment in CI and inside magus diff --impact locally.

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.