(experimental) Linkify git commit references

[cboos]

Bullet	Reading
"git history matching"	Correlate session events with git commits. "Which session produced commit abc123? What was the prompt that led to this change?"

grep/rg <commit> <rendered-projects-dir> -t md could easily locate the session and the closest prompt.
#151 could make that easier, but even now with <rendered-projects-dir> == ~/.claude/projects, this would work.

However, we could still enrich the markup with links to the remote (branch -> remote, remote -> GitHub/GitLab detection on the URL). Local commits would be rendered as 7c2e6f6, those found on the remote as 7c2e6f6.

Originally posted by @cboos in #110

[cboos]

(Claude) Researched what it would take to write a mistune plugin that scans plain text and emits inline links from matched content (git commit SHA → GitHub/GitLab commit URL when resolvable). Below is the plugin shape only — the resolve-against-remote logic itself is out of scope for this note.

1. Inline parser API (mistune 3.x)

An inline plugin registers a regex + a parse function on md.inline. The function signature is parse_xxx(inline: InlineParser, m: re.Match, state: InlineState) -> int and must return the new cursor position. Registration:

md.inline.register("sha_link", SHA_PATTERN, parse_sha_link)

(register calls register_rule + appends to DEFAULT_RULES.) Docs: https://mistune.lepture.com/en/latest/advanced.html#create-plugins and https://mistune.lepture.com/en/latest/plugins.html.

2. Renderer dispatch

BaseRenderer.render_token looks up a method by token type. Two ways to handle the new node:

• Cheapest: emit a stock "link" token (the trick the built-in url plugin uses) — no renderer changes, both HTMLRenderer and the project's _TagProtectingMarkdownRenderer already know link.
• Custom token type: emit {"type": "sha_link", ...} and call md.renderer.register("sha_link", render_fn) once per renderer (gated by md.renderer.NAME == "html" vs "markdown").

For this use case, option 1 is enough.

3. Does it fire inside *…* / **…** / etc.?

Yes. InlineParser.parse_emphasis extracts the inner text into a fresh InlineState and recurses via self.render(new_state) — which re-runs the full inline rule set including registered plugins. Confirmed gotchas:

• Won't fire inside codespan / fenced code (parsed as raw, not re-rendered) — desired here. So `7c2e6f6` stays unchanged.
• Won't fire inside an existing link (state.in_link guard — copy the pattern from url.py to avoid double-wrap).

4. Best reference plugin

mistune/plugins/url.py (~33 lines). Identical shape: regex → parse function → emit link token. Copy it and swap the regex + URL-resolution call.

The in-project Pygments plugin (claude_code_log/html/utils.py:_create_pygments_plugin) is not the right precedent — it monkey-patches md.renderer.block_code for fenced code, never touches the inline parser.

5. Minimal sketch

import re
from typing import Callable, Optional

SHA_PATTERN = r"\b[0-9a-f]{7,40}\b"  # word-bounded; tune for false-match shapes

def make_sha_plugin(resolve: Callable[[str], Optional[str]]):
    """resolve(sha) -> URL or None. Plugin leaves text unchanged on None."""

    def parse_sha_link(inline, m, state) -> int:
        sha = m.group(0)
        pos = m.end()
        if state.in_link:                       # don't nest links
            inline.process_text(sha, state)
            return pos
        url = resolve(sha)                      # <-- remote-resolution hook
        if url is None:
            inline.process_text(sha, state)     # leave as plain text
            return pos
        state.append_token({
            "type": "link",
            "children": [{"type": "text", "raw": sha}],
            "attrs": {"url": url},
        })
        return pos

    def plugin(md) -> None:
        md.inline.register("sha_link", SHA_PATTERN, parse_sha_link)

    return plugin

# usage:
# mistune.create_markdown(plugins=[..., make_sha_plugin(my_resolver)])

resolve is the only thing to write — wrap in functools.lru_cache. For git ls-remote-class latency, consider a two-phase scan (collect candidates → batch-resolve → render) instead of inline resolution.

Open uncertainties

• Plugin rule ordering: register() appends to DEFAULT_RULES, so built-ins like link, auto_link, codespan win on overlap (good — [abc1234](url) stays one link). Interaction with the 'url' built-in if a SHA-shape appears inside an autolinked URL is not 100% verified; if it matters, gate the regex with surrounding-char checks.
• Word boundary \b against hex: \b treats 0-9a-f as word chars, so abc7c2e6f6 won't false-match — but 7c2e6f6. will. Tune to taste.