feat(ci): PR size (non-test churn) pre-commit hook + size-labeling workflow

[arekay-nv]

What does this PR do?

Adds a PR-size classifier used two ways, implementing the "CI job for LOC count / label large PRs" item from the Endpoints PR Review Policy:

• pre-commit hook pr-size-check — prints the one-line size class on every commit (verbose: true). Run python3 scripts/pr_size_check.py --verbose for the threshold grid and per-class review requirements.
• CI workflow .github/workflows/pr-size-label.yml — labels each PR size/normal | size/large | size/very-large from the same logic.

Size = non-test churn (additions + deletions and changed-file count) excluding tests/**, lockfiles, vendored sources, and generated files. Class = the higher of the lines/files dimensions. Advisory only — nothing blocks.

Per its own tool, this PR classifies as Normal.

Type of change

• New feature (tooling / CI)

Testing

• Tests added — tests/unit/scripts/test_pr_size_check.py (21 cases): classify boundaries, numstat parsing, verbose gating, temp-git measurement, $GITHUB_OUTPUT, the CI two-ref --head path, top-level *.lock exclusion, and base-ref auto-detection (candidate scan + GITHUB_BASE_REF).
• All new tests pass locally (21 passed)
• Manual testing — verified per-commit hook output and the label logic against a temp repo

Checklist

• Code follows project style (ruff / ruff-format / license header)
• Pre-commit hooks pass — mypy skipped locally (known macOS sched_setaffinity env issue on unrelated files; green on Linux CI)
• Documentation updated — base-branch resolution / forked-PR behavior (below)

Notes for reviewers

• The labeling workflow uses pull_request_target so GITHUB_TOKEN can write labels on fork PRs (a plain pull_request token is read-only for forks). It never checks out or runs PR code — only the trusted base-repo copy of scripts/pr_size_check.py over the fetched PR diff.
• Because pull_request_target runs the workflow from the base branch, this very PR won't be auto-labeled; labeling takes effect for PRs opened after this merges.
• Label provisioning is a one-off manual step (labels are no longer auto-created). The per-PR workflow only needs pull-requests: write to attach labels, whereas creating label definitions needs issues: write; keeping them separate keeps the per-PR token minimally scoped. Create the labels once with:

  gh label create size/normal     -c 0E8A16 -d "PR Review Policy: <=500 non-test lines & <=20 files" --force
  gh label create size/large      -c FBCA04 -d "PR Review Policy: 501-1500 lines or 21-50 files"     --force
  gh label create size/very-large -c B60205 -d "PR Review Policy: >1500 lines or >50 files"          --force

  Applying is best-effort: a missing label or transient API error emits a ::warning:: and never fails the PR, and stale size/* labels are removed only after the new label is successfully applied (so a failed add never leaves a PR unlabeled).

Base-branch resolution & forked PRs

The size class is computed against a base branch. When --base / PR_BASE_REF are unset, resolve_base_ref() tries, in order: GITHUB_BASE_REF → origin/main → main → upstream/main → any other <remote>/main.

• CI (labeling workflow): always measures against the exact pull_request.base.sha, so the applied label is correct regardless of local remotes.
• Local pre-commit in a forked clone: in the common fork layout — origin = your fork, upstream = mlcommons/endpoints — origin/main resolves before upstream/main. If your fork's origin/main is stale, the local advisory size can count already-merged upstream commits and over-classify. This affects only the local hint, never the CI label. To pin the base locally, either keep your fork's main synced with upstream, or set the base explicitly:

  PR_BASE_REF=upstream/main pre-commit run pr-size-check   # or, ad hoc:
  python3 scripts/pr_size_check.py --base upstream/main --verbose

[github-actions]

MLCommons CLA bot All contributors have signed the MLCommons CLA ✍️ ✅

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@4b3e7af). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #445   +/-   ##
=======================================
  Coverage        ?   80.98%           
=======================================
  Files           ?      150           
  Lines           ?    20208           
  Branches        ?        0           
=======================================
  Hits            ?    16366           
  Misses          ?     3842           
  Partials        ?        0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[nv-alicheng]

Review Council — Multi-AI Code Review

Reviewed by: Codex + Claude + Code-Quality | Depth: standard

Found 4 issues (0 critical/high). Solid, well-tested tooling PR. Security note: all three reviewers independently cleared the pull_request_target workflow — it checks out the trusted base.sha, fetches the PR head as data only (never executes PR code), validates PR_NUMBER against injection, uses env-var indirection (no untrusted PR fields in run:), minimizes permissions, and pins the action SHA. No token-exfil / script-injection vector found.

#	File	Line	Severity	Category	Reviewer(s)	Summary
1	scripts/pr_size_check.py	75	medium	code-quality	Code-Quality	Thresholds 500/1500/20/50 duplicated across classify, the _GRID string, and the docstring — no single source; grid can silently drift from behavior.
2	scripts/pr_size_check.py	57	low	design	Codex	origin/main resolved before upstream/main; stale fork main over-classifies the local hint (documented tradeoff; CI label unaffected). Reconsider default precedence.
3	scripts/pr_size_check.py	70	low	code-quality	Code-Quality	classify() -> str stringly-typed over a closed 3-value set; a Literal would let mypy check _REQUIREMENTS exhaustiveness.
4	scripts/pr_size_check.py	129	low	testing	Claude	Resilience fallbacks (remote-scan base resolution; measure() -> None skip path) untested — the exact CI-degradation paths the design relies on.

Codex also raised a finding on tests/performance/.../test_token_metrics_perf.py; dropped as out of scope (not in this PR's diff).

[nv-alicheng]

[Codex] low (design): _BASE_CANDIDATES tries origin/main before upstream/main. In the common fork layout (origin = personal fork, upstream = canonical), a stale fork main makes the local pre-commit hint count already-merged commits and over-classify — exactly the contributor workflow this hook exists to help. You already document this tradeoff in the PR description ("Base-branch resolution & forked PRs"), and it never affects the CI label (that measures base.sha directly), so this is not a bug. But since the hint is for contributors and the fork layout is their common case, worth reconsidering whether upstream/main should take precedence by default (or resolving to whichever candidate yields the nearer merge-base).

[nv-alicheng]

[Claude] low (testing): the graceful-degradation fallbacks — the whole point of this resilient advisory check — are untested. (1) The remote-scan base fallback here (for remote in _git(["remote"]).stdout.split(): ref = f"{remote}/main", L129-132): every test_main_* resolves the base via PR_BASE_REF/GITHUB_BASE_REF/--base/_BASE_CANDIDATES, so this loop never runs. (2) measure() returning None on a failed merge-base/diff and the corresponding "could not diff … skipping" path in main (L230-235) — test_main_skips_when_base_unresolvable only covers base_ref is None, not the unrelated-history/shallow-clone case. The workflow's "No size class computed … nothing to label" handling depends on these skipping cleanly. A small unit test for each (a repo with only an upstream/main remote; a diff against unrelated history) closes the gap.