Fix #4207: Preserve display text for reference-style documentation links

[NamanGoyalK]

Fixes #4207

Description

This PR fixes an issue where Dartdoc ignores the custom text provided in a Markdown reference-style link ([text][target]) and instead aggressively overwrites it with the target's element name.

With this fix, writing [Platform.current][Platform.nativePlatform] will correctly link to Platform.nativePlatform while displaying Platform.current as the link text.

Implementation Details

Instead of heavily refactoring Dartdoc's core link resolver (_makeLinkNode / getMatchingLinkElement), which handles complex edge cases like callable hints, shadowing, and inherited documentation, this fix introduces a localized, safe AST interception via package:markdown.

• Added _LinkSyntaxWithPreservedReferenceText which extends md.LinkSyntax.
• It intercepts the node creation in the close() method.
• If the linkResolver has overwritten the text to match the target label, it safely swaps the md.Text child back to the user's intended referenceText.
• Implemented _parseFullReferenceLabel to safely extract the target label while accounting for escaped characters and ignoring collapsed links ([text][]).

This approach guarantees that standard Markdown links remain unaffected while accurately restoring the text for Dartdoc-resolved elements.

Testing

Added comprehensive tests in test/reference_style_links_test.dart:

• Verified that standard defined Markdown reference links are untouched.
• Verified that [text][target] correctly falls back to Dartdoc link resolution.
• Verified that the first label (text) is successfully preserved in the generated HTML and the fallback target label is not displayed.

Checklist

• I have read the Contributor Guide.
• I have added tests to cover my changes.
• All tests pass (dart test).

[kevmoo]

You sent a PR with TESTS. I gotta help you out.

@srawlins is likely the person who will need to review, though.

[srawlins]

I'll certainly take a look, but I believe @szakarias is the primary owner of Dartdoc.

[srawlins]

This looks good to me. The parser work is a little dicey, but I don't know of a way around it (I think maybe that's just par-for-the-course for parser work 😅 ).

[NamanGoyalK]

Thanks for the review and the approval, @srawlins! Completely agree on the parser work, it was a bit of a puzzle to find a localized way to handle it without over-engineering the core resolver.

Standing by for whenever @szakarias has a moment for the final look!