#!/usr/bin/env python3
# Copyright 2026 The HuggingFace Team. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Post mlinter findings as an inline PR review.
Runs in the workflow_run privileged job (pull-requests: write). Reads
mlinter-findings.json and mlinter-pr-number.txt produced by the
check_code_quality job. Never checks out or executes PR code.
Usage:
GITHUB_TOKEN=... GITHUB_REPOSITORY=owner/repo python utils/post_mlinter_review.py
"""
import hashlib
import json
import os
import re
import sys
from collections import Counter, defaultdict
from pathlib import Path
# github_utils is present because the workflow checks out the repo.
from github_utils import get_github_json, github_request
GITHUB_API_URL = os.environ.get("GITHUB_API_URL", "https://api.github.com")
MAX_INLINE = 40
MAX_PER_FILE = 10
# Delimiters for the mlinter state block embedded in the PR description.
_STATE_START = ""
_STATE_END = ""
def _findings_hash(findings):
"""Short SHA-256 hash of findings content, excluding parse-error sentinels (rule=None)."""
key = json.dumps(
sorted([(f["path"], f["line"], f["rule"], f["message"]) for f in findings if f.get("rule")])
).encode()
return hashlib.sha256(key).hexdigest()[:8]
def _read_pr_state(pr_body):
"""Extract the mlinter hash and review ID from the PR description state block.
Returns (hash_str, review_id_str) or (None, None).
"""
m = re.search(
r".*?hash: `([0-9a-f]{8})`.*?"
r"review: [^\n]*#pullrequestreview-(\d+).*?",
pr_body or "",
re.DOTALL,
)
if not m:
return None, None
return m.group(1), m.group(2)
def _delete_old_review_comments(review_id, pulls_url, token):
"""Delete all inline comments from a previous mlinter review to prevent accumulation."""
try:
comments = get_github_json(f"{pulls_url}/reviews/{review_id}/comments", token=token) or []
except RuntimeError as exc:
print(f"Could not fetch comments for review {review_id}: {exc}; skipping cleanup.", file=sys.stderr)
return
repo_api_url = pulls_url.split("/pulls/")[0]
for comment in comments:
try:
github_request(f"{repo_api_url}/pulls/comments/{comment['id']}", token=token, method="DELETE")
except RuntimeError as exc:
print(f"Failed to delete comment {comment['id']}: {exc}", file=sys.stderr)
def _update_pr_description(pr_body, findings_hash, commit_sha, review_url):
"""Add or replace the mlinter state block in the PR description."""
block = "\n".join(
[
_STATE_START,
"",
"🤖 mlinter review state
",
"",
f"- hash: `{findings_hash}`",
f"- commit: `{commit_sha}`",
f"- review: {review_url}",
"",
" ",
_STATE_END,
]
)
if _STATE_START in (pr_body or ""):
return re.sub(
r".*?",
block,
pr_body,
flags=re.DOTALL,
)
return (pr_body or "").rstrip() + "\n\n" + block
def _paginate(url, token):
items = []
page = 1
while page <= 20:
sep = "&" if "?" in url else "?"
batch = get_github_json(f"{url}{sep}per_page=100&page={page}", token=token)
if not isinstance(batch, list) or not batch:
break
items.extend(batch)
if len(batch) < 100:
break
page += 1
return items
def _commentable_lines(patch):
"""Return line numbers on the head side that GitHub accepts as comment anchors."""
lines = set()
head = 0
for raw in (patch or "").splitlines():
if raw.startswith("@@"):
try:
head = int(raw.split("+", 1)[1].split(",")[0].split()[0])
except (IndexError, ValueError):
head = 0
continue
if raw.startswith("-"):
continue
if raw.startswith(("+", " ")) and head:
lines.add(head)
head += 1
return lines
def _comment_body(finding, rules):
rule = finding["rule"]
spec = rules.get(rule, {})
lines = [f"**{rule}** — {finding['message']}"]
why = (spec.get("why_bad") or "").strip()
diff = (spec.get("diff") or "").strip()
if why or diff:
lines += ["", "Why this matters
", ""]
if why:
lines += [why, ""]
if diff:
lines += ["```diff", diff, "```", ""]
lines += [f"Suppress with `# trf-ignore: {rule}` if intentional.", "", "{len(skipped)} item(s) outside this diff
",
"",
]
for f in skipped:
lines.append(f"- `{f['path']}:{f['line']}` **{f['rule']}** — {f['message']}")
lines += ["", "