scripts/diff_shades_gha_helper.py - third_party/github.com/psf/black - Git at Google

 """Helper script for psf/black's diff-shades Github Actions integration.

 diff-shades is a tool for analyzing what happens when you run Black on
 OSS code capturing it for comparisons or other usage. It's used here to
 help measure the impact of a change *before* landing it (in particular
 posting a comment on completion for PRs).

 This script exists as a more maintainable alternative to using inline
 Javascript in the workflow YAML files. The revision configuration and
 resolving, caching, and PR comment logic is contained here.

 For more information, please see the developer docs:

 https://black.readthedocs.io/en/latest/contributing/gauging_changes.html#diff-shades
 """

 import json
 import os
 import platform
 import pprint
 import subprocess
 import sys
 from base64 import b64encode
 from os.path import dirname, join
 from pathlib import Path
 from typing import Any, Final

 import click
 import urllib3
 from packaging.version import Version

 COMMENT_FILE: Final = ".pr-comment.md"
 DIFF_STEP_NAME: Final = "Generate HTML diff report"
 DOCS_URL: Final = (
     "https://black.readthedocs.io/en/latest/contributing/gauging_changes.html#diff-shades"
 )
 SHA_LENGTH: Final = 10
 GH_API_TOKEN: Final = os.getenv("GITHUB_TOKEN")
 REPO: Final = os.getenv("GITHUB_REPOSITORY", default="psf/black")
 USER_AGENT: Final = f"{REPO} diff-shades workflow via urllib3/{urllib3.__version__}"
 http = urllib3.PoolManager()


 def set_output(name: str, value: str) -> None:
     if len(value) < 200:
         print(f"[INFO]: setting '{name}' to '{value}'")
     else:
         print(f"[INFO]: setting '{name}' to [{len(value)} chars]")

     if "GITHUB_OUTPUT" in os.environ:
         if "\n" in value:
             # https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#multiline-strings
             delimiter = b64encode(os.urandom(16)).decode()
             value = f"{delimiter}\n{value}\n{delimiter}"
             command = f"{name}<<{value}"
         else:
             command = f"{name}={value}"
         with open(os.environ["GITHUB_OUTPUT"], "a") as f:
             print(command, file=f)


 def http_get(url: str, *, is_json: bool = True, **kwargs: Any) -> Any:
     headers = kwargs.get("headers") or {}
     headers["User-Agent"] = USER_AGENT
     if "github" in url:
         if GH_API_TOKEN:
             headers["Authorization"] = f"token {GH_API_TOKEN}"
         headers["Accept"] = "application/vnd.github.v3+json"
     kwargs["headers"] = headers

     r = http.request("GET", url, **kwargs)
     if is_json:
         data = json.loads(r.data.decode("utf-8"))
     else:
         data = r.data
     print(f"[INFO]: issued GET request for {r.geturl()}")
     if not (200 <= r.status < 300):
         pprint.pprint(dict(r.info()))
         pprint.pprint(data)
         raise RuntimeError(f"unexpected status code: {r.status}")

     return data


 def get_latest_revision(ref: str) -> str:
     data = http_get(
         f"https://api.github.com/repos/{REPO}/commits",
         fields={"per_page": "1", "sha": ref},
     )
     assert isinstance(data[0]["sha"], str)
     return data[0]["sha"]


 def get_pr_branches(pr: int | None = None) -> tuple[Any, Any, int]:
     if not pr:
         pr_ref = os.getenv("GITHUB_REF")
         assert pr_ref is not None
         pr = int(pr_ref[10:-6])

     data = http_get(f"https://api.github.com/repos/{REPO}/pulls/{pr}")
     assert isinstance(data["base"]["sha"], str)
     assert isinstance(data["head"]["sha"], str)
     return data["base"], data["head"], pr


 def get_pypi_version() -> Version:
     data = http_get("https://pypi.org/pypi/black/json")
     versions = [Version(v) for v in data["releases"]]
     sorted_versions = sorted(versions, reverse=True)
     return sorted_versions[0]


 @click.group()
 def main() -> None:
     pass


 @main.command("config", help="Acquire run configuration and metadata.")
 def config() -> None:
     import diff_shades  # type: ignore[import-not-found]

     jobs = [{"mode": "preview-new-changes", "style": "preview"}]

     event = os.getenv("GITHUB_EVENT_NAME")
     if event == "push":
         # Push on main, let's use PyPI Black as the baseline.
         baseline_name = str(get_pypi_version())
         baseline_cmd = f"git checkout {baseline_name}"

         target_rev = os.getenv("GITHUB_SHA")
         assert target_rev is not None
         target_name = "main-" + target_rev[:SHA_LENGTH]
         target_cmd = f"git checkout {target_rev}"

     elif event == "pull_request":
         jobs.insert(0, {"mode": "assert-no-changes", "style": "stable"})
         # PR, let's use the PR base as the baseline.
         base, head, pr_num = get_pr_branches()

         baseline_rev = get_latest_revision(base["ref"])
         baseline_name = f"{base['ref']}-{baseline_rev[:SHA_LENGTH]}"
         baseline_cmd = f"git checkout {baseline_rev}"

         target_name = f"pr-{pr_num}-{head['sha'][:SHA_LENGTH]}"
         target_cmd = f"gh pr checkout {pr_num}\ngit merge origin/{base['ref']}"
     else:
         raise ValueError(f"Unknown event {event}")

     env = f"{platform.system()}-{platform.python_version()}-{diff_shades.__version__}"
     for entry in jobs:
         entry["baseline-analysis"] = f"{entry['style']}-{baseline_name}.json"
         entry["baseline-setup-cmd"] = baseline_cmd
         entry["baseline-cache-key"] = f"{env}-{baseline_name}-{entry['style']}"

         entry["target-analysis"] = f"{entry['style']}-{target_name}.json"
         entry["target-setup-cmd"] = target_cmd

     set_output("matrix", json.dumps(jobs, indent=None))
     pprint.pprint(jobs)


 @main.command("comment-body", help="Generate the body for a summary PR comment.")
 @click.argument("baseline", type=click.Path(exists=True, path_type=Path))
 @click.argument("target", type=click.Path(exists=True, path_type=Path))
 @click.argument("style")
 @click.argument("mode")
 def comment_body(baseline: Path, target: Path, style: str, mode: str) -> None:
     cmd = (
         f"{sys.executable} -m diff_shades --no-color "
         f"compare {baseline} {target} --quiet --check"
     ).split(" ")
     proc = subprocess.run(cmd, stdout=subprocess.PIPE, encoding="utf-8")
     if proc.returncode:
         run_id = os.getenv("GITHUB_RUN_ID")
         jobs = http_get(
             f"https://api.github.com/repos/{REPO}/actions/runs/{run_id}/jobs",
         )["jobs"]
         job = next(j for j in jobs if j["name"] == f"compare / {mode}")
         diff_step = next(s for s in job["steps"] if s["name"] == DIFF_STEP_NAME)
         diff_url = f"{job['html_url']}#step:{diff_step['number']}:1"

         body = (
             "<details>"
             f"<summary><b><code>--{style}</code> style</b> "
             f'(<a href="{diff_url}">View full diff</a>):</summary>'
             f"<pre>{proc.stdout.strip()}</pre>"
             "</details>"
         )
     else:
         body = f"<b><code>--{style}</code> style</b>: no changes"

     filename = f".{style}{COMMENT_FILE}"
     print(f"[INFO]: writing comment details to {filename}")
     with open(filename, "w", encoding="utf-8") as f:
         f.write(body)


 @main.command("comment-details", help="Get PR comment resources from a workflow run.")
 @click.argument("pr")
 @click.argument("run-id")
 @click.argument("styles", nargs=-1)
 def comment_details(pr: int, run_id: str, styles: tuple[str, ...]) -> None:
     base, head, _ = get_pr_branches(pr)

     lines = [
         f"**diff-shades** results comparing this PR ({head['sha']}) to {base['ref']}"
         f" ({base['sha']}):"
     ]
     for style_file in styles:
         with open(
             join(dirname(__file__), "..", style_file),
             "r",
             encoding="utf-8",
         ) as f:
             content = f.read()
             lines.append(content)

     lines.append("---")

     lines.append(
         f"[**What is this?**]({DOCS_URL}) | "
         f"[Workflow run](https://github.com/psf/black/actions/runs/{run_id}) | "
         "[diff-shades documentation](https://github.com/ichard26/diff-shades#readme)"
     )

     body = "\n\n".join(lines)
     set_output("comment-body", body)


 if __name__ == "__main__":
     main()
	"""Helper script for psf/black's diff-shades Github Actions integration.

	diff-shades is a tool for analyzing what happens when you run Black on
	OSS code capturing it for comparisons or other usage. It's used here to
	help measure the impact of a change before landing it (in particular
	posting a comment on completion for PRs).

	This script exists as a more maintainable alternative to using inline
	Javascript in the workflow YAML files. The revision configuration and
	resolving, caching, and PR comment logic is contained here.

	For more information, please see the developer docs:

	https://black.readthedocs.io/en/latest/contributing/gauging_changes.html#diff-shades
	"""

	import json
	import os
	import platform
	import pprint
	import subprocess
	import sys
	from base64 import b64encode
	from os.path import dirname, join
	from pathlib import Path
	from typing import Any, Final

	import click
	import urllib3
	from packaging.version import Version

	COMMENT_FILE: Final = ".pr-comment.md"
	DIFF_STEP_NAME: Final = "Generate HTML diff report"
	DOCS_URL: Final = (
	"https://black.readthedocs.io/en/latest/contributing/gauging_changes.html#diff-shades"
	)
	SHA_LENGTH: Final = 10
	GH_API_TOKEN: Final = os.getenv("GITHUB_TOKEN")
	REPO: Final = os.getenv("GITHUB_REPOSITORY", default="psf/black")
	USER_AGENT: Final = f"{REPO} diff-shades workflow via urllib3/{urllib3.__version__}"
	http = urllib3.PoolManager()


	def set_output(name: str, value: str) -> None:
	if len(value) < 200:
	print(f"[INFO]: setting '{name}' to '{value}'")
	else:
	print(f"[INFO]: setting '{name}' to [{len(value)} chars]")

	if "GITHUB_OUTPUT" in os.environ:
	if "\n" in value:
	# https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#multiline-strings
	delimiter = b64encode(os.urandom(16)).decode()
	value = f"{delimiter}\n{value}\n{delimiter}"
	command = f"{name}<<{value}"
	else:
	command = f"{name}={value}"
	with open(os.environ["GITHUB_OUTPUT"], "a") as f:
	print(command, file=f)


	def http_get(url: str, , is_json: bool = True, *kwargs: Any) -> Any:
	headers = kwargs.get("headers") or {}
	headers["User-Agent"] = USER_AGENT
	if "github" in url:
	if GH_API_TOKEN:
	headers["Authorization"] = f"token {GH_API_TOKEN}"
	headers["Accept"] = "application/vnd.github.v3+json"
	kwargs["headers"] = headers

	r = http.request("GET", url, **kwargs)
	if is_json:
	data = json.loads(r.data.decode("utf-8"))
	else:
	data = r.data
	print(f"[INFO]: issued GET request for {r.geturl()}")
	if not (200 <= r.status < 300):
	pprint.pprint(dict(r.info()))
	pprint.pprint(data)
	raise RuntimeError(f"unexpected status code: {r.status}")

	return data


	def get_latest_revision(ref: str) -> str:
	data = http_get(
	f"https://api.github.com/repos/{REPO}/commits",
	fields={"per_page": "1", "sha": ref},
	)
	assert isinstance(data[0]["sha"], str)
	return data[0]["sha"]


	def get_pr_branches(pr: int \| None = None) -> tuple[Any, Any, int]:
	if not pr:
	pr_ref = os.getenv("GITHUB_REF")
	assert pr_ref is not None
	pr = int(pr_ref[10:-6])

	data = http_get(f"https://api.github.com/repos/{REPO}/pulls/{pr}")
	assert isinstance(data["base"]["sha"], str)
	assert isinstance(data["head"]["sha"], str)
	return data["base"], data["head"], pr


	def get_pypi_version() -> Version:
	data = http_get("https://pypi.org/pypi/black/json")
	versions = [Version(v) for v in data["releases"]]
	sorted_versions = sorted(versions, reverse=True)
	return sorted_versions[0]


	@click.group()
	def main() -> None:
	pass


	@main.command("config", help="Acquire run configuration and metadata.")
	def config() -> None:
	import diff_shades # type: ignore[import-not-found]

	jobs = [{"mode": "preview-new-changes", "style": "preview"}]

	event = os.getenv("GITHUB_EVENT_NAME")
	if event == "push":
	# Push on main, let's use PyPI Black as the baseline.
	baseline_name = str(get_pypi_version())
	baseline_cmd = f"git checkout {baseline_name}"

	target_rev = os.getenv("GITHUB_SHA")
	assert target_rev is not None
	target_name = "main-" + target_rev[:SHA_LENGTH]
	target_cmd = f"git checkout {target_rev}"

	elif event == "pull_request":
	jobs.insert(0, {"mode": "assert-no-changes", "style": "stable"})
	# PR, let's use the PR base as the baseline.
	base, head, pr_num = get_pr_branches()

	baseline_rev = get_latest_revision(base["ref"])
	baseline_name = f"{base['ref']}-{baseline_rev[:SHA_LENGTH]}"
	baseline_cmd = f"git checkout {baseline_rev}"

	target_name = f"pr-{pr_num}-{head['sha'][:SHA_LENGTH]}"
	target_cmd = f"gh pr checkout {pr_num}\ngit merge origin/{base['ref']}"
	else:
	raise ValueError(f"Unknown event {event}")

	env = f"{platform.system()}-{platform.python_version()}-{diff_shades.__version__}"
	for entry in jobs:
	entry["baseline-analysis"] = f"{entry['style']}-{baseline_name}.json"
	entry["baseline-setup-cmd"] = baseline_cmd
	entry["baseline-cache-key"] = f"{env}-{baseline_name}-{entry['style']}"

	entry["target-analysis"] = f"{entry['style']}-{target_name}.json"
	entry["target-setup-cmd"] = target_cmd

	set_output("matrix", json.dumps(jobs, indent=None))
	pprint.pprint(jobs)


	@main.command("comment-body", help="Generate the body for a summary PR comment.")
	@click.argument("baseline", type=click.Path(exists=True, path_type=Path))
	@click.argument("target", type=click.Path(exists=True, path_type=Path))
	@click.argument("style")
	@click.argument("mode")
	def comment_body(baseline: Path, target: Path, style: str, mode: str) -> None:
	cmd = (
	f"{sys.executable} -m diff_shades --no-color "
	f"compare {baseline} {target} --quiet --check"
	).split(" ")
	proc = subprocess.run(cmd, stdout=subprocess.PIPE, encoding="utf-8")
	if proc.returncode:
	run_id = os.getenv("GITHUB_RUN_ID")
	jobs = http_get(
	f"https://api.github.com/repos/{REPO}/actions/runs/{run_id}/jobs",
	)["jobs"]
	job = next(j for j in jobs if j["name"] == f"compare / {mode}")
	diff_step = next(s for s in job["steps"] if s["name"] == DIFF_STEP_NAME)
	diff_url = f"{job['html_url']}#step:{diff_step['number']}:1"

	body = (
	"<details>"
	f"<summary><b><code>--{style}</code> style</b> "
	f'(<a href="{diff_url}">View full diff</a>):</summary>'
	f"<pre>{proc.stdout.strip()}</pre>"
	"</details>"
	)
	else:
	body = f"<b><code>--{style}</code> style</b>: no changes"

	filename = f".{style}{COMMENT_FILE}"
	print(f"[INFO]: writing comment details to {filename}")
	with open(filename, "w", encoding="utf-8") as f:
	f.write(body)


	@main.command("comment-details", help="Get PR comment resources from a workflow run.")
	@click.argument("pr")
	@click.argument("run-id")
	@click.argument("styles", nargs=-1)
	def comment_details(pr: int, run_id: str, styles: tuple[str, ...]) -> None:
	base, head, _ = get_pr_branches(pr)

	lines = [
	f"diff-shades results comparing this PR ({head['sha']}) to {base['ref']}"
	f" ({base['sha']}):"
	]
	for style_file in styles:
	with open(
	join(dirname(__file__), "..", style_file),
	"r",
	encoding="utf-8",
	) as f:
	content = f.read()
	lines.append(content)

	lines.append("---")

	lines.append(
	f"[What is this?]({DOCS_URL}) \| "
	f"[Workflow run](https://github.com/psf/black/actions/runs/{run_id}) \| "
	"[diff-shades documentation](https://github.com/ichard26/diff-shades#readme)"
	)

	body = "\n\n".join(lines)
	set_output("comment-body", body)


	if __name__ == "__main__":
	main()