fix: doctype-first does not account for comments being permitted beforehand

[coliff]

Fixes: #1594

[gemini-code-assist]

Code Review

This pull request effectively addresses issue #1594 by refining the doctype-first rule to correctly allow comments and whitespace before the DOCTYPE declaration. The changes are well-implemented across the rule logic, tests, and documentation.

Key improvements:

• Corrected Logic: The rule now accurately distinguishes between comments (allowed) and other non-whitespace content (not allowed) before the DOCTYPE.
• Clearer Descriptions: Both the rule's description and the error messages have been updated for better clarity.
• Comprehensive Tests: New test cases have been added to specifically validate the behavior with preceding comments and non-comment content.
• Updated Documentation: The documentation now reflects the nuanced behavior of the rule with accurate examples of valid and invalid patterns.

The updated logic in src/core/rules/doctype-first.ts using the doctypeFound and nonCommentContentBeforeDoctype flags is robust and handles the different scenarios correctly. The changes to the distributed files (dist/) are as expected.

Overall, this is a high-quality contribution that improves the accuracy and usability of the doctype-first rule. Great job!

Merge Readiness

The changes in this pull request are well-implemented, tested, and documented. The code appears to be in good shape and addresses the reported issue effectively. While I cannot approve the pull request myself, I believe it is ready for merging after any standard internal review processes are completed.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (95e6a13) to head (2db5879).
Report is 37 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main     #1610      +/-   ##
===========================================
+ Coverage   96.99%   100.00%   +3.00%     
===========================================
  Files           2         1       -1     
  Lines        1628         1    -1627     
  Branches      335         0     -335     
===========================================
- Hits         1579         1    -1578     
+ Misses         49         0      -49     

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 5535109...2db5879. Read the comment docs.

🚀 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.