Streamline validators.md index

[alganet]

Makes it so the index looks more like a cheatsheet, condensing information instead of making long lists that require lots of
scrolling to explore.

Additionally, the happy path for each validator was also added, providing a quick reference use for comparison.

The direct markdown links were replaced by titled markdown references, offering mouse-over tooltips over links that
display the validator one-line description.

To ensure a proper source of truth for these new index goodies, the AssertionMessageLinter was modified to verify that the first assertion in each doc is a single-line validator that passes (a happy path), further making our documentation conventions more solid.

---

Cheatsheet-style and tooltips on mouse-over

Alphabetical list with happy path examples

Plain text

Viewing the document in plain-text gives almost the same feeling as the rendered markdown, respecting the true spirit of the format.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.03%. Comparing base (00e7f2a) to head (834a3cd).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##               main    #1632   +/-   ##
=========================================
  Coverage     98.03%   98.03%           
  Complexity      961      961           
=========================================
  Files           197      197           
  Lines          2234     2234           
=========================================
  Hits           2190     2190           
  Misses           44       44           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR refactors the validators.md index to be auto-generated and more “cheatsheet-like”, with compact category sections, an alphabetical list of validators including example usages, and link references with tooltip descriptions sourced from individual validator docs.

Changes:

• Updated ValidatorIndexLinter to derive categories, short descriptions, and example snippets from each validator’s markdown file, and to regenerate docs/validators.md with a compact category summary, an alphabetical list including “happy path” examples, and a reference section.
• Extended Content with helpers for generating reference-style Markdown links (reference()) and stripping inline/reference link syntax from text (stripRefs()).
• Replaced the manually-maintained lists in docs/validators.md with the new cheatsheet-style layout and reference definitions for every validator.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 8 comments.

File	Description
src-dev/Markdown/Linters/ValidatorIndexLinter.php	Changes the linter to discover validator categories, descriptions, and example lines from individual validator docs and to emit the new category + alphabetical layout plus reference definitions.
src-dev/Markdown/Content.php	Adds utilities to emit reference-style Markdown link definitions and to remove inline/reference link markup from descriptions when building tooltips.
docs/validators.md	Replaces the long per-category and alphabetical lists with a compact cheatsheet-style index, including one-line categories, alphabetical entries with example snippets, and reference-style link definitions with short descriptions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[henriquemoody]

I love the new validators.md, and I the linter for the first assertion is really great, regardless of how they look in validators.md.

I made a comment about the first code block change, but I won't block this merge -- nothing we couldn't change afterwards, and since that's not code we ship in the package we can change it at any time.