--attach stack 3/8: Rewrite markdown references to uploaded assets - #14179

Part of the pull request stack tracked in #14186.

Description

This is the third layer of the stack, and the largest and hardest pull request in it. Nothing here is reachable from a command yet.

Given some markdown and a set of attached files, it finds every reference in the markdown that points at one of those files and rewrites the destination to the uploaded URL. It reports which attachments were never referenced, so the caller can append them.

The code runs in three phases, and it is ordered that way on purpose:

1. Find every reference. The markdown is parsed with goldmark, the parser gh already depends on, and each link or image node is asked for its position.
2. Plan the edits. Each reference becomes a byte range and a replacement.
3. Apply the edits, working back to front so the earlier ranges stay valid.

The behaviour that follows from that:

• A reference style definition is rewritten once, at the definition, so every use of that label follows from one edit.
• A path inside a code fence or an inline code span is left exactly as written.
• A plain link stays a link. Only the destination moves, so alt text, titles and formatting inside the label survive.
• A video embedded alone on its own line has the whole node replaced by a bare URL, because that is what GitHub needs to render a player. A video embedded inline degrades to a link instead, since a player cannot render in the middle of a sentence.
• A video written as a reference style image is refused, because rewriting it would produce an image tag pointing at a video.
• The same file referenced twice is uploaded once and both references get the same URL.

The second commit adds one markdown document that exercises every syntax the package handles, together with its expected output.

How did you test this change?

The whole stack was built and each of the behaviours above was exercised by hand against a private test repository. That covered a reference rewritten in place, a reference style definition with two uses following one edit, a fenced block and an inline code span left untouched, a plain link staying a link, a video alone on a line becoming a bare URL, a video inline becoming a link, a video as a reference style image being refused, an unused definition left alone, a file named in the body but never attached left alone, and the same file referenced twice sharing one uploaded asset.

Key points

About 110 lines of this are hand written byte scanning. It exists because goldmark reports the position of a node but not the position of the destination inside that node.

The alternative would be to re-render the document from the parsed tree. That would be worse, because it normalises the author's own prose, and someone who wrote a comment by hand should get their comment back rather than a reformatted version of it. A follow up can restructure this around goldmark's node identity and delete some of the scanning. That work is not here.

Notes for reviewers

Start with the two entry points and read the three phases in order.

The fixture document in the second commit is the fastest way to understand the behaviour. Reading the input and the expected output side by side shows what the package does without reading the scanner at all, which is why it is a separate commit.

Authorship and follow-up

Who wrote this:

• A human wrote it.
• An agent wrote it under close human direction.
• An agent wrote it independently, and no human has guided the implementation beyond the initial prompt.

Who answers review comments:

• @BagToad will read and reply directly. Name the account.
• An agent will draft replies and @BagToad will read them before they are posted.
• Nobody has explicitly committed to replying.