diff --git a/docs/planning/EVENT-AWARE-CHANNELS-DESIGN-NOTE.md b/docs/planning/EVENT-AWARE-CHANNELS-DESIGN-NOTE.md index ec9cdaf..cd356e9 100644 --- a/docs/planning/EVENT-AWARE-CHANNELS-DESIGN-NOTE.md +++ b/docs/planning/EVENT-AWARE-CHANNELS-DESIGN-NOTE.md @@ -45,29 +45,24 @@ Per channel, from data the build already holds: the channel name, the provider g ### Signals, strong and weak -Points are a first guess [UNVERIFIED]. They must be tuned in the report-only step on the user's real lineup, and never trusted after tuning on one lineup. - -| Signal | Where | Strength | Points | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | -------- | ----------------------------------------------- | -| Guide time mostly fillers: at least half of the window is titles like "No Event", "No Events", "No Live Event", "TBA", "TBD", "To Be Announced", "Coming Soon", "Event Offline" | provider guide | Strong | 3 | -| Name has PPV or "Pay Per View" as a whole word | channel name | Strong | 3 | -| Numbered family: two or more channels in one group share a name stem and differ by a trailing number ("PPV 1", "PPV 2") | names and groups | Medium | 2 | -| Provider group has PPV, "Pay Per View", "Event" or "Events" | group title | Medium | 2 | -| Name has "Event" or "Special Event" as a whole word with a slot number ("Event 3") | channel name | Medium | 2 | -| Name has "Event" as a whole word, no number | channel name | Weak | 1 | -| Few, long programmes: median programme length at least 2 hours | provider guide | Weak | 1 | -| One distinct title per local day, no title repeated | provider guide | Weak | 1 | -| Titles carry event words ("vs", "Main Card", "Prelims", "Live", a sports name token) | provider guide | Weak | 1 | -| Category is wrestling, mma, boxing or other sports | category decision | Weak | 1, only if other signals already gave 2 or more | -| Only filler "Off Air" or "Stand By" titles (no event wording) | provider guide | Weak | 1 | -| Normal TV pattern: 10 or more non-filler programmes in the window with median length 60 minutes or less | provider guide | Against | minus 2 | +Slice 1 measured two real guides (28,239 and 6,100 channels). Filler share alone flagged 129 and 57 normal channels (off-air and blacked-out feeds) and missed event channels whose placeholder is the channel name or one generic word. Average block length, distinct titles per day and venue text did not separate event channels from normal ones, so they are not used. The rules below replace the first guess of points and scores. + +Placeholder time is programme time whose title is a filler ("Next Event Coming Soon", "SIGN OFF", "Channel No Longer Available", "To Be Announced", "No Event", "TBA", "Event Not Started", "Coming Soon"), equals the channel name (ignoring case and punctuation), or is one generic word such as "Pay-Per-View". The filler list is one small data list in `Get-ChannelForgeEventChannelCandidate.ps1`. + +| Signal | Where | Result | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------- | +| Name has PPV, Pay Per View or Pay-Per-View | channel name | `high`, always; `medium` only with 3 or more different real programmes and placeholder time at most half | +| Name has an event word (PPV, Pay Per View, Event, Events, UFC, WWE, AEW, Boxing, Fight, Wrestling, Live Event) and placeholder time over half of guide time | name and guide | `high` | +| Name has an event word and real programmes | name and guide | `medium` | +| Name has an event word and no programmes at all | channel name | `medium`, reason "no guide data" | +| No event word, category is a sports category, and most guide time is in single blocks of 6 hours or more | category and guide | `low` | Rules for the result: -- Score 6 or more is `high`, 4 to 5 `medium`, 2 to 3 `low`, under 2 is not reported. -- Without any guide signal, confidence stops at `medium`. A name and a group are only words; guide behavior is evidence. -- Each fired signal adds one plain reason, for example `name has "PPV"; 3 sibling channels PPV 2 to PPV 4; 78% of guide time is "No Event"`. -- The category never counts by itself. It tells which events matter, not whether the channel is an event channel. +- A channel that matches none of the rows is not reported. A normal channel with filler and no event word is not flagged. +- Each rule adds one plain reason, for example `name has "ppv"; 78% of guide time is placeholder titles`. +- Only `high` will act (slice 3). `medium` and `low` keep their normal guide and are only listed. +- The 6 hour block limit for `low` is a first guess [UNVERIFIED]; it was not tuned on the measured guides. ### False-positive and false-negative risk (plain) diff --git a/scripts/Build-Lineup.ps1 b/scripts/Build-Lineup.ps1 index 7183b2a..fbc2e2c 100644 --- a/scripts/Build-Lineup.ps1 +++ b/scripts/Build-Lineup.ps1 @@ -1138,6 +1138,19 @@ if ($candidatePublished) { } } +# Event channels (event-channel/v2, slice 1): report only. A failure is one warning line. +if ($candidatePublished) { + try { + $eventInput = @(Invoke-ChannelForgePrivateCandidateFunction -Name 'Get-ChannelForgeEventChannelInput' -Arguments @{ CandidateDirectory = $candidateNamespacePath; CategoryReport = (Get-ChannelForgeCategoryReport -CandidateDirectory $candidateNamespacePath -RepositoryRoot $Root); Programme = @($allProgrammes) }) + $eventFound = @(Invoke-ChannelForgePrivateCandidateFunction -Name 'Get-ChannelForgeEventChannelCandidate' -Arguments @{ Channel = $eventInput }) + $eventLines = Invoke-ChannelForgePrivateCandidateFunction -Name 'Get-ChannelForgeEventChannelSummaryLines' -Arguments @{ Candidate = $eventFound } + foreach ($eventLine in $eventLines) { $md += (Get-SafeReportText $eventLine) } + } + catch { + Write-Warning 'The event channel check could not run, so the event channel section is left out of the summary.' + } +} + # Guide comparison (xguide-compare/v1): report only. A failure is one warning line. if (@($allProgrammes).Count -gt 0) { try { diff --git a/src/ChannelForge/Private/Get-ChannelForgeEventChannelCandidate.ps1 b/src/ChannelForge/Private/Get-ChannelForgeEventChannelCandidate.ps1 new file mode 100644 index 0000000..6ef8a49 --- /dev/null +++ b/src/ChannelForge/Private/Get-ChannelForgeEventChannelCandidate.ps1 @@ -0,0 +1,94 @@ +function Get-ChannelForgeEventChannelCandidate { + # event-channel/v2, slice 1: report only. One record per channel that looks like an event + # channel (PPV 1 and similar), with a confidence and plain reasons. Pure: no file access, + # nothing stored, nothing hashed. Rules and measured counts are in + # docs\planning\EVENT-AWARE-CHANNELS-DESIGN-NOTE.md (part A). + # Each Channel needs Key, DisplayName, GroupTitle, Category and Programmes (Title, Start, Stop). + [CmdletBinding()] + param([Parameter(Mandatory)][AllowEmptyCollection()][object[]]$Channel) + + # Placeholder titles, compared after lowercasing and dropping punctuation. Extend here. + $fillers = @('next event coming soon', 'sign off', 'channel no longer available', 'to be announced', 'tba', 'tbd', + 'no event', 'no events', 'no live event', 'event not started', 'coming soon', 'event offline', + 'pay per view', 'ppv', 'event', 'events') + $ppvWords = @([pscustomobject]@{ Key = 'ppv'; Aliases = @('ppv', 'pay per view') }) + $eventWords = @([pscustomobject]@{ Key = 'event'; Aliases = @('ppv', 'pay per view', 'event', 'events', 'ufc', 'wwe', 'aew', 'boxing', 'fight', 'wrestling', 'live event') }) + $sportsKeys = @(Get-ChannelForgeOneGuideCategoryRegistry | Where-Object { $_.Group -ceq 'sports' } | ForEach-Object { [string]$_.Key }) + $normalize = { param([string]$Text) ((($Text.ToLowerInvariant() -replace '[^\p{L}\p{N}]+', ' ')).Trim()) } + + foreach ($item in $Channel) { + $name = & $normalize ([string]$item.DisplayName) + $ppvHit = @(Find-ChannelForgeCategoryWord -Text $name -Registry $ppvWords -Property Aliases) + $eventHit = @(Find-ChannelForgeCategoryWord -Text $name -Registry $eventWords -Property Aliases) + $programmes = @($item.Programmes) + + $total = 0.0; $placeholder = 0.0; $long = 0.0; $realTitles = @{} + foreach ($programme in $programmes) { + $hours = ([datetimeoffset]$programme.Stop - [datetimeoffset]$programme.Start).TotalHours + if ($hours -le 0) { continue } + $title = & $normalize ([string]$programme.Title) + $total += $hours + if ($fillers -contains $title -or $title -ceq $name) { $placeholder += $hours } + else { $realTitles[$title] = $true; if ($hours -ge 6) { $long += $hours } } + } + $share = if ($total -gt 0) { $placeholder / $total } else { 0.0 } + $percent = [int][math]::Round($share * 100) + $reasons = [System.Collections.Generic.List[string]]::new() + $confidence = $null + + if ($ppvHit.Count -gt 0) { + $reasons.Add("name has `"$($ppvHit[0].Word)`"") + # Always high, unless the guide shows several different real programmes. + if ($realTitles.Count -ge 3 -and $share -le 0.5) { $confidence = 'medium'; $reasons.Add("$($realTitles.Count) different real programmes, so the normal guide is likely fine") } + else { $confidence = 'high'; if ($total -gt 0) { $reasons.Add("$percent% of guide time is placeholder titles") } } + } + elseif ($eventHit.Count -gt 0) { + $reasons.Add("name has `"$($eventHit[0].Word)`"") + if ($total -eq 0) { $confidence = 'medium'; $reasons.Add('no guide data') } + elseif ($share -gt 0.5) { $confidence = 'high'; $reasons.Add("$percent% of guide time is placeholder titles") } + else { $confidence = 'medium'; $reasons.Add('real programmes in the guide') } + } + elseif ($sportsKeys -contains [string]$item.Category -and $total -gt 0 -and $long / $total -gt 0.5) { + $confidence = 'low' + $reasons.Add("category $($item.Category); most guide time is in blocks of 6 hours or more") + } + if ($null -eq $confidence) { continue } + + [pscustomobject][ordered]@{ + Key = [string]$item.Key + DisplayName = [string]$item.DisplayName + GroupTitle = [string]$item.GroupTitle + Confidence = $confidence + Reasons = @($reasons) + } + } +} + +function Get-ChannelForgeEventChannelInput { + # Joins the candidate channels, their category and their provider programmes into the + # shape Get-ChannelForgeEventChannelCandidate reads. Programmes join on the exact tvg-id. + [CmdletBinding()] + param( + [Parameter(Mandatory)][string]$CandidateDirectory, + [Parameter(Mandatory)][object]$CategoryReport, + [AllowEmptyCollection()][object[]]$Programme = @() + ) + + $categoryOf = @{} + foreach ($row in $CategoryReport.Rows) { if ($null -ne $row.Category) { $categoryOf[[string]$row.ChannelKey] = [string]$row.Category } } + $byGuideId = [System.Collections.Generic.Dictionary[string, object]]::new([System.StringComparer]::Ordinal) + foreach ($entry in $Programme) { + $guideId = [string]$entry.RawChannelId + if (-not $byGuideId.ContainsKey($guideId)) { $byGuideId[$guideId] = [System.Collections.Generic.List[object]]::new() } + $byGuideId[$guideId].Add([pscustomobject]@{ Title = [string]$entry.Title; Start = $entry.Start; Stop = $entry.End }) + } + foreach ($channel in @(Read-ChannelForgeCandidateChannels -Directory $CandidateDirectory)) { + $key = Get-ChannelForgeChannelKey -Url ([string]$channel.Url) + $guideId = [string]$channel.TvgId + [pscustomobject]@{ + Key = $key; DisplayName = [string]$channel.DisplayName; GroupTitle = [string]$channel.Group + Category = $categoryOf[$key] + Programmes = $(if ($guideId -and $byGuideId.ContainsKey($guideId)) { @($byGuideId[$guideId]) } else { @() }) + } + } +} diff --git a/src/ChannelForge/Private/Get-ChannelForgeEventChannelSummaryLines.ps1 b/src/ChannelForge/Private/Get-ChannelForgeEventChannelSummaryLines.ps1 new file mode 100644 index 0000000..981b267 --- /dev/null +++ b/src/ChannelForge/Private/Get-ChannelForgeEventChannelSummaryLines.ps1 @@ -0,0 +1,21 @@ +function Get-ChannelForgeEventChannelSummaryLines { + <# + .SYNOPSIS + Turns event channel candidates into the few lines shown in the build summary (event-channel/v2, report only). + #> + [CmdletBinding()] + param([AllowEmptyCollection()][object[]]$Candidate = @(), [int]$Cap = 5) + + $found = @($Candidate) + if ($found.Count -eq 0) { return @() } + $high = @($found | Where-Object { $_.Confidence -ceq 'high' }) + $medium = @($found | Where-Object { $_.Confidence -ceq 'medium' }) + $low = @($found | Where-Object { $_.Confidence -ceq 'low' }) + $lines = @('', '## Event Channels', + "$($found.Count) channels look like event channels: $($high.Count) high, $($medium.Count) medium, $($low.Count) low. Nothing was changed.") + foreach ($row in @($high | Select-Object -First $Cap)) { + $lines += "- $($row.DisplayName) (group '$($row.GroupTitle)', high): $(@($row.Reasons) -join '; ')" + } + if ($high.Count -gt $Cap) { $lines += "- and $($high.Count - $Cap) more" } + return $lines +} diff --git a/tests/unit/EventChannelCandidate.Tests.ps1 b/tests/unit/EventChannelCandidate.Tests.ps1 new file mode 100644 index 0000000..99756b3 --- /dev/null +++ b/tests/unit/EventChannelCandidate.Tests.ps1 @@ -0,0 +1,99 @@ +BeforeAll { + $script:RepoRoot = Split-Path -Parent (Split-Path -Parent $PSScriptRoot) + $script:BuildPath = Join-Path $script:RepoRoot 'scripts\Build-Lineup.ps1' + $script:GuideFixture = Join-Path $script:RepoRoot 'tests\fixtures\identity-binding\guide.xml' + Import-Module (Join-Path $script:RepoRoot 'src\ChannelForge\ChannelForge.psd1') -Global -Force + + function New-EventChannel { + param([string]$Name, [string[]]$Titles = @(), [int]$Hours = 4, [string]$Category = $null) + $start = [datetimeoffset]'2026-11-14T00:00:00Z' + $programmes = for ($i = 0; $i -lt $Titles.Count; $i++) { + [pscustomobject]@{ Title = $Titles[$i]; Start = $start.AddHours($i * $Hours); Stop = $start.AddHours(($i + 1) * $Hours) } + } + [pscustomobject]@{ Key = ('{0:x64}' -f $Name.Length); DisplayName = $Name; GroupTitle = 'Test'; Category = $Category; Programmes = @($programmes) } + } + function Get-Rated { + param([object[]]$Channel) + InModuleScope ChannelForge -Parameters @{ Channel = $Channel } { @(Get-ChannelForgeEventChannelCandidate -Channel $Channel) } + } +} + +Describe 'Event channel candidates' { + It 'rates every PPV name high, and medium only with several different real programmes' { + $rated = Get-Rated -Channel @( + (New-EventChannel -Name 'PPV 1' -Titles @('No Event', 'No Event')) + (New-EventChannel -Name 'Pay-Per-View 2') + (New-EventChannel -Name 'Sport PPV 3' -Titles @('News', 'Match A', 'Match B', 'Match C')) + ) + ($rated | Where-Object DisplayName -ceq 'PPV 1').Confidence | Should -Be 'high' + ($rated | Where-Object DisplayName -ceq 'Pay-Per-View 2').Confidence | Should -Be 'high' + ($rated | Where-Object DisplayName -ceq 'Sport PPV 3').Confidence | Should -Be 'medium' + } + + It 'rates an event-word channel high when over half its guide time is placeholder, medium when it has real programmes' { + $rated = Get-Rated -Channel @( + (New-EventChannel -Name 'Fight Night 4' -Titles @('Fight Night 4', 'Fight Night 4', 'Weigh-in')) + (New-EventChannel -Name 'Fight Network' -Titles @('Bout A', 'Bout B', 'Bout C')) + (New-EventChannel -Name 'UFC Extra') + ) + ($rated | Where-Object DisplayName -ceq 'Fight Night 4').Confidence | Should -Be 'high' + ($rated | Where-Object DisplayName -ceq 'Fight Network').Confidence | Should -Be 'medium' + $none = $rated | Where-Object DisplayName -ceq 'UFC Extra' + $none.Confidence | Should -Be 'medium' + $none.Reasons | Should -Contain 'no guide data' + } + + It 'does not flag a normal channel full of filler, and reports nothing for a normal channel' { + $rated = Get-Rated -Channel @( + (New-EventChannel -Name 'City News' -Titles @('Off Air', 'SIGN OFF', 'To Be Announced')) + (New-EventChannel -Name 'Movie Max' -Titles @('Film A', 'Film B')) + ) + $rated.Count | Should -Be 0 + } +} + +Describe 'Event channel summary lines' { + It 'counts each level and caps the high list' { + $rows = @(1..8 | ForEach-Object { [pscustomobject]@{ DisplayName = "PPV $_"; GroupTitle = 'G'; Confidence = 'high'; Reasons = @('r') } }) + + [pscustomobject]@{ DisplayName = 'M'; GroupTitle = 'G'; Confidence = 'medium'; Reasons = @('r') } + $lines = InModuleScope ChannelForge -Parameters @{ Rows = $rows } { @(Get-ChannelForgeEventChannelSummaryLines -Candidate $Rows) } + $lines | Should -Contain '9 channels look like event channels: 8 high, 1 medium, 0 low. Nothing was changed.' + @($lines | Where-Object { $_ -like '- PPV*' }).Count | Should -Be 5 + $lines | Should -Contain '- and 3 more' + } +} + +Describe 'Build summary event channel section' { + It 'turns a failure inside the block into one warning and leaves the build and candidate hash alone' { + function New-Root([string]$Name) { + $root = Join-Path $TestDrive $Name + $data = Join-Path $root 'data' + New-Item -ItemType Directory -Force -Path (Join-Path $data 'providers'), (Join-Path $data 'epg'), (Join-Path $data 'lineup'), (Join-Path $data 'rules'), (Join-Path $data 'playlists') | Out-Null + $playlist = @('#EXTM3U', '#EXTINF:-1 tvg-id="zeta.us" group-title="PPV",PPV 1', 'https://example.invalid/live/ppv1', '#EXTINF:-1 tvg-id="misc.us" group-title="Misc",Mystery Channel', 'https://example.invalid/live/misc') + [IO.File]::WriteAllText((Join-Path $data 'playlists\playlist.m3u'), (($playlist -join "`n") + "`n"), [System.Text.UTF8Encoding]::new($false)) + Copy-Item -LiteralPath $script:GuideFixture -Destination (Join-Path $data 'epg\guide.xml') + @{ provider = 'event-fixture'; sources = @(@{ name = 'Playlist'; group = 'General'; url = 'https://example.invalid/fixture'; enabled = $true; local_playlist = 'data/playlists/playlist.m3u' }) } | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath (Join-Path $data 'providers\mybunny.json') -Encoding UTF8 + @{ epg_sources = @(@{ name = 'Guide'; priority = 10; path = 'guide.xml'; enabled = $true; role = 'primary' }) } | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath (Join-Path $data 'epg\epg_sources.json') -Encoding UTF8 + @{ locals = @() } | ConvertTo-Json | Set-Content -LiteralPath (Join-Path $data 'lineup\locals.json') -Encoding UTF8 + @{ blocks = @(@{ start = 1; end = 9999; category = 'General'; notes = 'fixture' }) } | ConvertTo-Json -Depth 6 | Set-Content -LiteralPath (Join-Path $data 'lineup\numbering_blocks.json') -Encoding UTF8 + @{ aliases = @() } | ConvertTo-Json | Set-Content -LiteralPath (Join-Path $data 'rules\aliases.json') -Encoding UTF8 + return $root + } + function Invoke-Build([string]$Root) { + $warnings = @(& $script:BuildPath -Root $Root 3>&1 | Where-Object { $_ -is [System.Management.Automation.WarningRecord] }) + $summary = Get-Content -LiteralPath (Join-Path $Root 'output\reports\build-summary.json') -Raw | ConvertFrom-Json + [pscustomobject]@{ Hash = [string]$summary.CandidateManifestHash; Markdown = (Get-Content -LiteralPath (Join-Path $Root 'output\reports\lineup-plan.md')) -join "`n"; Warnings = @($warnings | ForEach-Object { [string]$_.Message }) } + } + $good = Invoke-Build (New-Root 'good') + $brokenRoot = New-Root 'broken' + New-Item -ItemType Directory -Force -Path (Join-Path $brokenRoot 'state') | Out-Null + [IO.File]::WriteAllText((Join-Path $brokenRoot 'state\category-overrides.json'), '{ not json') + $bad = Invoke-Build $brokenRoot + + $good.Markdown | Should -BeLike '*## Event Channels*PPV 1 (group ''PPV'', high): name has "ppv"; 0% of guide time is placeholder titles*' + @($good.Warnings | Where-Object { $_ -like '*event channel*' }).Count | Should -Be 0 + @($bad.Warnings | Where-Object { $_ -like '*event channel*' }).Count | Should -Be 1 + $bad.Markdown | Should -Not -BeLike '*## Event Channels*' + $bad.Hash | Should -Be $good.Hash + } +}