pr-analyzer-cli 0.1.0__py3-none-any.whl

pr_analyzer/exceptions.py

@@ -0,0 +1,41 @@
+from datetime import datetime
+
+
+class PRAnalyzerError(Exception):
+    pass
+
+
+class InvalidPRURLError(PRAnalyzerError, ValueError):
+    # also a ValueError, so code that validates URLs with `except ValueError` keeps working
+    pass
+
+
+class ConfigError(PRAnalyzerError):
+    pass
+
+
+class InvalidTokenError(PRAnalyzerError):
+    pass
+
+
+class PrivateRepoError(PRAnalyzerError):
+    pass
+
+
+class PRNotFoundError(PRAnalyzerError):
+    pass
+
+
+class RepositoryNotFoundError(PRAnalyzerError):
+    pass
+
+
+class RateLimitError(PRAnalyzerError):
+    def __init__(self, reset_time: datetime):
+        self.reset_time = reset_time
+        super().__init__(f"Rate limit exceeded. Resets at {reset_time.strftime('%H:%M:%S')}")
+
+
+class LLMError(PRAnalyzerError):
+    # the LLM provider could not be reached or returned something unusable
+    pass

pr_analyzer/github/client.py

@@ -0,0 +1,398 @@
+import threading
+from concurrent.futures import FIRST_EXCEPTION, ThreadPoolExecutor, wait
+from datetime import datetime, timedelta
+from urllib.parse import urlsplit
+
+import requests
+import structlog
+from github import Auth, Github, GithubException, RateLimitExceededException
+from github.Commit import Commit
+from github.GithubObject import NotSet, Opt
+from github.PullRequest import PullRequest, ReviewComment
+
+from pr_analyzer.cache import DiskCache
+from pr_analyzer.config import settings
+from pr_analyzer.exceptions import (
+    InvalidPRURLError,
+    InvalidTokenError,
+    PRAnalyzerError,
+    PRNotFoundError,
+    PrivateRepoError,
+    RateLimitError,
+    RepositoryNotFoundError,
+)
+from pr_analyzer.github.markdown import neutralise, neutralise_line
+from pr_analyzer.github.ratelimit import (
+    RateLimitExceeded,
+    RateLimitPause,
+    RateLimitRetry,
+    github_retry,
+)
+from pr_analyzer.models import FileChange, PRSummary, Suggestion
+
+log = structlog.get_logger(__name__)
+
+GITHUB_HOSTS = {"github.com", "www.github.com"}
+# PR pages people copy URLs from: /pull/123, /pull/123/files, /pull/123/commits, /pull/123/checks
+PR_SUBPAGES = {"files", "commits", "checks"}
+# hidden tag on the summary review, so a later run can find and update it
+REVIEW_MARKER = "<!-- pr-analyzer -->"
+# GitHub's maximum page size: a PR with 300 files is listed in 3 requests instead of 10
+PER_PAGE = 100
+
+
+class GithubClient:
+
+    def __init__(
+        self,
+        token: str | None = None,
+        cache: DiskCache | None = None,
+        rate_limits: RateLimitPause | None = None,
+    ):
+        self.token = settings.github_token if token is None else token
+        self.cache = cache if cache is not None else DiskCache.disabled()
+        self.max_workers = settings.github_max_workers
+        # retry transient 5xx errors on reads, and wait out rate limits for up to
+        # GITHUB_RATE_LIMIT_MAX_WAIT_SECONDS; a longer wait surfaces as RateLimitError
+        self.retry = github_retry(settings.github_rate_limit_max_wait_seconds, rate_limits)
+        self.auth = Auth.Token(self.token) if self.token else None
+        self.git_instance = self._new_github()
+
+    def _new_github(self, lazy: bool = False, retry: RateLimitRetry | None = None) -> Github:
+        return Github(
+            auth=self.auth,
+            timeout=settings.github_timeout_seconds,
+            retry=retry if retry is not None else self.retry,
+            per_page=PER_PAGE,
+            lazy=lazy,
+        )
+
+    def close(self) -> None:
+        self.git_instance.close()
+
+    def fetch_pr(self, url: str) -> PRSummary:
+        repo_name, pr_number = self.parse_url_and_validate(url)
+        if not self.token:
+            log.warning("github_token_missing", hint="unauthenticated requests are limited to 60/hour")
+        log.info("fetch_started", repo=repo_name, pr=pr_number)
+
+        try:
+            try:
+                repo = self.git_instance.get_repo(repo_name)
+            except GithubException as e:
+                if e.status == 404:
+                    raise RepositoryNotFoundError(
+                        f"{repo_name} does not exist or your token cannot see it"
+                    ) from e
+                raise
+
+            try:
+                pr = repo.get_pull(pr_number)
+            except GithubException as e:
+                if e.status == 404:
+                    raise PRNotFoundError(f"PR #{pr_number} not found in {repo_name}") from e
+                raise
+
+            return PRSummary(
+                number=pr.number,
+                title=pr.title,
+                author=pr.user.login if pr.user else "unknown",
+                repo=repo_name,
+                base_branch=pr.base.ref,
+                head_branch=pr.head.ref,
+                total_additions=pr.additions,
+                total_deletions=pr.deletions,
+                is_draft=bool(pr.draft),
+                files=self.build_file_changes(pr, repo),
+                head_sha=pr.head.sha,
+            )
+        except RateLimitExceededException as e:
+            raise RateLimitError(self._reset_time(e)) from e
+        except GithubException as e:
+            raise self._map_error(e, repo_name) from e
+        except requests.exceptions.RequestException as e:
+            raise PRAnalyzerError(f"Could not reach GitHub: {e}") from e
+
+    def parse_url_and_validate(self, pr_url: str) -> tuple[str, int]:
+        if not pr_url or not pr_url.strip():
+            raise InvalidPRURLError("The URL cannot be empty")
+
+        parts = urlsplit(pr_url.strip())
+        if parts.scheme != "https":
+            raise InvalidPRURLError("URL must start with https://")
+        if parts.netloc.lower() not in GITHUB_HOSTS:
+            raise InvalidPRURLError("Domain must be github.com")
+
+        path = parts.path.strip("/").split("/")
+        if len(path) == 5 and path[4] in PR_SUBPAGES:
+            path = path[:4]
+        if len(path) != 4 or path[2] != "pull" or not path[0] or not path[1]:
+            raise InvalidPRURLError("Expected https://github.com/<owner>/<repo>/pull/<number>")
+        if not (path[3].isascii() and path[3].isdigit()):
+            raise InvalidPRURLError(f"PR number must be an integer, got: {path[3]!r}")
+
+        repo_name = f"{path[0]}/{path[1]}"
+        pr_number = int(path[3])
+        log.info("url_validated", repo=repo_name, pr=pr_number)
+        return repo_name, pr_number
+
+    def build_file_changes(self, pr, repo) -> list[FileChange]:
+        files = []
+        blobs: dict[str, str | None] = {}
+        for f in pr.get_files():
+            if f.patch is None:
+                # binary files, very large diffs and pure renames come without a patch
+                log.info("file_skipped_no_patch", filename=f.filename, status=f.status)
+                continue
+
+            files.append(FileChange(
+                filename=f.filename,
+                status=f.status,
+                additions=f.additions,
+                deletions=f.deletions,
+                patch=f.patch,
+            ))
+            # the file's git blob SHA: its content's identity, the same from push to push
+            # while the file doesn't change
+            sha = getattr(f, "sha", None)
+            blobs[f.filename] = sha if isinstance(sha, str) else None
+
+        present = [f for f in files if f.status != "removed"]
+        wanted = [(f.filename, blobs[f.filename]) for f in present]
+        contents = self.fetch_contents(repo, wanted, pr.head.sha)
+        for f, content in zip(present, contents, strict=True):
+            f.raw_content = content
+
+        log.info("files_fetched", repo=repo.full_name, pr=pr.number, file_count=len(files))
+        return files
+
+    def fetch_contents(
+        self, repo, files: list[tuple[str, str | None]], ref: str
+    ) -> list[str | None]:
+        """The text at `ref` of each (path, blob SHA) in `files`, in order (None where it isn't
+        available), from the cache or fetched GITHUB_MAX_WORKERS at a time.
+
+        The first failure, or Ctrl-C, ends a parallel fetch at once: the files still queued
+        aren't fetched, and the requests in flight stop waiting and aren't sent again."""
+        repo_name = repo.full_name
+        if len(files) < 2 or self.max_workers < 2:
+            # on the main thread, which Ctrl-C reaches itself
+            return [
+                self._cached_content(repo, repo_name, file, ref, self.retry.pause) for file in files
+            ]
+
+        # PyGithub's Requester isn't thread-safe: it keeps one connection object per client, and
+        # that object holds each request's verb, URL and headers in attributes between request()
+        # and getresponse() (HTTPSRequestsConnectionClass in github/Requester.py), so two threads
+        # sharing a client can send each other's requests. Each worker thread gets a client of
+        # its own instead: its own Requester, connection and requests.Session. What the threads
+        # share (the token, the retry policy and the cache) holds no per-request state.
+        # Their rate-limit waits hold back the run's other requests as usual, but this fetch can
+        # cancel them: Ctrl-C reaches only the main thread.
+        pause = self.retry.pause.scope()
+        retry = self.retry.new(pause=pause)
+        local = threading.local()
+        clients: list[Github] = []
+        lock = threading.Lock()
+
+        def fetch(file: tuple[str, str | None]) -> str | None:
+            thread_repo = getattr(local, "repo", None)
+            if thread_repo is None:
+                with lock:   # once the clients are being closed, no new one is made
+                    pause.raise_if_cancelled()
+                    client = self._new_github(lazy=True, retry=retry)   # lazy: no request yet
+                    clients.append(client)
+                thread_repo = local.repo = client.get_repo(repo_name)
+            return self._cached_content(thread_repo, repo_name, file, ref, pause)
+
+        pool = ThreadPoolExecutor(
+            max_workers=min(self.max_workers, len(files)), thread_name_prefix="github-contents"
+        )
+        try:
+            futures = [pool.submit(fetch, file) for file in files]
+            # a failure is raised as soon as it happens, not once the files before it are in
+            wait(futures, return_when=FIRST_EXCEPTION)
+            errors = [e for f in futures if f.done() and (e := f.exception()) is not None]
+            if errors:
+                raise errors[0]
+            contents = [future.result() for future in futures]
+        except BaseException:
+            # Ctrl-C or a failure: the waits in flight end and nothing is sent again, the fetches
+            # still queued are dropped, and the ones in flight aren't waited for
+            pause.cancel()
+            pool.shutdown(wait=False, cancel_futures=True)
+            raise
+        finally:
+            with lock:
+                for client in clients:
+                    client.close()
+        pool.shutdown()   # every fetch is done: the workers are idle
+        return contents
+
+    def _cached_content(
+        self, repo, repo_name: str, file: tuple[str, str | None], ref: str, pause: RateLimitPause
+    ) -> str | None:
+        # the text of a blob never changes, and neither does a path's at a commit
+        path, blob = file
+        owner_repo = repo_name.lower()
+        key = ("blob", owner_repo, blob) if blob else ("commit", owner_repo, ref, path)
+        text = self.cache.get("contents", *key)
+        if text is not None:
+            return text
+
+        pause.wait_if_paused()   # while a request waits out a rate limit, hold back
+        text, sha = self._fetch_content(repo, path, ref)
+        # the PR may have moved on since its files were listed; a blob's key gets only its text
+        if text is not None and (blob is None or sha == blob):
+            self.cache.put("contents", *key, value=text)
+        return text
+
+    def _fetch_content(self, repo, path: str, ref: str) -> tuple[str | None, str | None]:
+        """The file's text at `ref` and its blob SHA, or (None, None) if it can't be had."""
+        try:
+            content = repo.get_contents(path, ref=ref)
+        except RateLimitExceededException:
+            raise
+        except GithubException as e:
+            log.warning("content_unavailable", filename=path, status=e.status)
+            return None, None
+
+        # a list means a directory or submodule; files over 1 MB come back without base64 content
+        if isinstance(content, list) or content.encoding != "base64":
+            log.warning("content_unavailable", filename=path, reason="not a file or over 1 MB")
+            return None, None
+        text = content.decoded_content.decode("utf-8", errors="replace")
+        return text, getattr(content, "sha", None)
+
+    def fetch_file(self, repo_name: str, path: str, ref: str) -> bytes | None:
+        """The raw bytes of `path` at `ref` (a branch, tag or commit), or None if there's no such
+        file. Used for .pr-analyzer.toml on the PR's base branch."""
+        try:
+            content = self.git_instance.get_repo(repo_name).get_contents(path, ref=ref)
+        except RateLimitExceededException as e:
+            raise RateLimitError(self._reset_time(e)) from e
+        except GithubException as e:
+            if e.status == 404:
+                return None
+            # anything else must not silently fall back to defaults the project didn't choose
+            problem = self._map_error(e, repo_name)
+            raise PRAnalyzerError(f"Could not read {path} at {ref}: {problem}") from e
+        except requests.exceptions.RequestException as e:
+            raise PRAnalyzerError(f"Could not reach GitHub: {e}") from e
+
+        if isinstance(content, list):
+            return None   # a directory of that name
+        if content.encoding != "base64":
+            raise PRAnalyzerError(f"{path} at {ref} is over 1 MB, too large to read")
+        return content.decoded_content
+
+    def post_review(
+        self, pr: PRSummary, body: str, comments: list[tuple[Suggestion, int]]
+    ) -> None:
+        if not self.token:
+            raise InvalidTokenError("--post-review needs a GITHUB_TOKEN that can write pull requests")
+
+        # titles and descriptions can come from the LLM or quote the PR's code: neutralise them so
+        # they can't ping people, hide text in HTML or show links (the path is an API field)
+        review_comments: list[ReviewComment] = [
+            {
+                "path": suggestion.filename,
+                "line": line,
+                "side": "RIGHT",
+                "body": f"**{suggestion.severity}** — {neutralise_line(suggestion.title)}\n\n"
+                        f"{neutralise(suggestion.description)}",
+            }
+            for suggestion, line in comments
+        ]
+        summary = f"{body}\n\n{REVIEW_MARKER}"
+
+        try:
+            repo = self.git_instance.get_repo(pr.repo)
+            pull = repo.get_pull(pr.number)
+            # pin the review to the analysed commit so line numbers match even if the PR moved on
+            commit = repo.get_commit(pr.head_sha) if pr.head_sha else NotSet
+
+            # every push re-runs the analysis, and each run used to add a whole new review that
+            # repeated every comment. Skip findings already commented on (GitHub clears `line`
+            # once the code under a comment changes, so those get a fresh comment) and update the
+            # earlier summary in place.
+            posted = {(c.path, c.line, c.body.strip()) for c in pull.get_review_comments()}
+            review_comments = [
+                c for c in review_comments if (c["path"], c["line"], c["body"].strip()) not in posted
+            ]
+            if not self._update_summary(pull, summary):
+                review_comments = self._create_review(pull, commit, summary, review_comments)
+            elif review_comments:
+                note = (f"**pr-analyzer:** {len(review_comments)} new finding(s) since the last run. "
+                        f"The summary in its earlier review is kept up to date.")
+                review_comments = self._create_review(pull, commit, note, review_comments)
+        except RateLimitExceededException as e:
+            raise RateLimitError(self._reset_time(e)) from e
+        except GithubException as e:
+            raise self._map_error(e, pr.repo) from e
+        except requests.exceptions.RequestException as e:
+            raise PRAnalyzerError(f"Could not reach GitHub: {e}") from e
+
+        log.info("review_posted", pr=pr.number, comments=len(review_comments))
+
+    @staticmethod
+    def _update_summary(pull: PullRequest, summary: str) -> bool:
+        """Edit the summary review an earlier run posted; False if there's none this token may edit."""
+        # newest first: when several accounts run pr-analyzer on a PR, only our own review is editable
+        for review in reversed(list(pull.get_reviews())):
+            if REVIEW_MARKER not in (review.body or ""):
+                continue
+            try:
+                review.edit(summary)
+                return True
+            except RateLimitExceededException:
+                # a 403 too, but not "someone else's review": posting a new one would duplicate it
+                raise
+            except GithubException as e:
+                if e.status not in (403, 404):
+                    raise
+        return False
+
+    @staticmethod
+    def _create_review(
+        pull: PullRequest, commit: Opt[Commit], body: str, comments: list[ReviewComment]
+    ) -> list[ReviewComment]:
+        """Post a review and return the inline comments that went with it."""
+        try:
+            pull.create_review(commit=commit, body=body, event="COMMENT", comments=comments)
+            return comments
+        except GithubException as e:
+            if e.status != 422 or not comments:
+                raise
+            # GitHub rejects the whole review if any inline comment falls outside the diff;
+            # post the text alone rather than nothing
+            log.warning("inline_comments_rejected", error=str(e.data))
+            pull.create_review(
+                commit=commit,
+                body=body + "\n\n_Inline comments could not be attached to this diff._",
+                event="COMMENT",
+            )
+            return []
+
+    @staticmethod
+    def _map_error(e: GithubException, repo_name: str) -> PRAnalyzerError:
+        if e.status == 401:
+            return InvalidTokenError("GITHUB_TOKEN is invalid or expired")
+        if e.status == 403:
+            return PrivateRepoError(f"Your token is not allowed to access {repo_name}")
+        message = e.data.get("message") if isinstance(e.data, dict) else e.data
+        return PRAnalyzerError(f"GitHub error {e.status}: {message}")
+
+    @staticmethod
+    def _reset_time(e: RateLimitExceededException) -> datetime:
+        if isinstance(e, RateLimitExceeded):
+            # the retry policy worked it out, from an HTTP date or GitHub's minute for a limit
+            # named only in the message too (x-ratelimit-reset is the hourly limit's)
+            return datetime.fromtimestamp(e.retry_at)
+        headers = {k.lower(): v for k, v in (e.headers or {}).items()}
+        try:
+            if "retry-after" in headers:  # secondary rate limits say how long to wait
+                return datetime.now() + timedelta(seconds=int(headers["retry-after"]))
+            return datetime.fromtimestamp(int(headers["x-ratelimit-reset"]))
+        except (KeyError, TypeError, ValueError):
+            return datetime.now()

pr_analyzer/github/markdown.py

@@ -0,0 +1,199 @@
+"""Neutralise untrusted text before the bot posts it on GitHub.
+
+Much of what the bot posts is shaped by the PR: titles and descriptions the LLM wrote after
+reading it, Semgrep messages that quote its code, and file names it chose. Posted as-is, that text
+could ping people, hide the rest of the review inside an HTML comment, fake the bot's hidden
+review tag, or show a convincing link. A zero-width space after the character that starts each
+of these keeps the text looking the same while GitHub no longer recognises it:
+
+    @                   mentions (@user, @org/team) and e-mail autolinks
+    < + letter / ! ?    raw HTML, including <!-- comments --> and <https://...> autolinks
+    ] + ( [ :           links and images, [text](url), [text][ref] and ![alt](src), and
+                        reference definitions [x]: url
+    :// www.            bare-URL autolinks
+    # or GH- + digit    issue and PR references (#12, GH-12), which would add a cross-link to
+                        the referenced issue
+    & + # or name;      character references such as &#x40; and &commat;, which GitHub would
+                        decode into the characters above
+
+Nothing else changes. A "<" or "]" that can't start any of these is left as it is, and so is
+code: GitHub shows inline code spans and fenced code blocks exactly as written, and an invisible
+character in them would break copying the code or committing a suggested change. Only "]:" in
+inline code still gets one, since a reference definition is read before code spans are. Whatever
+GitHub might not show as code is neutralised like the rest: blocks it draws instead (maths,
+diagrams), code that a "$" could turn into maths, and code whose place can't be told for sure.
+
+Single-line contexts (list items, table cells) also lose their newlines, so the text can't add
+headings or rows of its own.
+"""
+import re
+
+ZERO_WIDTH_SPACE = "\u200b"
+
+# where a zero-width space goes, unless one is already there. GitHub decodes backslash escapes
+# too, so GH\-12, http:\/\/ and www\. count as well.
+_BREAK = re.compile(
+    r"(?:(?<=@)"
+    r"|(?<=<)(?=[a-z/!?])"
+    r"|(?<=\])(?=[(\[:])"
+    r"|(?<=:)(?=\\?/\\?/)"
+    r"|(?<=www)(?=\\?\.)"
+    r"|(?<=#)(?=\d)"
+    r"|(?:(?<=gh-)|(?<=gh\\-))(?=\d)"
+    r"|(?<=&)(?=#|[a-z][a-z0-9]*;)"
+    r")(?!\u200b)",
+    re.IGNORECASE,
+)
+# A reference definition, [label]: url, is read before code spans are, so that a later [label]
+# links to url. Inline code still gets a zero-width space between "]" and ":".
+_LABEL_END = re.compile(r"(?<=\])(?=:)")
+
+# CommonMark's line endings; split() keeps them, so the text goes back together unchanged
+_LINE_ENDING = re.compile(r"(\r\n|\r|\n)")
+_BLANK = re.compile(r"[ \t]*")
+# a line that opens a fenced code block: three or more backticks with none in the info string
+# after them, or three or more tildes
+_FENCE_OPEN = re.compile(r"(`{3,})([^`]*)|(~{3,})(.*)", re.DOTALL)
+_FENCE_CLOSE = re.compile(r" {0,3}(`+|~+)[ \t]*")
+# a fence indented by one to three spaces, which may belong to a list item
+_INDENTED_FENCE = re.compile(r" {1,3}(?:```|~~~)")
+# what could be a fence anywhere in a line, as in a list item or a block quote
+_FENCE_RUN = re.compile(r"`{3,}|~{3,}")
+# GitHub draws these blocks (maths, diagrams, maps, models) instead of showing them as code, and
+# the drawing could hold a link; so could maths written with "$" around code. Both are text here.
+_DRAWN = {"math", "mermaid", "geojson", "topojson", "stl"}
+# a plain language name in an info string, such as python, c++ or objective-c
+_LANGUAGE = re.compile(r"[\w+#.-]+")
+# what an inline parser stops at on its way to a code span: a backslash escape or backticks
+_ESCAPE_OR_BACKTICKS = re.compile(r"\\[!-/:-@\[-`{-~]|`+")
+# an e-mail autolink, <name@host>, whose name holds a backtick: the autolink comes first
+_MAIL_WITH_BACKTICK = re.compile(r"<[\w.!#$%&'*+/=?^`{|}~-]*`[\w.!#$%&'*+/=?^`{|}~-]*@")
+# GitHub's parser (cmark-gfm) never opens a code span with a longer run of backticks
+_MAX_BACKTICKS = 1000
+
+
+def neutralise(text: str) -> str:
+    """Untrusted text made safe to post as GitHub Markdown, still reading the same. The text must
+    start a block of its own at the top level of the comment, as a review comment's description
+    does after a blank line; in a list item or a table cell, use neutralise_line()."""
+    parts = _LINE_ENDING.split(str(text))
+    lines = parts[::2]
+    unsure = False   # whether an earlier line of the paragraph makes its code spans uncertain
+    for i, block in enumerate(_fenced_blocks(lines)):
+        if block == "code" or _BLANK.fullmatch(lines[i]):
+            unsure = False   # a code block or a blank line ends the paragraph
+            continue
+        lines[i], unsettling = _neutralise_inline(lines[i], trust_code=block == "" and not unsure)
+        # so does a drawn block, whose lines are all neutralised
+        unsure = block == "" and (unsure or unsettling)
+    parts[::2] = lines
+    return "".join(parts)
+
+
+def neutralise_line(text: str) -> str:
+    """neutralise() for text that must stay on one line."""
+    return _neutralise_inline(" ".join(str(text).split()))[0]
+
+
+def code_span(text: str) -> str:
+    """Untrusted text as inline code. The fence is longer than any run of backticks inside, so
+    a file name like a`b can't close the span early."""
+    text = " ".join(str(text).split())
+    longest = max((len(run) for run in re.findall(r"`+", text)), default=0)
+    fence = "`" * (longest + 1)
+    padding = " " if text.startswith("`") or text.endswith("`") else ""
+    return f"{fence}{padding}{text}{padding}{fence}"
+
+
+def _neutralise_inline(line: str, trust_code: bool = True) -> tuple[str, bool]:
+    """One line of Markdown neutralised outside its code spans, and whether the later lines of
+    its paragraph can no longer trust theirs: a run of backticks left open could pair with one of
+    theirs, and after a "$" their code could be maths."""
+    spans, left_open = _code_spans(line)
+    # a run left open on an earlier line, or an e-mail autolink, would pair the backticks
+    # differently, and a table splits its rows at every "|", inside code spans too: then none of
+    # the line counts as code
+    if (not trust_code or _MAIL_WITH_BACKTICK.search(line)
+            or any("|" in line[start:end] for start, end in spans)):
+        spans = []
+    # code after a "$" could be maths, $`...`$ or inside $...$ or $$...$$, which GitHub draws
+    dollar = line.find("$")
+    if dollar != -1:
+        spans = [(start, end) for start, end in spans if start < dollar]
+    pieces, pos = [], 0
+    for start, end in spans:
+        code = _LABEL_END.sub(ZERO_WIDTH_SPACE, line[start:end])
+        pieces += [_BREAK.sub(ZERO_WIDTH_SPACE, line[pos:start]), code]
+        pos = end
+    pieces.append(_BREAK.sub(ZERO_WIDTH_SPACE, line[pos:]))
+    return "".join(pieces), left_open or dollar != -1
+
+
+def _code_spans(line: str) -> tuple[list[tuple[int, int]], bool]:
+    """The (start, end) of each inline code span in one line, found as CommonMark finds them, and
+    whether a run of backticks found no partner on the line.
+
+    A span opens at a run of backticks that isn't backslash-escaped and closes at the next run of
+    exactly as many; a backslash inside a span is just a backslash. A run with no partner is
+    plain text, and the search goes on after it."""
+    spans: list[tuple[int, int]] = []
+    left_open = False
+    pos = 0
+    while opening := _ESCAPE_OR_BACKTICKS.search(line, pos):
+        pos = opening.end()
+        if opening[0].startswith("\\") or len(opening[0]) > _MAX_BACKTICKS:
+            continue
+        closing = re.compile(rf"(?<!`){opening[0]}(?!`)").search(line, pos)
+        if closing:
+            spans.append((opening.start(), closing.end()))
+            pos = closing.end()
+        else:
+            left_open = True
+    return spans, left_open
+
+
+def _fenced_blocks(lines: list[str]) -> list[str]:
+    """For each line, the fenced block it belongs to, fences included: "code" for one GitHub
+    shows as code, "drawn" for one it draws instead (see _DRAWN), "" for none.
+
+    A fence at the very start of a line can't be inside a list item or a block quote, so its block
+    ends only at its closing fence (or the end of the text). One indented by a few spaces may be in
+    a list item, which a later line can end before the fence does, so from there on no fence is
+    trusted. Once a drawn block may have opened where its end can't be told, every later line
+    counts as drawn."""
+    blocks: list[str] = []
+    fence = kind = ""   # the open block's fence, such as ``` or ~~~~, and its kind
+    trusted = True
+    rest = ""   # what lines outside a trusted block count as
+    for line in lines:
+        if fence:
+            blocks.append(kind)
+            fence = "" if _closes(line, fence) else fence
+            continue
+        opening = _FENCE_OPEN.fullmatch(line) if trusted else None
+        if opening:
+            fence = opening[1] or opening[3]
+            kind = "code" if _shown_as_code(opening[2] if opening[1] else opening[4]) else "drawn"
+            blocks.append(kind)
+            continue
+        if any(not _shown_as_code(line[run.end():]) for run in _FENCE_RUN.finditer(line)):
+            rest = "drawn"
+        trusted = trusted and not _INDENTED_FENCE.match(line)
+        blocks.append(rest)
+    return blocks
+
+
+def _closes(line: str, fence: str) -> bool:
+    """Whether the line is a closing fence for a block opened with `fence`."""
+    closing = _FENCE_CLOSE.fullmatch(line)
+    return closing is not None and closing[1][0] == fence[0] and len(closing[1]) >= len(fence)
+
+
+def _shown_as_code(info: str) -> bool:
+    """Whether GitHub shows a fenced block with this info string as code. The first word names
+    the language; one that isn't a plain name could still decode to the name of a drawn block.
+    Zero-width spaces don't count, so that neutralising the text again can't change the answer."""
+    words = info.replace(ZERO_WIDTH_SPACE, "").split()
+    if not words:
+        return True
+    return _LANGUAGE.fullmatch(words[0]) is not None and words[0].lower() not in _DRAWN