hotpath-cloud

Get the default policy document (its keys at their defaults, comments included), as `source`. Every uploaded report must carry a policy file of its repository: write it as hotpath/policy.toml (or hotpath/<benchmark>-policy.toml), edit it, then check it with validate_policy.

Takes no parameters.

Explain what changed in a benchmark: compare a stored report with the baseline recorded for it at upload (the report the PR comment compared), judged under the policy the report carried. The head is picked as in get_report. Values are strings formatted as the PR comment shows them, with a `unit`; `change_percent` is the exact number. Compared, no baseline and an unreadable side all answer successfully: read the top-level `verdict`. `verdict.judged` and not `verdict.regressed` means judged and fine. `regressed` means a judged family regressed or a budget is broken (see rows whose `outcome` is `regression` and their `crossed` cells, and `budgets.findings`). Not `judged` means nothing was judged: no baseline and no budgets, an unreadable head, or a policy of unjudged families only.

Fetch one stored report by pull request, commit or id (exactly one). `pr` and `commit` answer the newest matching upload; `commit` matches the measured commit or a PR's head commit, so the local HEAD sha of a PR branch finds the PR's report. The summary names the policy file the report was judged under (`policy_path`, `policy_url`), its verdict, its run `totals` and its dashboard URL. `include_payload` adds the uploaded hotpath JSON report. No report yet answers not_found: poll with `commit` to wait for CI's upload. For what changed against the baseline (regressions, improvements), use get_diff. To find reports without knowing a PR or commit, use list_reports.

List one repository's benchmarks. A repository that does not exist, that the user cannot see or that has no App installed all answer not_found. list_repos already includes every repository's benchmarks; use this one when the repository is known.

List a repository's stored reports, newest first, as summaries without payloads: id, benchmark, commit, PR, event, verdict, dashboard URL and the run's `totals` (wall time, allocated bytes or allocation count, peak RSS, Callgrind instructions and Callgrind wall time, as display strings; null when the report has none). Use it to discover report history (recent runs of one or all benchmarks, a PR's or a commit's reports, regressions in a time window) and to follow a benchmark's totals across runs without fetching each payload. Filters combine; `benchmark` narrows to one series. `metadata` narrows to runs with given user_metadata pairs, e.g. one runner or CPU. 20 per page by default, up to 50; pass `next_cursor` back as `cursor` for the next page, with the same filters. Use get_report with an `id` from here for one report's payload, and get_diff for what changed against its baseline.

List the repositories the token's user can see with the hotpath GitHub App installed, ordered by full name, each with its benchmarks (name, stored reports, time of the newest report). Start here: `full_name` is the `repo` argument of the other tools. A user in a large organization may see hundreds of repositories, most without benchmarks: pass `with_benchmarks: true` to list only the profiled ones, or `query` to find one by name.

Check that a policy TOML document parses as a hotpath policy, with the parser that judges uploaded reports. Stores nothing. A document with a problem is an error naming it. Use it after editing a policy file, before committing it.

Show which user and API token this connection acts as: the GitHub login, the token's name and expiry. Use it to confirm the connection works, or after a call answers invalid_token.

Takes no parameters.