Expose the build model as JSON via --describe and --plan --json (#642)

[phmatray]

Implements #642.

Closes #642.

Executing the implementation plan task-by-task; the checklist below — and the plan on the issue — are ticked as each task lands. Opened as a draft — will be marked ready after the final task and a code-review pass.

Two constraints shaped the design, both verified in the tree:

• BuildGraphUtility already projects targets and all four relation kinds into a schema-versioned document, so this extends that model additively rather than inventing a second one. SchemaVersion stays 1, which also delivers Emit declared build parameters into build-graph.json #499's parameters[].
• BuildManager.Execute runs ToolRequirementService.EnsureToolRequirements (writes nuget.csproj, shells out to dotnet restore) before the IOnBuildInitialized hooks. So the "runs no external tool" criterion rules out another extension; the emission short-circuits above that line.

The commands land as the build-side parameters --describe and --plan --json, because CommandDispatcher routes bare arguments to the build and reserves :-prefixed tokens for CLI commands.

Plan

• Task 1: Project tool requirements onto the target model
• Task 2: Project declared parameters onto the model (also closes Emit declared build parameters into build-graph.json #499)
• Task 3: --describe emits the model before tool requirements run
• Task 4: --plan --json emits the resolved execution plan
• Task 5: Machine-readable error envelope on failure
• Task 6: Render --help from the shared model

--help is byte-identical to main

Verified by building main in a scratch worktree and diffing the output: the only difference is the version string. --help takes its displayed fields from the shared model (so the two views cannot drift) but keeps ordering — of targets, of each dependency line, and of parameters — from the declarations, because declaration order carries the pipeline reading a human wants.

Code review

A review of the branch surfaced 15 findings; all are addressed. The ones worth calling out:

• The plan contradicted the executor. BuildExecutor.MarkTargetSkipped only skips when !target.Invoked, so --skip never stops an explicitly invoked target. The projection had no such guard and reported "skip": "via parameter" for it — a consumer driving CI off the plan would conclude nothing runs. Fixed, with a spec that pins the parity.
• The gate was in the wrong place. It sat after the IOnBuildCreated extensions, so each misbehaving extension needed its own opt-out — and UpdateNotificationAttribute calls Console.ReadKey(), which would have deadlocked a piped --describe. The gate now fires before any extension runs, and the per-extension opt-out is gone. IsRequested reads each flag from the injected property or the raw arguments, because InjectParameterValuesAttribute is itself an IOnBuildCreated extension.
• Build-level [Requires<T>] was invisible. That attribute targets Class/Interface only, so class-level requirements could never appear on a target and were missing entirely. They now project to a root-level toolRequirements[].
• Type.FullName leaked the runtime version into the contract for constructed generics (List\1[[System.String, …, Version=10.0.0.0, …]]`). Generic arguments are now rendered recursively.
• Dropped a list field that could never be false, gave the plan and error documents their own schema-version constants, and de-duplicated the serializer options, version lookup, and skip-reason string that had been copy-pasted.

Making standard output actually parseable

Running the feature revealed that the document was correct but unreachable through any shipped entry point — everything upstream of the build wrote to stdout too, so --describe could not be piped into a parser. Three fixes:

• Fallout.Cli compiled the build project with its output inherited on stdout. For an introspection request that step now goes to standard error. Measured through the locally built CLI: 12 123 bytes of JSON on stdout, 8 582 bytes of build noise on stderr. Ordinary runs are unchanged — build output stays on stdout.
• build.ps1 / build.sh (and the shipped templates, kept in sync) printed their banner and dotnet tool restore output to stdout. That is provisioning diagnostics, so it moves to standard error.
• --help no longer aborts when stdout has no console. Console.BufferWidth throws IOException behind a pipe or on a console-less agent, which killed --help after the target list and before the parameters. The wrap width is cosmetic, so it now falls back to the existing 90-column cap. This closes --help crashes with IOException when stdout has no console handle #616.

Also: the emitted documents are newline-terminated, matching SchemaUtility's JSON.

⚠️ ./build.ps1 --describe stays unparseable until a Fallout release carrying the CLI fix is installed, because the script delegates to whatever dotnet fallout is on the machine. Nothing in this PR can change an already-installed tool.

Follow-ups

• A versionless [Requires] resolves its version over the network inside NuGetPackageRequirement's constructor, before any short-circuit. Pre-existing, affects --help too; "runs no external tool" is scoped to this code path.
• The IOnBuildPlanned extension hook this deliberately avoided is worth revisiting once FT-7 ([Foundation] FT-7: Formalize the build extension pipeline (deterministic ordering + typed phases) #312) formalizes the extension pipeline; Declare target effects and gate them at plan time #644 would use it too.

🤖 Generated with Claude Code

[ChrisonSimtian]

a lot of this code is static methods and static classes. I think this one needs a bit more hands on from a human, the code quality unfortunately trips AI to think all-static is a good and preferred pattern.
might be worth to nudge your agent into the right direction and have it have another go 😊

[phmatray]

Fair call, and it turned out to be hiding a real bug rather than just style. Pushed in e6c358d.

BuildIntrospectionService is a sealed class now, holding the resolved request. BuildManager builds one with For(build) and reuses it at the gate, on the failure path, and before the outcome tables. Those three sites each re-read the flags out of ParameterService, so a single run answered "is this an introspection request?" three separate times from process-global state that nothing kept in agreement. The invoked targets are read once now too, rather than once for the planner and again inside GetDocument.

The part worth flagging: dropping the static shape removed a test-only overload, and that overload was papering over a coverage gap. Production described a build through GetJsonString(build, targets), which projects the class-level [Requires<T>] requirements. The specs called GetDescribeJson(build, targets, version), which routed to a GetModel overload passing no requirements — so the specs were asserting a document the product never emits, and that projection had no coverage at all. BuildGraphUtility now takes the version on the same path production uses, and there is a new spec pinning a build-level requirement reaching the document.

One thing I deliberately left static: IsRequested(IReadOnlyCollection<string>). The CLI calls it before a build process exists, and it is a pure function of its arguments, so an instance would only add ceremony. Happy to move it if you would rather it lived somewhere else.

I did not touch BuildGraphUtility's other members or BuildManager/BuildExecutor themselves — they are pre-existing static utilities and pure projections, and converting them looked like a bigger change than this PR should carry. Say the word if you want that too.

Full suite green: 849 passing.

[phmatray]

Conflict with develop resolved

Merged upstream/develop into the branch (cb0bdc22). Four files conflicted, all under src/Fallout.Build/Execution/.

Cause. develop ran a formatting pass over that folder: braces around single-statement blocks, blank lines between statements, re-indented array initializers, and one using moved. On develop's side every conflicting change was style only. This branch had rewritten the same regions for real.

Resolution. Kept this branch's logic in all four files and applied develop's style around it.

File	What was kept
BuildManager.cs	Finish() keeps the introspection is { IsRequestedForRun: true } guard, now braced.
Extensions/HandleHelpRequestsAttribute.cs	The projected model, the GetBufferWidth() fallback and the (Member, Model) tuple. Braces and blank lines follow develop.
Extensions/SerializeBuildGraphAttribute.cs	Both usings, plus develop's unqualified Log.Verbose.
ValueInjectionUtility.cs	The Describe and Json entries, inside develop's re-indented array.

One change sits just outside a conflict hunk: the if (!projected.Listed) guard in GetTargetsText is now braced. Leaving it alone would have made that guard the only unformatted statement in a file develop had just formatted end to end.

Verified after merging:

• dotnet build fallout.slnx — 0 errors.
• dotnet test fallout.slnx — 0 failures across all 13 test projects, including BuildGraphUtilitySpecs, BuildIntrospectionServiceSpecs and HandleHelpRequestsSpecs. No Verify snapshot drift, so no .received. file was produced.
• ./build.sh --help renders --describe and --json through the merged HandleHelpRequestsAttribute, which was the largest conflict.
• ./build.sh --describe emits a well-formed document (19 targets, 22 parameters) and ./build.sh --plan --json emits version / invokedTargets / plan. Both exercise the BuildManager short-circuit and the Finish() guard that were resolved by hand.
• .fallout/build.schema.json does not drift: booting the build project leaves git status clean.

The PR is mergeable again.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EnT6hhAWLHoiVdx8NMAu7u

[ChrisonSimtian]

@phmatray Sorry for the long wait. You answered my review on 3 Sep and merged develop on 9 Sep, and we did not reply. That was our fault, and I am sorry. Thank you for your patience and for the careful work here.

My static-code concern is mostly resolved. BuildIntrospectionService is an instance class now, and the gap you found in the specs was a good catch.

What I checked

I built this branch and ran --describe and --plan --json against this repo's own build.

• Standard output is only JSON. Standard error is empty. The working tree is unchanged afterwards.
• A skipped dependency reports "via parameter". An invoked target is never reported as skipped. This matches the executor.
• An unknown target gives a JSON error and exit code 255.
• [Secret] parameters are flagged and carry no value.
• --help differs from develop only by the two new parameters.
• Build.Specs (277) and Cli.Specs (47) pass. The branch merges cleanly into current develop.

Changes needed

1. The acceptance criteria of #642 are not fully met.

• default and allowedValues are null for all 22 parameters. #642 asks for the default value. Please fill them in, or remove the fields until they carry data. A consumer cannot tell "no default" from "not reported". allowedValues matters most for configuration, verbosity and host.
• type shows internal .NET types. --target and --skip report IReadOnlyCollection<ExecutableTarget>, which users never type. Renaming an internal type would then break the JSON contract. Please map to a small stable set (for example string, bool, int, path, string[], enum).
• #642 asks for a machine-readable error when the build project fails to load. A compile error in the build project gives no JSON, only text on stderr. I read this in the code and did not run it. Please cover it, or say in the description that it is out of scope.

2. The script changes affect every run, not only introspection.

• build.ps1, build.sh and the templates now write the banner and tool restore output to stderr for all users. Some CI systems treat stderr output as a failure signal.
• In build.ps1, 2>&1 with $ErrorActionPreference = "Stop" may fail on Windows PowerShell 5.1 when dotnet tool restore writes to stderr. CI only ran on ubuntu, and I could not test Windows.
• Please redirect only when the arguments request introspection. Or show a passing run on Windows PowerShell 5.1.

3. The riskiest code has no tests.

• Nothing tests the gate in BuildManager: no extension runs, the Finish() guard, the error path and the exit codes. Nothing tests the stdout redirect in RunCommand either. I checked the gate by hand, but nothing would catch a regression.
• None of the new or changed specs use // Arrange, // Act, // Assert (CONTRIBUTING.md, "Pull requests").

4. Public API and PR housekeeping.

• The PR adds public FalloutBuild.Describe and FalloutBuild.Json, and Plan { internal set; }. A consumer's own Json or Describe member on their build class could collide. I have not tested that. Please follow "Proposing new public API" in CONTRIBUTING.md, and say whether [Experimental] fits.
• The PR needs labels (target/vCurrent and a changelog category) and a milestone. I will add these.
• Please add docs for the two flags and the JSON documents, including the schema version rules.
• Please curate the 11 commits. Fold "Scaffold draft PR", "Address code-review findings" and the merge commit into the commits they belong to. Consider moving the --help crash fix for #616 into its own commit.

Smaller points (not blocking)

• BuildGraphUtility has four GetModel and four GetJsonString overloads, and the specs use the shorter ones. Please collapse them.
• The skip logic is copied from BuildExecutor, and only the reason string is shared. Please share the predicate so the two cannot drift. IsRequested also reimplements the flag parsing.
• The error kind is the .NET type name, which is just "Exception" for an unknown target. A stable error code would help machines. #643 covers exit codes.
• Please shorten the comments and use plain, literal English, as in AGENTS.md rule 8 and the plain-english skill.

If anything is unclear, ask here and I will answer the same day. Once these are done I will review again promptly.

[dennisdoomen]

🤔 I'm struggling with this PR. It clearly was built by an AI and because of that, resulted in something that is hacked into the existing codebase and therefor very hard to follow.
🔧 Lots of new code has the wrong namespace.
🔧 The new tests don't follow the AAA principle and are optimized to be as small as possible instead of demonstrating the arrange, act and assert parts

[dennisdoomen]

What about consumers that didn't update their build.ps1?

[dennisdoomen]

Unused namespaces

[dennisdoomen]

🔧 Unused

[dennisdoomen]

🔧 Doesn't need to be internal. Same with the others.

[dennisdoomen]

🔧🤖 Execute grows by ~20 more lines; extract the introspection gate into its own method.

[dennisdoomen]

🤔 This class seems to be misused and suddenly has a ton of internal members which I do not understand why they are needed.

[dennisdoomen]

🔧Make the public API of this class public and avoid internal. Don't touch internals through tests only. Always use the public API.

[dennisdoomen]

🔧 Needs a rewrite as it is unreadable for a human being

[dennisdoomen]

🔧Wrong namespace

[dennisdoomen]

⛏ IsRequested is a bit of a weird way to ask the service