Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

5.2 KB
Raw Blame
"""Reads one command out of a GitHub comment body.

The parser is deliberately strict. A command is a line that starts with the mention, so prose
that only talks about the bot ("thanks @posthog, review looks good") never fires. Commands come
only from top-level paragraphs, as the CommonMark reference implementation parses them, so text
that GitHub shows as a quote, code, a list item or an HTML block never fires. That matters most
for the bot's own replies and for agents that echo a comment back, because both repeat the
command text they answer.
"""

import re

from markdown_it import MarkdownIt
from markdown_it.token import Token

from posthog.dataclasses import frozen

from ...logic.schema import HELP_VERB, MENTION, sanitize_argument

# A command comment is short, and the CommonMark parse of the largest comment GitHub allows costs
# most of a second inside the webhook request.
MAX_BODY_LENGTH = 10_000

# The "commonmark" preset parses raw HTML, so HTML blocks become their own tokens. GitHub renders
# tables, and a table cell is shown as table content, not as a paragraph.
_MARKDOWN = MarkdownIt("commonmark").enable("table")
_CONTAINER_OPEN = frozenset({"blockquote_open", "bullet_list_open", "ordered_list_open", "list_item_open"})
_CONTAINER_CLOSE = frozenset({"blockquote_close", "bullet_list_close", "ordered_list_close", "list_item_close"})
# A code span becomes a placeholder, so the text before a mention keeps it off the line start.
_CODE_SPAN_PLACEHOLDER = "x"
# GitHub's table parser accepts a delimiter row that markdown-it rejects, such as a header with no
# pipe, so a paragraph holding one may be a table on GitHub.
_TABLE_DELIMITER_ROW_RE = re.compile(r"^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?\s*$")
# Paragraph lines carry no leading indentation, so the mention must be the first character.
# The mention must stand alone: `@posthog-bot` and `@posthogx` are other accounts.
_COMMAND_LINE_RE = re.compile(
    rf"^{re.escape(MENTION)}(?![\w-])[ \t]+(?P<verb>[A-Za-z][\w-]{{0,31}})(?P<rest>.*)$",
    re.IGNORECASE,
)
_BARE_MENTION_RE = re.compile(rf"^{re.escape(MENTION)}(?![\w-])\s*$", re.IGNORECASE)


@frozen
class ParsedCommand:
    verb: str
    argument: str


@frozen
class AmbiguousCommand:
    """The comment holds more than one command line, so no single intent can be read from it."""

    count: int


ParseResult = ParsedCommand | AmbiguousCommand | None


def parse_command(body: str) -> ParseResult:
    """Return the one command in ``body``, ``AmbiguousCommand`` for several, or ``None`` for none.

    A line with the bare mention and no verb is read as ``help``.
    """
    # Nearly every comment has no mention, so the CommonMark parse runs only for the few that might
    # hold a command, which keeps the webhook request cheap.
    if MENTION not in body.casefold() or len(body) > MAX_BODY_LENGTH:
        return None
    commands: list[ParsedCommand] = []
    for line in _live_lines(body):
        if _BARE_MENTION_RE.match(line):
            commands.append(ParsedCommand(verb=HELP_VERB, argument=""))
            continue
        match = _COMMAND_LINE_RE.match(line)
        if match is None:
            continue
        commands.append(
            ParsedCommand(verb=match.group("verb").lower(), argument=sanitize_argument(match.group("rest")))
        )
    if len(commands) > 1:
        return AmbiguousCommand(count=len(commands))
    return commands[0] if commands else None


def _paragraph_lines(inline: Token) -> list[str]:
    lines = [""]
    for child in inline.children or []:
        if child.type == "html_inline":
            # GitHub renders raw HTML by its own rules (unclosed tags, nesting, block tags mid-line),
            # so the line holding it and the text after it are not reliably the person's plain words.
            return lines[:-1]
        if child.type == "text":
            lines[-1] += child.content
        elif child.type in ("softbreak", "hardbreak"):
            lines.append("")
        elif child.type in ("code_inline", "image"):
            lines[-1] += _CODE_SPAN_PLACEHOLDER
    return lines


def _is_table_delimiter_row(line: str) -> bool:
    # A plain "---" is a heading underline, which markdown-it already reads as a heading.
    return ("|" in line or ":" in line) and _TABLE_DELIMITER_ROW_RE.match(line) is not None


def _live_lines(body: str) -> list[str]:
    """Lines of the top-level paragraphs, the only text a person types as their own words.

    GitHub shows everything else as code, a quote, a list item, a table or an HTML block.
    """
    lines: list[str] = []
    container_depth = 0
    in_live_paragraph = False
    for token in _MARKDOWN.parse(body):
        if token.type in _CONTAINER_OPEN:
            container_depth += 1
        elif token.type in _CONTAINER_CLOSE:
            container_depth -= 1
        elif token.type == "paragraph_open":
            in_live_paragraph = container_depth == 0
        elif token.type == "paragraph_close":
            in_live_paragraph = False
        elif token.type == "inline" and in_live_paragraph:
            paragraph_lines = _paragraph_lines(token)
            if not any(_is_table_delimiter_row(line) for line in paragraph_lines):
                lines.extend(paragraph_lines)
    return lines