feat: Implement discriminated union pattern for ModuleResult<T>

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

@@ -76,8 +76,8 @@ switch (result)
     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}");
+    case ModuleResult<string>.Skipped { Decision: var skip }:
+        Console.WriteLine($"Skipped: {skip.Reason}");
         break;
 }
 ```
@@ -172,11 +172,13 @@ internal static Skipped CreateSkipped(SkipDecision decision, ModuleExecutionCont
 
 ### Removed
 - `ModuleResult<T>.Value` property (the throwing one)
-- `ModuleFailedException` class
-- `ModuleSkippedException` class
 - `SkippedModuleResult<T>` subclass
 - `TimedOutModuleResult<T>` subclass
 
+### Deprecated (not removed)
+- `ModuleFailedException` class (marked with [Obsolete])
+- `ModuleSkippedException` class (marked with [Obsolete])
+
 ### Preserved
 - `ModuleResultType` property (now computed)
 - `IModuleResult` interface

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 == true)
                 {
                     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.Examples/Modules/Azure/AssignAccessToBlobStorageModule.cs

@@ -21,8 +21,8 @@ public class AssignAccessToBlobStorageModule : Module<RoleAssignmentResource>
         var storageAccount = context.GetModule<ProvisionBlobStorageAccountModule, StorageAccountResource>();
 
         var roleAssignmentResource = await context.Azure().Provisioner.Security.RoleAssignment(
-            storageAccount.Value!.Id,
-            new RoleAssignmentCreateOrUpdateContent(WellKnownRoleDefinitions.BlobStorageOwnerDefinitionId, userAssignedIdentity.Value!.Data.PrincipalId!.Value)
+            storageAccount.ValueOrDefault!.Id,
+            new RoleAssignmentCreateOrUpdateContent(WellKnownRoleDefinitions.BlobStorageOwnerDefinitionId, userAssignedIdentity.ValueOrDefault!.Data.PrincipalId!.Value)
         );
 
         return roleAssignmentResource.Value;

src/ModularPipelines.Examples/Modules/Azure/ProvisionAzureFunction.cs

@@ -31,7 +31,7 @@ public class ProvisionAzureFunction : Module<WebSiteResource>
             {
                 Identity = new ManagedServiceIdentity(ManagedServiceIdentityType.UserAssigned)
                 {
-                    UserAssignedIdentities = { { userAssignedIdentity.Value!.Id, new UserAssignedIdentity() } },
+                    UserAssignedIdentities = { { userAssignedIdentity.ValueOrDefault!.Id, new UserAssignedIdentity() } },
                 },
                 SiteConfig = new SiteConfigProperties
                 {
@@ -40,12 +40,12 @@ public class ProvisionAzureFunction : Module<WebSiteResource>
                         new()
                         {
                             Name = "BlobStorageConnectionString",
-                            Value = storageAccount.Value!.Data.PrimaryEndpoints.BlobUri.AbsoluteUri,
+                            Value = storageAccount.ValueOrDefault!.Data.PrimaryEndpoints.BlobUri.AbsoluteUri,
                         },
                         new()
                         {
                             Name = "BlobContainerName",
-                            Value = blobContainer.Value!.Data.Name,
+                            Value = blobContainer.ValueOrDefault!.Data.Name,
                         },
                     },
                 },

src/ModularPipelines.Examples/Modules/Azure/ProvisionBlobStorageContainerModule.cs

@@ -15,7 +15,7 @@ public class ProvisionBlobStorageContainerModule : Module<BlobContainerResource>
         var blobStorageAccount = context.GetModule<ProvisionBlobStorageAccountModule, StorageAccountResource>();
 
         var blobContainerProvisionResponse = await context.Azure().Provisioner.Storage.BlobContainer(
-            blobStorageAccount.Value!.Id,
+            blobStorageAccount.ValueOrDefault!.Id,
             "MyContainer",
             new BlobContainerData()
         );

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 />