modelpin-relay 0.1.1__py3-none-any.whl

modelpin_relay/__init__.py

@@ -0,0 +1,6 @@
+"""modelpin-relay: sends Modelpin results from CI to Jira and Bitbucket (BUILD_BRIEF section 8)."""
+
+__version__ = "0.1.1"
+
+#: Modelpin versions whose output files the relay is tested against (BUILD_BRIEF 8).
+TESTED_MODELPIN_VERSIONS = frozenset({"0.5.3"})

modelpin_relay/ci_env.py

@@ -0,0 +1,142 @@
+"""Which CI the relay runs in, and the event's `source` block (BUILD_BRIEF 8.2).
+
+Bitbucket Pipelines is detected by `BITBUCKET_BUILD_NUMBER`, GitHub Actions by `GITHUB_ACTIONS=true`; anything
+else is `local`. URL shapes for Bitbucket were confirmed in spike S3 (`<origin>/pipelines/results/<build>`,
+`<origin>/pull-requests/<id>`). On GitHub `pull_request` events, `GITHUB_SHA` is a merge commit, so the head
+commit, number and URL come from the event payload file.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from modelpin_relay.git_context import current_branch, head_commit, local_repo_key
+from modelpin_relay.payload import Source
+
+CI_CHOICES = ("auto", "bitbucket", "github", "local")
+
+_SEGMENT = re.compile(r"[A-Za-z0-9._-]+")
+_FULL_HASH = re.compile(r"[0-9a-f]{40}(?:[0-9a-f]{24})?")
+_HTTPS_URL = re.compile(r"https://[^\s]+")
+
+
+class UnsupportedCI(Exception):
+    """The environment doesn't describe the CI it claims to be (a usage problem, exit 2)."""
+
+
+def detect_ci(env: Mapping[str, str]) -> str:
+    if env.get("BITBUCKET_BUILD_NUMBER"):
+        return "bitbucket"
+    if env.get("GITHUB_ACTIONS") == "true":
+        return "github"
+    return "local"
+
+
+def resolve_ci(choice: str, env: Mapping[str, str]) -> str:
+    return detect_ci(env) if choice == "auto" else choice
+
+
+def _https(url: str | None) -> str | None:
+    """Bitbucket's documented origin example is http://; event URLs are always https://."""
+    if not url:
+        return None
+    text = url.strip().rstrip("/")
+    if text.startswith("http://"):
+        text = "https://" + text[len("http://") :]
+    return text if _HTTPS_URL.fullmatch(text) and len(text) <= 2000 else None
+
+
+def _full_hash(value: str | None) -> str | None:
+    return value if value and _FULL_HASH.fullmatch(value) else None
+
+
+def _positive_int(value: object) -> int | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value if value > 0 else None
+    if isinstance(value, str) and value.isdigit():
+        number = int(value)
+        return number if number > 0 else None
+    return None
+
+
+def bitbucket_source(env: Mapping[str, str]) -> Source:
+    workspace = env.get("BITBUCKET_WORKSPACE", "")
+    slug = env.get("BITBUCKET_REPO_SLUG", "")
+    if not (_SEGMENT.fullmatch(workspace) and _SEGMENT.fullmatch(slug)):
+        raise UnsupportedCI("BITBUCKET_WORKSPACE and BITBUCKET_REPO_SLUG are not both set")
+    origin = _https(env.get("BITBUCKET_GIT_HTTP_ORIGIN")) or f"https://bitbucket.org/{workspace}/{slug}"
+    build = env.get("BITBUCKET_BUILD_NUMBER") or None
+    pr_id = _positive_int(env.get("BITBUCKET_PR_ID"))
+    return Source(
+        ci="bitbucket",
+        repo_key=f"bitbucket:{workspace}/{slug}",
+        repo_url=origin,
+        commit=_full_hash(env.get("BITBUCKET_COMMIT")),
+        branch=(env.get("BITBUCKET_BRANCH") or "")[:255] or None,
+        pr_id=pr_id,
+        pr_url=f"{origin}/pull-requests/{pr_id}" if pr_id else None,
+        build_url=f"{origin}/pipelines/results/{build}" if build else None,
+        build_number=build[:64] if build else None,
+    )
+
+
+def _event_payload(env: Mapping[str, str]) -> dict[str, Any]:
+    path = env.get("GITHUB_EVENT_PATH")
+    if not path:
+        return {}
+    try:
+        file = Path(path)
+        if file.stat().st_size > 5_000_000:
+            return {}
+        data = json.loads(file.read_text(encoding="utf-8"))
+    except (OSError, ValueError, UnicodeDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def github_source(env: Mapping[str, str]) -> Source:
+    repository = env.get("GITHUB_REPOSITORY", "")
+    parts = repository.split("/")
+    if len(parts) != 2 or not all(_SEGMENT.fullmatch(p) for p in parts):
+        raise UnsupportedCI("GITHUB_REPOSITORY is not set to <owner>/<repo>")
+    server = _https(env.get("GITHUB_SERVER_URL")) or "https://github.com"
+    repo_url = f"{server}/{repository}"
+    run_id = env.get("GITHUB_RUN_ID") or None
+    commit = _full_hash(env.get("GITHUB_SHA"))
+    branch = env.get("GITHUB_REF_NAME") or None
+    pr_id: int | None = None
+    pr_url: str | None = None
+    if env.get("GITHUB_EVENT_NAME", "").startswith("pull_request"):
+        pull = _event_payload(env).get("pull_request")
+        if isinstance(pull, dict):
+            head = pull.get("head")
+            if isinstance(head, dict):
+                commit = _full_hash(head.get("sha") if isinstance(head.get("sha"), str) else None)
+            pr_id = _positive_int(pull.get("number"))
+            pr_url = _https(pull.get("html_url") if isinstance(pull.get("html_url"), str) else None)
+        branch = env.get("GITHUB_HEAD_REF") or None
+    return Source(
+        ci="github",
+        repo_key=f"github:{repository}",
+        repo_url=repo_url,
+        commit=commit,
+        branch=branch[:255] if branch else None,
+        pr_id=pr_id,
+        pr_url=pr_url,
+        build_url=f"{repo_url}/actions/runs/{run_id}" if run_id else None,
+        build_number=run_id[:64] if run_id else None,
+    )
+
+
+def build_source(ci: str, env: Mapping[str, str], cwd: Path) -> Source:
+    if ci == "bitbucket":
+        return bitbucket_source(env)
+    if ci == "github":
+        return github_source(env)
+    return Source(ci="local", repo_key=local_repo_key(cwd), commit=head_commit(cwd), branch=current_branch(cwd))

modelpin_relay/cli.py

@@ -0,0 +1,320 @@
+"""The `modelpin-relay` command (BUILD_BRIEF 8.1).
+
+Exit codes: 0 done (or nothing to send), 2 usage error, 5 a send failed. The relay never changes the check's
+own exit code; the pipeline exits with that (8.3). Notes go to stderr; stdout carries only `--dry-run` output.
+The webhook URL and secret are read from the environment and never printed, logged or written to `--out`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any, TextIO
+
+from modelpin_relay import TESTED_MODELPIN_VERSIONS, __version__, insights
+from modelpin_relay import git_context as git
+from modelpin_relay.ci_env import CI_CHOICES, UnsupportedCI, build_source, resolve_ci
+from modelpin_relay.modelpin_files import ModelpinFileError, read_config, read_watch_output
+from modelpin_relay.payload import CheckInputs, PayloadError, Source, build_check, build_watch, make_event
+from modelpin_relay.transport import send_event
+from modelpin_relay.truncate import EventTooLarge, fit
+
+EXIT_OK = 0
+EXIT_USAGE = 2
+EXIT_SEND_FAILED = 5
+
+
+def _common(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--ci", choices=CI_CHOICES, default="auto", help="which CI to describe (default: detect)")
+    parser.add_argument("--url-env", default="MODELPIN_WEBHOOK_URL", help="variable holding the web trigger URL")
+    parser.add_argument("--secret-env", default="MODELPIN_WEBHOOK_SECRET", help="variable holding the signing secret")
+
+
+def _event_flags(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--no-event", action="store_true", help="build the event but do not send it")
+    parser.add_argument("--dry-run", action="store_true", help="print the event to stdout and send nothing")
+    parser.add_argument("--out", type=Path, help="write event.json into this folder (one folder per event)")
+    parser.add_argument("--sample", action="store_true", help='mark the event "sample": true (in-app sample data only)')
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="modelpin-relay", description="Send Modelpin check and watch results from CI to Jira and Bitbucket."
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    pending = commands.add_parser("pending", help="post the PENDING Code Insights report (Bitbucket only)")
+    pending.add_argument("--config", type=Path, default=Path("modelpin.yaml"))
+    _common(pending)
+
+    skip = commands.add_parser("skip", help="post a PASSED report: nothing Modelpin checks changed (Bitbucket only)")
+    skip.add_argument("--reason", required=True, help="the sentence the report shows")
+    skip.add_argument("--config", type=Path, default=Path("modelpin.yaml"))
+    _common(skip)
+
+    publish = commands.add_parser("publish", help="send the check event for this step's modelpin check")
+    publish.add_argument("--exit-code", required=True, help="the exit code of modelpin check in this step")
+    publish.add_argument("--since", required=True, type=float, help="step start, in Unix seconds (date +%%s)")
+    publish.add_argument("--to", required=True, dest="to_model", help="the candidate model passed to --to")
+    publish.add_argument("--from", dest="from_model", help="the current model, if --from was passed to modelpin")
+    publish.add_argument("--provider", help="the --provider passed to modelpin, if any")
+    publish.add_argument("--config", type=Path, default=Path("modelpin.yaml"))
+    publish.add_argument("--store-dir", type=Path, default=Path(".modelpin"))
+    publish.add_argument("--scenarios-dir", type=Path)
+    publish.add_argument("--no-insights", action="store_true", help="do not post a Code Insights report")
+    publish.add_argument("--outcome-file", type=Path, help="write the outcome (clean, regression, ...) here")
+    _event_flags(publish)
+    _common(publish)
+
+    watch = commands.add_parser("publish-watch", help="send the watch event from modelpin watch --json output")
+    watch.add_argument("--input", required=True, type=Path, help="file holding modelpin watch --json output")
+    _event_flags(watch)
+    _common(watch)
+
+    commands.add_parser("version", help="print the relay version")
+    return parser
+
+
+def _note(err: TextIO, text: str) -> None:
+    print(f"modelpin-relay: {text}", file=err)
+
+
+def _print_utf8(out: TextIO, text: str) -> None:
+    """Writes UTF-8 whatever the console code page is (Windows defaults to cp1252, which garbles `’` and
+    emoji in model output); falls back to text writes for streams without a byte buffer (tests)."""
+    buffer = getattr(out, "buffer", None)
+    if buffer is None:
+        print(text, file=out)
+        return
+    out.flush()
+    buffer.write((text + "\n").encode("utf-8"))
+    buffer.flush()
+
+
+def _json(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, indent=2)
+
+
+def _write(folder: Path, name: str, value: Any) -> None:
+    folder.mkdir(parents=True, exist_ok=True)
+    (folder / name).write_text(_json(value) + "\n", encoding="utf-8", newline="\n")
+
+
+def _warn_version(version: str | None, err: TextIO) -> None:
+    if version is not None and version not in TESTED_MODELPIN_VERSIONS:
+        tested = ", ".join(sorted(TESTED_MODELPIN_VERSIONS))
+        _note(err, f"warning: Modelpin {version} wrote these files; this relay is tested with {tested}")
+
+
+def _installed_modelpin_version() -> str | None:
+    """5.2: when the files don't say, the installed Modelpin's version, read from package metadata only."""
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version("modelpin")
+    except PackageNotFoundError:
+        return None
+
+
+def _relative(path: Path, root: Path) -> str | None:
+    try:
+        return path.resolve().relative_to(root.resolve()).as_posix()
+    except ValueError:
+        return None
+
+
+def _insights_target(source: Source) -> insights.Target | None:
+    """Only a Bitbucket Pipelines build with a full commit hash can post a report."""
+    if source.ci != "bitbucket" or not source.commit:
+        return None
+    workspace, _, slug = source.repo_key.removeprefix("bitbucket:").partition("/")
+    return insights.Target(workspace, slug, source.commit)
+
+
+def _deliver(
+    event: dict[str, Any], args: argparse.Namespace, env: Mapping[str, str], out: TextIO, err: TextIO
+) -> int:
+    try:
+        body = fit(event)
+    except EventTooLarge as exc:
+        _note(err, f"event not sent: {exc}")
+        return EXIT_SEND_FAILED
+    if args.out is not None:
+        _write(args.out, "event.json", event)
+    if args.dry_run:
+        _print_utf8(out, _json(event))
+        return EXIT_OK
+    if args.no_event:
+        return EXIT_OK
+    url = env.get(args.url_env, "").strip()
+    secret = env.get(args.secret_env, "").strip()
+    if not url or not secret:
+        missing = args.url_env if not url else args.secret_env
+        _note(err, f"{missing} is not set, so the event was not sent")
+        return EXIT_OK
+    if not url.startswith("https://") or any(c.isspace() or ord(c) < 32 or ord(c) == 127 for c in url):
+        # Only the variable's name is printed: the URL itself is a secret.
+        _note(err, f"{args.url_env} must be one https:// URL with no spaces or line breaks; the event was not sent")
+        return EXIT_USAGE
+    result = send_event(url, secret, body)
+    answer = f"HTTP {result.status}" if result.status is not None else (result.error or "no response")
+    if result.app_status:
+        answer += f" {result.app_status}"
+    tries = "" if result.attempts == 1 else f" after {result.attempts} attempts"
+    if result.ok:
+        _note(err, f"event {event['event_id']} sent: {answer}{tries}")
+        return EXIT_OK
+    _note(err, f"event {event['event_id']} was not accepted: {answer}{tries}")
+    return EXIT_SEND_FAILED
+
+
+def _post_report(
+    target: insights.Target,
+    report: dict[str, Any],
+    notes: list[dict[str, Any]],
+    *,
+    replace: bool,
+    err: TextIO,
+) -> int:
+    posted = insights.post(target, report, notes, replace=replace)
+    _note(err, "Code Insights: " + "; ".join(posted.steps))
+    return EXIT_OK if posted.ok else EXIT_SEND_FAILED
+
+
+def _pending_or_skip(args: argparse.Namespace, env: Mapping[str, str], cwd: Path, err: TextIO) -> int:
+    ci = resolve_ci(args.ci, env)
+    if ci != "bitbucket":
+        _note(err, "not running in Bitbucket Pipelines, so no Code Insights report was posted")
+        return EXIT_OK
+    source = build_source(ci, env, cwd)
+    target = _insights_target(source)
+    if target is None:
+        _note(err, "BITBUCKET_COMMIT is not a full commit hash, so no Code Insights report was posted")
+        return EXIT_USAGE
+    config = read_config(args.config)
+    from_model = config.models[0] if config.models else None
+    version = _installed_modelpin_version()
+    if args.command == "pending":
+        report = insights.pending_report(from_model, version, source.build_url)
+    else:
+        report = insights.skip_report(args.reason, from_model, version, source.build_url)
+    return _post_report(target, report, [], replace=True, err=err)
+
+
+def _publish(args: argparse.Namespace, env: Mapping[str, str], cwd: Path, out: TextIO, err: TextIO) -> int:
+    source = build_source(resolve_ci(args.ci, env), env, cwd)
+    inputs = CheckInputs(
+        exit_code_raw=args.exit_code,
+        since=args.since,
+        to_model=args.to_model,
+        from_model=args.from_model,
+        provider=args.provider,
+        config_path=args.config,
+        store_dir=args.store_dir,
+        scenarios_dir=args.scenarios_dir,
+        repo_root=cwd,
+    )
+    built = build_check(inputs, source)
+    _warn_version(built.modelpin_version, err)
+    for warning in built.warnings:
+        _note(err, f"warning: {warning}")
+    check = built.payload
+
+    # Git context (8.2): keys in the branch and commit, the files that name either model, their recent history.
+    scenarios_dir = args.scenarios_dir or args.config.parent / built.config.scenarios_dir
+    excluded = [p for p in (_relative(args.store_dir, cwd), _relative(scenarios_dir, cwd), _relative(args.config, cwd)) if p]
+    truncated = list(built.truncated)
+    source.jira_keys = git.jira_keys(source.branch, source.commit, cwd)
+    source.code_refs = git.code_refs([check["from_model"], check["to_model"]], cwd, excluded=excluded)
+    source.history_keys = git.history_keys(source.code_refs, source.jira_keys, cwd)
+    if source.code_refs and git.is_shallow(cwd):
+        truncated.append("history_keys")
+
+    if args.outcome_file is not None:
+        args.outcome_file.write_text(check["outcome"] + "\n", encoding="utf-8")
+    version = built.modelpin_version or _installed_modelpin_version()
+    event = make_event(
+        "check", source, check=check, watch=None, sample=args.sample, modelpin_version=version, truncated=truncated
+    )
+
+    insights_code = EXIT_OK
+    target = _insights_target(source)
+    if target is not None and not args.no_insights:
+        runs = insights.runs_per_scenario(check, built.config.runs)
+        report = insights.check_report(check, version, runs, source.build_url)
+        notes = insights.annotations_for(check)
+        if args.out is not None:
+            _write(args.out, "insights-report.json", report)
+            _write(args.out, "insights-annotations.json", notes)
+        if args.dry_run:
+            _print_utf8(err, "Code Insights report (not posted):\n" + _json({"report": report, "annotations": notes}))
+        else:
+            insights_code = _post_report(target, report, notes, replace=False, err=err)
+    event_code = _deliver(event, args, env, out, err)
+    return event_code if event_code != EXIT_OK else insights_code
+
+
+def _publish_watch(args: argparse.Namespace, env: Mapping[str, str], cwd: Path, out: TextIO, err: TextIO) -> int:
+    source = build_source(resolve_ci(args.ci, env), env, cwd)
+    built = build_watch(read_watch_output(args.input))
+    _warn_version(built.modelpin_version, err)
+    source.jira_keys = git.jira_keys(source.branch, source.commit, cwd)
+    excluded = [p for p in (".modelpin", "scenarios", "modelpin.yaml") if p]
+    input_rel = _relative(args.input, cwd)
+    if input_rel:
+        excluded.append(input_rel)
+    shallow = git.is_shallow(cwd)
+    any_refs = False
+    for model in built.payload["models"]:
+        model["code_refs"] = git.code_refs([model["id"]], cwd, excluded=excluded)
+        model["history_keys"] = git.history_keys(model["code_refs"], source.jira_keys, cwd)
+        any_refs = any_refs or bool(model["code_refs"])
+    event = make_event(
+        "watch",
+        source,
+        check=None,
+        watch=built.payload,
+        sample=args.sample,
+        modelpin_version=built.modelpin_version or _installed_modelpin_version(),
+        truncated=["history_keys"] if shallow and any_refs else [],
+    )
+    return _deliver(event, args, env, out, err)
+
+
+def main(
+    argv: Sequence[str] | None = None,
+    *,
+    env: Mapping[str, str] | None = None,
+    cwd: Path | None = None,
+    out: TextIO | None = None,
+    err: TextIO | None = None,
+) -> int:
+    stdout = out or sys.stdout
+    stderr = err or sys.stderr
+    try:
+        args = build_parser().parse_args(argv)
+    except SystemExit as exc:
+        return int(exc.code) if isinstance(exc.code, int) else EXIT_USAGE
+    environment = os.environ if env is None else env
+    folder = cwd or Path.cwd()
+    # Relative paths are taken from the working folder, so `main(cwd=...)` behaves like running there.
+    for name in ("config", "store_dir", "scenarios_dir", "out", "outcome_file", "input"):
+        value = getattr(args, name, None)
+        if isinstance(value, Path) and not value.is_absolute():
+            setattr(args, name, folder / value)
+    try:
+        if args.command == "version":
+            print(f"modelpin-relay {__version__}", file=stdout)
+            return EXIT_OK
+        if args.command in ("pending", "skip"):
+            return _pending_or_skip(args, environment, folder, stderr)
+        if args.command == "publish":
+            return _publish(args, environment, folder, stdout, stderr)
+        return _publish_watch(args, environment, folder, stdout, stderr)
+    except (PayloadError, ModelpinFileError, UnsupportedCI, OSError) as exc:
+        _note(stderr, f"error: {exc}")
+        return EXIT_USAGE

modelpin_relay/git_context.py

@@ -0,0 +1,139 @@
+"""Read-only git commands (BUILD_BRIEF 8.2). Skipped quietly when git or the repository is unavailable.
+
+The repository's identity for `--ci local` (origin, commit, branch), and the git context of every event: Jira keys
+in the branch and the commit's subject, the files that name the model (`code_refs`), and the Jira keys in the
+last 180 days of those files' folders (`history_keys`). Never authors, emails or messages beyond the keys.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from collections.abc import Iterable
+from pathlib import Path, PurePosixPath
+
+JIRA_KEY = re.compile(r"\b[A-Z][A-Z0-9_]+-[1-9][0-9]*\b")
+MAX_JIRA_KEYS = 10
+MAX_CODE_REFS = 20
+MAX_HISTORY_KEYS = 20
+HISTORY_DAYS = 180
+#: CI configuration files never count as code that calls the model (8.2).
+CI_PATHS = ("bitbucket-pipelines.yml", ".github")
+
+_SEGMENT = re.compile(r"[A-Za-z0-9._-]+")
+_URL_REMOTE = re.compile(r"^(?:https?|ssh|git)://(?:[^@/]+@)?(?P<host>[^/:]+)(?::[0-9]+)?/(?P<path>.+)$")
+_SCP_REMOTE = re.compile(r"^(?:[^@/]+@)?(?P<host>[^:/]+):(?P<path>[^/].*)$")
+_HOSTS = {"bitbucket.org": "bitbucket", "github.com": "github"}
+_FULL_HASH = re.compile(r"[0-9a-f]{40}(?:[0-9a-f]{24})?")
+
+
+def run_git(args: list[str], cwd: Path) -> str | None:
+    """stdout of `git <args>` in `cwd`, or None if git is missing or the command fails."""
+    try:
+        done = subprocess.run(
+            ["git", *args],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=15,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return done.stdout.strip() if done.returncode == 0 else None
+
+
+def repo_key_from_remote(url: str | None) -> str | None:
+    """`bitbucket:<workspace>/<slug>` or `github:<owner>/<repo>` from a remote URL, else None (5.2)."""
+    if not url:
+        return None
+    text = url.strip()
+    found = _URL_REMOTE.match(text) or _SCP_REMOTE.match(text)
+    if found is None:
+        return None
+    prefix = _HOSTS.get(found.group("host").lower())
+    if prefix is None:
+        return None
+    path = found.group("path").rstrip("/")
+    path = path.removesuffix(".git")
+    parts = path.split("/")
+    if len(parts) != 2 or not all(_SEGMENT.fullmatch(p) for p in parts):
+        return None
+    return f"{prefix}:{parts[0]}/{parts[1]}"
+
+
+def local_repo_key(cwd: Path) -> str:
+    """5.2 `ci: local`: the normalised origin, else `local:<folder name>`."""
+    from_remote = repo_key_from_remote(run_git(["remote", "get-url", "origin"], cwd))
+    if from_remote:
+        return from_remote
+    top = run_git(["rev-parse", "--show-toplevel"], cwd)
+    name = Path(top).name if top else cwd.resolve().name
+    name = re.sub(r"[/\\]", "_", name)[:200] or "repository"
+    return f"local:{name}"
+
+
+def head_commit(cwd: Path) -> str | None:
+    commit = run_git(["rev-parse", "HEAD"], cwd)
+    return commit if commit and _FULL_HASH.fullmatch(commit) else None
+
+
+def current_branch(cwd: Path) -> str | None:
+    branch = run_git(["rev-parse", "--abbrev-ref", "HEAD"], cwd)
+    return branch[:255] if branch and branch != "HEAD" else None
+
+
+def _unique(items: Iterable[str]) -> list[str]:
+    return list(dict.fromkeys(items))
+
+
+def jira_keys(branch: str | None, commit: str | None, cwd: Path) -> list[str]:
+    """Keys in the branch name and in the subject of the checked commit (never HEAD, a merge in PR builds)."""
+    texts = [branch or ""]
+    if commit:
+        texts.append(run_git(["log", "-1", "--format=%s", commit], cwd) or "")
+    keys = [k for k in JIRA_KEY.findall("\n".join(texts)) if len(k) <= 64]
+    return _unique(keys)[:MAX_JIRA_KEYS]
+
+
+def code_refs(model_ids: Iterable[str], cwd: Path, *, excluded: Iterable[str] = ()) -> list[str]:
+    """Tracked files that contain any of the model ids, minus `excluded` paths and CI configuration (8.2)."""
+    patterns: list[str] = []
+    for model_id in _unique(m for m in model_ids if m):
+        patterns += ["-e", model_id]
+    if not patterns:
+        return []
+    exclusions = [f":(exclude){p}" for p in (*excluded, *CI_PATHS) if p and p != "."]
+    found = run_git(["-c", "core.quotePath=false", "grep", "-l", "-z", "-F", *patterns, "--", ".", *exclusions], cwd)
+    if not found:
+        return []
+    names = {name.replace("\\", "/")[:500] for name in found.split("\0") if name.strip()}
+    return sorted(names)[:MAX_CODE_REFS]
+
+
+def history_folders(refs: Iterable[str]) -> list[str]:
+    """The folder of each file; a file at the root stands for itself, never for the whole repository."""
+    folders = set()
+    for ref in refs:
+        path = PurePosixPath(ref)
+        folders.add(str(path.parent) if str(path.parent) != "." else str(path))
+    return sorted(folders)
+
+
+def is_shallow(cwd: Path) -> bool:
+    return run_git(["rev-parse", "--is-shallow-repository"], cwd) == "true"
+
+
+def history_keys(refs: Iterable[str], exclude: Iterable[str], cwd: Path) -> list[str]:
+    """Jira keys in the subjects of the last 180 days of commits that touched the folders, newest first (8.2)."""
+    folders = history_folders(refs)
+    if not folders:
+        return []
+    subjects = run_git(["log", f"--since={HISTORY_DAYS} days ago", "--format=%s", "--", *folders], cwd)
+    if not subjects:
+        return []
+    skip = set(exclude)
+    keys = [key for key in _unique(JIRA_KEY.findall(subjects)) if key not in skip and len(key) <= 64]
+    return keys[:MAX_HISTORY_KEYS]