Expand Nuke.* transition shims to full public API coverage via source generator

[ChrisonSimtian]

Follow-up to #47 / PR that ships the Nuke.Common MVP shim.

Current state

src/Shims/Nuke.Common/ ships a hand-written shim covering the entry-point surface: NukeBuild, INukeBuild, [Parameter], [Secret], [Solution], [GitRepository]. That's enough for a class Build : NukeBuild { ... } declaration to compile against the shim.

Gap

Hand-written shims don't scale. Fallout.Common alone has 158 public types. Add Fallout.Build, Fallout.Components, Fallout.Tooling, ProjectModel, SolutionModel, Utilities (and sub-packages) — easily 500+ public types across all shim packages. Each needs:

C# construct	Shim mechanism
Class	Public subclass with constructors mirrored
Sealed class	Wrapper with member-by-member delegation
Interface	Sub-interface
Abstract class	Public subclass (stays abstract)
Enum	Cannot be subclassed — needs a using = alias documentation, or skip
Delegate	Cannot be implicitly converted across types — skip
Static helper class	Static wrapper with method-by-method delegation
Attribute	Subclass with constructor pass-through
Generic class/method	Pass through type parameters / constraints

Design

A Roslyn source generator referenced from each shim project. The generator:

1. Reads [assembly: ShimAllPublicTypesFrom("Fallout.Common")] marker (or similar).
2. Finds the canonical referenced assembly in the compilation's references.
3. Walks every public type via INamespaceSymbol/INamedTypeSymbol.
4. For each, emits source for the appropriate shim mechanism above into a generated .cs file in the shim project.
5. Skips types it can't bridge (enums, delegates) — logs them and emits build warnings so we know what consumers are still locked out of.

Out of scope (deliberately)

• Bridging delegates — fallout-migrate handles that
• Bridging enums — fallout-migrate handles that

Why hand-written shipped first

• Source generator is non-trivial (~500 LOC of generator code + tests)
• A hand-written MVP gave Chris's other Fallout-consuming project something to test today
• Architecture (subclass-based) is the same in both — only the generation method differs

Done when

• Generator produces shims for every public class/interface/struct/attribute/static-helper-method in the marker's target assembly
• All 15 Fallout.* canonical packages have matching shim projects (Nuke.Common, Nuke.Build, Nuke.Components, etc.)
• tests/Nuke.Common.Shim.Tests/SampleConsumerBuild.cs expanded to exercise the full surface a typical consumer touches and still compiles
• Release pipeline pushes shim nupkgs to GitHub Packages alongside the Fallout.* push to nuget.org

[ChrisonSimtian]

Session 1 landed in 230e7a2: TransitionShimGenerator + Easy-tier coverage on Nuke.Common.

• Generator scaffolding, marker attribute, Easy-tier emitters (class/abstract/interface/attribute/generic/nested)
• Applied to Nuke.Common shim — 900 generated shim types (was 4 hand-written)
• SHIM001 build warnings track every skipped Hard-tier type (sealed, static, enum, delegate, no-accessible-ctor)
• Snapshot tests in Fallout.SourceGenerators.Tests
• Existing Nuke.Common.Shim.Tests compile-only test passes against generated+hand-written hybrid

Remaining (deferred to follow-up sessions):

• Hard tier: sealed class wrappers + static-class method delegation
• 14 other shim projects (Nuke.Build, Nuke.Components, Nuke.Tooling, ...)
• Release pipeline: dual-publish Nuke.* to GH Packages alongside Fallout.* to nuget.org

[ChrisonSimtian]

Session 2 landed in 163c262 — static-class method delegation.

• All static classes now emit forwarding shims (DotNetTasks, MSBuildTasks, *Extensions, utility helpers, etc.)
• Method shapes covered: plain, void, generic (with constraints), optional/params/ref/out/in args, extension methods, enum and type-parameter defaults
• Ambiguity detection: same FQN across multiple Fallout.* assemblies now emits SHIM001:ambiguous-across-assemblies and skips (avoids CS0433)
• Snapshot tests + Nuke.Common.Shim.Tests still green
• 0 errors on Nuke.Common shim build

Remaining for follow-ups:

• Session 2b: sealed-class wrappers with member-by-member delegation + implicit conversions (2 sealed-class skips + 4 struct skips remain)
• Session 3: 14 other shim projects (Nuke.Build, Nuke.Components, ...) — needs csproj scaffolding, not new generator work

[ChrisonSimtian]

Session 4 landed in 6225d73 (#140) — hand-written CI host singletons in Nuke.Common.

What shipped

• 10 hand-written public static class shims under Nuke.Common.CI.<Vendor>/: AppVeyor, AzurePipelines, Bamboo, Bitbucket, Bitrise, GitHubActions, GitLab, Jenkins, TeamCity, TravisCI
• Each re-exposes the canonical .Instance (returning canonical type); AppVeyor also re-exposes MessageLimit
• SampleConsumerBuild.TouchCiHostShims() exercises the new surface — compile-only contract enforced
• README updated with coverage row + "CI host shim limitation" callout

Why hand-written, not generator-driven

These hit two walls the generator can't cleanly bridge:

1. No accessible ctor — all 10 host ctors are internal; SHIM001 skips them as no-accessible-ctor
2. Subclassing wouldn't help anyway — consumers don't new these; they receive canonical-typed instances from Host.Instance which can't be cast back to a shim subclass. A subclass shim breaks [CI] readonly GitHubActions GitHubActions; field-injection and Host is GitHubActions checks

Static pass-through is the honest fix. Consumers write GitHubActions.Instance.Workflow — Instance returns canonical so member chains flow through naturally. Field-injection patterns still need fallout-migrate to flip type refs to canonical, documented in the shim README.

ROI calibration along the way

Forced rebuild of the Nuke.Common shim surfaced the true skip distribution:

Kind	Count
enum	76
no-accessible-ctor	28
delegate	14
struct	4
ambiguous-across-assemblies	4
sealed-class	2 (both GlobbingOptionsAttribute)

Most of the remaining Hard-tier surface is bounded by C# limits (enum/delegate/struct can't be subclassed) and is fallout-migrate work. The largest addressable skip bucket was the 28 no-accessible-ctor types — 10 of which (the CI singletons) are now bridged.

Verification

• Nuke.Common, Nuke.Build, Nuke.Components 10.3.13 live on GitHub Packages (pushed 02:01:3xZ on 2026-05-24)
• All 18 Fallout.* packages 10.3.13 live on nuget.org
• 5/5 Fallout.SourceGenerators.Tests pass — no snapshot regression
• 0 errors on shim + shim-tests builds

Roadmap status

• session 1: ✅ Easy-tier generator + Nuke.Common shim
• session 2: ✅ Static-class method delegation
• session 2b: ⏸️ Sealed-class wrappers — live ROI is 1 attribute type; deferred (better addressed by un-sealing the canonical or by fallout-migrate)
• session 3: ✅ Nuke.Build + Nuke.Components shims
• session 4 (this comment): ✅ CI host singletons (10 vendors, hand-written)

Still open under this issue:

• Other no-accessible-ctor types: AbsolutePath, AzureKeyVault, MSBuildProject, DelegateDisposable — these are not singletons, each needs a separate look
• SHIM001 suppression mechanism for hand-bridged types (cosmetic — currently 10 warnings still fire on the bridged hosts)
• Wider consumer-surface verification in SampleConsumerBuild beyond CI hosts