Private/Compliance/ConvertTo-GovernancePreflightTemplateReport.ps1
|
function Get-GovernancePreflightModel { <# .SYNOPSIS The facts a templated preflight report may quote (ADR-014), built from the same data and findings documents the fixed renderer reads. Every list is sorted here, once, so a template never decides an order and re-rendering unchanged inputs produces unchanged bytes. Lists are sorted largest first by work items, then by name (culture, case-insensitive — the order a reader expects). #> [CmdletBinding()] param( [Parameter(Mandatory)][System.Collections.IDictionary]$Data, [Parameter(Mandatory)][System.Collections.IDictionary]$Findings, [object]$Source = $null, # this node's sources.yaml entry (for contacts) [System.Collections.IDictionary]$Notes = @{} ) $inv = [System.Globalization.CultureInfo]::InvariantCulture $byCheck = @{} foreach ($f in @($Findings.findings)) { $k = [string]$f.check if (-not $byCheck.ContainsKey($k)) { $byCheck[$k] = [System.Collections.Generic.List[object]]::new() } $byCheck[$k].Add($f) } $of = { param($check) @(if ($byCheck.ContainsKey($check)) { $byCheck[$check] }) } $orgName = { param($url) ([string]$url).TrimEnd('/') -replace '^.*/', '' } $srcRoot = [string]$Data.source.areaPath $parent = $srcRoot.Substring(0, [Math]::Max(0, $srcRoot.LastIndexOf('\'))) $rel = { param($p) $p = [string]$p; if ($p -eq $srcRoot) { '' } elseif ($p.StartsWith("$srcRoot\")) { $p.Substring($srcRoot.Length + 1) } else { $p } } $short = { param($p) $p = [string]$p; if ($parent -and $p.StartsWith("$parent\")) { $p.Substring($parent.Length + 1) } else { $p.TrimStart('\') } } $row = { param($a) [ordered]@{ source = [string]$a.source; target = [string]$a.target; workItems = [long]$a.workItems; rel = (& $rel $a.source); short = (& $short $a.source) } } $areas = @($Data.areas | ForEach-Object { & $row $_ }) $orphanSources = @{}; foreach ($f in (& $of 'area.orphan')) { $orphanSources[[string]$f.source] = $true } $byWork = { param($items, $name) @($items | Sort-Object @{ Expression = { $_.workItems }; Descending = $true }, @{ Expression = { $_[$name] } }) } $gathered = if ($Data.gathered -is [datetime]) { ([datetime]$Data.gathered).ToUniversalTime() } else { $t = [datetime]::MinValue; [void][datetime]::TryParse([string]$Data.gathered, $inv, [System.Globalization.DateTimeStyles]::AdjustToUniversal, [ref]$t); $t } $contacts = [ordered]@{} if ($Source -and $Source.contacts) { foreach ($k in @($Source.contacts.Keys)) { $contacts[[string]$k] = if ($null -eq $Source.contacts[$k]) { '' } else { [string]$Source.contacts[$k] } } } $tagRows = @(foreach ($k in @($Data.tags.Keys)) { [ordered]@{ name = [string]$k; workItems = [long]$Data.tags[$k] } }) $iterRows = @(foreach ($k in @($Data.iterations.Keys)) { [ordered]@{ path = [string]$k; leaf = ([string]$k -replace '^.*\\', ''); workItems = [long]$Data.iterations[$k] } }) return [ordered]@{ team = [ordered]@{ code = [string]$Data.node name = ($srcRoot -replace '^.*\\', '') areaPath = $srcRoot sourceOrg = (& $orgName $Data.source.org) sourceProject = [string]$Data.source.project targetOrg = (& $orgName $Data.target.org) targetProject = [string]$Data.target.project targetRoot = [string]$Data.target.root } gathered = $gathered.ToString('d MMMM yyyy', $inv) scope = [ordered]@{ label = [string]$Data.scope.label; query = [string]$Data.scope.query } workItems = [long]$Data.workItems.count contacts = $contacts areas = [ordered]@{ all = $areas subCount = @($areas | Where-Object { $_.source -ne $srcRoot }).Count inPlace = @($areas | Where-Object { -not $orphanSources.ContainsKey($_.source) } | Sort-Object { $_.short }) orphans = (& $byWork @($areas | Where-Object { $orphanSources.ContainsKey($_.source) }) 'source') unmapped = @((& $of 'area.unmapped') | ForEach-Object { [ordered]@{ source = [string]$_.source; workItems = [long]$_.workItems } }) } tags = [ordered]@{ inUse = (& $byWork $tagRows 'name') undecided = (& $byWork @((& $of 'tag.unsanctioned') | ForEach-Object { [ordered]@{ name = [string]$_.subject; workItems = [long]$_.workItems } }) 'name') families = @((& $of 'tag.disallowed') | ForEach-Object { [ordered]@{ pattern = [string]$_.subject; tags = [long]$_.tags; workItems = [long]$_.workItems } }) boardColumns = @((& $of 'tag.boardColumn') | ForEach-Object { [ordered]@{ name = [string]$_.subject; workItems = [long]$_.workItems } }) retire = @((& $of 'tag.retire') | ForEach-Object { [ordered]@{ name = [string]$_.subject; workItems = [long]$_.workItems } }) } iterations = (& $byWork $iterRows 'path') members = [ordered]@{ authored = @($Data.authored.members).Count + @($Data.authored.teamAdmins).Count unresolvable = @(@(& $of 'member.unresolvable') + @(& $of 'teamAdmin.unresolvable') | ForEach-Object { [ordered]@{ name = [string]$_.subject } }) unauthored = @((& $of 'member.unauthored') | ForEach-Object { [ordered]@{ name = [string]$_.subject } }) sourceTeamsDeclared = (@($Data.source.teams | Where-Object { $_ }).Count -gt 0) } repos = [ordered]@{ declared = ($null -ne $Data.source.repoInclude) orphans = @((& $of 'repo.orphan') | ForEach-Object { [ordered]@{ name = [string]$_.subject } }) } notes = $Notes } } function Read-GovernanceTemplateSections { # '<!-- <kind>: name -->' starts a section; it runs to the next marker or # the end. Leading/trailing blank lines are trimmed, so sections can be # spaced out in the file without the spacing reaching the report. param([string]$Text, [string]$Kind) $Text = $Text -replace "`r`n", "`n" $out = [ordered]@{} $rx = [regex]"(?m)^<!--\s*$($Kind):\s*([\w.\-]+)\s*-->[ \t]*\n?" $ms = $rx.Matches($Text) for ($i = 0; $i -lt $ms.Count; $i++) { $start = $ms[$i].Index + $ms[$i].Length $end = if ($i + 1 -lt $ms.Count) { $ms[$i + 1].Index } else { $Text.Length } $name = $ms[$i].Groups[1].Value if ($out.Contains($name)) { throw "Duplicate $Kind '$name'" } $out[$name] = ($Text.Substring($start, $end - $start) -replace '^(\s*\n)+', '').TrimEnd() } return $out } function ConvertTo-GovernancePreflightTemplateReport { <# .SYNOPSIS Renders a team's preflight report by filling the program's own document with that team's facts (ADR-014). The document (a team-facing standard, say) carries markers; the program's slots file says, in the placeholder language of Expand-GovernanceTemplate, what goes at each marker; this function supplies the numbers. Nothing program-specific lives here. Markers in the document, invisible when the document is published on its own: <!-- team:replace NAME --> … <!-- team:end --> the lines between are replaced by slot NAME <!-- team:slot NAME --> replaced by slot NAME — inline if it shares a line with text, as whole lines if it is alone on its line <!-- team:check NAME --> (at the end of a '- [ ]' checklist item) slot NAME starts with [x] or [ ], which sets the box; the rest follows the item's text, further lines follow the item <!-- team:fill COLUMN ROWPREFIX --> in the table that follows, cell COLUMN (1-based) of each body row becomes slot ROWPREFIX.<first cell> <!-- team:column HEADER SEPARATOR ROWPREFIX --> the table that follows gains a column: slot HEADER is its heading, slot SEPARATOR replaces the separator row, and each body row gets slot ROWPREFIX.<first cell> Notes (the team's observations file, sections '<!-- note: NAME -->') are available as {{note NAME}}. Notes older than the findings are withheld, exactly as the fixed renderer withholds stale observations. #> [CmdletBinding()] param( [Parameter(Mandatory)][string]$DataPath, [Parameter(Mandatory)][string]$FindingsPath, [Parameter(Mandatory)][string]$DocumentPath, [Parameter(Mandatory)][string]$SlotsPath, [string]$NotesPath = '', [string]$OutputPath = '', [string]$AssetPrefix = '', [object]$Source = $null, [object]$Reporting = $null ) foreach ($p in $DataPath, $FindingsPath, $DocumentPath, $SlotsPath) { if (-not (Test-Path -LiteralPath $p)) { throw "ConvertTo-GovernancePreflightTemplateReport: input not found: $p" } } $data = Get-Content -LiteralPath $DataPath -Raw | ConvertFrom-Json -AsHashtable -Depth 20 $fin = Get-Content -LiteralPath $FindingsPath -Raw | ConvertFrom-Json -AsHashtable -Depth 20 if ([string]$data.schema -ne 'nkdagility.governance.preflight-data/1') { throw "'$DataPath' is not a preflight data document this engine understands (schema '$($data.schema)')." } if ([string]$fin.mode -ne 'Preflight') { throw "'$FindingsPath' is a '$($fin.mode)' report, not a preflight findings document." } $notes = @{} if ($NotesPath -and (Test-Path -LiteralPath $NotesPath)) { $stale = (Get-Item -LiteralPath $NotesPath).LastWriteTimeUtc -lt (Get-Item -LiteralPath $FindingsPath).LastWriteTimeUtc if ($stale) { Write-Warning "Notes withheld: '$(Split-Path -Leaf $NotesPath)' was written before the current analysis." } else { $notes = Read-GovernanceTemplateSections -Text (Get-Content -LiteralPath $NotesPath -Raw) -Kind 'note' } } $model = Get-GovernancePreflightModel -Data $data -Findings $fin -Source $Source -Notes $notes $slots = Read-GovernanceTemplateSections -Text (Get-Content -LiteralPath $SlotsPath -Raw) -Kind 'slot' $slot = { param($name) if (-not $slots.Contains($name)) { throw "Slots file '$SlotsPath' has no slot '$name'" } (Expand-GovernanceTemplate -Template $slots[$name] -Model $model).TrimEnd("`n") } $doc = (Get-Content -LiteralPath $DocumentPath -Raw) -replace "`r`n", "`n" $doc = $doc -replace '^(?s)---\n.*?\n---\n', '' $lines = $doc -split "`n" $out = [System.Collections.Generic.List[string]]::new() $i = 0 while ($i -lt $lines.Count) { $line = $lines[$i] if ($line -match '^\s*<!--\s*team:replace\s+([\w.\-]+)\s*-->\s*$') { $name = $Matches[1] $j = $i + 1 while ($j -lt $lines.Count -and $lines[$j] -notmatch '^\s*<!--\s*team:end\s*-->\s*$') { $j++ } if ($j -ge $lines.Count) { throw "Document '$DocumentPath': team:replace $name has no team:end" } foreach ($l in ((& $slot $name) -split "`n")) { $out.Add($l) } $i = $j + 1; continue } if ($line -match '^\s*<!--\s*team:column\s+([\w.\-]+)\s+([\w.\-]+)\s+([\w.\-]+)\s*-->\s*$') { $hdr = & $slot $Matches[1]; $sep = & $slot $Matches[2]; $prefix = $Matches[3] $j = $i + 1 while ($j -lt $lines.Count -and $lines[$j] -notmatch '^\|') { if ($lines[$j].Trim()) { throw "Document '$DocumentPath': team:column must be followed by its table" } $j++ } if ($j -ge $lines.Count) { throw "Document '$DocumentPath': team:column is not followed by a table" } $out.Add("$($lines[$j]) $hdr |"); $j++ $out.Add($sep); $j++ while ($j -lt $lines.Count -and $lines[$j] -match '^\|') { $key = ($lines[$j] -split '\|')[1].Trim() $out.Add("$($lines[$j]) $(& $slot "$prefix.$key") |"); $j++ } $i = $j; continue } if ($line -match '^\s*<!--\s*team:fill\s+(\d+)\s+([\w.\-]+)\s*-->\s*$') { $col = [int]$Matches[1]; $prefix = $Matches[2] $j = $i + 1 while ($j -lt $lines.Count -and $lines[$j] -notmatch '^\|') { if ($lines[$j].Trim()) { throw "Document '$DocumentPath': team:fill must be followed by its table" } $j++ } if ($j + 1 -ge $lines.Count) { throw "Document '$DocumentPath': team:fill is not followed by a table" } $out.Add($lines[$j]); $out.Add($lines[$j + 1]); $j += 2 while ($j -lt $lines.Count -and $lines[$j] -match '^\|') { $cells = $lines[$j] -split '\|' if ($col -lt 1 -or $col -ge $cells.Count - 1) { throw "Document '$DocumentPath': team:fill column $col is outside the table" } $cells[$col] = " $(& $slot "$prefix.$($cells[1].Trim())") " $out.Add($cells -join '|'); $j++ } $i = $j; continue } if ($line -match '^(?<lead>\s*[-*] )\[[ xX]\] (?<text>.*?)\s*<!--\s*team:check\s+(?<name>[\w.\-]+)\s*-->\s*$') { # A checklist item: the slot's first line starts with [x] or [ ], # which sets the box; the rest of that line follows the item's # text, and any further lines follow the item. $lead = $Matches.lead; $text = $Matches.text; $name = $Matches.name $exp = (& $slot $name) -split "`n" if ($exp[0] -notmatch '^\[(?<box>[ x])\]\s?(?<rest>.*)$') { throw "Slot '$name' must start with [x] or [ ] (it sets a checklist box)" } $first = "$lead[$($Matches.box)] $text" if ($Matches.rest) { $first += " $($Matches.rest)" } $out.Add($first) for ($k = 1; $k -lt $exp.Count; $k++) { $out.Add($exp[$k]) } $i++; continue } if ($line -match '^\s*<!--\s*team:slot\s+([\w.\-]+)\s*-->\s*$') { foreach ($l in ((& $slot $Matches[1]) -split "`n")) { $out.Add($l) } $i++; continue } $line = [regex]::Replace($line, '\s*<!--\s*team:slot\s+([\w.\-]+)\s*-->', { param($m) ' ' + (& $slot $m.Groups[1].Value) }) if ($AssetPrefix) { $line = $line.Replace('](assets/', "]($($AssetPrefix)assets/") } $out.Add($line) $i++ } $body = ($out -join "`n") -replace '^\n+', '' $leftover = [regex]::Match($body, '<!--\s*team:[^>]*-->') if ($leftover.Success) { throw "Document '$DocumentPath': unrecognised team marker '$($leftover.Value)'" } # Frontmatter, as the fixed renderer emits it (ADR-009): reporting.frontmatter # with {code} filled in, keys in ordinal order, date = the data's date. $inv = [System.Globalization.CultureInfo]::InvariantCulture $fmLines = [System.Collections.Generic.List[string]]::new() $fm = if ($Reporting) { $Reporting.frontmatter } else { $null } if ($fm) { $code = [string]$data.node $fmKeys = [string[]]@($fm.Keys); [array]::Sort($fmKeys, [System.StringComparer]::Ordinal) $fmLines.Add('---') foreach ($k in $fmKeys) { $v = $fm[$k] $s = if ($v -is [bool]) { if ($v) { 'true' } else { 'false' } } elseif ($v -is [int] -or $v -is [long] -or $v -is [double]) { [string]$v } else { '"' + ([string]$v).Replace('{code}', $code).Replace('\', '\\').Replace('"', '\"') + '"' } $fmLines.Add("$($k): $s") } if ('date' -notin $fmKeys) { $g = if ($data.gathered -is [datetime]) { ([datetime]$data.gathered).ToUniversalTime() } else { [datetime]::Parse([string]$data.gathered, $inv) } $fmLines.Add("date: $($g.ToString('yyyy-MM-dd', $inv))") } $fmLines.Add('---') $fmLines.Add('') } if (-not $OutputPath) { $stem = [System.IO.Path]::GetFileName($DataPath) -replace '[-.]?data\.json$', '' $OutputPath = Join-Path ([System.IO.Path]::GetDirectoryName($DataPath)) "$stem-report.md" } $text = (($fmLines -join "`n") + $(if ($fmLines.Count) { "`n" } else { '' }) + $body) [System.IO.File]::WriteAllText($OutputPath, $text, [System.Text.UTF8Encoding]::new($false)) return $OutputPath } |