Skip to content

Native Android client for Spotify, built with Jetpack Compose

3.5 KB
Raw Blame
"""Write docs/api/CAPABILITIES.md: every Web Player GraphQL operation, grouped by domain,
with whether a spec in docs/api documents it and whether its variables are known.

    python capability_report.py
"""
import json, re
from pathlib import Path

ROOT = Path(__file__).resolve().parents[3]
OPS = Path(__file__).resolve().parents[1] / "src/main/resources/spotify/gql-ops.json"
DOCS = ROOT / "docs/api"
OUT = DOCS / "CAPABILITIES.md"
VARS = DOCS / "gql-variables.json"  # optional: {opName: example variables}, filled by online captures

DOMAINS = [
    ("Search", r"^search|recentSearches|saveRecentSearches|removeRecentSearches"),
    ("Home and browse", r"^home|^browse|countryHub|whatsNew|WhatsNew|watchFeed|seoRecommended"),
    ("Tracks", r"Track(?!s?Entity)|^getTrack|trackPreview|^canvas|^npv|smartShuffle"),
    ("Albums", r"Album"),
    ("Artists", r"Artist|thisisPlaylist"),
    ("Playlists", r"[Pp]laylist|^getLists|curat|Curat"),
    ("Library", r"[Ll]ibrary|areEntitiesInLibrary|^recents$|pinLibrary"),
    ("Podcasts and audiobooks", r"Episode|Show|Podcast|Book|Audiobook|Chapter|showItems"),
    ("User and social", r"[Uu]ser|follow|account|profile|Comment|Reaction|Repl"),
    ("Concerts and location", r"[Cc]oncert|[Vv]enue|[Ll]ocation"),
    ("Colors and images", r"Color|Image"),
    ("Other", r"."),
]


def main():
    table = json.loads(OPS.read_text())
    ops = table["operations"]
    # Only the per-domain specs describe variables; SESSION.md and CAPTURE-MAP.md just list names.
    specs = ("CATALOG.md", "SEARCH-HOME.md", "EXTRAS.md", "LIBRARY.md")
    docs_text = "\n".join((DOCS / f).read_text() for f in specs if (DOCS / f).exists())
    known_vars = json.loads(VARS.read_text()) if VARS.exists() else {}
    groups = {name: [] for name, _ in DOMAINS}
    for op in ops:
        for name, pattern in DOMAINS:
            if re.search(pattern, op):
                groups[name].append(op)
                break
    lines = [
        "# Web Player capabilities",
        "",
        f"Generated by `base/api-spotify/tools/capability_report.py` from build `{table['buildVersion']}`:",
        f"{len(ops)} GraphQL operations. Every one can be called through the bridge with",
        "`gql.query {name, hash, variables}`. Hashes: `base/api-spotify/src/main/resources/spotify/gql-ops.json`,",
        "refreshed by `tools/refresh_gql_ops.py`.",
        "",
        "Status: **spec** = documented in a docs/api file, **vars** = variables known from a capture.",
        "Non-GraphQL capabilities (playback, queue, volume, Connect, playlist edits, folders) go through the",
        "player and `service.call`; see the bridge README.",
        "",
    ]
    total_spec = total_vars = 0
    for name, _ in DOMAINS:
        items = sorted(groups[name])
        if not items:
            continue
        lines += [f"## {name} ({len(items)})", "", "| Operation | Kind | Spec | Vars |", "|---|---|---|---|"]
        for op in items:
            spec = bool(re.search(rf"`{re.escape(op)}`|\b{re.escape(op)}\b", docs_text))
            has_vars = op in known_vars or spec
            total_spec += spec
            total_vars += has_vars
            lines.append(f"| `{op}` | {ops[op]['kind']} | {'yes' if spec else ''} | {'yes' if has_vars else ''} |")
        lines.append("")
    lines.insert(9, f"Coverage: {total_spec} documented, {total_vars} with known variables, out of {len(ops)}.")
    OUT.write_text("\n".join(lines) + "\n")
    print(f"{OUT}: {total_spec} documented / {total_vars} with vars / {len(ops)} ops")


if __name__ == "__main__":
    main()