Pennington.Infrastructure.XrefResolvingService

namespace Pennington.Infrastructure;

/// Resolves xref: cross-reference links in HTML. Two phases:
ResolveXrefTagsAsync substitutes raw <xref:uid> tags via regex. These are not valid HTML, so they must be rewritten before any DOM parser sees them.
ResolveXrefLinksAsync walks a[href^='xref:'] on an already-parsed document.
The response pipeline calls both phases via XrefHtmlRewriter, reusing the orchestrator's shared document. The SPA data endpoint for island HTML fragments calls the combined ResolveAsync entrypoint, which performs its own parse/serialize because it receives raw HTML strings with no caller-owned document.Registered as a transient so every resolution picks up the current file-watched XrefResolver instance. The orchestrator (and rewriter that wraps this service) are transient too; the whole chain is rebuilt per request when the middleware resolves its processors, so no capture pins a stale XrefResolver.
public class XrefResolvingService
{
    /// Initializes the service with the current XrefResolver from DI.
    
public XrefResolvingService(XrefResolver resolver);

    /// Standalone entrypoint for callers that have a raw HTML string and no document (SPA island fragments). Returns resolved HTML.
    
public async Task<string> ResolveAsync(string html, DiagnosticContext? diagnostics = null);

    /// Phase 2: DOM rewrite of a[href^='xref:'] links on an already-parsed document. Returns true when any link was rewritten — callers that used ResolveAsync use this to decide whether to re-serialize the document.
    
public async Task<bool> ResolveXrefLinksAsync(IDocument document, DiagnosticContext? diagnostics);

    /// Phase 1: regex substitution of raw <xref:uid> tags. Produces an <a> element that the later DOM phase (or any downstream HTML parser) can see as normal markup. Skips content inside <code> and <pre> blocks so authoring docs can show literal <xref:uid> samples in fenced code without the rewriter latching onto them — the highlighter also splits long tokens across span boundaries, which would otherwise let [^>]+ consume span markup as the uid.
    
public async Task<string> ResolveXrefTagsAsync(string html, DiagnosticContext? diagnostics);
}