Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions src/ChannelForge/ChannelForge.psd1
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,7 @@ FunctionsToExport = @(
'Get-ChannelForgeEventChannelReport'
'Set-ChannelForgeEventChannel'
'Get-ChannelForgeGuideReadiness'
'Get-ChannelForgeGuideQualityReport'
'Get-ChannelForgeOneGuide'
'Get-ChannelForgeWebStatus'
'Read-ChannelForgeEpgSource'
Expand Down
108 changes: 108 additions & 0 deletions src/ChannelForge/Private/Get-ChannelForgeGuideQualityScorecard.ps1
Original file line number Diff line number Diff line change
@@ -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
}
}
20 changes: 20 additions & 0 deletions src/ChannelForge/Public/Get-ChannelForgeGuideQualityReport.ps1
Original file line number Diff line number Diff line change
@@ -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
}
110 changes: 110 additions & 0 deletions tests/unit/GuideQualityScorecard.Tests.ps1
Original file line number Diff line number Diff line change
@@ -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'
}
}
Loading