Merge develop into main

.claude/commands/coverage.md

@@ -6,12 +6,11 @@ pwsh scripts/Run-Tests.ps1 -Coverage
 ```
 
 Options:
-- `-Mode Ai` - AI-optimized output, excludes integration tests (default)
-- `-Mode Ci` - Full output, excludes integration tests
-- `-Mode AiFull` - AI-optimized output, includes all tests
-- `-Mode Full` - Full output, includes all tests
-- `-Mode AiIntegrations` - AI-optimized output, only integration tests
-- `-Mode IntegrationsOnly` - Full output, only integration tests
+- `-Mode Ai` - AI-optimized output, ALL tests (default)
+- `-Mode AiUnit` - AI-optimized output, unit tests only
+- `-Mode AiIntegrations` - AI-optimized output, integration tests only
+- `-Mode Unit` - Verbose output, unit tests only
+- `-Mode Integration` - Verbose output, integration tests only
 - `-ProjectFilter "Core"` - Run only matching projects
 
 This will:

.claude/commands/release.md

@@ -201,15 +201,25 @@ gh workflow run release.yml -f release_type=patch  # 0.0.x
 gh workflow run release.yml -f release_type=auto -f dry_run=true
 ```
 
+### Versioning Philosophy
+
+**All 0.x.x releases are pre-releases working toward v1.0.0.**
+
+- Library versions: `0.5.1-alpha.177`, `0.6.0-beta.1`, etc.
+- Documentation: Single `v1.0.0/` folder (no separate v0.1.0, v0.2.0 docs)
+- `<docs>` tags in code: Always versionless (e.g., `<docs>core-concepts/dispatcher</docs>`)
+
+When v1.0.0 is released, the library version will match the documentation version.
+
 ### GitFlow Branch Versioning
 
 | Branch | Version Format | Example |
 |--------|---------------|---------|
-| `main` | Stable release | `0.2.0` |
-| `develop` | Alpha pre-release | `0.3.0-alpha.1` |
-| `release/*` | Beta pre-release | `0.2.0-beta.1` |
-| `feature/*` | Feature pre-release | `0.3.0-feat-xyz.1` |
-| `hotfix/*` | Hotfix pre-release | `0.2.1-hotfix.1` |
+| `main` | Stable release | `1.0.0` (future) |
+| `develop` | Alpha pre-release | `0.6.0-alpha.1` |
+| `release/*` | Beta pre-release | `0.6.0-beta.1` |
+| `feature/*` | Feature pre-release | `0.6.0-feat-xyz.1` |
+| `hotfix/*` | Hotfix pre-release | `0.5.2-hotfix.1` |
 
 ### Conventional Commits for Version Bumps
 

.github/RELEASE.md

@@ -241,7 +241,7 @@ pwsh scripts/Run-Tests.ps1
 pwsh scripts/Run-Tests.ps1 -ProjectFilter "Core"
 
 # Run with AI-friendly output
-pwsh scripts/Run-Tests.ps1 -AiMode
+pwsh scripts/Run-Tests.ps1
 ```
 
 ### 1.3 Fix Absolute Paths
@@ -990,7 +990,7 @@ pwsh scripts/Run-Tests.ps1 -ProjectFilter "Core"
 pwsh scripts/Run-Tests.ps1 -TestFilter "DispatcherTests"
 
 # AI-friendly output
-pwsh scripts/Run-Tests.ps1 -AiMode
+pwsh scripts/Run-Tests.ps1
 ```
 
 ## Building
@@ -1752,19 +1752,19 @@ To release:
   - Set `<PackageDescription>`
   - Verify `<IsPackable>true</IsPackable>`
 
-- [ ] **Whizbang.Testing** - Testing utilities
-  - Set `<PackageDescription>`
-  - Verify `<IsPackable>true</IsPackable>`
-
 #### Data Packages
 - [ ] **Whizbang.Data.Schema** - Schema management
 - [ ] **Whizbang.Data.Postgres** - PostgreSQL support
+- [ ] **Whizbang.Data.Dapper.Custom** - Base Dapper abstractions
 - [ ] **Whizbang.Data.Dapper.Postgres** - Dapper + PostgreSQL
 - [ ] **Whizbang.Data.Dapper.Sqlite** - Dapper + SQLite
-- [ ] **Whizbang.Data.Dapper.Custom** - Custom Dapper implementations
+- [ ] **Whizbang.Data.EFCore.Custom** - Base EF Core abstractions
 - [ ] **Whizbang.Data.EFCore.Postgres** - EF Core + PostgreSQL
 - [ ] **Whizbang.Data.EFCore.Postgres.Generators** - EF Core source generators
-- [ ] **Whizbang.Data.EFCore.Custom** - Custom EF Core implementations
+
+#### Internal Packages (NOT published to NuGet - IsPackable=false)
+- **Whizbang.Generators.Shared** - ILMerged into generator packages
+- **Whizbang.Testing** - Empty placeholder
 
 #### Hosting & Transport Packages
 - [ ] **Whizbang.Hosting.Azure.ServiceBus** - Azure Service Bus hosting

.github/workflows/ci.yml

@@ -27,6 +27,7 @@ jobs:
     needs: build
     uses: ./.github/workflows/reusable-test-unit.yml
     with:
+      # Use pre-built artifacts with in-job instrumentation for coverage
       artifact-name: build-${{ github.run_id }}
 
   postgres-integration:

.github/workflows/nuget-pack.yml

@@ -31,10 +31,12 @@ jobs:
     - name: Verify packages created
       run: |
         # List of all expected packages (with SoftwareExtravaganza prefix)
+        # NOTE: Internal packages excluded (IsPackable=false):
+        #   - Whizbang.Generators.Shared (ILMerged into generator packages)
+        #   - Whizbang.Testing (empty placeholder)
         EXPECTED_PACKAGES=(
           "SoftwareExtravaganza.Whizbang.Core"
           "SoftwareExtravaganza.Whizbang.Generators"
-          "SoftwareExtravaganza.Whizbang.Generators.Shared"
           "SoftwareExtravaganza.Whizbang.Data.Postgres"
           "SoftwareExtravaganza.Whizbang.Data.Schema"
           "SoftwareExtravaganza.Whizbang.Data.Dapper.Custom"
@@ -54,7 +56,6 @@ jobs:
           "SoftwareExtravaganza.Whizbang.Transports.HotChocolate.Generators"
           "SoftwareExtravaganza.Whizbang.Hosting.Azure.ServiceBus"
           "SoftwareExtravaganza.Whizbang.Hosting.RabbitMQ"
-          "SoftwareExtravaganza.Whizbang.Testing"
           "SoftwareExtravaganza.Whizbang.Migrate"
           "SoftwareExtravaganza.Whizbang.CLI"
         )

.github/workflows/reusable-quality.yml

@@ -89,36 +89,49 @@ jobs:
           COVERAGE_FILES="${{ steps.check-coverage.outputs.files }}"
           echo "Coverage files to merge: $COVERAGE_FILES"
 
+          # File filters to exclude from coverage reports
+          # Only exclude source-generated files (*.g.cs, .whizbang-generated)
+          # Note: samples/benchmarks/tools are excluded via sonar.coverage.exclusions in SonarCloud
+          FILE_FILTERS="-*.g.cs;-**/.whizbang-generated/*"
+
           # Generate merged report in SonarQube format
-          # Exclude source-generated files from coverage (*.g.cs, .whizbang-generated)
           reportgenerator \
             "-reports:${COVERAGE_FILES}" \
             "-targetdir:coverage/sonarqube" \
             "-reporttypes:SonarQube" \
-            "-filefilters:-*.g.cs;-*/.whizbang-generated/*"
+            "-filefilters:${FILE_FILTERS}"
 
           # Convert absolute paths to relative paths for SonarCloud
+          # Remove CI runner path AND deterministic build prefix (/_/)
           sed -i 's|/home/runner/work/whizbang/whizbang/||g' coverage/sonarqube/SonarQube.xml
+          sed -i 's|/_/||g' coverage/sonarqube/SonarQube.xml
 
           # Debug: show first few lines to verify paths
           echo "=== Merged coverage report (first 30 lines) ==="
           head -30 coverage/sonarqube/SonarQube.xml
 
-          # Also generate text summary for coverage check
-          # Use same exclusions as SonarQube report
+          # Also generate text summary for coverage check (same filters)
           reportgenerator \
             "-reports:${COVERAGE_FILES}" \
             "-targetdir:coverage/summary" \
             "-reporttypes:TextSummary" \
-            "-filefilters:-*.g.cs;-*/.whizbang-generated/*"
+            "-filefilters:${FILE_FILTERS}"
 
       - name: Check Coverage Threshold
         run: |
           # Parse coverage from TextSummary report
           COVERAGE=$(grep "Line coverage:" coverage/summary/Summary.txt | grep -oP '\d+(\.\d+)?(?=%)' | head -1)
           echo "Line coverage: ${COVERAGE}%"
 
-          # Check against threshold (80%)
+          # Fail if coverage could not be parsed
+          if [ -z "$COVERAGE" ]; then
+            echo "::error::Failed to parse coverage percentage from Summary.txt"
+            echo "Summary.txt contents:"
+            cat coverage/summary/Summary.txt
+            exit 1
+          fi
+
+          # Check against threshold
           THRESHOLD=80
           if (( $(echo "$COVERAGE < $THRESHOLD" | bc -l) )); then
             echo "::error::Coverage ${COVERAGE}% is below threshold ${THRESHOLD}%"
@@ -128,15 +141,24 @@ jobs:
           fi
 
       - name: SonarCloud Analysis
-        # Only run on main/develop pushes - PR analysis not supported by current SonarCloud plan
-        if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop')
         env:
           GITHUB_TOKEN: ${{ github.token }}
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          EVENT_NAME: ${{ github.event_name }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          HEAD_REF: ${{ github.head_ref }}
+          BASE_REF: ${{ github.base_ref }}
         run: |
+          # Build PR-specific parameters if this is a pull request
+          PR_PARAMS=""
+          if [ "$EVENT_NAME" = "pull_request" ]; then
+            PR_PARAMS="/d:sonar.pullrequest.key=$PR_NUMBER /d:sonar.pullrequest.branch=$HEAD_REF /d:sonar.pullrequest.base=$BASE_REF"
+          fi
+
           dotnet-sonarscanner begin /k:"whizbang-lib_whizbang" /o:"whizbang-lib" \
             /d:sonar.token="${SONAR_TOKEN}" \
             /d:sonar.host.url="https://sonarcloud.io" \
+            ${PR_PARAMS} \
             /d:sonar.exclusions="**/samples/**,**/benchmarks/**,**/node_modules/**,**/*Generated.cs,**/.whizbang-generated/**" \
             /d:sonar.cpd.exclusions="**/tests/**,**/tools/**,**/samples/**,**/benchmarks/**,src/Whizbang.Generators/**,src/Whizbang.Generators.Shared/**,src/Whizbang.Data.EFCore.Postgres.Generators/**,src/Whizbang.Transports.HotChocolate.Generators/**,src/Whizbang.Transports.FastEndpoints.Generators/**" \
             /d:sonar.coverage.exclusions="**/samples/**,**/benchmarks/**,**/tests/**,**/tools/**,src/Whizbang.Generators/**,src/Whizbang.Generators.Shared/**,src/Whizbang.Data.Schema/**,src/Whizbang.Data.EFCore.Postgres.Generators/**,src/Whizbang.Transports.HotChocolate.Generators/**,src/Whizbang.Transports.FastEndpoints.Generators/**,src/Whizbang.Hosting.Azure.ServiceBus/**,src/Whizbang.Hosting.RabbitMQ/**,src/Whizbang.Data.Dapper.Postgres/**,src/Whizbang.Transports.RabbitMQ/**,src/Whizbang.Data.EFCore.Postgres/**,src/Whizbang.Transports.AzureServiceBus/**,src/Whizbang.Data.Dapper.Sqlite/**,src/Whizbang.Data.Dapper.Custom/**,src/Whizbang.Data.EFCore.Custom/**,src/Whizbang.Data.Postgres/**,src/Whizbang.Testing/**,src/Whizbang.Observability/**,src/Whizbang.SignalR/**" \

.github/workflows/reusable-test-inmemory.yml

@@ -4,7 +4,7 @@ on:
   workflow_call:
     inputs:
       artifact-name:
-        description: 'Build artifact to download (skips build if provided)'
+        description: 'Build artifact to download (enables -NoBuild with coverage)'
         type: string
         required: false
 
@@ -46,13 +46,66 @@ jobs:
         if: inputs.artifact-name == ''
         run: dotnet build --no-restore --configuration Release -maxcpucount:1
 
-      - name: Run InMemory Integration Tests
-        run: pwsh scripts/Run-Tests.ps1 -Mode Full -Coverage -Configuration Release -ProjectFilter "InMemory.Integration"
+      - name: Install dotnet-coverage
+        if: inputs.artifact-name != ''
+        run: dotnet tool install --global dotnet-coverage
+
+      # Instrument Whizbang DLLs in test output dirs (where tests load from)
+      - name: Instrument Whizbang Assemblies for Coverage
+        if: inputs.artifact-name != ''
+        run: |
+          SESSION_ID="coverage-${{ github.run_id }}-inmemory"
+          echo "SESSION_ID=$SESSION_ID" >> "$GITHUB_ENV"
+          echo "=== Instrumenting Whizbang assemblies for coverage ==="
+
+          find . -path "*/bin/Release/net10.0/Whizbang.*.dll" -type f | while read dll; do
+            if [[ "$dll" == *".resources.dll" ]] || [[ "$dll" == */ref/* ]] || [[ "$dll" == *".g.dll" ]]; then
+              continue
+            fi
+            echo "Instrumenting: $dll"
+            dotnet-coverage instrument "$dll" --session-id "$SESSION_ID" || echo "Warning: Could not instrument $dll"
+          done
+
+          echo "=== Instrumentation complete ==="
+
+      - name: Start Coverage Collection Server
+        if: inputs.artifact-name != ''
+        run: |
+          echo "Starting coverage collection server with session: $SESSION_ID"
+          mkdir -p TestResults
+          dotnet-coverage collect --session-id "$SESSION_ID" --server-mode --background \
+            -f cobertura -o TestResults/inmemory.cobertura.xml
+
+      - name: Run InMemory Integration Tests (with pre-built coverage)
+        if: inputs.artifact-name != ''
+        run: pwsh scripts/Run-Tests.ps1 -Mode Integration -Configuration Release -Tag InMemory -NoBuild
+        env:
+          TESTCONTAINERS_RYUK_DISABLED: 'false'
+
+      - name: Run InMemory Integration Tests (with dynamic coverage)
+        if: inputs.artifact-name == ''
+        run: pwsh scripts/Run-Tests.ps1 -Mode Integration -Coverage -Configuration Release -Tag InMemory
         env:
           TESTCONTAINERS_RYUK_DISABLED: 'false'
 
-      - name: Upload Coverage
-        if: success()
+      - name: Shutdown Coverage Collection
+        if: inputs.artifact-name != ''
+        run: |
+          echo "Shutting down coverage collection session: $SESSION_ID"
+          dotnet-coverage shutdown "$SESSION_ID" || true
+          echo "=== Coverage file contents ==="
+          ls -la TestResults/ || true
+
+      - name: Upload Coverage (pre-built)
+        if: success() && inputs.artifact-name != ''
+        uses: actions/upload-artifact@v6
+        with:
+          name: coverage-inmemory
+          path: TestResults/*.cobertura.xml
+          retention-days: 1
+
+      - name: Upload Coverage (dynamic)
+        if: success() && inputs.artifact-name == ''
         uses: actions/upload-artifact@v6
         with:
           name: coverage-inmemory

.github/workflows/reusable-test-postgres.yml

@@ -4,7 +4,7 @@ on:
   workflow_call:
     inputs:
       artifact-name:
-        description: 'Build artifact to download (skips build if provided)'
+        description: 'Build artifact to download (enables -NoBuild with coverage)'
         type: string
         required: false
 
@@ -46,13 +46,66 @@ jobs:
         if: inputs.artifact-name == ''
         run: dotnet build --no-restore --configuration Release -maxcpucount:1
 
-      - name: Run PostgreSQL Integration Tests
-        run: pwsh scripts/Run-Tests.ps1 -Mode Full -Coverage -Configuration Release -ProjectFilter "Postgres"
+      - name: Install dotnet-coverage
+        if: inputs.artifact-name != ''
+        run: dotnet tool install --global dotnet-coverage
+
+      # Instrument Whizbang DLLs in test output dirs (where tests load from)
+      - name: Instrument Whizbang Assemblies for Coverage
+        if: inputs.artifact-name != ''
+        run: |
+          SESSION_ID="coverage-${{ github.run_id }}-postgres"
+          echo "SESSION_ID=$SESSION_ID" >> "$GITHUB_ENV"
+          echo "=== Instrumenting Whizbang assemblies for coverage ==="
+
+          find . -path "*/bin/Release/net10.0/Whizbang.*.dll" -type f | while read dll; do
+            if [[ "$dll" == *".resources.dll" ]] || [[ "$dll" == */ref/* ]] || [[ "$dll" == *".g.dll" ]]; then
+              continue
+            fi
+            echo "Instrumenting: $dll"
+            dotnet-coverage instrument "$dll" --session-id "$SESSION_ID" || echo "Warning: Could not instrument $dll"
+          done
+
+          echo "=== Instrumentation complete ==="
+
+      - name: Start Coverage Collection Server
+        if: inputs.artifact-name != ''
+        run: |
+          echo "Starting coverage collection server with session: $SESSION_ID"
+          mkdir -p TestResults
+          dotnet-coverage collect --session-id "$SESSION_ID" --server-mode --background \
+            -f cobertura -o TestResults/postgres.cobertura.xml
+
+      - name: Run PostgreSQL Integration Tests (with pre-built coverage)
+        if: inputs.artifact-name != ''
+        run: pwsh scripts/Run-Tests.ps1 -Mode Integration -Configuration Release -Tag Postgres -NoBuild
+        env:
+          TESTCONTAINERS_RYUK_DISABLED: 'false'
+
+      - name: Run PostgreSQL Integration Tests (with dynamic coverage)
+        if: inputs.artifact-name == ''
+        run: pwsh scripts/Run-Tests.ps1 -Mode Integration -Coverage -Configuration Release -Tag Postgres
         env:
           TESTCONTAINERS_RYUK_DISABLED: 'false'
 
-      - name: Upload Coverage
-        if: success()
+      - name: Shutdown Coverage Collection
+        if: inputs.artifact-name != ''
+        run: |
+          echo "Shutting down coverage collection session: $SESSION_ID"
+          dotnet-coverage shutdown "$SESSION_ID" || true
+          echo "=== Coverage file contents ==="
+          ls -la TestResults/ || true
+
+      - name: Upload Coverage (pre-built)
+        if: success() && inputs.artifact-name != ''
+        uses: actions/upload-artifact@v6
+        with:
+          name: coverage-postgres
+          path: TestResults/*.cobertura.xml
+          retention-days: 1
+
+      - name: Upload Coverage (dynamic)
+        if: success() && inputs.artifact-name == ''
         uses: actions/upload-artifact@v6
         with:
           name: coverage-postgres