personaEngine2/tests/Unit/RecordContracts.Tests.ps1

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

BeforeAll {
    $repoRoot = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
    . (Join-Path $repoRoot 'src/Normalization/New-PersonaMembershipRecord.ps1')
    . (Join-Path $repoRoot 'src/Normalization/New-PersonaUserRecord.ps1')
    . (Join-Path $repoRoot 'src/Configuration/New-PersonaValidationFinding.ps1')
}

Describe 'New-PersonaMembershipRecord' {

    Context 'retrieval flags default to unretrieved' {

        It 'defaults every facet to $false so an unset flag means unknown, never "not a member"' {
            # The safety-critical default. If any of these flip, a failed group
            # lookup satisfies notMemberOf and privileged accounts get misclassified.
            $record = New-PersonaMembershipRecord
            $record.DirectRetrieved | Should -BeFalse
            $record.TransitiveRetrieved | Should -BeFalse
            $record.RolesRetrieved | Should -BeFalse
        }

        It 'sets a facet only when explicitly requested' {
            $record = New-PersonaMembershipRecord -DirectRetrieved
            $record.DirectRetrieved | Should -BeTrue
            $record.TransitiveRetrieved | Should -BeFalse
        }

        It 'AllRetrieved sets every facet' {
            $record = New-PersonaMembershipRecord -AllRetrieved
            $record.DirectRetrieved | Should -BeTrue
            $record.TransitiveRetrieved | Should -BeTrue
            $record.RolesRetrieved | Should -BeTrue
        }
    }

    Context 'independent facets (RE-007)' {

        It 'carries direct and transitive membership simultaneously' {
            # The reason this record has three facets rather than one mode: a rule
            # set may ask for direct membership in one rule and transitive in
            # another, and a single-mode record cannot answer both.
            $record = New-PersonaMembershipRecord `
                -DirectGroupObjectIds @('00000000-0000-0000-0000-0000000000a0') `
                -TransitiveGroupObjectIds @('00000000-0000-0000-0000-0000000000a0', '00000000-0000-0000-0000-0000000000b0') `
                -AllRetrieved

            $record.DirectGroupObjectIds | Should -HaveCount 1
            $record.TransitiveGroupObjectIds | Should -HaveCount 2
        }

        It 'contains a failure to the facet that failed' {
            # A transitive lookup that times out must not make direct-membership
            # conditions unevaluable — otherwise one slow endpoint becomes a
            # tenant-wide outage.
            $record = New-PersonaMembershipRecord -DirectRetrieved -RolesRetrieved -TransitiveFailureReason 'Graph 503'

            $record.DirectRetrieved | Should -BeTrue
            $record.RolesRetrieved | Should -BeTrue
            $record.TransitiveRetrieved | Should -BeFalse
            $record.TransitiveFailureReason | Should -Be 'Graph 503'
        }
    }

    Context 'shape' {

        It 'always returns arrays, never $null, for the identifier collections' {
            $record = New-PersonaMembershipRecord -AllRetrieved
            , $record.DirectGroupObjectIds | Should -BeOfType [System.Array]
            , $record.TransitiveGroupObjectIds | Should -BeOfType [System.Array]
            , $record.DirectoryRoleIds | Should -BeOfType [System.Array]
        }

        It 'refuses to be both retrieved and failed on the same facet' {
            { New-PersonaMembershipRecord -DirectRetrieved -DirectFailureReason 'boom' } |
                Should -Throw '*cannot be both*'
        }

        It 'refuses AllRetrieved alongside any failure reason' {
            { New-PersonaMembershipRecord -AllRetrieved -RolesFailureReason 'boom' } |
                Should -Throw '*cannot be both*'
        }
    }
}

Describe 'New-PersonaUserRecord' {

    Context 'required identity fields' {

        It 'requires a non-empty AccountObjectId' {
            { New-PersonaUserRecord -AccountObjectId '' -UserPrincipalName 'a@example.invalid' } |
                Should -Throw
        }

        It 'requires a non-empty UserPrincipalName' {
            { New-PersonaUserRecord -AccountObjectId '00000000-0000-0000-0000-000000000101' -UserPrincipalName '' } |
                Should -Throw
        }
    }

    Context 'property bag' {

        BeforeAll {
            $script:record = New-PersonaUserRecord `
                -AccountObjectId '00000000-0000-0000-0000-000000000101' `
                -UserPrincipalName 'alex.employee@example.invalid' `
                -UserType 'Member' `
                -Properties @{ Department = 'Finance'; CompanyName = $null }
        }

        It 'looks up properties case-insensitively (RE-006)' {
            $record.Properties['department'] | Should -Be 'Finance'
            $record.Properties['DEPARTMENT'] | Should -Be 'Finance'
        }

        It 'returns $null for an absent property rather than throwing (FR-012)' {
            $record.Properties['NoSuchProperty'] | Should -BeNullOrEmpty
        }

        It 'preserves an explicit null value' {
            $record.Properties['CompanyName'] | Should -BeNullOrEmpty
        }

        It 'exposes intrinsic fields as addressable properties' {
            $record.Properties['UserPrincipalName'] | Should -Be 'alex.employee@example.invalid'
            $record.Properties['UserType'] | Should -Be 'Member'
            $record.Properties['AccountEnabled'] | Should -Be $true
        }

        It 'lets an explicit property override an intrinsic default' {
            $overridden = New-PersonaUserRecord `
                -AccountObjectId '00000000-0000-0000-0000-000000000101' `
                -UserPrincipalName 'a@example.invalid' `
                -Properties @{ UserType = 'Overridden' }
            $overridden.Properties['UserType'] | Should -Be 'Overridden'
        }
    }

    Context 'membership default' {

        It 'never leaves Membership null' {
            $record = New-PersonaUserRecord -AccountObjectId '00000000-0000-0000-0000-000000000101' -UserPrincipalName 'a@example.invalid'
            $record.Membership | Should -Not -BeNullOrEmpty
        }

        It 'defaults to a fully unretrieved record so membership conditions yield Unknown' {
            # An absent lookup is unknown, never "member of nothing". A rule set
            # with no membership conditions never consults this; one that does must
            # get EvaluationError rather than a fabricated non-match.
            $record = New-PersonaUserRecord -AccountObjectId '00000000-0000-0000-0000-000000000101' -UserPrincipalName 'a@example.invalid'
            $record.Membership.DirectRetrieved | Should -BeFalse
            $record.Membership.TransitiveRetrieved | Should -BeFalse
            $record.Membership.RolesRetrieved | Should -BeFalse
        }
    }
}

Describe 'New-PersonaValidationFinding' {

    It 'derives the layer from the code namespace' {
        (New-PersonaValidationFinding -Severity Error -Code 'PE-SEM-001' -Location 'rules[0]' -Description 'd' -SuggestedResolution 'r').Layer |
            Should -Be 'Semantic'
        (New-PersonaValidationFinding -Severity Warning -Code 'PE-SAF-001' -Location 'engine' -Description 'd' -SuggestedResolution 'r').Layer |
            Should -Be 'Safety'
    }

    It 'rejects a malformed finding code' {
        { New-PersonaValidationFinding -Severity Error -Code 'BAD-001' -Location 'x' -Description 'd' -SuggestedResolution 'r' } |
            Should -Throw
    }

    It 'requires a suggested resolution' {
        { New-PersonaValidationFinding -Severity Error -Code 'PE-SEM-001' -Location 'x' -Description 'd' -SuggestedResolution '' } |
            Should -Throw
    }

    It 'rejects an unrecognized severity' {
        { New-PersonaValidationFinding -Severity Critical -Code 'PE-SEM-001' -Location 'x' -Description 'd' -SuggestedResolution 'r' } |
            Should -Throw
    }
}