the compare endpoint stops at 250 commits and says nothing

"""Report whether a compare response was silently truncated at 250 commits.

Read only. One GET, no writes: a token with read access to the repository is
enough. The repair is printed, never performed.

The request is deliberately made without per_page or page, because that is the
call whose 250-commit cap is invisible, and reproducing it is the only way to
measure what an unpaginated client is missing.
"""
import argparse
import logging
import os
import sys

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("github_compare_truncation")

API = "https://api.github.com"

CAP = 250


def verdict(compare):
    """Classify one compare response. Pure. Returns (state, detail).

    `compare` is the parsed JSON: total_commits, commits and files.

    A missing total_commits is its own state rather than a default of zero.
    Defaulting it would report a truncated comparison as complete, which is the
    exact failure this script exists to catch.
    """
    total = compare.get("total_commits")
    if total is None:
        return ("unknown",
                "no total_commits in the response, so completeness cannot be "
                "judged. Do not treat this as complete.")

    total = int(total)
    commits = compare.get("commits") or []
    received = len(commits)
    files = len(compare.get("files") or [])

    if total == 0:
        return ("empty", "no commits between these refs; head is not ahead of base")

    if received >= total:
        return ("complete",
                "%d commit(s), all present%s."
                % (total, " (%d changed file(s))" % files if files else ""))

    if received == CAP:
        return ("capped",
                "total_commits is %d and %d came back: the unpaginated 250-commit "
                "cap, so %d commit(s) are missing. The last entry in this list is "
                "the head of the comparison, not the 250th commit from the base, "
                "so the array is not a contiguous history."
                % (total, received, total - received))

    return ("truncated",
            "total_commits is %d and %d came back, so %d commit(s) are missing. "
            "This is what a paginated read looks like mid-walk; keep paging until "
            "the counts agree." % (total, received, total - received))


def get(session, path, **params):
    r = session.get(API + path, params=params, timeout=30)
    if r.status_code == 401:
        raise SystemExit("401 from GitHub: GITHUB_TOKEN is missing, malformed or "
                         "revoked")
    if r.status_code == 403 and "rate limit" in r.text.lower():
        raise SystemExit("403 rate limited. GET /rate_limit reports the reset time "
                         "and does not itself consume quota")
    if r.status_code == 404:
        raise SystemExit("404 on %s: check the repository and that both refs exist" % path)
    r.raise_for_status()
    return r.json()


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--repo", required=True, help="owner/name")
    ap.add_argument("--base", required=True, help="base ref, tag or sha")
    ap.add_argument("--head", required=True, help="head ref, tag or sha")
    args = ap.parse_args()

    token = os.environ.get("GITHUB_TOKEN")
    if not token:
        log.error("set GITHUB_TOKEN (a read-only token is enough)")
        return 2

    session = requests.Session()
    session.headers.update({
        "Authorization": "Bearer " + token,
        "Accept": "application/vnd.github+json",
        "X-GitHub-Api-Version": "2022-11-28",
        "User-Agent": "github-compare-truncation",
    })

    # No per_page and no page on purpose: this is the call the cap applies to.
    path = "/repos/%s/compare/%s...%s" % (args.repo, args.base, args.head)
    body = get(session, path)
    state, detail = verdict(body)

    line = "%-10s %s...%s  %s" % (state, args.base, args.head, detail)
    if state in ("complete", "empty"):
        log.info(line)
        return 0

    log.warning(line)
    log.warning("  repair: read total_commits first, then page this endpoint with "
                "per_page=100 and page=N until you have that many commits, keeping "
                "files from the first page only. Or read "
                "/repos/%s/commits?sha=%s, which paginates through the Link "
                "header and has no 250-commit ceiling.", args.repo, args.head)
    return 1


if __name__ == "__main__":
    sys.exit(main())

/**
 * Report whether a compare response was silently truncated at 250 commits.
 *
 * Read only. One GET, no writes: a token with read access is enough. The repair
 * is printed, never performed.
 *
 * The request deliberately omits per_page and page, because that is the call the
 * 250-commit cap applies to.
 */
const API = 'https://api.github.com';

const CAP = 250;

/**
 * Classify one compare response. Pure. Returns [state, detail].
 *
 * A missing total_commits is its own state rather than a default of zero:
 * defaulting it would report a truncated comparison as complete.
 */
export function verdict(compare) {
  const raw = compare.total_commits;
  if (raw === undefined || raw === null) {
    return ['unknown',
      'no total_commits in the response, so completeness cannot be judged. Do ' +
      'not treat this as complete.'];
  }

  const total = Number(raw);
  const commits = compare.commits ?? [];
  const received = commits.length;
  const files = (compare.files ?? []).length;

  if (total === 0) {
    return ['empty', 'no commits between these refs; head is not ahead of base'];
  }

  if (received >= total) {
    return ['complete',
      `${total} commit(s), all present` +
      (files ? ` (${files} changed file(s))` : '') + '.'];
  }

  if (received === CAP) {
    return ['capped',
      `total_commits is ${total} and ${received} came back: the unpaginated ` +
      `250-commit cap, so ${total - received} commit(s) are missing. The last ` +
      'entry in this list is the head of the comparison, not the 250th commit ' +
      'from the base, so the array is not a contiguous history.'];
  }

  return ['truncated',
    `total_commits is ${total} and ${received} came back, so ${total - received} ` +
    'commit(s) are missing. This is what a paginated read looks like mid-walk; ' +
    'keep paging until the counts agree.'];
}

function arg(name) {
  const i = process.argv.indexOf(`--${name}`);
  return i === -1 ? undefined : process.argv[i + 1];
}

async function get(token, path) {
  const res = await fetch(API + path, {
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: 'application/vnd.github+json',
      'X-GitHub-Api-Version': '2022-11-28',
      'User-Agent': 'github-compare-truncation',
    },
  });
  if (res.status === 401) {
    throw new Error('401 from GitHub: GITHUB_TOKEN is missing, malformed or revoked');
  }
  if (res.status === 403) {
    throw new Error('403 from GitHub. If this is a rate limit, GET /rate_limit ' +
                    'reports the reset and does not itself consume quota');
  }
  if (res.status === 404) {
    throw new Error(`404 on ${path}: check the repository and that both refs exist`);
  }
  if (!res.ok) throw new Error(`${res.status} from ${path}`);
  return res.json();
}

async function main() {
  const token = process.env.GITHUB_TOKEN;
  const repo = arg('repo');
  const base = arg('base');
  const head = arg('head');
  if (!token || !repo || !base || !head) {
    console.error('set GITHUB_TOKEN and pass --repo owner/name --base X --head Y');
    process.exitCode = 2;
    return;
  }

  const path = `/repos/${repo}/compare/${base}...${head}`;
  const [state, detail] = verdict(await get(token, path));

  const line = `${state.padEnd(10)} ${base}...${head}  ${detail}`;
  if (state === 'complete' || state === 'empty') {
    console.log(line);
    return;
  }

  console.warn(line);
  console.warn('  repair: read total_commits first, then page this endpoint with ' +
               'per_page=100 and page=N until you have that many commits, keeping ' +
               'files from the first page only. Or read ' +
               `/repos/${repo}/commits?sha=${head}, which paginates through the ` +
               'Link header and has no 250-commit ceiling.');
  process.exitCode = 1;
}

// Only run when invoked directly, so the test file can import verdict without
// main() running and failing the suite on a missing token.
if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((err) => { console.error(err.message); process.exitCode = 2; });
}

from github_compare_truncation import verdict


def compare(total, received, files=0):
    return {"total_commits": total,
            "commits": [{"sha": "%040x" % i} for i in range(received)],
            "files": [{"filename": "f%d" % i} for i in range(files)]}


def test_a_small_comparison_is_complete():
    state, detail = verdict(compare(18, 18, files=42))
    assert state == "complete"
    assert "18 commit(s)" in detail
    assert "42 changed file(s)" in detail


def test_exactly_250_with_more_to_come_is_the_cap():
    state, detail = verdict(compare(812, 250))
    assert state == "capped"
    assert "562 commit(s) are missing" in detail
    # The sharp edge: the array is not a contiguous prefix of the history.
    assert "not the 250th commit" in detail


def test_a_partial_page_is_not_the_same_finding_as_the_cap():
    state, detail = verdict(compare(812, 100))
    assert state == "truncated"
    assert "712 commit(s) are missing" in detail


def test_no_commits_between_the_refs_is_not_a_failure():
    assert verdict(compare(0, 0))[0] == "empty"


def test_a_missing_total_commits_is_never_reported_as_complete():
    # Defaulting the count to zero here would call a truncated comparison
    # complete, which is precisely the bug being hunted.
    state, _ = verdict({"commits": [{"sha": "abc"}]})
    assert state == "unknown"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { verdict } from './github-compare-truncation.mjs';

const compare = (total, received, files = 0) => ({
  total_commits: total,
  commits: Array.from({ length: received }, (_, i) => ({ sha: String(i) })),
  files: Array.from({ length: files }, (_, i) => ({ filename: `f${i}` })),
});

test('a small comparison is complete', () => {
  const [state, detail] = verdict(compare(18, 18, 42));
  assert.equal(state, 'complete');
  assert.match(detail, /18 commit\(s\)/);
  assert.match(detail, /42 changed file\(s\)/);
});

test('exactly 250 with more to come is the cap', () => {
  const [state, detail] = verdict(compare(812, 250));
  assert.equal(state, 'capped');
  assert.match(detail, /562 commit\(s\) are missing/);
  assert.match(detail, /not the 250th commit/);
});

test('a partial page is not the same finding as the cap', () => {
  const [state, detail] = verdict(compare(812, 100));
  assert.equal(state, 'truncated');
  assert.match(detail, /712 commit\(s\) are missing/);
});

test('no commits between the refs is not a failure', () => {
  assert.equal(verdict(compare(0, 0))[0], 'empty');
});

test('a missing total_commits is never reported as complete', () => {
  assert.equal(verdict({ commits: [{ sha: 'abc' }] })[0], 'unknown');
});