feat: Implement discriminated union pattern for ModuleResult<T>

docs/plans/2026-01-07-module-result-discriminated-union.md

@@ -0,0 +1,198 @@
+# ModuleResult Discriminated Union Design
+
+**Issue:** #1869
+**Date:** 2026-01-07
+**Status:** Approved
+
+## Problem
+
+The current `ModuleResult<T>.Value` property throws exceptions when accessed on failed or skipped results:
+
+```csharp
+var result = await myModule;
+var value = result.Value; // Throws ModuleFailedException or ModuleSkippedException!
+```
+
+This leads to:
+- Implicit exceptions and poor control flow
+- No compile-time exhaustiveness checking
+- Awkward try-catch patterns around property access
+
+## Solution
+
+Replace with a discriminated union pattern using C# records:
+
+```csharp
+public abstract record ModuleResult<T> : IModuleResult
+{
+    // Metadata (available on all outcomes)
+    public required string ModuleName { get; init; }
+    public required TimeSpan ModuleDuration { get; init; }
+    public required DateTimeOffset ModuleStart { get; init; }
+    public required DateTimeOffset ModuleEnd { get; init; }
+    public required Status ModuleStatus { get; init; }
+
+    // Quick checks
+    public bool IsSuccess => this is Success;
+    public bool IsFailure => this is Failure;
+    public bool IsSkipped => this is Skipped;
+
+    // Safe accessors (no exceptions)
+    public T? ValueOrDefault => this is Success s ? s.Value : default;
+    public Exception? ExceptionOrDefault => this is Failure f ? f.Exception : null;
+    public SkipDecision? SkipDecisionOrDefault => this is Skipped sk ? sk.Decision : null;
+
+    // Computed for compatibility
+    public ModuleResultType ModuleResultType => this switch
+    {
+        Success => ModuleResultType.Success,
+        Failure => ModuleResultType.Failure,
+        Skipped => ModuleResultType.Skipped,
+        _ => throw new InvalidOperationException()
+    };
+
+    // Discriminated variants
+    public sealed record Success(T Value) : ModuleResult<T>;
+    public sealed record Failure(Exception Exception) : ModuleResult<T>;
+    public sealed record Skipped(SkipDecision Decision) : ModuleResult<T>;
+
+    // Prevent external inheritance
+    private ModuleResult() { }
+}
+```
+
+## Usage Examples
+
+### Pattern Matching (Recommended)
+
+```csharp
+var result = await buildModule;
+
+switch (result)
+{
+    case ModuleResult<string>.Success { Value: var value }:
+        Console.WriteLine($"Got: {value}");
+        break;
+    case ModuleResult<string>.Failure { Exception: var ex }:
+        Console.WriteLine($"Failed: {ex.Message}");
+        break;
+    case ModuleResult<string>.Skipped { Decision.Reason: var reason }:
+        Console.WriteLine($"Skipped: {reason}");
+        break;
+}
+```
+
+### Match Helper
+
+```csharp
+string message = result.Match(
+    onSuccess: value => $"Got: {value}",
+    onFailure: ex => $"Error: {ex.Message}",
+    onSkipped: skip => $"Skipped: {skip.Reason}"
+);
+```
+
+### Quick Checks
+
+```csharp
+if (result.IsSuccess)
+{
+    DoSomething(result.ValueOrDefault!);
+}
+```
+
+## Helper Methods
+
+```csharp
+// Match - transform to single type
+public TResult Match<TResult>(
+    Func<T, TResult> onSuccess,
+    Func<Exception, TResult> onFailure,
+    Func<SkipDecision, TResult> onSkipped);
+
+// Switch - side effects
+public void Switch(
+    Action<T> onSuccess,
+    Action<Exception> onFailure,
+    Action<SkipDecision> onSkipped);
+```
+
+## JSON Serialization
+
+Uses .NET 7+ polymorphic serialization:
+
+```csharp
+[JsonDerivedType(typeof(Success), "Success")]
+[JsonDerivedType(typeof(Failure), "Failure")]
+[JsonDerivedType(typeof(Skipped), "Skipped")]
+public abstract record ModuleResult<T> : IModuleResult
+```
+
+Output:
+```json
+{
+  "$type": "Success",
+  "Value": "build output",
+  "ModuleName": "BuildModule",
+  "ModuleDuration": "00:01:23"
+}
+```
+
+## Non-Generic Interface
+
+For type-erased scenarios (registries, summaries):
+
+```csharp
+public interface IModuleResult
+{
+    string ModuleName { get; }
+    TimeSpan ModuleDuration { get; }
+    DateTimeOffset ModuleStart { get; }
+    DateTimeOffset ModuleEnd { get; }
+    Status ModuleStatus { get; }
+    ModuleResultType ModuleResultType { get; }
+
+    object? ValueOrDefault { get; }
+    Exception? ExceptionOrDefault { get; }
+    SkipDecision? SkipDecisionOrDefault { get; }
+}
+```
+
+## Factory Methods
+
+Internal factory methods for engine use:
+
+```csharp
+internal static Success CreateSuccess(T value, ModuleExecutionContext ctx);
+internal static Failure CreateFailure(Exception exception, ModuleExecutionContext ctx);
+internal static Skipped CreateSkipped(SkipDecision decision, ModuleExecutionContext ctx);
+```
+
+## Breaking Changes
+
+### Removed
+- `ModuleResult<T>.Value` property (the throwing one)
+- `ModuleFailedException` class
+- `ModuleSkippedException` class
+- `SkippedModuleResult<T>` subclass
+- `TimedOutModuleResult<T>` subclass
+
+### Preserved
+- `ModuleResultType` property (now computed)
+- `IModuleResult` interface
+- All metadata property names
+- JSON serialization support
+
+## Target
+
+.NET 10 only - no backward compatibility shims needed.
+
+## Files to Modify
+
+1. `src/ModularPipelines/Models/ModuleResult.cs` - Main implementation
+2. `src/ModularPipelines/Models/IModuleResult.cs` - Update interface
+3. `src/ModularPipelines/Engine/Execution/ModuleResultFactory.cs` - Update factory
+4. `src/ModularPipelines/Exceptions/` - Remove ModuleFailedException, ModuleSkippedException
+5. `src/ModularPipelines/Models/SkippedModuleResult.cs` - Delete
+6. `src/ModularPipelines/Models/TimedOutModuleResult.cs` - Delete
+7. All files accessing `.Value` - Update to pattern matching

src/ModularPipelines.Build/Modules/CreateReleaseModule.cs

@@ -57,9 +57,9 @@ public Task<SkipDecision> ShouldSkip(IPipelineContext context)
         }
 
         return await context.GitHub().Client.Repository.Release.Create(repositoryId,
-            new NewRelease($"v{versionInfoResult.Value}")
+            new NewRelease($"v{versionInfoResult.ValueOrDefault}")
             {
-                Name = versionInfoResult.Value,
+                Name = versionInfoResult.ValueOrDefault,
                 GenerateReleaseNotes = true,
             });
     }

src/ModularPipelines.Build/Modules/FindProjectDependenciesModule.cs

@@ -16,7 +16,7 @@ public class FindProjectDependenciesModule : Module<FindProjectDependenciesModul
 
         var dependencies = new List<File>();
 
-        foreach (var file in projects.Value!)
+        foreach (var file in projects.ValueOrDefault!)
         {
             var projectRootElement = ProjectRootElement.Open(file)!;
 
@@ -27,7 +27,7 @@ public class FindProjectDependenciesModule : Module<FindProjectDependenciesModul
             foreach (var reference in projectReferences)
             {
                 var name = Path.GetFileName(reference);
-                var project = projects.Value!.FirstOrDefault(x => x.Name == name);
+                var project = projects.ValueOrDefault!.FirstOrDefault(x => x.Name == name);
 
                 if (project != null)
                 {
@@ -36,7 +36,7 @@ public class FindProjectDependenciesModule : Module<FindProjectDependenciesModul
             }
         }
 
-        var projectDependencies = new ProjectDependencies(Dependencies: dependencies.Distinct().ToList(), Others: projects.Value!.Except(dependencies).Distinct().ToList());
+        var projectDependencies = new ProjectDependencies(Dependencies: dependencies.Distinct().ToList(), Others: projects.ValueOrDefault!.Except(dependencies).Distinct().ToList());
 
         LogProjects(context, projectDependencies);
 

src/ModularPipelines.Build/Modules/GenerateReadMeModule.cs

@@ -27,7 +27,7 @@ public class GenerateReadMeModule : Module<IDictionary<string, object>>, IAlways
 
         var projects = context.GetModule<FindProjectsModule, IReadOnlyList<File>>();
 
-        foreach (var project in projects.Value!
+        foreach (var project in projects.ValueOrDefault!
                      .Where(x => !x.NameWithoutExtension.StartsWith("ModularPipelines.Analyzers")))
         {
             var moduleName = project.NameWithoutExtension;

src/ModularPipelines.Build/Modules/LocalMachine/AddLocalNugetSourceModule.cs

@@ -27,7 +27,7 @@ public Task<bool> ShouldIgnoreFailures(IPipelineContext context, Exception excep
         return await context.DotNet().Nuget.Add.Source(new DotNetNugetAddSourceOptions
         {
             Name = "ModularPipelinesLocalNuGet",
-            Packagesourcepath = localNugetPathResult.Value.AssertExists(),
+            Packagesourcepath = localNugetPathResult.ValueOrDefault.AssertExists(),
         }, cancellationToken: cancellationToken);
     }
 }

src/ModularPipelines.Build/Modules/LocalMachine/UploadPackagesToLocalNuGetModule.cs

@@ -21,8 +21,8 @@ public class UploadPackagesToLocalNuGetModule : Module<CommandResult[]>
 
         return await NugetUploadHelper.UploadPackagesAsync(
             context,
-            packagePaths.Value!,
-            source: localRepoLocation.Value.AssertExists()!.Path,
+            packagePaths.ValueOrDefault!,
+            source: localRepoLocation.ValueOrDefault.AssertExists()!.Path,
             apiKey: null,
             cancellationToken);
     }

src/ModularPipelines.Build/Modules/PackProjectsModule.cs

@@ -28,23 +28,23 @@ public class PackProjectsModule : Module<CommandResult[]>
 
         var changedFiles = context.GetModule<ChangedFilesInPullRequestModule, IReadOnlyList<File>>();
 
-        var dependencies = await projectFiles.Value!.Dependencies
+        var dependencies = await projectFiles.ValueOrDefault!.Dependencies
             .ToAsyncProcessorBuilder()
             .SelectAsync(async projectFile => await Pack(context, cancellationToken, projectFile, packageVersion))
             .ProcessOneAtATime();
 
         var gitVersioningInformation = await context.Git().Versioning.GetGitVersioningInformation();
 
-        var others = await projectFiles.Value!.Others
+        var others = await projectFiles.ValueOrDefault!.Others
             .Where(x =>
             {
-                if (changedFiles.SkipDecision.ShouldSkip)
+                if (changedFiles.SkipDecisionOrDefault.ShouldSkip)
                 {
                     return true;
                 }
 
                 return ProjectHasChanged(x,
-                    changedFiles.Value!, context);
+                    changedFiles.ValueOrDefault!, context);
             })
             .ToAsyncProcessorBuilder()
             .SelectAsync(async projectFile => await Pack(context, cancellationToken, projectFile, packageVersion))
@@ -79,8 +79,8 @@ private static async Task<CommandResult> Pack(IModuleContext context, Cancellati
             NoRestore = true,
             Properties = new List<KeyValue>
             {
-                ("PackageVersion", packageVersion.Value!),
-                ("Version", packageVersion.Value!),
+                ("PackageVersion", packageVersion.ValueOrDefault!),
+                ("Version", packageVersion.ValueOrDefault!),
             },
         }, cancellationToken: cancellationToken);
     }

src/ModularPipelines.Build/Modules/PackagePathsParserModule.cs

@@ -17,7 +17,7 @@ public class PackagePathsParserModule : Module<List<File>>
     {
         var packPackagesModuleResult = context.GetModule<PackProjectsModule, CommandResult[]>();
 
-        return Task.FromResult<List<File>?>(packPackagesModuleResult.Value!
+        return Task.FromResult<List<File>?>(packPackagesModuleResult.ValueOrDefault!
             .Select(x => x.StandardOutput)
             .Select(x => x.Split(PackageCreationSuccessPrefix)[1])
             .Select(x => x.Split(PackagePathSuffix)[0])

src/ModularPipelines.Build/Modules/PushVersionTagModule.cs

@@ -18,7 +18,7 @@ public Task<bool> ShouldIgnoreFailures(IPipelineContext context, Exception excep
     {
         var versionInformation = ((IModuleContext) context).GetModule<NugetVersionGeneratorModule, string>();
 
-        return Task.FromResult(exception.Message.Contains($"tag 'v{versionInformation.Value!}' already exists"));
+        return Task.FromResult(exception.Message.Contains($"tag 'v{versionInformation.ValueOrDefault!}' already exists"));
     }
 
     public override async Task<CommandResult?> ExecuteAsync(IModuleContext context, CancellationToken cancellationToken)
@@ -27,7 +27,7 @@ public Task<bool> ShouldIgnoreFailures(IPipelineContext context, Exception excep
 
         await context.Git().Commands.Tag(new GitTagOptions
         {
-            Arguments = [$"v{versionInformation.Value!}"],
+            Arguments = [$"v{versionInformation.ValueOrDefault!}"],
         }, token: cancellationToken);
 
         return await context.Git().Commands.Push(new GitPushOptions

src/ModularPipelines.Build/Modules/UploadPackagesToNugetModule.cs

@@ -41,7 +41,7 @@ public Task<SkipDecision> ShouldSkip(IPipelineContext context)
 
         return await NugetUploadHelper.UploadPackagesAsync(
             context,
-            packagePaths.Value!,
+            packagePaths.ValueOrDefault!,
             source: "https://api.nuget.org/v3/index.json",
             apiKey: _nugetSettings.Value.ApiKey,
             cancellationToken);

src/ModularPipelines.GitHub/GitHubMarkdownSummaryGenerator.cs

@@ -63,8 +63,8 @@ private async Task<string> GetException(PipelineSummary pipelineSummary)
 
         var exception = results
                             .FirstOrDefault(x => x.ModuleStatus == Status.Failed)
-                            ?.Exception
-                        ?? results.Select(x => x.Exception).FirstOrDefault();
+                            ?.ExceptionOrDefault
+                        ?? results.Select(x => x.ExceptionOrDefault).FirstOrDefault();
 
         if (exception is null)
         {

src/ModularPipelines/Attributes/Events/IModuleEndEventReceiver.cs

@@ -20,5 +20,5 @@ public interface IModuleEndEventReceiver
     /// <param name="context">The event context providing module information and control flow.</param>
     /// <param name="result">The result of the module execution.</param>
     /// <returns>A task representing the async operation.</returns>
-    Task OnModuleEndAsync(IModuleEventContext context, ModuleResult result);
+    Task OnModuleEndAsync(IModuleEventContext context, IModuleResult result);
 }

src/ModularPipelines/Engine/Attributes/AttributeEventInvoker.cs

@@ -85,7 +85,7 @@ public async Task InvokeStartReceiversAsync(
     public async Task InvokeEndReceiversAsync(
         IEnumerable<IModuleEndEventReceiver> receivers,
         IModuleEventContext context,
-        ModuleResult result)
+        IModuleResult result)
     {
         foreach (var receiver in receivers)
         {

src/ModularPipelines/Engine/Attributes/IAttributeEventInvoker.cs

@@ -14,7 +14,7 @@ internal interface IAttributeEventInvoker
 
     Task InvokeStartReceiversAsync(IEnumerable<IModuleStartEventReceiver> receivers, IModuleEventContext context);
 
-    Task InvokeEndReceiversAsync(IEnumerable<IModuleEndEventReceiver> receivers, IModuleEventContext context, ModuleResult result);
+    Task InvokeEndReceiversAsync(IEnumerable<IModuleEndEventReceiver> receivers, IModuleEventContext context, IModuleResult result);
 
     Task InvokeFailureReceiversAsync(IEnumerable<IModuleFailureEventReceiver> receivers, IModuleEventContext context, Exception exception);
 

src/ModularPipelines/Engine/Execution/ModuleLifecycleEventInvoker.cs

@@ -96,7 +96,7 @@ public async Task InvokeEndEventAsync(ModuleLifecycleContext context, Enums.Stat
             _metadataRegistry,
             context.CancellationToken);
 
-        await _attributeEventInvoker.InvokeEndReceiversAsync(receivers, eventContext, (ModuleResult)result).ConfigureAwait(false);
+        await _attributeEventInvoker.InvokeEndReceiversAsync(receivers, eventContext, result).ConfigureAwait(false);
     }
 
     /// <inheritdoc />