statcast-bigquery 0.1.0__tar.gz

statcast_bigquery-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      dist-path: ${{ steps.build.outputs.dist-path }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv python install 3.13
+      - name: Create venv
+        run: uv venv
+      - name: Install build tools
+        run: uv pip install build
+      - id: build
+        run: |
+          uv run python -m build
+          echo "dist-path=dist" >> $GITHUB_OUTPUT
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

statcast_bigquery-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,30 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Create venv
+        run: uv venv
+      - name: Install
+        run: uv pip install -e ".[dev]"
+      - name: Lint
+        run: uv run ruff check .
+      - name: Type check
+        run: uv run pyright
+      - name: Test
+        run: uv run pytest -v --cov=statcast_bigquery --cov-report=xml
+      - name: Build
+        run: uv run python -m build

statcast_bigquery-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.pyc
+.venv/
+.uv-cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.python-version-local
+.env
+.env.*
+!.env.example
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

statcast_bigquery-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

statcast_bigquery-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## [0.1.0] - 2026-05-?? (planned)
+
+### Added
+- Initial release.
+- `statcast-bigquery sync` — idempotent Statcast pitch-level ingestion to BigQuery.
+- `statcast-bigquery docs` — 5 documentation renderers (BQ-native, LLM, dictionary, markdown, dbt).
+- `statcast-bigquery verify` — Baseball Savant leaderboard verification (8 metrics).
+- 25 vetted example queries; 10+ pitfall catalog; statsapi cross-reference.
+- Schema spans pybaseball Statcast columns (~118 fields); auto-applied BQ-native column descriptions.

statcast_bigquery-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing
+
+Bug reports + small PRs welcome. Please open an issue before large changes.
+
+This is a hobbyist project; review cadence is best-effort.
+
+## Dev setup
+
+    uv venv
+    uv pip install -e ".[dev]"
+    pytest
+
+## Style
+
+Ruff + pyright. Run `ruff check . && pyright` before opening a PR.

statcast_bigquery-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Jason Blahovec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This software does not include or distribute MLB data. MLB data accessed via
+this software is governed by its source's terms (Baseball Savant / MLBAM).

statcast_bigquery-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: statcast-bigquery
+Version: 0.1.0
+Summary: Statcast → BigQuery: idempotent ingestion + LLM-friendly docs + Baseball Savant verification
+Project-URL: Homepage, https://github.com/blahovec-labs/statcast-bigquery
+Project-URL: Issues, https://github.com/blahovec-labs/statcast-bigquery/issues
+Project-URL: Changelog, https://github.com/blahovec-labs/statcast-bigquery/blob/main/CHANGELOG.md
+Author: Jason Blahovec
+License: MIT
+License-File: LICENSE
+Keywords: baseball,bigquery,data-engineering,mlb,statcast
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: google-cloud-bigquery<4.0,>=3.20
+Requires-Dist: pandas<3.0,>=2.0
+Requires-Dist: pyarrow<19.0,>=15.0
+Requires-Dist: pybaseball<3.0,>=2.2.7
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: duckdb<2.0,>=1.0; extra == 'dev'
+Requires-Dist: pyright>=1.1.380; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# statcast-bigquery
+
+Idempotent Statcast → BigQuery ingestion, with first-class documentation for SQL/LLM agents and round-trip validation against Baseball Savant.
+
+## Install
+
+    pip install statcast-bigquery
+
+## Quickstart
+
+    gcloud auth application-default login
+    statcast-bigquery sync \
+        --start 2024-04-01 --end 2024-10-31 \
+        --table myproject.mydataset.statcast_pitches
+
+## Documentation
+
+    statcast-bigquery docs --format llm > STATCAST_FOR_LLMS.md
+
+## Verification
+
+    statcast-bigquery verify \
+        --source baseball-savant \
+        --aggregation player-season \
+        --metric all --season 2024 \
+        --table myproject.mydataset.statcast_pitches
+
+MIT licensed. This software does not include or distribute MLB data.

statcast_bigquery-0.1.0/README.md

@@ -0,0 +1,28 @@
+# statcast-bigquery
+
+Idempotent Statcast → BigQuery ingestion, with first-class documentation for SQL/LLM agents and round-trip validation against Baseball Savant.
+
+## Install
+
+    pip install statcast-bigquery
+
+## Quickstart
+
+    gcloud auth application-default login
+    statcast-bigquery sync \
+        --start 2024-04-01 --end 2024-10-31 \
+        --table myproject.mydataset.statcast_pitches
+
+## Documentation
+
+    statcast-bigquery docs --format llm > STATCAST_FOR_LLMS.md
+
+## Verification
+
+    statcast-bigquery verify \
+        --source baseball-savant \
+        --aggregation player-season \
+        --metric all --season 2024 \
+        --table myproject.mydataset.statcast_pitches
+
+MIT licensed. This software does not include or distribute MLB data.

statcast_bigquery-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "statcast-bigquery"
+version = "0.1.0"
+description = "Statcast → BigQuery: idempotent ingestion + LLM-friendly docs + Baseball Savant verification"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Jason Blahovec" }]
+requires-python = ">=3.11"
+keywords = ["mlb", "baseball", "statcast", "bigquery", "data-engineering"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "pybaseball>=2.2.7,<3.0",
+    "pandas>=2.0,<3.0",
+    "google-cloud-bigquery>=3.20,<4.0",
+    "pyarrow>=15.0,<19.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.6.0",
+    "pyright>=1.1.380",
+    "build>=1.2.0",
+    "duckdb>=1.0,<2.0",
+]
+
+[project.scripts]
+statcast-bigquery = "statcast_bigquery.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/blahovec-labs/statcast-bigquery"
+Issues = "https://github.com/blahovec-labs/statcast-bigquery/issues"
+Changelog = "https://github.com/blahovec-labs/statcast-bigquery/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["statcast_bigquery"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "W"]
+
+[tool.pyright]
+pythonVersion = "3.13"
+typeCheckingMode = "standard"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

statcast_bigquery-0.1.0/scripts/_pybaseball_columns_2024-04-01.txt

@@ -0,0 +1,124 @@
+This is a large query, it may take a moment to complete
+
  0%|          | 0/1 [00:00<?, ?it/s]C:\Users\jason\Projects\statcast-bigquery\.venv\Lib\site-packages\pybaseball\datahelpers\postprocessing.py:59: FutureWarning: errors='ignore' is deprecated and will raise in a future version. Use to_datetime without passing `errors` and catch exceptions explicitly instead
+  data_copy[column] = data_copy[column].apply(pd.to_datetime, errors='ignore', format=date_format)
+
+Rows: 4190
+Columns: 118
+  'pitch_type'                         object
+  'game_date'                          datetime64[ns]
+  'release_speed'                      Float64
+  'release_pos_x'                      Float64
+  'release_pos_z'                      Float64
+  'player_name'                        object
+  'batter'                             Int64
+  'pitcher'                            Int64
+  'events'                             object
+  'description'                        object
+  'spin_dir'                           Int64
+  'spin_rate_deprecated'               Int64
+  'break_angle_deprecated'             Int64
+  'break_length_deprecated'            Int64
+  'zone'                               Int64
+  'des'                                object
+  'game_type'                          object
+  'stand'                              object
+  'p_throws'                           object
+  'home_team'                          object
+  'away_team'                          object
+  'type'                               object
+  'hit_location'                       Int64
+  'bb_type'                            object
+  'balls'                              Int64
+  'strikes'                            Int64
+  'game_year'                          Int64
+  'pfx_x'                              Float64
+  'pfx_z'                              Float64
+  'plate_x'                            Float64
+  'plate_z'                            Float64
+  'on_3b'                              Int64
+  'on_2b'                              Int64
+  'on_1b'                              Int64
+  'outs_when_up'                       Int64
+  'inning'                             Int64
+  'inning_topbot'                      object
+  'hc_x'                               Float64
+  'hc_y'                               Float64
+  'tfs_deprecated'                     Int64
+  'tfs_zulu_deprecated'                Int64
+  'umpire'                             Int64
+  'sv_id'                              Int64
+  'vx0'                                Float64
+  'vy0'                                Float64
+  'vz0'                                Float64
+  'ax'                                 Float64
+  'ay'                                 Float64
+  'az'                                 Float64
+  'sz_top'                             Float64
+  'sz_bot'                             Float64
+  'hit_distance_sc'                    Int64
+  'launch_speed'                       Float64
+  'launch_angle'                       Int64
+  'effective_speed'                    Float64
+  'release_spin_rate'                  Int64
+  'release_extension'                  Float64
+  'game_pk'                            Int64
+  'fielder_2'                          Int64
+  'fielder_3'                          Int64
+  'fielder_4'                          Int64
+  'fielder_5'                          Int64
+  'fielder_6'                          Int64
+  'fielder_7'                          Int64
+  'fielder_8'                          Int64
+  'fielder_9'                          Int64
+  'release_pos_y'                      Float64
+  'estimated_ba_using_speedangle'      Float64
+  'estimated_woba_using_speedangle'    Float64
+  'woba_value'                         Float64
+  'woba_denom'                         Int64
+  'babip_value'                        Int64
+  'iso_value'                          Int64
+  'launch_speed_angle'                 Int64
+  'at_bat_number'                      Int64
+  'pitch_number'                       Int64
+  'pitch_name'                         object
+  'home_score'                         Int64
+  'away_score'                         Int64
+  'bat_score'                          Int64
+  'fld_score'                          Int64
+  'post_away_score'                    Int64
+  'post_home_score'                    Int64
+  'post_bat_score'                     Int64
+  'post_fld_score'                     Int64
+  'if_fielding_alignment'              object
+  'of_fielding_alignment'              object
+  'spin_axis'                          Int64
+  'delta_home_win_exp'                 Float64
+  'delta_run_exp'                      Float64
+  'bat_speed'                          Int64
+  'swing_length'                       Int64
+  'estimated_slg_using_speedangle'     Float64
+  'delta_pitcher_run_exp'              Float64
+  'hyper_speed'                        Float64
+  'home_score_diff'                    Int64
+  'bat_score_diff'                     Int64
+  'home_win_exp'                       Float64
+  'bat_win_exp'                        Float64
+  'age_pit_legacy'                     Int64
+  'age_bat_legacy'                     Int64
+  'age_pit'                            Int64
+  'age_bat'                            Int64
+  'n_thruorder_pitcher'                Int64
+  'n_priorpa_thisgame_player_at_bat'   Int64
+  'pitcher_days_since_prev_game'       Int64
+  'batter_days_since_prev_game'        Int64
+  'pitcher_days_until_next_game'       Int64
+  'batter_days_until_next_game'        Int64
+  'api_break_z_with_gravity'           Float64
+  'api_break_x_arm'                    Float64
+  'api_break_x_batter_in'              Float64
+  'arm_angle'                          Float64
+  'attack_angle'                       Int64
+  'attack_direction'                   Int64
+  'swing_path_tilt'                    Int64
+  'intercept_ball_minus_batter_pos_x_inches'  Int64
+  'intercept_ball_minus_batter_pos_y_inches'  Int64

statcast_bigquery-0.1.0/scripts/discover_pybaseball_columns.py

@@ -0,0 +1,22 @@
+"""Run pybaseball.statcast for one day; print column names + dtypes.
+
+Use this once at the start of Task 3 to ensure PITCHES_SCHEMA covers every column.
+Output is informational only; not committed as a test.
+"""
+
+from __future__ import annotations
+
+import pybaseball as pb
+
+
+def main() -> None:
+    df = pb.statcast(start_dt="2024-04-01", end_dt="2024-04-01")
+    print(f"Rows: {len(df)}")
+    print(f"Columns: {len(df.columns)}")
+    for col in df.columns:
+        dtype = df[col].dtype
+        print(f"  {col!r:<35}  {dtype}")
+
+
+if __name__ == "__main__":
+    main()

statcast_bigquery-0.1.0/statcast_bigquery/__init__.py

@@ -0,0 +1,8 @@
+"""statcast-bigquery.
+
+Statcast pitch-level ingestion + LLM-friendly docs + Baseball Savant verification.
+"""
+
+from statcast_bigquery._version import __version__
+
+__all__ = ["__version__"]

statcast_bigquery-0.1.0/statcast_bigquery/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

statcast_bigquery-0.1.0/statcast_bigquery/cli.py

@@ -0,0 +1,194 @@
+"""CLI entrypoint: statcast-bigquery {sync,docs,verify}."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from datetime import date, datetime, timedelta
+
+from google.cloud import bigquery
+
+from statcast_bigquery._version import __version__
+from statcast_bigquery.client import StatcastClient
+from statcast_bigquery.docs.renderers import (
+    render_bq_descriptions,
+    render_data_dictionary,
+    render_dbt_yaml,
+    render_llm_context,
+    render_markdown,
+)
+from statcast_bigquery.verify.savant import (
+    BATTING_METRIC_TO_SAVANT_FIELD,
+    PITCHING_METRIC_TO_SAVANT_FIELD,
+    BaseballSavantBattingVerifier,
+    BaseballSavantPitchingVerifier,
+)
+from statcast_bigquery.writer import BigQueryWriter, TableRef
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(name)s] %(message)s")
+log = logging.getLogger("statcast-bigquery")
+
+ALL_BATTING_METRICS = list(BATTING_METRIC_TO_SAVANT_FIELD)
+ALL_PITCHING_METRICS = list(PITCHING_METRIC_TO_SAVANT_FIELD)
+DOC_FORMATS = ["bq-apply", "llm", "dictionary", "markdown", "dbt"]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="statcast-bigquery")
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # sync
+    p_sync = sub.add_parser("sync", help="Pull Statcast and write to BigQuery")
+    p_sync.add_argument("--start", required=True, help="YYYY-MM-DD start (inclusive)")
+    p_sync.add_argument("--end", required=True, help="YYYY-MM-DD end (inclusive)")
+    p_sync.add_argument("--table", required=True, help="project.dataset.table")
+    p_sync.add_argument("--chunk-by", default="year", choices=["year", "month", "range"])
+    p_sync.add_argument("--resume", action="store_true",
+                        help="Skip year-chunks already recorded in _statcast_ingest_runs")
+    p_sync.add_argument("--dry-run", action="store_true")
+
+    # docs
+    p_docs = sub.add_parser("docs", help="Render documentation in various formats")
+    p_docs.add_argument("--format", required=True, choices=DOC_FORMATS)
+    p_docs.add_argument("--table", help="project.dataset.table (required for bq-apply, dictionary)")
+    p_docs.add_argument("--dataset", help="for dictionary format")
+    p_docs.add_argument("--output", default="-", help="path or '-' for stdout (default)")
+
+    # verify
+    p_v = sub.add_parser("verify", help="Compare aggregations to external sources")
+    p_v.add_argument("--source", default="baseball-savant", choices=["baseball-savant"])
+    p_v.add_argument("--aggregation", required=True,
+                     choices=["player-season", "pitcher-season"])
+    p_v.add_argument("--metric", required=True,
+                     choices=[*ALL_BATTING_METRICS, *ALL_PITCHING_METRICS, "all"])
+    p_v.add_argument("--season", required=True, type=int)
+    p_v.add_argument("--table", required=True)
+    p_v.add_argument("--tolerance", type=float, default=None)
+    p_v.add_argument("--min-sample-size", type=int, default=50)
+    p_v.add_argument("--threshold", type=float, default=0.99)
+    p_v.add_argument("--output", default="-")
+
+    return parser
+
+
+def _iter_year_chunks(start: str, end: str) -> list[tuple[str, str]]:
+    s = datetime.strptime(start, "%Y-%m-%d").date()
+    e = datetime.strptime(end, "%Y-%m-%d").date()
+    chunks: list[tuple[str, str]] = []
+    cur = s
+    while cur <= e:
+        year_end = date(cur.year, 12, 31)
+        last = min(year_end, e)
+        chunks.append((cur.isoformat(), last.isoformat()))
+        cur = last + timedelta(days=1)
+    return chunks
+
+
+def cmd_sync(ns: argparse.Namespace) -> int:
+    client = bigquery.Client()
+    sc = StatcastClient()
+    writer = BigQueryWriter(client=client)
+    ref = TableRef.parse(ns.table)
+    if not ns.dry_run:
+        writer.create_table_if_missing(ref)
+
+    chunks = _iter_year_chunks(ns.start, ns.end) if ns.chunk_by == "year" \
+        else [(ns.start, ns.end)]
+    for cs, ce in chunks:
+        log.info("chunk %s -> %s", cs, ce)
+        if ns.dry_run:
+            continue
+        df = sc.fetch(cs, ce)
+        writer.write(ref, df, cs, ce)
+    return 0
+
+
+def cmd_docs(ns: argparse.Namespace) -> int:
+    if ns.format == "bq-apply":
+        if not ns.table:
+            log.error("--table required for bq-apply")
+            return 2
+        client = bigquery.Client()
+        ref = TableRef.parse(ns.table)
+        table = client.get_table(str(ref))
+        table.schema = render_bq_descriptions()
+        client.update_table(table, ["schema"])
+        log.info("updated schema descriptions on %s", ref)
+        return 0
+
+    if ns.format == "llm":
+        out = render_llm_context()
+    elif ns.format == "dictionary":
+        if not (ns.dataset and ns.table):
+            log.error("--dataset and --table required for dictionary")
+            return 2
+        ref = TableRef.parse(ns.table)
+        out = json.dumps(
+            render_data_dictionary(dataset=ns.dataset, table=ref.table), indent=2
+        )
+    elif ns.format == "markdown":
+        out = render_markdown()
+    elif ns.format == "dbt":
+        out = render_dbt_yaml()
+    else:
+        raise AssertionError(f"unhandled format {ns.format}")
+
+    if ns.output == "-":
+        with open(sys.stdout.fileno(), mode="w", encoding="utf-8", newline="") as f:
+            f.write(out)
+    else:
+        with open(ns.output, "w", encoding="utf-8") as f:
+            f.write(out)
+    return 0
+
+
+def cmd_verify(ns: argparse.Namespace) -> int:
+    client = bigquery.Client()
+    metrics = ([*ALL_BATTING_METRICS] if ns.aggregation == "player-season"
+               else [*ALL_PITCHING_METRICS]) if ns.metric == "all" else [ns.metric]
+
+    overall_pass = True
+    all_results: list[dict] = []
+    for m in metrics:
+        if ns.aggregation == "player-season":
+            v = BaseballSavantBattingVerifier(
+                client=client, table=ns.table, season=ns.season, metric=m,
+                min_sample_size=ns.min_sample_size, tolerance=ns.tolerance,
+            )
+        else:
+            v = BaseballSavantPitchingVerifier(
+                client=client, table=ns.table, season=ns.season, metric=m,
+                min_sample_size=ns.min_sample_size, tolerance=ns.tolerance,
+            )
+        result = v.run()
+        print(result.summary())
+        verdict = "PASS" if result.passed(ns.threshold) else "FAIL"
+        print(f"{verdict} (threshold {ns.threshold:.2%})\n")
+        if not result.passed(ns.threshold):
+            overall_pass = False
+        all_results.append(result.to_json())
+
+    if ns.output != "-":
+        with open(ns.output, "w", encoding="utf-8") as f:
+            json.dump(all_results, f, indent=2)
+
+    return 0 if overall_pass else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    ns = parser.parse_args(argv)
+    if ns.command == "sync":
+        return cmd_sync(ns)
+    if ns.command == "docs":
+        return cmd_docs(ns)
+    if ns.command == "verify":
+        return cmd_verify(ns)
+    raise AssertionError(f"unhandled command {ns.command}")
+
+
+if __name__ == "__main__":
+    sys.exit(main())