Merge pull request #79 from Chris-Wolfgang/feature/testkit-changes

Chris-Wolfgang · web-flow · commit 5d2841fe7828 · 2026-03-14T21:20:35.000-04:00
Feature/testkit changes
diff --git a/.editorconfig b/.editorconfig
@@ -352,6 +352,12 @@ dotnet_diagnostic.MA0004.severity = none     # Meziantou: Use ConfigureAwait
 dotnet_diagnostic.S3216.severity = none      # SonarAnalyzer: ConfigureAwait
 dotnet_diagnostic.CA2007.severity = none     # .NET Analyzer: Use ConfigureAwait
 
+# Prefer expression bodies - suppress the suggestion to use block bodies instead
+dotnet_diagnostic.IDE0022.severity = none    # Expression bodies preferred
+
+# Test method names use Async by convention — VSTHRD200 is a false positive here
+dotnet_diagnostic.VSTHRD200.severity = none  # Async suffix not required in test method names
+
 # Test projects - relaxed naming, no doc requirements
 [tests/**/*.cs]
 # Allow Test_Method_Names_With_Underscores
@@ -402,7 +408,8 @@ dotnet_diagnostic.SA1600.severity = none
 dotnet_diagnostic.SA1601.severity = none
 dotnet_diagnostic.SA1602.severity = none
 
-# Benchmark projects - relaxed naming, no doc requirements
+
+# Benchmark, no doc requirements
 [benchmarks/**/*.cs]
 # Allow Benchmark_Method_Names
 dotnet_diagnostic.SA1300.severity = none
diff --git a/.github/workflows/pr.yaml b/.github/workflows/pr.yaml
@@ -53,10 +53,10 @@ jobs:
           fi
 
   # ============================================================================
-  # STAGE 1: Linux - .NET Tests (no coverage collection)
+  # STAGE 1: Linux - .NET Core/5+ Tests with Coverage Gate
   # ============================================================================
   test-linux-core: 
-    name: "Stage 1: Linux Tests (.NET 5.0-10.0 and netcoreapp3.1) + Coverage Gate"
+    name: "Stage 1: Linux Tests (.NET 5.0-10.0) + Coverage Gate"
     runs-on:  ubuntu-latest
     needs: detect-projects
     if: github.repository != 'Chris-Wolfgang/repo-template' && needs.detect-projects.outputs.has-projects == 'true'
@@ -175,7 +175,7 @@ jobs:
           echo ""
           echo "✅ All compatible projects built successfully"
 
-      - name: Run tests (.NET 5.0-10.0 and netcoreapp3.1)
+      - name: Run tests with coverage (.NET Core 5.0 - 10.0)
         run: |
           # Find all test projects (C#, VB.NET, F#)
           mapfile -d '' -t test_projects < <(find ./tests -type f \( -name "*.csproj" -o -name "*.vbproj" -o -name "*.fsproj" \) -print0)
@@ -310,10 +310,10 @@ jobs:
             tests/**/bin/Release
 
   # ============================================================================
-  # STAGE 2: Windows - All .NET Tests + Coverage Gate (Gated by Stage 1)
+  # STAGE 2: Windows - All .NET Tests (Gated by Stage 1)
   # ============================================================================
   test-windows:
-    name: "Stage 2: Windows Tests (.NET 5.0-10.0, Framework 4.6.2-4.8.1) + Coverage"
+    name: "Stage 2: Windows Tests (.NET 5.0-10.0, Framework 4.6.2-4.8.1)"
     runs-on: windows-latest
     needs: [detect-projects, test-linux-core]
     if: success() && github.repository != 'Chris-Wolfgang/repo-template' && needs.detect-projects.outputs.has-projects == 'true'
@@ -329,8 +329,6 @@ jobs:
         uses: actions/setup-dotnet@v4
         with:
           dotnet-version: |
-            3.1.x
-            3.1.x
             3.1.x
             5.0.x
             6.0.x
@@ -345,7 +343,7 @@ jobs:
       - name: Build solution
         run: dotnet build --no-restore --configuration Release
 
-      - name: Run all .NET tests with coverage (.NET 5.0-10.0 and Framework 4.6.2-4.8.1)
+      - name: Run all .NET tests (.NET 5.0-10.0 and Framework 4.6.2-4.8.1)
         shell: pwsh
         run: |
           $ErrorActionPreference = 'Stop'
@@ -506,10 +504,10 @@ jobs:
             CoverageReport/
 
   # ============================================================================
-  # STAGE 3: macOS Tests (Gated by Stage 2) + Coverage
+  # STAGE 3: macOS Tests (Gated by Stage 2)
   # ============================================================================
   test-macos-core:
-    name: "Stage 3: macOS Tests (.NET 6.0-10.0) + Coverage"
+    name: "Stage 3: macOS Tests (.NET 6.0-10.0)"
     runs-on: macos-latest
     needs: [detect-projects, test-windows]
     if: github.repository != 'Chris-Wolfgang/repo-template' && needs.detect-projects.outputs.has-projects == 'true' && needs.test-windows.result == 'success'
diff --git a/Directory.Build.props b/Directory.Build.props
@@ -45,13 +45,13 @@
     </PackageReference>
     
     <!-- Meziantou - Comprehensive code quality -->
-    <PackageReference Include="Meziantou.Analyzer" Version="3.0.22">
+    <PackageReference Include="Meziantou.Analyzer" Version="3.0.23">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
 
     <!-- SonarAnalyzer - Industry-standard analysis -->
-    <PackageReference Include="SonarAnalyzer.CSharp" Version="10.20.0.135146">
+    <PackageReference Include="SonarAnalyzer.CSharp" Version="10.21.0.135717">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
diff --git a/examples/Net4.8/Example1-BasicETL/packages.config b/examples/Net4.8/Example1-BasicETL/packages.config
@@ -1,6 +1,6 @@
 ﻿<?xml version="1.0" encoding="utf-8"?>
 <packages>
-  <package id="Microsoft.Bcl.AsyncInterfaces" version="10.0.3" targetFramework="net48" />
+  <package id="Microsoft.Bcl.AsyncInterfaces" version="10.0.5" targetFramework="net48" />
   <package id="System.Runtime.CompilerServices.Unsafe" version="6.1.2" targetFramework="net48" />
   <package id="System.Threading.Tasks.Extensions" version="4.6.3" targetFramework="net48" />
 </packages>
diff --git a/examples/Net4.8/Example2-WithCancellationToken/packages.config b/examples/Net4.8/Example2-WithCancellationToken/packages.config
@@ -1,6 +1,6 @@
 ﻿<?xml version="1.0" encoding="utf-8"?>
 <packages>
-  <package id="Microsoft.Bcl.AsyncInterfaces" version="10.0.3" targetFramework="net48" />
+  <package id="Microsoft.Bcl.AsyncInterfaces" version="10.0.5" targetFramework="net48" />
   <package id="System.Runtime.CompilerServices.Unsafe" version="6.1.2" targetFramework="net48" />
   <package id="System.Threading.Tasks.Extensions" version="4.6.3" targetFramework="net48" />
 </packages>
diff --git a/examples/Net4.8/Example3-WithGracefulCancellation/packages.config b/examples/Net4.8/Example3-WithGracefulCancellation/packages.config
@@ -1,6 +1,6 @@
 ﻿<?xml version="1.0" encoding="utf-8"?>
 <packages>
-  <package id="Microsoft.Bcl.AsyncInterfaces" version="10.0.3" targetFramework="net48" />
+  <package id="Microsoft.Bcl.AsyncInterfaces" version="10.0.5" targetFramework="net48" />
   <package id="System.Runtime.CompilerServices.Unsafe" version="6.1.2" targetFramework="net48" />
   <package id="System.Threading.Tasks.Extensions" version="4.6.3" targetFramework="net48" />
 </packages>
diff --git a/examples/Net4.8/Example4a-WithExtractorProgress/packages.config b/examples/Net4.8/Example4a-WithExtractorProgress/packages.config
@@ -1,6 +1,6 @@
 ﻿<?xml version="1.0" encoding="utf-8"?>
 <packages>
-  <package id="Microsoft.Bcl.AsyncInterfaces" version="10.0.3" targetFramework="net48" />
+  <package id="Microsoft.Bcl.AsyncInterfaces" version="10.0.5" targetFramework="net48" />
   <package id="System.Runtime" version="4.3.1" targetFramework="net48" />
   <package id="System.Runtime.CompilerServices.Unsafe" version="6.1.2" targetFramework="net48" />
   <package id="System.Threading.Tasks.Extensions" version="4.6.3" targetFramework="net48" />
diff --git a/examples/Net4.8/Example4b-WithTransformerProgress/packages.config b/examples/Net4.8/Example4b-WithTransformerProgress/packages.config
@@ -1,6 +1,6 @@
 ﻿<?xml version="1.0" encoding="utf-8"?>
 <packages>
-  <package id="Microsoft.Bcl.AsyncInterfaces" version="10.0.3" targetFramework="net48" />
+  <package id="Microsoft.Bcl.AsyncInterfaces" version="10.0.5" targetFramework="net48" />
   <package id="System.Runtime.CompilerServices.Unsafe" version="6.1.2" targetFramework="net48" />
   <package id="System.Threading.Tasks.Extensions" version="4.6.3" targetFramework="net48" />
 </packages>
diff --git a/examples/Net4.8/Example4c-WithLoaderProgress/packages.config b/examples/Net4.8/Example4c-WithLoaderProgress/packages.config
@@ -1,6 +1,6 @@
 ﻿<?xml version="1.0" encoding="utf-8"?>
 <packages>
-  <package id="Microsoft.Bcl.AsyncInterfaces" version="10.0.3" targetFramework="net48" />
+  <package id="Microsoft.Bcl.AsyncInterfaces" version="10.0.5" targetFramework="net48" />
   <package id="System.Runtime.CompilerServices.Unsafe" version="6.1.2" targetFramework="net48" />
   <package id="System.Threading.Tasks.Extensions" version="4.6.3" targetFramework="net48" />
 </packages>
diff --git a/examples/Net4.8/Example5a-ExtractorWithProgressAndCancellation/packages.config b/examples/Net4.8/Example5a-ExtractorWithProgressAndCancellation/packages.config
@@ -1,6 +1,6 @@
 ﻿<?xml version="1.0" encoding="utf-8"?>
 <packages>
-  <package id="Microsoft.Bcl.AsyncInterfaces" version="10.0.3" targetFramework="net48" />
+  <package id="Microsoft.Bcl.AsyncInterfaces" version="10.0.5" targetFramework="net48" />
   <package id="System.Runtime.CompilerServices.Unsafe" version="6.1.2" targetFramework="net48" />
   <package id="System.Threading.Tasks.Extensions" version="4.6.3" targetFramework="net48" />
 </packages>
diff --git a/examples/Net4.8/Example6-ReducingDuplicateCode/packages.config b/examples/Net4.8/Example6-ReducingDuplicateCode/packages.config
@@ -1,6 +1,6 @@
 ﻿<?xml version="1.0" encoding="utf-8"?>
 <packages>
-  <package id="Microsoft.Bcl.AsyncInterfaces" version="10.0.3" targetFramework="net48" />
+  <package id="Microsoft.Bcl.AsyncInterfaces" version="10.0.5" targetFramework="net48" />
   <package id="System.Runtime.CompilerServices.Unsafe" version="6.1.2" targetFramework="net48" />
   <package id="System.Threading.Tasks.Extensions" version="4.6.3" targetFramework="net48" />
 </packages>
diff --git a/src/Wolfgang.Etl.Abstractions/ExtractorBase.cs b/src/Wolfgang.Etl.Abstractions/ExtractorBase.cs
@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
+using System.Runtime.CompilerServices;
 using System.Threading;
 
 
@@ -73,7 +74,7 @@ public int ReportingInterval
     /// This is useful for partially extracting data from a source, especially when the source is large
     /// or infinite or during development.
     /// </remarks>
-    /// <exception cref="ArgumentOutOfRangeException">The specified value is less than 0.</exception>
+    /// <exception cref="ArgumentOutOfRangeException">The specified value is less than 1.</exception>
     /// <example>
     /// <code>
     ///     var count = 0;
@@ -98,11 +99,11 @@ public int MaximumItemCount
         set
         {
 #if NET8_0_OR_GREATER
-            ArgumentOutOfRangeException.ThrowIfLessThan(value, 0);
+            ArgumentOutOfRangeException.ThrowIfLessThan(value, 1);
 #else
-            if (value < 0)
+            if (value < 1)
             {
-                throw new ArgumentOutOfRangeException(nameof(value), "Maximum item count cannot be less than 0.");
+                throw new ArgumentOutOfRangeException(nameof(value), "Maximum item count cannot be less than 1.");
             }
 #endif
             field = value;
@@ -218,17 +219,7 @@ public virtual IAsyncEnumerable<TSource> ExtractAsync(IProgress<TProgress> progr
 #pragma warning restore RCS1140
 #endif
 
-        // Timer is synchronously disposed when this method returns its IAsyncEnumerable.
-        // MA0042 (prefer await using) is suppressed: System.Threading.Timer does not implement IAsyncDisposable.
-#pragma warning disable MA0042
-        using var timer = new Timer(
-            ReportProgress,
-            state: progress,
-            TimeSpan.Zero,
-            TimeSpan.FromMilliseconds(ReportingInterval));
-#pragma warning restore MA0042
-
-        return ExtractWorkerAsync(CancellationToken.None);
+        return ExtractWithProgressAsync(progress, CancellationToken.None);
     }
 
 
@@ -260,17 +251,38 @@ public virtual IAsyncEnumerable<TSource> ExtractAsync(IProgress<TProgress> progr
 #pragma warning restore RCS1140
 #endif
 
-        // Timer is synchronously disposed when this method returns its IAsyncEnumerable.
-        // MA0042 (prefer await using) is suppressed: System.Threading.Timer does not implement IAsyncDisposable.
+        return ExtractWithProgressAsync(progress, token);
+    }
+
+
+
+    private async IAsyncEnumerable<TSource> ExtractWithProgressAsync(
+        IProgress<TProgress> progress,
+        [EnumeratorCancellation] CancellationToken token)
+    {
+        // MA0042 suppressed: System.Threading.Timer does not implement IAsyncDisposable.
 #pragma warning disable MA0042
-        using var timer = new Timer(
+        var timer = new Timer(
             ReportProgress,
             state: progress,
-            TimeSpan.Zero,
+            TimeSpan.FromMilliseconds(ReportingInterval),
             TimeSpan.FromMilliseconds(ReportingInterval));
 #pragma warning restore MA0042
 
-        return ExtractWorkerAsync(token);
+        try
+        {
+            await foreach (var item in ExtractWorkerAsync(token))
+            {
+                yield return item;
+            }
+        }
+        finally
+        {
+#pragma warning disable CA1849, VSTHRD103 // Timer.Dispose() is correct here; await is not valid in a finally block
+            timer.Dispose();
+#pragma warning restore CA1849, VSTHRD103
+            progress.Report(CreateProgressReport());
+        }
     }
 
 
diff --git a/src/Wolfgang.Etl.Abstractions/IProgressTimer.cs b/src/Wolfgang.Etl.Abstractions/IProgressTimer.cs
@@ -0,0 +1,38 @@
+using System;
+
+
+
+namespace Wolfgang.Etl.Abstractions;
+
+/// <summary>
+/// Represents a timer that raises <see cref="Elapsed"/> at a regular interval,
+/// used by extractor, transformer, and loader base classes to drive progress callbacks.
+/// </summary>
+/// <remarks>
+/// The default production implementation typically uses <see cref="System.Threading.Timer"/>
+/// internally. In unit tests, a custom implementation can be injected to fire the
+/// <see cref="Elapsed"/> event on demand, making progress callback assertions
+/// deterministic.
+/// </remarks>
+public interface IProgressTimer : IDisposable
+{
+    /// <summary>
+    /// Raised at each timer interval. Subscribers receive progress notifications
+    /// and should call <c>CreateProgressReport()</c> then <c>Report()</c>.
+    /// </summary>
+    event Action? Elapsed;
+
+    /// <summary>
+    /// Starts the timer with the specified interval in milliseconds.
+    /// </summary>
+    /// <param name="intervalMilliseconds">
+    /// The number of milliseconds between <see cref="Elapsed"/> events.
+    /// </param>
+    void Start(int intervalMilliseconds);
+
+    /// <summary>
+    /// Stops the timer. No further <see cref="Elapsed"/> events will be raised
+    /// until <see cref="Start"/> is called again.
+    /// </summary>
+    void StopTimer();
+}
diff --git a/src/Wolfgang.Etl.Abstractions/LoaderBase.cs b/src/Wolfgang.Etl.Abstractions/LoaderBase.cs
@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
+using System.Runtime.CompilerServices;
 using System.Threading;
 using System.Threading.Tasks;
 
@@ -219,17 +220,7 @@ public virtual Task LoadAsync(IAsyncEnumerable<TDestination> items, IProgress<TP
 #pragma warning restore RCS1140
 #endif
 
-        // Timer is synchronously disposed when this method returns its Task.
-        // MA0042 (prefer await using) is suppressed: System.Threading.Timer does not implement IAsyncDisposable.
-#pragma warning disable MA0042
-        using var timer = new Timer(
-            ReportProgress,
-            state: progress,
-            TimeSpan.Zero,
-            TimeSpan.FromMilliseconds(ReportingInterval));
-#pragma warning restore MA0042
-
-        return LoadWorkerAsync(items, CancellationToken.None);
+        return LoadWithProgressAsync(items, progress, CancellationToken.None);
     }
 
 
@@ -264,17 +255,36 @@ public virtual Task LoadAsync(IAsyncEnumerable<TDestination> items, IProgress<TP
 #pragma warning restore RCS1140
 #endif
 
-        // Timer is synchronously disposed when this method returns its Task.
-        // MA0042 (prefer await using) is suppressed: System.Threading.Timer does not implement IAsyncDisposable.
+        return LoadWithProgressAsync(items, progress, token);
+    }
+
+
+
+    private async Task LoadWithProgressAsync(
+        IAsyncEnumerable<TDestination> items,
+        IProgress<TProgress> progress,
+        CancellationToken token)
+    {
+        // MA0042 suppressed: System.Threading.Timer does not implement IAsyncDisposable.
 #pragma warning disable MA0042
-        using var timer = new Timer(
+        var timer = new Timer(
             ReportProgress,
             state: progress,
-            TimeSpan.Zero,
+            TimeSpan.FromMilliseconds(ReportingInterval),
             TimeSpan.FromMilliseconds(ReportingInterval));
 #pragma warning restore MA0042
 
-        return LoadWorkerAsync(items, token);
+        try
+        {
+            await LoadWorkerAsync(items, token).ConfigureAwait(false);
+        }
+        finally
+        {
+#pragma warning disable CA1849, VSTHRD103 // Timer.Dispose() is correct here; await is not valid in a finally block
+            timer.Dispose();
+#pragma warning restore CA1849, VSTHRD103
+            progress.Report(CreateProgressReport());
+        }
     }
 
 
diff --git a/src/Wolfgang.Etl.Abstractions/TransformerBase.cs b/src/Wolfgang.Etl.Abstractions/TransformerBase.cs
diff --git a/src/Wolfgang.Etl.Abstractions/Wolfgang.Etl.Abstractions.csproj b/src/Wolfgang.Etl.Abstractions/Wolfgang.Etl.Abstractions.csproj
diff --git a/tests/Wolfgang.Etl.Abstractions.Tests.Unit/BaseClassTests/ExtractorBaseTests.cs b/tests/Wolfgang.Etl.Abstractions.Tests.Unit/BaseClassTests/ExtractorBaseTests.cs
diff --git a/tests/Wolfgang.Etl.Abstractions.Tests.Unit/Wolfgang.Etl.Abstractions.Tests.Unit.csproj b/tests/Wolfgang.Etl.Abstractions.Tests.Unit/Wolfgang.Etl.Abstractions.Tests.Unit.csproj
