personaEngine2/tests/Unit/SummaryInterval.Tests.ps1

#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '5.0.0' }

<#
    FR-019, FR-020: interim summaries appear at the configured interval, an interval of
    0 suppresses them, and a final summary appears in every case.

    The zero case is the one that matters. Suppressing interim output is a reasonable
    thing to want on a large run; suppressing the final summary too would leave an
    operator with per-user lines and no totals.
#>

BeforeAll {
    $repoRoot = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
    . (Join-Path $repoRoot 'tests/TestHelpers.ps1')
    foreach ($file in (Get-PersonaSourceFile -RepoRoot $repoRoot)) { . $file }

    $script:target = 'extension_<EXTENSION-APP-ID>_<PERSONA>'
    $script:population = @(New-TestPopulation -Count 20 -TargetAttribute $target)
}

Describe 'Summary interval semantics (FR-019, FR-020)' {

    BeforeEach {
        Mock Get-PersonaUsers { $script:population }
        Mock Write-Host { }
        Mock Write-PersonaSummary { }
    }

    It 'emits a final summary and no interim summaries when the interval is 0' {
        $config = New-TestRuntimeConfiguration -TargetAttribute $target -SummaryInterval 0

        $null = Invoke-PersonaEngineRun -Configuration $config -TargetAttribute $target -Context (New-TestAuditContext)

        Should -Invoke Write-PersonaSummary -Times 1 -Exactly
        Should -Invoke Write-PersonaSummary -Times 1 -Exactly -ParameterFilter { $SummaryType -eq 'Final' }
        Should -Invoke Write-PersonaSummary -Times 0 -Exactly -ParameterFilter { $SummaryType -eq 'Interim' }
    }

    It 'emits an interim summary at each interval boundary' {
        $config = New-TestRuntimeConfiguration -TargetAttribute $target -SummaryInterval 5

        $null = Invoke-PersonaEngineRun -Configuration $config -TargetAttribute $target -Context (New-TestAuditContext)

        # 20 users at an interval of 5: boundaries at 5, 10, 15, 20.
        Should -Invoke Write-PersonaSummary -Times 4 -Exactly -ParameterFilter { $SummaryType -eq 'Interim' }
        Should -Invoke Write-PersonaSummary -Times 1 -Exactly -ParameterFilter { $SummaryType -eq 'Final' }
    }

    It 'honours the documented default of 25' {
        # 20 users at the default interval: no boundary reached, so only the final
        # summary appears. This is the shape of a small run.
        $config = New-TestRuntimeConfiguration -TargetAttribute $target -SummaryInterval 25

        $null = Invoke-PersonaEngineRun -Configuration $config -TargetAttribute $target -Context (New-TestAuditContext)

        Should -Invoke Write-PersonaSummary -Times 0 -Exactly -ParameterFilter { $SummaryType -eq 'Interim' }
        Should -Invoke Write-PersonaSummary -Times 1 -Exactly -ParameterFilter { $SummaryType -eq 'Final' }
    }

    It 'emits one interim summary per user at an interval of 1' {
        $config = New-TestRuntimeConfiguration -TargetAttribute $target -SummaryInterval 1

        $null = Invoke-PersonaEngineRun -Configuration $config -TargetAttribute $target -Context (New-TestAuditContext)

        Should -Invoke Write-PersonaSummary -Times 20 -Exactly -ParameterFilter { $SummaryType -eq 'Interim' }
    }

    It 'emits a final summary even when the population is empty' {
        Mock Get-PersonaUsers { @() }

        $config = New-TestRuntimeConfiguration -TargetAttribute $target -SummaryInterval 5
        $outcome = Invoke-PersonaEngineRun -Configuration $config -TargetAttribute $target -Context (New-TestAuditContext)

        Should -Invoke Write-PersonaSummary -Times 1 -Exactly -ParameterFilter { $SummaryType -eq 'Final' }
        $outcome.Counters.Processed | Should -Be 0
    }
}

Describe 'Summary content (FR-019)' {

    It 'lists every rule, including disabled ones and those with no matches' {
        # A rule that never fired and a rule that is not in the configuration look
        # identical if zero-match rules are omitted, and that difference is exactly
        # what an operator investigating a missing classification needs.
        $rules = @(
            [pscustomobject]@{ id = 'RULE-0010-OFF'; name = 'Disabled rule'; enabled = $false; priority = 10; persona = 'Guest'
                match = [pscustomobject]@{ operator = 'all'; conditions = @([pscustomobject]@{ type = 'property'; property = 'UserType'; operator = 'equals'; value = 'Guest' }) } }
            [pscustomobject]@{ id = 'RULE-0020-NEVER'; name = 'Never matches'; enabled = $true; priority = 20; persona = 'Tier0-Admin'
                match = [pscustomobject]@{ operator = 'all'; conditions = @([pscustomobject]@{ type = 'property'; property = 'Department'; operator = 'equals'; value = 'NoSuchDepartment' }) } }
            [pscustomobject]@{ id = 'RULE-0900-EMPLOYEE'; name = 'Employees'; enabled = $true; priority = 900; persona = 'Employee'
                match = [pscustomobject]@{ operator = 'all'; conditions = @([pscustomobject]@{ type = 'property'; property = 'Department'; operator = 'isNotNull' }) } }
        )

        $counters = New-PersonaRunCounter -Rules $rules

        $counters.RuleCounts.Count | Should -Be 3
        ($counters.RuleCounts | Where-Object RuleId -EQ 'RULE-0010-OFF').Enabled | Should -BeFalse
        ($counters.RuleCounts | Where-Object RuleId -EQ 'RULE-0020-NEVER').Matches | Should -Be 0
    }

    It 'orders rules by priority so the table reads in evaluation order' {
        $rules = @(
            [pscustomobject]@{ id = 'C'; name = 'C'; enabled = $true; priority = 900; persona = 'Employee'; match = $null }
            [pscustomobject]@{ id = 'A'; name = 'A'; enabled = $true; priority = 10; persona = 'Guest'; match = $null }
            [pscustomobject]@{ id = 'B'; name = 'B'; enabled = $true; priority = 30; persona = 'Tier0-Admin'; match = $null }
        )

        $counters = New-PersonaRunCounter -Rules $rules

        ($counters.RuleCounts | ForEach-Object RuleId) -join ',' | Should -Be 'A,B,C'
    }

    It 'increments the matched rule and no other' {
        $rules = @(
            [pscustomobject]@{ id = 'RULE-A'; name = 'A'; enabled = $true; priority = 10; persona = 'Guest'; match = $null }
            [pscustomobject]@{ id = 'RULE-B'; name = 'B'; enabled = $true; priority = 20; persona = 'Employee'; match = $null }
        )

        $counters = New-PersonaRunCounter -Rules $rules

        Add-PersonaRunResult -Counters $counters -Result ([pscustomobject]@{
                Outcome = 'Matched'; MatchedRuleId = 'RULE-B'; Action = 'Unchanged' })

        ($counters.RuleCounts | Where-Object RuleId -EQ 'RULE-A').Matches | Should -Be 0
        ($counters.RuleCounts | Where-Object RuleId -EQ 'RULE-B').Matches | Should -Be 1
    }
}