Private/ConvertTo-PostureCaDiffMarkdown.ps1

# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md.
function ConvertTo-PostureCaDiffMarkdown {
    <#
    .SYNOPSIS
        Renders a Compare-PostureCaSnapshot report model as email-ready Markdown, risk-relevant changes first.
    #>

    [CmdletBinding()]
    [OutputType([string])]
    param(
        [Parameter(Mandatory)] [System.Collections.IDictionary] $Report
    )

    $ErrorActionPreference = 'Stop'
    $sb = [System.Text.StringBuilder]::new()
    $line = { param([string] $Text = '') $null = $sb.AppendLine($Text) }
    $esc = { param([object] $Text) ([string]$Text).Replace('|', '\|').Replace("`r", '').Replace("`n", ' ') }
    $fmtDate = { param($Value) $u = ConvertTo-PostureUtcDateTime $Value; if ($u) { $u.ToString('yyyy-MM-dd HH:mm') + ' UTC' } else { 'unknown' } }
    $table = {
        param([string[]] $Headers, [object[]] $Rows)
        & $line "| $($Headers -join ' | ') |"
        & $line "|$(@($Headers | ForEach-Object { '---' }) -join '|')|"
        foreach ($r in $Rows) { & $line "| $(@($r | ForEach-Object { & $esc $_ }) -join ' | ') |" }
        & $line
    }
    $stateLabel = @{ enabled = 'Enabled'; reportOnly = 'Report-only'; disabled = 'Disabled' }
    $st = { param($s) if ($stateLabel.ContainsKey([string]$s)) { $stateLabel[[string]$s] } else { [string]$s } }
    $blank = { param($v) if ([string]::IsNullOrEmpty([string]$v)) { '(empty)' } else { [string]$v } }

    $r = $Report; $d = $r.diff; $b = $r.brand
    & $line "# $($r.title)"
    & $line
    $prepared = [string]$b.preparedBy.name
    if ($b.client.name) { $prepared += " for $($b.client.name)" }
    & $line "Prepared by $prepared. Before: $(& $fmtDate $d.before.timestampUtc) ($($d.before.policyCount) policies). After: $(& $fmtDate $d.after.timestampUtc) ($($d.after.policyCount) policies). Tenant ``$($d.after.tenantId)``. Generated $(& $fmtDate $r.generatedUtc) with TenantKeep.Posture $($r.moduleVersion)."
    if ($b.confidentiality) { & $line; & $line "*$($b.confidentiality)*" }
    & $line

    & $line '## Risk-relevant changes'
    & $line
    if (@($d.risk).Count -eq 0) { & $line 'None.'; & $line }
    else {
        & $line "**$(@($d.risk).Count) change(s) need a look.**"
        & $line
        & $table @('Rule', 'Subject', 'Detail') @($d.risk | ForEach-Object { , @($_.rule, $_.subject, $_.detail) })
    }

    & $line '## Summary'
    & $line
    $c = $r.counts
    & $table @('Added', 'Removed', 'Renamed', 'State changed', 'Modified', 'Locations', 'Strengths', 'Contexts', 'Groups drifted') @(, @($c.added, $c.removed, $c.renamed, $c.stateChanged, $c.modified, $c.locations, $c.strengths, $c.contexts, $c.scope))
    if ($r.noChanges) { & $line 'No differences between the two snapshots.'; & $line }

    & $line '## Policies added'
    & $line
    if (@($d.policies.added).Count -eq 0) { & $line 'None.'; & $line }
    else { & $table @('Policy', 'State', 'Summary') @($d.policies.added | ForEach-Object { , @($_.name, (& $st $_.state), $_.after.summary) }) }

    & $line '## Policies removed'
    & $line
    if (@($d.policies.removed).Count -eq 0) { & $line 'None.'; & $line }
    else { & $table @('Policy', 'State', 'Summary') @($d.policies.removed | ForEach-Object { , @($_.name, (& $st $_.state), $_.before.summary) }) }

    & $line '## Policies changed'
    & $line
    if (@($d.policies.changed).Count -eq 0) { & $line 'None.'; & $line }
    foreach ($p in @($d.policies.changed)) {
        & $line "### $(& $esc $p.name)"
        & $line
        if ($p.renamed) { & $line "- Renamed from **$(& $esc $p.nameBefore)**" }
        if ($p.stateChanged) { & $line "- State: **$(& $st $p.stateBefore)** to **$(& $st $p.stateAfter)**" }
        & $line "- Last modified: $(& $fmtDate $p.modifiedBefore) to $(& $fmtDate $p.modifiedAfter)"
        & $line "- Now: $(& $esc $p.after.summary)"
        & $line
        if (@($p.fields).Count -gt 0) { & $table @('Field', 'Before', 'After') @($p.fields | ForEach-Object { , @($_.path, (& $blank $_.before), (& $blank $_.after)) }) }
    }

    foreach ($coll in @($d.locations, $d.strengths, $d.contexts)) {
        & $line "## $($coll.label)"
        & $line
        if (@($coll.added).Count + @($coll.removed).Count + @($coll.changed).Count -eq 0) { & $line 'No changes.'; & $line; continue }
        if (@($coll.added).Count -gt 0) { & $line "Added: $(@($coll.added | ForEach-Object { & $esc $_.name }) -join ', ')"; & $line }
        if (@($coll.removed).Count -gt 0) { & $line "Removed: $(@($coll.removed | ForEach-Object { & $esc $_.name }) -join ', ')"; & $line }
        foreach ($x in @($coll.changed)) {
            & $line "### $(& $esc $x.name)"
            & $line
            & $table @('Field', 'Before', 'After') @($x.fields | ForEach-Object { , @($_.path, (& $blank $_.before), (& $blank $_.after)) })
        }
    }

    & $line '## Scope drift'
    & $line
    if (@($d.scope).Count -eq 0) { & $line 'No referenced group changed.'; & $line }
    else {
        $rows = foreach ($g in @($d.scope)) {
            $added = if ($g.memberDetail) { @($g.membersAdded | ForEach-Object { if ($_.userPrincipalName) { $_.userPrincipalName } else { $_.displayName } }) -join ', ' } else { 'n/a (no -IncludeMembers)' }
            $removed = if ($g.memberDetail) { @($g.membersRemoved | ForEach-Object { if ($_.userPrincipalName) { $_.userPrincipalName } else { $_.displayName } }) -join ', ' } else { 'n/a (no -IncludeMembers)' }
            $delta = if ($null -ne $g.delta) { ('{0:+#;-#;0}' -f $g.delta) } else { '?' }
            , @($g.name, $g.countBefore, $g.countAfter, $delta, $added, $removed)
        }
        & $table @('Group', 'Before', 'After', 'Delta', 'Members added', 'Members removed') @($rows)
    }

    & $line '## Appendix'
    & $line
    & $table @('Field', 'Value') @(, @('Before snapshot', $d.before.path), @('After snapshot', $d.after.path), @('Break-glass accounts', $(if ($r.breakGlass) { $r.breakGlass -join ', ' } else { 'name heuristic (break-glass, emergency)' })))
    if ($b.footer) { & $line '---'; & $line; & $line $b.footer }
    return $sb.ToString()
}