Public/Get-ShellPhishSongGap.ps1

function Get-ShellPhishSongGap {
    <#
    .SYNOPSIS
        Shows every performance of a song with the gap (in shows) between appearances.
    .PARAMETER Song
        Song name or slug to look up.
    .PARAMETER ExportPath
        Optional file path (.csv or .json) to export results.
    .EXAMPLE
        PS C:\> Get-ShellPhishSongGap -Song tweezer
    #>

    [CmdletBinding()]
    param (
        [Parameter(Mandatory=$true)]
        [string]$Song,

        [Parameter()]
        [string]$ExportPath
    )

    Write-Verbose "Fetching setlists for '$Song'..."
    $setlists = (Get-ShellPhishSetlists -Slug $Song).data

    if (-not $setlists) {
        # Try as song name
        $setlists = (Get-ShellPhishSetlists -Song $Song).data
    }

    if (-not $setlists) {
        Write-Warning "No performances found for '$Song'"
        return
    }

    $dates = $setlists | Select-Object -ExpandProperty showdate -Unique | Sort-Object
    Write-Verbose "Found $($dates.Count) performance(s)"

    # Fetch all Phish show dates to calculate gaps in shows (not calendar days)
    Write-Verbose "Fetching all show dates for gap calculation..."
    $allShows = (Get-ShellPhishShows -Artist phish -OrderBy showdate -Direction asc).data
    $allDates = @($allShows | Select-Object -ExpandProperty showdate -Unique | Sort-Object)

    $results = @()
    $prevIdx = $null
    foreach ($date in $dates) {
        $idx = $allDates.IndexOf($date)
        $gap = if ($null -ne $prevIdx -and $idx -ge 0) { $idx - $prevIdx } else { 0 }
        $results += [PSCustomObject]@{
            ShowDate  = $date
            ShowGap   = $gap
        }
        if ($idx -ge 0) { $prevIdx = $idx }
    }

    # Current gap
    $lastPlayedIdx = $allDates.IndexOf($dates[-1])
    $totalShows = $allDates.Count
    $currentGap = if ($lastPlayedIdx -ge 0) { $totalShows - $lastPlayedIdx - 1 } else { 0 }

    Write-Host "`n=== $Song Gap Chart ===" -ForegroundColor Cyan
    Write-Host "Total performances: $($dates.Count)"
    Write-Host "Current gap: $currentGap show(s) since last played`n"

    Export-ShellPhishData -Data $results -ExportPath $ExportPath
}