personaEngine2/tests/Configuration/LayerOrdering.Tests.ps1

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

<#
    VR-001: the four layers run in order and stop at the first that produces errors.

    The reason is signal, not speed. A document missing a required section produces a
    cascade of consequent semantic errors, and the author then has to guess which one
    is the cause. Stopping at the structural failure reports the one thing that is
    actually wrong.
#>

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

    $script:schema = Join-Path $repoRoot 'config/persona-engine.schema.json'
    $script:scratch = Join-Path ([System.IO.Path]::GetTempPath()) ("pe-layers-{0}" -f [guid]::NewGuid().ToString('N'))
    $null = New-Item -ItemType Directory -Path $script:scratch -Force
}

AfterAll {
    Remove-Item -LiteralPath $script:scratch -Recurse -Force -ErrorAction SilentlyContinue
}

Describe 'Layer ordering and fail-fast (VR-001)' {

    It 'stops at layer 1 for malformed JSON' {
        $path = Join-Path $script:scratch 'malformed.json'
        Set-Content -LiteralPath $path -Value '{ "configVersion": "1.0.0", ' -Encoding utf8NoBOM

        $result = Test-PersonaConfiguration -Path $path -SchemaPath $script:schema

        $result.IsValid | Should -BeFalse
        $result.StoppedAtLayer | Should -Be 'Syntax'
        $result.Findings.Code | Should -Contain 'PE-SYN-003'
    }

    It 'reports a missing file at layer 1 without attempting to parse it' {
        $result = Test-PersonaConfiguration -Path (Join-Path $script:scratch 'absent.json') -SchemaPath $script:schema

        $result.StoppedAtLayer | Should -Be 'Syntax'
        $result.Findings.Code | Should -Contain 'PE-SYN-001'
    }

    It 'stops at layer 2 for a structurally invalid document, before semantic checks run' {
        # The document below also has a semantic defect - a duplicate rule ID - which
        # must NOT appear, because layer 3 never ran.
        $document = New-TestConfigurationDocument
        $document.rules[1].id = $document.rules[0].id
        $document.engine.Remove('approvedWritableAttributes')

        $path = Save-TestConfiguration -Document $document -Directory $script:scratch
        $result = Test-PersonaConfiguration -Path $path -SchemaPath $script:schema

        $result.IsValid | Should -BeFalse
        $result.StoppedAtLayer | Should -Be 'Schema'
        $result.Findings.Code | Should -Contain 'PE-SCH-001'
        $result.Findings.Code | Should -Not -Contain 'PE-SEM-001'
    }

    It 'stops at layer 3 for a semantic error, before safety checks run' {
        $document = New-TestConfigurationDocument
        $document.rules[1].id = $document.rules[0].id

        $path = Save-TestConfiguration -Document $document -Directory $script:scratch
        $result = Test-PersonaConfiguration -Path $path -SchemaPath $script:schema

        $result.StoppedAtLayer | Should -Be 'Semantic'
        $result.Findings.Code | Should -Contain 'PE-SEM-001'
        @($result.Findings | Where-Object Layer -EQ 'Safety') | Should -BeNullOrEmpty
    }

    It 'reaches layer 4 when layers 1 to 3 are clean' {
        $path = Save-TestConfiguration -Document (New-TestConfigurationDocument) -Directory $script:scratch
        $result = Test-PersonaConfiguration -Path $path -SchemaPath $script:schema

        $result.IsValid | Should -BeTrue
        $result.StoppedAtLayer | Should -BeNullOrEmpty
        @($result.Findings | Where-Object Layer -EQ 'Safety') | Should -Not -BeNullOrEmpty
    }

    It 'skips layer 4 on request without claiming it passed' {
        $path = Save-TestConfiguration -Document (New-TestConfigurationDocument) -Directory $script:scratch
        $result = Test-PersonaConfiguration -Path $path -SchemaPath $script:schema -SkipSafety

        @($result.Findings | Where-Object Layer -EQ 'Safety') | Should -BeNullOrEmpty
    }
}

Describe 'A schema that cannot be used is never reported as a pass (V-5a)' {

    It 'flags an unparseable schema rather than trusting the $true return value' {
        # Test-Json returns $true here. Trusting it would validate every configuration
        # against a schema that never ran.
        $brokenSchema = Join-Path $script:scratch 'broken-schema.json'
        Set-Content -LiteralPath $brokenSchema -Value '{ not json' -Encoding utf8NoBOM

        $path = Save-TestConfiguration -Document (New-TestConfigurationDocument) -Directory $script:scratch
        $result = Test-PersonaConfiguration -Path $path -SchemaPath $brokenSchema

        $result.IsValid | Should -BeFalse
        $result.SchemaUnusable | Should -BeTrue
        $result.Findings.Code | Should -Contain 'PE-SCH-003'
    }

    It 'flags a missing schema file separately from an invalid configuration' {
        $path = Save-TestConfiguration -Document (New-TestConfigurationDocument) -Directory $script:scratch
        $result = Test-PersonaConfiguration -Path $path -SchemaPath (Join-Path $script:scratch 'no-such-schema.json')

        $result.SchemaUnusable | Should -BeTrue
        $result.Findings.Code | Should -Contain 'PE-SCH-002'
    }
}

Describe 'The shipped example configuration passes every layer' {

    It 'validates cleanly against the shipped schema' {
        # If the example the documentation points at cannot pass its own validator,
        # every reader's first run fails.
        $result = Test-PersonaConfiguration -Path (Join-Path $repoRoot 'config/persona-engine.example.json')

        $result.IsValid | Should -BeTrue
        $result.ErrorCount | Should -Be 0
        $result.WarningCount | Should -Be 0
    }
}