262 lines
11 KiB
PowerShell
262 lines
11 KiB
PowerShell
|
function Test-PersonaConfiguration {
|
||
|
|
<#
|
||
|
|
.SYNOPSIS
|
||
|
|
Runs all four validation layers over a configuration file (VR-001, FR-002).
|
||
|
|
|
||
|
|
.DESCRIPTION
|
||
|
|
Layers run in order and fail fast between them:
|
||
|
|
|
||
|
|
1. Syntax ConvertFrom-Json PE-SYN-nnn
|
||
|
|
2. Schema Test-Json -SchemaFile PE-SCH-nnn
|
||
|
|
3. Semantic Test-PersonaConfigurationSemantic PE-SEM-nnn
|
||
|
|
4. Safety Test-PersonaConfigurationSafety PE-SAF-nnn
|
||
|
|
|
||
|
|
A layer that produces Error findings stops the sequence. Running semantic
|
||
|
|
checks over a structurally invalid document produces noise, not signal: every
|
||
|
|
missing field yields a cascade of consequent errors, and the author has to
|
||
|
|
guess which one is the actual cause.
|
||
|
|
|
||
|
|
Layer 2 error handling is driven by the V-5a observation
|
||
|
|
(specs/001-persona-engine/verification/V-5a.md), which matters more than it
|
||
|
|
looks. On PowerShell 7.6.5, Test-Json returns $true when the SCHEMA ITSELF is
|
||
|
|
unparseable, writing the failure to the error stream instead. A wrapper that
|
||
|
|
trusted the return value would report a configuration as schema-valid when
|
||
|
|
the schema never ran. So this function treats a non-empty error variable as
|
||
|
|
failure regardless of what was returned, and separates the "schema is broken"
|
||
|
|
case from the "configuration is invalid" case, because they need different
|
||
|
|
exit codes.
|
||
|
|
|
||
|
|
.PARAMETER Path
|
||
|
|
Configuration file to validate.
|
||
|
|
|
||
|
|
.PARAMETER SchemaPath
|
||
|
|
Schema override. Defaults to the shipped config/persona-engine.schema.json.
|
||
|
|
|
||
|
|
.PARAMETER PreviousConfigPath
|
||
|
|
A previously deployed configuration, enabling the VR-003 comparison checks
|
||
|
|
(version downgrade, undeclared rule deletion or reorder).
|
||
|
|
|
||
|
|
.PARAMETER EnforcementEnabled
|
||
|
|
Whether this configuration will be used for an enforcing run. Raises the
|
||
|
|
severity of several safety findings.
|
||
|
|
|
||
|
|
.PARAMETER SkipSafety
|
||
|
|
Runs layers 1-3 only. Used by the editor while a document is mid-edit.
|
||
|
|
|
||
|
|
.OUTPUTS
|
||
|
|
PersonaEngine.ValidationResult
|
||
|
|
#>
|
||
|
|
[CmdletBinding()]
|
||
|
|
[OutputType([pscustomobject])]
|
||
|
|
param(
|
||
|
|
[Parameter(Mandatory)]
|
||
|
|
[ValidateNotNullOrEmpty()]
|
||
|
|
[string] $Path,
|
||
|
|
|
||
|
|
[string] $SchemaPath,
|
||
|
|
|
||
|
|
[string] $PreviousConfigPath,
|
||
|
|
|
||
|
|
[switch] $EnforcementEnabled,
|
||
|
|
|
||
|
|
[switch] $SkipSafety
|
||
|
|
)
|
||
|
|
|
||
|
|
$findings = [System.Collections.Generic.List[object]]::new()
|
||
|
|
$document = $null
|
||
|
|
$stoppedAtLayer = $null
|
||
|
|
$schemaUnusable = $false
|
||
|
|
|
||
|
|
# ---------------------------------------------------------------- Layer 1
|
||
|
|
|
||
|
|
if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
|
||
|
|
$findings.Add((New-PersonaValidationFinding -Severity Error -Code 'PE-SYN-001' `
|
||
|
|
-Location $Path `
|
||
|
|
-Description "Configuration file not found or is not a file: '$Path'." `
|
||
|
|
-SuggestedResolution 'Check the path. In a pipeline, confirm the file was checked out and the working directory is what you expect.'))
|
||
|
|
|
||
|
|
return New-PersonaValidationResult -Findings $findings -Document $null -StoppedAtLayer 'Syntax' -SchemaUnusable $false
|
||
|
|
}
|
||
|
|
|
||
|
|
$raw = $null
|
||
|
|
try {
|
||
|
|
$raw = Get-Content -LiteralPath $Path -Raw -ErrorAction Stop
|
||
|
|
}
|
||
|
|
catch {
|
||
|
|
$findings.Add((New-PersonaValidationFinding -Severity Error -Code 'PE-SYN-002' `
|
||
|
|
-Location $Path `
|
||
|
|
-Description "Configuration file could not be read: $($_.Exception.Message)" `
|
||
|
|
-SuggestedResolution 'Check file permissions and that no other process holds an exclusive lock.'))
|
||
|
|
|
||
|
|
return New-PersonaValidationResult -Findings $findings -Document $null -StoppedAtLayer 'Syntax' -SchemaUnusable $false
|
||
|
|
}
|
||
|
|
|
||
|
|
try {
|
||
|
|
$document = $raw | ConvertFrom-Json -Depth 32 -ErrorAction Stop
|
||
|
|
}
|
||
|
|
catch {
|
||
|
|
$findings.Add((New-PersonaValidationFinding -Severity Error -Code 'PE-SYN-003' `
|
||
|
|
-Location $Path `
|
||
|
|
-Description "Configuration is not valid JSON: $($_.Exception.Message)" `
|
||
|
|
-SuggestedResolution 'Fix the JSON syntax. A trailing comma or an unquoted key is the usual cause.'))
|
||
|
|
|
||
|
|
return New-PersonaValidationResult -Findings $findings -Document $null -StoppedAtLayer 'Syntax' -SchemaUnusable $false
|
||
|
|
}
|
||
|
|
|
||
|
|
# ---------------------------------------------------------------- Layer 2
|
||
|
|
|
||
|
|
if (-not $SchemaPath) {
|
||
|
|
$moduleRoot = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
|
||
|
|
$SchemaPath = Join-Path $moduleRoot 'config/persona-engine.schema.json'
|
||
|
|
}
|
||
|
|
|
||
|
|
if (-not (Test-Path -LiteralPath $SchemaPath -PathType Leaf)) {
|
||
|
|
$findings.Add((New-PersonaValidationFinding -Severity Error -Code 'PE-SCH-002' `
|
||
|
|
-Location $SchemaPath `
|
||
|
|
-Description "Schema file not found: '$SchemaPath'." `
|
||
|
|
-SuggestedResolution 'Supply -SchemaPath, or restore config/persona-engine.schema.json.'))
|
||
|
|
|
||
|
|
return New-PersonaValidationResult -Findings $findings -Document $document -StoppedAtLayer 'Schema' -SchemaUnusable $true
|
||
|
|
}
|
||
|
|
|
||
|
|
$schemaErrors = $null
|
||
|
|
$schemaOk = $raw | Test-Json -SchemaFile $SchemaPath -ErrorAction SilentlyContinue -ErrorVariable schemaErrors
|
||
|
|
|
||
|
|
foreach ($schemaError in @($schemaErrors)) {
|
||
|
|
$message = [string]$schemaError.Exception.Message
|
||
|
|
|
||
|
|
# V-5a: this message arrives with a $true return value. Treating it as a
|
||
|
|
# pass would validate every configuration against a schema that never ran.
|
||
|
|
if ($message -match 'Cannot parse the JSON schema') {
|
||
|
|
$schemaUnusable = $true
|
||
|
|
|
||
|
|
$findings.Add((New-PersonaValidationFinding -Severity Error -Code 'PE-SCH-003' `
|
||
|
|
-Location $SchemaPath `
|
||
|
|
-Description "The schema file itself is not valid JSON Schema and could not be used: $message" `
|
||
|
|
-SuggestedResolution 'Repair the schema file. Until it parses, no configuration can be schema-validated, and a passing result would be meaningless.'))
|
||
|
|
continue
|
||
|
|
}
|
||
|
|
|
||
|
|
$findings.Add((New-PersonaValidationFinding -Severity Error -Code 'PE-SCH-001' `
|
||
|
|
-Location (Get-PersonaSchemaErrorLocation -Message $message) `
|
||
|
|
-Description $message `
|
||
|
|
-SuggestedResolution 'Correct the document to match config/persona-engine.schema.json. Test-Json reports only the first violation per run, so re-validate after each fix.'))
|
||
|
|
}
|
||
|
|
|
||
|
|
if ($schemaUnusable -or -not $schemaOk -or @($schemaErrors).Count -gt 0) {
|
||
|
|
return New-PersonaValidationResult -Findings $findings -Document $document -StoppedAtLayer 'Schema' -SchemaUnusable $schemaUnusable
|
||
|
|
}
|
||
|
|
|
||
|
|
# ---------------------------------------------------------------- Layer 3
|
||
|
|
|
||
|
|
foreach ($finding in (Test-PersonaConfigurationSemantic -Document $document)) { $findings.Add($finding) }
|
||
|
|
|
||
|
|
if (@($findings | Where-Object Severity -EQ 'Error').Count -gt 0) {
|
||
|
|
return New-PersonaValidationResult -Findings $findings -Document $document -StoppedAtLayer 'Semantic' -SchemaUnusable $false
|
||
|
|
}
|
||
|
|
|
||
|
|
# ---------------------------------------------------------------- Layer 4
|
||
|
|
|
||
|
|
if (-not $SkipSafety) {
|
||
|
|
$safetyParams = @{ Document = $document; EnforcementEnabled = $EnforcementEnabled }
|
||
|
|
if ($PreviousConfigPath) { $safetyParams['PreviousConfigPath'] = $PreviousConfigPath }
|
||
|
|
|
||
|
|
foreach ($finding in (Test-PersonaConfigurationSafety @safetyParams)) { $findings.Add($finding) }
|
||
|
|
}
|
||
|
|
|
||
|
|
New-PersonaValidationResult -Findings $findings -Document $document -StoppedAtLayer $null -SchemaUnusable $false
|
||
|
|
}
|
||
|
|
|
||
|
|
function New-PersonaValidationResult {
|
||
|
|
<#
|
||
|
|
.SYNOPSIS
|
||
|
|
Wraps a finding collection into the shape every caller consumes.
|
||
|
|
|
||
|
|
.DESCRIPTION
|
||
|
|
IsValid is computed here rather than by each caller, so console, pipeline,
|
||
|
|
and editor cannot disagree about what "valid" means. Warnings never affect
|
||
|
|
IsValid; escalation under -TreatWarningsAsErrors is the caller's decision
|
||
|
|
(VR-005) and belongs where the exit code is chosen.
|
||
|
|
#>
|
||
|
|
[CmdletBinding()]
|
||
|
|
[OutputType([pscustomobject])]
|
||
|
|
param(
|
||
|
|
[Parameter(Mandatory)] [AllowEmptyCollection()] [object] $Findings,
|
||
|
|
[AllowNull()] [object] $Document,
|
||
|
|
[AllowNull()] [string] $StoppedAtLayer,
|
||
|
|
[bool] $SchemaUnusable
|
||
|
|
)
|
||
|
|
|
||
|
|
$all = @($Findings)
|
||
|
|
|
||
|
|
[pscustomobject]@{
|
||
|
|
PSTypeName = 'PersonaEngine.ValidationResult'
|
||
|
|
IsValid = (@($all | Where-Object Severity -EQ 'Error').Count -eq 0)
|
||
|
|
Findings = $all
|
||
|
|
ErrorCount = @($all | Where-Object Severity -EQ 'Error').Count
|
||
|
|
WarningCount = @($all | Where-Object Severity -EQ 'Warning').Count
|
||
|
|
Document = $Document
|
||
|
|
StoppedAtLayer = $StoppedAtLayer
|
||
|
|
SchemaUnusable = $SchemaUnusable
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
function Get-PersonaSchemaErrorLocation {
|
||
|
|
<#
|
||
|
|
.SYNOPSIS
|
||
|
|
Extracts the JSON pointer from a Test-Json error message.
|
||
|
|
|
||
|
|
.DESCRIPTION
|
||
|
|
Test-Json embeds the failing location in prose - "... at '/rules/3/priority'".
|
||
|
|
VR-004 requires a location on every finding, so it is lifted out here rather
|
||
|
|
than leaving the caller to read it out of the description. When no pointer is
|
||
|
|
present the document root is reported, which is honest: the violation is
|
||
|
|
somewhere in the document and the message says where in words.
|
||
|
|
#>
|
||
|
|
[CmdletBinding()]
|
||
|
|
[OutputType([string])]
|
||
|
|
param([Parameter(Mandatory)] [AllowEmptyString()] [string] $Message)
|
||
|
|
|
||
|
|
if ($Message -match "at '([^']*)'") {
|
||
|
|
$pointer = $Matches[1]
|
||
|
|
return $pointer ? $pointer : '/'
|
||
|
|
}
|
||
|
|
|
||
|
|
'/'
|
||
|
|
}
|
||
|
|
|
||
|
|
function Write-PersonaValidationFinding {
|
||
|
|
<#
|
||
|
|
.SYNOPSIS
|
||
|
|
Renders validation findings for a human reader.
|
||
|
|
|
||
|
|
.DESCRIPTION
|
||
|
|
Grouped by severity, most serious first, with the suggested resolution on
|
||
|
|
its own line. A finding without a visible resolution just tells someone they
|
||
|
|
are wrong, which is why VR-004 makes the field mandatory and why it is
|
||
|
|
printed rather than hidden behind a verbose switch.
|
||
|
|
#>
|
||
|
|
[CmdletBinding()]
|
||
|
|
param(
|
||
|
|
[Parameter(Mandatory)] [AllowEmptyCollection()] [object[]] $Findings
|
||
|
|
)
|
||
|
|
|
||
|
|
if (@($Findings).Count -eq 0) {
|
||
|
|
Write-Host 'Validation passed with no findings.' -ForegroundColor Green
|
||
|
|
return
|
||
|
|
}
|
||
|
|
|
||
|
|
foreach ($severity in @('Error', 'Warning', 'Information')) {
|
||
|
|
$set = @($Findings | Where-Object Severity -EQ $severity)
|
||
|
|
if ($set.Count -eq 0) { continue }
|
||
|
|
|
||
|
|
$colour = switch ($severity) { 'Error' { 'Red' } 'Warning' { 'Yellow' } default { 'Gray' } }
|
||
|
|
|
||
|
|
foreach ($finding in $set) {
|
||
|
|
Write-Host ("[{0}] {1} {2}" -f $finding.Severity.ToUpperInvariant(), $finding.Code, $finding.Location) -ForegroundColor $colour
|
||
|
|
Write-Host (" {0}" -f $finding.Description)
|
||
|
|
Write-Host (" -> {0}" -f $finding.SuggestedResolution) -ForegroundColor DarkGray
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|