Part X: Roslyn Analyzers & Quality Gates📋

// Scenario: Feature exists but no spec interface references it
error REQ100: UserRolesFeature has 3 acceptance criteria but no ISpec
              interface references it via [ForRequirement(typeof(UserRolesFeature))]
              Location: MyApp.Requirements/Features/UserRolesFeature.cs(12,0)
              Fix: Create IUserRolesSpec with [ForRequirement(typeof(UserRolesFeature))]

// Scenario: Feature has spec, but one AC is not covered by a spec method
error REQ101: UserRolesFeature.RoleChangeTakesEffectImmediately has no matching
              spec method with [ForRequirement(typeof(UserRolesFeature),
              nameof(UserRolesFeature.RoleChangeTakesEffectImmediately))]
              Location: MyApp.Requirements/Features/UserRolesFeature.cs(28,0)
              Fix: Add a method to IUserRolesSpec with the matching [ForRequirement]

// Scenario: Story has ACs but no spec (acceptable in some projects)
warning REQ102: JwtRefreshStory has 2 acceptance criteria but no specification
                interface references it. Consider creating IJwtRefreshSpec.
                Location: MyApp.Requirements/Stories/JwtRefreshStory.cs(5,0)

// Scenario: Feature fully specified
info REQ103: UserRolesFeature: all 3 acceptance criteria have matching spec methods
             (AdminCanAssignRoles, ViewerHasReadOnlyAccess,
              RoleChangeTakesEffectImmediately)

// Scenario: Spec interface exists but no class implements it
error REQ200: IUserRolesSpec is not implemented by any class in the compilation.
              IUserRolesSpec is linked to UserRolesFeature (3 ACs).
              Location: MyApp.Specifications/IUserRolesSpec.cs(8,0)
              Fix: Create a class that implements IUserRolesSpec

// Scenario: Class implements spec but forgot class-level attribute
warning REQ201: AuthorizationService implements IUserRolesSpec but is missing
                [ForRequirement(typeof(UserRolesFeature))] on the class declaration.
                The implementation works, but IDE navigation and traceability
                reports will not discover it.
                Location: MyApp.Domain/Auth/AuthorizationService.cs(10,0)
                Fix: Add [ForRequirement(typeof(UserRolesFeature))] to the class

// Scenario: Class has class-level attribute but method-level is missing
warning REQ202: AuthorizationService.VerifyImmediateRoleEffect implements
                IUserRolesSpec.VerifyImmediateRoleEffect but is missing
                [ForRequirement(typeof(UserRolesFeature),
                nameof(UserRolesFeature.RoleChangeTakesEffectImmediately))].
                Location: MyApp.Domain/Auth/AuthorizationService.cs(45,0)
                Fix: Add method-level [ForRequirement] for IDE navigation

// Scenario: Full coverage
info REQ203: IUserRolesSpec: fully implemented by AuthorizationService
             with complete [ForRequirement] coverage on class and all 3 methods.

// Scenario: Feature has no test class at all
error REQ300: UserRolesFeature has 3 acceptance criteria but no test class
              with [TestsFor(typeof(UserRolesFeature))].
              Location: MyApp.Requirements/Features/UserRolesFeature.cs(12,0)
              Fix: Create a test class with [TestsFor(typeof(UserRolesFeature))]

// Scenario: Test class exists but one AC has no [Verifies] test
warning REQ301: UserRolesFeature.RoleChangeTakesEffectImmediately has no test
                method with [Verifies(typeof(UserRolesFeature),
                nameof(UserRolesFeature.RoleChangeTakesEffectImmediately))].
                Location: MyApp.Requirements/Features/UserRolesFeature.cs(28,0)
                Fix: Add a test method with the matching [Verifies] attribute

// Scenario: Test references a deleted AC (stale reference)
error REQ302: UserRolesTests.OldTest_DeletedACStillWorks has
              [Verifies(typeof(UserRolesFeature), "DeletedAC")]
              but UserRolesFeature has no method named "DeletedAC".
              This test verifies a criterion that no longer exists.
              Location: MyApp.Tests/Auth/UserRolesTests.cs(88,0)
              Fix: Remove or update the stale [Verifies] attribute

// Scenario: Full coverage
info REQ303: UserRolesFeature: all 3 acceptance criteria have [Verifies] tests
             AdminCanAssignRoles: 2 tests
             ViewerHasReadOnlyAccess: 2 tests
             RoleChangeTakesEffectImmediately: 1 test

dotnet quality-gates check \
    --trx TestResults/*.trx \
    --coverage TestResults/**/coverage.cobertura.xml \
    --traceability obj/TraceabilityMatrix.g.cs \
    --min-pass-rate 100 \
    --min-coverage 80 \
    --max-duration 5000 \
    --fuzz-inputs 500

REQ400 PASS: UserRolesFeature.AdminCanAssignRoles
             2/2 [Verifies] tests passed
REQ400 PASS: UserRolesFeature.ViewerHasReadOnlyAccess
             2/2 [Verifies] tests passed
REQ400 FAIL: JwtRefreshStory.TokensExpireAfterOneHour
             1/1 [Verifies] test FAILED
             -> JwtRefreshTests.Token_expires_after_one_hour: Assert.That failed

REQ401 PASS: UserRolesFeature -- 3/3 ACs have passing tests
REQ401 FAIL: JwtRefreshStory -- 0/2 ACs have passing tests
             Missing: TokensExpireAfterOneHour, RefreshExtendsBySevenDays

REQ402 PASS: AuthorizationService.AssignRole
             94% line coverage (threshold: 80%)
REQ402 PASS: AuthorizationService.EnforceReadOnlyAccess
             88% line coverage (threshold: 80%)
REQ402 FAIL: AuthorizationService.VerifyImmediateRoleEffect
             62% line coverage (threshold: 80%)
             -> Lines 45-52 not covered (cache invalidation error path)

REQ403 PASS: Admin_can_assign_role_to_another_user          12ms (max: 5000ms)
REQ403 PASS: Non_admin_cannot_assign_roles                   8ms (max: 5000ms)
REQ403 PASS: Viewer_cannot_write                             6ms (max: 5000ms)
REQ403 PASS: Viewer_can_read                                 5ms (max: 5000ms)
REQ403 FAIL: Role_change_invalidates_cache_immediately    6200ms (max: 5000ms)
             -> Test exceeds duration budget by 1200ms

REQ404 PASS: Admin_can_assign_role_to_another_user       3/3 runs passed
REQ404 PASS: Non_admin_cannot_assign_roles               3/3 runs passed
REQ404 FAIL: Role_change_invalidates_cache_immediately   2/3 runs passed (FLAKY)
             -> Run 1: PASS (14ms), Run 2: FAIL (timeout), Run 3: PASS (12ms)
             -> Flaky tests cannot verify acceptance criteria reliably

// AC signature:
public abstract AcceptanceCriterionResult AdminCanAssignRoles(
    UserId actingUser, UserId targetUser, RoleId role);

// The tool knows:
//   - actingUser is UserId(Guid, string, string, Email)
//   - targetUser is UserId(Guid, string, string, Email)
//   - role is RoleId(string)
//
// It generates 500 inputs including:
//   - Guid.Empty for all Guid fields
//   - null strings (where nullable)
//   - empty strings
//   - extremely long strings (10,000+ characters)
//   - Unicode edge cases (RTL, zero-width, emoji, surrogate pairs)
//   - Duplicate actingUser == targetUser
//   - Same UserId assigned to both parameters
//   - RoleId with whitespace, special characters

REQ405 PASS: UserRolesFeature.AdminCanAssignRoles
             500 inputs generated, 0 crashes
             488 -> Result.Success (valid inputs)
             12  -> Result.Failure (correctly rejected: null role, empty Guid, etc.)

REQ405 PASS: UserRolesFeature.ViewerHasReadOnlyAccess
             500 inputs generated, 0 crashes
             492 -> Result.Success
             8   -> Result.Failure

REQ405 FAIL: UserRolesFeature.RoleChangeTakesEffectImmediately
             500 inputs generated, 1 CRASH
             Input: UserId(Guid.Empty, "", "", Email("")), RoleId(""),  RoleId("")
             Exception: NullReferenceException at
               AuthorizationService.VerifyImmediateRoleEffect:L47
               _cache.Invalidate(user.Id) -- user.Id.Value is Guid.Empty
             -> Implementation must handle empty/default inputs gracefully

$ dotnet quality-gates check --trx results.trx --coverage coverage.xml \
    --min-pass-rate 100 --min-coverage 80 --max-duration 5000 --fuzz-inputs 500

Quality Gates Report
====================

FEATURE: UserRolesFeature (3 ACs, 5 tests)
  [REQ400] Pass Rate
    AdminCanAssignRoles:                 2/2 passed    PASS
    ViewerHasReadOnlyAccess:             2/2 passed    PASS
    RoleChangeTakesEffectImmediately:    1/1 passed    PASS

  [REQ401] AC Coverage
    AdminCanAssignRoles:                 covered       PASS
    ViewerHasReadOnlyAccess:             covered       PASS
    RoleChangeTakesEffectImmediately:    covered       PASS

  [REQ402] Code Coverage
    AuthorizationService.AssignRole:              94%  PASS (>= 80%)
    AuthorizationService.EnforceReadOnlyAccess:   88%  PASS (>= 80%)
    AuthorizationService.VerifyImmediateRoleEffect: 62% FAIL (< 80%)
      -> Lines 45-52 not covered

  [REQ403] Duration
    Admin_can_assign_role:                12ms          PASS (< 5000ms)
    Non_admin_cannot_assign_roles:         8ms          PASS
    Viewer_cannot_write:                   6ms          PASS
    Viewer_can_read:                       5ms          PASS
    Role_change_invalidates_cache:        14ms          PASS

  [REQ405] Fuzz Testing
    AdminCanAssignRoles:        500 inputs, 0 crashes   PASS
    ViewerHasReadOnlyAccess:    500 inputs, 0 crashes   PASS
    RoleChangeTakesEffectImmediately: 500 inputs, 1 CRASH  FAIL
      -> NullReferenceException with empty RoleId

STORY: JwtRefreshStory (2 ACs, 0 tests)
  [REQ400] Pass Rate:    N/A (no tests)
  [REQ401] AC Coverage:  0/2 ACs covered               FAIL
    Missing: TokensExpireAfterOneHour, RefreshExtendsBySevenDays

Summary
-------
UserRolesFeature:  4/5 gates passed (code coverage FAIL, fuzz FAIL)
JwtRefreshStory:   0/1 gates passed (AC coverage FAIL)
Overall: FAIL (exit code 1)

# .editorconfig
[*.cs]

# ── REQ1xx: Requirement → Specification ──────────────────
# Missing spec for feature: always an error
dotnet_diagnostic.REQ100.severity = error
# Missing spec method for AC: always an error
dotnet_diagnostic.REQ101.severity = error
# Missing spec for story: warning (not all stories need specs)
dotnet_diagnostic.REQ102.severity = warning
# Fully specified: informational
dotnet_diagnostic.REQ103.severity = suggestion

# ── REQ2xx: Specification → Implementation ───────────────
# Spec with no implementation: error
dotnet_diagnostic.REQ200.severity = error
# Missing class-level [ForRequirement]: warning (still works)
dotnet_diagnostic.REQ201.severity = warning
# Missing method-level [ForRequirement]: suggestion
dotnet_diagnostic.REQ202.severity = suggestion
# Fully implemented: informational
dotnet_diagnostic.REQ203.severity = suggestion

# ── REQ3xx: Implementation → Test ────────────────────────
# Feature with no tests: warning in dev, error in CI
dotnet_diagnostic.REQ300.severity = warning
# AC with no [Verifies] test: warning
dotnet_diagnostic.REQ301.severity = warning
# Stale [Verifies] reference: always an error (dead code)
dotnet_diagnostic.REQ302.severity = error
# Fully tested: informational
dotnet_diagnostic.REQ303.severity = suggestion

<!-- Directory.Build.props -->
<Project>
  <PropertyGroup Condition="'$(CI)' == 'true'">
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <WarningsAsErrors>
      REQ100;REQ101;REQ200;REQ300;REQ301;REQ302
    </WarningsAsErrors>
  </PropertyGroup>

  <!-- Quality gates thresholds -->
  <PropertyGroup>
    <RequirementMinPassRate>100</RequirementMinPassRate>
    <RequirementMinCoverage>80</RequirementMinCoverage>
    <RequirementMaxTestDuration>5000</RequirementMaxTestDuration>
    <RequirementFuzzInputs>500</RequirementFuzzInputs>
  </PropertyGroup>
</Project>

<!-- MyApp.Tests.csproj -->
<Target Name="RequirementQualityGates" AfterTargets="VSTest">
  <Exec Command="dotnet quality-gates check
    --trx $(TestResultsDir)/*.trx
    --coverage $(CoverageResultsDir)/coverage.cobertura.xml
    --traceability $(IntermediateOutputPath)/TraceabilityMatrix.g.cs
    --min-pass-rate $(RequirementMinPassRate)
    --min-coverage $(RequirementMinCoverage)
    --max-duration $(RequirementMaxTestDuration)
    --fuzz-inputs $(RequirementFuzzInputs)"
    ConsoleToMsBuild="true" />
</Target>

# .github/workflows/build.yml
name: Build & Quality Gates

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  DOTNET_VERSION: '10.0.x'
  CI: true  # Enables strict analyzer mode via Directory.Build.props

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: ${{ env.DOTNET_VERSION }}

      # Step 1: Build with analyzers (REQ1xx, REQ2xx, REQ3xx)
      # CI=true makes warnings into errors via Directory.Build.props
      - name: Build (Roslyn Analyzers)
        run: dotnet build --configuration Release --warnaserror

      # Step 2: Run tests with coverage collection
      - name: Test
        run: |
          dotnet test --configuration Release \
            --no-build \
            --collect:"XPlat Code Coverage" \
            --logger:trx \
            --results-directory TestResults

      # Step 3: Quality gates (REQ4xx)
      - name: Quality Gates
        run: |
          dotnet quality-gates check \
            --trx TestResults/*.trx \
            --coverage TestResults/**/coverage.cobertura.xml \
            --min-pass-rate 100 \
            --min-coverage 80 \
            --max-duration 5000 \
            --fuzz-inputs 500

// Simplified structure of the REQ1xx analyzer
[DiagnosticAnalyzer(LanguageNames.CSharp)]
public class RequirementSpecificationAnalyzer : DiagnosticAnalyzer
{
    // Diagnostic descriptors
    private static readonly DiagnosticDescriptor REQ100 = new(
        id: "REQ100",
        title: "Feature has no specification",
        messageFormat: "{0} has {1} acceptance criteria but no specification " +
                       "interface references it via [ForRequirement(typeof({0}))]",
        category: "Requirements",
        defaultSeverity: DiagnosticSeverity.Error,
        isEnabledByDefault: true,
        helpLinkUri: "https://cmf.dev/analyzers/REQ100");

    private static readonly DiagnosticDescriptor REQ101 = new(
        id: "REQ101",
        title: "Acceptance criterion has no spec method",
        messageFormat: "{0}.{1} has no matching spec method with " +
                       "[ForRequirement(typeof({0}), nameof({0}.{1}))]",
        category: "Requirements",
        defaultSeverity: DiagnosticSeverity.Error,
        isEnabledByDefault: true,
        helpLinkUri: "https://cmf.dev/analyzers/REQ101");

    // ... REQ102, REQ103

    public override ImmutableArray<DiagnosticDescriptor>
        SupportedDiagnostics => ImmutableArray.Create(
            REQ100, REQ101, REQ102, REQ103);

    public override void Initialize(AnalysisContext context)
    {
        context.ConfigureGeneratedCodeAnalysis(
            GeneratedCodeAnalysisFlags.None);
        context.EnableConcurrentExecution();
        context.RegisterCompilationAction(AnalyzeCompilation);
    }

    private void AnalyzeCompilation(CompilationAnalysisContext ctx)
    {
        var compilation = ctx.Compilation;

        // 1. Find all RequirementMetadata subtypes with abstract AC methods
        var requirements = FindRequirementTypes(compilation);

        // 2. Find all interfaces with [ForRequirement]
        var specifications = FindSpecInterfaces(compilation);

        // 3. Cross-reference and emit diagnostics
        foreach (var req in requirements)
        {
            var matchingSpec = specifications
                .FirstOrDefault(s => s.ForRequirementType == req.Type);

            if (matchingSpec is null)
            {
                ctx.ReportDiagnostic(Diagnostic.Create(
                    REQ100,
                    req.Location,
                    req.TypeName,
                    req.AcceptanceCriteria.Length));
                continue;
            }

            foreach (var ac in req.AcceptanceCriteria)
            {
                var hasSpecMethod = matchingSpec.Methods
                    .Any(m => m.ForRequirementAC == ac.Name);

                if (!hasSpecMethod)
                {
                    ctx.ReportDiagnostic(Diagnostic.Create(
                        REQ101,
                        ac.Location,
                        req.TypeName,
                        ac.Name));
                }
            }
        }
    }
}

info: RequirementComplianceCheck[0]
      ── Requirement Compliance Report ──
info: RequirementComplianceCheck[0]
      PlatformScalabilityEpic: 0 direct ACs (epic)
info: RequirementComplianceCheck[0]
      UserRolesFeature: 3/3 ACs covered
        AdminCanAssignRoles: 2 tests, 94% coverage
        ViewerHasReadOnlyAccess: 2 tests, 88% coverage
        RoleChangeTakesEffectImmediately: 1 test, 62% coverage [BELOW THRESHOLD]
warn: RequirementComplianceCheck[0]
      JwtRefreshStory: 0/2 ACs covered
        Missing: TokensExpireAfterOneHour, RefreshExtendsBySevenDays
info: RequirementComplianceCheck[0]
      ── Summary: 3/5 ACs covered across 2 requirements ──