feat: add extended media details to Search-PatMedia output

[tablackburn]

Summary

• Add 11 new properties to Search-PatMedia results with zero performance impact
• All fields are sourced from existing search API response data (no additional API calls)
• Add Format-PatDuration private helper for human-readable duration formatting

New Properties

Property	Type	Description
Duration	long	Duration in milliseconds
DurationFormatted	string	Human-readable (e.g., "2h 16m", "45m")
ContentRating	string	Age rating (PG-13, R, TV-MA, etc.)
Rating	decimal	Critic/Plex rating (0-10)
AudienceRating	decimal	Audience rating (0-10)
Studio	string	Production company
ViewCount	int	Number of times watched
OriginallyAvailableAt	datetime	Release date
ShowName	string	TV show name (episodes only)
Season	int	Season number (episodes only)
Episode	int	Episode number (episodes only)

Performance

Tested against real Plex server - no measurable performance impact since all fields come from existing search API response.

Test plan

• Format-PatDuration unit tests (17 tests)
• Search-PatMedia unit tests updated (44 tests)
• Full unit test suite passes (1973 passed, 15 skipped)

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

This pull request adds 11 new properties to the Search-PatMedia function's output, enriching media search results with additional metadata. The changes include creating a new private helper function Format-PatDuration to provide human-readable duration formatting.

Changes:

• Added Format-PatDuration private helper function for converting milliseconds to human-readable format (e.g., "2h 16m")
• Extended Search-PatMedia output with 11 new properties: Duration, DurationFormatted, ContentRating, Rating, AudienceRating, Studio, ViewCount, OriginallyAvailableAt, ShowName, Season, and Episode
• Added comprehensive test coverage with 17 tests for Format-PatDuration and updated Search-PatMedia tests with 44 additional test cases

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
PlexAutomationToolkit/Private/Format-PatDuration.ps1	New private helper function that converts duration in milliseconds to human-readable format
PlexAutomationToolkit/Public/Search-PatMedia.ps1	Added 11 new properties to search results output object with proper type conversions and null handling
tests/Unit/Private/Format-PatDuration.tests.ps1	Comprehensive test suite (17 tests) covering formatting, edge cases, and pipeline support
tests/Unit/Public/Search-PatMedia.tests.ps1	Updated mock data and added test cases for new properties, episode-specific fields, and null handling

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The ViewCount property is inconsistent with how other nullable properties are handled in the same object. When viewCount is null or missing, it returns 0 instead of $null. This creates a semantic difference - 0 implies "never watched" while $null would indicate "unknown". Since other properties like Duration, Rating, etc. return $null when not available, ViewCount should follow the same pattern for consistency. Consider changing the logic to: if ($item.viewCount) { [int]$item.viewCount } else { $null }

Suggested change

	ViewCount = if ($item.viewCount) { [int]$item.viewCount } else { 0 }
	ViewCount = if ($item.viewCount) { [int]$item.viewCount } else { $null }

[Copilot]

The function declares [OutputType([string])] but can return $null when the input is null or 0 (line 45). This creates a mismatch between the declared output type and actual behavior. While PowerShell doesn't strictly enforce OutputType, this could mislead developers and affect pipeline behavior. Consider either removing the OutputType attribute or changing it to allow null values. If keeping the current behavior, the test at line 110 in the test file may fail for null inputs since $null is not of type [string].

Suggested change

[OutputType([string])]

[tablackburn]

Response to Copilot Review Comments

ViewCount returning 0 vs $null (Search-PatMedia.ps1:223)

Keeping 0 intentionally - the semantics differ from other nullable fields:

• Duration = $null → "duration unknown" (e.g., live content)
• Rating = $null → "no rating available"
• ViewCount = 0 → "not watched" (definitively zero views, not unknown)

In Plex's API, viewCount is only present when an item has been watched at least once. Absence means 0 views - it's not "unknown", it's explicitly unwatched.

Keeping 0 also provides better UX for filtering:

# Find unwatched items - intuitive
$results | Where-Object { $_.ViewCount -eq 0 }

# vs with $null - less intuitive  
$results | Where-Object { -not $_.ViewCount }

---

OutputType mismatch (Format-PatDuration.ps1:35)

Keeping [OutputType([string])] - the null return case is already documented in the .OUTPUTS section which states "Returns $null if input is $null or 0."

Reasons to keep it:

• The primary return type IS string
• Helps IntelliSense/tooling understand expected output
• Null returns are a common pattern in PowerShell cmdlets
• Removing it loses useful metadata for developers