command reference generator from package source — no editor, no dump

[ArkTarusov]

Context. skills/unity-pipeline/references/editor-commands.md is currently produced in two manual steps: a unity --json command dump taken from a live editor (categorized part, tools/gen-commands-md.js) plus a hand-extracted RuntimeOnly section from the package source. Regular updates would require a running Unity Editor with the package installed.

Source of truth. The complete com.unity.pipeline package, with C# sources of every command, is publicly available on the UPM registry with no auth:

• version list: https://packages.unity.com/com.unity.pipeline (JSON; versions, each with dist.tarball);
• the tarball contains Editor/Commands/*.cs and Runtime/Commands/*.cs with all [CliCommand]/[CliArg] attributes.

On 0.4.0-exp.1 the sources declare 154 [CliCommand] methods — a strict superset of the live listing (140), including every RuntimeOnly command hidden from the listing, and capture_editor_element, which appears nowhere else. Descriptions and argument metadata match the live listing.

What to build. A C# console project (net8+, Roslyn Microsoft.CodeAnalysis.CSharp; no other external dependencies), which:

1. Takes the package version as an argument, or latest for the highest entry in the registry versions.
2. Downloads the tarball via dist.tarball and unpacks it to a temp directory (HttpClient, GZipStream + System.Formats.Tar).
3. Parses [CliCommand] / [CliArg] attributes and parameter signatures (C# type, default value) from the syntax tree, not with regexes: attributes span multiple lines, and a [CliArg] default falls back to the C# parameter default when the attribute sets no DefaultValue. Excludes Tests/ — it holds registration fixtures (log_editor, test_types, test_structured), not real commands.
4. Generates editor-commands.md in full: preamble with the package version, categorized sections (categories from source directories Editor/Commands/<Category>/), and a section for RuntimeOnly commands hidden from the live listing. No manually maintained part remains.
5. Prints a diff summary against the current file: added / removed / changed commands and arguments.

Project-defined commands are out of scope — the reference documents the package surface only.

CI. A bare runner with the .NET SDK: dotnet run --project tools/CommandRefGen -- --version latest → updated file + diff summary in the log. Triggered manually or by the release-watch workflow from #2, which polls the same versions endpoint.

Replaces tools/gen-commands-md.js.

Acceptance criteria:

• a run on a clean machine without Unity produces a file equivalent to the current one (modulo newly added commands);
• the RuntimeOnly section is generated, not hand-maintained;
• a package version bump is a rerun with a different argument, no code edits.

[ArkTarusov]

Requirements picked up from the field-run review:

• Descriptions: no truncation. The old 140/150-char cap cut load-bearing details (e.g. default shader names). DO collapse newlines/whitespace runs to a single space — a multi-line description must not break the markdown list layout. Optional: an emergency ceiling (~1000 chars) that prints a warning to stderr when hit — never a silent cut.
• Version-gated commands. The package compiles some commands conditionally (e.g. capture_runtime_element under #if UNITY_6000_7_OR_NEWER). The generator must mark such commands with their minimum Unity version instead of presenting them as universally available.
• Single ownership of the output file. The generator must own the whole file (preamble, Contents/TOC, RuntimeOnly section) or clearly delimit generated vs hand-maintained regions — the current split (stale preamble inside the script + manual re-splicing) is the drift trap this issue exists to remove.