Private/Import-PostureCheckCatalog.ps1

# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md.
function Import-PostureCheckCatalog {
    <#
    .SYNOPSIS
        Loads and validates the check catalog: every checks/*.json plus optional custom check folders.
    .DESCRIPTION
        Each file holds { "domain": "ca", "checks": [ ... ] }. Every check must carry the fields CLAUDE.md lists;
        a bad check fails the load with the file, id and missing field named, so a broken catalog never ships.
        catalog.json in the folder gives the catalog version. Custom checks are tagged custom = true.
    #>

    [CmdletBinding()]
    [OutputType([System.Collections.Specialized.OrderedDictionary])]
    param(
        [string] $Path,
        [string[]] $CustomPath = @()
    )

    $ErrorActionPreference = 'Stop'
    if (-not $Path) { $Path = Get-PostureDataFolder -Name 'checks' }
    if (-not (Test-Path -LiteralPath $Path -PathType Container)) { throw "Check catalog folder not found: $Path" }

    $version = 'unversioned'
    $versionFile = Join-Path $Path 'catalog.json'
    if (Test-Path -LiteralPath $versionFile) { $version = [string](Get-Content -Raw -LiteralPath $versionFile | ConvertFrom-Json -AsHashtable).version }

    $required = 'id', 'domain', 'title', 'severityDefault', 'license', 'applicableWhen', 'coveredBy', 'thresholds', 'evidence', 'pass', 'remediation', 'learn', 'deepLink', 'narrative', 'frameworks'
    $severities = 'Critical', 'High', 'Medium', 'Low'
    $checks = [System.Collections.Generic.List[object]]::new()
    $seen = @{}
    $files = @()

    $load = {
        param([string] $Folder, [bool] $Custom)
        foreach ($file in (Get-ChildItem -LiteralPath $Folder -Filter '*.json' | Where-Object { $_.Name -ne 'catalog.json' })) {
            $doc = Get-Content -Raw -LiteralPath $file.FullName | ConvertFrom-Json -AsHashtable -Depth 20
            $domain = [string](Get-PostureValue $doc 'domain')
            $list = if ($doc -is [System.Collections.IDictionary]) { @($doc['checks']) } else { @($doc) }
            foreach ($c in $list) {
                if (-not ($c -is [System.Collections.IDictionary])) { throw "$($file.Name): a check is not an object." }
                $missing = @($required | Where-Object { -not $c.Contains($_) })
                if ($missing.Count -gt 0) { throw "$($file.Name): check '$(Get-PostureValue $c 'id')' is missing: $($missing -join ', ')" }
                if (-not $c['domain'] -and $domain) { $c['domain'] = $domain }
                if ([string]$c['severityDefault'] -notin $severities) { throw "$($file.Name): check '$($c['id'])' has severityDefault '$($c['severityDefault'])'; expected $($severities -join ', ')" }
                if ([string]::IsNullOrWhiteSpace([string]$c['pass'])) { throw "$($file.Name): check '$($c['id'])' has an empty pass expression" }
                if ($c['id'] -notmatch '^[A-Z]{2,6}-\d{3}$') { throw "$($file.Name): check id '$($c['id'])' must look like CA-001" }
                if ($seen.ContainsKey($c['id'])) { throw "Duplicate check id '$($c['id'])' in $($file.Name) and $($seen[$c['id']])" }
                $seen[$c['id']] = $file.Name
                $c['custom'] = $Custom
                $c['source'] = $file.Name
                $checks.Add($c)
            }
            $files += $file.FullName
        }
    }
    & $load $Path $false
    foreach ($cp in $CustomPath) {
        if (-not (Test-Path -LiteralPath $cp -PathType Container)) { throw "Custom check folder not found: $cp" }
        & $load $cp $true
    }

    return [ordered]@{
        version = $version
        path    = $Path
        checks  = @($checks | Sort-Object { $_['id'] })
    }
}