91 lines
3.5 KiB
Markdown
91 lines
3.5 KiB
Markdown
|
# Contract: `Edit-PersonaEngineConfig.ps1`
|
|||
|
|
|
|||
|
|
Configuration validation, interactive editing, synthetic rule testing, and pipeline enforcement
|
|||
|
|
(FR-023 – FR-026).
|
|||
|
|
|
|||
|
|
## Signature
|
|||
|
|
|
|||
|
|
```powershell
|
|||
|
|
[CmdletBinding(SupportsShouldProcess = $true)]
|
|||
|
|
param(
|
|||
|
|
[Parameter(Mandatory)][string] $ConfigPath,
|
|||
|
|
[Parameter()][switch] $ValidateOnly,
|
|||
|
|
[Parameter()][switch] $NonInteractive,
|
|||
|
|
[Parameter()][string] $SchemaPath,
|
|||
|
|
[Parameter()][string] $OutputPath,
|
|||
|
|
[Parameter()][switch] $TreatWarningsAsErrors,
|
|||
|
|
[Parameter()][string] $TestDataPath
|
|||
|
|
)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Parameter contract
|
|||
|
|
|
|||
|
|
| Parameter | Behaviour |
|
|||
|
|
| --- | --- |
|
|||
|
|
| `-ConfigPath` | Required. Configuration to validate or edit. |
|
|||
|
|
| `-ValidateOnly` | Validate and report; never enter the editor. |
|
|||
|
|
| `-NonInteractive` | Pipeline mode. **MUST NOT prompt and MUST NOT hang** (SC-010). Returns an exit code. |
|
|||
|
|
| `-SchemaPath` | Override the shipped schema. |
|
|||
|
|
| `-OutputPath` | Save-As target; leaves the input file untouched. |
|
|||
|
|
| `-TreatWarningsAsErrors` | Escalates `Warning` findings to blocking (VR-005). |
|
|||
|
|
| `-TestDataPath` | Synthetic sample users for offline rule testing (FR-025). No tenant connectivity. |
|
|||
|
|
|
|||
|
|
## Validation layers (VR-001, ordered, fail-fast between layers)
|
|||
|
|
|
|||
|
|
| Layer | Mechanism | Example findings |
|
|||
|
|
| --- | --- | --- |
|
|||
|
|
| 1. Syntax | `ConvertFrom-Json` | Malformed JSON |
|
|||
|
|
| 2. Schema | `Test-Json -SchemaFile` (draft-07, OTD-005) | Missing required field, wrong type, bad enum |
|
|||
|
|
| 3. Semantic | PowerShell checks | Every condition in VR-002 |
|
|||
|
|
| 4. Safety | PowerShell checks | Every condition in VR-003 |
|
|||
|
|
|
|||
|
|
A layer that produces `Error` findings stops the sequence — running semantic checks over a
|
|||
|
|
structurally invalid document yields noise, not signal.
|
|||
|
|
|
|||
|
|
### Layer 2 error-handling requirement
|
|||
|
|
|
|||
|
|
`Test-Json` reports schema failure by writing errors rather than returning `$false` in several
|
|||
|
|
PowerShell versions. The wrapper MUST invoke it with `-ErrorAction SilentlyContinue -ErrorVariable`
|
|||
|
|
and convert collected errors into `ValidationFinding` objects, so layer 2 emits the same structured
|
|||
|
|
shape as every other layer (VR-004).
|
|||
|
|
|
|||
|
|
## Finding contract
|
|||
|
|
|
|||
|
|
Every finding carries `Severity`, `Code`, `Location` (JSON path or rule ID), `Description`,
|
|||
|
|
`SuggestedResolution`, and `Layer`. Finding codes are stable and namespaced by layer:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
PE-SYN-nnn syntax
|
|||
|
|
PE-SCH-nnn schema
|
|||
|
|
PE-SEM-nnn semantic (one code per VR-002 condition)
|
|||
|
|
PE-SAF-nnn safety (one code per VR-003 condition)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Stability matters: pipelines and runbooks will match on these codes.
|
|||
|
|
|
|||
|
|
## Exit codes
|
|||
|
|
|
|||
|
|
| Code | Condition |
|
|||
|
|
| --- | --- |
|
|||
|
|
| `0` | Valid; no blocking findings |
|
|||
|
|
| `1` | One or more `Error` findings |
|
|||
|
|
| `2` | `Warning` findings present with `-TreatWarningsAsErrors` |
|
|||
|
|
| `3` | Configuration file not found or unreadable |
|
|||
|
|
| `4` | Schema file not found or itself invalid |
|
|||
|
|
|
|||
|
|
## Save contract (FR-026)
|
|||
|
|
|
|||
|
|
1. Re-validate the edited document in full.
|
|||
|
|
2. Block the save on any `Error` finding.
|
|||
|
|
3. Write a timestamped backup — or require `-OutputPath` — before replacing an existing file.
|
|||
|
|
4. Overwriting the only valid configuration without a backup is a safety finding (VR-003), not
|
|||
|
|
merely a warning.
|
|||
|
|
|
|||
|
|
## Invariants (test-asserted)
|
|||
|
|
|
|||
|
|
| Invariant | Assertion |
|
|||
|
|
| --- | --- |
|
|||
|
|
| Non-interactive never prompts | Runs to completion with stdin closed; no prompt, no hang (SC-010) |
|
|||
|
|
| Every VR-002/VR-003 condition detected | One test per condition, each asserting code, severity, and location (SC-009) |
|
|||
|
|
| Offline | Full validation and synthetic rule testing complete with no network access (SC-008) |
|