MGS3031: a declaration claim nothing can grade

magus job fork, the client tool (magus\job.put) and a magusfile's magus\job.put refused a job because one of its write paths or deny paths names a declaration (<file>#<declaration>) that no footprint could ever check. For a write path:

[MGS3031] job: wave/notes claims a declaration no footprint can grade:
  "notes.txt" has no diff driver, so no changed line of it can be placed in a
  declaration; give `*.txt` one in .gitattributes (`magus doctor` lists the
  managed ones). Claim the whole file instead, or fix what is named

For a deny path, the refusal names the field:

[MGS3031] job: wave/notes claims a declaration no footprint can grade:
  deny path "notes.txt" has no diff driver, so no changed line of it can be
  placed in a declaration; give `*.txt` one in .gitattributes (`magus doctor`
  lists the managed ones). Claim the whole file instead, or fix what is named

Nothing was written to the job store. A put that adds such a path to a job that already exists is refused the same way and leaves the job as it was.

Why

A claim like run.go#executeStages lets two jobs start on one file. It holds only because magus can say, from the job's diff, which declaration every changed line lands in. That placement is git's: the file's diff driver (the diff= attribute) names the declaration each line sits under. A claim on a file with no driver, on a pattern, or in a checkout whose version control places no lines would read as a boundary and check nothing, so it is refused rather than recorded.

A deny path such as run.go#executeStages is placed the same way: the guard and magus job wait refuse only a change inside that declaration. One magus cannot place would deny the whole file while the job says one declaration, so the same rules refuse it.

What is refused

Each of these, in a write path or a deny path:

• An empty declaration, such as run.go#.

• A pattern, such as internal/*.go#Run. A declaration lives in one file.

• A file with no diff driver. magus manages drivers for Go, Python, Rust, Markdown, TypeScript, Buzz and YAML in its .gitattributes block. Any other extension needs a *.<ext> diff=<driver> line of your own.

• A checkout with no version control, or one that does not place changed lines. Only git does today.

• A word that names more than one declaration of its file. A claim names a declaration when it equals the declaration line or any identifier-bounded run of it, so ctx or String names every line that holds the word, and the guard and magus job wait would hold all of them. The refusal counts the matches and prints words that name one each:

  [MGS3031] job: wave/api claims a declaration no footprint can grade:
    "run.go#ctx" names 2 declarations of run.go (such as `func A(ctx int) {`), and
    a claim guards exactly one; use a word only one of them has, such as `A`, `B`.
    Claim the whole file instead, or fix what is named
  

  A word that names none is accepted: the declaration may not be written yet, and the guard and wait place the new function under its own name. Check the spelling, since a typo reads the same.

  The same rule holds for a key claim in a magusfile or magus.yaml (MGS3036): magusfile.buzz#project.targets names every placed entry of targets, so it is refused in favor of magusfile.buzz#project.targets.test.

• A path that contains #, spelled bare. When notes/a#b.md exists, it reads both as the path and as a claim on notes/a. Spell the path ./notes/a#b.md or notes/a\#b.md; the escaped form also takes a claim, notes/a\#b.md#Intro.

What to do

Claim the whole file, which is what the job was going to be graded against anyway:

magus job fork wave/notes --write-paths notes.txt

For a deny path, deny the whole file, or leave it out:

magus job fork wave/notes --write-paths src/run.go --deny-paths notes.txt

Or give the extension a driver, then fork again with the declaration.

See also

• Leases: write paths, claims, and what the guard enforces.
• MGS3018: a directory as a job write path.