Private/Compliance/Expand-GovernanceTemplate.ps1

function Expand-GovernanceTemplate {
    <#
        .SYNOPSIS
        Expands a small placeholder language against a model (ADR-014). The
        language is deliberately tiny: the program owns the wording, the engine
        owns the numbers, and nothing in between should be clever enough to
        need a debugger.

        Placeholders:
          {{path}} a value from the model ('.field' or
                                           'this' inside a loop; 'a.x'/'b.x' in zip)
          {{count path [where=…]}} number of items in a list
          {{sum path field [where=…]}} sum of a numeric field over a list
          {{words …}} / {{Words …}} a number 0–20 as a word (capitalised)
          {{note name}} a section of the team's notes file
          {{#each path [limit=N] [where=…]}} … {{/each}}
                                           loop; @first, @last, @index inside
          {{#zip a=path [awhere=…] b=path [bwhere=…]}} … {{/zip}}
                                           two lists side by side; a or b is
                                           empty when its list has run out
          {{#if expr}} … {{else}} … {{/if}} / {{#unless expr}} … {{/unless}}
                                           expr is any value above, optionally
                                           followed by == N, > N or < N

        where= takes field~regex, field!~regex, field=N, field>N or field<N.

        A block tag alone on its line takes the whole line with it, so the
        template can be laid out readably without leaving blank lines behind.
        An unknown helper, an unclosed block or a path that does not exist
        throws: a report that silently drops a number is worse than no report.
    #>

    [CmdletBinding()]
    param(
        [Parameter(Mandatory)][AllowEmptyString()][string]$Template,
        [Parameter(Mandatory)][System.Collections.IDictionary]$Model
    )

    $tokens = Split-GovernanceTemplate -Template $Template
    $pos = 0
    $tree = Read-GovernanceTemplateBlock -Tokens $tokens -Position ([ref]$pos) -Closer $null
    $sb = [System.Text.StringBuilder]::new()
    Write-GovernanceTemplateNodes -Nodes $tree.Body -Scope @(@{}) -Model $Model -Out $sb
    return $sb.ToString()
}

function Split-GovernanceTemplate {
    # Text and tag tokens. A block tag ({{#…}}, {{/…}}, {{else}}) that is the
    # only thing on its line swallows that line's indentation and newline.
    param([string]$Template)
    $Template = $Template -replace "`r`n", "`n"
    $list = [System.Collections.Generic.List[object]]::new()
    $rx = [regex]'\{\{(.*?)\}\}'
    $last = 0
    foreach ($m in $rx.Matches($Template)) {
        $inner = $m.Groups[1].Value.Trim()
        $isBlock = $inner -match '^(#|/|else$)'
        $start = $m.Index; $end = $m.Index + $m.Length
        if ($isBlock) {
            $lineStart = if ($start -eq 0) { 0 } else { $Template.LastIndexOf("`n", $start - 1) + 1 }
            $lineEnd = $Template.IndexOf("`n", $end)
            $before = $Template.Substring($lineStart, $start - $lineStart)
            $after  = if ($lineEnd -lt 0) { $Template.Substring($end) } else { $Template.Substring($end, $lineEnd - $end) }
            if ($lineStart -ge $last -and $before.Trim() -eq '' -and $after.Trim() -eq '') {
                $start = $lineStart
                $end = if ($lineEnd -lt 0) { $Template.Length } else { $lineEnd + 1 }
            }
        }
        if ($start -gt $last) { $list.Add(@{ Kind = 'text'; Value = $Template.Substring($last, $start - $last) }) }
        $list.Add(@{ Kind = 'tag'; Value = $inner })
        $last = $end
    }
    if ($last -lt $Template.Length) { $list.Add(@{ Kind = 'text'; Value = $Template.Substring($last) }) }
    return , $list
}

function Read-GovernanceTemplateBlock {
    param($Tokens, [ref]$Position, $Closer)
    $body = [System.Collections.Generic.List[object]]::new()
    $else = $null
    $current = $body
    while ($Position.Value -lt $Tokens.Count) {
        $t = $Tokens[$Position.Value]; $Position.Value++
        if ($t.Kind -eq 'text') { $current.Add(@{ Kind = 'text'; Value = $t.Value }); continue }
        $v = $t.Value
        if ($v -eq 'else') {
            if ($Closer -notin 'if', 'unless') { throw "Template: {{else}} outside an {{#if}} or {{#unless}} block" }
            $else = [System.Collections.Generic.List[object]]::new(); $current = $else; continue
        }
        if ($v.StartsWith('/')) {
            $name = $v.Substring(1).Trim()
            if ($name -ne $Closer) { throw "Template: {{/$name}} closes a block that was not opened (expected {{/$Closer}})" }
            return @{ Body = $body; Else = $else }
        }
        if ($v.StartsWith('#')) {
            $parts = $v.Substring(1).Trim() -split '\s+', 2
            $kind = $parts[0]
            if ($kind -notin 'each', 'if', 'unless', 'zip') { throw "Template: unknown block {{#$kind}}" }
            $inner = Read-GovernanceTemplateBlock -Tokens $Tokens -Position $Position -Closer $kind
            $current.Add(@{ Kind = $kind; Args = $(if ($parts.Count -gt 1) { $parts[1] } else { '' }); Body = $inner.Body; Else = $inner.Else })
            continue
        }
        $current.Add(@{ Kind = 'var'; Value = $v })
    }
    if ($Closer) { throw "Template: {{#$Closer}} is never closed" }
    return @{ Body = $body; Else = $else }
}

function Write-GovernanceTemplateNodes {
    param($Nodes, $Scope, $Model, [System.Text.StringBuilder]$Out)
    foreach ($n in $Nodes) {
        switch ($n.Kind) {
            'text' { [void]$Out.Append($n.Value) }
            'var'  {
                $val = Get-GovernanceTemplateValue -Expr $n.Value -Scope $Scope -Model $Model
                [void]$Out.Append((Format-GovernanceTemplateScalar $val))
            }
            { $_ -in 'if', 'unless' } {
                $truth = Test-GovernanceTemplateCondition -Expr $n.Args -Scope $Scope -Model $Model
                if ($n.Kind -eq 'unless') { $truth = -not $truth }
                $branch = if ($truth) { $n.Body } else { $n.Else }
                if ($branch) { Write-GovernanceTemplateNodes -Nodes $branch -Scope $Scope -Model $Model -Out $Out }
            }
            'each' {
                $a = ConvertFrom-GovernanceTemplateArgs $n.Args
                $items = @(Select-GovernanceTemplateList -Path $a.Positional[0] -Where $a.where -Scope $Scope -Model $Model)
                if ($a.limit) { $items = @($items | Select-Object -First ([int]$a.limit)) }
                for ($i = 0; $i -lt $items.Count; $i++) {
                    $frame = @{ this = $items[$i]; '@index' = $i; '@first' = ($i -eq 0); '@last' = ($i -eq $items.Count - 1) }
                    Write-GovernanceTemplateNodes -Nodes $n.Body -Scope (@($frame) + $Scope) -Model $Model -Out $Out
                }
            }
            'zip' {
                $a = ConvertFrom-GovernanceTemplateArgs $n.Args
                if (-not $a.a -or -not $a.b) { throw "Template: {{#zip}} needs a=<list> and b=<list>" }
                $la = @(Select-GovernanceTemplateList -Path $a.a -Where $a.awhere -Scope $Scope -Model $Model)
                $lb = @(Select-GovernanceTemplateList -Path $a.b -Where $a.bwhere -Scope $Scope -Model $Model)
                $rows = [Math]::Max($la.Count, $lb.Count)
                for ($i = 0; $i -lt $rows; $i++) {
                    $frame = @{
                        a = $(if ($i -lt $la.Count) { $la[$i] } else { $null })
                        b = $(if ($i -lt $lb.Count) { $lb[$i] } else { $null })
                        '@index' = $i; '@first' = ($i -eq 0); '@last' = ($i -eq $rows - 1)
                    }
                    Write-GovernanceTemplateNodes -Nodes $n.Body -Scope (@($frame) + $Scope) -Model $Model -Out $Out
                }
            }
        }
    }
}

function ConvertFrom-GovernanceTemplateArgs {
    param([string]$Text)
    $named = @{}; $pos = [System.Collections.Generic.List[string]]::new()
    foreach ($w in ($Text.Trim() -split '\s+' | Where-Object { $_ })) {
        if ($w -match '^(limit|where|a|b|awhere|bwhere)=(.*)$') { $named[$Matches[1]] = $Matches[2] } else { $pos.Add($w) }
    }
    $named['Positional'] = $pos
    return $named
}

function Resolve-GovernanceTemplatePath {
    # A dotted path, looked up first in the loop frames then in the model.
    # '.field' and 'this.field' are the current item. Missing → throw.
    param([string]$Path, $Scope, $Model)
    if ($Path.StartsWith('.')) { $Path = "this$Path" }
    $segments = $Path -split '\.'
    $head = $segments[0]
    $found = $false; $value = $null
    foreach ($frame in $Scope) {
        if ($frame.ContainsKey($head)) { $value = $frame[$head]; $found = $true; break }
    }
    if (-not $found) {
        if (-not $Model.Contains($head)) { throw "Template: '$Path' is not in the report model" }
        $value = $Model[$head]
    }
    for ($i = 1; $i -lt $segments.Count; $i++) {
        if ($null -eq $value) { return $null }      # a/b in a zip after its list ran out
        $seg = $segments[$i]
        if ($value -is [System.Collections.IDictionary]) {
            if (-not $value.Contains($seg)) {
                # contacts are keyed by the program, not the engine: absent = not recorded yet.
                if ($segments[0] -eq 'contacts') { return '' }
                throw "Template: '$Path' — no field '$seg'"
            }
            $value = $value[$seg]
        } else {
            $prop = $value.PSObject.Properties[$seg]
            if (-not $prop) { throw "Template: '$Path' — no field '$seg'" }
            $value = $prop.Value
        }
    }
    return $value
}

function Get-GovernanceTemplateField {
    param($Item, [string]$Field)
    if ($Item -is [System.Collections.IDictionary]) {
        if (-not $Item.Contains($Field)) { throw "Template: where= field '$Field' is not on the list items" }
        return $Item[$Field]
    }
    $p = $Item.PSObject.Properties[$Field]
    if (-not $p) { throw "Template: where= field '$Field' is not on the list items" }
    return $p.Value
}

function Select-GovernanceTemplateList {
    param([string]$Path, [string]$Where, $Scope, $Model)
    if (-not $Path) { throw "Template: a list path is required" }
    $list = Resolve-GovernanceTemplatePath -Path $Path -Scope $Scope -Model $Model
    if ($null -eq $list) { return @() }
    $items = @($list)
    if (-not $Where) { return $items }
    if ($Where -notmatch '^(?<f>[\w@]+)(?<op>!~|~|=|>|<)(?<v>.*)$') { throw "Template: cannot read where=$Where" }
    $f = $Matches.f; $op = $Matches.op; $v = $Matches.v
    return @($items | Where-Object {
        $x = Get-GovernanceTemplateField -Item $_ -Field $f
        switch ($op) {
            '~'  { [string]$x -match $v }
            '!~' { [string]$x -notmatch $v }
            '='  { [string]$x -eq $v }
            '>'  { [double]$x -gt [double]$v }
            '<'  { [double]$x -lt [double]$v }
        }
    })
}

function Get-GovernanceTemplateValue {
    param([string]$Expr, $Scope, $Model)
    $words = $Expr -split '\s+'
    switch -CaseSensitive ($words[0]) {
        'words' { return (ConvertTo-GovernanceNumberWord (Get-GovernanceTemplateValue ($words[1..($words.Count - 1)] -join ' ') $Scope $Model) $false) }
        'Words' { return (ConvertTo-GovernanceNumberWord (Get-GovernanceTemplateValue ($words[1..($words.Count - 1)] -join ' ') $Scope $Model) $true) }
        'count' {
            $a = ConvertFrom-GovernanceTemplateArgs ($words[1..($words.Count - 1)] -join ' ')
            return @(Select-GovernanceTemplateList -Path $a.Positional[0] -Where $a.where -Scope $Scope -Model $Model).Count
        }
        'sum' {
            $a = ConvertFrom-GovernanceTemplateArgs ($words[1..($words.Count - 1)] -join ' ')
            $field = $a.Positional[1]
            if (-not $field) { throw "Template: {{sum <list> <field>}} needs a field" }
            $total = 0
            foreach ($i in @(Select-GovernanceTemplateList -Path $a.Positional[0] -Where $a.where -Scope $Scope -Model $Model)) { $total += [double](Get-GovernanceTemplateField $i $field) }
            return $total
        }
        'note' {
            $notes = $Model['notes']
            if ($notes -and $notes.Contains($words[1])) { return $notes[$words[1]] }
            return ''
        }
    }
    if ($words.Count -gt 1) { throw "Template: unknown helper '$($words[0])' in {{$Expr}}" }
    return (Resolve-GovernanceTemplatePath -Path $Expr -Scope $Scope -Model $Model)
}

function Test-GovernanceTemplateCondition {
    param([string]$Expr, $Scope, $Model)
    $Expr = $Expr.Trim()
    $negate = $false
    if ($Expr.StartsWith('!')) { $negate = $true; $Expr = $Expr.Substring(1).Trim() }
    $result = if ($Expr -match '^(?<lhs>.+?)\s*(?<op>==|>|<)\s*(?<rhs>-?\d+)$') {
        $lhs = [double](Get-GovernanceTemplateValue $Matches.lhs.Trim() $Scope $Model)
        $rhs = [double]$Matches.rhs
        switch ($Matches.op) { '==' { $lhs -eq $rhs } '>' { $lhs -gt $rhs } '<' { $lhs -lt $rhs } }
    } else {
        $v = Get-GovernanceTemplateValue $Expr $Scope $Model
        if ($null -eq $v) { $false }
        elseif ($v -is [bool]) { $v }
        elseif ($v -is [string]) { $v -ne '' }
        elseif ($v -is [System.Collections.IDictionary]) { $v.Count -gt 0 }
        elseif ($v -is [System.Collections.IEnumerable]) { @($v).Count -gt 0 }
        elseif ($v -is [ValueType]) { [double]$v -ne 0 }
        else { $true }
    }
    if ($negate) { return -not $result } else { return [bool]$result }
}

function ConvertTo-GovernanceNumberWord {
    param($Number, [bool]$Capital)
    $n = [int]$Number
    $names = 'zero','one','two','three','four','five','six','seven','eight','nine','ten',
             'eleven','twelve','thirteen','fourteen','fifteen','sixteen','seventeen','eighteen','nineteen','twenty'
    $w = if ($n -ge 0 -and $n -le 20) { $names[$n] } else { [string]$n }
    if ($Capital -and $w.Length -gt 0) { $w = $w.Substring(0, 1).ToUpper() + $w.Substring(1) }
    return $w
}

function Format-GovernanceTemplateScalar {
    param($Value)
    if ($null -eq $Value) { return '' }
    if ($Value -is [double] -and $Value -eq [Math]::Floor($Value)) { return ([long]$Value).ToString() }
    if ($Value -is [System.Collections.IEnumerable] -and $Value -isnot [string]) { throw "Template: a list cannot be printed directly; use {{#each}} or {{count}}" }
    return [string]$Value
}