Add validation warnings with category and suggestion support

[dereuromark]

Summary

• Extends ParseWarning with optional category and suggestion fields for more actionable feedback
• Adds detection for unused reference definitions (defined but never used)
• Enhances undefined reference warnings with category and suggestion
• Tracks reference usage only when warnings: true (zero overhead when disabled)
• Skips heading auto-references and footnote definitions from unused checks

Changes

• ParseWarning: Added category and suggestion constructor params with getters
• BlockParser: Added validateReferences() method, usedReferences tracking, updated addWarning() signature
• InlineParser: Calls markReferenceUsed() when reference links are resolved
• ReferenceDefinition: Added line field for better warning locations

Backwards Compatibility

Fully backwards compatible:

• New ParseWarning fields are optional (default null)
• Existing getWarnings() calls continue to work
• No performance impact when warnings disabled

Example

$converter = new DjotConverter(warnings: true);
$converter->convert("[Missing][ref]\n\n[unused]: https://example.com");

foreach ($converter->getWarnings() as $warning) {
    echo "[{$warning->getCategory()}] {$warning->getMessage()}\n";
    if ($warning->getSuggestion()) {
        echo "  Suggestion: {$warning->getSuggestion()}\n";
    }
}
// [reference] Undefined reference 'ref' at line 1, column 1
//   Suggestion: Define with [ref]: url or use inline link
// [reference] Reference 'unused' defined but never used at line 3, column 1

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.68%. Comparing base (5085c8e) to head (4d12ce7).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff              @@
##             master      #51      +/-   ##
============================================
+ Coverage     93.64%   93.68%   +0.04%     
- Complexity     1916     1928      +12     
============================================
  Files            74       74              
  Lines          5143     5177      +34     
============================================
+ Hits           4816     4850      +34     
  Misses          327      327              

☔ 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.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.