Public/ConvertTo-GovernancePreflightReport.ps1
|
function ConvertTo-GovernancePreflightReport { <# .SYNOPSIS Renders one team's preflight fix report as markdown from the two files preflight already wrote — the data document (facts) and the findings document (verdicts) — plus, when present, an observations fragment written separately (by a person, or by the preflight-report skill). This function OWNS the document (ADR-009). Every count, table and label in it is copied from the inputs; nothing is computed by anyone who might get it wrong. The fragment is inserted between two markers in one bounded section and can never reach a table. Idempotent: the same inputs produce the same bytes, and re-running after the fragment appears produces the same document plus that section. Engagement vocabulary (rule numbers, task ids, owner lanes) comes from the finding objects and the optional -Labels map; the name of the standard they refer to and the candidate-tag threshold come from -Reporting. The engine itself names no customer document. #> [CmdletBinding()] param( [Parameter(Mandatory)][string]$DataPath, [Parameter(Mandatory)][string]$FindingsPath, [string]$ObservationsPath = '', [string]$OutputPath = '', [object]$Labels = $null, # check id -> @{ rule; task; lane; ... } [object]$Reporting = $null # @{ standard; audience; candidateTagMinUses; iterationTop; title; # preamble; scopeNote; glossary; observationsLead; labelColumns } ) foreach ($p in $DataPath, $FindingsPath) { if (-not (Test-Path -LiteralPath $p)) { throw "ConvertTo-GovernancePreflightReport: 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." } $code = [string]$data.node $threshold = if ($Reporting -and $Reporting.candidateTagMinUses) { [int]$Reporting.candidateTagMinUses } else { 20 } $iterTop = if ($Reporting -and $Reporting.iterationTop) { [int]$Reporting.iterationTop } else { 7 } $title = if ($Reporting -and $Reporting.title) { [string]$Reporting.title } else { 'Pre-migration readiness check' } # Default beside the inputs, carrying the same self-describing stem the # data file has ('<program>-preflight-<CODE>-data.json' -> '…-report.md'), # so a report lifted out of the folder still says what it is. if (-not $OutputPath) { $stem = [System.IO.Path]::GetFileName($DataPath) -replace '[-.]?data\.json$', '' $name = if ($stem) { "$stem-report.md" } else { "preflight-$code-report.md" } $OutputPath = Join-Path ([System.IO.Path]::GetDirectoryName($DataPath)) $name } # ── helpers ──────────────────────────────────────────────────────────── $inv = [System.Globalization.CultureInfo]::InvariantCulture $n = { param($v) ([long]$v).ToString('N0', $inv) } $esc = { param($s) ([string]$s) -replace '\|', '\|' -replace "`r?`n", ' ' } $L = [System.Collections.Generic.List[string]]::new() $table = { param([string[]]$header, [object[]]$rows) $L.Add('| ' + (($header | ForEach-Object { & $esc $_ }) -join ' | ') + ' |') $L.Add('|' + (($header | ForEach-Object { ' --- ' }) -join '|') + '|') foreach ($r in $rows) { $L.Add('| ' + ((@($r) | ForEach-Object { & $esc $_ }) -join ' | ') + ' |') } $L.Add('') } $findings = @($fin.findings) $byCheck = @{} foreach ($f in $findings) { $k = [string]$f.check if (-not $byCheck.ContainsKey($k)) { $byCheck[$k] = [System.Collections.Generic.List[object]]::new() } $byCheck[$k].Add($f) } $count = { param($check) if ($byCheck.ContainsKey($check)) { $byCheck[$check].Count } else { 0 } } # Label columns: whatever the program attached, in `reporting.labelColumns` # order when declared, else rule/task/lane first. $engineFields = @('class', 'check', 'subject', 'message', 'source', 'workItems', 'tags', 'examples', 'group', 'team', 'sourceTeam', 'suggestions', 'why') $labelKeys = [System.Collections.Generic.List[string]]::new() $prefKeys = if ($Reporting -and $Reporting.labelColumns) { @($Reporting.labelColumns | ForEach-Object { [string]$_ }) } else { @('rule', 'task', 'lane') } foreach ($pref in $prefKeys) { $labelKeys.Add($pref) } if ($Labels) { foreach ($c in @($Labels.Keys)) { foreach ($k in @($Labels[$c].Keys)) { if ($k -notin $labelKeys) { $labelKeys.Add([string]$k) } } } } foreach ($f in $findings) { foreach ($k in @($f.Keys)) { if ($k -notin $engineFields -and $k -notin $labelKeys) { $labelKeys.Add([string]$k) } } } $labelsFor = { param($check) $out = [ordered]@{} if ($Labels -and $Labels.Contains($check)) { foreach ($k in @($Labels[$check].Keys)) { $out[[string]$k] = [string]$Labels[$check][$k] } } if ($byCheck.ContainsKey($check)) { $first = $byCheck[$check][0] foreach ($k in $labelKeys) { if (-not $out.Contains($k) -and $first.Contains($k)) { $out[$k] = [string]$first[$k] } } } $out } $anyLabels = $false foreach ($c in @($byCheck.Keys) + @(if ($Labels) { $Labels.Keys })) { if ((& $labelsFor $c).Count -gt 0) { $anyLabels = $true; break } } $usedLabelKeys = @($labelKeys | Where-Object { $k = $_; @(@($byCheck.Keys) + @(if ($Labels) { $Labels.Keys }) | Where-Object { (& $labelsFor $_).Contains($k) }).Count -gt 0 }) $titleCase = { param($s) ([string]$s).Substring(0, 1).ToUpperInvariant() + ([string]$s).Substring(1) } # ── facts ───────────────────────────────────────────────────────────── $areas = @($data.areas) $unmappedAreas = @($data.unmappedAreas | Where-Object { $_ }) $srcRoot = [string]$data.source.areaPath $subAreas = @($areas | Where-Object { [string]$_.source -ne $srcRoot }) $orphanSet = @{}; foreach ($f in @(if ($byCheck.ContainsKey('area.orphan')) { $byCheck['area.orphan'] })) { $orphanSet[[string]$f.source] = $true } $families = @(if ($byCheck.ContainsKey('tag.disallowed')) { $byCheck['tag.disallowed'] }) $unsanct = @(if ($byCheck.ContainsKey('tag.unsanctioned')) { $byCheck['tag.unsanctioned'] }) $asColumn = @(if ($byCheck.ContainsKey('tag.boardColumn')) { $byCheck['tag.boardColumn'] }) $toRetire = @(if ($byCheck.ContainsKey('tag.retire')) { $byCheck['tag.retire'] }) $famTags = ($families | ForEach-Object { [long]$_.tags } | Measure-Object -Sum).Sum $famItems = ($families | ForEach-Object { [long]$_.workItems } | Measure-Object -Sum).Sum $teamsDecl = @($data.source.teams | Where-Object { $_ }).Count -gt 0 $reposDecl = $null -ne $data.source.repoInclude $authoredN = @($data.authored.members).Count + @($data.authored.teamAdmins).Count $unresolved = @(if ($byCheck.ContainsKey('member.unresolvable')) { $byCheck['member.unresolvable'] }) + @(if ($byCheck.ContainsKey('teamAdmin.unresolvable')) { $byCheck['teamAdmin.unresolvable'] }) $unauth = @(if ($byCheck.ContainsKey('member.unauthored')) { $byCheck['member.unauthored'] }) $repoOrph = @(if ($byCheck.ContainsKey('repo.orphan')) { $byCheck['repo.orphan'] }) $errors = @(if ($byCheck.ContainsKey('preflight.error')) { $byCheck['preflight.error'] }) $infoLines = @($fin.info) $sanctionedUnused = @($infoLines | ForEach-Object { if ($_ -match '^sanctioned tag not in use at the source \(apply seeds it in the target\): (.+)$') { $Matches[1] } }) # ── document ────────────────────────────────────────────────────────── # Optional YAML frontmatter. A publishing system (engage-system, say) will # not accept a deliverable without it: brand, designation, kind. Emitting it # HERE is what keeps the rendered report a valid deliverable source, so # publishing stays a copy and never becomes an edit — the same reason no # other line of this document is written by hand. A report that has to be # hand-topped before it can ship is a report that goes stale the first time # anyone re-runs the analysis. # # Values come from `sources.yaml reporting.frontmatter:`; {code} and {title} # are substituted so one declaration covers every team. `date` defaults to # the date the DATA was gathered, not today, so re-rendering unchanged data # produces unchanged bytes. $fm = if ($Reporting) { $Reporting.frontmatter } else { $null } if ($fm) { $yamlScalar = { param($v) if ($v -is [bool]) { return $(if ($v) { 'true' } else { 'false' }) } if ($v -is [int] -or $v -is [long] -or $v -is [double] -or $v -is [decimal]) { return [string]$v } $s = ([string]$v).Replace('{code}', $code).Replace('{title}', $title) '"' + $s.Replace('\', '\\').Replace('"', '\"') + '"' } # Ordinal sort, because the YAML reader hands back an unordered map and # PowerShell does not promise a stable enumeration order for one. Authored # order is unrecoverable here, so the alternative to sorting is a document # whose first ten lines shuffle between runs — which would break the # byte-for-byte determinism the rest of this renderer is built on. $fmKeys = [string[]]@($fm.Keys) [array]::Sort($fmKeys, [System.StringComparer]::Ordinal) $L.Add('---') foreach ($k in $fmKeys) { $L.Add("$([string]$k): $(& $yamlScalar $fm[$k])") } if ('date' -notin $fmKeys) { $d = if ($data.gathered -is [datetime]) { ([datetime]$data.gathered).ToUniversalTime().ToString('yyyy-MM-dd', $inv) } else { $t = [datetime]::MinValue if ([datetime]::TryParse([string]$data.gathered, $inv, [System.Globalization.DateTimeStyles]::AdjustToUniversal, [ref]$t)) { $t.ToString('yyyy-MM-dd', $inv) } else { '' } } if ($d) { $L.Add("date: $d") } } $L.Add('---') $L.Add('') } $L.Add("# $code — $title") $L.Add('') # Framing notes (preamble, scope note, glossary, observations lead) are # program prose from `reporting:`, maintained by hand there. The engine # renders them verbatim and puts no number in them except {label}/{date}. $gatheredDate = if ($data.gathered -is [datetime]) { ([datetime]$data.gathered).ToUniversalTime().ToString('d MMMM yyyy', $inv) } else { [string]$data.gathered } $prose = { param($s) ([string]$s).Trim().Replace('{code}', $code).Replace('{date}', $gatheredDate).Replace('{label}', [string]$data.scope.label) } if ($Reporting -and $Reporting.preamble) { foreach ($line in ((& $prose $Reporting.preamble) -split "`r?`n")) { $L.Add("> $line".TrimEnd()) } $L.Add('') } $head = [System.Collections.Generic.List[object]]::new() $head.Add(@('**Team**', "``$code``")) $head.Add(@('**Today**', "``$($data.source.org)`` / ``$($data.source.project)`` / ``$srcRoot`` — $(& $n $data.workItems.count) work items")) $head.Add(@('**Destination**', "``$($data.target.org)`` / ``$($data.target.project)`` / ``$($data.target.root)``")) # ConvertFrom-Json turns the ISO string back into a DateTime; render it # invariantly so the document is the same bytes on every machine. $gathered = if ($data.gathered -is [datetime]) { ([datetime]$data.gathered).ToUniversalTime().ToString("yyyy-MM-dd HH:mm 'UTC'", $inv) } else { [string]$data.gathered } $head.Add(@('**Data gathered**', $gathered)) # Never let a reader guess which work items these counts cover. An # unscoped run includes archive nobody will migrate, and saying so is the # prompt that gets the migration query written. # The query itself is in the appendix; the cell says what it selects and, # via `reporting.scopeNote`, how that compares with the program's own scope. $hasQuery = $data.scope -and $data.scope.query $scopeCell = if ($hasQuery) { $lbl = [string]$data.scope.label $s = "$(if ($lbl) { "$lbl " })(query in Appendix A)." if ($Reporting -and $Reporting.scopeNote) { $s += ' ' + (& $prose $Reporting.scopeNote) } else { $s += " Taken on $gatheredDate." } $s } else { '**every work item under the area, archive included** — no migration query declared' } $head.Add(@('**Work items checked**', $scopeCell)) if ($Reporting -and $Reporting.standard) { $head.Add(@('**Measured against**', [string]$Reporting.standard)) } if ($Reporting -and $Reporting.audience) { $head.Add(@('**Audience**', [string]$Reporting.audience)) } # Checks that could not run count in the headline: a gap of zero with two # checks skipped is not a team at the target. $notChecked = @(@{ off = -not $teamsDecl; what = 'source-team' }, @{ off = -not $reposDecl; what = 'repository' } | Where-Object { $_.off }) $ncText = if ($notChecked.Count) { ", plus $($notChecked.Count) not checked.** A full readiness picture needs the $(@($notChecked.what) -join ' and ') declaration$(if ($notChecked.Count -gt 1) { 's' }) below." } else { '.**' } $result = if ($errors.Count -gt 0) { "**ERROR** — the gather did not complete; see Errors" } elseif ($findings.Count -eq 0 -and $notChecked.Count -eq 0) { '**Matches the proposed target** — no gaps found' } else { "**Gap to the proposed target: $(& $n $findings.Count) item$(if ($findings.Count -ne 1) { 's' })$ncText" } $head.Add(@('**Result**', $result)) & $table @('', '') $head if ($errors.Count -gt 0) { $L.Add('## Errors'); $L.Add('') foreach ($e in $errors) { $L.Add("- $($e.message)"); if ($e.why) { $L.Add(" - **Why:** $($e.why)") } } $L.Add('') } # Summary $L.Add('## Summary'); $L.Add('') $catalogue = @( @{ check = 'area.orphan'; label = 'Area paths not authored in the target'; result = { $c = & $count 'area.orphan'; if ($c) { "$(& $n $c) of $(& $n $subAreas.Count) sub-areas differ" } else { "$(& $n $subAreas.Count) sub-areas — matches" } } }, @{ check = 'area.unmapped'; label = 'Selected source areas without target placement'; result = { if ($unmappedAreas.Count) { "$(& $n $unmappedAreas.Count) area$(if ($unmappedAreas.Count -ne 1) { 's' }) differ" } else { '0 areas — matches' } } }, @{ check = 'tag.disallowed'; label = 'Tags: machine-generated families'; result = { if ($families.Count) { "$($families.Count) families, $(& $n $famTags) tags on $(& $n $famItems) work items" } else { 'none — matches' } } }, @{ check = 'tag.boardColumn'; label = 'Tags that become board columns'; result = { if ($asColumn.Count) { "$(& $n $asColumn.Count) tags" } else { 'none declared yet' } } }, @{ check = 'tag.retire'; label = 'Tags to retire outright'; result = { if ($toRetire.Count) { "$(& $n $toRetire.Count) tags" } else { 'none declared yet' } } }, @{ check = 'tag.unsanctioned'; label = 'Tags with no destination decided'; result = { if ($unsanct.Count) { "$(& $n $unsanct.Count) tags" } else { 'none — matches' } } }, @{ check = 'repo.orphan'; label = 'Repositories not authored'; result = { if (-not $reposDecl) { 'not checked — no repository filter declared' } elseif ($repoOrph.Count) { "$(& $n $repoOrph.Count) of $(& $n @($data.repos).Count) repos differ" } else { "matches — $(& $n @($data.repos).Count) repos, all authored" } } }, @{ check = 'member.unresolvable'; label = 'Authored people the target cannot resolve'; result = { if ($unresolved.Count) { "$(& $n $unresolved.Count) of $(& $n $authoredN) differ" } elseif ($authoredN -eq 1) { 'matches — 1 authored, resolves' } else { "matches — $(& $n $authoredN) authored, all resolve" } } }, @{ check = 'member.unauthored'; label = 'People in the source team today, not authored'; result = { if (-not $teamsDecl) { 'not checked — no source teams declared' } elseif ($unauth.Count) { "$(& $n $unauth.Count) of $(& $n @($data.population.Keys).Count) differ" } else { "matches — $(& $n @($data.population.Keys).Count) people, all authored" } } } ) $hdr = @('Check', 'Result') + @($usedLabelKeys | ForEach-Object { & $titleCase $_ }) # Rows are emitted with a leading comma throughout this function: a bare # array coming out of a foreach statement unrolls into single cells. $rows = foreach ($c in $catalogue) { $lab = & $labelsFor $c.check if ($c.check -eq 'member.unresolvable' -and $lab.Count -eq 0) { $lab = & $labelsFor 'teamAdmin.unresolvable' } , (@($c.label, (& $c.result)) + @($usedLabelKeys | ForEach-Object { if ($lab.Contains($_)) { $lab[$_] } else { '' } })) } & $table $hdr @($rows) if ($Reporting -and $Reporting.glossary) { $L.Add((& $prose $Reporting.glossary)); $L.Add('') } if ($notChecked.Count) { $decl = @(if (-not $teamsDecl) { "the team's source team(s)" }; if (-not $reposDecl) { 'its repository filter' }) $L.Add("To run the check$(if ($notChecked.Count -gt 1) { 's' }) marked ""not checked"", declare $($decl -join ' and ')."); $L.Add('') } # 1. Area paths $L.Add("## 1. Area paths that fold to tags — $(& $n (& $count 'area.orphan')) of $(& $n $subAreas.Count) sub-areas"); $L.Add('') $L.Add('In the proposed target, an area path means one thing: who answers for the work. A sub-area that is authored has a node to land on; one that is not folds — to a tag, or to nothing. Work items are those sitting directly on each path.'); $L.Add('') $areaRows = foreach ($a in ($areas | Sort-Object { -[long]$_.workItems }, { [string]$_.source })) { $src = [string]$a.source $st = if ($src -eq $srcRoot) { 'the team root' } elseif ($orphanSet.ContainsKey($src)) { 'folds — not authored' } else { "authored as ``$([string]$a.target)``" } , @((& $n $a.workItems), "``$src``", $st) } $areaRows += @(foreach ($a in ($unmappedAreas | Sort-Object { -[long]$_.workItems }, { [string]$_.source })) { , @((& $n $a.workItems), "``$($a.source)``", 'outside source root — target placement required') }) & $table @('Work items', 'Area path today', 'In the target') @($areaRows) # 2. Tags $L.Add("## 2. Tags — $(& $n @($data.tags.Keys).Count) distinct tags in use"); $L.Add('') # Sub-sections are lettered as they appear, so an empty one leaves no gap. $sub = [ref][int][char]'a' $next = { $c = [char]$sub.Value; $sub.Value++; "2$c" } $L.Add("### $(& $next). Machine-generated families"); $L.Add('') if ($families.Count -eq 0) { $L.Add('None matched a disallowed pattern.'); $L.Add('') } else { $L.Add('Each row is one disallowed pattern. These are reported as families because no one applied them by hand, and the programme removes them as families.'); $L.Add('') # @() keeps a single family as one row; a bare assignment unrolls it into cells. $famRows = @(foreach ($f in ($families | Sort-Object { -[long]$_.tags })) { , @("``$($f.subject)``", (& $n $f.tags), (& $n $f.workItems), (@($f.examples | Select-Object -First 3) -join ', ')) }) & $table @('Pattern', 'Distinct tags', 'Work items', 'Examples') @($famRows) } if ($asColumn.Count -gt 0) { $L.Add("### $(& $next). Tags that become board columns — $(& $n $asColumn.Count)"); $L.Add('') $L.Add('These name where work has got to, not what it is. A board column carries that, and the tag stops being applied once the column exists — so this is a board change, not a vocabulary decision.'); $L.Add('') & $table @('Uses', 'Tag') @(foreach ($t in ($asColumn | Sort-Object { -[long]$_.workItems }, { [string]$_.subject })) { , @((& $n $t.workItems), $t.subject) }) } if ($toRetire.Count -gt 0) { $L.Add("### $(& $next). Tags to retire outright — $(& $n $toRetire.Count)"); $L.Add('') $L.Add('Declared for removal with no replacement. Nothing depends on them.'); $L.Add('') & $table @('Uses', 'Tag') @(foreach ($t in ($toRetire | Sort-Object { -[long]$_.workItems }, { [string]$_.subject })) { , @((& $n $t.workItems), $t.subject) }) } $L.Add("### $(& $next). Tags with no destination decided — $(& $n $unsanct.Count)"); $L.Add('') $none = if ($asColumn.Count -eq 0 -and $toRetire.Count -eq 0) { ' No tags have yet been declared as board columns or for retirement.' } else { '' } $L.Add("Each of these needs one of three answers: **sanction** it into the vocabulary, make it a **board column**, or **retire** it. Anything still undecided at migration shows up on the target's audit from day one, so it is worth deciding first.$none"); $L.Add('') if ($unsanct.Count -gt 0) { $buckets = [ordered]@{ '1 work item' = 0; '2 to 5' = 0; '6 to 20' = 0; '21 to 50' = 0; 'more than 50' = 0 } foreach ($t in $unsanct) { $w = [long]$t.workItems $k = if ($w -le 1) { '1 work item' } elseif ($w -le 5) { '2 to 5' } elseif ($w -le 20) { '6 to 20' } elseif ($w -le 50) { '21 to 50' } else { 'more than 50' } $buckets[$k]++ } & $table @('Used on', 'Distinct tags') @(foreach ($k in $buckets.Keys) { , @($k, (& $n $buckets[$k])) }) $cands = @($unsanct | Where-Object { [long]$_.workItems -gt $threshold } | Sort-Object { -[long]$_.workItems }, { [string]$_.subject }) $L.Add("Tags used on more than $(& $n $threshold) work items — we suggest deciding these first ($(& $n $cands.Count)):"); $L.Add('') if ($cands.Count -gt 0) { & $table @('Uses', 'Tag') @(foreach ($t in $cands) { , @((& $n $t.workItems), $t.subject) }) } else { $L.Add('None.'); $L.Add('') } } if ($sanctionedUnused.Count -gt 0) { $L.Add("Sanctioned tags not yet in use here, created in the target automatically: $(($sanctionedUnused | Sort-Object) -join ', ').") $L.Add('') } # 3. People $L.Add('## 3. People'); $L.Add('') if ($unresolved.Count -eq 0) { if ($authoredN -eq 1) { $L.Add('The 1 authored person (including team admins) resolves in the target organisation.') } else { $L.Add("All $(& $n $authoredN) authored people (including team admins) resolve in the target organisation.") } } else { $L.Add("$(& $n $unresolved.Count) authored entries do not resolve in the target organisation:"); $L.Add('') & $table @('UPN', 'Where', 'Did you mean') @(foreach ($u in $unresolved) { , @($u.subject, $(if ($u.group) { $u.group } else { $u.team }), (@($u.suggestions) -join ', ')) }) } $L.Add('') if (-not $teamsDecl) { $L.Add('**Not checked:** no source teams are declared, so whether anyone working here today is missing from the authored list is unknown. Declaring the source team(s) enables this check.') } elseif ($unauth.Count -eq 0) { $L.Add("Everyone in the declared source team(s) ($(& $n @($data.population.Keys).Count) people) is authored.") } else { $L.Add("$(& $n $unauth.Count) people work here today and are not authored — they lose access at migration unless added or deliberately left out:"); $L.Add('') & $table @('UPN', 'Source team') @(foreach ($u in $unauth) { , @($u.subject, $u.sourceTeam) }) } $L.Add('') # 4. Repositories $L.Add('## 4. Repositories'); $L.Add('') if (-not $reposDecl) { $L.Add('**Not checked:** no repository filter is declared for this team. Declaring one enables the naming check.') } elseif ($repoOrph.Count -eq 0) { $L.Add("All $(& $n @($data.repos).Count) matched repositories have an authored name.") } else { $L.Add("$(& $n $repoOrph.Count) of $(& $n @($data.repos).Count) matched repositories have no authored name:"); $L.Add('') & $table @('Repository') @(foreach ($r in $repoOrph) { , @($r.subject) }) } $L.Add('') # 5. Iterations $iters = @($data.iterations.Keys | Sort-Object { -[long]$data.iterations[$_] }, { $_ } | Select-Object -First $iterTop) if ($iters.Count -gt 0) { $L.Add("## 5. Iteration paths in use — top $(& $n $iters.Count) of $(& $n @($data.iterations.Keys).Count)"); $L.Add('') $L.Add('Context for the migration mapping, not a gap.'); $L.Add('') # Backticked like every other path in this document. Not cosmetic: an # iteration path is full of backslashes, and a bare `Petrel\2026\S2\W6` in a # markdown table becomes `\S2` and `\W6` — undefined control sequences — the # moment anyone renders this to PDF through pandoc/LaTeX. Code spans pass # through verbatim. & $table @('Work items', 'Iteration path') @(foreach ($i in $iters) { , @((& $n $data.iterations[$i]), "``$i``") }) } # 6. Observations (the only section anyone other than this function writes) $L.Add('## 6. Observations'); $L.Add('') if ($Reporting -and $Reporting.observationsLead) { $L.Add((& $prose $Reporting.observationsLead)); $L.Add('') } $L.Add('<!-- observations:begin -->') # Observations comment on a specific analysis. If the findings have been # regenerated since the fragment was written, the commentary may contradict # the tables above it - which is exactly how a report ends up arguing with # itself - so it is WITHHELD rather than spliced. Modification time is the # test on purpose: a confused writer cannot forge it the way it could forge # a stamp inside the file. $obsStale = $false if ($ObservationsPath -and (Test-Path -LiteralPath $ObservationsPath)) { $obsStale = (Get-Item -LiteralPath $ObservationsPath).LastWriteTimeUtc -lt (Get-Item -LiteralPath $FindingsPath).LastWriteTimeUtc } if ($ObservationsPath -and (Test-Path -LiteralPath $ObservationsPath) -and -not $obsStale) { $frag = (Get-Content -LiteralPath $ObservationsPath -Raw) -replace "`r`n", "`n" foreach ($line in ($frag.Trim() -split "`n")) { $L.Add($line) } } elseif ($obsStale) { $L.Add("_Observations withheld: ``$(Split-Path -Leaf $ObservationsPath)`` was written before the current analysis, so it may contradict the tables above. Re-run the observation step, or delete the file._") } else { $L.Add('_No observations were generated for this report._') } $L.Add('<!-- observations:end -->') $L.Add('') # The per-check "what this team owes" list was dropped: it repeated the # Summary table row for row, with the same labels. # Appendix A. The exact selection and patterns, so the tables above can be # reproduced. Kept out of the header because a WIQL block is not a sentence. if ($hasQuery -or $families.Count -gt 0) { $L.Add('## Appendix A — Query and tag patterns'); $L.Add('') if ($hasQuery) { $L.Add("**Query (WIQL)** used for this check, as run on $($gatheredDate):"); $L.Add('') $L.Add('```sql') foreach ($line in (([string]$data.scope.query).Trim() -split "`r?`n")) { $L.Add($line.TrimEnd()) } $L.Add('```'); $L.Add('') } if ($families.Count -gt 0) { $L.Add('**Machine-generated tag patterns:**'); $L.Add('') & $table @('Pattern') @(foreach ($f in ($families | Sort-Object { -[long]$_.tags })) { , @("``$($f.subject)``") }) } } $L.Add('---') $L.Add("_Rendered by NKDAgility.AzureDevOps.Governance from ``$(Split-Path -Leaf $DataPath)`` and ``$(Split-Path -Leaf $FindingsPath)``. Every number above is copied from those files; the framing notes are maintained by hand in the program's reporting settings, and they and the Observations section are the only prose written by anyone else._") $L.Add('') $outDir = [System.IO.Path]::GetDirectoryName($OutputPath) if ($outDir -and -not (Test-Path -LiteralPath $outDir)) { New-Item -ItemType Directory -Path $outDir -Force | Out-Null } [System.IO.File]::WriteAllText($OutputPath, ($L -join "`n"), [System.Text.UTF8Encoding]::new($false)) return $OutputPath } |