diff --git a/src/ChannelForge/ChannelForge.psd1 b/src/ChannelForge/ChannelForge.psd1 index 4821352..f3883bd 100644 --- a/src/ChannelForge/ChannelForge.psd1 +++ b/src/ChannelForge/ChannelForge.psd1 @@ -124,6 +124,7 @@ FunctionsToExport = @( 'Get-ChannelForgeEventChannelReport' 'Set-ChannelForgeEventChannel' 'Get-ChannelForgeGuideReadiness' + 'Get-ChannelForgeGuideQualityReport' 'Get-ChannelForgeOneGuide' 'Get-ChannelForgeWebStatus' 'Read-ChannelForgeEpgSource' diff --git a/src/ChannelForge/Private/Get-ChannelForgeGuideQualityScorecard.ps1 b/src/ChannelForge/Private/Get-ChannelForgeGuideQualityScorecard.ps1 new file mode 100644 index 0000000..9643ca7 --- /dev/null +++ b/src/ChannelForge/Private/Get-ChannelForgeGuideQualityScorecard.ps1 @@ -0,0 +1,108 @@ +function Get-ChannelForgeGuideQualityScorecard { + <# + .SYNOPSIS + Turns the outputs of existing guide reports into six quality gates (guide-quality-scorecard/v1). Pure, report only. + + .DESCRIPTION + Contract: + - Inputs are report objects that already exist. Nothing is read from disk, written, merged or changed. + XguideReport = Get-ChannelForgeXguideReport; CategoryReport = Get-ChannelForgeCategoryReport; + ReadinessResult = Get-ChannelForgeGuideReadiness; Programme = programme rows (ChannelId or RawChannelId, Start, + Title, optional CanonicalEventId). + - Gates: Accuracy, Completeness, Freshness, Deduplication, Classification, Availability. + Each gate has Name, Verdict, Counts (plain numbers) and Reason (one line). + - Verdict rule: any Fail-level finding gives Fail; else any Review-level finding gives Review; else Pass. + A gate whose input was not supplied is NotMeasured, never Pass. No percentages. + Accuracy: Fail = readiness Contradiction. Review = xguide TitleDiffers or StartShift. + Completeness: Fail = a guide with no programmes. Review = xguide MissingChannel. + Freshness: Fail = a guide that ended before the build. Review = a guide more than 24 h behind, or readiness StaleSource. + Deduplication: Review = channels with the same title and start time and no CanonicalEventId. Count only, nothing is merged. + Classification: Review = any ambiguous (conflict) or unknown (no-rule) channel. An ambiguous category is never Pass. + Availability: Fail = readiness SourceUnavailable. Review = readiness Unresolved. + - Overall = the worst gate verdict (Fail, then Review). NotMeasured counts as Review for Overall. + - Totals carry the input channel counts so a caller can prove no channel was dropped. + #> + [CmdletBinding()] + param( + [AllowNull()][object]$XguideReport = $null, + [AllowNull()][object]$CategoryReport = $null, + [AllowNull()][object]$ReadinessResult = $null, + [AllowNull()][object[]]$Programme = $null + ) + + function New-Gate([string]$Name, [bool]$Measured, [System.Collections.IDictionary]$Counts, [string[]]$Fail, [string[]]$Review) { + $Fail = @($Fail | Where-Object { $_ }) + $Review = @($Review | Where-Object { $_ }) + if (-not $Measured) { $verdict = 'NotMeasured'; $reason = 'No report was supplied for this gate, so nothing is claimed.' } + elseif ($Fail.Count -gt 0) { $verdict = 'Fail'; $reason = $Fail -join '; ' } + elseif ($Review.Count -gt 0) { $verdict = 'Review'; $reason = $Review -join '; ' } + else { $verdict = 'Pass'; $reason = 'No problems found in the supplied report.' } + [pscustomobject][ordered]@{ Name = $Name; Verdict = $verdict; Counts = [pscustomobject]$Counts; Reason = $reason } + } + function Get-Number($Source, [string]$Name) { if ($null -eq $Source) { 0 } else { [int]$Source.$Name } } + function Get-DuplicateGroupCount([object[]]$Rows) { + $groups = @{} + foreach ($p in $Rows) { + $channel = if ([string]::IsNullOrEmpty($p.RawChannelId)) { [string]$p.ChannelId } else { [string]$p.RawChannelId } + $identity = $p.PSObject.Properties['CanonicalEventId'] + if ($identity -and -not [string]::IsNullOrWhiteSpace([string]$identity.Value)) { continue } + $key = '{0}|{1}' -f ([regex]::Replace(([string]$p.Title).Trim().ToLowerInvariant(), '\s+', ' ')), $p.Start.UtcTicks + if (-not $groups.ContainsKey($key)) { $groups[$key] = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::Ordinal) } + [void]$groups[$key].Add($channel) + } + @($groups.Values | Where-Object { $_.Count -gt 1 }).Count + } + + $x = $XguideReport; $r = $ReadinessResult + $xCounts = if ($x) { $x.Counts } else { $null } + $rCounts = if ($r) { $r.StateCounts } else { $null } + $guides = if ($x) { @($x.Guides) } else { @() } + $ended = @($guides | Where-Object { $_.State -ceq 'ended' }).Count + $empty = @($guides | Where-Object { $_.State -ceq 'empty' }).Count + $behind = [math]::Max(0, (Get-Number $xCounts 'GuideBehind') - $ended - $empty) + $titleDiffers = Get-Number $xCounts 'TitleDiffers'; $startShift = Get-Number $xCounts 'StartShift' + $contradiction = Get-Number $rCounts 'Contradiction'; $stale = Get-Number $rCounts 'StaleSource' + $unavailable = Get-Number $rCounts 'SourceUnavailable'; $unresolved = Get-Number $rCounts 'Unresolved' + $missing = Get-Number $xCounts 'MissingChannel' + + $rows = if ($CategoryReport) { @($CategoryReport.Rows) } else { @() } + $ambiguous = @($rows | Where-Object { $_.Decision -ceq 'conflict' }).Count + $unknown = @($rows | Where-Object { $_.Decision -ceq 'no-rule' }).Count + $high = @($rows | Where-Object { $_.Confidence -ceq 'high' }).Count + $dupGroups = if ($null -ne $Programme) { Get-DuplicateGroupCount @($Programme) } else { 0 } + + $gates = @( + New-Gate 'Accuracy' ($null -ne $x -or $null -ne $r) ([ordered]@{ TitleDiffers = $titleDiffers; StartShift = $startShift; Contradiction = $contradiction }) ` + @(if ($contradiction) { "$contradiction readiness contradictions" }) ` + @(if ($titleDiffers + $startShift) { "$titleDiffers title and $startShift start-time differences between guides" }) + New-Gate 'Completeness' ($null -ne $x) ([ordered]@{ MissingChannel = $missing; EmptyGuides = $empty }) ` + @(if ($empty) { "$empty guides have no programmes" }) ` + @(if ($missing) { "$missing channels are missing from some guides" }) + New-Gate 'Freshness' ($null -ne $x -or $null -ne $r) ([ordered]@{ EndedGuides = $ended; BehindGuides = $behind; StaleSource = $stale }) ` + @(if ($ended) { "$ended guides ended before this build" }) ` + @(if ($behind + $stale) { "$behind guides behind and $stale stale sources" }) + New-Gate 'Deduplication' ($null -ne $Programme) ([ordered]@{ DuplicateGroups = $dupGroups }) ` + @() @(if ($dupGroups) { "$dupGroups same-title same-time groups on different channels with no canonical identity" }) + New-Gate 'Classification' ($null -ne $CategoryReport) ([ordered]@{ High = $high; Ambiguous = $ambiguous; Unknown = $unknown }) ` + @() @(if ($ambiguous + $unknown) { "$ambiguous ambiguous and $unknown unknown channels" }) + New-Gate 'Availability' ($null -ne $r) ([ordered]@{ SourceUnavailable = $unavailable; Unresolved = $unresolved }) ` + @(if ($unavailable) { "$unavailable guide records have an unavailable source" }) ` + @(if ($unresolved) { "$unresolved guide records are unresolved" }) + ) + + $overall = 'Pass' + if (@($gates | Where-Object { $_.Verdict -in @('Review', 'NotMeasured') }).Count -gt 0) { $overall = 'Review' } + if (@($gates | Where-Object { $_.Verdict -ceq 'Fail' }).Count -gt 0) { $overall = 'Fail' } + + return [pscustomobject][ordered]@{ + SchemaVersion = 'guide-quality-scorecard/v1' + Overall = $overall + Totals = [pscustomobject][ordered]@{ + CategoryChannelCount = if ($CategoryReport) { [int]$CategoryReport.ChannelCount } else { $null } + XguideSharedChannels = if ($x) { [int]$x.SharedChannelCount } else { $null } + ReadinessRecordCount = if ($r) { @($r.Records).Count } else { $null } + ProgrammeCount = if ($null -ne $Programme) { @($Programme).Count } else { $null } + } + Gates = $gates + } +} diff --git a/src/ChannelForge/Public/Get-ChannelForgeGuideQualityReport.ps1 b/src/ChannelForge/Public/Get-ChannelForgeGuideQualityReport.ps1 new file mode 100644 index 0000000..6003c35 --- /dev/null +++ b/src/ChannelForge/Public/Get-ChannelForgeGuideQualityReport.ps1 @@ -0,0 +1,20 @@ +function Get-ChannelForgeGuideQualityReport { + <# + .SYNOPSIS + Shows six guide quality gates (accuracy, completeness, freshness, deduplication, classification, availability) in one report. + + .DESCRIPTION + Read-only report (contract guide-quality-scorecard/v1). Pass in the outputs of the existing reports: + Get-ChannelForgeXguideReport, Get-ChannelForgeCategoryReport, Get-ChannelForgeGuideReadiness and the programme rows. + A gate with no input is NotMeasured, never Pass. It writes nothing and changes nothing. + #> + [CmdletBinding()] + param( + [AllowNull()][object]$XguideReport = $null, + [AllowNull()][object]$CategoryReport = $null, + [AllowNull()][object]$ReadinessResult = $null, + [AllowNull()][object[]]$Programme = $null + ) + + return Get-ChannelForgeGuideQualityScorecard -XguideReport $XguideReport -CategoryReport $CategoryReport -ReadinessResult $ReadinessResult -Programme $Programme +} diff --git a/tests/unit/GuideQualityScorecard.Tests.ps1 b/tests/unit/GuideQualityScorecard.Tests.ps1 new file mode 100644 index 0000000..fff486a --- /dev/null +++ b/tests/unit/GuideQualityScorecard.Tests.ps1 @@ -0,0 +1,110 @@ +BeforeAll { + $script:RepoRoot = Split-Path -Parent (Split-Path -Parent $PSScriptRoot) + Import-Module (Join-Path $script:RepoRoot 'src\ChannelForge\ChannelForge.psd1') -Force + + function New-Xguide([int]$Missing = 0, [string]$State = 'ok', [int]$Behind = 0) { + [pscustomobject]@{ + Contract = 'xguide-compare/v1'; SharedChannelCount = 4 + Guides = @([pscustomobject]@{ SourceId = 'a'; State = 'ok' }, [pscustomobject]@{ SourceId = 'b'; State = $State }) + Counts = [pscustomobject]@{ MissingChannel = $Missing; StartShift = 0; TitleDiffers = 0; Unmatched = 0; GuideBehind = $Behind } + } + } + function New-Categories([string]$Decision = 'name-and-group') { + $conf = if ($Decision -ceq 'conflict') { 'none' } else { 'high' } + [pscustomobject]@{ + ChannelCount = 3 + Rows = @( + [pscustomobject]@{ ChannelKey = 'k1'; Decision = 'name-and-group'; Confidence = 'high' } + [pscustomobject]@{ ChannelKey = 'k2'; Decision = 'name-and-group'; Confidence = 'high' } + [pscustomobject]@{ ChannelKey = 'k3'; Decision = $Decision; Confidence = $conf } + ) + } + } + function New-Readiness { + [pscustomobject]@{ + Records = @([pscustomobject]@{ ChannelReference = 'c1' }, [pscustomobject]@{ ChannelReference = 'c2' }) + StateCounts = [pscustomobject]@{ Confirmed = 2; Contradiction = 0; StaleSource = 0; SourceUnavailable = 0; Unresolved = 0 } + } + } + function New-Programmes { + $start = [datetimeoffset]::Parse('2026-10-01T12:00:00Z') + @( + New-ChannelForgeProgramme -ChannelId 'one' -Start $start -End $start.AddHours(1) -Title 'Show A' -SourceId 'p' + New-ChannelForgeProgramme -ChannelId 'two' -Start $start -End $start.AddHours(1) -Title 'Show B' -SourceId 'p' + ) + } + function Get-Card($Params) { InModuleScope ChannelForge -Parameters @{ P = $Params } { Get-ChannelForgeGuideQualityScorecard @P } } + function Get-Gate($Card, [string]$Name) { @($Card.Gates | Where-Object { $_.Name -ceq $Name })[0] } + function New-CleanInput { @{ XguideReport = (New-Xguide); CategoryReport = (New-Categories); ReadinessResult = (New-Readiness); Programme = (New-Programmes) } } +} + +Describe 'Guide quality scorecard: what the owner sees' { + It 'gives six Pass gates and Overall Pass for clean input' { + $card = Get-Card (New-CleanInput) + $card.SchemaVersion | Should -Be 'guide-quality-scorecard/v1' + @($card.Gates).Count | Should -Be 6 + @($card.Gates | Where-Object { $_.Verdict -ne 'Pass' }) | Should -BeNullOrEmpty + $card.Overall | Should -Be 'Pass' + } + + It 'makes completeness Review for a missing channel and Overall follows' { + $in = New-CleanInput; $in.XguideReport = New-Xguide -Missing 2 + $card = Get-Card $in + (Get-Gate $card 'Completeness').Verdict | Should -Be 'Review' + (Get-Gate $card 'Completeness').Counts.MissingChannel | Should -Be 2 + $card.Overall | Should -Be 'Review' + } + + It 'does not pass freshness for a guide that ended before the build' { + $in = New-CleanInput; $in.XguideReport = New-Xguide -State 'ended' -Behind 1 + $card = Get-Card $in + (Get-Gate $card 'Freshness').Verdict | Should -Be 'Fail' + $card.Overall | Should -Be 'Fail' + } + + It 'makes an ambiguous category Review, never Pass' { + $in = New-CleanInput; $in.CategoryReport = New-Categories -Decision 'conflict' + $gate = Get-Gate (Get-Card $in) 'Classification' + $gate.Verdict | Should -Be 'Review' + $gate.Counts.Ambiguous | Should -Be 1 + } + + It 'counts same title and time on different channels with no identity (Deduplication Review)' { + $start = [datetimeoffset]::Parse('2026-10-01T12:00:00Z') + $in = New-CleanInput + $in.Programme = @( + New-ChannelForgeProgramme -ChannelId 'one' -Start $start -End $start.AddHours(1) -Title 'Same Show' -SourceId 'p' + New-ChannelForgeProgramme -ChannelId 'two' -Start $start -End $start.AddHours(1) -Title 'same show' -SourceId 'p' + ) + $gate = Get-Gate (Get-Card $in) 'Deduplication' + $gate.Verdict | Should -Be 'Review' + $gate.Counts.DuplicateGroups | Should -Be 1 + } + + It 'reports NotMeasured, never Pass, for a missing input report' { + $card = Get-Card @{ CategoryReport = (New-Categories) } + foreach ($name in 'Accuracy', 'Completeness', 'Freshness', 'Deduplication', 'Availability') { + (Get-Gate $card $name).Verdict | Should -Be 'NotMeasured' + } + (Get-Gate $card 'Classification').Verdict | Should -Be 'Pass' + $card.Overall | Should -Be 'Review' + } + + It 'keeps the input channel totals and does not change its inputs' { + $in = New-CleanInput + $before = $in | ConvertTo-Json -Depth 8 + $card = Get-Card $in + $again = Get-Card $in + $card.Totals.CategoryChannelCount | Should -Be 3 + $card.Totals.XguideSharedChannels | Should -Be 4 + $card.Totals.ReadinessRecordCount | Should -Be 2 + $card.Totals.ProgrammeCount | Should -Be 2 + ($in | ConvertTo-Json -Depth 8) | Should -Be $before + ($card | ConvertTo-Json -Depth 8) | Should -Be ($again | ConvertTo-Json -Depth 8) + } + + It 'is returned by the public command' { + $card = Get-ChannelForgeGuideQualityReport -CategoryReport (New-Categories) + $card.SchemaVersion | Should -Be 'guide-quality-scorecard/v1' + } +}