Give the build six names instead of one

[tamnd]

The M1 line that says "the six step build: resolve, verify citations, execute, generate, assemble, check". They now exist, they are what runs, and the tool prints them.

What was wrong with one step

The build was one operation. It went red, and what you knew was that it had gone red. Working out which of several unrelated things had happened meant reading the log from the top.

The two failures worth telling apart are these. A lesson whose code is wrong. A lesson whose code is right and whose committed page is out of date. The first one is a bug you go and fix. The second one is a build you forgot to run and commit. They took the same amount of squinting to identify and they should not.

The six

  resolve   .NET 10.0.11 on osx-arm64, SDK 10.0.400, pin.json holds no version yet so no citation resolves
  cite      none yet, because pin.json holds a null commit and a citation without one is not accepted
  execute   2 lesson(s) and 1 blueprint(s), 18 block(s) run, 8 assertion(s) held
  generate  13 diagram(s), 9 captured output(s), 2 generated section(s)
  assemble  3 page(s)
  check     42 file(s), and what is committed is what the code produces
xray check: 0 problem(s)

Every number there is worth reading. Zero assertions held would mean the assertion checker is running and checking nothing. Zero citations is the honest count today and will be a lie the day after the pin lands.

Written up in docs/the-build.md, with a picture.

A step that finds a problem is the last step that runs

Not tidiness. Every step reads what the one before it produced, so output from a step standing on a failed one is not a second opinion, it is noise with a line number in it. A lesson whose code did not run has no captured output, and the page assembled around the hole where that output belongs reports a second failure that is the first one wearing a hat.

Inside a step it goes the other way. All the lessons execute even after the first one fails, because those really are independent, and hearing about three broken lessons in one run is worth a longer log.

resolve is new

It reads pin.json and global.json, asks the SDK which version of itself is about to compile everything, and reports the platform. Then it refuses a build that cannot say what it is standing on:

• No pin.json at the top of the repository.
• A second pin.json somewhere below it. Two pins is the state where half the pages resolve against one commit and half against another.
• No global.json, or one with no SDK version, which means two people cloning this can be compiling it with two different compilers.
• Half a pin: a tag with no commit, or a commit with no tag.
• A pin and a global.json naming different SDK versions, once the pin has landed.

That last one is worth being plain about. Those two files disagree right now, on purpose: the citations will be written against .NET 11 and the tooling builds on 10. That was true before this pull request and nothing anywhere said it. Now the first line of every build says it, and the day pin.json gets a version the disagreement stops being allowed.

Nothing is written until step six

Every generator used to write its own files as it went. They now hand their work to a plan, and the plan is settled once, at the end. So build and check are one code path with one flag rather than the same decision made independently in four places.

Two things fall out of that for free.

A file two generators both want to produce is an error. Before, whichever ran second won, the build was green, and half the work quietly did not appear on the page.

A generated file the build no longer produces gets found. Rename a block and its old captured output stays on disk forever, unread and uncompared, and the next person to open the directory finds two files where one of them is the truth. check names it, build deletes it. Only directories this build put something into are swept, so a lesson nobody has built yet is not accused of having leftovers.

The self test grows

check --selftest is at nine cases, two of which change nothing and have to pass.

ok    passes an untouched lesson
ok    refuses a number changed by hand in a captured output
ok    refuses a captured output deleted
ok    refuses a sentence added by hand to a generated page
ok    refuses a captured output left behind by a block that no longer exists
ok    refuses a build that cannot say what it is pinned to
ok    passes an untouched blueprint
ok    refuses a number changed by hand in a generated blueprint section
ok    refuses a sentence added by hand to a generated blueprint page

The pin case is the one that is not about a generated file. It deletes pin.json and requires two things: that the build says what is missing, and that it stops at step one rather than going on to produce five steps worth of output about a repository it cannot describe. An expectation is now a list rather than a single string, so a case can insist on both.

CI

Three steps in the lessons job become one. It runs the whole repository rather than three named directories, so nothing gets left out by a path somebody forgot to add. --offline skips the cite step, which keeps the separate job it already had: a citation resolves or it does not, and the answer does not depend on which of the four machines asked.

Checked locally

xray lint       19 files, 0 problems
xray check --offline   44 files, 0 problems
xray cite       0 citations, 0 problems
xray numbers lessons   2 lessons, 0 problems
xray numbers --selftest  0 failures
xray cite --selftest     0 failures
xray assert --selftest   0 failures
xray check --selftest    0 failures, 9 cases
dotnet format --verify-no-changes  clean

Also checked by hand: build twice in a row leaves the tree clean, a planted file under expected/ is reported by check and removed by build, and check ../lessons from inside docs/ still passes, which is the working directory bug #34 fixed and this refactor could have brought back.