lambda-watcher 0.1.0__py3-none-any.whl

lambda_watcher/diffing/highlight.py

@@ -0,0 +1,312 @@
+"""Syntax highlighting for the HTML report, without a highlighting library.
+
+A report is meant to survive being emailed, dropped in a bucket or attached to
+a change ticket, so it cannot pull Prism or highlight.js off a CDN — and
+vendoring one would be a lot of borrowed code to carry for a diff view. What a
+diff actually needs is much smaller: enough colour to tell comments, strings,
+numbers and keywords apart so the eye can skip to the line that matters.
+
+So each language family is one combined regular expression whose named groups
+carry the token class, scanned left to right; whatever falls between two
+matches is plain text. The first letter of the group name *is* the class, which
+is what keeps the rule tables below readable.
+
+There are two ways in:
+
+* ``highlight_lines(text, lang)`` tokenises a **whole file** and hands back one
+  string per line. This is the one the report uses, because a docstring or a
+  licence header only comes out right when the lexer can see where the block
+  opened. Multi-line rules are written to span newlines, so the same grammar
+  serves both entry points.
+* ``highlight(text, lang)`` tokenises **one line** on its own. A diff row falls
+  back to this when its source file cannot be read or no longer matches, so a
+  report degrades to line-local colour rather than to none.
+
+It is approximate and never authoritative either way: nothing downstream reads
+these classes, and getting a token wrong costs a colour, not a fact.
+
+The one invariant that has to hold is the escaping one: every character of the
+input comes back HTML-escaped, whether it landed inside a span or not.
+``tests/test_highlight.py`` asserts exactly that.
+"""
+
+from __future__ import annotations
+
+import html
+import re
+from pathlib import PurePosixPath
+
+# Token classes. The letter is the CSS class suffix (`tk-k`) and the first
+# character of every named group that produces it:
+#
+#   c  comment                     k  keyword
+#   s  string                      t  literal constant, built-in type
+#   n  number                      f  name — call, decorator, variable, attribute
+#   y  key, tag or heading
+
+# A line long enough to be minified output is not worth tokenising: the regex
+# would do real work and the spans would outweigh the code they wrap. The file
+# bound catches the same thing from the other side — a bundle that *is* one
+# enormous line, or a generated file where the win is not worth the scan.
+MAX_LINE = 4000
+MAX_FILE = 1 << 20
+
+
+def _grammar(*rules: tuple[str, str]) -> re.Pattern[str]:
+    """Combine ``(class, pattern)`` rules into one alternation.
+
+    Order matters — the leftmost match wins, and ties at the same position go to
+    the earlier rule, so comments and strings come before anything that could
+    also match inside one.
+
+    Every group a rule opens must be non-capturing: ``lastgroup`` reports the
+    last *capturing* group that matched, so one stray ``(…)`` would hand back a
+    group with no class letter. The count check makes that a startup failure
+    rather than a rendering one.
+    """
+    joined = "|".join(f"(?P<{cls}{i}>{rule})" for i, (cls, rule) in enumerate(rules))
+    # MULTILINE so that a rule anchored with ^ (a YAML key, a heading, an INI
+    # section) keeps meaning "start of line" when the grammar is handed a whole
+    # file. On a single line it changes nothing.
+    pattern = re.compile(joined, re.MULTILINE)
+    if pattern.groups != len(rules):
+        raise ValueError("a highlight rule opened a capturing group; use (?:…)")
+    return pattern
+
+
+def _words(cls: str, words: str) -> tuple[str, str]:
+    """A word-boundary alternation over a whitespace-separated vocabulary."""
+    return cls, r"\b(?:" + "|".join(words.split()) + r")\b"
+
+
+# --------------------------------------------------------------- shared rules
+# Quoted strings accept an unterminated tail so that the opening line of a
+# multi-line string still reads as one, rather than dissolving into keywords.
+# Rules that must stay on one line say so with an explicit ``\n`` exclusion:
+# scanning a whole file, an unterminated quote would otherwise swallow the rest
+# of it. Rules that legitimately span lines end at ``\Z``, the end of the text —
+# not ``$``, which under re.MULTILINE would stop at the first newline.
+_HASH      = ("c", r"#[^\n]*")
+_SEMI      = ("c", r";[^\n]*")
+_SLASHES   = ("c", r"//[^\n]*")
+_BLOCK     = ("c", r"/\*[\s\S]*?(?:\*/|\Z)")
+_SQL_DASH  = ("c", r"--[^\n]*")
+_SGML      = ("c", r"<!--[\s\S]*?(?:-->|\Z)")
+_DQUOTE    = ("s", r'"(?:\\.|[^"\\\n])*"?')
+_SQUOTE    = ("s", r"'(?:\\.|[^'\\\n])*'?")
+_BACKTICK  = ("s", r"`(?:\\.|[^`\\])*`?")
+_TRIPLE    = ("s", r'[rbfuRBFU]{0,2}(?:"""[\s\S]*?(?:"""|\Z)|\'\'\'[\s\S]*?(?:\'\'\'|\Z))')
+_PY_QUOTE  = ("s", r'[rbfuRBFU]{0,2}(?:"(?:\\.|[^"\\\n])*"?|\'(?:\\.|[^\'\\\n])*\'?)')
+_NUMBER    = ("n", r"\b(?:0[xXbBoO][0-9a-fA-F_]+|\d[\d_]*(?:\.\d[\d_]*)?(?:[eE][+-]?\d+)?)\w*")
+_CALL      = ("f", r"[A-Za-z_]\w*(?=\s*\()")
+
+
+# ------------------------------------------------------------------ languages
+_PY_KEYWORDS = """
+    and as assert async await break case class continue def del elif else except finally for from
+    global if import in is lambda match nonlocal not or pass raise return try while with yield
+"""
+_PY_CONSTANTS = "True False None self cls NotImplemented Ellipsis"
+
+_C_KEYWORDS = """
+    abstract as async await break case catch class const constexpr continue debugger default defer
+    delegate delete do else enum event export extends fallthrough final finally fn for func function
+    go goto if impl implements import in instanceof interface internal let lock loop mod module move
+    mut namespace new operator out override package private protected pub public range readonly
+    record ref return sealed select static struct super switch synchronized template throw throws
+    trait transient try type typealias typedef typeof union unsafe use using val var virtual void
+    volatile when where while with yield
+"""
+_C_CONSTANTS = """
+    any bool boolean byte char chan complex64 complex128 double error false float float32 float64
+    Infinity int int8 int16 int32 int64 isize long map NaN never nil null number object rune sbyte
+    self short str string symbol this true u8 u16 u32 u64 uint uint8 uint16 uint32 uint64 uintptr
+    undefined unknown usize
+"""
+
+_RB_KEYWORDS = """
+    alias and begin break case class def do else elsif end ensure for if in module next not or redo
+    require require_relative rescue retry return super then undef unless until when while yield
+"""
+_RB_CONSTANTS = "true false nil self __FILE__ __dir__"
+
+_SH_KEYWORDS = """
+    alias break case continue declare do done elif else esac eval exec exit export fi for function
+    if in local readonly return select set shift source then trap unset until while
+    ADD ARG CMD COPY ENTRYPOINT ENV EXPOSE FROM HEALTHCHECK LABEL ONBUILD RUN SHELL STOPSIGNAL USER
+    VOLUME WORKDIR
+"""
+
+_SQL_KEYWORDS = """
+    add all alter and as asc begin between by case column commit constraint create cross default
+    delete desc distinct drop else end exists foreign from full group having if in index inner
+    insert into is join key left like limit not null offset on or order outer primary references
+    returning right rollback select set table then union unique update values view when where with
+"""
+
+GRAMMARS: dict[str, re.Pattern[str]] = {
+    "python": _grammar(
+        _HASH, _TRIPLE, _PY_QUOTE, _NUMBER,
+        _words("k", _PY_KEYWORDS), _words("t", _PY_CONSTANTS),
+        ("f", r"@[\w.]+"), _CALL,
+    ),
+    "clike": _grammar(
+        _SLASHES, _BLOCK, _DQUOTE, _SQUOTE, _BACKTICK, _NUMBER,
+        _words("k", _C_KEYWORDS), _words("t", _C_CONSTANTS),
+        ("f", r"@[\w.]+"), _CALL,
+    ),
+    "ruby": _grammar(
+        ("c", r"^=begin[\s\S]*?(?:^=end[^\n]*|\Z)"),
+        _HASH, _DQUOTE, _SQUOTE, _NUMBER,
+        _words("k", _RB_KEYWORDS), _words("t", _RB_CONSTANTS),
+        ("t", r":[A-Za-z_]\w*[?!]?"), ("f", r"[@$]{1,2}[A-Za-z_]\w*"), _CALL,
+    ),
+    "shell": _grammar(
+        _HASH, _DQUOTE, _SQUOTE, _BACKTICK, _NUMBER,
+        _words("k", _SH_KEYWORDS),
+        ("f", r"\$\{[^}\n]*\}?|\$[A-Za-z_]\w*|\$[@*#?!$0-9-]"),
+    ),
+    "json": _grammar(
+        ("y", r'"(?:\\.|[^"\\])*"(?=\s*:)'), _DQUOTE, _NUMBER,
+        _words("t", "true false null"),
+    ),
+    "yaml": _grammar(
+        _HASH,
+        ("y", r"^[ \t]*(?:-[ \t]+)?[A-Za-z_0-9.$/-]+(?=[ \t]*:(?:[ \t]|$))"),
+        _DQUOTE, _SQUOTE, _NUMBER,
+        _words("t", "true false null yes no on off"),
+        ("f", r"[&*][A-Za-z_]\w*|<<"),
+    ),
+    "ini": _grammar(
+        _HASH, _SEMI,
+        ("y", r"^[ \t]*\[[^\]\n]*\]?"),
+        ("y", r"^[ \t]*[A-Za-z_0-9.$-]+(?=[ \t]*=)"),
+        _DQUOTE, _SQUOTE, _NUMBER,
+        _words("t", "true false null"),
+    ),
+    "dotenv": _grammar(
+        _HASH,
+        ("y", r"^[ \t]*(?:export[ \t]+)?[A-Za-z_][\w.]*(?==)"),
+        _DQUOTE, _SQUOTE, _NUMBER,
+    ),
+    "markup": _grammar(
+        _SGML,
+        ("c", r"<[?!][^>\n]*>?"),
+        ("y", r"</?[A-Za-z][\w:.-]*|/?>"),
+        ("f", r"[A-Za-z_:][\w:.-]*(?=\s*=)"),
+        _DQUOTE, _SQUOTE,
+        ("t", r"&\#?\w+;"),
+    ),
+    "css": _grammar(
+        _BLOCK, _DQUOTE, _SQUOTE,
+        ("k", r"@[-\w]+"),
+        ("f", r"[-a-zA-Z][-\w]*(?=[ \t]*:)"),
+        ("n", r"\#[0-9a-fA-F]{3,8}\b"), _NUMBER,
+        ("y", r"\.[-\w]+|:{1,2}[-\w]+"),
+    ),
+    "sql": _grammar(
+        _SQL_DASH, _BLOCK, _SQUOTE, _DQUOTE, _NUMBER,
+        ("k", r"(?i:" + _words("k", _SQL_KEYWORDS)[1] + r")"),
+    ),
+    "markdown": _grammar(
+        ("y", r"^\#{1,6}[ \t].*"),
+        ("k", r"^[ \t]*(?:```|~~~).*|^[ \t]*(?:[-*+]|\d+\.)(?=[ \t])|^[ \t]*>"),
+        ("s", r"`[^`\n]*`?"),
+        ("f", r"\[[^\]\n]*\]\([^)\n]*\)?"),
+    ),
+}
+
+FAMILY_BY_LANG: dict[str, str] = {
+    "python": "python", "javascript": "clike", "typescript": "clike", "java": "clike",
+    "kotlin": "clike", "go": "clike", "rust": "clike", "csharp": "clike", "php": "clike",
+    "scala": "clike", "swift": "clike", "c": "clike", "cpp": "clike",
+    "ruby": "ruby",
+    "shell": "shell", "powershell": "shell", "dockerfile": "shell", "makefile": "shell",
+    "json": "json", "yaml": "yaml", "toml": "ini", "ini": "ini", "dotenv": "dotenv",
+    "html": "markup", "xml": "markup", "css": "css", "sql": "sql", "markdown": "markdown",
+}
+
+
+# `utils.language_for` reads an extension, and a dotfile has none: `.env.production`
+# and `.npmrc` are both indexed as plain text. Correcting that here rather than in
+# the analysis layer keeps it a presentation choice — the label already written into
+# every manifest on disk stays what it was.
+_BY_NAME: tuple[tuple[str, str], ...] = ((".env", "dotenv"), (".npmrc", "dotenv"))
+
+
+def language_of(path: str, lang: str) -> str:
+    """The language to render a file as: what the index recorded, corrected by name."""
+    name = PurePosixPath(path).name.lower()
+    for prefix, corrected in _BY_NAME:
+        if name.startswith(prefix):
+            return corrected
+    return lang
+
+
+def highlight_lines(text: str, lang: str) -> list[str]:
+    """A whole file as escaped HTML, one entry per line.
+
+    This is where the cross-line constructs are won: the grammar sees the whole
+    text, so a docstring, a licence header or an HTML comment is one match no
+    matter how many lines it covers, and each line it crosses gets its own span.
+
+    The result always has exactly ``len(text.split("\n"))`` entries, so a caller
+    can index it by line number and check its own work against the same split.
+
+    The cost is scanning a whole file to colour the handful of lines a hunk
+    quotes from it — about 90ms for a 220 KB file, and `DiffConfig` already
+    refuses to diff anything past 512 KB. Skipping the scan for files with no
+    spanning construct in them would save that, at the price of a second path
+    through here that a later rule could silently fall out of sync with.
+    """
+    raw = text.split("\n")
+    grammar = GRAMMARS.get(FAMILY_BY_LANG.get(lang, ""))
+    if grammar is None or len(text) > MAX_FILE or any(len(line) > MAX_LINE for line in raw):
+        return [html.escape(line, quote=True) for line in raw]
+
+    lines: list[list[str]] = [[]]
+
+    def emit(chunk: str, cls: str) -> None:
+        for i, piece in enumerate(chunk.split("\n")):
+            if i:
+                lines.append([])
+            if piece:
+                escaped = html.escape(piece, quote=True)
+                lines[-1].append(f'<span class="tk-{cls}">{escaped}</span>' if cls else escaped)
+
+    pos = 0
+    for match in grammar.finditer(text):
+        start, end = match.span()
+        if start == end:
+            continue
+        if start > pos:
+            emit(text[pos:start], "")
+        emit(match.group(), match.lastgroup[0])
+        pos = end
+    emit(text[pos:], "")
+    return ["".join(parts) for parts in lines]
+
+
+def highlight(text: str, lang: str) -> str:
+    """One line of source as escaped HTML, with token spans where we know the language.
+
+    Falls back to plain escaped text for anything unrecognised, so the caller
+    never needs to ask whether a language is supported.
+    """
+    grammar = GRAMMARS.get(FAMILY_BY_LANG.get(lang, ""))
+    if grammar is None or len(text) > MAX_LINE:
+        return html.escape(text, quote=True)
+
+    parts: list[str] = []
+    pos = 0
+    for match in grammar.finditer(text):
+        start, end = match.span()
+        if start == end:  # a zero-width rule would colour nothing and stall nothing
+            continue
+        if start > pos:
+            parts.append(html.escape(text[pos:start], quote=True))
+        token = html.escape(match.group(), quote=True)
+        parts.append(f'<span class="tk-{match.lastgroup[0]}">{token}</span>')
+        pos = end
+    parts.append(html.escape(text[pos:], quote=True))
+    return "".join(parts)

lambda_watcher/diffing/icons.py

@@ -0,0 +1,132 @@
+"""File-type icons for the report's file list.
+
+Every row of a diff already spells out its path, so an icon that only repeated
+the extension would be decoration. What it can add is *shape*: a scroll through
+sixty changed files should show at a glance where the code is, where the
+configuration is, and which one of them is a ``.env``.
+
+So the icons are eight glyph families rather than sixty logos — nothing is
+borrowed artwork, nothing needs a licence, and a language nobody thought of
+still gets a sensible mark. The language it came from survives as colour.
+
+The glyphs are drawn once into a hidden ``<symbol>`` sprite that the document
+carries at the top of its body; each row then costs one ``<use>``. The colours
+are emitted as one small stylesheet from the same table, so a row costs no
+inline style either — which matters when a vendored diff runs to thousands of
+files.
+"""
+
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+
+# 16×16, stroked rather than filled so a single colour drives the whole glyph.
+GLYPHS: dict[str, str] = {
+    "code":     '<path d="M6.2 4.4 2.6 8l3.6 3.6"/><path d="M9.8 4.4 13.4 8l-3.6 3.6"/>',
+    "markup":   '<path d="M5.4 3.6 2 8l3.4 4.4"/><path d="M10.6 3.6 14 8l-3.4 4.4"/>'
+                '<path d="M9.4 2.6 6.6 13.4"/>',
+    "data":     '<path d="M6.6 2.8c-1.4 0-2 .7-2 1.9v1.4c0 1-.6 1.6-1.6 1.9 1 .3 1.6.9 1.6 1.9v1.4'
+                'c0 1.2.6 1.9 2 1.9"/>'
+                '<path d="M9.4 2.8c1.4 0 2 .7 2 1.9v1.4c0 1 .6 1.6 1.6 1.9-1 .3-1.6.9-1.6 1.9v1.4'
+                'c0 1.2-.6 1.9-2 1.9"/>',
+    "doc":      '<path d="M3.2 4.2h9.6"/><path d="M3.2 8h9.6"/><path d="M3.2 11.8h5.8"/>',
+    "terminal": '<rect x="2.2" y="3.2" width="11.6" height="9.6" rx="2"/>'
+                '<path d="M4.9 6.9 7 9l-2.1 2.1"/><path d="M8.7 11.1h2.8"/>',
+    "style":    '<path d="M8 2.4c2.6 2.7 4 4.7 4 6.3a4 4 0 0 1-8 0c0-1.6 1.4-3.6 4-6.3z"/>',
+    "lock":     '<rect x="3.2" y="7" width="9.6" height="6.2" rx="1.6"/>'
+                '<path d="M5.6 7V5.4a2.4 2.4 0 0 1 4.8 0V7"/>',
+    "image":    '<rect x="2.4" y="3.4" width="11.2" height="9.2" rx="1.8"/>'
+                '<circle cx="6" cy="6.9" r="1.1"/><path d="m3 11.8 3.2-3 2.4 2.3 2.2-1.8 2.8 2.5"/>',
+    "binary":   '<path d="M8 2.4 13.6 5.4v5.2L8 13.6 2.4 10.6V5.4z"/>'
+                '<path d="M2.4 5.4 8 8.4l5.6-3"/><path d="M8 8.4v5.2"/>',
+}
+
+# Key -> (glyph, colour). The keys are the language labels `utils.language_for`
+# produces plus the two below that no label can express, and one mid-tone colour
+# each, because the report is read in both themes and the icon sits on the same
+# panel in either one.
+ICONS: dict[str, tuple[str, str]] = {
+    "python":     ("code",     "#4b8bbe"),
+    "javascript": ("code",     "#c9a227"),
+    "typescript": ("code",     "#3178c6"),
+    "java":       ("code",     "#c26a4a"),
+    "kotlin":     ("code",     "#9a6ef0"),
+    "go":         ("code",     "#23a3c4"),
+    "ruby":       ("code",     "#cc4b4b"),
+    "rust":       ("code",     "#c8763c"),
+    "csharp":     ("code",     "#8a63c4"),
+    "php":        ("code",     "#6e7fbc"),
+    "scala":      ("code",     "#c4574a"),
+    "swift":      ("code",     "#e0713d"),
+    "c":          ("code",     "#6d8bbd"),
+    "cpp":        ("code",     "#8a7fc4"),
+    "sql":        ("code",     "#4a9aa8"),
+    "shell":      ("terminal", "#6ea84f"),
+    "powershell": ("terminal", "#3f7fd0"),
+    "dockerfile": ("terminal", "#2f8fd0"),
+    "makefile":   ("terminal", "#8a8f98"),
+    "json":       ("data",     "#b58900"),
+    "yaml":       ("data",     "#9068c0"),
+    "toml":       ("data",     "#a5713d"),
+    "ini":        ("data",     "#8a8f98"),
+    "html":       ("markup",   "#e06c50"),
+    "xml":        ("markup",   "#d4713f"),
+    "css":        ("style",    "#3c9ad9"),
+    "markdown":   ("doc",      "#7a8290"),
+    "csv":        ("doc",      "#5f9e6e"),
+    "text":       ("doc",      "#8b8f97"),
+    "dotenv":     ("lock",     "#b58900"),
+    "binary":     ("binary",   "#8b8f97"),
+    # Two keys no language label produces. An image is indexed as `binary`,
+    # the same label a shared object gets; and a file that carries credentials
+    # is worth a lock whatever syntax happens to be inside it.
+    "image":      ("image",    "#a06fc0"),
+    "_other":     ("doc",      "#8b8f97"),
+}
+
+IMAGE_SUFFIXES = {".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp", ".ico", ".bmp"}
+SECRET_NAMES = ("credentials", "id_rsa", ".netrc", ".pem", ".key", ".p12", ".pfx")
+
+
+def icon_key(path: str, lang: str) -> str:
+    """Which entry of ``ICONS`` a file gets — what the path says first, then its language.
+
+    ``.env`` files need no rule here: they reach this point already labelled
+    ``dotenv`` by `highlight.language_of`, which is where reading a name for a
+    language belongs.
+    """
+    name = PurePosixPath(path).name.lower()
+    if PurePosixPath(name).suffix in IMAGE_SUFFIXES:
+        return "image"
+    if name.startswith(SECRET_NAMES) or name.endswith(SECRET_NAMES):
+        return "dotenv"
+    return lang if lang in ICONS else "_other"
+
+
+def file_icon(path: str, lang: str) -> str:
+    """A decorative icon for one file: the path beside it already names it."""
+    key = icon_key(path, lang)
+    glyph = ICONS[key][0]
+    return (
+        f'<svg class="fic fic-{key}" viewBox="0 0 16 16" aria-hidden="true">'
+        f'<use href="#g-{glyph}"/></svg>'
+    )
+
+
+def sprite() -> str:
+    """The hidden glyph sheet every ``file_icon`` points at, emitted once."""
+    symbols = "".join(
+        f'<symbol id="g-{name}" viewBox="0 0 16 16">{body}</symbol>' for name, body in GLYPHS.items()
+    )
+    return f'<svg class="sprite" aria-hidden="true">{symbols}</svg>'
+
+
+def css() -> str:
+    """One colour rule per key, generated from the table above."""
+    base = [
+        "svg.sprite { display: none; }",
+        ".fic { width: 16px; height: 16px; flex: 0 0 auto; fill: none; stroke: currentColor;",
+        "  stroke-width: 1.5; stroke-linecap: round; stroke-linejoin: round; }",
+    ]
+    rules = [f".fic-{key} {{ color: {colour}; }}" for key, (_, colour) in ICONS.items()]
+    return "\n".join(base + rules) + "\n"

lambda_watcher/diffing/intraline.py

@@ -0,0 +1,162 @@
+"""Which *words* of a changed line actually changed.
+
+A diff that paints a whole line green says "this line is new". Most of the time
+it is not new — three characters of it are, and the eye has to re-read forty to
+find them. This module finds those characters, and marks them inside a line the
+highlighter has already coloured.
+
+Two problems, kept apart:
+
+`pair_rows` decides *which* removed line a given added line is a rewrite of.
+Getting that wrong is worse than not marking at all — a confident mark on an
+unrelated pair sends the reader hunting for a change that is not there — so the
+pairing is deliberately shy: it takes the strongest match for each line, and
+only when the two are more alike than not.
+
+`mark` then wraps the differing ranges. The line reaching it is already HTML,
+so the wrapper is split at every tag boundary rather than straddling one: two
+adjacent marks paint one continuous background, and the nesting stays
+well-formed whatever `highlight` decided to emit.
+"""
+
+from __future__ import annotations
+
+import re
+from difflib import SequenceMatcher
+
+#: Words, runs of whitespace, and every other character on its own. Splitting
+#: this way means a renamed identifier marks as one unit instead of dissolving
+#: into the letters it happens to share with the old name.
+_TOKEN = re.compile(r"\w+|\s+|.")
+
+#: A tag, an entity, or a run of neither — the three things a highlighted line
+#: is made of. Entities matter because `&` is five characters of markup and
+#: one character of the file.
+_PIECE = re.compile(r"<[^>]*>|&[#A-Za-z0-9]+;|[^<&]+|.")
+
+#: Below this, "rewrite" is a fiction: the two lines have little in common and
+#: marking their scattered shared characters would be confetti, not information.
+MIN_SIMILARITY = 0.5
+
+#: Above this, almost the whole line is marked and the marks stop distinguishing
+#: anything — the plain add/remove wash already said it.
+MAX_MARKED = 0.75
+
+#: Pairing is quadratic in the size of a replaced block. Blocks this large are
+#: wholesale rewrites, where per-word marks would not help anyone anyway.
+MAX_BLOCK = 40
+
+
+def _tokens(text: str) -> list[str]:
+    return _TOKEN.findall(text)
+
+
+def _ranges(tokens: list[str], opcodes: list[tuple], side: int) -> list[tuple[int, int]]:
+    """Character ranges of the tokens this side does not share with the other."""
+    starts, offset = [], 0
+    for token in tokens:
+        starts.append(offset)
+        offset += len(token)
+    starts.append(offset)
+
+    spans: list[tuple[int, int]] = []
+    for tag, i1, i2, j1, j2 in opcodes:
+        if tag == "equal":
+            continue
+        lo, hi = (i1, i2) if side == 0 else (j1, j2)
+        if lo == hi:
+            continue
+        if spans and spans[-1][1] == starts[lo]:
+            spans[-1] = (spans[-1][0], starts[hi])
+        else:
+            spans.append((starts[lo], starts[hi]))
+    return spans
+
+
+def word_diff(before: str, after: str) -> tuple[list[tuple[int, int]], list[tuple[int, int]]]:
+    """The differing character ranges of two lines, as ``(before, after)``.
+
+    Returns empty lists when marking would not help: when the lines are too
+    unlike to be a rewrite of each other, and when so much of them differs that
+    the marks would cover the line they are supposed to pick things out of.
+    """
+    if before == after:
+        return [], []
+    old, new = _tokens(before), _tokens(after)
+    matcher = SequenceMatcher(None, old, new, autojunk=False)
+    if matcher.ratio() < MIN_SIMILARITY:
+        return [], []
+
+    opcodes = matcher.get_opcodes()
+    old_spans = _ranges(old, opcodes, 0)
+    new_spans = _ranges(new, opcodes, 1)
+    marked = sum(hi - lo for lo, hi in old_spans) + sum(hi - lo for lo, hi in new_spans)
+    if marked > MAX_MARKED * (len(before) + len(after)):
+        return [], []
+    return old_spans, new_spans
+
+
+def pair_rows(removed: list[str], added: list[str]) -> dict[tuple[int, int], None]:
+    """Which removed line each added line rewrites, as ``{(old_i, new_i)}``.
+
+    Strongest pair first, each line spoken for once. A line whose best partner
+    is still mostly different stays unpaired, and is painted the plain way.
+    """
+    if not removed or not added or len(removed) > MAX_BLOCK or len(added) > MAX_BLOCK:
+        return {}
+
+    scored = []
+    for i, old in enumerate(removed):
+        for j, new in enumerate(added):
+            ratio = SequenceMatcher(None, old, new, autojunk=False).ratio()
+            if ratio >= MIN_SIMILARITY:
+                scored.append((ratio, i, j))
+
+    pairs: dict[tuple[int, int], None] = {}
+    used_old: set[int] = set()
+    used_new: set[int] = set()
+    for _, i, j in sorted(scored, key=lambda s: (-s[0], s[1], s[2])):
+        if i in used_old or j in used_new:
+            continue
+        used_old.add(i)
+        used_new.add(j)
+        pairs[(i, j)] = None
+    return pairs
+
+
+def mark(rendered: str, spans: list[tuple[int, int]], css: str = "wd") -> str:
+    """Wrap the given character ranges of an already-highlighted line.
+
+    ``spans`` index the *plain text* of the line — the same offsets `word_diff`
+    returned — while ``rendered`` is what `highlight` made of it. Walking the
+    two together is the whole job: markup is stepped over, an entity counts as
+    the one character it stands for, and a range that reaches across a syntax
+    span is emitted as one wrapper per piece it covers.
+    """
+    if not spans:
+        return rendered
+
+    def covered(start: int, stop: int) -> list[tuple[int, int]]:
+        return [(max(lo, start), min(hi, stop)) for lo, hi in spans if lo < stop and hi > start]
+
+    out: list[str] = []
+    at = 0
+    for piece in _PIECE.findall(rendered):
+        if piece.startswith("<"):
+            out.append(piece)
+            continue
+        width = 1 if piece.startswith("&") else len(piece)
+        hits = covered(at, at + width)
+        if not hits:
+            out.append(piece)
+        elif piece.startswith("&"):
+            out.append(f'<span class="{css}">{piece}</span>')
+        else:
+            cursor = at
+            for lo, hi in hits:
+                out.append(piece[cursor - at : lo - at])
+                out.append(f'<span class="{css}">{piece[lo - at : hi - at]}</span>')
+                cursor = hi
+            out.append(piece[cursor - at :])
+        at += width
+    return "".join(out)